@proveanything/smartlinks 2.0.5 → 2.0.9

package/docs/iframe-streaming-parent-changes.md

@@ -1,308 +0,0 @@
-# Iframe Streaming Parent Changes
-
-This note describes the parent-side changes needed to support AI streaming when an embedded SmartLinks app is running in iframe proxy mode.
-
-If you are using the SDK `IframeResponder` directly, this is already implemented in the SDK changes. You only need this document if your parent application has its own iframe proxy handler and does not rely on `IframeResponder`.
-
-## Goal
-
-Keep the existing architecture:
-
-- local mode: child calls API directly
-- iframe proxy mode: child never owns auth state and streams through the parent
-
-This keeps user/session authority in the parent while making AI streaming behave like the rest of the SDK transport.
-
-## What changed
-
-Previously, proxy mode only supported one-shot request/response messages:
-
-- `_smartlinksProxyRequest`
-- `_smartlinksProxyResponse`
-
-Streaming now adds a second protocol for long-lived responses:
-
-- `_smartlinksProxyStreamRequest`
-- `_smartlinksProxyStream`
-- `_smartlinksProxyStreamAbort`
-
-## New parent message handling
-
-### 1. Listen for stream requests
-
-The iframe child may now send this message:
-
-```ts
-{
-  _smartlinksProxyStreamRequest: true,
-  id: string,
-  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
-  path: string,
-  body?: any,
-  headers?: Record<string, string>
-}
-```
-
-Parent behavior:
-
-- treat this like a proxied API request
-- build the real API URL from your configured base URL plus `path`
-- send the request using the parent's current auth/session context
-- expect an SSE / streaming response body
-- keep the request open until the stream ends or is aborted
-
-### 2. Forward stream lifecycle messages back to the child
-
-The parent should send messages back to the iframe using this envelope:
-
-```ts
-{
-  _smartlinksProxyStream: true,
-  id: string,
-  phase: 'open' | 'event' | 'end' | 'error',
-  data?: any,
-  error?: string,
-  status?: number
-}
-```
-
-Phases:
-
-- `open`
-  - optional but recommended
-  - indicates the upstream streaming request was accepted and a body exists
-- `event`
-  - contains one parsed JSON event from an SSE `data:` frame
-  - send one message per logical event payload
-- `end`
-  - sent once when the stream finishes normally
-- `error`
-  - sent if the upstream request fails before or during streaming
-
-### 3. Support abort from the child
-
-The child may stop reading early and send:
-
-```ts
-{
-  _smartlinksProxyStreamAbort: true,
-  id: string
-}
-```
-
-Parent behavior:
-
-- look up the active stream by `id`
-- abort the underlying fetch / reader
-- clean up any local state for that stream
-- do not keep streaming after abort
-
-## SSE forwarding rules
-
-The upstream AI endpoints return SSE-like frames. The parent should:
-
-- read the response body as a stream
-- buffer text until line boundaries
-- collect `data:` lines for a single event
-- join multi-line `data:` payloads with `\n`
-- ignore blank events
-- stop on `data: [DONE]`
-- JSON-parse each event payload
-- forward parsed payloads to the iframe as `_smartlinksProxyStream` with `phase: 'event'`
-
-Minimal parsing behavior:
-
-1. accumulate bytes into text
-2. split on `\r?\n`
-3. collect each `data:` line
-4. on blank line, finalize the event
-5. if payload is `[DONE]`, finish
-6. otherwise `JSON.parse(payload)` and forward
-
-## Auth and session expectations
-
-The parent remains the source of truth for auth.
-
-That means the parent stream handler should:
-
-- use the same auth headers/token source as normal proxied requests
-- not require the iframe to know the bearer token or API key
-- naturally pick up the current logged-in user when the stream starts
-- cancel active streams if your app invalidates session state on logout or account switch
-
-In practice, the stream request should use the same header-building logic as your normal parent proxy transport.
-
-## Error handling expectations
-
-If the upstream fetch returns a non-2xx status:
-
-- try to read the JSON error body
-- derive a useful message
-- send one `_smartlinksProxyStream` message with `phase: 'error'`
-- include `status` when available
-- do not send `end` afterward
-
-If the stream body is missing unexpectedly:
-
-- send `phase: 'error'`
-
-If JSON parsing fails for a single event chunk:
-
-- safest behavior is to ignore that malformed chunk and continue
-
-## State the parent should keep
-
-Track active streams in a map keyed by `id`:
-
-```ts
-Map<string, AbortController>
-```
-
-Recommended cleanup points:
-
-- on normal stream end
-- on error
-- on child abort
-- on iframe detach/unmount
-- on parent auth reset/logout if you want all in-flight streams cancelled immediately
-
-## Parent implementation outline
-
-```ts
-const activeStreams = new Map<string, AbortController>()
-
-window.addEventListener('message', async (event) => {
-  const msg = event.data
-
-  if (msg?._smartlinksProxyStreamAbort && msg.id) {
-    activeStreams.get(msg.id)?.abort()
-    activeStreams.delete(msg.id)
-    return
-  }
-
-  if (msg?._smartlinksProxyStreamRequest && msg.id) {
-    const controller = new AbortController()
-    activeStreams.set(msg.id, controller)
-
-    try {
-      const response = await fetch(buildUrl(msg.path), {
-        method: msg.method,
-        headers: msg.headers,
-        body: msg.body ? JSON.stringify(msg.body) : undefined,
-        signal: controller.signal,
-      })
-
-      if (!response.ok || !response.body) {
-        postError(...)
-        return
-      }
-
-      postOpen(...)
-      await forwardSse(response.body, parsed => postEvent(...parsed))
-      postEnd(...)
-    } catch (err) {
-      if (err?.name !== 'AbortError') postError(...)
-    } finally {
-      activeStreams.delete(msg.id)
-    }
-  }
-})
-```
-
-## Exact protocol summary
-
-### Child → parent
-
-Standard stream request:
-
-```ts
-{
-  _smartlinksProxyStreamRequest: true,
-  id,
-  method,
-  path,
-  body,
-  headers
-}
-```
-
-Abort request:
-
-```ts
-{
-  _smartlinksProxyStreamAbort: true,
-  id
-}
-```
-
-### Parent → child
-
-Open:
-
-```ts
-{
-  _smartlinksProxyStream: true,
-  id,
-  phase: 'open'
-}
-```
-
-Event:
-
-```ts
-{
-  _smartlinksProxyStream: true,
-  id,
-  phase: 'event',
-  data: parsedJsonEvent
-}
-```
-
-End:
-
-```ts
-{
-  _smartlinksProxyStream: true,
-  id,
-  phase: 'end'
-}
-```
-
-Error:
-
-```ts
-{
-  _smartlinksProxyStream: true,
-  id,
-  phase: 'error',
-  error: 'message',
-  status?: number
-}
-```
-
-## What does not change
-
-These parts of the parent iframe integration stay the same:
-
-- normal `_smartlinksProxyRequest` request/response flow
-- upload proxy flow
-- auth login/logout postMessage handling
-- route/deep-link handling
-- resize handling
-
-This is an additive protocol, not a replacement.
-
-## Current SDK reference
-
-The SDK implementation lives in:
-
-- [src/http.ts](src/http.ts)
-- [src/iframeResponder.ts](src/iframeResponder.ts)
-- [src/types/iframeResponder.ts](src/types/iframeResponder.ts)
-- [src/api/ai.ts](src/api/ai.ts)
-
-## Practical recommendation
-
-If your parent already uses `IframeResponder`, prefer upgrading to the SDK version with these changes instead of re-implementing the protocol manually.
-
-If your parent has a custom iframe bridge, implement exactly the three new message types above and reuse your existing auth/header logic from normal proxied requests.

