@synod-ai/extension-feedback 0.1.1

package/README.md

@@ -0,0 +1,308 @@
+# @synod-ai/extension-feedback
+
+Synod Feedback Extension SDK — submit in-app feedback as structured findings to a Synod gateway instance. Captures element context (CSS selector, viewport, route), optional screenshots, and queues findings for batch submission with retry.
+
+## Installation
+
+```bash
+npm install @synod-ai/extension-feedback
+```
+
+### Peer Dependencies
+
+- **React** ≥18 and **react-dom** ≥18 (only if using the React wrapper)
+- The core SDK is framework-agnostic — zero React imports
+
+---
+
+## Quick Start
+
+### Vanilla JavaScript
+
+```js
+import { init, enable, queue, sendBatch } from '@synod-ai/extension-feedback';
+
+// 1. Configure with your gateway URL, project ID, and extension token
+init({
+  gatewayUrl: 'http://localhost:8787',
+  projectId: 'your-project-id',
+  token: 'your-extension-token',
+});
+
+// 2. Enable the feedback overlay (key-combo listener activates)
+enable();
+
+// 3. Queue a finding manually (or use the built-in element picker via Ctrl+Shift+E)
+queue({
+  title: 'Button contrast too low',
+  description: 'The checkout button fails WCAG AA contrast at 2.4:1',
+  severity: 'high',
+  context_json: {
+    url: 'https://shop.example.com/checkout',
+    css_selector: '#checkout-btn',
+    element_text: 'Pay Now',
+    viewport: { width: 1440, height: 900 },
+    route: '/checkout',
+  },
+});
+
+// 4. Submit batch to the gateway
+const result = await sendBatch();
+console.log(`Created: ${result.created.length}, Errors: ${result.errors.length}`);
+```
+
+### React
+
+```jsx
+import { FeedbackProvider, useFeedback } from '@synod-ai/extension-feedback/react';
+
+// Wrap your app
+function App() {
+  return (
+    <FeedbackProvider
+      config={{
+        gatewayUrl: 'http://localhost:8787',
+        projectId: 'your-project-id',
+        token: 'your-extension-token',
+        keyCombo: 'Ctrl+Shift+E',
+      }}
+      autoEnable
+    >
+      <YourApp />
+    </FeedbackProvider>
+  );
+}
+
+// Use the hook in any child component
+function FeedbackButton() {
+  const { isEnabled, enable, disable, sendBatch } = useFeedback();
+
+  return (
+    <button onClick={() => (isEnabled ? disable() : enable())}>
+      {isEnabled ? 'Disable Feedback' : 'Enable Feedback'}
+    </button>
+  );
+}
+```
+
+---
+
+## Configuration
+
+### `FeedbackConfig`
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `gatewayUrl` | `string` | Yes (defaults if omitted) | `http://localhost:8787` | Synod gateway base URL |
+| `projectId` | `string` | **Yes** | — | Target project ID |
+| `token` | `string` | **Yes** | — | Extension auth token (generated in Desktop → Extensions settings tab) |
+| `keyCombo` | `string` | No | `Ctrl+Shift+E` | Key combo to activate the feedback overlay (hold ~500ms) |
+| `timeout` | `number` | No | `15000` | Request timeout in ms |
+| `maxRetries` | `number` | No | `3` | Max retry attempts on transient failures |
+
+### Key Combo Format
+
+The `keyCombo` string uses `+`-separated modifiers + key:
+
+```
+Ctrl+Shift+E    (default — avoids Ctrl+Shift+F browser fullscreen conflict)
+Ctrl+Alt+F
+Shift+Q
+```
+
+Supported modifiers: `Ctrl` (or `Control`), `Shift`, `Alt`.
+
+Hold detection: the combo must be held for ~500ms to activate, preventing accidental triggers.
+
+---
+
+## API Reference
+
+### Core Functions (`@synod-ai/extension-feedback`)
+
+| Function | Description |
+|---|---|
+| `init(config)` | Initialize the SDK with gateway config |
+| `enable()` | Enable the feedback overlay + key-combo listener |
+| `disable()` | Disable the feedback overlay |
+| `isEnabled()` | Returns `true` if the overlay is active |
+| `queue(finding)` | Add a finding to the submission queue |
+| `sendBatch()` | Submit all queued findings to the gateway (returns `Promise<BatchResult>`) |
+| `clearQueue()` | Remove all findings from the queue |
+| `getQueueLength()` | Current queue size |
+
+### React (`@synod-ai/extension-feedback/react`)
+
+| Export | Description |
+|---|---|
+| `<FeedbackProvider config={...} autoEnable?>` | Context provider that manages the FeedbackManager lifecycle |
+| `useFeedback()` | Hook returning `{ init, enable, disable, sendBatch, queue, isEnabled, enabled }` |
+
+### Types
+
+```typescript
+type FindingSeverity = 'low' | 'medium' | 'high';
+
+interface FindingContextJson {
+  url?: string;
+  css_selector?: string;
+  element_text?: string;
+  viewport?: { width: number; height: number };
+  route?: string;
+  screenshot_data_url?: string;  // data:image/* URL, ≤10KB total context budget
+}
+
+interface FindingPayload {
+  title: string;
+  description: string;
+  severity: FindingSeverity;
+  suggested_action?: 'create_story';
+  context_json: FindingContextJson;
+}
+```
+
+---
+
+## Gateway Setup
+
+### 1. Token Generation
+
+Generate an extension token from the Synod Desktop app:
+
+1. Open **Settings → Extensions** tab
+2. Click **Generate Token**
+3. Copy the token and pass it to `init({ token })`
+
+### 2. Project ID
+
+Find your project ID in the Synod Desktop sidebar or via `GET /v2/projects/active`.
+
+---
+
+## Network Topology
+
+The extension SDK communicates with the Synod gateway via HTTP `POST /v2/findings/external`. The gateway URL determines how the extension connects.
+
+### Localhost (Default)
+
+```
+Browser (your app)  →  http://localhost:8787  →  Synod Gateway
+```
+
+- **Default mode** — works for same-machine testing
+- Chrome and Firefox have a **localhost mixed-content exemption**: `fetch()` from an HTTPS page to `http://localhost:*` is allowed
+- No additional setup needed
+- Gateway URL: `http://localhost:8787`
+
+### LAN (Same Network)
+
+```
+Browser (other device)  →  http://192.168.x.x:8787  →  Synod Gateway (0.0.0.0 binding)
+```
+
+- For testing from other devices on the same local network
+- Bind the gateway to `0.0.0.0` to accept LAN connections
+- Gateway URL: `http://<your-lan-ip>:8787`
+- **Note:** Only works if your app is served over HTTP. If your app is HTTPS, see Tunnel mode below.
+
+### Tunnel (HTTPS Apps / Remote Access)
+
+```
+Browser (HTTPS app)  →  https://your-tunnel.ngrok.io  →  Synod Gateway
+```
+
+**When to use:** Your web app is served over HTTPS and needs to call the gateway. Browsers block `fetch()` from HTTPS pages to HTTP endpoints (**mixed content blocking**). The localhost exemption does not apply to LAN IPs — only to `localhost` / `127.0.0.1`.
+
+**Setup with ngrok:**
+
+```bash
+# Expose the Synod gateway (default port 8787) via HTTPS
+ngrok http 8787
+
+# Copy the HTTPS forwarding URL (e.g., https://abc123.ngrok.io)
+# Use it as the gatewayUrl:
+```
+
+```js
+init({
+  gatewayUrl: 'https://abc123.ngrok.io',
+  projectId: 'your-project-id',
+  token: 'your-extension-token',
+});
+```
+
+**Setup with Cloudflare Tunnel:**
+
+```bash
+cloudflared tunnel --url http://localhost:8787
+# Copy the generated HTTPS URL
+```
+
+### Mixed Content Guidance
+
+| App URL | Gateway URL | Works? | Notes |
+|---|---|---|---|
+| `http://localhost:3000` | `http://localhost:8787` | ✅ | Same-origin HTTP, no issue |
+| `https://localhost:3000` | `http://localhost:8787` | ✅ | Localhost mixed-content exemption |
+| `https://app.example.com` | `http://localhost:8787` | ❌ | Mixed content blocked — use tunnel |
+| `https://app.example.com` | `http://192.168.x.x:8787` | ❌ | Mixed content blocked — use tunnel |
+| `https://app.example.com` | `https://tunnel.ngrok.io` | ✅ | HTTPS-to-HTTPS via tunnel |
+
+**Recommendation:** For production HTTPS environments, always use a tunnel (ngrok or Cloudflare Tunnel) to provide an HTTPS endpoint for the gateway.
+
+---
+
+## Context JSON
+
+The `context_json` object captures browser context for each finding. All fields are optional; the gateway enforces a **10KB total budget** (`MAX_CONTEXT_JSON_BYTES = 10_240`).
+
+| Field | Type | Description |
+|---|---|---|
+| `url` | `string` | Full page URL |
+| `css_selector` | `string` | CSS selector of the target element |
+| `element_text` | `string` | Text content of the target element |
+| `viewport` | `{ width, height }` | Browser viewport dimensions |
+| `route` | `string` | Current route/pathname |
+| `screenshot_data_url` | `string` | Base64 `data:image/*` screenshot (pre-compressed to fit budget) |
+| `user_agent` | `string` | Browser user agent |
+| `batch_id` | `string` | Batch correlation ID |
+| `extension_version` | `string` | SDK version |
+
+### Screenshot Size Limit
+
+The `screenshot_data_url` must fit within the 10KB total `context_json` budget. The SDK pre-compresses screenshots before queuing. If the serialized context exceeds 10KB, the gateway rejects the batch with a `CONTEXT_TOO_LARGE` error.
+
+---
+
+## Error Handling
+
+```js
+import { sendBatch } from '@synod-ai/extension-feedback';
+
+try {
+  const result = await sendBatch();
+  // result.created: array of { id, title, severity }
+  // result.errors: array of { index, error }
+} catch (err) {
+  // err.code: 'AUTH_ERROR' | 'RATE_LIMITED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'SERVER_ERROR' | 'CONTEXT_TOO_LARGE'
+  console.error(`[${err.code}] ${err.message}`);
+  if (err.retryable) {
+    // SDK already retries automatically (maxRetries), but you can re-queue
+  }
+}
+```
+
+| Error Code | Retryable | Description |
+|---|---|---|
+| `AUTH_ERROR` | No | Invalid or expired token |
+| `RATE_LIMITED` | Yes | Gateway rate limit hit (429) |
+| `NETWORK_ERROR` | Yes | Connection failed |
+| `TIMEOUT` | Yes | Request exceeded timeout |
+| `SERVER_ERROR` | Yes | Gateway 5xx response |
+| `CONTEXT_TOO_LARGE` | No | `context_json` exceeds 10KB budget |
+
+---
+
+## License
+
+MIT

