@ad-execute-manager/core 2.0.0-alpha.3 → 2.0.0

package/README.md

@@ -1,110 +1,367 @@
-# @singcl/core
-
-Core functionality for ad execution management including AdExecuteManager, utility functions, and middleware composition.
-
-## Installation
-
-```bash
-npm install @singcl/core
-```
-
-## Features
-
-- **AdExecuteManager**: A powerful ad execution management class for handling reward-based ads, interstitial ads, and other advertising formats
-- **compose**: A middleware composition utility inspired by Koa
-- **needRetryAdError**: A utility function for determining if an ad error should be retried
-
-## Usage
-
-### AdExecuteManager
-
-```javascript
-import { AdExecuteManager } from '@singcl/core';
-
-const adManager = new AdExecuteManager({
-  // Configuration options
-});
-
-// Initialize ad
-const result = await adManager.init();
-
-// Show ad
-const showResult = await adManager.show();
-```
-
-### Middleware Composition
-
-```javascript
-import { compose } from '@singcl/core';
-
-const middlewares = [
-  async (ctx, next) => {
-    console.log('Middleware 1 start');
-    await next();
-    console.log('Middleware 1 end');
-  },
-  async (ctx, next) => {
-    console.log('Middleware 2 start');
-    await next();
-    console.log('Middleware 2 end');
-  }
-];
-
-const composedMiddleware = compose(middlewares);
-await composedMiddleware({});
-```
-
-### Error Retry Utility
-
-```javascript
-import { needRetryAdError } from '@singcl/core';
-
-const apiError = {
-  errMsg: 'ad_show_timeout: normal',
-  timeout: 5000
-};
-
-const shouldRetry = needRetryAdError({
-  apiError,
-  configuredAdTimeout: 5000,
-  errorRetryStrategy: {
-    timeout: true,
-    background: true
-  }
-});
-
-console.log('Should retry:', shouldRetry);
-```
-
-## API
-
-### AdExecuteManager
-
-The main class for managing ad execution with support for initialization, showing, and error handling.
-
-### compose
-
-```typescript
-function compose(middlewares: Array<(ctx: any, next: () => Promise<void>) => Promise<void>>): (ctx: any) => Promise<void>
-```
-
-### needRetryAdError
-
-```typescript
-function needRetryAdError({
-  apiError,
-  configuredAdTimeout,
-  errorRetryStrategy
-}: {
-  apiError: { errMsg?: string; timeout?: number };
-  configuredAdTimeout: number;
-  errorRetryStrategy?: {
-    timeout?: boolean;
-    background?: boolean;
-  };
-}): boolean
-```
-
-## License
-
-MIT
+# @ad-execute-manager/core
+
+Core functionality for ad execution management including AdExecuteManager, utility functions, and middleware composition.
+
+## Installation
+
+```bash
+npm install @ad-execute-manager/core
+```
+
+## Features
+
+- **AdExecuteManager**: A powerful ad execution management class for handling reward-based ads, interstitial ads, and other advertising formats
+- **compose**: A middleware composition utility inspired by Koa
+- **needRetryAdError**: A utility function for determining if an ad error should be retried
+
+## Usage
+
+### AdExecuteManager
+
+```javascript
+import { AdExecuteManager } from '@ad-execute-manager/core';
+
+const adManager = new AdExecuteManager({
+  // Configuration options
+});
+
+// Initialize ad
+const result = await adManager.init();
+
+// Show ad
+const showResult = await adManager.show();
+```
+
+### Middleware Composition
+
+```javascript
+import { compose } from '@ad-execute-manager/core';
+
+const middlewares = [
+  async (ctx, next) => {
+    console.log('Middleware 1 start');
+    await next();
+    console.log('Middleware 1 end');
+  },
+  async (ctx, next) => {
+    console.log('Middleware 2 start');
+    await next();
+    console.log('Middleware 2 end');
+  }
+];
+
+const composedMiddleware = compose(middlewares);
+await composedMiddleware({});
+```
+
+### Error Retry Utility
+
+```javascript
+import { needRetryAdError } from '@ad-execute-manager/core';
+
+const apiError = {
+  errMsg: 'ad_show_timeout: normal',
+  timeout: 5000
+};
+
+const shouldRetry = needRetryAdError({
+  apiError,
+  configuredAdTimeout: 5000,
+  errorRetryStrategy: {
+    timeout: true,
+    background: true
+  }
+});
+
+console.log('Should retry:', shouldRetry);
+```
+
+## Examples
+
+### 实际应用场景示例
+
+#### 1. 完整的广告执行流程
+
+```javascript
+import { AdExecuteManager } from '@ad-execute-manager/core';
+
+// 创建广告执行管理器实例
+const adManager = new AdExecuteManager({
+  log: true,
+  enableVisibilityListener: true,
+  maxRetryCount: 2,
+  errorRetryStrategy: {
+    timeout: true,
+    background: true
+  }
+});
+
+// 假设我们有一个广告实例类
+class MyRewardAd {
+  constructor() {
+    this._adTimeoutTime = 5000;
+  }
+
+  initialize(options) {
+    console.log('Initializing ad with options:', options);
+    return this;
+  }
+
+  async ad(ctx, next) {
+    const { options, collection, recovered } = ctx;
+    console.log('Showing ad with options:', options);
+    console.log('Recovered info:', recovered);
+
+    try {
+      // 模拟广告加载和显示
+      await new Promise(resolve => setTimeout(resolve, 1000));
+      
+      // 模拟广告成功
+      if (collection && collection.onSuccess) {
+        collection.onSuccess();
+      }
+      
+      await next({ success: true });
+      return { success: true };
+    } catch (error) {
+      // 模拟广告失败
+      if (collection && collection.onFail) {
+        collection.onFail(error);
+      }
+      
+      await next({ success: false, error });
+      return { success: false, error };
+    }
+  }
+
+  clear() {
+    console.log('Clearing ad resources');
+  }
+
+  record(info) {
+    console.log('Recording ad info:', info);
+  }
+}
+
+// 创建广告实例
+const rewardAd = new MyRewardAd();
+
+// 添加广告任务
+const result = await adManager.addTask(rewardAd, {
+  options: {
+    adUnitId: 'your-ad-unit-id',
+    userId: 'user123'
+  },
+  collection: {
+    onSuccess: () => console.log('Ad success callback'),
+    onFail: (error) => console.log('Ad fail callback:', error),
+    onCancel: () => console.log('Ad cancel callback')
+  }
+});
+
+console.log('Ad execution result:', result);
+
+// 等待所有任务完成
+await adManager.whenAllTasksComplete();
+console.log('All tasks completed');
+```
+
+#### 2. 自定义中间件组合
+
+```javascript
+import { compose } from '@ad-execute-manager/core';
+
+// 定义中间件
+const middleware1 = async (ctx, next) => {
+  console.log('Middleware 1 start');
+  ctx.value1 = 'value1';
+  await next();
+  console.log('Middleware 1 end');
+};
+
+const middleware2 = async (ctx, next) => {
+  console.log('Middleware 2 start');
+  console.log('Received value1:', ctx.value1);
+  ctx.value2 = 'value2';
+  await next();
+  console.log('Middleware 2 end');
+};
+
+const middleware3 = async (ctx, next) => {
+  console.log('Middleware 3 start');
+  console.log('Received value1:', ctx.value1);
+  console.log('Received value2:', ctx.value2);
+  ctx.value3 = 'value3';
+  await next();
+  console.log('Middleware 3 end');
+};
+
+// 组合中间件
+const composedMiddleware = compose([middleware1, middleware2, middleware3]);
+
+// 执行组合后的中间件
+const ctx = { initialValue: 'initial' };
+await composedMiddleware(ctx);
+
+console.log('Final ctx:', ctx);
+```
+
+#### 3. 错误处理和重试策略
+
+```javascript
+import { needRetryAdError } from '@ad-execute-manager/core';
+
+// 模拟不同类型的错误
+const timeoutError = {
+  errMsg: 'ad_show_timeout: normal',
+  timeout: 5000
+};
+
+const backgroundError = {
+  errMsg: 'app in background is not support show ad'
+};
+
+const otherError = {
+  errMsg: 'ad_load_fail: network error'
+};
+
+// 配置重试策略
+const retryStrategy = {
+  timeout: true,
+  background: true
+};
+
+// 检查各种错误是否需要重试
+const shouldRetryTimeout = needRetryAdError({
+  apiError: timeoutError,
+  configuredAdTimeout: 5000,
+  errorRetryStrategy: retryStrategy
+});
+
+const shouldRetryBackground = needRetryAdError({
+  apiError: backgroundError,
+  configuredAdTimeout: 5000,
+  errorRetryStrategy: retryStrategy
+});
+
+const shouldRetryOther = needRetryAdError({
+  apiError: otherError,
+  configuredAdTimeout: 5000,
+  errorRetryStrategy: retryStrategy
+});
+
+console.log('Should retry timeout error:', shouldRetryTimeout);
+console.log('Should retry background error:', shouldRetryBackground);
+console.log('Should retry other error:', shouldRetryOther);
+```
+
+## API
+
+### AdExecuteManager
+
+The main class for managing ad execution with support for initialization, showing, and error handling.
+
+#### Constructor
+
+```javascript
+new AdExecuteManager(args)
+```
+
+- **args** (Object): 构造函数参数
+  - **options** (Object, optional): 广告执行选项
+  - **log** (Boolean, optional): 是否打印日志
+  - **enableVisibilityListener** (Boolean, optional): 是否启用前后台监听
+  - **maxRetryCount** (Number, optional): 最大重试次数，默认为 1，0 表示不重试
+  - **errorRetryStrategy** (Object, optional): 错误重试策略
+    - **timeout** (Boolean, optional): 是否重试超时错误
+    - **background** (Boolean, optional): 是否重试后台错误
+
+#### Methods
+
+- **initialize(_args)**: 初始化 AdExecuteManager 实例
+  - **_args** (Any): 初始化参数
+  - 返回: AdExecuteManager 实例
+
+- **addTask(adInstance, ctx)**: 添加广告任务
+  - **adInstance** (Object): RewardAdFather 的子类实例
+  - **ctx** (Object): 广告执行上下文
+    - **options** (Object): 广告执行选项
+    - **collection** (Object): 回调集合
+  - 返回: Promise，广告执行结果的 Promise
+
+- **clearTasks()**: 清空任务栈并取消所有任务
+
+- **getTaskCount()**: 获取当前未完成的任务总数
+  - 返回: Number，未完成的任务数量
+
+- **isRunning()**: 是否有任务正在运行
+  - 返回: Boolean
+
+- **getCurrentTaskId()**: 获取当前执行的任务 ID
+  - 返回: String|null，当前任务 ID
+
+- **whenAllTasksComplete()**: 返回一个 Promise，当任务队列中的所有任务都完成时 resolve
+  - 返回: Promise<void>
+
+- **enableVisibilityListener()**: 启用前后台监听
+
+- **disableVisibilityListener()**: 禁用前后台监听
+
+- **isVisibilityListenerEnabled()**: 获取前后台监听器状态
+  - 返回: Boolean，是否启用
+
+- **destroyVisibilityListener()**: 销毁前后台监听器
+
+- **static getInstance(args)**: 获取单例实例
+  - **args** (Object, optional): 构造函数参数
+  - 返回: AdExecuteManager 实例
+
+- **static build(args)**: 获取单例实例
+  - **args** (Object, optional): 构造函数参数
+  - 返回: AdExecuteManager 实例
+
+- **static new(args)**: 创建新实例
+  - **args** (Object, optional): 构造函数参数
+  - 返回: AdExecuteManager 实例
+
+- **static getSafeInstance()**: 获取单例实例，如果不存在则返回 null
+  - 返回: AdExecuteManager|null
+
+### compose
+
+```typescript
+function compose(middlewares: Array<(ctx: any, next: () => Promise<void>) => Promise<void>>): (ctx: any) => Promise<void>
+```
+
+- **middlewares** (Array<Function>): KOA 中间件数组，每个中间件函数接收 ctx 和 next 参数
+- 返回: Function，返回一个组合后的中间件函数，接收 ctx 参数并按顺序执行所有中间件
+
+### needRetryAdError
+
+```typescript
+function needRetryAdError({
+  apiError,
+  configuredAdTimeout,
+  errorRetryStrategy
+}: {
+  apiError: { errMsg?: string; timeout?: number };
+  configuredAdTimeout: number;
+  errorRetryStrategy?: {
+    timeout?: boolean;
+    background?: boolean;
+  };
+}): boolean
+```
+
+- **apiError** (Object): 广告错误信息
+  - **errMsg** (String, optional): 错误信息
+  - **timeout** (Number, optional): 超时时间
+- **configuredAdTimeout** (Number): 配置的广告超时时间
+- **errorRetryStrategy** (Object, optional): 错误重试策略
+  - **timeout** (Boolean, optional): 是否重试超时错误
+  - **background** (Boolean, optional): 是否重试后台错误
+- 返回: Boolean，是否需要重试
+
+## License
+
+MIT