package/docs/manifests.md

@@ -1,204 +0,0 @@
-# AI-Native App Manifests
-
-SmartLinks apps are designed to be **AI-discoverable, AI-configurable, and AI-importable**. Every app ships with a structured manifest and a prose guide that allow AI systems to set up, configure, and populate apps without custom integration code.
-
----
-
-## The Split Manifest
-
-The manifest is split into two files so the public portal never loads admin-only configuration data.
-
-```text
-app.manifest.json   ←  lean, always loaded (widget render, SEO, executor discovery)
-app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flows)
-```
-
-### `app.manifest.json` — always loaded
-
-| Section | Purpose | AI Consumer |
-|---------|---------|-------------|
-| `meta` | App identity, version, appId, SEO priority | All workflows |
-| `admin` | Pointer to `app.admin.json` | Admin orchestrators |
-| `widgets` | Bundle files + component definitions + settings schemas; can also declare widget-instance resolution via `widgetId` | Widget Builder |
-| `containers` | Bundle files + component definitions | Container Loader |
-| `executor` | Bundle files, factory name, exports list | Server / AI |
-| `linkable` | Static deep-link routes | Portal menus / AI nav |
-
-```json
-{
-  "meta": { "name": "My App", "appId": "my-app", "version": "1.0.0" },
-  "admin": "app.admin.json",
-  "widgets": {
-    "instanceResolution": true,
-    "instanceParam": "widgetId",
-    "files": {
-      "js": { "umd": "dist/widgets.umd.js", "esm": "dist/widgets.es.js" },
-      "css": null
-    },
-    "components": [
-      {
-        "name": "MyWidget",
-        "description": "Compact summary card.",
-        "sizes": ["compact", "standard", "large"],
-        "settings": { ... }
-      }
-    ]
-  },
-  "containers": {
-    "files": {
-      "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.es.js" },
-      "css": null
-    },
-    "components": [{ "name": "PublicContainer", "description": "Full app view." }]
-  },
-  "executor": {
-    "files": { "js": { "umd": "dist/executor.umd.js", "esm": "dist/executor.es.js" } },
-    "factory": "createMyAppExecutor",
-    "exports": ["createMyAppExecutor", "getSEO", "getLLMContent"],
-    "description": "Programmatic configuration and SEO API for My App."
-  },
-  "linkable": [
-    { "title": "Home", "path": "/" },
-    { "title": "Gallery", "path": "/gallery" }
-  ]
-}
-```
-
-When `instanceResolution` is enabled, the app is declaring that consumers can pass a widget instance identifier such as `?appId=widget-toolkit&widgetId=launch-countdown`, and the widget bundle will resolve its stored configuration from app config.
-
-> ⚠️ **`css` is `null` by default.** Most widgets and containers use Tailwind/shadcn classes inherited from the parent and produce **no CSS output file**. Set `"css": null` in the manifest. Only set it to a filename if your widget/container ships a custom CSS file that actually exists in `dist/`. The parent portal checks this value before injecting a `<link>` tag — a non-null value pointing to a missing file will cause a 404.
-
----
-
-### `app.admin.json` — loaded on-demand
-
-| Section | Purpose | AI Consumer |
-|---------|---------|-------------|
-| `aiGuide` | Pointer to `ai-guide.md` prose instructions | All AI workflows |
-| `setup` | Setup wizard: questions, config schema, save instructions | Setup Wizard |
-| `import` | Bulk data import: field definitions, CSV shape, API calls | Data Importer |
-| `tunable` | Runtime-adjustable settings | AI Optimizer |
-| `metrics` | Tracked interactions and KPIs | Analytics Advisor |
-
-The admin orchestrator fetches the manifest, reads the `admin` pointer, and fetches `app.admin.json` only when needed — never on public page loads.
-
-See the [App Configuration Files reference](app-manifest.md) for the full field-by-field schema for both files.
-
----
-
-## Widget Settings Schema
-
-Each widget component in `app.manifest.json` should include a `settings` object using **JSON Schema** to describe its configurable props. This enables schema-form libraries and AI orchestrators to auto-generate configuration UIs without per-widget code.
-
-```json
-"components": [
-  {
-    "name": "MyWidget",
-    "description": "What this widget does",
-    "sizes": ["compact", "standard", "large"],
-    "settings": {
-      "type": "object",
-      "properties": {
-        "displayMode": {
-          "type": "string",
-          "title": "Display Mode",
-          "description": "How the widget renders",
-          "enum": ["compact", "standard", "large"],
-          "enumLabels": {
-            "compact": "Icons only",
-            "standard": "With names",
-            "large": "Full cards"
-          },
-          "default": "standard",
-          "order": 1
-        },
-        "showImage": {
-          "type": "boolean",
-          "title": "Show Product Image",
-          "default": true,
-          "order": 2
-        }
-      }
-    }
-  }
-]
-```
-
-| Field | Purpose |
-|-------|---------|
-| `type`, `enum` | Standard JSON Schema for validation |
-| `title` | Human-readable label for form rendering |
-| `description` | Help text shown alongside the field |
-| `enumLabels` | Friendly display names for enum values (`{ value → label }`) |
-| `default` | Pre-selected value when no configuration exists |
-| `order` | Field display order in rendered forms (lower number = higher position) |
-
-The `settings` schema serves dual purposes: AI orchestrators use it to understand what a widget accepts and generate configuration conversationally; schema-form renderers (e.g., in admin consoles) use it to auto-generate settings UIs.
-
----
-
-## The AI Guide (`ai-guide.md`)
-
-A companion Markdown file deployed alongside the manifest provides **natural-language instructions** for AI orchestrators. The admin config references it via `"aiGuide": "ai-guide.md"` — orchestrators resolve and fetch it relative to the manifest URL.
-
-While the manifest is structured data, the AI guide provides prose context, nuance, and step-by-step instructions that help an LLM drive setup wizards, imports, and troubleshooting flows conversationally.
-
-Use the [AI Guide Template](ai-guide-template.md) as your starting point.
-
----
-
-## Three AI Workflows
-
-### 1. Widget Builder
-
-An AI fetches `app.manifest.json`, reads `widgets.components[]` including the `settings` JSON Schema for each widget, and can:
-- Generate React code to embed the widget with correct props
-- Auto-render a configuration UI from the settings schema
-- Understand valid size hints and required vs optional props
-
-### 2. Setup Wizard
-
-An AI reads `setup` from `app.admin.json` to drive a conversational configuration flow:
-
-1. Walk the user through each `setup.questions[]` entry
-2. Validate answers against `setup.configSchema` (JSON Schema)
-3. Optionally use `setup.contentHints` to auto-generate content via `SL.ai.chat.completions`
-4. Save using the `setup.saveWith` instructions (method, scope, admin flag)
-
-The AI guide (`ai-guide.md`) provides prose instructions on how to handle each question, what sensible defaults look like, and what to do if the user is unsure.
-
-### 3. Data Importer
-
-An AI reads `import` from `app.admin.json` to:
-
-1. Generate a CSV template from `import.fields[]` (with types, required flags, and examples)
-2. Normalise user-provided data against field types
-3. Call `import.saveWith.method` for each row
-
-For multi-app imports, fields from multiple manifests can be merged into a single CSV template.
-
----
-
-## Maintaining the Manifest
-
-When you change your app's configuration shape, update all three files together:
-
-| File | What to update |
-|------|---------------|
-| `app.manifest.json` | `widgets.components[].settings`, `containers`, `executor.exports`, `linkable` |
-| `app.admin.json` | `setup.questions`, `setup.configSchema`, `import.fields`, `tunable.fields` |
-| `ai-guide.md` | Prose instructions, validation rules, examples, and any new question guidance |
-
-Keeping all three in sync ensures AI orchestrators, setup wizards, and data importers all work from consistent, accurate information.
-
----
-
-## Related Guides
-
-| Guide | What it covers |
-|-------|---------------|
-| [App Configuration Files](app-manifest.md) | Full field-by-field reference for both JSON files |
-| [Executor Model](executor.md) | Building `executor.umd.js` — SEO, LLM content, config mutations |
-| [Deep Link Discovery](deep-link-discovery.md) | `linkable` — static and dynamic navigable states |
-| [AI Guide Template](ai-guide-template.md) | Starter template for `ai-guide.md` |
-| [AI & Chat Completions](ai.md) | `SL.ai` — used in `contentHints` auto-generation |