nativex: describe interfaces

Signed-off-by: Varun Patil <radialapps@gmail.com>

src/native.ts

@@ -1,42 +1,140 @@
 import axios from '@nextcloud/axios';
 import { constants } from './services/Utils';
 import { generateUrl } from '@nextcloud/router';
-import type { IDay, IPhoto } from './types';
+import type { IDay, IPhoto, IImageInfo } from './types';
 const euc = encodeURIComponent;
 
 /** Access NativeX over localhost */
 const BASE_URL = 'http://127.0.0.1';
 
-/** NativeX API implemented by the native code */
+/** NativeX asynchronous API */
 export const API = {
+  /**
+   * Local days API.
+   * @returns {IDay[]} for all locally available days.
+   */
   DAYS: () => `${BASE_URL}/api/days`,
+  /**
+   * Local photos API.
+   * @param dayId Day ID to fetch photos for
+   * @returns {IPhoto[]} for all locally available photos for this day.
+   */
   DAY: (dayId: number) => `${BASE_URL}/api/days/${dayId}`,
+
+  /**
+   * Local photo metadata API.
+   * @returns {IImageInfo} for the given file ID (local).
+   */
   IMAGE_INFO: (fileId: number) => `${BASE_URL}/api/image/info/${fileId}`,
+
+  /**
+   * Delete files using local fileids.
+   * @param fileIds Comma-separated list of file IDs to delete
+   * @returns {void}
+   */
   IMAGE_DELETE: (fileIds: number[]) => `${BASE_URL}/api/image/delete/${fileIds.join(',')}`,
 
+  /**
+   * Local photo preview API.
+   * @param fileId File ID of the photo
+   * @returns {Blob} JPEG preview of the photo.
+   */
   IMAGE_PREVIEW: (fileId: number) => `${BASE_URL}/image/preview/${fileId}`,
+  /**
+   * Local photo full API.
+   * @param fileId File ID of the photo
+   * @returns {Blob} JPEG full image of the photo.
+   */
   IMAGE_FULL: (fileId: number) => `${BASE_URL}/image/full/${fileId}`,
 
+  /**
+   * Share a URL with native page.
+   * The native client MUST NOT download the object but share the URL directly.
+   * @param url URL to share (double-encoded)
+   * @returns {void}
+   */
   SHARE_URL: (url: string) => `${BASE_URL}/api/share/url/${euc(euc(url))}`,
+  /**
+   * Share an object (as blob) natively using a given URL.
+   * The native client MUST download the object using a download manager
+   * and immediately prompt the user to download it. The asynchronous call
+   * must return only after the object has been downloaded.
+   * @param url URL to share (double-encoded)
+   * @returns {void}
+   */
   SHARE_BLOB: (url: string) => `${BASE_URL}/api/share/blob/${euc(euc(url))}`,
+  /**
+   * Share a local file (as blob) with native page.
+   * @param fileId File ID of the photo
+   * @returns {void}
+   */
   SHARE_LOCAL: (fileId: number) => `${BASE_URL}/api/share/local/${fileId}`,
 
+  /**
+   * Get list of local folders configuration.
+   * @returns {LocalFolderConfig[]} List of local folders configuration
+   */
   CONFIG_LOCAL_FOLDERS: () => `${BASE_URL}/api/config/local-folders`,
 };
 
-/** The global NativeX interface. */
+/** NativeX synchronous API. */
 export type NativeX = {
+  /**
+   * Check if the native interface is available.
+   * @returns Should always return true.
+   */
   isNative: () => boolean;
+
+  /**
+   * Set the theme color of the app.
+   * @param color Color to set
+   * @param isDark Whether the theme is dark (for navigation bar)
+   */
   setThemeColor: (color: string, isDark: boolean) => void;
-  downloadFromUrl: (url: string, filename: string) => void;
+
+  /**
+   * Play a tap sound for UI interaction.
+   */
   playTouchSound: () => void;
 
+  /**
+   * Start downloading a file from a given URL.
+   * @param url URL to download from
+   * @param filename Filename to save as
+   * @details An error must be shown to the user natively if the download fails.
+   */
+  downloadFromUrl: (url: string, filename: string) => void;
+
+  /**
+   * Play a video from the given file ID (local file).
+   * @param fileid File ID of the video
+   */
   playVideoLocal: (fileid: string) => void;
+  /**
+   * Play a video from the given URL(s).
+   * @param fileid Remote file ID of the video (used for play tracking)
+   * @param urlArray JSON-encoded array of URLs to play
+   * @details The URL array may contain multiple URLs, e.g. direct playback
+   * and HLS separately. The native client must try to play the first URL.
+   */
   playVideoRemote: (fileid: string, urlArray: string) => void;
+  /**
+   * Destroy the video player.
+   * @param fileid File ID of the video
+   * @details The native client must destroy the video player and free up resources.
+   * If the fileid doesn't match the playing video, the call must be ignored.
+   */
   destroyVideo: (fileid: string) => void;
 
+  /**
+   * Set the local folders configuration to show in the timeline.
+   * @param json JSON-encoded array of LocalFolderConfig
+   */
   configSetLocalFolders: (json: string) => void;
 
+  /**
+   * Log out from Nextcloud and delete the tokens.
+   */
   logout: () => void;
 };