@weave-apps/sdk 0.1.5 → 0.1.6

package/README.md

@@ -10,6 +10,10 @@ Official SDK for building third-party applications for the Weave Platform.
 - ✅ **Project Scaffolding** - Quick start with `weave-init`
 - ✅ **DOM API** - Secure parent page DOM manipulation
 - ✅ **Shadow DOM Isolation** - Scoped styles and encapsulation
+- ✅ **Background Services** - Run code without user interaction
+- ✅ **Form Integration** - Auto-fill forms with extracted data
+- ✅ **AI Integration** - Leverage AI for smart form filling
+- ✅ **Data Persistence** - Store app data with the Weave API
 
 ## Quick Start
 
@@ -19,6 +23,7 @@ Official SDK for building third-party applications for the Weave Platform.
 npx weave-init my-custom-app
 cd my-custom-app
 npm install
+npm run build
 ```
 
 ### 2. Develop Your App
@@ -26,7 +31,7 @@ npm install
 Edit `src/app.ts`:
 
 ```typescript
-import { WeaveBaseApp } from '@weave/app-sdk';
+import { WeaveBaseApp } from '@weave-apps/sdk';
 
 class MyCustomApp extends WeaveBaseApp {
   constructor() {
@@ -39,24 +44,43 @@ class MyCustomApp extends WeaveBaseApp {
       author: 'Your Name',
       tags: ['custom']
     });
+
+    this.state = {
+      count: 0
+    };
   }
 
   protected render(): void {
     this.renderHTML(`
       <style>
-        .container { padding: 20px; }
-        button { padding: 10px 20px; }
+        .container { 
+          padding: 20px; 
+          font-family: system-ui, sans-serif;
+        }
+        button { 
+          padding: 10px 20px; 
+          background: #3b82f6;
+          color: white;
+          border: none;
+          border-radius: 6px;
+          cursor: pointer;
+        }
+        button:hover {
+          background: #2563eb;
+        }
       </style>
       <div class="container">
-        <h1>Hello Weave!</h1>
-        <button id="myBtn">Click Me</button>
+        <h1>Counter App</h1>
+        <p>Count: <span id="count">${this.state.count}</span></p>
+        <button id="incrementBtn">Increment</button>
       </div>
     `);
   }
 
   protected setupEventListeners(): void {
-    this.query('#myBtn')?.addEventListener('click', () => {
-      alert('Button clicked!');
+    this.query('#incrementBtn')?.addEventListener('click', () => {
+      this.setState({ count: this.state.count + 1 });
+      this.render();
     });
   }
 }
@@ -72,19 +96,19 @@ npm run build
 
 This runs:
 1. `tsc` - Compiles TypeScript to JavaScript
-2. `weave-build` - Transpiles to clean, platform-ready JavaScript
+2. `weave-compile` - Transpiles to clean, platform-ready JavaScript
 
-Output: `dist/app.js` - ready for upload to Weave Platform.
+Output: `dist/my-custom-app.js` - ready for upload to Weave Platform.
 
 ### 4. Upload to Weave
 
-Upload the generated `dist/app.js` file to the Weave Platform via the Enterprise Management Console.
+Upload the generated `dist/my-custom-app.js` file to the Weave Platform via the Enterprise Management Console.
 
 ## API Reference
 
 ### WeaveBaseApp
 
-Base class for all Weave apps.
+Base class for all Weave apps. Handles state management, rendering, and lifecycle hooks.
 
 #### Constructor
 
@@ -99,53 +123,153 @@ constructor(appInfo: WeaveAppInfo)
 - `category` (string) - App category
 - `description` (string) - Detailed description
 - `author` (string) - Author name
-- `tags` (string[]) - Optional tags
+- `tags` (string[])` - Optional tags
+
+#### Settings & State
+
+Define typed settings and state:
+
+```typescript
+interface MyAppSettings {
+  apiEndpoint?: string;
+  debugMode?: boolean;
+}
+
+interface MyAppState {
+  isLoading: boolean;
+  data: any;
+}
+
+class MyApp extends WeaveBaseApp<MyAppSettings, MyAppState> {
+  constructor() {
+    super({ /* ... */ });
+    
+    this.state = {
+      isLoading: false,
+      data: null
+    };
+
+    // Access settings (injected from Enterprise Console)
+    console.log(this.appSettings?.apiEndpoint);
+  }
+}
+```
 
 #### Methods to Implement
 
-##### `render(): void`
+##### `render(): void | Promise<void>`
 Render your app's UI. Use `this.renderHTML()` to inject HTML.
 
+```typescript
+protected async render(): Promise<void> {
+  this.renderHTML(`
+    <div>Content here</div>
+  `);
+}
+```
+
 ##### `setupEventListeners(): void` (Optional)
 Setup event listeners for your app's elements.
 
+```typescript
+protected setupEventListeners(): void {
+  this.query('#myBtn')?.addEventListener('click', () => {
+    // Handle click
+  });
+}
+```
+
+##### `onBackgroundService(): void` (Optional)
+Background service that runs when sidebar loads, even if app drawer isn't open.
+
+```typescript
+async onBackgroundService(): Promise<void> {
+  const url = await window.weaveDOM.getPageUrl();
+  if (url.includes('mypage.com')) {
+    // Do something on background
+  }
+}
+```
+
+##### `onUrlChange(newUrl: string): void` (Optional)
+Called when the page URL changes (SPA navigation).
+
+```typescript
+async onUrlChange(newUrl: string): Promise<void> {
+  if (newUrl.includes('form')) {
+    await this.checkAndInjectButton();
+  }
+}
+```
+
 ##### `cleanup(): void` (Optional)
-Cleanup when app is removed from DOM.
+Cleanup when app is removed from DOM. Clear intervals, listeners, watchers.
+
+```typescript
+protected cleanup(): void {
+  if (this.myInterval) {
+    clearInterval(this.myInterval);
+  }
+}
+```
 
 #### Helper Methods
 
 ##### `renderHTML(html: string): void`
 Renders HTML into the shadow root.
 
+```typescript
+this.renderHTML('<h1>Hello</h1>');
+```
+
+##### `setState(updates: object): void`
+Update app state (shallow merge).
+
+```typescript
+this.setState({ isLoading: true, count: 5 });
+```
+
 ##### `query<T>(selector: string): T | null`
 Query a single element in shadow root.
 
+```typescript
+const btn = this.query<HTMLButtonElement>('#myBtn');
+```
+
 ##### `queryAll<T>(selector: string): NodeListOf<T>`
 Query all matching elements in shadow root.
 
-##### `setState(updates: object): void`
-Update app state.
+```typescript
+const buttons = this.queryAll<HTMLButtonElement>('button');
+```
 
 ### WeaveDOMAPI
 
-API for interacting with the parent page DOM.
+API for securely interacting with the parent page DOM. Available globally as `window.weaveDOM`.
 
-**Available globally as `window.weaveDOM`**
+#### URL & Navigation
+
+```typescript
+// Get current page URL
+const url = await window.weaveDOM.getPageUrl();
+
+// Open new tab
+window.open(url, '_blank');
+```
 
 #### Read Operations
 
 ```typescript
 // Query element
 const element = await window.weaveDOM.query('h1');
+// Returns: { exists: boolean, value?: string, outerHTML?: string }
 
 // Get text content
 const text = await window.weaveDOM.getText('h1');
 
-// Get attribute
-const href = await window.weaveDOM.getAttribute('a', 'href');
-
-// Check if element has class
-const hasClass = await window.weaveDOM.hasClass('.btn', 'active');
+// Get form data
+const formData = await window.weaveDOM.getFormData('form');
+// Returns: { formId, formName, fields: [...] }
 ```
 
 #### Write Operations
@@ -154,70 +278,221 @@ const hasClass = await window.weaveDOM.hasClass('.btn', 'active');
 // Set text
 await window.weaveDOM.setText('h1', 'New Title');
 
-// Add class
-await window.weaveDOM.addClass('.btn', 'active');
+// Set form field value
+await window.weaveDOM.setFormFieldValue('#email', 'user@example.com', true);
 
-// Set style
-await window.weaveDOM.setStyle('h1', 'color', 'red');
+// Click element
+await window.weaveDOM.clickElement('.submit-btn');
 
-// Set attribute
-await window.weaveDOM.setAttribute('input', 'placeholder', 'Enter text');
+// Remove element
+await window.weaveDOM.removeElement('.old-element');
 ```
 
-#### DOM Manipulation
+#### DOM Injection
 
 ```typescript
-// Insert HTML
-await window.weaveDOM.insertHTML('.container', '<p>New content</p>', 'beforeend');
+// Inject HTML element
+const elementId = await window.weaveDOM.injectElement(
+  '.target-container',
+  'beforeend',
+  '<button id="my-btn">Click Me</button>',
+  {
+    onClick: async () => {
+      console.log('Button clicked!');
+    }
+  }
+);
 
-// Remove element
-await window.weaveDOM.removeElement('.old-element');
+// Remove injected element
+await window.weaveDOM.removeInjectedElement(elementId);
+```
+
+#### Event Listeners
+
+```typescript
+// Start form click listener
+await window.weaveDOM.startFormClickListener(async (data) => {
+  console.log('Form detected:', data.formData);
+  await window.weaveDOM.stopFormClickListener();
+});
+
+// Watch element for changes
+const watcherId = await window.weaveDOM.watchElement(
+  '.target',
+  (data) => {
+    console.log('Element changed:', data.changeType);
+  },
+  { watchChildren: true, watchAttributes: true }
+);
+
+// Stop watching
+await window.weaveDOM.unwatchElement(watcherId);
 ```
 
+### WeaveAPIClient
+
+API for accessing backend services. Available as `this.weaveAPI` or `window.weaveAPI`.
+
+#### App Data Management
+
+```typescript
+// Create app data
+await this.weaveAPI.appData.create({
+  dataKey: 'my-key',
+  data: { content: '...', timestamp: new Date() }
+});
+
+// Get all app data
+const response = await this.weaveAPI.appData.getAll();
+const allData = response.data || [];
+
+// Update existing data
+await this.weaveAPI.appData.update(dataId, {
+  dataKey: 'my-key',
+  data: { content: '...', timestamp: new Date() }
+});
+```
+
+#### AI Integration
+
+```typescript
+// Call AI for text analysis
+const response = await this.weaveAPI.ai.chat({
+  prompt: 'Extract patient name from this text: ...',
+  context: 'Medical form filling',
+  disableJsonExtraction: false
+});
+
+console.log(response.response);
+```
+
+#### Utilities
+
+```typescript
+// Convert HTML to Markdown
+const markdown = window.weaveAPI.utils.htmlToMarkdown(htmlString);
+
+// Convert Markdown to HTML
+const html = window.weaveAPI.utils.markdownToHtml(markdownString);
+```
+
+## Real-World Example: Heidi to DCP
+
+The included `DemoWeaveHeidiDcp` app demonstrates advanced features:
+
+- **Background Services** - Injects button on Heidi scribe pages
+- **URL Monitoring** - Reacts to SPA navigation
+- **DOM Injection** - Adds UI elements to parent page
+- **Form Detection** - Captures form structure and data
+- **Data Persistence** - Stores consultation notes
+- **AI Integration** - Auto-fills forms using AI
+- **State Management** - Multi-stage workflow (idle → select-form → confirm → filling → success)
+
+Check `src/app.ts` for the complete implementation.
+
+## Advanced Topics
+
+### Settings & Configuration
+
+Settings are injected from the Enterprise Console and displayed as auto-extracted form fields:
+
+```typescript
+interface MyAppSettings {
+  /**
+   * @description API endpoint for the service
+   * @default "https://api.example.com"
+   */
+  apiEndpoint?: string;
+
+  /**
+   * @description Enable debug logging
+   * @default false
+   */
+  debugMode?: boolean;
+}
+
+class MyApp extends WeaveBaseApp<MyAppSettings, MyAppState> {
+  constructor() {
+    super({ /* ... */ });
+    
+    const endpoint = this.appSettings?.apiEndpoint || 'https://api.example.com';
+    const debug = this.appSettings?.debugMode || false;
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+try {
+  const data = await this.weaveAPI.appData.getAll();
+} catch (error) {
+  console.error('Failed to fetch data:', error);
+  this.setState({ error: error.message });
+  this.render();
+}
+```
+
+### Performance Tips
+
+- Use `async/await` for API calls to avoid blocking UI
+- Debounce rapid state changes with timers
+- Clear intervals and listeners in `cleanup()`
+- Use `isCheckingContainer` flags to prevent overlapping async callbacks
+- Minimize re-renders by updating state only when needed
+
 ## Build Process
 
-The build uses two commands:
+The build pipeline has two steps:
+
+1. **TypeScript Compilation** (`tsc`)
+    - Compiles TypeScript to ES2020 JavaScript
+    - Outputs to `dist/`
 
-1. **`tsc`** - TypeScript compiler (ES2020 target)
-2. **`weave-build`** - SDK's build tool that:
-   - Removes import statements (SDK is global)
-   - Replaces SDK references with `window.*`
-   - Adds header comment
-   - Generates clean, readable JavaScript
+2. **SDK Build** (`weave-compile`)
+    - Removes SDK imports (SDK is global)
+    - Replaces SDK references with `window.*`
+    - Generates final output ready for deployment
 
-You can also run `weave-build` manually after compiling:
+You can also run manually:
 ```bash
 tsc
-weave-build
+weave-compile
 ```
 
 ## Security
 
 - ✅ **Selector Validation** - Prevents dangerous selectors
-- ✅ **HTML Sanitization** - Removes scripts and event handlers
+- ✅ **HTML Sanitization** - Removes scripts and dangerous content
 - ✅ **Attribute Whitelist** - Blocks dangerous attributes
 - ✅ **Shadow DOM Isolation** - Scoped styles and encapsulation
-- ✅ **No Direct DOM Access** - All operations go through secure bridge
+- ✅ **Secure Bridge** - All DOM operations go through security validation
 
 ## Project Structure
 
 ```
 my-app/
 ├── src/
-│   └── app.ts          # Your TypeScript source
+│   └── app.ts                    # Your TypeScript app
 ├── dist/
-│   └── app.js          # Compiled JavaScript (upload this)
+│   └── my-app.js                 # Compiled output (upload this)
 ├── package.json
 ├── tsconfig.json
+├── SIDEKICK_SPEC.md              # AI assistant guide
 └── README.md
 ```
 
-**Note:** The build script (`weave-build`) is part of the SDK, not copied to your app.
+## Troubleshooting
+
+### "TypeScript not found in SDK"
+Make sure to run `npm install` in your app directory after initialization.
 
-## Examples
+### Form not filling
+Check that selectors match the actual form structure. Use browser DevTools to inspect the form.
 
-See the [examples directory](./examples) for complete app examples.
+### Button not injecting
+Verify the target selector exists before injection attempt. Check browser console for errors.
 
-## License
+### State not persisting
+Use `this.weaveAPI.appData.*` methods to persist data to backend. In-memory state is lost on refresh.
 
-MIT

package/package.json

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