📝 OO connector technical documentation (#547)

tdrive/connectors/onlyoffice-connector/src/controllers/index.controller.ts

@@ -23,7 +23,17 @@ interface RequestEditorQuery {
   file_id: string;
 }
 
+/**
+ * These routes are called by Twake Drive frontend. The user's browser opens ( +) `${config.plugin.edition_url}/` (`index`).
+ * The user is redirected from there to open directly the OnlyOffice edition server's web UI, with appropriate preview or not
+ * and rights checks.
+ */
 class IndexController {
+  /**
+   * Opened by the user's browser, proxied through the Twake Drive backend. Checks access to the
+   * file with the backend, then redirects the user to the `editor` method but directly on this
+   * connector, not proxied by Twake Drive's backend anymore.
+   */
   public index = async (req: Request<{}, {}, {}, RequestQuery>, res: Response, next: NextFunction): Promise<void> => {
     try {
       const { file_id, drive_file_id, company_id, preview, token } = req.query;
@@ -89,6 +99,9 @@ class IndexController {
     }
   };
 
+  /**
+   * Renders this connector's view to initialise the Docs API client side component.
+   */
   public editor = async (req: Request<{}, {}, {}, RequestEditorQuery>, res: Response, next: NextFunction): Promise<void> => {
     try {
       const { office_token } = req.query;

tdrive/connectors/onlyoffice-connector/src/controllers/onlyoffice.controller.ts

@@ -21,7 +21,16 @@ interface SaveRequestBody {
   users: string[];
 }
 
+/** These expose a OnlyOffice document storage service methods, called by the OnlyOffice document editing service
+ * to load and save files
+ */
 class OnlyOfficeController {
+  /**
+   * Get a file from Twake Drive backend, and proxy it back the previewer/editor (via the document editing service).
+   *
+   * Parameters are standard Express middleware.
+   * @see https://api.onlyoffice.com/editors/open
+   */
   public read = async (req: Request<{}, {}, {}, RequestQuery>, res: Response, next: NextFunction): Promise<void> => {
     try {
       const { token } = req.query;
@@ -55,6 +64,13 @@ class OnlyOfficeController {
     }
   };
 
+  /**
+   * Receive a file from OnlyOffice document editing service and save it into Twake Drive backend
+   *
+   * Parameters are standard Express middleware.
+   * @see https://api.onlyoffice.com/editors/save
+   * @see https://api.onlyoffice.com/editors/callback
+   */
   public save = async (req: Request<{}, {}, SaveRequestBody, RequestQuery>, res: Response, next: NextFunction): Promise<void> => {
     try {
       const { url, key } = req.body;

tdrive/connectors/onlyoffice-connector/src/services/api.service.ts

@@ -7,6 +7,8 @@ import {
 import axios, { Axios, AxiosRequestConfig, AxiosResponse } from 'axios';
 import { CREDENTIALS_ENDPOINT, CREDENTIALS_ID, CREDENTIALS_SECRET, ONLY_OFFICE_SERVER } from '@config';
 import loggerService from './logger.service';
+
+/** Client for the Twake Drive backend API on behalf of the plugin (or provided token in parameters) */
 class ApiService implements IApiService {
   private axios: Axios;
   private initialized: Promise<string>;
@@ -20,7 +22,7 @@ class ApiService implements IApiService {
     setInterval(() => {
       this.initialized = this.refreshToken();
       loggerService.info('Refreshing token 🪙');
-    }, 1000 * 60); //Every 10 minutes
+    }, 1000 * 60); //TODO: should be Every 10 minutes
   }
 
   public get = async <T>(params: IApiServiceRequestParams<T>): Promise<T> => {

tdrive/connectors/onlyoffice-connector/src/services/drive.service.ts

@@ -2,6 +2,7 @@ import { DriveFileType, IDriveService } from '@/interfaces/drive.interface';
 import apiService from './api.service';
 import loggerService from './logger.service';
 
+/** Client for the Twake Drive backend API dealing with `DriveItem`s  */
 class DriveService implements IDriveService {
   public get = async (params: { company_id: string; drive_file_id: string; user_token?: string }): Promise<DriveFileType> => {
     try {