@weave-apps/sdk 0.9.0 → 0.11.0

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

@@ -0,0 +1,434 @@
+/**
+ * Weave Base App
+ *
+ * Base class for all Weave apps. Provides common functionality and lifecycle methods.
+ * Third-party developers should extend this class instead of HTMLElement directly.
+ *
+ * @example
+ * ```typescript
+ * // Define your settings and state types
+ * interface MyAppSettings {
+ *   apiKey: string;
+ *   endpoint: string;
+ * }
+ *
+ * interface MyAppState {
+ *   count: number;
+ *   isLoading: boolean;
+ *   data: any[];
+ * }
+ *
+ * class MyApp extends WeaveBaseApp<MyAppSettings, MyAppState> {
+ *   constructor() {
+ *     super({
+ *       id: 'my-app',
+ *       name: 'My App',
+ *       version: '1.0.0',
+ *       category: 'utility',
+ *       description: 'My custom app',
+ *       author: 'Your Name',
+ *       tags: ['custom'],
+ *       // Enable auto-persist to survive page reloads
+ *       persistState: true,
+ *     });
+ *
+ *     // Settings are now type-safe!
+ *     const apiKey = this.appSettings?.apiKey; // ✅ TypeScript knows this exists
+ *
+ *     // Initialize state with proper typing
+ *     this.state = {
+ *       count: 0,
+ *       isLoading: false,
+ *       data: []
+ *     };
+ *   }
+ *
+ *   render() {
+ *     return `<div>My App Content</div>`;
+ *   }
+ *
+ *   setupEventListeners() {
+ *     // setState is also type-safe and auto-persists if enabled
+ *     this.setState({ count: this.state.count + 1 }); // ✅ Type-safe
+ *   }
+ * }
+ *
+ * customElements.define('my-app', MyApp);
+ * ```
+ */
+/**
+ * Simple debounce utility
+ */
+function debounce(fn, delay) {
+    let timeoutId = null;
+    return (...args) => {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => {
+            fn(...args);
+            timeoutId = null;
+        }, delay);
+    };
+}
+/**
+ * Base class for Weave apps
+ * @template TSettings - Type for app settings, defaults to an empty object
+ * @template TState - Type for app state, defaults to an empty object
+ */
+export class WeaveBaseApp extends HTMLElement {
+    /**
+     * Creates a new Weave app
+     * @param appInfo - App metadata configuration
+     */
+    constructor(appInfo) {
+        super();
+        /** App-specific state (override in subclass) */
+        this.state = {};
+        /** Background API for state persistence */
+        this._backgroundAPI = null;
+        /** Cron API for scheduled tasks */
+        this._cronAPI = null;
+        /** App Instance API for cross-tab communication */
+        this._instancesAPI = null;
+        /** Debounced persist function */
+        this._debouncedPersist = null;
+        /** Flag to track if state has been restored */
+        this._stateRestored = false;
+        /** App UUID from registry */
+        this._appUuid = null;
+        /** User's company role (e.g., 'admin', 'member') */
+        this.companyRole = null;
+        /** Current user object */
+        this.currentUser = null;
+        /** Current company object */
+        this.currentCompany = null;
+        // Validate required fields
+        if (!appInfo.id || !appInfo.name || !appInfo.version) {
+            throw new Error('WeaveBaseApp: id, name, and version are required');
+        }
+        this.appInfo = appInfo;
+        // Create shadow DOM for style isolation and store reference
+        this._shadowRoot = this.attachShadow({ mode: 'open' });
+        // Read UUID and settings from global registry (set by BackgroundAppManager before element creation)
+        // This allows the constructor to access both UUID and settings immediately
+        const registry = window.__weaveAppRegistry;
+        const tagName = this.tagName.toLowerCase();
+        const registryData = registry?.[tagName];
+        // Set app settings if available in registry
+        if (registryData?.settings) {
+            this.appSettings = registryData.settings;
+        }
+        // Store app UUID for background API
+        this._appUuid = registryData?.uuid || null;
+        // Store user context for conditional rendering and personalization
+        this.currentUser = registryData?.currentUser || null;
+        this.currentCompany = registryData?.currentCompany || null;
+        this.companyRole = registryData?.companyRole || null;
+        // Set app UUID on the global API client so it's included in all requests
+        // This allows background services to make API calls without the app being open
+        if (window.weaveAPI) {
+            if (this._appUuid) {
+                // Create a new API client instance for THIS app
+                this.weaveAPI = new window.WeaveAPIClient();
+                this.weaveAPI.setAppId(this._appUuid);
+                // Create background API instance for state persistence
+                if (window.WeaveBackgroundAPI) {
+                    this._backgroundAPI = new window.WeaveBackgroundAPI(this._appUuid);
+                }
+                // Create cron API instance for scheduled tasks
+                if (window.WeaveCronAPI) {
+                    this._cronAPI = new window.WeaveCronAPI(this._appUuid);
+                    this._cronAPI.initialize();
+                }
+                // Create app instance API for cross-tab communication
+                if (window.WeaveAppInstanceAPI) {
+                    this._instancesAPI = new window.WeaveAppInstanceAPI(this._appUuid);
+                }
+                // Set up debounced persist if enabled
+                if (appInfo.persistState) {
+                    const delay = appInfo.persistDebounce ?? 100;
+                    this._debouncedPersist = debounce(() => {
+                        this._persistState();
+                    }, delay);
+                }
+            }
+            else {
+                console.warn('⚠️ App UUID not found in registry - API calls may fail. App:', appInfo.id);
+                // Fallback to global API client (will have wrong app ID, but better than nothing)
+                this.weaveAPI = window.weaveAPI;
+            }
+        }
+        else {
+            console.warn('⚠️ window.weaveAPI not available - API calls will fail. App:', appInfo.id);
+        }
+    }
+    /**
+     * Get the background API for state persistence and pending operations
+     * Use this for manual state management or multi-page flows
+     */
+    get background() {
+        return this._backgroundAPI;
+    }
+    /**
+     * Get the cron API for scheduled tasks
+     */
+    get cron() {
+        return this._cronAPI;
+    }
+    /**
+     * Get the app instance API for cross-tab communication
+     *
+     * Use this to:
+     * - Discover other instances of your app across browser tabs
+     * - Claim/release controller status (for automation coordination)
+     * - Send messages between instances
+     * - Listen for instance changes
+     *
+     * @example
+     * // Register this instance and check for others
+     * const instances = await this.instances.register();
+     * if (instances.length > 1) {
+     *   // Other instances exist
+     * }
+     *
+     * // Claim controller status
+     * const claimed = await this.instances.claimController();
+     *
+     * // Listen for messages from other instances
+     * this.instances.onMessage((msg) => {
+     *   if (msg.type === 'YIELD_CONTROL') {
+     *     // Another tab wants control
+     *   }
+     * });
+     */
+    get instances() {
+        return this._instancesAPI;
+    }
+    /**
+     * Register a cron job with a callback
+     *
+     * @param cronExpression - Standard cron expression (5 or 6 fields)
+     *   - 5 fields: minute hour dayOfMonth month dayOfWeek
+     *   - 6 fields: second minute hour dayOfMonth month dayOfWeek
+     * @param callback - Function to call when cron triggers
+     * @param jobName - Optional unique name for the job
+     * @returns Job ID if successful, null otherwise
+     *
+     * @example
+     * // Every second
+     * this.cronTab('* * * * * *', this.handleEverySecond);
+     *
+     * // Every minute
+     * this.cronTab('* * * * *', this.handleEveryMinute);
+     *
+     * // Every 5 seconds
+     * this.cronTab('0/5 * * * * *', this.handleEvery5Seconds);
+     *
+     * // Every hour at minute 0
+     * this.cronTab('0 * * * *', this.handleEveryHour);
+     */
+    async cronTab(cronExpression, callback, jobName) {
+        if (!this._cronAPI) {
+            console.error('Cron API not available - app UUID may be missing');
+            return null;
+        }
+        // Bind callback to this instance
+        const boundCallback = callback.bind(this);
+        return this._cronAPI.register(cronExpression, boundCallback, jobName);
+    }
+    /**
+     * Unregister a cron job by name
+     */
+    async cronUnregister(jobName) {
+        if (!this._cronAPI)
+            return false;
+        return this._cronAPI.unregister(jobName);
+    }
+    /**
+     * Unregister all cron jobs for this app
+     */
+    async cronUnregisterAll() {
+        if (!this._cronAPI)
+            return 0;
+        return this._cronAPI.unregisterAll();
+    }
+    /**
+     * Get shadow root (override native property)
+     */
+    get shadowRoot() {
+        return this._shadowRoot;
+    }
+    /**
+     * Render method - must be implemented by subclass
+     * Should return HTML string or directly manipulate shadowRoot
+     */
+    render() {
+        // Default implementation - subclasses should override
+    }
+    /**
+     * Setup event listeners - optional override in subclass
+     */
+    setupEventListeners() {
+        // Default implementation - subclasses can override
+    }
+    /**
+     * Initialize background service
+     * Called by BackgroundAppManager after instantiation
+     */
+    initializeBackgroundService() {
+        if (this.onBackgroundService) {
+            this.onBackgroundService();
+        }
+    }
+    /**
+     * Handle URL change
+     * Called by BackgroundAppManager when URL changes
+     */
+    handleUrlChange(url) {
+        if (this.onUrlChange) {
+            this.onUrlChange(url);
+        }
+    }
+    /**
+     * Handle server event
+     * Called by BackgroundAppManager when a WebSocket event is received for this app
+     */
+    handleServerEvent(event, data) {
+        if (this.onServerEvent) {
+            this.onServerEvent(event, data);
+        }
+    }
+    /**
+     * Lifecycle: Called when element is added to DOM
+     * This happens when user opens the app in the drawer
+     */
+    connectedCallback() {
+        // Render the app UI
+        this.render();
+        // Setup event listeners for UI
+        this.setupEventListeners();
+        // Notify Weave Platform that app UI is ready
+        this.dispatchEvent(new CustomEvent('weave-app-ready', {
+            detail: {
+                appInfo: this.appInfo,
+                timestamp: new Date().toISOString()
+            },
+            bubbles: true,
+            composed: true
+        }));
+    }
+    /**
+     * Lifecycle: Called when element is removed from DOM
+     */
+    disconnectedCallback() {
+        this.cleanup();
+    }
+    /**
+     * Cleanup method - optional override in subclass
+     * Called when app is disconnected from DOM
+     */
+    cleanup() {
+        // Default implementation - subclasses can override
+    }
+    /**
+     * Get app configuration (for Weave Platform)
+     */
+    getAppInfo() {
+        return this.appInfo;
+    }
+    /**
+     * Get current app state (for Weave Platform)
+     */
+    getAppState() {
+        return {
+            ...this.state,
+            lastUpdated: new Date().toISOString()
+        };
+    }
+    /**
+     * Set app configuration (for Weave Platform)
+     * Override this method to handle configuration updates
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    setAppConfig(_config) {
+        // Default implementation - subclasses can override
+    }
+    /**
+     * Helper: Update app state
+     * If persistState is enabled, state is automatically saved to background service
+     */
+    setState(updates) {
+        this.state = { ...this.state, ...updates };
+        // Auto-persist if enabled
+        if (this.appInfo.persistState && this._debouncedPersist) {
+            this._debouncedPersist();
+        }
+    }
+    /**
+     * Persist current state to background service
+     * Called automatically when persistState is enabled
+     */
+    async _persistState() {
+        if (!this._backgroundAPI)
+            return;
+        try {
+            await this._backgroundAPI.saveState(this.state);
+        }
+        catch (error) {
+            console.error('❌ Failed to persist state:', error);
+        }
+    }
+    /**
+     * Restore state from background service
+     * Called by BackgroundAppManager during initialization
+     */
+    async restoreState() {
+        if (!this._backgroundAPI || !this.appInfo.persistState) {
+            return false;
+        }
+        if (this._stateRestored) {
+            return true; // Already restored
+        }
+        try {
+            const savedState = await this._backgroundAPI.loadState();
+            if (savedState) {
+                this.state = { ...this.state, ...savedState };
+                this._stateRestored = true;
+                console.log('✅ State restored for app:', this.appInfo.id);
+                return true;
+            }
+        }
+        catch (error) {
+            console.error('❌ Failed to restore state:', error);
+        }
+        return false;
+    }
+    /**
+     * Helper: Render HTML into shadow root
+     */
+    renderHTML(html) {
+        if (this._shadowRoot) {
+            this._shadowRoot.innerHTML = html;
+        }
+        else {
+            console.error('❌ No shadow root available!');
+        }
+    }
+    /**
+     * Helper: Query element in shadow root
+     */
+    query(selector) {
+        return this._shadowRoot?.querySelector(selector) || null;
+    }
+    /**
+     * Helper: Query all elements in shadow root
+     */
+    queryAll(selector) {
+        return this._shadowRoot?.querySelectorAll(selector) || [];
+    }
+}
+// Export for global usage
+if (typeof window !== 'undefined') {
+    window.WeaveBaseApp = WeaveBaseApp;
+}

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

