@weave-apps/sdk 0.1.12 → 0.1.14

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/package.json

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

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