package/dist/index.d.cts

@@ -0,0 +1,253 @@
+type FindingSeverity = 'low' | 'medium' | 'high';
+interface FindingContextJson {
+    url?: string;
+    /** SPA route or pathname (best-effort). Helps the agent know which "screen" the user was on. */
+    route?: string;
+    /** Document title — gives the agent a human-readable label for the page. */
+    page_title?: string;
+    element_text?: string;
+    /** outerHTML of the selected element, truncated at ~1500 chars. */
+    element_html?: string;
+    /** Filtered attribute map of the selected element. */
+    element_attributes?: Record<string, string>;
+    /**
+     * Root-first parent chain, filtered to ancestors with an id or class.
+     * Generic wrappers are skipped on the client. Each entry is
+     * {tag, id?, className?}.
+     */
+    parent_chain?: Array<{
+        tag: string;
+        id?: string;
+        className?: string;
+    }>;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    user_agent?: string;
+    screenshot_data_url?: string;
+    batch_id?: string;
+    extension_version?: string;
+}
+interface FindingPayload {
+    title: string;
+    description: string;
+    severity: FindingSeverity;
+    suggested_action?: 'create_story';
+    context_json: FindingContextJson;
+}
+interface ExternalFindingsRequest {
+    project_id: string;
+    findings: FindingPayload[];
+}
+interface CreatedFinding {
+    id: string;
+    title: string;
+    severity: FindingSeverity;
+}
+interface FindingError {
+    index: number;
+    error: string;
+}
+interface BatchResponse {
+    created: CreatedFinding[];
+    errors: FindingError[];
+}
+interface BatchResult {
+    created: CreatedFinding[];
+    errors: FindingError[];
+}
+type ClientErrorCode = 'AUTH_ERROR' | 'RATE_LIMITED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'SERVER_ERROR' | 'CLIENT_ERROR' | 'CONTEXT_TOO_LARGE';
+interface ClientError extends Error {
+    code: ClientErrorCode;
+    statusCode?: number;
+    retryable: boolean;
+}
+interface FeedbackConfig {
+    gatewayUrl: string;
+    projectId: string;
+    token: string;
+    keyCombo?: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+
+declare class SynodFeedbackClient {
+    private readonly config;
+    private _queue;
+    private _abortControllers;
+    constructor(config: FeedbackConfig);
+    /**
+     * Add a finding to the local batch queue.
+     * Pre-validates context_json size to prevent oversized payloads.
+     */
+    queue(finding: FindingPayload): void;
+    /**
+     * Get the current queue length.
+     */
+    get queueLength(): number;
+    /**
+     * Get a shallow copy of the current queue.
+     */
+    getQueueSnapshot(): FindingPayload[];
+    /**
+     * Clear all items from the queue.
+     */
+    clearQueue(): void;
+    /**
+     * Send all queued findings as a batch to the gateway.
+     * On success (201): created items are dequeued; errored items remain.
+     * On full failure (after retries): entire batch remains in queue.
+     *
+     * @returns BatchResult with created and errors arrays
+     * @throws ClientError on full failure after retries, or on non-retryable error
+     */
+    sendBatch(): Promise<BatchResult>;
+    /**
+     * POST to the gateway with retry/backoff logic.
+     * Retries up to maxRetries times on retryable failures (5xx, 429, network, timeout).
+     * Does NOT retry on 401 or other 4xx (except 429).
+     *
+     * Worst-case wall time: ~1s + timeout + 2s + timeout + 4s + timeout.
+     */
+    private postWithRetry;
+    /**
+     * Process the gateway response: dequeue created items, retain errored items.
+     * Findings are matched by their position in the original sent batch.
+     */
+    private processResponse;
+    /**
+     * Remove successfully sent items from the live queue.
+     *
+     * The sentFindings were a snapshot of the queue at send time. We need to remove
+     * the successful ones while keeping the failed ones. Since they were all at the
+     * front of the queue (in order), we rebuild: remove createdIndices from [0..sentCount-1].
+     */
+    private dequeueByIndices;
+    private classifyHttpError;
+    private classifyTransportError;
+    /**
+     * Abort all in-flight requests.
+     */
+    destroy(): void;
+    private sleep;
+}
+
+type EnableHandler = () => void;
+type DisableHandler = () => void;
+/**
+ * Singleton lifecycle manager for the feedback extension.
+ *
+ * State machine:
+ *   uninitialized → (init) → initialized (enabled=false)
+ *                              ↕ enable() / disable()
+ *                        initialized (enabled=true/false)
+ *
+ * The client and queue are ALWAYS available regardless of `enabled` state —
+ * `enabled` is a semantic signal for the interaction layer (SDG-294), not a gate on transport.
+ */
+declare class FeedbackManager {
+    private _initialized;
+    private _enabled;
+    private _client;
+    private _config;
+    private _enableHandlers;
+    private _disableHandlers;
+    get initialized(): boolean;
+    get enabled(): boolean;
+    /** The active client instance, or null if not initialized. */
+    get client(): SynodFeedbackClient | null;
+    /** The validated config, or null if not initialized. */
+    get config(): FeedbackConfig | null;
+    /**
+     * Initialize the feedback system with configuration.
+     * Creates the singleton client instance. Re-init replaces existing state.
+     */
+    init(config: FeedbackConfig): void;
+    /**
+     * Enable the feedback system. Fires all registered onEnable handlers.
+     */
+    enable(): void;
+    /**
+     * Disable the feedback system. Fires all registered onDisable handlers.
+     */
+    disable(): void;
+    /**
+     * Register a handler to be called when enable() is invoked.
+     * If already enabled, the handler fires immediately.
+     * @returns unregister function
+     */
+    onEnable(handler: EnableHandler): () => void;
+    /**
+     * Register a handler to be called when disable() is invoked.
+     * @returns unregister function
+     */
+    onDisable(handler: DisableHandler): () => void;
+    queue(finding: FindingPayload): void;
+    sendBatch(): Promise<BatchResult>;
+    get queueLength(): number;
+    getQueueSnapshot(): FindingPayload[];
+    /**
+     * Clear all items from the queue.
+     */
+    clearQueue(): void;
+    /**
+     * Replace the entire queue with the given items.
+     * Used by the interaction layer for remove/edit operations.
+     */
+    replaceQueue(items: FindingPayload[]): void;
+    /**
+     * Reset the manager to uninitialized state.
+     * Destroys client, clears handlers.
+     */
+    destroy(): void;
+    private requireClient;
+}
+
+/**
+ * Encode an array of findings into the clipboard transfer format.
+ * Screenshots are stripped from every finding's context_json.
+ *
+ * Empty arrays still encode (returns the prefix + empty-list base64)
+ * so consumers can distinguish "Synod clipboard blob with no items" from
+ * "not a Synod clipboard blob at all".
+ */
+declare function encodeFindingsToClipboard(findings: FindingPayload[]): string;
+/**
+ * Decode a clipboard string back into findings.
+ *
+ * Returns `{ ok: true, findings }` on success, or `{ ok: false, error }`
+ * if the input is not a Synod findings blob, the JSON is malformed, the
+ * version is unsupported, or any finding has an invalid shape.
+ *
+ * On any decode error the consumer should fall back to plain-text paste
+ * behaviour (or just show an "invalid clipboard" toast).
+ */
+declare function decodeFindingsFromClipboard(raw: string): {
+    ok: true;
+    findings: FindingPayload[];
+} | {
+    ok: false;
+    error: string;
+};
+
+declare function init(config: FeedbackConfig): void;
+declare function enable(): void;
+declare function disable(): void;
+declare function onEnable(handler: () => void): () => void;
+declare function onDisable(handler: () => void): () => void;
+declare function sendBatch(): Promise<BatchResult>;
+declare function queue(finding: FindingPayload): void;
+declare function clearQueue(): void;
+declare function replaceQueue(items: FindingPayload[]): void;
+declare function isEnabled(): boolean;
+declare function getQueueSnapshot(): FindingPayload[];
+declare function getQueueLength(): number;
+
+/**
+ * @internal Reset singleton state. Intended for test isolation only.
+ * Creates a fresh manager and re-registers interaction layer hooks.
+ */
+declare function __resetForTesting(): void;
+
+export { type BatchResponse, type BatchResult, type ClientError, type ClientErrorCode, type CreatedFinding, type ExternalFindingsRequest, type FeedbackConfig, FeedbackManager, type FindingContextJson, type FindingError, type FindingPayload, type FindingSeverity, SynodFeedbackClient, __resetForTesting, clearQueue, decodeFindingsFromClipboard, disable, enable, encodeFindingsToClipboard, getQueueLength, getQueueSnapshot, init, isEnabled, onDisable, onEnable, queue, replaceQueue, sendBatch };