@ad-execute-manager/ad 2.0.0-alpha.1 → 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 singcl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,380 @@
+# @ad-execute-manager/ad
+
+Ad-related classes including InterstitialAdFather, InterstitialAdNovel, RewardAdFather, and RewardAdNovel for ad management.
+
+## Installation
+
+```bash
+npm install @ad-execute-manager/ad
+```
+
+## Features
+
+- **InterstitialAdFather**: Base class for interstitial ads with common functionality
+- **InterstitialAdNovel**: Novel-specific interstitial ad implementation with enhanced features
+- **RewardAdFather**: Base class for reward ads with common functionality
+- **RewardAdNovel**: Novel-specific reward ad implementation with enhanced features
+
+## Usage
+
+### InterstitialAdNovel
+
+```javascript
+import { InterstitialAdNovel } from '@ad-execute-manager/ad';
+
+const interstitialAd = InterstitialAdNovel.new({
+  sign: 'novel_interstitial',
+  preserveOnEnd: false,
+  needEndOnTimeout: true,
+  collection: {
+    onHalfway: (args) => {
+      console.log('Ad halfway:', args);
+    },
+    onShow: (args) => {
+      console.log('Ad shown:', args);
+    },
+    onFinish: (args) => {
+      console.log('Ad finished:', args);
+    },
+    onAlways: (args) => {
+      console.log('Ad always:', args);
+    },
+    onError: (error) => {
+      console.error('Ad error:', error);
+    }
+  }
+});
+
+// Initialize ad
+interstitialAd.initialize({
+  adUnitId: 'your-ad-unit-id',
+  retry: 3
+});
+
+// Show ad
+const result = await interstitialAd.addExecuteManager({
+  options: {
+    scene: 1
+  }
+});
+
+console.log('Ad result:', result);
+```
+
+### RewardAdNovel
+
+```javascript
+import { RewardAdNovel } from '@ad-execute-manager/ad';
+
+const rewardAd = RewardAdNovel.new({
+  sign: 'novel_reward',
+  preserveOnEnd: false,
+  needEndOnTimeout: true,
+  collection: {
+    onHalfway: (args) => {
+      console.log('Ad halfway:', args);
+    },
+    onShow: (args) => {
+      console.log('Ad shown:', args);
+    },
+    onFinish: (args) => {
+      console.log('Ad finished:', args);
+    },
+    onAlways: (args) => {
+      console.log('Ad always:', args);
+    },
+    onError: (error) => {
+      console.error('Ad error:', error);
+    }
+  }
+});
+
+// Initialize ad
+rewardAd.initialize({
+  adUnitId: 'your-ad-unit-id',
+  retry: 3
+});
+
+// Show ad
+const result = await rewardAd.addExecuteManager({
+  options: {
+    scene: 2,
+    timeout: 10000
+  }
+});
+
+console.log('Ad result:', result);
+```
+
+## API
+
+### InterstitialAdFather
+
+Base class for interstitial ads with common functionality.
+
+### InterstitialAdNovel
+
+```typescript
+class InterstitialAdNovel extends InterstitialAdFather {
+  /**
+   * Builds and returns an instance of InterstitialAdNovel
+   * @param args Construction arguments
+   * @returns Instance of InterstitialAdNovel
+   */
+  static build(args: IConstructArgs): InterstitialAdNovel;
+  
+  /**
+   * Gets the singleton instance of InterstitialAdNovel
+   * @returns Singleton instance of InterstitialAdNovel
+   */
+  static getInstance(): InterstitialAdNovel;
+  
+  /**
+   * Creates a new instance of InterstitialAdNovel
+   * @param args Construction arguments
+   * @returns New instance of InterstitialAdNovel
+   */
+  static new(args: IConstructArgs): InterstitialAdNovel;
+  
+  /**
+   * Initializes the ad with configuration
+   * @param params Ad configuration parameters
+   * @param callback Optional callback function
+   * @returns Current instance for method chaining
+   */
+  initialize(params: IRewordAdConfig, callback?: (v: IRewardedVideoAd) => void): this;
+  
+  /**
+   * Adds execute manager and runs the ad
+   * @param ctx Context object with options
+   * @returns Promise with ad execution result
+   */
+  addExecuteManager(ctx: any): Promise<any>;
+  
+  /**
+   * Clears the ad instance
+   */
+  clear(): void;
+  
+  /**
+   * Shifts the ad instance
+   */
+  shift(): void;
+}
+```
+
+### RewardAdFather
+
+Base class for reward ads with common functionality.
+
+### RewardAdNovel
+
+```typescript
+class RewardAdNovel extends RewardAdFather {
+  /**
+   * Builds and returns an instance of RewardAdNovel
+   * @param args Construction arguments
+   * @returns Instance of RewardAdNovel
+   */
+  static build(args: IConstructArgs): RewardAdNovel;
+  
+  /**
+   * Gets the singleton instance of RewardAdNovel
+   * @returns Singleton instance of RewardAdNovel
+   */
+  static getInstance(): RewardAdNovel;
+  
+  /**
+   * Creates a new instance of RewardAdNovel
+   * @param args Construction arguments
+   * @returns New instance of RewardAdNovel
+   */
+  static new(args: IConstructArgs): RewardAdNovel;
+  
+  /**
+   * Initializes the ad with configuration
+   * @param params Ad configuration parameters
+   * @param callback Optional callback function
+   * @returns Current instance for method chaining
+   */
+  initialize(params: IRewordAdConfig, callback?: (v: IRewardedVideoAd) => void): this;
+  
+  /**
+   * Adds execute manager and runs the ad
+   * @param ctx Context object with options
+   * @returns Promise with ad execution result
+   */
+  addExecuteManager(ctx: any): Promise<any>;
+  
+  /**
+   * Clears the ad instance
+   */
+  clear(): void;
+  
+  /**
+   * Shifts the ad instance
+   */
+  shift(): void;
+}
+```
+
+## Configuration
+
+### Construction Arguments
+
+When creating an ad instance, you can pass the following configuration options:
+
+- **sign**: Unique identifier for the ad instance
+- **preserveOnEnd**: Whether to preserve the instance after ad ends
+- **needEndOnTimeout**: Whether to end the ad on timeout
+- **collection**: Event collection object with callback functions
+  - **onHalfway**: Called when ad reaches halfway point
+  - **onShow**: Called when ad is shown
+  - **onFinish**: Called when ad finishes
+  - **onAlways**: Called always after ad operation
+  - **onError**: Called when ad encounters error
+
+### Initialize Parameters
+
+When initializing an ad, you can pass the following parameters:
+
+- **adUnitId**: Unique identifier for the ad unit
+- **retry**: Number of retry attempts on ad error
+
+## Examples
+
+### Example 1: Basic Interstitial Ad Usage
+
+```javascript
+import { InterstitialAdNovel } from '@ad-execute-manager/ad';
+
+// Create ad instance
+const interstitialAd = InterstitialAdNovel.new({
+  sign: 'chapter_end_interstitial',
+  preserveOnEnd: false,
+  needEndOnTimeout: true,
+  collection: {
+    onFinish: () => {
+      console.log('Interstitial ad finished, proceeding to next chapter');
+      // Proceed to next chapter logic here
+    },
+    onError: (error) => {
+      console.error('Interstitial ad error:', error);
+      // Handle error gracefully, maybe skip ad
+    }
+  }
+});
+
+// Initialize and show ad
+interstitialAd.initialize({ adUnitId: 'ca-app-pub-xxx/xxx', retry: 2 });
+
+// Show ad at chapter end
+async function showAdAtChapterEnd() {
+  try {
+    const result = await interstitialAd.addExecuteManager({ options: { scene: 1 } });
+    console.log('Ad result:', result);
+  } catch (error) {
+    console.error('Ad execution error:', error);
+  }
+}
+
+// Usage
+// showAdAtChapterEnd();
+```
+
+### Example 2: Reward Ad for Premium Content
+
+```javascript
+import { RewardAdNovel } from '@ad-execute-manager/ad';
+
+// Create reward ad instance
+const rewardAd = RewardAdNovel.new({
+  sign: 'premium_content_reward',
+  preserveOnEnd: true,
+  needEndOnTimeout: true,
+  collection: {
+    onFinish: (args) => {
+      console.log('Reward ad finished, unlocking premium content');
+      // Unlock premium content logic here
+      unlockPremiumContent();
+    },
+    onError: (error) => {
+      console.error('Reward ad error:', error);
+      // Show error message to user
+      showErrorMessage('Failed to load ad. Please try again later.');
+    }
+  }
+});
+
+// Initialize ad
+rewardAd.initialize({ adUnitId: 'ca-app-pub-xxx/xxx', retry: 3 });
+
+// Function to unlock premium content
+function unlockPremiumContent() {
+  // Logic to unlock premium content
+  console.log('Premium content unlocked!');
+}
+
+// Function to show error message
+function showErrorMessage(message) {
+  // Logic to show error message
+  console.log('Error:', message);
+}
+
+// Show reward ad to unlock premium content
+async function showRewardAdForPremium() {
+  try {
+    const result = await rewardAd.addExecuteManager({ 
+      options: { 
+        scene: 2, 
+        timeout: 15000 
+      } 
+    });
+    console.log('Reward ad result:', result);
+  } catch (error) {
+    console.error('Reward ad execution error:', error);
+  }
+}
+
+// Usage
+// showRewardAdForPremium();
+```
+
+### Example 3: Ad Instance Management
+
+```javascript
+import { InterstitialAdNovel, RewardAdNovel } from '@ad-execute-manager/ad';
+
+// Create ad instances
+const interstitialAd = InterstitialAdNovel.new({ sign: 'interstitial' });
+const rewardAd = RewardAdNovel.new({ sign: 'reward' });
+
+// Initialize ads
+interstitialAd.initialize({ adUnitId: 'ca-app-pub-xxx/xxx', retry: 2 });
+rewardAd.initialize({ adUnitId: 'ca-app-pub-xxx/xxx', retry: 3 });
+
+// Function to show appropriate ad based on user action
+async function showAdBasedOnAction(action) {
+  try {
+    switch (action) {
+      case 'chapter_end':
+        return await interstitialAd.addExecuteManager({ options: { scene: 1 } });
+      case 'unlock_premium':
+        return await rewardAd.addExecuteManager({ options: { scene: 2 } });
+      default:
+        throw new Error('Invalid ad action');
+    }
+  } catch (error) {
+    console.error('Ad error:', error);
+    return { success: false, error: error.message };
+  }
+}
+
+// Usage examples
+// showAdBasedOnAction('chapter_end');
+// showAdBasedOnAction('unlock_premium');
+```
+
+## License
+
+MIT

