@weave-apps/sdk 0.10.0 → 0.12.0

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

@@ -0,0 +1,361 @@
+/**
+ * Weave API Client
+ *
+ * Client-side API for iframe apps to interact with the Weave backend
+ * through a secure proxy in the sidebar.
+ *
+ * Apps can call AI services and manage their own app data.
+ */
+/**
+ * API operation types
+ */
+var APIOperation;
+(function (APIOperation) {
+    // AI Service
+    APIOperation["AI_CHAT"] = "AI_CHAT";
+    // Company Members Service
+    APIOperation["COMPANY_MEMBERS_GET"] = "COMPANY_MEMBERS_GET";
+    // App Data Service
+    APIOperation["APP_DATA_GET_ALL"] = "APP_DATA_GET_ALL";
+    APIOperation["APP_DATA_CREATE"] = "APP_DATA_CREATE";
+    APIOperation["APP_DATA_GET"] = "APP_DATA_GET";
+    APIOperation["APP_DATA_UPDATE"] = "APP_DATA_UPDATE";
+    APIOperation["APP_DATA_DELETE"] = "APP_DATA_DELETE";
+    // Forms Service
+    APIOperation["FORMS_GET_ALL"] = "FORMS_GET_ALL";
+    APIOperation["FORMS_GET"] = "FORMS_GET";
+    APIOperation["FORMS_GET_DATA"] = "FORMS_GET_DATA";
+    APIOperation["FORMS_SUBMIT_DATA"] = "FORMS_SUBMIT_DATA";
+})(APIOperation || (APIOperation = {}));
+/**
+ * Weave API Client
+ * Provides methods for iframe apps to interact with Weave backend
+ */
+export class WeaveAPIClient {
+    constructor() {
+        this.pendingRequests = new Map();
+        this.messageListener = null;
+        this.requestCounter = 0;
+        this.timeout = 180000; // 3 minute timeout for API calls (AI can take time on large forms)
+        this.appId = null; // App ID set by the app
+        // ============================================================================
+        // AI Service
+        // ============================================================================
+        /**
+         * Send a chat message to the AI service
+         *
+         * Note: App ID is automatically injected by the APIBridge.
+         * You only need to provide the prompt and optional context.
+         *
+         * @example
+         * ```javascript
+         * const response = await weaveAPI.ai.chat({
+         *   prompt: 'What is the capital of France?',
+         *   context: 'User is learning geography'
+         * });
+         * ```
+         */
+        this.ai = {
+            chat: async (request) => {
+                return this.sendRequest(APIOperation.AI_CHAT, request);
+            }
+        };
+        // =========================================================================
+        // App Data Service
+        // =========================================================================
+        /**
+         * App Data operations - CRUD for app-specific data storage
+         */
+        this.appData = {
+            /**
+             * Get all app data for the current company (paginated)
+             *
+             * Returns a paginated response with data and metadata.
+             * Default limit is 25 items. For apps with large datasets (500-5000+ rows),
+             * use pagination to avoid performance issues.
+             *
+             * @example
+             * ```javascript
+             * // Get first page (default: 25 items)
+             * const response = await weaveAPI.appData.getAll();
+             *
+             * // Access the array of items
+             * const items = response.data;
+             * items.forEach(item => {
+             * });
+             * ```
+             */
+            getAll: async () => {
+                return this.sendRequest(APIOperation.APP_DATA_GET_ALL, {});
+            },
+            /**
+             * Create new app data
+             *
+             * Note: App ID is automatically injected by the APIBridge.
+             *
+             * @example
+             * ```javascript
+             * const newData = await weaveAPI.appData.create({
+             *   dataKey: 'user-preferences',
+             *   data: { theme: 'dark', language: 'en' }
+             * });
+             * ```
+             */
+            create: async (request) => {
+                return this.sendRequest(APIOperation.APP_DATA_CREATE, request);
+            },
+            /**
+             * Get specific app data by ID
+             *
+             * @example
+             * ```javascript
+             * const data = await weaveAPI.appData.get('data-id-123');
+             * ```
+             */
+            get: async (appDataId) => {
+                return this.sendRequest(APIOperation.APP_DATA_GET, { appDataId });
+            },
+            /**
+             * Update existing app data
+             *
+             * @example
+             * ```javascript
+             * const updated = await weaveAPI.appData.update('data-id-123', {
+             *   data: { theme: 'light' }
+             * });
+             * ```
+             */
+            update: async (appDataId, request) => {
+                return this.sendRequest(APIOperation.APP_DATA_UPDATE, {
+                    appDataId,
+                    ...request
+                });
+            },
+            /**
+             * Delete app data
+             *
+             * @example
+             * ```javascript
+             * await weaveAPI.appData.delete('data-id-123');
+             * ```
+             */
+            delete: async (appDataId) => {
+                return this.sendRequest(APIOperation.APP_DATA_DELETE, { appDataId });
+            }
+        };
+        // =========================================================================
+        // Company Members Service
+        // =========================================================================
+        /**
+         * Company member operations for app/user discovery scenarios.
+         */
+        this.companyMembers = {
+            /**
+             * Get company members scoped by current user's location (supports ancestor traversal).
+             *
+             * Defaults to current app context (`targetType: 'app'`, `targetId` from app ID).
+             */
+            getAll: async (options = {}) => {
+                return this.sendRequest(APIOperation.COMPANY_MEMBERS_GET, options);
+            },
+        };
+        /**
+         * Forms API
+         *
+         * Methods for fetching company forms and submitting form data.
+         */
+        this.forms = {
+            /**
+             * Get all forms for the company
+             *
+             * @example
+             * ```javascript
+             * const response = await weaveAPI.forms.getAll();
+             * console.log(response.data); // Array of forms
+             * ```
+             */
+            getAll: async () => {
+                return this.sendRequest(APIOperation.FORMS_GET_ALL, {});
+            },
+            /**
+             * Get a specific form by ID
+             *
+             * @example
+             * ```javascript
+             * const form = await weaveAPI.forms.get('form-id-123');
+             * console.log(form.name, form.fields);
+             * ```
+             */
+            get: async (formId) => {
+                return this.sendRequest(APIOperation.FORMS_GET, { formId });
+            },
+            /**
+             * Get all submissions (app data) for a specific form
+             *
+             * @example
+             * ```javascript
+             * const response = await weaveAPI.forms.getFormData('form-id-123');
+             * console.log(response.data); // Array of form submissions
+             * ```
+             */
+            getFormData: async (formId, scopeOptions = {}) => {
+                return this.sendRequest(APIOperation.FORMS_GET_DATA, {
+                    formId,
+                    ...scopeOptions,
+                });
+            },
+            /**
+             * Submit form data
+             * Creates app data with targetType: 'form' and targetId: formId
+             *
+             * @example
+             * ```javascript
+             * await weaveAPI.forms.submitFormData('form-id-123', {
+             *   dataKey: 'form_submission',
+             *   data: {
+             *     formName: 'User Signup',
+             *     responses: { field1: 'value1', field2: 'value2' }
+             *   }
+             * });
+             * ```
+             */
+            submitFormData: async (formId, payload) => {
+                return this.sendRequest(APIOperation.FORMS_SUBMIT_DATA, { formId, ...payload });
+            }
+        };
+        /**
+         * Utility functions for common operations
+         *
+         * Note: These utilities are loaded from the sidebar-loader at runtime.
+         * They are available through the window object and don't need to be bundled with apps.
+         */
+        this.utils = {
+            /**
+             * Convert HTML to Markdown
+             *
+             * @example
+             * ```javascript
+             * const markdown = weaveAPI.utils.htmlToMarkdown('<h1>Hello</h1>');
+             * console.log(markdown); // # Hello
+             * ```
+             */
+            htmlToMarkdown: (html) => {
+                // Access the utility from window object (loaded by sidebar-loader)
+                if (typeof window !== 'undefined' && window.__weaveUtils?.htmlToMarkdown) {
+                    return window.__weaveUtils.htmlToMarkdown(html);
+                }
+                throw new Error('htmlToMarkdown utility not available. Ensure sidebar-loader is loaded.');
+            },
+            /**
+             * Convert Markdown to HTML (sanitized)
+             *
+             * @example
+             * ```javascript
+             * const html = weaveAPI.utils.markdownToHtml('# Hello');
+             * console.log(html); // <h1>Hello</h1>
+             * ```
+             */
+            markdownToHtml: (markdown) => {
+                // Access the utility from window object (loaded by sidebar-loader)
+                if (typeof window !== 'undefined' && window.__weaveUtils?.markdownToHtml) {
+                    return window.__weaveUtils.markdownToHtml(markdown);
+                }
+                throw new Error('markdownToHtml utility not available. Ensure sidebar-loader is loaded.');
+            }
+        };
+        this.initialize();
+    }
+    /**
+     * Set the app ID for this client
+     * Called automatically by WeaveBaseApp
+     */
+    setAppId(appId) {
+        this.appId = appId;
+    }
+    /**
+     * Initialize the API client and start listening for responses
+     */
+    initialize() {
+        this.messageListener = (event) => {
+            this.handleResponse(event);
+        };
+        window.addEventListener('message', this.messageListener);
+    }
+    /**
+     * Cleanup
+     */
+    destroy() {
+        if (this.messageListener) {
+            window.removeEventListener('message', this.messageListener);
+            this.messageListener = null;
+        }
+        this.pendingRequests.clear();
+    }
+    /**
+     * Handle response from sidebar
+     */
+    handleResponse(event) {
+        const data = event.data;
+        if (data?.type !== 'WEAVE_API_RESPONSE') {
+            return;
+        }
+        const response = data;
+        const pending = this.pendingRequests.get(response.id);
+        if (!pending) {
+            return;
+        }
+        this.pendingRequests.delete(response.id);
+        if (response.success) {
+            pending.resolve(response.data);
+        }
+        else {
+            pending.reject(new Error(response.error || 'Unknown error'));
+        }
+    }
+    /**
+     * Send request to sidebar
+     */
+    sendRequest(operation, payload) {
+        return new Promise((resolve, reject) => {
+            const id = `api-request-${++this.requestCounter}`;
+            const request = {
+                type: 'WEAVE_API_REQUEST',
+                id,
+                operation,
+                payload,
+                appId: this.appId || undefined, // Include app ID if set
+            };
+            // Store pending request
+            this.pendingRequests.set(id, { resolve, reject });
+            // Set timeout
+            const timeoutId = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`Request timeout: ${operation}`));
+            }, this.timeout);
+            // Clear timeout on resolve/reject
+            const originalResolve = resolve;
+            const originalReject = reject;
+            this.pendingRequests.set(id, {
+                resolve: (value) => {
+                    clearTimeout(timeoutId);
+                    originalResolve(value);
+                },
+                reject: (error) => {
+                    clearTimeout(timeoutId);
+                    originalReject(error);
+                },
+            });
+            // Send to current window (sidebar APIBridge will intercept)
+            // Apps run in the sidebar's window, not in a separate iframe
+            window.postMessage(request, '*');
+            APIOperation;
+        });
+    }
+}
+// Create singleton instance
+const weaveAPI = new WeaveAPIClient();
+// Export for global usage
+if (typeof window !== 'undefined') {
+    window.weaveAPI = weaveAPI;
+}
+export default weaveAPI;

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

