@proveanything/smartlinks 2.0.60 → 2.0.63

package/dist/types/integrations.d.ts

@@ -93,6 +93,103 @@ export interface FailedRecord {
     lastError?: string | null;
     updatedAt?: string;
 }
+/** How one flow is doing (GET /integrations/flows/:id/health). */
+export interface FlowHealth {
+    flowId: string;
+    name: string;
+    direction: FlowDirection;
+    status: FlowStatus;
+    /** Set while the flow has paused itself (its destination / provider keeps failing). */
+    paused: {
+        since: string;
+        nextCheckAt: string | null;
+        reason: string | null;
+    } | null;
+    /** The sweep in progress, if any (progress counts grow as it goes). */
+    running: {
+        runId: string;
+        startedAt: string;
+        heartbeatAt: string | null;
+        trigger: string;
+        progress: Record<string, number | string>;
+    } | null;
+    lastRun: {
+        at: string | null;
+        status: string | null;
+        error: string | null;
+    };
+    last24h: {
+        runs: number;
+        byStatus: Record<string, number>;
+        records: number;
+        /** Outbound: sent; inbound: created + updated. */
+        delivered: number;
+        failed: number;
+        /** failed / records, 0..1 */
+        failureRate: number;
+        avgRunMs: number | null;
+        recordsPerSecond: number | null;
+    };
+    /** Inbound: landed / waiting / oldestWaitingSince / retrying / retriesDue / gaveUp. Outbound: delivered / retrying / retriesDue / gaveUp. */
+    backlog: {
+        landed?: number;
+        waiting?: number;
+        oldestWaitingSince?: string | null;
+        delivered?: number;
+        retrying: number;
+        retriesDue: number;
+        gaveUp: number;
+    };
+}
+/** Every flow in the collection (GET /integrations/health). */
+export interface IntegrationHealth {
+    flows: FlowHealth[];
+    summary: {
+        flows: number;
+        active: number;
+        paused: number;
+        running: number;
+        failedLast24h: number;
+        gaveUp: number;
+    };
+}
+/** Where a product's data came from and where it went (GET /integrations/lineage/product/:id). */
+export interface ProductLineage {
+    productId: string;
+    sources: Array<{
+        /** 'connector:<appId>' or 'flow:<flowId>' */
+        source: string;
+        /** The provider's id for the record. */
+        externalId: string;
+        flow: {
+            id: string;
+            name: string;
+        };
+        fetchedAt: string;
+        processedAt: string | null;
+        processedRunId: string | null;
+        status: string;
+        lastError: string | null;
+        /** Written with the flow's current mapping and settings (false: an earlier version). */
+        currentMapping: boolean;
+        mapping: FieldMapping[];
+        /** The provider record as received (with `payload: true`). */
+        payload?: unknown;
+    }>;
+    deliveries: Array<{
+        flow: {
+            id: string;
+            name: string;
+        };
+        status: 'sent' | 'failed' | 'dead';
+        lastSentAt: string | null;
+        attempts: number;
+        nextAttemptAt: string | null;
+        lastError: string | null;
+        lastRunId: string | null;
+    }>;
+    recentRuns: FlowRun[];
+}
 export interface FailedRecordList {
     direction: FlowDirection;
     items: FailedRecord[];

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.60  |  Generated: 2026-10-13T16:25:55.817Z
+Version: 2.0.63  |  Generated: 2026-10-14T09:04:47.371Z
 
 This is a concise summary of all available API functions and types.
 
@@ -135,6 +135,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **serialNumber** - Assign, lookup, and manage serial numbers across scopes.
 
 — Other —
+- **adminCards** - Functions for adminCards operations
 - **analytics** - Functions for analytics operations
 - **async** - Functions for async operations
 - **attestation** - Functions for attestation operations
@@ -474,6 +475,112 @@ Examples include:
 
 ## Types
 
+### adminCards
+
+**AdminCardRefresh** (interface)
+```typescript
+interface AdminCardRefresh {
+  on?: AdminCardRefreshOn[]
+  maxAge?: number | string
+}
+```
+
+**AdminCardDeclaration** (interface)
+```typescript
+interface AdminCardDeclaration {
+  id: string
+  title: string
+  description?: string
+  kind?: 'data' | 'component'
+  function?: string
+  component?: string
+  sizes?: AdminCardSize[]
+  priority?: number
+  levels?: Array<'collection'>
+  refresh?: AdminCardRefresh
+}
+```
+
+**AppManifestAdminCards** (interface)
+```typescript
+interface AppManifestAdminCards {
+  cards: AdminCardDeclaration[]
+  files?: {
+  js: { umd: string; esm?: string }
+  css?: string
+  }
+}
+```
+
+**AdminCardAction** (interface)
+```typescript
+interface AdminCardAction {
+  label: string
+  path?: string
+  url?: string
+}
+```
+
+**AdminCardPayload** (interface)
+```typescript
+interface AdminCardPayload {
+  title?: string
+  value?: number | string
+  label?: string
+  unit?: string
+  trend?: { direction: 'up' | 'down' | 'flat'; label?: string; good?: boolean }
+  status?: { tone: 'ok' | 'attention' | 'neutral' | 'error'; text: string }
+  progress?: { done: number; total: number; label?: string }
+  items?: Array<{ title: string; subtitle?: string; meta?: string; path?: string }>
+  todo?: Array<{ text: string; action?: AdminCardAction }>
+  actions?: AdminCardAction[]
+  empty?: { text: string; action?: AdminCardAction }
+}
+```
+
+**AdminCard** (interface)
+```typescript
+interface AdminCard {
+  key: string
+  appId: string
+  cardId: string
+  title: string
+  description?: string
+  kind: 'data' | 'component'
+  sizes: AdminCardSize[]
+  size: AdminCardSize
+  priority: number
+  state: AdminCardState
+  payload: AdminCardPayload | null
+  computedAt: number | null
+  error?: string
+  component?: { name: string; files: NonNullable<AppManifestAdminCards['files']> }
+}
+```
+
+**StudioHomeLayout** (interface)
+```typescript
+interface StudioHomeLayout {
+  version: 1
+  cards: Array<{ key: string; size?: AdminCardSize; hidden?: boolean }>
+}
+```
+
+**AdminCardsResponse** (interface)
+```typescript
+interface AdminCardsResponse {
+  cards: AdminCard[]
+  hidden: AdminCard[]
+  layout: StudioHomeLayout | null
+}
+```
+
+**AdminCardSize** = `'small' | 'medium' | 'wide' | 'full'`
+
+**AdminCardRefreshOn** = ``
+
+**AdminCardState** = ``
+
 ### ai
 
 **ContentPart** (interface)
@@ -2852,6 +2959,7 @@ interface AppManifest {
   executor?: AppManifestExecutor;
   functions?: AppManifestFunctions;
   realtime?: { channels: RealtimeChannelDeclaration[] };
+  adminCards?: AppManifestAdminCards;
   data?: AppDataDeclaration;
   headless?: AppHeadlessDeclaration;
   connector?: AppConnectorDeclaration;
@@ -7138,6 +7246,76 @@ interface FailedRecord {
 }
 ```
 
+**FlowHealth** (interface)
+```typescript
+interface FlowHealth {
+  flowId: string
+  name: string
+  direction: FlowDirection
+  status: FlowStatus
+  paused: { since: string; nextCheckAt: string | null; reason: string | null } | null
+  running: { runId: string; startedAt: string; heartbeatAt: string | null; trigger: string; progress: Record<string, number | string> } | null
+  lastRun: { at: string | null; status: string | null; error: string | null }
+  last24h: {
+  runs: number
+  byStatus: Record<string, number>
+  records: number
+  delivered: number
+  failed: number
+  failureRate: number
+  avgRunMs: number | null
+  recordsPerSecond: number | null
+  }
+  backlog: {
+  landed?: number
+  waiting?: number
+  oldestWaitingSince?: string | null
+  delivered?: number
+  retrying: number
+  retriesDue: number
+  gaveUp: number
+  }
+}
+```
+
+**IntegrationHealth** (interface)
+```typescript
+interface IntegrationHealth {
+  flows: FlowHealth[]
+  summary: { flows: number; active: number; paused: number; running: number; failedLast24h: number; gaveUp: number }
+}
+```
+
+**ProductLineage** (interface)
+```typescript
+interface ProductLineage {
+  productId: string
+  sources: Array<{
+  source: string
+  externalId: string
+  flow: { id: string; name: string }
+  fetchedAt: string
+  processedAt: string | null
+  processedRunId: string | null
+  status: string
+  lastError: string | null
+  currentMapping: boolean
+  mapping: FieldMapping[]
+  payload?: unknown
+  }>
+  deliveries: Array<{
+  flow: { id: string; name: string }
+  status: 'sent' | 'failed' | 'dead'
+  lastSentAt: string | null
+  attempts: number
+  nextAttemptAt: string | null
+  lastError: string | null
+  lastRunId: string | null
+  }>
+  recentRuns: FlowRun[]
+}
+```
+
 **FailedRecordList** (interface)
 ```typescript
 interface FailedRecordList {
@@ -10320,6 +10498,17 @@ interface Gs1DigitalLinkParams {
 
 ## API Functions
 
+### adminCards
+
+**list**(collectionId: string) → `Promise<AdminCardsResponse>`
+The collection's dashboard: every card, in display order, with its cached payload and how fresh it is (`state`). Never waits on slow cards — those come back `stale` / `pending` and arrive later as a realtime `cards` change.
+
+**refresh**(collectionId: string, appId: string, cardId: string) → `Promise<AdminCard>`
+Recompute one card now (the card's "refresh" button). Rate-limited per card.
+
+**saveLayout**(collectionId: string, layout: StudioHomeLayout) → `Promise<StudioHomeLayout>`
+Save the collection's dashboard layout (order, sizes, hidden cards) — every admin sees it.
+
 ### agent
 
 **run**(collectionId: string, body: AgentRunRequest) → `Promise<AgentRunResult>`
@@ -11749,6 +11938,15 @@ A flow's failed / dead records. GET /integrations/flows/:id/failed
 **retryFailed**(collectionId: string, flowId: string, ids?: string[]) → `Promise<`
 Retry failed / dead records now (all of them when `ids` is omitted). POST /integrations/flows/:id/failed/retry
 
+**getHealth**(collectionId: string) → `Promise<IntegrationHealth>`
+Every flow at a glance: paused?, running?, last 24h, backlog. GET /integrations/health
+
+**getFlowHealth**(collectionId: string, flowId: string) → `Promise<FlowHealth>`
+One flow's health. GET /integrations/flows/:id/health
+
+**getProductLineage**(collectionId: string, productId: string, opts: { payload?: boolean } = {}) → `Promise<ProductLineage>`
+Where a product's data came from (the provider record, when it was fetched and imported, by which run, with the current mapping or an older one) and where it went (each outbound flow's last delivery). `payload: true` includes the provider records as received. GET /integrations/lineage/product/:productId
+
 **resumeFlow**(collectionId: string, flowId: string) → `Promise<`
 Resume a flow that paused itself (circuit open): held records go out now. POST /integrations/flows/:id/resume
 

package/docs/admin-cards.md

@@ -0,0 +1,187 @@
+# Admin cards
+
+Cards your app adds to a collection's **dashboard** in SmartLinks Studio — the first thing an admin
+sees. "3 new enquiries", "2 questions waiting for an answer", "Your site is live", with a button
+straight into your app's admin.
+
+- **Data cards** (the default, any app): you declare the card and an **admin server function** that
+  returns a small JSON payload. Studio draws it — a consistent look, no app code in Studio.
+- **Component cards** (first-party and approved publishers): a React component from your app's
+  `adminCards` bundle, for things a data card can't show (charts, inline edits). It gets the same
+  cached payload as its `data` prop.
+
+## Fast by construction
+
+Dashboards that load 20 widgets × 50 calls on every visit are the thing to avoid. So:
+
+1. **One request per dashboard.** Studio calls `adminCards.list(collectionId)` once and gets every
+   card back — never one request per card.
+2. **Served from a cache.** A card's last payload is kept and shown immediately. On a warm dashboard
+   **no card function runs at all.**
+3. **Recomputed only when its data changed.** You declare what the card depends on in
+   `refresh.on`; when one of those changes (any write through SmartLinks), the card is marked stale and
+   recomputed **in the background** the next time someone looks. The new payload arrives over
+   SmartLinks Realtime as a `cards` change. Your FAQ count is recounted when an FAQ changes, not on
+   every login.
+4. **Budgets.** A card function gets about **2 seconds** and **8KB** of output. A slow or failing card
+   shows its last payload marked as updating / couldn't refresh — it never holds up the page.
+
+Keep card functions to one cheap query. If a number is expensive (a big aggregate), keep it up to date
+yourself as data changes and have the card function read it.
+
+## Declare a card
+
+In `app.manifest.json`:
+
+```json
+"adminCards": {
+  "cards": [
+    {
+      "id": "unanswered",
+      "title": "FAQ",
+      "description": "Questions waiting for an answer",
+      "function": "cardUnanswered",
+      "sizes": ["small", "medium"],
+      "priority": 40,
+      "refresh": { "on": ["records:question"], "maxAge": "1d" }
+    }
+  ]
+},
+"functions": {
+  "files": { "js": { "umd": "functions.umd.js", "esm": "functions.es.js" } },
+  "definitions": [
+    { "name": "cardUnanswered", "trigger": { "type": "http" }, "visibility": "admin",
+      "authority": "collection", "capabilities": ["sl:records:read"] }
+  ]
+}
+```
+
+| Field | |
+|---|---|
+| `id` | Unique in the app (letters, digits, `-`, `_`; up to 40). |
+| `title` | The card's heading (the payload can override it). |
+| `description` | One line for the "add a card" picker. |
+| `kind` | `data` (default) or `component`. |
+| `function` | The **admin** http server function returning the payload. Required for data cards. |
+| `component` | Component cards: the export name in the `adminCards` bundle. |
+| `sizes` | `small` (3/12), `medium` (6/12), `wide` (8/12), `full` (12/12). First = default. Default `["medium"]`. |
+| `priority` | Lower first, until the collection arranges its dashboard. Default 100. |
+| `refresh.on` | What the data depends on — see below. |
+| `refresh.maxAge` | Recompute at least this often: seconds, or `"30m"`, `"6h"`, `"2d"`. Default 6h, minimum 1m. |
+
+### `refresh.on`
+
+| Value | Changes when |
+|---|---|
+| `records` | Any of **this app's** records is created, updated or deleted |
+| `records:<type>` | This app's records of that `recordType` |
+| `products` | A product in the collection |
+| `proofs` | A proof |
+| `assets` | An asset |
+| `apps` | The collection's installed apps |
+| `collection` | The collection itself |
+| `settings` / `settings:<group>` | Any settings group / that one |
+
+Data that changes without an event (visit counts, "due this week") — use `maxAge` only.
+
+## Return the payload
+
+The function returns an `AdminCardPayload` — every field optional; return what the card needs:
+
+```ts
+import type { AdminCardPayload } from '@proveanything/smartlinks'
+
+export async function cardUnanswered(ctx): Promise<AdminCardPayload> {
+  // One query: the newest 3 open questions, plus the total.
+  const open = await ctx.sl.appRecords.query({ recordType: 'question', status: 'open', limit: 3, sort: '-createdAt' })
+  const total = open.pagination.total ?? open.data.length
+  if (!total) return { value: 0, label: 'questions waiting', status: { tone: 'ok', text: 'All answered' } }
+  return {
+    value: total,
+    label: total === 1 ? 'question waiting' : 'questions waiting',
+    status: { tone: 'attention', text: 'Answer them so they show on your site' },
+    items: open.data.map((q) => ({ title: q.data.question, meta: q.createdAt, path: `/questions/${q.id}` })),
+    todo: [{ text: `Answer ${total} FAQ question${total === 1 ? '' : 's'}`, action: { label: 'Answer', path: '/questions?status=open' } }],
+    actions: [{ label: 'Open FAQ', path: '/' }],
+  }
+}
+```
+
+| Field | Shown as |
+|---|---|
+| `title` | Heading (overrides the declared title) |
+| `value`, `label`, `unit` | The big number/value and its caption |
+| `trend` | `{ direction: 'up'\|'down'\|'flat', label?, good? }` — `good` picks the colour |
+| `status` | `{ tone: 'ok'\|'attention'\|'neutral'\|'error', text }` — `attention`/`error` also go to the To do strip |
+| `progress` | `{ done, total, label? }` — a progress bar |
+| `items` | Up to 5 rows `{ title, subtitle?, meta?, path? }` |
+| `todo` | `[{ text, action? }]` — collected into the dashboard's To do strip |
+| `actions` | Up to 2 buttons `{ label, path? \| url? }` — `path` opens your app's admin at that path |
+| `empty` | `{ text, action? }` — shown instead of the body when there's nothing yet |
+
+No HTML, no styling: Studio draws every card the same way, in the collection's theme.
+
+Use **`authority: "collection"`** with read capabilities: a card's payload is cached and shown to every
+admin of the collection, so it shouldn't depend on who happened to load it.
+
+## The dashboard and its layout
+
+The layout belongs to the **collection** — every admin sees the same dashboard, set up once (by the
+sign-up wizard, or an admin arranging it). It's the `studioHome` settings group:
+
+```json
+{ "version": 1, "cards": [ { "key": "faq:unanswered", "size": "small" }, { "key": "platform:products", "hidden": true } ] }
+```
+
+Cards not in the layout follow by `priority`, so a newly installed app's cards appear on their own;
+an uninstalled app's cards drop out. Save it with `adminCards.saveLayout`.
+
+## Reading the dashboard (hosts)
+
+```ts
+import { adminCards, realtime } from '@proveanything/smartlinks'
+
+const { cards, hidden, layout } = await adminCards.list(collectionId)   // display order
+realtime.onChange({ collectionId }, { type: 'cards' }, () => reload())  // a card was recomputed
+await adminCards.refresh(collectionId, 'faq', 'unanswered')             // the card's refresh button
+```
+
+Draw them with the SDK's renderer, so every host (Studio, Forge's preview) shows a card the same
+way. Pass your React in; the SDK doesn't bundle React:
+
+```tsx
+import React from 'react'
+import { createAdminCardViews } from '@proveanything/smartlinks'
+const { AdminCardView, AdminCardGrid, AdminCardTodo } = createAdminCardViews(React)
+
+<AdminCardTodo cards={cards} onAction={open} />
+<AdminCardGrid>
+  {cards.map((c) => <AdminCardView key={c.key} card={c} onAction={open} onRefresh={refresh} />)}
+</AdminCardGrid>
+```
+
+`onAction(action, card)`: `action.path` opens the card's app admin at that path; `action.url` opens a
+link. Colours follow the SDK theme tokens (`--sl-color-*`); override with `--slc-bg`, `--slc-fg`,
+`--slc-muted`, `--slc-border`, `--slc-accent`, `--slc-ok`, `--slc-attention`, `--slc-error`,
+`--slc-radius`. `normaliseAdminCardPayload(raw)` trims a raw function result exactly as the server
+does (for previews).
+
+Each card has `state`: `fresh`, `stale` (last payload, a newer one is coming), `pending` (first
+computation still running) or `error` (last attempt failed; `payload` is the last good one).
+
+## Component cards
+
+For first-party and approved publishers. Ship an `adminCards` bundle (built like widgets) and declare
+it:
+
+```json
+"adminCards": {
+  "files": { "js": { "umd": "admin-cards.umd.js", "esm": "admin-cards.esm.js" }, "css": "admin-cards.css" },
+  "cards": [ { "id": "visits", "title": "Visitors", "kind": "component", "component": "VisitsCard",
+               "function": "cardVisits", "sizes": ["wide", "full"], "refresh": { "maxAge": "1h" } } ]
+}
+```
+
+The component gets `{ collectionId, appId, size, data, SL, openApp(path?), lang }`. Draw from `data`
+(the cached payload of its `function`) — don't fetch on mount; that's what keeps the dashboard fast.
+`smartlinks-doctor` checks your cards.

package/docs/integrations.md

@@ -23,9 +23,20 @@ Provider-specific logic (a provider's payload format, its API, its connect form)
 destination's `Retry-After`); a permanent failure (most 4xx) or one out of attempts is **dead** and
 waits in `integrations.listFailed` for `integrations.retryFailed`. A destination that keeps failing
 **pauses the flow automatically** (`flow.circuitOpenedAt`): edits are held, small probes check for
-recovery, and it resumes on its own (or with `integrations.resumeFlow`). Every product and record
-change is recorded durably before it's dispatched, so an edit can't be missed; scheduled sweeps are
-the reconciliation net.
+recovery, and it resumes on its own (or with `integrations.resumeFlow`).
+
+**Observability.** `integrations.getHealth` shows every flow at a glance (paused?, running?, last 24h,
+backlog); `getFlowHealth` one flow; `getProductLineage` where a product's data came from and where it
+went. Every run and every record is kept in BigQuery (`analytics.integration_runs`,
+`analytics.integration_run_items`); the API's run history is a 7-day window. Outbound sends carry
+`X-SmartLinks-Run` (the run) and an `Idempotency-Key` (same record, same content → same key).
+
+**Change capture.** Every product and record write is captured where it's saved, whatever made it (the
+admin, an import, a server function). A product change *wakes* each subscribed outbound flow, which then
+sweeps every product changed since its last sweep (deletions included). A burst of edits, such as a big
+import, is one sweep, not one send per product. A reconciliation sweep every 15 minutes catches anything
+a wake missed. Events that need one call each (app functions, flows on record events) are recorded
+durably and retried until they're delivered.
 
 Credentials are **never** stored on the flow. The connection holds an opaque
 `credentialRef` into the **sealed-secret store** (`secrets` namespace); the value is sealed

package/docs/overview.md

@@ -69,6 +69,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Portal Request Action** | `docs/portal-request-action.md` | Triggering portal built-in actions (__qrScanner, __share, __logout, etc.) from sub-apps |
 | **Interactions** | `docs/interactions.md` | Business events, outcomes, voting, competitions, and journey triggers |
 | **App Config Files** | `docs/app-manifest.md` | Full field-by-field reference for both JSON config files |
+| **Admin cards** | `docs/admin-cards.md` | Cards on the collection's dashboard in Studio: declare a card + an admin function returning its data; cached, refreshed only when its data changes |
 | **Realtime** | `docs/realtime.md` | Live updates: change events (refetch when something changes) and declared app channels (a draw, a status) — no provider library or keys |
 | **Liquid Templates** | `docs/liquid-templates.md` | Dynamic content rendering with LiquidJS |
 | **Iframe Responder** | `docs/iframe-responder.md` | Iframe communication and proxy mode internals |
@@ -359,6 +360,7 @@ The SmartLinks SDK is organised into namespaces. See `docs/API_SUMMARY.md` for t
 - `contact` — Customer contact management
 - `comms` / `broadcasts` — Notifications and campaigns
 - `asset` — File/image uploads
+- `adminCards` — the collection's dashboard: `list`, `refresh`, `saveLayout` (see `docs/admin-cards.md`)
 - `realtime` — SmartLinks Realtime: `onChange`, `channel`, `onMine` (see `docs/realtime.md`)
 
 ---