@weave-apps/sdk 0.1.11 → 0.1.13

package/README.md

@@ -12,6 +12,7 @@ Official SDK for building third-party applications for the Weave Platform.
 - ✅ **Shadow DOM Isolation** - Scoped styles and encapsulation
 - ✅ **Background Services** - Run code without user interaction
 - ✅ **State Persistence** - Survive page reloads with auto-persist
+- ✅ **Scheduled Tasks** - Cron jobs with standard cron syntax
 - ✅ **Multi-Page Flows** - Pending operations across navigations
 - ✅ **Form Integration** - Auto-fill forms with extracted data
 - ✅ **AI Integration** - Leverage AI for smart form filling
@@ -58,6 +59,9 @@ Official SDK for building third-party applications for the Weave Platform.
     - [Auto-Persist (Recommended)](#auto-persist-recommended)
     - [Multi-Page Flows (Pending Operations)](#multi-page-flows-pending-operations)
     - [State TTL](#state-ttl)
+  - [Scheduled Tasks (Cron Jobs)](#scheduled-tasks-cron-jobs)
+    - [🔮 Secret Hack: Persistent Cron](#-secret-hack-persistent-cron)
+    - [Cron Syntax](#cron-syntax)
   - [Settings & Configuration](#settings--configuration)
   - [Error Handling](#error-handling)
   - [Performance Tips](#performance-tips)
@@ -540,6 +544,92 @@ class DataTransferApp extends WeaveBaseApp {
 
 Persisted state expires after **5 minutes** by default. This prevents stale state from accumulating.
 
+### Scheduled Tasks (Cron Jobs)
+
+Apps can register scheduled tasks using standard cron syntax. The browser extension acts as the master clock.
+
+```typescript
+class PollingApp extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'polling-app',
+      name: 'Polling App',
+      version: '1.0.0',
+      category: 'utility',
+      description: 'App with scheduled polling',
+      author: 'Your Name',
+      persistState: true, // Important for cron!
+    });
+    
+    this.state = { 
+      cronEnabled: false,  // Track cron state
+      tickCount: 0 
+    };
+  }
+  
+  async onBackgroundService() {
+    // Re-register cron if it was enabled before page reload
+    if (this.state.cronEnabled) {
+      await this.startPolling();
+    }
+  }
+  
+  async startPolling() {
+    // Register cron job - every 5 seconds
+    const jobId = await this.cronTab('*/5 * * * * *', this.handleTick, 'poller');
+    if (jobId) {
+      this.setState({ cronEnabled: true });
+    }
+  }
+  
+  async stopPolling() {
+    await this.cronUnregisterAll();
+    this.setState({ cronEnabled: false });
+  }
+  
+  handleTick() {
+    this.setState({ tickCount: this.state.tickCount + 1 });
+    console.log('Tick!', this.state.tickCount);
+    
+    // Update UI if app is open
+    if (this.isConnected) {
+      this.render();
+      this.setupEventListeners();
+    }
+  }
+}
+```
+
+#### 🔮 Secret Hack: Persistent Cron
+
+Cron jobs don't survive page reloads by default. The **secret hack** is to combine `persistState: true` with a `cronEnabled` state flag:
+
+1. **Track cron state** - Add `cronEnabled: boolean` to your state
+2. **Set flag when starting** - `this.setState({ cronEnabled: true })`
+3. **Re-register on reload** - Check `this.state.cronEnabled` in `onBackgroundService()`
+
+This way, when the page reloads, your state is restored (including `cronEnabled: true`), and `onBackgroundService()` automatically re-registers the cron job!
+
+#### Cron Syntax
+
+```
+┌───────────── second (0-59) - optional
+│ ┌───────────── minute (0-59)
+│ │ ┌───────────── hour (0-23)
+│ │ │ ┌───────────── day of month (1-31)
+│ │ │ │ ┌───────────── month (1-12)
+│ │ │ │ │ ┌───────────── day of week (0-6)
+│ │ │ │ │ │
+* * * * * *
+```
+
+**Common patterns:**
+- `* * * * * *` - Every second
+- `*/5 * * * * *` - Every 5 seconds
+- `*/30 * * * * *` - Every 30 seconds
+- `0 * * * * *` - Every minute
+- `0 */5 * * * *` - Every 5 minutes
+
 ### Settings & Configuration
 
 Settings are injected from the Enterprise Console and displayed as auto-extracted form fields:

package/dist/WeaveBaseApp.d.ts

@@ -56,8 +56,14 @@
  * customElements.define('my-app', MyApp);
  * ```
  */
-import { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
-export type { PendingOperation } from './WeaveBackgroundAPI';
+/**
+ * Pending operation for multi-page flows
+ */
+export interface PendingOperation {
+    type: string;
+    data: any;
+    targetUrl?: string;
+}
 /**
  * App metadata configuration
  */
@@ -108,6 +114,8 @@ export declare abstract class WeaveBaseApp<TSettings = Record<string, any>, TSta
     protected weaveAPI: any;
     /** Background API for state persistence */
     private _backgroundAPI;
+    /** Cron API for scheduled tasks */
+    private _cronAPI;
     /** Debounced persist function */
     private _debouncedPersist;
     /** Flag to track if state has been restored */
@@ -123,7 +131,43 @@ export declare abstract class WeaveBaseApp<TSettings = Record<string, any>, TSta
      * Get the background API for state persistence and pending operations
      * Use this for manual state management or multi-page flows
      */
-    protected get background(): WeaveBackgroundAPI | null;
+    protected get background(): any;
+    /**
+     * Get the cron API for scheduled tasks
+     */
+    protected get cron(): 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)
      */

package/dist/WeaveBaseApp.d.ts.map

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

package/dist/WeaveBaseApp.js

@@ -56,7 +56,6 @@
  * customElements.define('my-app', MyApp);
  * ```
  */
-import { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
 /**
  * Simple debounce utility
  */
@@ -88,6 +87,8 @@ export class WeaveBaseApp extends HTMLElement {
         this.state = {};
         /** Background API for state persistence */
         this._backgroundAPI = null;
+        /** Cron API for scheduled tasks */
+        this._cronAPI = null;
         /** Debounced persist function */
         this._debouncedPersist = null;
         /** Flag to track if state has been restored */
@@ -120,7 +121,14 @@ export class WeaveBaseApp extends HTMLElement {
                 this.weaveAPI = new window.WeaveAPIClient();
                 this.weaveAPI.setAppId(this._appUuid);
                 // Create background API instance for state persistence
-                this._backgroundAPI = new WeaveBackgroundAPI(this._appUuid);
+                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();
+                }
                 // Set up debounced persist if enabled
                 if (appInfo.persistState) {
                     const delay = appInfo.persistDebounce ?? 100;
@@ -143,6 +151,60 @@ export class WeaveBaseApp extends HTMLElement {
     get background() {
         return this._backgroundAPI;
     }
+    /**
+     * Get the cron API for scheduled tasks
+     */
+    get cron() {
+        return this._cronAPI;
+    }
+    /**
+     * 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)
      */

package/dist/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/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/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;

package/dist/global.d.ts

@@ -8,6 +8,7 @@ import { WeaveBaseApp } from './WeaveBaseApp';
 import { WeaveDOMAPI } from './WeaveDOMAPI';
 import { WeaveAPIClient } from './WeaveAPIClient';
 import { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
+import { WeaveCronAPI } from './WeaveCronAPI';
 declare global {
     interface Window {
         WeaveBaseApp: typeof WeaveBaseApp;
@@ -16,6 +17,7 @@ declare global {
         WeaveAPIClient: typeof WeaveAPIClient;
         weaveAPI: WeaveAPIClient;
         WeaveBackgroundAPI: typeof WeaveBackgroundAPI;
+        WeaveCronAPI: typeof WeaveCronAPI;
     }
 }
 //# sourceMappingURL=global.d.ts.map

package/dist/global.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"global.d.ts","sourceRoot":"","sources":["../src/global.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,YAAY,EAAE,OAAO,YAAY,CAAC;QAClC,WAAW,EAAE,OAAO,WAAW,CAAC;QAChC,QAAQ,EAAE,WAAW,CAAC;QACtB,cAAc,EAAE,OAAO,cAAc,CAAC;QACtC,QAAQ,EAAE,cAAc,CAAC;QACzB,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;KAAG;CACpD"}
+{"version":3,"file":"global.d.ts","sourceRoot":"","sources":["../src/global.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,YAAY,EAAE,OAAO,YAAY,CAAC;QAClC,WAAW,EAAE,OAAO,WAAW,CAAC;QAChC,QAAQ,EAAE,WAAW,CAAC;QACtB,cAAc,EAAE,OAAO,cAAc,CAAC;QACtC,QAAQ,EAAE,cAAc,CAAC;QACzB,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;QAC9C,YAAY,EAAE,OAAO,YAAY,CAAC;KAAG;CACxC"}

package/dist/global.js

@@ -10,6 +10,7 @@ import weavekDOM from './WeaveDOMAPI';
 import { WeaveAPIClient } from './WeaveAPIClient';
 import weaveAPI from './WeaveAPIClient';
 import { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
+import { WeaveCronAPI } from './WeaveCronAPI';
 // Make SDK available globally
 window.WeaveBaseApp = WeaveBaseApp;
 window.WeaveDOMAPI = WeaveDOMAPI;
@@ -17,3 +18,4 @@ window.weaveDOM = weavekDOM;
 window.WeaveAPIClient = WeaveAPIClient;
 window.weaveAPI = weaveAPI;
 window.WeaveBackgroundAPI = WeaveBackgroundAPI;
+window.WeaveCronAPI = WeaveCronAPI;

package/dist/index.d.ts

@@ -9,5 +9,6 @@ export { default as weaveDOM } from './WeaveDOMAPI';
 export { WeaveAPIClient, type AIChatRequest, type AIChatResponse, type AppData, type CreateAppDataRequest, type UpdateAppDataRequest } from './WeaveAPIClient';
 export { default as weaveAPI } from './WeaveAPIClient';
 export { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
+export { WeaveCronAPI } from './WeaveCronAPI';
 import './global';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACxF,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACvF,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACxF,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACvF,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,UAAU,CAAC"}

package/dist/index.js

@@ -9,5 +9,6 @@ export { default as weaveDOM } from './WeaveDOMAPI';
 export { WeaveAPIClient } from './WeaveAPIClient';
 export { default as weaveAPI } from './WeaveAPIClient';
 export { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
+export { WeaveCronAPI } from './WeaveCronAPI';
 // Import global.ts to ensure Window interface augmentation is included
 import './global';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weave-apps/sdk",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "SDK for building Weave Micro Apps",
   "publishConfig": {
     "access": "public"

package/scripts/copy-sdk-files.js

@@ -17,6 +17,7 @@ const filesToCopy = [
   'WeaveDOMAPI.ts',
   'WeaveAPIClient.ts',
   'WeaveBackgroundAPI.ts',
+  'WeaveCronAPI.ts',
   'global.ts',
   'app-template.js',
   'README.md',

package/templates/WEAVE_SPEC.md

@@ -1088,9 +1088,10 @@ customElements.define('smart-form-assistant', SmartFormAssistant);
 4. **Multi-Page Flows**: Use `this.background?.setPendingOperation()` for cross-page operations
 5. **Background Service**: `onBackgroundService()` runs immediately, before DOM attachment
 6. **URL Monitoring**: `onUrlChange()` detects SPA navigation automatically
-7. **Shared Context**: Background and foreground share the same instance and state
-8. **DOM Check**: Use `this.isConnected` to check if app is attached to DOM
-9. **No User Interaction Required**: Apps can run and inject UI automatically
+7. **Scheduled Tasks**: Use `this.cronTab()` to register cron jobs with standard cron syntax
+8. **Shared Context**: Background and foreground share the same instance and state
+9. **DOM Check**: Use `this.isConnected` to check if app is attached to DOM
+10. **No User Interaction Required**: Apps can run and inject UI automatically
 
 ### Helper Methods (Available in `this`)
 
@@ -1118,6 +1119,18 @@ this.shadowRoot: ShadowRoot
 
 // Access background API for state persistence
 this.background: WeaveBackgroundAPI | null
+
+// Access cron API for scheduled tasks
+this.cron: WeaveCronAPI | null
+
+// Register a cron job (shorthand)
+await this.cronTab(expression: string, callback: () => void, jobName?: string): Promise<string | null>
+
+// Unregister a cron job by name
+await this.cronUnregister(jobName: string): Promise<boolean>
+
+// Unregister all cron jobs for this app
+await this.cronUnregisterAll(): Promise<number>
 ```
 
 ## State Persistence (Survive Page Reloads)
@@ -1372,6 +1385,255 @@ For long-term persistence, use `this.weaveAPI.appData.*` methods instead.
 - Don't forget to clear pending operations
 - Don't assume state will persist forever (5 min TTL)
 
+## Scheduled Tasks (Cron Service)
+
+### Overview
+
+Apps can register **scheduled tasks** that run on a timer using standard cron syntax. The browser extension acts as the master clock, ticking every second and notifying apps when their cron expressions match.
+
+**Use cases:**
+- ⏰ **Periodic polling** - Check for updates every N seconds
+- 🔄 **Auto-refresh** - Update UI or data at intervals
+- 📊 **Monitoring** - Track metrics over time
+- 🔔 **Reminders** - Trigger notifications on schedule
+
+### Architecture
+
+```
+[Background Script: CronService] ← Master clock (ticks every second)
+            ↓
+[Content Script: CronBridge] ← Routes tick messages
+            ↓
+[Iframe: App] ← Receives CRON_TICK, executes callback
+```
+
+### Registering a Cron Job
+
+Use `this.cronTab()` to register a cron job:
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'my-app',
+      name: 'My App',
+      version: '1.0.0',
+      category: 'utility',
+      description: 'App with scheduled tasks',
+      tags: ['cron'],
+      persistState: true, // Recommended for cron apps
+    });
+    
+    this.state = {
+      tickCount: 0,
+      cronEnabled: false
+    };
+  }
+  
+  async onBackgroundService() {
+    // Re-register cron if it was enabled before page reload
+    if (this.state.cronEnabled) {
+      await this.startCron();
+    }
+  }
+  
+  async startCron() {
+    // Register a cron job - every 5 seconds
+    const jobId = await this.cronTab('*/5 * * * * *', this.handleTick, 'myTicker');
+    
+    if (jobId) {
+      console.log('Cron registered:', jobId);
+      this.setState({ cronEnabled: true });
+    }
+  }
+  
+  async stopCron() {
+    await this.cronUnregisterAll();
+    this.setState({ cronEnabled: false });
+  }
+  
+  // Cron callback - called every 5 seconds
+  handleTick() {
+    this.setState({ tickCount: this.state.tickCount + 1 });
+    console.log('Tick!', this.state.tickCount);
+    
+    // Update UI if app is open
+    if (this.isConnected) {
+      this.render();
+      this.setupEventListeners();
+    }
+  }
+}
+```
+
+### Cron Syntax
+
+The cron service supports both **5-field** (standard) and **6-field** (with seconds) expressions:
+
+#### 5-Field (Standard Cron)
+```
+┌───────────── minute (0-59)
+│ ┌───────────── hour (0-23)
+│ │ ┌───────────── day of month (1-31)
+│ │ │ ┌───────────── month (1-12)
+│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
+│ │ │ │ │
+* * * * *
+```
+
+#### 6-Field (With Seconds)
+```
+┌───────────── second (0-59)
+│ ┌───────────── minute (0-59)
+│ │ ┌───────────── hour (0-23)
+│ │ │ ┌───────────── day of month (1-31)
+│ │ │ │ ┌───────────── month (1-12)
+│ │ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
+│ │ │ │ │ │
+* * * * * *
+```
+
+#### Special Characters
+
+| Character | Description | Example |
+|-----------|-------------|---------|
+| `*` | Any value | `* * * * * *` = every second |
+| `,` | Value list | `0,30 * * * * *` = at 0 and 30 seconds |
+| `-` | Range | `0-10 * * * * *` = seconds 0-10 |
+| `/` | Step | `*/5 * * * * *` = every 5 seconds |
+
+#### Common Examples
+
+```typescript
+// Every second
+await this.cronTab('* * * * * *', callback);
+
+// Every 5 seconds
+await this.cronTab('*/5 * * * * *', callback);
+
+// Every 10 seconds
+await this.cronTab('*/10 * * * * *', callback);
+
+// Every 30 seconds
+await this.cronTab('0,30 * * * * *', callback);
+
+// Every minute (at second 0)
+await this.cronTab('0 * * * * *', callback);
+
+// Every 5 minutes
+await this.cronTab('0 */5 * * * *', callback);
+
+// Every hour at minute 0
+await this.cronTab('0 0 * * * *', callback);
+
+// Standard 5-field: every minute
+await this.cronTab('* * * * *', callback);
+```
+
+### Cron API Methods
+
+```typescript
+// Register a cron job
+// Returns job ID if successful, null if failed
+await this.cronTab(
+  cronExpression: string,  // Cron expression (5 or 6 fields)
+  callback: () => void,    // Function to call on each tick
+  jobName?: string         // Optional unique name for the job
+): Promise<string | null>
+
+// Unregister a specific job by name
+await this.cronUnregister(jobName: string): Promise<boolean>
+
+// Unregister all cron jobs for this app
+await this.cronUnregisterAll(): Promise<number>
+
+// Access cron API directly (advanced)
+this.cron?.register(expression, callback, name)
+this.cron?.unregister(jobName)
+this.cron?.unregisterAll()
+this.cron?.list()
+```
+
+### Persisting Cron State Across Page Reloads
+
+Cron jobs are **not automatically re-registered** after a page reload. Use `persistState: true` and re-register in `onBackgroundService()`:
+
+```typescript
+class PersistentCronApp extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'persistent-cron',
+      name: 'Persistent Cron',
+      version: '1.0.0',
+      category: 'utility',
+      description: 'Cron that survives page reloads',
+      tags: ['cron'],
+      persistState: true, // ✅ Enable state persistence
+    });
+    
+    this.state = {
+      cronEnabled: false,
+      tickCount: 0
+    };
+  }
+  
+  async onBackgroundService() {
+    // ✅ Re-register cron if it was enabled before reload
+    if (this.state.cronEnabled) {
+      await this.cronTab('*/5 * * * * *', this.handleTick, 'ticker');
+    }
+  }
+  
+  handleTick() {
+    this.setState({ tickCount: this.state.tickCount + 1 });
+  }
+  
+  async toggleCron() {
+    if (this.state.cronEnabled) {
+      await this.cronUnregisterAll();
+      this.setState({ cronEnabled: false });
+    } else {
+      await this.cronTab('*/5 * * * * *', this.handleTick, 'ticker');
+      this.setState({ cronEnabled: true });
+    }
+  }
+}
+```
+
+### Best Practices
+
+#### ✅ DO:
+- Use `persistState: true` to remember cron state across reloads
+- Re-register cron jobs in `onBackgroundService()` if they were enabled
+- Give jobs meaningful names for easier management
+- Use appropriate intervals (don't poll every second unless necessary)
+- Update UI only if `this.isConnected` (app is open)
+- Clean up cron jobs in `cleanup()` method
+
+#### ❌ DON'T:
+- Don't register cron jobs in the constructor (use `onBackgroundService()`)
+- Don't use very short intervals without good reason (battery/performance)
+- Don't assume cron jobs survive page reloads (they don't)
+- Don't forget to unregister jobs when no longer needed
+
+### Cleanup
+
+Cron jobs are automatically cleaned up when:
+- The tab is closed
+- The app explicitly unregisters them
+- The extension is reloaded
+
+For manual cleanup:
+
+```typescript
+class MyApp extends WeaveBaseApp {
+  protected cleanup(): void {
+    // Clean up cron jobs when app is removed from DOM
+    this.cronUnregisterAll();
+  }
+}
+```
+
 ## Weave Backend API
 
 ### ⚠️ CRITICAL: API Access Restrictions