@@ -0,0 +1,237 @@
+/**
+ * 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' });
+ * ```
+ */
+/**
+ * Represents a single app instance in a tab
+ */
+export interface AppInstance {
+    appId: string;
+    tabId: number;
+    url: string;
+    isController: boolean;
+    registeredAt: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Message sent between app instances
+ */
+export interface InstanceMessage {
+    type: string;
+    data?: any;
+    senderId: number;
+    timestamp: number;
+}
+/**
+ * Callback for instance messages
+ */
+export type InstanceMessageCallback = (message: InstanceMessage) => void;
+/**
+ * Callback for instance changes
+ */
+export type InstanceChangeCallback = (instances: AppInstance[]) => void;
+/**
+ * WeaveAppInstanceAPI class
+ *
+ * Provides methods for apps to discover and communicate with
+ * other instances of themselves across browser tabs.
+ */
+export declare class WeaveAppInstanceAPI {
+    private appId;
+    private _tabId;
+    constructor(appId: string);
+    /**
+     * Get this instance's tab ID (available after register)
+     */
+    get tabId(): number | null;
+    /**
+     * 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`);
+     */
+    register(metadata?: Record<string, any>): Promise<AppInstance[]>;
+    /**
+     * Unregister this app instance
+     * Call this when your app is being destroyed.
+     *
+     * @example
+     * await this.instances.unregister();
+     */
+    unregister(): Promise<void>;
+    /**
+     * 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);
+     */
+    getInstances(): Promise<AppInstance[]>;
+    /**
+     * 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();
+     * }
+     */
+    claimController(force?: boolean): Promise<boolean>;
+    /**
+     * Release controller status
+     * Call this when you want to give up control.
+     *
+     * @example
+     * await this.instances.releaseController();
+     */
+    releaseController(): Promise<void>;
+    /**
+     * 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
+     * }
+     */
+    isController(): Promise<boolean>;
+    /**
+     * 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}`);
+     * }
+     */
+    getController(): Promise<AppInstance | 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' }
+     * });
+     */
+    broadcast(message: {
+        type: string;
+        data?: any;
+    }): Promise<number[]>;
+    /**
+     * 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',
+     * });
+     */
+    sendToController(message: {
+        type: string;
+        data?: any;
+    }): Promise<number | 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',
+     * });
+     */
+    sendToTab(targetTabId: number, message: {
+        type: string;
+        data?: any;
+    }): Promise<boolean>;
+    /**
+     * 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: InstanceMessageCallback): () => void;
+    /**
+     * 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: InstanceChangeCallback): () => void;
+}
+//# sourceMappingURL=WeaveAppInstanceAPI.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WeaveAppInstanceAPI.d.ts","sourceRoot":"","sources":["../../../src/WeaveAppInstanceAPI.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAeH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAoBD;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE,KAAK,IAAI,CAAC;AAqHxE;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAuB;gBAEzB,KAAK,EAAE,MAAM;IAIzB;;OAEG;IACH,IAAI,KAAK,IAAI,MAAM,GAAG,IAAI,CAEzB;IAED;;;;;;;;;;;;;OAaG;IACG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAetE;;;;;;OAMG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOjC;;;;;;;;OAQG;IACG,YAAY,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAO5C;;;;;;;;;;;;;;;;OAgBG;IACG,eAAe,CAAC,KAAK,GAAE,OAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ/D;;;;;;OAMG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAMxC;;;;;;;;;OASG;IACG,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC;IAOtC;;;;;;;;;;OAUG;IACG,aAAa,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAOlD;;;;;;;;;;;OAWG;IACG,SAAS,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQzE;;;;;;;;;;OAUG;IACG,gBAAgB,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAQrF;;;;;;;;;;;OAWG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAS7F;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,QAAQ,EAAE,uBAAuB,GAAG,MAAM,IAAI;IAsBxD;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,IAAI;CAqB/D"}