@@ -0,0 +1,68 @@
+/**
+ * WeaveCronAPI - Client API for apps to register cron jobs
+ *
+ * Apps can register callbacks to be executed on a schedule using standard cron syntax.
+ * The browser extension's background script acts as the master clock.
+ *
+ * Cron syntax (5 or 6 fields):
+ * - 5 fields: minute hour dayOfMonth month dayOfWeek
+ * - 6 fields: second minute hour dayOfMonth month dayOfWeek
+ *
+ * Special characters: asterisk (any), comma (list), dash (range), slash (step)
+ */
+interface CronJob {
+    id: string;
+    appId: string;
+    tabId: number;
+    cronExpression: string;
+    jobName: string;
+    createdAt: number;
+}
+type CronCallback = () => void | Promise<void>;
+export declare class WeaveCronAPI {
+    private appId;
+    private callbacks;
+    private jobIds;
+    private pendingRequests;
+    private messageListener;
+    private isInitialized;
+    constructor(appId: string);
+    /**
+     * Initialize the cron API (sets up message listener)
+     */
+    initialize(): void;
+    /**
+     * Cleanup - unregister all jobs and remove listener
+     */
+    destroy(): Promise<void>;
+    /**
+     * Register a cron job
+     * @param cronExpression - Cron expression (5 or 6 fields)
+     * @param callback - Function to call when cron triggers
+     * @param jobName - Optional unique name for the job (defaults to callback name or random)
+     * @returns Job ID if successful
+     */
+    register(cronExpression: string, callback: CronCallback, jobName?: string): Promise<string | null>;
+    /**
+     * Unregister a cron job by name
+     */
+    unregister(jobName: string): Promise<boolean>;
+    /**
+     * Unregister all cron jobs for this app
+     */
+    unregisterAll(): Promise<number>;
+    /**
+     * List all cron jobs for this app
+     */
+    list(): Promise<CronJob[]>;
+    /**
+     * Handle incoming messages
+     */
+    private handleMessage;
+    /**
+     * Send request to content script bridge
+     */
+    private sendRequest;
+}
+export default WeaveCronAPI;
+//# sourceMappingURL=WeaveCronAPI.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WeaveCronAPI.d.ts","sourceRoot":"","sources":["../../../src/WeaveCronAPI.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,UAAU,OAAO;IACf,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAcD,KAAK,YAAY,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/C,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,SAAS,CAAwC;IACzD,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,eAAe,CAA2F;IAClH,OAAO,CAAC,eAAe,CAAgD;IACvE,OAAO,CAAC,aAAa,CAAS;gBAElB,KAAK,EAAE,MAAM;IAIzB;;OAEG;IACH,UAAU,IAAI,IAAI;IAUlB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAe9B;;;;;;OAMG;IACG,QAAQ,CACZ,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,YAAY,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAwBzB;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBnD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IActC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAQhC;;OAEG;IACH,OAAO,CAAC,aAAa;IAmCrB;;OAEG;IACH,OAAO,CAAC,WAAW;CAqBpB;AAED,eAAe,YAAY,CAAC"}

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

