@singcl/ad-execute-manager 1.5.1 → 1.5.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present, 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

@@ -1 +1,200 @@
-# AD Execute Manager
+# AD Execute Manager
+
+A powerful and flexible ad execution management library for handling reward-based ads, interstitial ads, and other advertising formats in JavaScript applications.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [API Reference](#api-reference)
+- [Examples](#examples)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- **Unified Ad Execution**: Single interface for managing different types of ads
+- **Task Queue Management**: Handles multiple ad execution tasks in a queue
+- **Flexible Control**: Manual control over ad execution flow with `next` function
+- **Error Handling**: Comprehensive error handling and logging
+- **State Persistence**: Built-in storage for ad state management
+- **Analytics Integration**: Built-in analytics support
+- **Middleware Pattern**: Uses middleware pattern for ad execution flow
+- **Cancellation Support**: Ability to clear and cancel pending tasks
+
+## Installation
+
+```bash
+npm install @singcl/ad-execute-manager
+```
+
+## Usage
+
+### Basic Usage
+
+```javascript
+import { AdExecuteManager, RewardAdFather } from '@singcl/ad-execute-manager';
+
+// Get the singleton instance
+const adManager = AdExecuteManager.getInstance();
+
+// Create an ad instance (extend RewardAdFather)
+class MyRewardAd extends RewardAdFather {
+  async ad(ctx, next) {
+    // Your ad logic here
+    console.log('Executing reward ad');
+    
+    // Call next when ready to proceed
+    await next();
+    
+    return { success: true, message: 'Ad executed successfully' };
+  }
+}
+
+// Create ad instance
+const myAd = new MyRewardAd();
+
+// Add task to execution queue
+const result = await adManager.addTask(myAd, {
+  options: { /* ad options */ },
+  collection: { /* callback collection */ }
+});
+```
+
+### Advanced Usage
+
+```javascript
+import { AdExecuteManager, RewardAdSceneTriggerManager } from '@singcl/ad-execute-manager';
+
+// Initialize with logging enabled
+const adManager = AdExecuteManager.getInstance({ log: true });
+
+// Check if manager is running
+if (adManager.isRunning()) {
+  console.log('Ad manager is currently executing tasks');
+}
+
+// Get current task ID
+const currentTaskId = adManager.getCurrentTaskId();
+
+// Get total number of pending tasks
+const taskCount = adManager.getTaskCount();
+
+// Wait for all tasks to complete
+await adManager.whenAllTasksComplete();
+
+// Clear all pending tasks
+adManager.clearTasks();
+```
+
+## API Reference
+
+### AdExecuteManager
+
+The main class for managing ad execution flow.
+
+#### Methods
+
+- `getInstance(args)`: Get the singleton instance of AdExecuteManager
+- `getSafeInstance()`: Get the instance, returns null if not initialized
+- `addTask(adInstance, ctx)`: Add an ad task to the execution queue
+- `clearTasks()`: Cancel all pending tasks
+- `getTaskCount()`: Get the number of pending tasks
+- `isRunning()`: Check if tasks are currently running
+- `getCurrentTaskId()`: Get the ID of the current executing task
+- `whenAllTasksComplete()`: Returns a Promise that resolves when all tasks are complete
+
+### RewardAdFather
+
+Base class for reward ad implementations.
+
+### InterstitialAdFather
+
+Base class for interstitial ad implementations.
+
+### Other Exports
+
+- `SerializableError`: Error class that can be serialized
+- `Logger`: Logging utility
+- `Storage`: Storage management
+- `CountRecorder`: Ad execution counter
+- `RewardAdGlobalRecorder`: Global ad recorder
+- `RewardAdSceneTriggerManager`: Scene-based ad trigger manager
+- `AdAnalyticsJS`: Analytics integration
+- `RewardAdNovel`: Novel-specific reward ad implementation
+- `InterstitialAdNovel`: Novel-specific interstitial ad implementation
+- `PubSub`: Publish-subscribe pattern implementation
+
+## Examples
+
+### Reward Ad Unlock
+
+```javascript
+import { AdExecuteManager, RewardAdFather } from '@singcl/ad-execute-manager';
+
+class UnlockAd extends RewardAdFather {
+  async ad(ctx, next) {
+    const { options, collection } = ctx;
+    
+    try {
+      // Show reward ad
+      const result = await this.showAd();
+      
+      if (result.isRewarded) {
+        // Execute success callback
+        collection.onSuccess && collection.onSuccess(result);
+        
+        // Proceed to next task
+        await next();
+        
+        return { success: true, data: result };
+      } else {
+        // Ad not completed
+        collection.onCancel && collection.onCancel();
+        return { success: false, message: 'Ad not completed' };
+      }
+    } catch (error) {
+      collection.onError && collection.onError(error);
+      throw error;
+    }
+  }
+}
+
+const adManager = AdExecuteManager.getInstance();
+const unlockAd = new UnlockAd();
+
+await adManager.addTask(unlockAd, {
+  options: { /* ad options */ },
+  collection: {
+    onSuccess: () => console.log('Reward received!'),
+    onCancel: () => console.log('Ad cancelled'),
+    onError: (error) => console.error('Ad error:', error)
+  }
+});
+```
+
+More examples can be found in the [examples](./example/) directory.
+
+## Contributing
+
+We welcome contributions to this project! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Commit your changes (`git commit -m 'Add some amazing feature'`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request
+
+### Development Scripts
+
+- `npm run build`: Build the library for production
+- `npm run dev`: Turn on watch mode
+- `npm run lint`: Lint your code
+- `npm run format`: Format your code
+- `npm run test`: Run tests
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

package/dist/ad/AdAnalyticsJS.d.ts

@@ -17,7 +17,7 @@ export type ICommonInfo = {
     [x: string]: any;
 };
 /**
- * @template {Object.<string, object>} EventDictionary
+ * @template {Object.<string, object>} EventDict
  */
 /**
  * @typedef {object} IConstructorArgs
@@ -66,13 +66,13 @@ declare class AdAnalyticsJS {
      * 追踪自定义事件
      * 用户交互，如点击、提交
      *
-     * @template {keyof EventDictionary} K
+     * @template {keyof EventDict} K
      * @param {K} eventName - The name of the event to track.
-     * @param {EventDictionary[K]} properties - The properties associated with the event.
+     * @param {EventDict[K]} properties - The properties associated with the event.
      * @param {object} [debugParams] - The debug parameters.
      * @param {string} [debugParams.sign] - Whether to enable debug mode.
      */
-    track<K extends keyof EventDictionary>(eventName: K, properties: EventDictionary[K], debugParams?: {
+    track<K extends keyof EventDict>(eventName: K, properties: EventDict[K], debugParams?: {
         sign?: string;
     }): void;
     /**
@@ -112,15 +112,15 @@ declare class AdAnalyticsJS {
      *
      * @template {'cpage'} K
      * @param {K} eventName - The name of the event to track.
-     * @param {EventDictionary[K]} properties - The properties associated with the event.
+     * @param {EventDict[K]} properties - The properties associated with the event.
      */
-    page<K extends "cpage">(eventName: K, properties: EventDictionary[K]): void;
+    page<K extends "cpage">(eventName: K, properties: EventDict[K]): void;
     /**
      *
-     * @param {EventDictionary['cpage']} properties
+     * @param {EventDict['cpage']} properties
      * @returns
      */
-    cpage(properties: EventDictionary["cpage"]): void;
+    cpage(properties: EventDict["cpage"]): void;
     /**
      * 站位方法，没有任何左右
      * @returns

package/dist/typings/tracker.d.ts

@@ -1,115 +1 @@
-/**
- * A dictionary mapping event names to their corresponding properties.
- */
-export type EventDictionary = {
-    /**
-     * - 免费解锁弹窗
-     */
-    free_unlock_popup: {
-        that: 0 | 1 | 2 | 3;
-        trigger_time: 0 | 1 | 2 | 3;
-        result: 0 | 1 | any;
-    };
-    /**
-     * - 加载激励广告 加载激励广告时触发 - 无太大参考意义，可以忽略
-     */
-    incentive_ad_load: {
-        scene: number;
-        result: string;
-    };
-    /**
-     * 展示激励广告 激励广告展示时触发
-     */
-    incentive_ad_show: {
-        scene: number;
-        result: string;
-        msg: string;
-    };
-    /**
-     * 关闭激励广告 激励广告关闭时触发
-     */
-    incentive_ad_close: {
-        scene: number;
-        ad_count: number;
-        ad_view_duration: string;
-        ad_is_completed: 0 | 1;
-    };
-    /**
-     * 注册登录 触发时机 "打开小程序 进行注册/登录
-     */
-    login: {
-        trigger_time: 1 | 2;
-        result: 0 | 1;
-    };
-    /**
-     * 简介页交互 触发时机 点击简介页的按钮
-     */
-    book_intro: {
-        trigger_time: 1 | 2 | 3 | 4;
-        book_title: 0 | 1;
-    };
-    /**
-     * 进入小程序页面
-     */
-    cpage: {
-        page: number;
-    };
-    /**
-     * 点击书籍
-     */
-    click_book: {
-        scene: number;
-        book_title: 0 | 1;
-    };
-    /**
-     * 添加桌面图标
-     */
-    add_shortcut: {
-        result: 0 | 1;
-        scene: number;
-    };
-    /**
-     * 小说章节展示 "1、用户首次展示新的章节（该章节如果未解锁，不上报；2s内只上报一次）2、用户解锁新的章节"
-     */
-    chapter_show: {
-        book_title: 0 | 1;
-        chapter_number: number;
-        is_end: number;
-    };
-    /**
-     * 小说阅读开始
-     */
-    speed_read_card: {
-        book_title: 0 | 1;
-        result: number;
-        trigger_time: number;
-    };
-    /**
-     * 展示首页福利弹窗
-     */
-    home_welfare_popup_show: {
-        trigger_time: 1 | 2;
-        result: 0 | 1;
-    };
-    /**
-     * 关闭首页福利弹窗
-     */
-    home_welfare_popup_close: {
-        trigger_way: 0 | 1 | 2;
-        result: 0 | 1;
-    };
-    /**
-     * 展示免费领取弹窗
-     */
-    free_popup_show: {
-        trigger_time: 1 | 2;
-        result: 0 | 1;
-    };
-    /**
-     * 关闭免费领取弹窗
-     */
-    free_popup_close: {
-        trigger_way: 0 | 1 | 2;
-        result: 0 | 1;
-    };
-};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@singcl/ad-execute-manager",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "type": "module",
   "exports": {
     ".": {
@@ -15,6 +15,7 @@
     "dist"
   ],
   "author": "singcl",
+  "license": "MIT",
   "homepage": "https://npmjs.com/package/@singcl/ad-execute-manager",
   "scripts": {
     "build": "rslib build && tsc",