@directo/adunit 0.0.1-beta.2

package/README.md

@@ -0,0 +1,228 @@
+# Directo adUnit Integration Guide
+
+<img alt="version" src="https://img.shields.io/badge/version-0.0.0-blue?style=flat" />
+<a href="https://getdirecto.com" target="_blank">
+  <img alt="getdirecto.com" src="https://img.shields.io/badge/getdirecto-join-brightgreen?style=flat" />
+</a>
+
+## Overview
+
+This guide provides comprehensive instructions for integrating the **Directo adUnit Library** into your browser extension projects. It covers installation, background/content setup, required permissions, message filtering, API usage, and troubleshooting. 
+
+## Installation Methods
+
+### Method 1: NPM Installation
+
+1. Install the package from npm:
+
+```shell
+npm install @directo/adunit
+```
+
+2. Import the library in your code:
+
+```javascript
+// In background scripts
+import { initializeAdUnit, isAdUnitMessage } from '@directo/adunit/background';
+
+// In content scripts
+import { initializeAdUnit } from '@directo/adunit/content';
+```
+
+3. Use your bundler of choice (Vite, webpack, Rollup, esbuild) to build your extension.
+
+**TypeScript Compatibility Note:** This package is bundled with the ES2022 library and targets ES6. Ensure your project's TypeScript configuration (`tsconfig.json`) is compatible with these settings for optimal type support and compatibility.
+
+@todo
+### Method 2: Direct Script Inclusion
+
+1. Obtain the Directo library JS builds from the `directo-global` folder:
+
+* directo-global/background.js – for background/service worker
+
+* directo-global/content.js – for content scripts
+
+2. Place these files in your extension (e.g., vendor/).
+
+3. Reference them in manifest.json and your entry points:
+
+```json
+{
+  "background": {
+    "service_worker": "background.js"
+  },
+  "content_scripts": [
+    {
+      "matches": ["<all_urls>"],
+      "js": [
+        "vendor/directo-global/content.js",
+        "content.js"
+      ]
+    }
+  ]
+}
+```
+
+## Implementation Guide
+
+### Background Script
+
+After installing via NPM or including the JS file:
+
+```javascript
+// For JS inclusion only (Method 2):
+// self.importScripts('vendor/directo-global/background.js');
+// this.DirectoAdUnit.initializeAdUnit('YOUR_PARTNER_API_KEY');
+
+// Using an IIFE for error handling isolation in the service worker context
+(() => {
+  try {
+    // Initialize the Directo adUnit with your partner API key
+    initializeAdUnit('YOUR_PARTNER_API_KEY');
+    console.log('Directo background initialized successfully');
+  } catch (err) {
+    console.error('Failed to initialize Directo:', err);
+    // Optional: fallback logic
+  }
+})();
+```
+
+The background process bootstraps the Directo runtime, sets up listeners, and coordinates content activity. 
+
+
+### Content Script
+
+```javascript
+async function initializeContent() {
+  if (document.body) {
+    try {
+      console.log('Attempting to initialize Directo AdUnit');
+      await initializeAdUnit();
+      console.log('Directo AdUnit initialized successfully');
+    } catch (error) {
+      console.error('Error initializing Directo AdUnit:', error);
+    }
+  } else {
+    console.warn('Document body not available yet');
+    setTimeout(initializeContent, 50);
+  }
+}
+
+if (document.readyState === 'loading') {
+  console.log('Document still loading, waiting for DOMContentLoaded');
+  document.addEventListener('DOMContentLoaded', initializeContent);
+} else {
+  console.log('Document already loaded, running initialization immediately');
+  initializeContent();
+}
+```
+
+Initialize the AdUnit early, once the DOM is ready, to ensure timely UI/display behavior. 
+
+## Required Permissions
+
+**Exception requested:** the required extension permissions for this Directo integration are **storage** and **unlimitedStorage**
+
+```json
+{
+  "permissions": [
+    "storage",
+    "unlimitedStorage"
+  ],
+  "host_permissions": [ "<all_urls>" ]
+}
+```
+
+**Permission explanation**
+
+* storage: persists configuration and user preferences used by the AdUnit/runtime.  
+* unlimitedStorage (optional but recommended): if your combined extension \+ Directo data may exceed 10 MB; expect several MB used by cached rules/assets.  
+
+Ensure your injection strategy (e.g., content scripts declared in manifest.json) aligns with this permissions model. 
+
+## Critical Integration Requirements
+
+### Auto-Rejecting Directo Messages
+
+⚠️ **IMPORTANT:** Your extension **must** short-circuit Directo internal messages in your message listener to avoid conflicts with your own app messages. 
+
+```javascript
+// If using the package:
+import { isAdUnitMessage } from '@directo/adunit/background';
+
+// Example message listener (service worker / background)
+chrome.runtime.onMessage.addListener((data, sender, sendResponse) => {
+  // Always gate Directo messages first:
+  if (isAdUnitMessage(data)) {
+    return; // Ignore: handled internally by Directo
+  }
+
+  // Your extension's message handling below...
+});
+```
+
+Why this is required
+
+Without this guard:
+
+1. Your extension might process Directo’s internal messages.
+
+2. Directo functionality could break or behave unpredictably.
+
+3. You may see console errors or crashes stemming from message handling. 
+
+## API Reference
+
+### Background Script API
+
+```javascript
+initializeAdUnit('YOUR_PARTNER_API_KEY');
+```
+
+### Content Script API
+
+```javascript
+// Sets up the Directo AdUnit and observers
+initializeAdUnit();
+```
+
+Implement robust try/catch (or .catch) around initialization to surface failures and enact fallbacks. Both functions return promises that should be fire-and-forget, however we encourage handling initialization errors.
+
+## Error Handling
+
+```javascript
+initializeAdUnit('YOUR_PARTNER_KEY')
+  .then(() => {
+    console.log('Directo background initialized successfully');
+  })
+  .catch((error) => {
+    console.error('Failed to initialize Directo:', error);
+    // Add any cleanup or degraded-mode logic here
+  });
+```
+
+## Testing Your Integration
+
+1. Confirm the background script initializes without errors (Service Worker logs).
+
+2. Navigate to pages where the AdUnit should activate and verify expected UI/behavior.
+
+## Troubleshooting
+
+### Common issues
+
+* **Initialization Failures**: Usually invalid/absent API key or network errors.
+
+* **Missing AdUnit UI**: Ensure content scripts are injected as expected (manifest matches) and that DOM is ready before calling initializeAdUnit().
+
+* **Console Errors**: Inspect logs from both background and content scripts.
+
+* **Minimum Version**: Confirm compatibility with the minimum Directo library version intended for this integration. 
+
+## Support
+
+For technical support or integration questions, contact julian@getdirecto.com.
+
+## License
+
+Proprietary - Directo Tech, Inc.

package/dist/background.d.ts

@@ -0,0 +1,10 @@
+// Generated by dts-bundle-generator v9.5.1
+
+declare function isCoreMessage(message: unknown): boolean;
+export declare function initializeAdUnit(partnerKey: string): Promise<void>;
+
+export {
+	isCoreMessage as isAdUnitMessage,
+};
+
+export {};