@weave-apps/sdk 0.9.0 → 0.11.0

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

@@ -0,0 +1,318 @@
+/**
+ * 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);
+ * ```
+ */
+/**
+ * Pending operation for multi-page flows
+ */
+export interface PendingOperation {
+    type: string;
+    data: any;
+    targetUrl?: string;
+}
+/**
+ * App metadata configuration
+ */
+export interface WeaveAppInfo {
+    /** Unique identifier for the app (kebab-case recommended) */
+    id: string;
+    /** Display name of the app */
+    name: string;
+    /** Semantic version (x.y.z) */
+    version: string;
+    /** Primary category for the app */
+    category: string;
+    /** Detailed description of the app */
+    description: string;
+    /** Author or organization name */
+    author: string;
+    /** Additional tags for search and categorization */
+    tags?: string[];
+    /**
+     * Enable automatic state persistence across page reloads.
+     * When true, state is automatically saved to background service on each setState() call.
+     * State is restored when the app initializes after a page reload.
+     * @default false
+     */
+    persistState?: boolean;
+    /**
+     * Debounce delay for state persistence in milliseconds.
+     * Prevents excessive saves when state changes rapidly.
+     * @default 100
+     */
+    persistDebounce?: number;
+}
+/**
+ * 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 declare abstract class WeaveBaseApp<TSettings = Record<string, any>, TState = Record<string, any>> extends HTMLElement {
+    /** App metadata */
+    protected appInfo: WeaveAppInfo;
+    /** App settings (override in subclass) **/
+    protected appSettings?: TSettings;
+    /** App-specific state (override in subclass) */
+    protected state: TState;
+    /** Shadow root for style isolation */
+    private _shadowRoot;
+    /** App-specific API client instance (prevents app ID conflicts) */
+    protected weaveAPI: any;
+    /** Background API for state persistence */
+    private _backgroundAPI;
+    /** Cron API for scheduled tasks */
+    private _cronAPI;
+    /** App Instance API for cross-tab communication */
+    private _instancesAPI;
+    /** Debounced persist function */
+    private _debouncedPersist;
+    /** Flag to track if state has been restored */
+    private _stateRestored;
+    /** App UUID from registry */
+    private _appUuid;
+    /** User's company role (e.g., 'admin', 'member') */
+    protected companyRole: string | null;
+    /** Current user object */
+    protected currentUser: any;
+    /** Current company object */
+    protected currentCompany: any;
+    /**
+     * Creates a new Weave app
+     * @param appInfo - App metadata configuration
+     */
+    constructor(appInfo: WeaveAppInfo);
+    /**
+     * Get the background API for state persistence and pending operations
+     * Use this for manual state management or multi-page flows
+     */
+    protected get background(): any;
+    /**
+     * Get the cron API for scheduled tasks
+     */
+    protected get cron(): any;
+    /**
+     * 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
+     *   }
+     * });
+     */
+    protected get instances(): any;
+    /**
+     * 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);
+     */
+    protected cronTab(cronExpression: string, callback: () => void | Promise<void>, jobName?: string): Promise<string | null>;
+    /**
+     * Unregister a cron job by name
+     */
+    protected cronUnregister(jobName: string): Promise<boolean>;
+    /**
+     * Unregister all cron jobs for this app
+     */
+    protected cronUnregisterAll(): Promise<number>;
+    /**
+     * Get shadow root (override native property)
+     */
+    get shadowRoot(): ShadowRoot;
+    /**
+     * Background service - optional override in subclass
+     * Called immediately after app instantiation, before DOM attachment
+     * Use this for background tasks like URL monitoring, event listening, etc.
+     */
+    protected onBackgroundService?(): void;
+    /**
+     * URL change handler - optional override in subclass
+     * Called when the page URL changes (SPA navigation)
+     * @param url - The new URL
+     */
+    protected onUrlChange?(url: string): void;
+    /**
+     * Server event handler - optional override in subclass
+     * Called when the server sends an event to this app via WebSocket
+     * Works whether the app is in background or foreground mode
+     *
+     * @param event - The event name (e.g., 'form_completed')
+     * @param data - Optional event data from the server
+     *
+     * @example
+     * protected onServerEvent(event: string, data?: Record<string, any>): void {
+     *   if (event === 'form_completed') {
+     *     console.log('Form completed:', data);
+     *     this.refreshData();
+     *   }
+     * }
+     */
+    protected onServerEvent?(event: string, data?: Record<string, any>): void;
+    /**
+     * Render method - must be implemented by subclass
+     * Should return HTML string or directly manipulate shadowRoot
+     */
+    protected render(): void;
+    /**
+     * Setup event listeners - optional override in subclass
+     */
+    protected setupEventListeners(): void;
+    /**
+     * Initialize background service
+     * Called by BackgroundAppManager after instantiation
+     */
+    initializeBackgroundService(): void;
+    /**
+     * Handle URL change
+     * Called by BackgroundAppManager when URL changes
+     */
+    handleUrlChange(url: string): void;
+    /**
+     * Handle server event
+     * Called by BackgroundAppManager when a WebSocket event is received for this app
+     */
+    handleServerEvent(event: string, data?: Record<string, any>): void;
+    /**
+     * Lifecycle: Called when element is added to DOM
+     * This happens when user opens the app in the drawer
+     */
+    connectedCallback(): void;
+    /**
+     * Lifecycle: Called when element is removed from DOM
+     */
+    disconnectedCallback(): void;
+    /**
+     * Cleanup method - optional override in subclass
+     * Called when app is disconnected from DOM
+     */
+    protected cleanup(): void;
+    /**
+     * Get app configuration (for Weave Platform)
+     */
+    getAppInfo(): WeaveAppInfo;
+    /**
+     * Get current app state (for Weave Platform)
+     */
+    getAppState(): Record<string, any>;
+    /**
+     * Set app configuration (for Weave Platform)
+     * Override this method to handle configuration updates
+     */
+    setAppConfig(_config: Record<string, any>): void;
+    /**
+     * Helper: Update app state
+     * If persistState is enabled, state is automatically saved to background service
+     */
+    protected setState(updates: Partial<TState>): void;
+    /**
+     * Persist current state to background service
+     * Called automatically when persistState is enabled
+     */
+    private _persistState;
+    /**
+     * Restore state from background service
+     * Called by BackgroundAppManager during initialization
+     */
+    restoreState(): Promise<boolean>;
+    /**
+     * Helper: Render HTML into shadow root
+     */
+    protected renderHTML(html: string): void;
+    /**
+     * Helper: Query element in shadow root
+     */
+    protected query<T extends Element = Element>(selector: string): T | null;
+    /**
+     * Helper: Query all elements in shadow root
+     */
+    protected queryAll<T extends Element = Element>(selector: string): NodeListOf<T>;
+}
+//# sourceMappingURL=WeaveBaseApp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WeaveBaseApp.d.ts","sourceRoot":"","sources":["../../../src/WeaveBaseApp.ts"],"names":[],"mappings":"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"}