@weave-apps/sdk 0.10.0 → 0.12.0

package/dist/app-sdk/src/WeaveAppInstanceAPI.js

@@ -0,0 +1,395 @@
+/**
+ * WeaveAppInstanceAPI
+ *
+ * Client-side API for Weave apps to discover and communicate with
+ * other instances of themselves across browser tabs.
+ *
+ * Use cases:
+ * - Prevent duplicate automation runs across tabs
+ * - Coordinate which tab is "controlling" vs "observing"
+ * - Send messages between app instances
+ *
+ * Usage:
+ * ```typescript
+ * // Register this instance
+ * const instances = await this.instances.register({ url: window.location.href });
+ *
+ * // Claim controller status (for automation)
+ * const claimed = await this.instances.claimController();
+ *
+ * // Listen for messages from other instances
+ * this.instances.onMessage((msg, sender) => {
+ *   if (msg.type === 'YIELD_CONTROL') {
+ *     // Another tab wants control
+ *   }
+ * });
+ *
+ * // Broadcast to all other instances
+ * await this.instances.broadcast({ type: 'YIELD_CONTROL' });
+ * ```
+ */
+// Request timeout in ms
+const REQUEST_TIMEOUT = 5000;
+// Counter for unique request IDs
+let requestIdCounter = 0;
+// Pending requests waiting for response
+const pendingRequests = new Map();
+// Flag to track if listener is set up
+let listenerInitialized = false;
+// Global callbacks for instance messages (keyed by appId)
+const messageCallbacks = new Map();
+// Global callbacks for instance changes (keyed by appId)
+const changeCallbacks = new Map();
+/**
+ * Initialize the response listener (called once)
+ */
+function initializeListener() {
+    if (listenerInitialized)
+        return;
+    listenerInitialized = true;
+    window.addEventListener('message', (event) => {
+        const message = event.data;
+        // Handle app instance responses
+        if (message?.type === 'APP_INSTANCE_RESPONSE') {
+            const response = message;
+            const pending = pendingRequests.get(response.requestId);
+            if (!pending)
+                return;
+            // Clear timeout and remove from pending
+            clearTimeout(pending.timeout);
+            pendingRequests.delete(response.requestId);
+            if (response.success) {
+                pending.resolve(response);
+            }
+            else {
+                pending.reject(new Error(response.error || 'Unknown error'));
+            }
+            return;
+        }
+        // Handle incoming instance messages from other tabs
+        if (message?.type === 'APP_INSTANCE_MESSAGE') {
+            const { appId, message: instanceMessage } = message.payload;
+            const callbacks = messageCallbacks.get(appId);
+            if (callbacks) {
+                for (const callback of callbacks) {
+                    try {
+                        callback(instanceMessage);
+                    }
+                    catch (error) {
+                        console.error('[WeaveAppInstanceAPI] Error in message callback:', error);
+                    }
+                }
+            }
+            return;
+        }
+        // Handle instance change notifications
+        if (message?.type === 'APP_INSTANCE_CHANGE') {
+            const { appId, instances } = message.payload;
+            const callbacks = changeCallbacks.get(appId);
+            if (callbacks) {
+                for (const callback of callbacks) {
+                    try {
+                        callback(instances);
+                    }
+                    catch (error) {
+                        console.error('[WeaveAppInstanceAPI] Error in change callback:', error);
+                    }
+                }
+            }
+            return;
+        }
+    });
+}
+/**
+ * Send a message to the background service via content script
+ */
+async function sendMessage(type, payload) {
+    // Initialize listener on first use
+    initializeListener();
+    const requestId = `app-${++requestIdCounter}-${Date.now()}`;
+    return new Promise((resolve, reject) => {
+        // Set up timeout
+        const timeout = setTimeout(() => {
+            pendingRequests.delete(requestId);
+            reject(new Error(`App instance request timed out: ${type}`));
+        }, REQUEST_TIMEOUT);
+        // Store pending request
+        pendingRequests.set(requestId, { resolve, reject, timeout });
+        // Send message to content script (which forwards to background)
+        window.parent.postMessage({
+            type,
+            requestId,
+            payload,
+        }, '*');
+    });
+}
+/**
+ * WeaveAppInstanceAPI class
+ *
+ * Provides methods for apps to discover and communicate with
+ * other instances of themselves across browser tabs.
+ */
+export class WeaveAppInstanceAPI {
+    constructor(appId) {
+        this._tabId = null;
+        this.appId = appId;
+    }
+    /**
+     * Get this instance's tab ID (available after register)
+     */
+    get tabId() {
+        return this._tabId;
+    }
+    /**
+     * Register this app instance
+     * Call this when your app starts to make it discoverable by other instances.
+     *
+     * @param metadata - Optional metadata to associate with this instance
+     * @returns All current instances of this app (including this one)
+     *
+     * @example
+     * const instances = await this.instances.register({
+     *   url: window.location.href,
+     *   startedAt: Date.now()
+     * });
+     * console.log(`There are ${instances.length} instances of this app`);
+     */
+    async register(metadata) {
+        const response = await sendMessage('APP_REGISTER_INSTANCE', {
+            appId: this.appId,
+            url: window.location.href,
+            metadata,
+        });
+        // Store our tab ID
+        if (response.tabId) {
+            this._tabId = response.tabId;
+        }
+        return response.instances || [];
+    }
+    /**
+     * Unregister this app instance
+     * Call this when your app is being destroyed.
+     *
+     * @example
+     * await this.instances.unregister();
+     */
+    async unregister() {
+        await sendMessage('APP_UNREGISTER_INSTANCE', {
+            appId: this.appId,
+        });
+        this._tabId = null;
+    }
+    /**
+     * Get all instances of this app
+     *
+     * @returns All current instances
+     *
+     * @example
+     * const instances = await this.instances.getInstances();
+     * const otherInstances = instances.filter(i => i.tabId !== this.instances.tabId);
+     */
+    async getInstances() {
+        const response = await sendMessage('APP_GET_INSTANCES', {
+            appId: this.appId,
+        });
+        return response.instances || [];
+    }
+    /**
+     * Claim controller status for this instance
+     * Only one instance can be controller at a time.
+     *
+     * @param force - If true, forcibly take control from current controller
+     * @returns true if successfully claimed, false if another instance is controller
+     *
+     * @example
+     * const claimed = await this.instances.claimController();
+     * if (claimed) {
+     *   // This instance is now the controller
+     *   this.startAutomation();
+     * } else {
+     *   // Another instance is already controlling
+     *   this.showObserverUI();
+     * }
+     */
+    async claimController(force = false) {
+        const response = await sendMessage('APP_CLAIM_CONTROLLER', {
+            appId: this.appId,
+            force,
+        });
+        return response.claimed ?? false;
+    }
+    /**
+     * Release controller status
+     * Call this when you want to give up control.
+     *
+     * @example
+     * await this.instances.releaseController();
+     */
+    async releaseController() {
+        await sendMessage('APP_RELEASE_CONTROLLER', {
+            appId: this.appId,
+        });
+    }
+    /**
+     * Check if this instance is the controller
+     *
+     * @returns true if this instance is the controller
+     *
+     * @example
+     * if (await this.instances.isController()) {
+     *   // We're in control
+     * }
+     */
+    async isController() {
+        const response = await sendMessage('APP_IS_CONTROLLER', {
+            appId: this.appId,
+        });
+        return response.isController ?? false;
+    }
+    /**
+     * Get the current controller instance
+     *
+     * @returns The controller instance, or null if none
+     *
+     * @example
+     * const controller = await this.instances.getController();
+     * if (controller) {
+     *   console.log(`Controller is in tab ${controller.tabId}`);
+     * }
+     */
+    async getController() {
+        const response = await sendMessage('APP_GET_CONTROLLER', {
+            appId: this.appId,
+        });
+        return response.controller ?? null;
+    }
+    /**
+     * Broadcast a message to all other instances
+     *
+     * @param message - Message to send (type and optional data)
+     * @returns Array of tab IDs that received the message
+     *
+     * @example
+     * await this.instances.broadcast({
+     *   type: 'YIELD_CONTROL',
+     *   data: { reason: 'User requested control' }
+     * });
+     */
+    async broadcast(message) {
+        const response = await sendMessage('APP_BROADCAST', {
+            appId: this.appId,
+            instanceMessage: message,
+        });
+        return response.recipientTabIds || [];
+    }
+    /**
+     * Send a message to the controller instance
+     *
+     * @param message - Message to send
+     * @returns Tab ID of the controller, or null if no controller
+     *
+     * @example
+     * await this.instances.sendToController({
+     *   type: 'REQUEST_STATUS',
+     * });
+     */
+    async sendToController(message) {
+        const response = await sendMessage('APP_SEND_TO_CONTROLLER', {
+            appId: this.appId,
+            instanceMessage: message,
+        });
+        return response.controllerTabId ?? null;
+    }
+    /**
+     * Send a message to a specific tab
+     *
+     * @param targetTabId - Tab ID to send to
+     * @param message - Message to send
+     * @returns true if sent successfully
+     *
+     * @example
+     * await this.instances.sendToTab(123, {
+     *   type: 'PING',
+     * });
+     */
+    async sendToTab(targetTabId, message) {
+        const response = await sendMessage('APP_SEND_TO_TAB', {
+            appId: this.appId,
+            targetTabId,
+            instanceMessage: message,
+        });
+        return response.sent ?? false;
+    }
+    /**
+     * Listen for messages from other instances
+     *
+     * @param callback - Function to call when a message is received
+     * @returns Unsubscribe function
+     *
+     * @example
+     * const unsubscribe = this.instances.onMessage((msg) => {
+     *   if (msg.type === 'YIELD_CONTROL') {
+     *     this.releaseController();
+     *     this.showObserverUI();
+     *   }
+     * });
+     *
+     * // Later, to stop listening:
+     * unsubscribe();
+     */
+    onMessage(callback) {
+        // Initialize listener
+        initializeListener();
+        // Get or create callback set for this app
+        let callbacks = messageCallbacks.get(this.appId);
+        if (!callbacks) {
+            callbacks = new Set();
+            messageCallbacks.set(this.appId, callbacks);
+        }
+        callbacks.add(callback);
+        // Return unsubscribe function
+        return () => {
+            callbacks?.delete(callback);
+            if (callbacks?.size === 0) {
+                messageCallbacks.delete(this.appId);
+            }
+        };
+    }
+    /**
+     * Listen for instance changes (new instances, removed instances)
+     *
+     * @param callback - Function to call when instances change
+     * @returns Unsubscribe function
+     *
+     * @example
+     * const unsubscribe = this.instances.onInstanceChange((instances) => {
+     *   console.log(`Now ${instances.length} instances`);
+     *   const controller = instances.find(i => i.isController);
+     *   if (controller) {
+     *     console.log(`Controller is tab ${controller.tabId}`);
+     *   }
+     * });
+     */
+    onInstanceChange(callback) {
+        // Initialize listener
+        initializeListener();
+        // Get or create callback set for this app
+        let callbacks = changeCallbacks.get(this.appId);
+        if (!callbacks) {
+            callbacks = new Set();
+            changeCallbacks.set(this.appId, callbacks);
+        }
+        callbacks.add(callback);
+        // Return unsubscribe function
+        return () => {
+            callbacks?.delete(callback);
+            if (callbacks?.size === 0) {
+                changeCallbacks.delete(this.appId);
+            }
+        };
+    }
+}
+// Export for global usage
+if (typeof window !== 'undefined') {
+    window.WeaveAppInstanceAPI = WeaveAppInstanceAPI;
+}

