@singcl/ad-execute-manager 1.5.2 → 1.5.3

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@singcl/ad-execute-manager",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "type": "module",
   "exports": {
     ".": {