@@ -0,0 +1,172 @@
+/**
+ * WeaveCronAPI - Client API for apps to register cron jobs
+ *
+ * Apps can register callbacks to be executed on a schedule using standard cron syntax.
+ * The browser extension's background script acts as the master clock.
+ *
+ * Cron syntax (5 or 6 fields):
+ * - 5 fields: minute hour dayOfMonth month dayOfWeek
+ * - 6 fields: second minute hour dayOfMonth month dayOfWeek
+ *
+ * Special characters: asterisk (any), comma (list), dash (range), slash (step)
+ */
+export class WeaveCronAPI {
+    constructor(appId) {
+        this.callbacks = new Map();
+        this.jobIds = new Map(); // jobName -> jobId
+        this.pendingRequests = new Map();
+        this.messageListener = null;
+        this.isInitialized = false;
+        this.appId = appId;
+    }
+    /**
+     * Initialize the cron API (sets up message listener)
+     */
+    initialize() {
+        if (this.isInitialized)
+            return;
+        this.messageListener = (event) => {
+            this.handleMessage(event);
+        };
+        window.addEventListener('message', this.messageListener);
+        this.isInitialized = true;
+    }
+    /**
+     * Cleanup - unregister all jobs and remove listener
+     */
+    async destroy() {
+        // Unregister all jobs for this app
+        await this.unregisterAll();
+        // Remove message listener
+        if (this.messageListener) {
+            window.removeEventListener('message', this.messageListener);
+            this.messageListener = null;
+        }
+        this.callbacks.clear();
+        this.jobIds.clear();
+        this.isInitialized = false;
+    }
+    /**
+     * Register a cron job
+     * @param cronExpression - Cron expression (5 or 6 fields)
+     * @param callback - Function to call when cron triggers
+     * @param jobName - Optional unique name for the job (defaults to callback name or random)
+     * @returns Job ID if successful
+     */
+    async register(cronExpression, callback, jobName) {
+        const name = jobName || callback.name || `job_${Date.now()}`;
+        // Store callback locally
+        this.callbacks.set(name, callback);
+        // Send registration request to background
+        const response = await this.sendRequest('CRON_REGISTER', {
+            appId: this.appId,
+            cronExpression,
+            jobName: name,
+        });
+        if (response.success && response.jobId) {
+            this.jobIds.set(name, response.jobId);
+            return response.jobId;
+        }
+        // Registration failed, remove callback
+        this.callbacks.delete(name);
+        console.error(`Failed to register cron job: ${response.error}`);
+        return null;
+    }
+    /**
+     * Unregister a cron job by name
+     */
+    async unregister(jobName) {
+        const jobId = this.jobIds.get(jobName);
+        if (!jobId) {
+            return false;
+        }
+        const response = await this.sendRequest('CRON_UNREGISTER', {
+            jobId,
+        });
+        if (response.success) {
+            this.callbacks.delete(jobName);
+            this.jobIds.delete(jobName);
+        }
+        return response.success;
+    }
+    /**
+     * Unregister all cron jobs for this app
+     */
+    async unregisterAll() {
+        const response = await this.sendRequest('CRON_UNREGISTER_APP', {
+            appId: this.appId,
+        });
+        if (response.success) {
+            this.callbacks.clear();
+            this.jobIds.clear();
+            return response.count;
+        }
+        return 0;
+    }
+    /**
+     * List all cron jobs for this app
+     */
+    async list() {
+        const response = await this.sendRequest('CRON_LIST', {
+            appId: this.appId,
+        });
+        return response.jobs || [];
+    }
+    /**
+     * Handle incoming messages
+     */
+    handleMessage(event) {
+        const { data } = event;
+        // Handle cron tick
+        if (data?.type === 'CRON_TICK') {
+            const { appId, jobName } = data.payload;
+            // Only handle ticks for this app
+            if (appId !== this.appId)
+                return;
+            const callback = this.callbacks.get(jobName);
+            if (callback) {
+                try {
+                    const result = callback();
+                    // Handle async callbacks
+                    if (result instanceof Promise) {
+                        result.catch(err => console.error(`Cron job ${jobName} error:`, err));
+                    }
+                }
+                catch (error) {
+                    console.error(`Cron job ${jobName} error:`, error);
+                }
+            }
+            return;
+        }
+        // Handle responses
+        if (data?.type?.endsWith('_RESPONSE') && data.requestId) {
+            const pending = this.pendingRequests.get(data.requestId);
+            if (pending) {
+                this.pendingRequests.delete(data.requestId);
+                pending.resolve(data.payload);
+            }
+        }
+    }
+    /**
+     * Send request to content script bridge
+     */
+    sendRequest(type, payload) {
+        return new Promise((resolve, reject) => {
+            const requestId = `cron_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+            this.pendingRequests.set(requestId, { resolve, reject });
+            // Timeout after 5 seconds
+            setTimeout(() => {
+                if (this.pendingRequests.has(requestId)) {
+                    this.pendingRequests.delete(requestId);
+                    reject(new Error('Cron request timeout'));
+                }
+            }, 5000);
+            window.parent.postMessage({
+                type,
+                requestId,
+                payload,
+            }, '*');
+        });
+    }
+}
+export default WeaveCronAPI;