package/dist/app-sdk/src/WeaveBackgroundAPI.d.ts

@@ -0,0 +1,81 @@
+/**
+ * WeaveBackgroundAPI
+ *
+ * Client-side API for Weave apps to interact with the background state service.
+ * Allows apps to persist state across page reloads and manage multi-page operations.
+ *
+ * Usage:
+ * ```typescript
+ * // Save state (survives page reload)
+ * await weaveAPI.background.saveState({ count: 5, items: [...] });
+ *
+ * // Load state after page reload
+ * const state = await weaveAPI.background.loadState();
+ *
+ * // Set pending operation before navigation
+ * await weaveAPI.background.setPendingOperation({
+ *   type: 'fill-form',
+ *   data: { content: '...' },
+ *   targetUrl: 'https://example.com/form'
+ * });
+ *
+ * // Check for pending operation after navigation
+ * const pending = await weaveAPI.background.getPendingOperation();
+ * ```
+ */
+/**
+ * Pending operation for multi-page flows
+ */
+export interface PendingOperation {
+    type: string;
+    data: any;
+    targetUrl?: string;
+}
+/**
+ * WeaveBackgroundAPI class
+ *
+ * Provides methods for apps to interact with background state service.
+ * Each app instance gets its own API instance with its appId.
+ */
+export declare class WeaveBackgroundAPI {
+    private appId;
+    constructor(appId: string);
+    /**
+     * Save app state to background service
+     * State survives page reloads within the browser session
+     *
+     * @param state - The state object to save
+     */
+    saveState(state: any): Promise<void>;
+    /**
+     * Load app state from background service
+     * Returns null if no state exists or if it has expired
+     *
+     * @returns The saved state or null
+     */
+    loadState<T = any>(): Promise<T | null>;
+    /**
+     * Clear app state from background service
+     */
+    clearState(): Promise<void>;
+    /**
+     * Set a pending operation for multi-page flows
+     * Use this before triggering navigation to save context
+     *
+     * @param operation - The operation to save
+     */
+    setPendingOperation(operation: PendingOperation): Promise<void>;
+    /**
+     * Get pending operation after navigation
+     * Returns null if no pending operation exists
+     *
+     * @returns The pending operation or null
+     */
+    getPendingOperation(): Promise<PendingOperation | null>;
+    /**
+     * Clear pending operation
+     * Call this after successfully handling the pending operation
+     */
+    clearPendingOperation(): Promise<void>;
+}
+//# sourceMappingURL=WeaveBackgroundAPI.d.ts.map

