@jolibox/sdk 1.1.27 → 1.1.28

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@jolibox/sdk",
   "description": "This project is common Jolibox JS-SDk interfere",
-  "version": "1.1.27",
+  "version": "1.1.28",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
   "typings": "dist/index.d.ts",
   "license": "MIT",
   "dependencies": {
-    "@jolibox/common": "1.1.27",
-    "@jolibox/types": "1.1.27"
+    "@jolibox/common": "1.1.28",
+    "@jolibox/types": "1.1.28"
   },
   "devDependencies": {
     "typescript": "5.7.3",
@@ -20,6 +20,17 @@
     "@babel/preset-env": "7.23.3",
     "@babel/preset-typescript": "7.23.3"
   },
+  "typedocOptions": {
+    "entryPoints": [
+      "src/index.ts",
+      "src/sdks/ads.ts",
+      "src/sdks/lifecycle.ts",
+      "src/sdks/runtime.ts",
+      "src/sdks/task.ts",
+      "src/api/*.ts"
+    ],
+    "name": "Jolibox SDK Document"
+  },
   "scripts": {
     "clean": "rimraf ./dist",
     "build": "npm run clean && npm run build:cjs && npm run build:esm && npm run build:iife && tsc",

package/sdk.build.log

@@ -1,17 +1,17 @@
 Invoking: npm run clean && npm run build:cjs && npm run build:esm && npm run build:iife && tsc 
 
-> @jolibox/sdk@1.1.27 clean
+> @jolibox/sdk@1.1.28 clean
 > rimraf ./dist
 
 
-> @jolibox/sdk@1.1.27 build:cjs
+> @jolibox/sdk@1.1.28 build:cjs
 > BUILD_VERSION=$(node -p "require('./package.json').version")  node esbuild.config.js --format=cjs
 
 
-> @jolibox/sdk@1.1.27 build:esm
+> @jolibox/sdk@1.1.28 build:esm
 > BUILD_VERSION=$(node -p "require('./package.json').version")  node esbuild.config.js --format=esm
 
 
-> @jolibox/sdk@1.1.27 build:iife
+> @jolibox/sdk@1.1.28 build:iife
 > BUILD_VERSION=$(node -p "require('./package.json').version")  node esbuild.config.js --format=iife
 

package/src/api/can-i-use.ts

@@ -3,6 +3,33 @@ import { getCanIUseConfig, get } from '../utils/can-i-use';
 
 const __VERSION__ = '__JOLIBOX_LOCAL_SDK_VERSION__'; // mock
 
+/**
+ * @public
+ * Checks if a specific API, component, or capability is available in the current environment.
+ * @param schema - The schema string to check (e.g., "component.button", "api.request").
+ * @returns True if available, false otherwise. Returns false if the underlying command execution fails.
+ *
+ * @example
+ * ```typescript
+ * // Check if a basic API is available
+ * if (canIUse('api.request')) {
+ *   console.log('Request API is available.');
+ * } else {
+ *   console.log('Request API is not available.');
+ * }
+ *
+ * // Check for a component
+ * if (canIUse('component.button')) {
+ *   console.log('Button component is supported.');
+ * }
+ *
+ * // Check for a specific method or property on an API
+ * // The schema format "ads:showInterstitialAd" is a common pattern for such checks.
+ * if (canIUse('ads:showInterstitialAd')) {
+ *   console.log('Showing interstitial ads is supported.');
+ * }
+ * ```
+ */
 export function canIUse(schema: string): boolean {
   const [name, ...rest] = schema.split(':');
 

package/src/api/get-system-info.ts

@@ -1,11 +1,37 @@
 import { createCommands } from '@jolibox/common';
+import type { ISystemInfo, Env, StandardResponse } from '@jolibox/types';
+// It's good practice to import specific types if known, e.g.:
+// import type { ISystemInfo, IEnvInfo } from '@jolibox/types';
 
 const commands = createCommands();
 
-export function getSystemInfoSync() {
+/**
+ * @public
+ * Synchronously retrieves system information.
+ * The specific structure of the returned system information object depends on the Jolibox environment.
+ * @returns {StandardResponse<ISystemInfo>} An object containing system information, wrapped in a StandardResponse.
+ * @see {@link ISystemInfo}
+ * @type {ISystemInfo}
+ * check IsystemInfo for more details
+ */
+export function getSystemInfoSync(): StandardResponse<ISystemInfo> {
   return commands.excuteCommandSync('API.getSystemInfoSync');
 }
 
-export function env() {
+/**
+ * @public
+ * Synchronously retrieves environment-specific information.
+ * This can include details about the host environment, application versions, etc., excluding 'hostUserInfo' and 'schema' from the full Env type.
+ * @returns {StandardResponse<Omit<Omit<Env, 'hostUserInfo'>, 'schema'>>} An object containing filtered environment information, wrapped in a StandardResponse.
+ * @see {@link Env}
+ * @type {Omit<Omit<Env, 'hostUserInfo'>, 'schema'>}
+ * check Env for more details
+ * @example
+ * ```typescript
+ * const envInfo = getEnvSync();
+ * console.log(envInfo);
+ * ```
+ */
+export function env(): StandardResponse<Omit<Omit<Env, 'hostUserInfo'>, 'schema'>> {
   return commands.excuteCommandSync('API.env');
 }

package/src/api/login.ts

@@ -1,24 +1,56 @@
 import { createCommands } from '@jolibox/common';
 import { canIUse } from './can-i-use';
-import { ResponseType } from '@jolibox/types';
+import { ResponseType, StandardResponse } from '@jolibox/types';
 
 const commands = createCommands();
-export async function login() {
+
+/**
+ * Data structure for successful login.
+ * @public
+ */
+export interface ILoginSuccessData {
+  isLogin: boolean;
+  token?: string;
+}
+
+/**
+ * @public
+ * Initiates the Jolibox login process.
+ * @returns A promise that resolves with the standard response containing login status and token if successful, or an error-like object if platform does not support login.
+ */
+export async function login(): Promise<
+  StandardResponse<ILoginSuccessData> | { code: ResponseType; message: string }
+> {
   if (!canIUse('login')) {
     return {
       code: 'FAILURE' as ResponseType,
       message: '[Jolibox SDK]login is not supported in this platform'
     };
   }
-  return await commands.executeCommand('API.login');
+  return (await commands.executeCommand('API.login')) as StandardResponse<ILoginSuccessData>;
+}
+
+/**
+ * Data structure for successful session check.
+ * @public
+ */
+export interface ICheckSessionSuccessData {
+  isLogin: boolean;
 }
 
-export async function checkSession() {
+/**
+ * @public
+ * Checks the current session status.
+ * @returns A promise that resolves with the standard response containing session status if successful, or an error-like object if platform does not support checkSession.
+ */
+export async function checkSession(): Promise<
+  StandardResponse<ICheckSessionSuccessData> | { code: ResponseType; message: string }
+> {
   if (!canIUse('checkSession')) {
     return {
       code: 'FAILURE' as ResponseType,
       message: '[Jolibox SDK]checkSession is not supported in this platform'
     };
   }
-  return await commands.executeCommand('API.checkSession');
+  return (await commands.executeCommand('API.checkSession')) as StandardResponse<ICheckSessionSuccessData>;
 }

package/src/api/on-custom-event.ts

@@ -3,31 +3,62 @@ import { hostEmitter } from '@jolibox/common';
 import { HostEventParamsMap } from '@jolibox/types';
 import { APIError } from '@jolibox/common';
 
-// Define the custom events we want to support
-type CustomEventType = 'onI18nChanged' | 'onBackPress';
+/**
+ * Defines the supported custom event names.
+ * @public
+ */
+export type CustomEventType = 'onI18nChanged' | 'onBackPress';
 
-const supportedEvents = ['onI18nChanged', 'onBackPress'];
+const supportedEvents: CustomEventType[] = ['onI18nChanged', 'onBackPress'];
 
-export const onCustomEvent = <T extends CustomEventType>(event: T, callback: HostEventParamsMap[T]) => {
+/**
+ * @public
+ * Registers a listener for a supported custom event.
+ * The callback will receive parameters specific to the event, as defined in {@link HostEventParamsMap}.
+ * @template T - The type of the event name, constrained to {@link CustomEventType}.
+ * @param event - The name of the event to listen for.
+ * @param callback - The callback function to execute when the event is triggered. Its parameters depend on the event type.
+ */
+export const onCustomEvent = <T extends CustomEventType>(event: T, callback: HostEventParamsMap[T]): void => {
   if (!supportedEvents.includes(event)) {
     reportError(new APIError(`[onCustomEvent] Unsupported event: ${event}`, 2000));
+    return; // It's good practice to return after reporting an error if proceeding is problematic
   }
-
   hostEmitter.on(event, callback);
 };
 
-export const offCustomEvent = <T extends CustomEventType>(event: T, callback: HostEventParamsMap[T]) => {
+/**
+ * @public
+ * Unregisters a listener for a custom event.
+ * @template T - The type of the event name, constrained to {@link CustomEventType}.
+ * @param event - The name of the event.
+ * @param callback - The specific callback to remove. If not provided, all listeners for the event might be removed (depending on hostEmitter implementation, though typically a specific callback is required by EventEmitter.off).
+ */
+export const offCustomEvent = <T extends CustomEventType>(
+  event: T,
+  callback: HostEventParamsMap[T]
+): void => {
   if (!supportedEvents.includes(event)) {
     reportError(new APIError(`[offCustomEvent] Unsupported event: ${event}`, 2000));
+    return;
   }
-
   hostEmitter.off(event, callback);
 };
 
-export const onceCustomEvent = <T extends CustomEventType>(event: T, callback: HostEventParamsMap[T]) => {
+/**
+ * @public
+ * Registers a one-time listener for a custom event. The listener is automatically removed after being invoked once.
+ * @template T - The type of the event name, constrained to {@link CustomEventType}.
+ * @param event - The name of the event to listen for.
+ * @param callback - The callback function to execute. Its parameters depend on the event type from {@link HostEventParamsMap}.
+ */
+export const onceCustomEvent = <T extends CustomEventType>(
+  event: T,
+  callback: HostEventParamsMap[T]
+): void => {
   if (!supportedEvents.includes(event)) {
     reportError(new APIError(`[onceCustomEvent] Unsupported event: ${event}`, 2000));
+    return;
   }
-
   hostEmitter.once(event, callback);
 };

package/src/index.ts

@@ -28,7 +28,7 @@ import { RouterSDK } from './sdks/router';
 
 declare global {
   interface Window {
-    JoliboxSDK: typeof JoliboxSDK; // TODO: code review this @Dengxue
+    JoliboxSDK: typeof JoliboxSDK;
     joliboxsdk: {
       runtime: InstanceType<typeof RuntimeSDK>;
       ads: InstanceType<typeof JoliboxAds>;
@@ -41,28 +41,159 @@ declare global {
   }
 }
 
+/**
+ * @public
+ * The main entry point and facade for the Jolibox JavaScript SDK.
+ * Provides access to various SDK modules and global API functions.
+ * This class is a singleton.
+ */
 export class JoliboxSDK {
   private static instance: JoliboxSDK | null = null;
 
+  /**
+   * @public
+   * @readonly
+   * The current version of the Jolibox JSSDK.
+   */
   readonly jssdkVersion = '__JOLIBOX_LOCAL_SDK_VERSION__';
+
+  /**
+   * @public
+   * @readonly
+   * Access to the Runtime SDK module.
+   * @see {@link RuntimeSDK} for more details.
+   * @type {RuntimeSDK}
+   */
   readonly runtime = new RuntimeSDK();
+
+  /**
+   * @public
+   * @readonly
+   * Access to the Ads SDK module.
+   * @see {@link JoliboxAds} for more details.
+   * @type {JoliboxAds}
+   */
   readonly ads = new JoliboxAds();
+
+  /**
+   * @public
+   * @readonly
+   * Access to the Lifecycle SDK module.
+   * @see {@link LifecycleSDK} for more details.
+   * @type {LifecycleSDK}
+   */
   readonly lifecycle = new LifecycleSDK();
+
+  /**
+   * @private
+   * @readonly
+   * Access to the Storage SDK module.
+   * @see {@link StorageSDK} for more details.
+   * @type {StorageSDK}
+   */
   readonly storage = new StorageSDK();
+
+  /**
+   * @private
+   * @readonly
+   * Access to the Keyboard SDK module.
+   * @see {@link KeyboardSDK} for more details.
+   * @type {KeyboardSDK}
+   */
   readonly keyboard = new KeyboardSDK();
+
+  /**
+   * @public
+   * @readonly
+   * Access to the Task Tracker SDK module.
+   * @see {@link TaskTrackerSDK} for more details.
+   * @type {TaskTrackerSDK}
+   */
   readonly task = new TaskTrackerSDK();
+
+  /**
+   * @private
+   * @readonly
+   * Access to the Router SDK module.
+   * @see {@link RouterSDK} for more details.
+   * @type {RouterSDK}
+   */
   readonly router = new RouterSDK();
 
   //global API
+  /**
+   * @public
+   * Synchronously gets system information.
+   * @see {@link getSystemInfoSync} for more details.
+   * @returns {ISystemInfo} The system information.
+   */
   getSystemInfoSync = getSystemInfoSync.bind(this);
+
+  /**
+   * @public
+   * Checks if a specific API, component, or capability is available in the current environment.
+   * @see {@link canIUse} for more details.
+   * @param {string} schema - The schema string to check (e.g., "component.button", "api.request").
+   * @returns {boolean} True if available, false otherwise.
+   */
   canIUse = canIUse.bind(this);
+
+  /**
+   * @public
+   * Initiates the login process.
+   * @see {@link login} for more details.
+   * @returns {Promise<ILoginSuccessData>} A promise that resolves with login success data.
+   */
   login = login.bind(this);
+
+  /**
+   * @public
+   * Checks the current session status.
+   * @see {@link checkSession} for more details.
+   * @returns {Promise<ICheckSessionSuccessData>} A promise that resolves with session status data.
+   */
   checkSession = checkSession.bind(this);
+
+  /**
+   * @private
+   * Makes an HTTP request.
+   * @see {@link request} for more details.
+   * @param {IRequestParams} params - Parameters for the HTTP request.
+   * @returns {Promise<IRequestSuccessData>} A promise that resolves with the request response.
+   */
   request = request.bind(this);
+
+  /**
+   * @public
+   * Registers a listener for a custom event.
+   * @see {@link onCustomEvent} for more details.
+   * @param {string} eventName - The name of the event to listen for.
+   * @param {(data: any) => void} callback - The callback function to execute when the event is triggered.
+   */
   on = onCustomEvent.bind(this);
+
+  /**
+   * @public
+   * Unregisters a listener for a custom event.
+   * @see {@link offCustomEvent} for more details.
+   * @param {string} eventName - The name of the event.
+   * @param {(data: any) => void} [callback] - The specific callback to remove. If not provided, all listeners for the event are removed.
+   */
   off = offCustomEvent.bind(this);
+
+  /**
+   * @public
+   * Registers a one-time listener for a custom event. The listener is automatically removed after being invoked once.
+   * @see {@link onceCustomEvent} for more details.
+   * @param {string} eventName - The name of the event to listen for.
+   * @param {(data: any) => void} callback - The callback function to execute.
+   */
   once = onceCustomEvent.bind(this);
 
+  /**
+   * @public
+   * Constructs a new JoliboxSDK instance or returns the existing singleton instance.
+   */
   constructor() {
     if (JoliboxSDK.instance) {
       return JoliboxSDK.instance;
@@ -82,7 +213,11 @@ export class JoliboxSDK {
     console.log(`JoliboxSDK ${this.jssdkVersion} init`);
   }
 
-  // 添加静态方法获取实例
+  /**
+   * @public
+   * Gets the singleton instance of the JoliboxSDK.
+   * @returns {JoliboxSDK} The singleton JoliboxSDK instance.
+   */
   public static getInstance(): JoliboxSDK {
     if (!JoliboxSDK.instance) {
       JoliboxSDK.instance = new JoliboxSDK();

package/src/sdks/ads.ts

@@ -7,8 +7,12 @@ import type {
 } from '@jolibox/types/dist/sdks/ads';
 import { BaseSDK, BaseSDKEventMap } from './sdk';
 
-type JoliboxAdsEventMap = BaseSDKEventMap
+export type JoliboxAdsEventMap = BaseSDKEventMap;
 
+/**
+ * @public
+ * Manages advertising functionalities within the Jolibox ecosystem.
+ */
 export class JoliboxAds extends BaseSDK<JoliboxAdsEventMap> implements IJoliboxAds {
   constructor() {
     super();
@@ -29,4 +33,13 @@ export class JoliboxAds extends BaseSDK<JoliboxAdsEventMap> implements IJoliboxA
   adUnit = (params: IAdUnitParams) => {
     this.commands.executeCommand('AdsSDK.adUnit', params);
   };
+
+  /**
+   * Initializes a new ad unit.
+   * @param unitId - The ID of the ad unit.
+   * @returns A promise that resolves when the ad is loaded.
+   */
+  public async initAd(unitId: string): Promise<void> {
+    // ...
+  }
 }

package/src/sdks/keyboard.ts

@@ -1,9 +1,13 @@
 import { BaseSDK } from './sdk';
 import { Keyboard, ResponseType } from '@jolibox/types';
 
+/**
+ * @private
+ * Manages keyboard functionalities within the Jolibox ecosystem. Only Support in Native App
+ */
 export class KeyboardSDK extends BaseSDK implements Keyboard {
   /**
-   * 显示键盘
+   * Show the keyboard
    * @param params
    * @returns
    */
@@ -15,7 +19,7 @@ export class KeyboardSDK extends BaseSDK implements Keyboard {
     this.commands.executeCommand('KeyboardSDK.showKeyboard', params);
   }
   /**
-   * 更新键盘
+   * Update the keyboard
    * @param value
    * @returns
    */
@@ -27,7 +31,7 @@ export class KeyboardSDK extends BaseSDK implements Keyboard {
     this.commands.executeCommand('KeyboardSDK.updateKeyboard', { value });
   }
   /**
-   * 隐藏键盘
+   * Hide the keyboard
    * @returns
    */
   hideKeyboard() {

package/src/sdks/lifecycle.ts

@@ -2,15 +2,32 @@ import { Env, Lifecycle } from '@jolibox/types';
 import { BaseSDK, BaseSDKEventMap } from './sdk';
 
 const LIFECYCLE_ON_READY = 'LifecycleSDK.onReady';
+
+/**
+ * @internal
+ * Defines the event map specific to the LifecycleSDK, extending BaseSDKEventMap.
+ */
 interface LifecycleSDKEventMap extends BaseSDKEventMap {
   [LIFECYCLE_ON_READY]: Env['hostUserInfo'] | undefined;
 }
 
+/**
+ * @public
+ * Manages lifecycle events and functionalities within the Jolibox SDK.
+ * This includes handling application readiness, exit procedures, and visibility changes.
+ */
 export class LifecycleSDK extends BaseSDK<LifecycleSDKEventMap> implements Lifecycle {
   constructor() {
     super();
   }
 
+  /**
+   * @public
+   * Registers a callback to be invoked when the Jolibox environment is ready.
+   * This typically signifies that the main application or game can start its operations.
+   * @param callback - A function to call when the environment is ready. It may receive host user information as a parameter.
+   * @event LifecycleSDK.onReady Dispatched after the provided callback is executed, with host user info.
+   */
   onReady(callback: (info?: Env['hostUserInfo']) => void) {
     const wrappedOnReady = (info?: Env['hostUserInfo']) => {
       callback.call(this, info);
@@ -19,6 +36,15 @@ export class LifecycleSDK extends BaseSDK<LifecycleSDKEventMap> implements Lifec
     this.commands.executeCommand('LifecycleSDK.onReady', wrappedOnReady.bind(this));
   }
 
+  /**
+   * @private
+   * Initiates the process to exit the Jolibox application or game.
+   * Allows registering a callback to be executed before the exit occurs.
+   * @param params - An object containing:
+   *   - `onBeforeExit`: A function to call before the application exits.
+   *   - `shouldStay` (optional): A boolean indicating if the application should attempt to prevent the exit. The exact behavior may depend on the host environment.
+   * @returns {object | undefined} An error object if the 'lifeCycle.exit' capability is not available, otherwise undefined.
+   */
   exit(params: { onBeforeExit: () => void; shouldStay?: boolean }) {
     const errMsg = this.canIUseIfThrow('lifeCycle.exit');
     if (errMsg) {
@@ -27,10 +53,21 @@ export class LifecycleSDK extends BaseSDK<LifecycleSDKEventMap> implements Lifec
     this.commands.executeCommand('LifecycleSDK.exit', params.onBeforeExit, params.shouldStay);
   }
 
-  onJoliboxHide(params: () => void) {
-    this.commands.executeCommand('LifecycleSDK.onJoliboxHide', params.bind(this));
+  /**
+   * @public
+   * Registers a callback to be invoked when the Jolibox application is hidden (e.g., moved to the background).
+   * @param callback - A function to call when the application is hidden.
+   */
+  onJoliboxHide(callback: () => void) {
+    this.commands.executeCommand('LifecycleSDK.onJoliboxHide', callback.bind(this));
   }
-  onJoliboxShow(params: () => void) {
-    this.commands.executeCommand('LifecycleSDK.onJoliboxShow', params.bind(this));
+
+  /**
+   * @public
+   * Registers a callback to be invoked when the Jolibox application is shown (e.g., brought to the foreground).
+   * @param callback - A function to call when the application is shown.
+   */
+  onJoliboxShow(callback: () => void) {
+    this.commands.executeCommand('LifecycleSDK.onJoliboxShow', callback.bind(this));
   }
 }