package/dist/{ad/InterstitialAdFather.d.ts → InterstitialAdFather.d.ts}

@@ -1,7 +1,11 @@
 export default InterstitialAdFather;
-export type IRewordAdConfig = import("../typings/ad.js").IRewordAdConfig;
-export type CallbackCollection = import("../typings/ad.js").CallbackCollection;
-export type IConstructArgs = import("../typings/ad.js").IConstructArgs;
+export type IRewordAdConfig = import("./typings/ad.js").IRewordAdConfig;
+export type CallbackCollection = import("./typings/ad.js").CallbackCollection;
+export type IConstructArgs = import("./typings/ad.js").IConstructArgs;
+/**
+ * 激励视频实例
+ */
+export type InterstitialAd = import("./typings/create-interstitial-ad.js").InterstitialAd;
 export type IRewardedVideoAd = {
     /**
      * 显示激励视频广告
@@ -24,23 +28,32 @@ declare class InterstitialAdFather {
      * @param {Object} adInstance 广告实例
      * @param {Object} ctx 上下文对象，用于传递数据和状态
      * @param {Object} ctx.options 广告执行选项
-     * @param {Object} ctx.options.log 是否打印日志
      * @param {Object} ctx.collection 回调集合
      * @returns {Promise} 广告执行结果的Promise
      */
     static executeWithManager(adInstance: any, ctx: {
-        options: {
-            log: any;
-        };
+        options: any;
         collection: any;
     }): Promise<any>;
     /**
      * @param {IConstructArgs} args
      */
     constructor(args: IConstructArgs);
+    /** @private  */
+    /** @type {Logger} */
+    _logger: Logger;
     _initSign: string;
     _preserveOnEnd: boolean;
-    _interstitialAd: any;
+    /**
+     * 激励视频实例
+     * @type {InterstitialAd | null}
+     */
+    _interstitialAd: InterstitialAd | null;
+    /**
+     * 激励视频实例
+     * @type {InterstitialAd | null}
+     */
+    __ad__: InterstitialAd | null;
     _ttErrorMsgs: string[];
     _ttErrorCodes: number[];
     _adConfig: {};
@@ -88,8 +101,26 @@ declare class InterstitialAdFather {
      * 任务执行完成后始终执行的一个方法
      * @abstract 任务执行完成后始终执行的一个方法，子类需要用到时实现此方法
      * @param {object} [_args] 执行结果信息
-     */
-    record(_args?: object): this;
+     * @param {number} [_args.scene] 场景信息
+     * @param {string} _args.id 任务id
+     * @param {object} [_args.apiError] 广告api错误信息
+     * @param {number} [_args.adTypeR] 广告类型 1 激励视频 2插屏广告
+     * @param {object} _args.recovered 后台恢复重试
+     * @param {boolean} [_args.recovered.retry] 后台恢复预估是否重试
+     * @param {number} [_args.recovered.count] 后台恢复预估重试次数
+     * @param {string} [_args.recovered.message] 后台恢复预估重试原因
+     */
+    record(_args?: {
+        scene?: number;
+        id: string;
+        apiError?: object;
+        adTypeR?: number;
+        recovered: {
+            retry?: boolean;
+            count?: number;
+            message?: string;
+        };
+    }): this;
     /**
      *
      * @param {({isEnded: boolean, count: number}) => void} callback
@@ -129,3 +160,4 @@ declare class InterstitialAdFather {
      */
     placeholder(): any;
 }
+import { Logger } from '@ad-execute-manager/helper';

package/dist/{ad/InterstitialAdNovel.d.ts → InterstitialAdNovel.d.ts}

@@ -1,5 +1,5 @@
 export default InterstitialAdNovel;
-export type IRewordAdConfig = import("../typings/ad.js").IRewordAdConfig;
+export type IRewordAdConfig = import("./typings/ad.js").IRewordAdConfig;
 export type ICallbackArgs = {
     /**
      * 广告执行场景
@@ -104,7 +104,7 @@ export type IRewardedVideoAd = {
     show: () => Promise<void>;
 };
 /**
- * @typedef {import('../typings/ad.js').IRewordAdConfig} IRewordAdConfig
+ * @typedef {import('./typings/ad.js').IRewordAdConfig} IRewordAdConfig
  */
 /**
  * @typedef ICallbackArgs
@@ -331,26 +331,30 @@ declare class InterstitialAdNovel extends InterstitialAdFather {
      * @override
      * @param {Object} [ctx] 上下文对象，用于传递数据和状态
      * @param {IRewordAdConfig} [ctx.options] 广告执行选项
-     * @param {import('../typings/ad.js').CallbackCollection} [ctx.collection] 回调集合
+     * @param {import('./typings/ad.js').CallbackCollection} [ctx.collection] 回调集合
      * @returns {Promise.<IEndArgs & ICloseArgs | Undefined>}
      */
     override addExecuteManager(ctx?: {
         options?: IRewordAdConfig;
-        collection?: import("../typings/ad.js").CallbackCollection;
+        collection?: import("./typings/ad.js").CallbackCollection;
     }): Promise<(IEndArgs & ICloseArgs) | undefined>;
     /**
+     * ATTENTION: 应用一旦进入后台，90%概率.show() 方法的.then() 回调将不会被执行, .catch() 回调也不会被执行。
+     * 此时将进入超时处理逻辑
      * @override
      * @param {object} [ctx] 广告执行上下文
-     * @param {import('../typings/ad.js').IRewordAdConfig} [ctx.options] 广告执行选项
-     * @param {import('../typings/ad.js').CallbackCollection} [ctx.collection] 回调集合
+     * @param {import('./typings/ad.js').IRewordAdConfig} [ctx.options] 广告执行选项
+     * @param {import('./typings/ad.js').CallbackCollection} [ctx.collection] 回调集合
      * @param {Function} next 执行下一个任务的回调函数，手动调用以继续执行流程
      * @returns {Promise.<IEndArgs & ICloseArgs | Undefined>}
      */
     override ad(ctx?: {
-        options?: import("../typings/ad.js").IRewordAdConfig;
-        collection?: import("../typings/ad.js").CallbackCollection;
+        options?: import("./typings/ad.js").IRewordAdConfig;
+        collection?: import("./typings/ad.js").CallbackCollection;
     }, next?: Function): Promise<(IEndArgs & ICloseArgs) | undefined>;
     /**
+     * ATTENTION: 应用一旦进入后台，90%概率.show() 方法的.then() 回调将不会被执行, .catch() 回调也不会被执行。
+     * 此时将进入超时处理逻辑
      * @param {object} [ctx] 广告执行上下文
      * @param {object} [ctx.options] 广告执行选项
      * @param {number} [ctx.options.scene] 广告执行场景

package/dist/{ad/RewardAdFather.d.ts → RewardAdFather.d.ts}

@@ -1,7 +1,9 @@
 export default RewardAdFather;
-export type IRewordAdConfig = import("../typings/ad.js").IRewordAdConfig;
-export type CallbackCollection = import("../typings/ad.js").CallbackCollection;
-export type IConstructArgs = import("../typings/ad.js").IConstructArgs;
+export type IRewordAdConfig = import("./typings/ad.js").IRewordAdConfig;
+export type CallbackCollection = import("./typings/ad.js").CallbackCollection;
+export type RecoveredInfo = import("./typings/ad.js").RecoveredInfo;
+export type IConstructArgs = import("./typings/ad.js").IConstructArgs;
+export type RewardedVideoAd = import("./typings/create-rewarded-video-ad.js").RewardedVideoAd;
 export type IRewardedVideoAd = {
     /**
      * 显示激励视频广告
@@ -24,25 +26,36 @@ declare class RewardAdFather {
      * @param {Object} adInstance 广告实例
      * @param {Object} ctx 上下文对象，用于传递数据和状态
      * @param {Object} ctx.options 广告执行选项
-     * @param {Object} ctx.options.log 是否打印日志
      * @param {Object} ctx.collection 回调集合
      * @returns {Promise} 广告执行结果的Promise
      */
     static executeWithManager(adInstance: any, ctx: {
-        options: {
-            log: any;
-        };
+        options: any;
         collection: any;
     }): Promise<any>;
     /**
      * @param {IConstructArgs} args
      */
     constructor(args: IConstructArgs);
+    /** @private  */
+    /** @type {Logger} */
+    _logger: Logger;
+    _adTimeoutTime: number;
     _initSign: string;
     _preserveOnEnd: boolean;
-    _rewardAd: any;
+    /**
+     * 激励视频实例
+     * @type {RewardedVideoAd | null}
+     */
+    _rewardAd: RewardedVideoAd | null;
+    /**
+     * 激励视频实例
+     * @type {RewardedVideoAd | null}
+     */
+    __ad__: RewardedVideoAd | null;
     _ttErrorMsgs: string[];
     _ttErrorCodes: number[];
+    __bindAdErrorForeverHandler: any;
     _adConfig: {};
     /**
      * 初始化
@@ -53,12 +66,29 @@ declare class RewardAdFather {
      */
     initialize(params: IRewordAdConfig, callback?: (v: IRewardedVideoAd) => void): this;
     initialized(): boolean;
+    /**
+     * 激励视频展示失败时始终执行的一个方法
+     * @private
+     * @param {{errMsg: string; errCode: number}} e 错误信息
+     */
+    private __adErrorForeverHandler;
+    /**
+     * 激励视频展示失败时始终执行的一个方法
+     * @abstract 激励视频展示失败时始终执行的一个方法，子类需要用到时实现此方法
+     * @param {{errMsg: string; errCode: number}} _e 错误信息
+     * @returns
+     */
+    adErrorForeverHandler(_e: {
+        errMsg: string;
+        errCode: number;
+    }): any;
     /**
      * 执行广告展示
      * @abstract
      * @param {Object} [ctx] 上下文对象，用于传递数据和状态
      * @param {IRewordAdConfig} [ctx.options] 广告执行选项
      * @param {CallbackCollection} [ctx.collection] 回调集合
+     * @param {RecoveredInfo} [ctx.recovered] 恢复重试信息
      * @param {Function} next 执行下一个任务的回调函数，在洋葱模型中手动调用以继续执行流程
      * @returns {Promise<unknown>} 广告执行结果的Promise
      * @throws {Error} 子类必须实现此方法
@@ -66,6 +96,7 @@ declare class RewardAdFather {
     ad(ctx?: {
         options?: IRewordAdConfig;
         collection?: CallbackCollection;
+        recovered?: RecoveredInfo;
     }, next?: Function): Promise<unknown>;
     /**
      * 确保广告按顺序执行
@@ -88,8 +119,26 @@ declare class RewardAdFather {
      * 任务执行完成后始终执行的一个方法
      * @abstract 任务执行完成后始终执行的一个方法，子类需要用到时实现此方法
      * @param {object} [_args] 执行结果信息
-     */
-    record(_args?: object): this;
+     * @param {number} [_args.scene] 场景信息
+     * @param {string} _args.id 任务id
+     * @param {object} [_args.apiError] 广告api错误信息
+     * @param {number} [_args.adTypeR] 广告类型 1 激励视频 2插屏广告
+     * @param {object} _args.recovered 后台恢复重试
+     * @param {boolean} [_args.recovered.retry] 后台恢复预估是否重试
+     * @param {number} [_args.recovered.count] 后台恢复预估重试次数
+     * @param {string} [_args.recovered.message] 后台恢复预估重试原因
+     */
+    record(_args?: {
+        scene?: number;
+        id: string;
+        apiError?: object;
+        adTypeR?: number;
+        recovered: {
+            retry?: boolean;
+            count?: number;
+            message?: string;
+        };
+    }): this;
     /**
      *
      * @param {({isEnded: boolean, count: number}) => void} callback
@@ -129,3 +178,4 @@ declare class RewardAdFather {
      */
     placeholder(): any;
 }
+import { Logger } from '@ad-execute-manager/helper';