package/dist/app-sdk/src/WeaveBackgroundAPI.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WeaveBackgroundAPI.d.ts","sourceRoot":"","sources":["../../../src/WeaveBackgroundAPI.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAWH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,GAAG,CAAC;IACV,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA4FD;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,KAAK,CAAS;gBAEV,KAAK,EAAE,MAAM;IAIzB;;;;;OAKG;IACG,SAAS,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1C;;;;;OAKG;IACG,SAAS,CAAC,CAAC,GAAG,GAAG,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAO7C;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC;;;;;OAKG;IACG,mBAAmB,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrE;;;;;OAKG;IACG,mBAAmB,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAO7D;;;OAGG;IACG,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7C"}

package/dist/app-sdk/src/WeaveBackgroundAPI.js

@@ -0,0 +1,165 @@
+/**
+ * WeaveBackgroundAPI
+ *
+ * Client-side API for Weave apps to interact with the background state service.
+ * Allows apps to persist state across page reloads and manage multi-page operations.
+ *
+ * Usage:
+ * ```typescript
+ * // Save state (survives page reload)
+ * await weaveAPI.background.saveState({ count: 5, items: [...] });
+ *
+ * // Load state after page reload
+ * const state = await weaveAPI.background.loadState();
+ *
+ * // Set pending operation before navigation
+ * await weaveAPI.background.setPendingOperation({
+ *   type: 'fill-form',
+ *   data: { content: '...' },
+ *   targetUrl: 'https://example.com/form'
+ * });
+ *
+ * // Check for pending operation after navigation
+ * const pending = await weaveAPI.background.getPendingOperation();
+ * ```
+ */
+// Request timeout in ms
+const REQUEST_TIMEOUT = 5000;
+// Counter for unique request IDs
+let requestIdCounter = 0;
+// Pending requests waiting for response
+const pendingRequests = new Map();
+// Flag to track if listener is set up
+let listenerInitialized = false;
+/**
+ * Initialize the response listener (called once)
+ */
+function initializeListener() {
+    if (listenerInitialized)
+        return;
+    listenerInitialized = true;
+    window.addEventListener('message', (event) => {
+        const message = event.data;
+        // Only handle background state responses
+        if (message?.type !== 'BG_STATE_RESPONSE')
+            return;
+        const pending = pendingRequests.get(message.requestId);
+        if (!pending)
+            return;
+        // Clear timeout and remove from pending
+        clearTimeout(pending.timeout);
+        pendingRequests.delete(message.requestId);
+        if (message.success) {
+            pending.resolve({
+                state: message.state,
+                operation: message.operation,
+            });
+        }
+        else {
+            pending.reject(new Error(message.error || 'Unknown error'));
+        }
+    });
+}
+/**
+ * Send a message to the background state service via content script
+ */
+async function sendMessage(type, payload) {
+    // Initialize listener on first use
+    initializeListener();
+    const requestId = `bg-${++requestIdCounter}-${Date.now()}`;
+    return new Promise((resolve, reject) => {
+        // Set up timeout
+        const timeout = setTimeout(() => {
+            pendingRequests.delete(requestId);
+            reject(new Error(`Background state request timed out: ${type}`));
+        }, REQUEST_TIMEOUT);
+        // Store pending request
+        pendingRequests.set(requestId, { resolve, reject, timeout });
+        // Send message to content script (which forwards to background)
+        window.parent.postMessage({
+            type,
+            requestId,
+            payload,
+        }, '*');
+    });
+}
+/**
+ * WeaveBackgroundAPI class
+ *
+ * Provides methods for apps to interact with background state service.
+ * Each app instance gets its own API instance with its appId.
+ */
+export class WeaveBackgroundAPI {
+    constructor(appId) {
+        this.appId = appId;
+    }
+    /**
+     * Save app state to background service
+     * State survives page reloads within the browser session
+     *
+     * @param state - The state object to save
+     */
+    async saveState(state) {
+        await sendMessage('BG_SAVE_STATE', {
+            appId: this.appId,
+            state,
+        });
+    }
+    /**
+     * Load app state from background service
+     * Returns null if no state exists or if it has expired
+     *
+     * @returns The saved state or null
+     */
+    async loadState() {
+        const response = await sendMessage('BG_LOAD_STATE', {
+            appId: this.appId,
+        });
+        return response.state;
+    }
+    /**
+     * Clear app state from background service
+     */
+    async clearState() {
+        await sendMessage('BG_CLEAR_STATE', {
+            appId: this.appId,
+        });
+    }
+    /**
+     * Set a pending operation for multi-page flows
+     * Use this before triggering navigation to save context
+     *
+     * @param operation - The operation to save
+     */
+    async setPendingOperation(operation) {
+        await sendMessage('BG_SET_PENDING_OP', {
+            appId: this.appId,
+            operation,
+        });
+    }
+    /**
+     * Get pending operation after navigation
+     * Returns null if no pending operation exists
+     *
+     * @returns The pending operation or null
+     */
+    async getPendingOperation() {
+        const response = await sendMessage('BG_GET_PENDING_OP', {
+            appId: this.appId,
+        });
+        return response.operation;
+    }
+    /**
+     * Clear pending operation
+     * Call this after successfully handling the pending operation
+     */
+    async clearPendingOperation() {
+        await sendMessage('BG_CLEAR_PENDING_OP', {
+            appId: this.appId,
+        });
+    }
+}
+// Export for global usage
+if (typeof window !== 'undefined') {
+    window.WeaveBackgroundAPI = WeaveBackgroundAPI;
+}