package/dist/AdExecuteManager.d.ts

@@ -1,17 +1,34 @@
 export default AdExecuteManager;
+export type IAdInstance = {
+    /**
+     * 超时时间
+     */
+    _adTimeoutTime: number;
+    /**
+     * 初始化广告
+     */
+    initialize: (ctx: unknown) => IAdInstance;
+    /**
+     * 显示广告
+     */
+    ad: (options: unknown, ctx: unknown, recovered: unknown) => Promise<unknown>;
+    clear: () => void;
+};
+export type IRewordAdConfig = import("./typings/ad.js").IRewordAdConfig;
+export type CallbackCollection = import("./typings/ad.js").CallbackCollection;
 export type AdTask = {
     /**
      * RewardAdFather的子类实例
      */
-    adInstance: any;
+    adInstance: IAdInstance;
     /**
      * 广告执行选项
      */
-    options: any;
+    options: IRewordAdConfig;
     /**
      * 回调集合
      */
-    callbackCollection: any;
+    callbackCollection: CallbackCollection;
     /**
      * 广告执行成功的回调函数
      */
@@ -191,15 +208,15 @@ declare class AdExecuteManager {
     isVisibilityListenerEnabled(): boolean;
     /**
      * 添加广告任务
-     * @param {import('../ad/RewardAdFather.js').default} adInstance RewardAdFather的子类实例
+     * @param {IAdInstance} adInstance RewardAdFather的子类实例
      * @param {Object} ctx 广告执行上下文
-     * @param {import('../typings/ad.js').IRewordAdConfig} ctx.options 广告执行选项
-     * @param {import('../typings/ad.js').CallbackCollection} ctx.collection 回调集合
+     * @param {IRewordAdConfig} ctx.options 广告执行选项
+     * @param {CallbackCollection} ctx.collection 回调集合
      * @returns {Promise} 广告执行结果的Promise
      */
-    addTask(adInstance: any, ctx: {
-        options: any;
-        collection: any;
+    addTask(adInstance: IAdInstance, ctx: {
+        options: IRewordAdConfig;
+        collection: CallbackCollection;
     }): Promise<any>;
     /**
      * 组合所有任务

package/dist/typings/ad.d.ts

@@ -0,0 +1,208 @@
+export type IRewordAdConfig = {
+    /**
+     * 激励视频广告id - 必填
+     */
+    adUnitId: string;
+    /**
+     * 是否开启进度提醒。开启时广告文案为「再看 n 个xxx」，关闭时为「再看 1 个xxx」。其中 n 表示用户当前还需额外观看广告的次数
+     */
+    progressTip?: boolean | undefined;
+    /**
+     * - 再得广告的奖励文案，用户每看完一个广告都会展示，multiton 为 true 时必填。
+     * - 文案完整内容为「再看 1 个xxx」，其中 xxx 是 multitonRewardMsg 配置的文案内容，最大长度为 7，
+     * - 文案内容根据 multitonRewardMsg 的配置按顺序展示。若 multitonRewardMsg 长度小于 multitonRewardTimes ，
+     * - 则后续的激励再得广告文案取 multitonRewardMsg 数组最后一个。
+     */
+    multitonRewardMsg?: Array<string> | undefined;
+    /**
+     * 是否开启激励再得广告
+     */
+    multiton?: boolean | undefined;
+    /**
+     * 额外观看广告的次数，合法的数据范围为 1～4，multiton 为 true 时必填
+     */
+    multitonRewardTimes?: number | undefined;
+    /**
+     * 场景值 - 自用参数，非tt API要求的参数
+     */
+    scene?: number | undefined;
+    /**
+     * 广告超时时间 单位ms - 自用参数，非tt API要求的参数
+     */
+    timeout?: number | undefined;
+    /**
+     * 重试次数 - 自用参数 ，非tt API要求的参数
+     */
+    retry: number;
+    /**
+     * 是否绑定永远的错误事件 - 自用参数，非tt API要求的参数
+     */
+    foreverErrorBind?: boolean | undefined;
+};
+export type InterstitialAdConfig = {
+    /**
+     * 单个广告单元的 id。可从「开放平台控制台-进入对应小程序-运营-商业化变现-广告管理」中获取 - 必填
+     */
+    adUnitId: string;
+    /**
+     * 场景值 - 自用参数
+     */
+    scene?: number | undefined;
+};
+export type IExeCallbackArgs = {
+    /**
+     * 广告执行场景
+     */
+    scene: number;
+    /**
+     * 是否看完
+     */
+    isEnded: boolean;
+    /**
+     * 完整观看次数
+     */
+    count: number;
+    /**
+     * 剩余观看次数
+     */
+    remain?: number;
+};
+export type CallbackCollection = {
+    /**
+     * 每次外部回调
+     */
+    always?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 完整看完广告外部回调 不管一个还是几个
+     */
+    finished?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 半途退出广告外部回调
+     */
+    halfway?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 完成广告外部回调 不管看不看完
+     */
+    complete?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 取消广告外部回调
+     */
+    onCancel?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 展示广告外部回调
+     */
+    before?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 展示广告成功外部回调
+     */
+    success?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 计时回调
+     */
+    prelude?: (ctx?: unknown) => void;
+};
+export type RecoveredInfo = {
+    /**
+     * 恢复重试次数
+     */
+    count: number;
+    /**
+     * 是否恢复重试
+     */
+    retry: boolean;
+    /**
+     * 恢复重试原因
+     */
+    message: string;
+};
+export type ICallbackArgs = {
+    /**
+     * 广告执行场景
+     */
+    scene: number;
+    /**
+     * 是否看完
+     */
+    isEnded: boolean;
+    /**
+     * 完整观看次数
+     */
+    count: number;
+    /**
+     * 剩余观看次数
+     */
+    remain?: number;
+    /**
+     * 执行下一个任务的回调函数，手动调用以继续执行流程[end]
+     */
+    end?: () => void;
+    /**
+     * 执行下一个任务的回调函数， 手动调用以继续执行流程[circle]
+     */
+    circle?: (args: {
+        ignoreRemain: boolean;
+        scene: number;
+    }) => void;
+};
+export type IConnection = {
+    /**
+     * 广告中途退出回调
+     */
+    onHalfway?: (args: ICallbackArgs) => void;
+    /**
+     * 广告展示回调
+     */
+    onShow?: (args: ICallbackArgs) => void;
+    /**
+     * 广告执行成功回调
+     */
+    onFinish?: (args: ICallbackArgs) => void;
+    /**
+     * 广告执行失败回调
+     */
+    onError?: (e: unknown) => void;
+};
+export type IConstructArgs = {
+    /**
+     * 初始化标识
+     */
+    sign: string;
+    /**
+     * 是否开启日志
+     */
+    log?: boolean | undefined;
+    /**
+     * 重试次数
+     */
+    retry: number;
+    /**
+     * 是否保留tt激励视频广告实例
+     */
+    preserveOnEnd: boolean;
+    /**
+     * 激励视频参数 (可选)
+     */
+    adConfig?: IRewordAdConfig | undefined;
+    /**
+     * 回调集合
+     */
+    collection?: IConnection | undefined;
+};
+/**
+ * 广告场景类型映射对象
+ */
+export type SceneTypeMap = {
+    readonly [x: number]: string;
+};
+/**
+ * 广告场景类型文本映射对象（反向映射）
+ */
+export type SceneTextMap = { readonly [K in SceneTypeMap[keyof SceneTypeMap]]: { [P in keyof SceneTypeMap]: SceneTypeMap[P] extends K ? P : never; }[keyof SceneTypeMap]; };
+/**
+ * 场景值枚举 可持续添加
+ */
+export type RewardAdTriggerScene = keyof SceneTextMap;
+/**
+ * 场景值枚举 可持续添加
+ */
+export type RewardAdTriggerSceneType = keyof SceneTypeMap;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ad-execute-manager/core",
-  "version": "2.0.0-alpha.3",
+  "version": "2.0.0",
   "description": "Core functionality for ad execution management including AdExecuteManager, utility functions, and middleware composition.",
   "type": "module",
   "exports": {
@@ -21,7 +21,7 @@
     "url": "https://github.com/singcl"
   },
   "license": "MIT",
-  "homepage": "https://npmjs.com/package/@singcl/core",
+  "homepage": "https://npmjs.com/package/@ad-execute-manager/core",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/singcl/ad-execute-manager.git"
@@ -52,7 +52,7 @@
   },
 
   "dependencies": {
-    "@ad-execute-manager/helper": "^2.0.0-alpha.2"
+    "@ad-execute-manager/helper": "^2.0.1"
   },
   "devDependencies": {
     "@babel/eslint-parser": "^7.28.5",