@jolibox/sdk 1.1.27 → 1.1.29-beta.1

package/src/sdks/router.ts

@@ -1,34 +1,73 @@
 import { BaseSDK } from './sdk';
-import { Router, ResponseType, StandardResponse, NavigateToNativePageType } from '@jolibox/types';
+import { Router, StandardResponse, ResponseType, NavigateToNativePageType } from '@jolibox/types';
 
 const NavigateToNativePageTypeTypes = ['openHistory'];
+
+/**
+ * @private
+ * Provides routing and navigation functionalities within the Jolibox SDK.
+ * This includes opening schemas, web pages, and navigating to native application pages.
+ * @implements {Router}
+ */
 export class RouterSDK extends BaseSDK implements Router {
-  async openSchema(schema: string) {
+  /**
+   * @public
+   * Opens a given schema URL.
+   * This is often used for deep linking or triggering specific actions within the host application or other apps.
+   * @param schema - The schema URL string to open (e.g., 'yourapp://action?param=value').
+   * @returns A promise that resolves with a StandardResponse, or an error object if the capability is not available.
+   */
+  async openSchema(
+    schema: string
+  ): Promise<StandardResponse<void> | { code: ResponseType; message: string }> {
     const errMsg = this.canIUseIfThrow('router.openSchema');
     if (errMsg) {
       return errMsg;
     }
     return await this.commands.executeCommand('RouterSDK.openSchema', schema);
   }
-  async openPage(url: string): Promise<
-    StandardResponse<{
-      webviewId: number;
-    }>
-  > {
+
+  /**
+   * @public
+   * Opens a web page in a new view (e.g., an in-app browser or a new tab).
+   * @param url - The URL of the web page to open.
+   * @returns A promise that resolves with a StandardResponse containing the webviewId, or an error object if the capability is not available.
+   */
+  async openPage(
+    url: string
+  ): Promise<StandardResponse<{ webviewId: number }> | { code: ResponseType; message: string }> {
     const errMsg = this.canIUseIfThrow('router.openPage');
     if (errMsg) {
       return errMsg;
     }
     return await this.commands.executeCommand('RouterSDK.openPage', url);
   }
-  async closePage(webviewId: number) {
+
+  /**
+   * @public
+   * Closes a previously opened web page/view, identified by its webviewId.
+   * @param webviewId - The ID of the webview to close.
+   * @returns A promise that resolves with a StandardResponse, or an error object if the capability is not available.
+   */
+  async closePage(
+    webviewId: number
+  ): Promise<StandardResponse<void> | { code: ResponseType; message: string }> {
     const errMsg = this.canIUseIfThrow('router.closePage');
     if (errMsg) {
       return errMsg;
     }
     return await this.commands.executeCommand('RouterSDK.closePage', webviewId);
   }
-  async interceptSystemExit(intercept: boolean) {
+
+  /**
+   * @public
+   * Intercepts the system's back button or exit gesture.
+   * @param intercept - A boolean indicating whether to intercept the exit (true) or allow default behavior (false).
+   * @returns A promise that resolves with a StandardResponse, or an error object if the capability is not available.
+   */
+  async interceptSystemExit(
+    intercept: boolean
+  ): Promise<StandardResponse<void> | { code: ResponseType; message: string }> {
     const errMsg = this.canIUseIfThrow('router.interceptSystemExit');
     if (errMsg) {
       return errMsg;
@@ -36,7 +75,17 @@ export class RouterSDK extends BaseSDK implements Router {
     return await this.commands.executeCommand('RouterSDK.interceptSystemExit', intercept);
   }
 
-  async navigateToNativePage(path: string, params: Record<string, unknown>) {
+  /**
+   * @public
+   * Navigates to a specific native page within the host application.
+   * @param path - The identifier for the native page to navigate to. Currently, only 'openHistory' is explicitly supported by this client-side check.
+   * @param params - A record of parameters to pass to the native page.
+   * @returns A promise that resolves with a StandardResponse, or an error object if the capability is not available or the path is invalid.
+   */
+  async navigateToNativePage(
+    path: string,
+    params: Record<string, unknown>
+  ): Promise<StandardResponse<void> | { code: ResponseType; message: string }> {
     const errMsg = this.canIUseIfThrow('router.navigateToNativePage');
     if (errMsg) {
       return errMsg;

package/src/sdks/runtime.ts

@@ -15,9 +15,10 @@ export enum JoliboxRuntimeEvents {
   LOAD_PROGRESS = 'JOLIBOX_RUNTIME_LOAD_PROGRESS'
 }
 /**
+ * @public
  * Default implementation of JoliboxRuntime, in case the JoliboxRuntime is not available
  */
-class FallbackJoliboxRuntime {
+export class FallbackJoliboxRuntime {
   /**
    * Notify the end of the loading, will close the loading splash screen
    */

package/src/sdks/sdk.ts

@@ -6,7 +6,16 @@ export interface BaseSDKEventMap {
 }
 
 export abstract class BaseSDK<T = BaseSDKEventMap> {
+  /**
+   * @private
+   * Instance for executing commands. Intended for internal SDK use.
+   */
   readonly commands = createCommands();
+
+  /**
+   * @private
+   * Event emitter instance for handling internal events. Intended for internal SDK use.
+   */
   readonly _emitter = new EventEmitter();
 
   addEventListener<K extends keyof T & string>(event: K, callback: (data: T[K]) => void) {

package/src/sdks/storage.ts

@@ -1,18 +1,38 @@
 import { BaseSDK } from './sdk';
 import { StandardResponse, Storage } from '@jolibox/types';
 
+/**
+ * @private
+ * Provides functionalities for persistent key-value storage within the Jolibox SDK.
+ * Allows setting, getting, removing items, and clearing the entire storage.
+ * @implements {Storage}
+ */
 export class StorageSDK extends BaseSDK implements Storage {
-  async getItem(key: string) {
+  /**
+   * @public
+   * Retrieves an item from storage based on its key.
+   * @param key - The key of the item to retrieve.
+   * @returns A promise that resolves with the value of the item, or null if the key is not found. The specific structure of the resolved value (e.g., if wrapped in StandardResponse) depends on the command execution result.
+   */
+  async getItem(key: string): Promise<StandardResponse<string | null>> {
     const result = await this.commands.executeCommand('StorageSDK.getItem', key);
-    return result;
+    return result as StandardResponse<string | null>;
   }
 
+  /**
+   * @public
+   * Sets an item in storage with a given key and value.
+   * There are limitations on the length of the key and the combined length of key and value.
+   * @param key - The key for the item. Should be less than 128 characters.
+   * @param value - The value to store. Can be a number, string, or boolean. It will be converted to a string for storage.
+   * @returns A promise that resolves with a StandardResponse. It might contain an error object if validation fails (e.g., key/value length exceeded).
+   */
   async setItem(key: string, value: number | string | boolean): Promise<StandardResponse<void>> {
     if (key.length > 128) {
       return {
         code: 'PARAMETER_ERROR',
         message: '[SDK] cloud storage setItem error: length of key should be less than 128'
-      };
+      } as StandardResponse<void>;
     }
 
     const valueToStore = typeof value == 'string' ? value : String(value);
@@ -20,16 +40,27 @@ export class StorageSDK extends BaseSDK implements Storage {
       return {
         code: 'PARAMETER_ERROR',
         message: '[SDK] cloud storage setItem error: length of key and value should be less than 1024'
-      };
+      } as StandardResponse<void>;
     }
-    return await this.commands.executeCommand('StorageSDK.setItem', key, value);
+    return await this.commands.executeCommand('StorageSDK.setItem', key, valueToStore);
   }
 
-  async removeItem(key: string) {
+  /**
+   * @public
+   * Removes an item from storage based on its key.
+   * @param key - The key of the item to remove.
+   * @returns A promise that resolves with a StandardResponse (or the direct result of command execution).
+   */
+  async removeItem(key: string): Promise<StandardResponse<void>> {
     return this.commands.executeCommand('StorageSDK.removeItem', key);
   }
 
-  async clear() {
+  /**
+   * @public
+   * Clears all items from the storage.
+   * @returns A promise that resolves with a StandardResponse (or the direct result of command execution).
+   */
+  async clear(): Promise<StandardResponse<void>> {
     return this.commands.executeCommand('StorageSDK.clear');
   }
 }

package/src/sdks/task.ts

@@ -1,6 +1,12 @@
 import { BaseSDK } from './sdk';
 import { TaskTracker, TaskResponse, type ResponseType } from '@jolibox/types';
 
+/**
+ * @public
+ * Provides functionalities for task tracking within the Jolibox SDK.
+ * Allows tracking of game levels, gameplay sessions, and level upgrades.
+ * @implements {TaskTracker}
+ */
 export class TaskTrackerSDK extends BaseSDK implements TaskTracker {
   /**
    * Handles completion of a game level by sending analytics data to the backend