@proveanything/smartlinks 2.0.58 → 2.0.62

package/README.md

@@ -28,6 +28,7 @@ If you're new to the SDK, this is the easiest path:
 - [docs/translations.md](docs/translations.md) — runtime translation lookup, browser-side caching, and translation admin flows
 - [docs/widgets.md](docs/widgets.md) — embeddable React components
 - [docs/realtime.md](docs/realtime.md) — subscriptions and live updates
+- [docs/admin-cards.md](docs/admin-cards.md) — cards on the collection's Studio dashboard
 - [docs/iframe-responder.md](docs/iframe-responder.md) — iframe integration and parent/child messaging
 - [docs/utils.md](docs/utils.md) — helper utilities and portal path generation
 

package/dist/api/adminCards.d.ts

@@ -0,0 +1,13 @@
+import type { AdminCard, AdminCardsResponse, StudioHomeLayout } from "../types/adminCards.js";
+export declare namespace adminCards {
+    /**
+     * 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.
+     */
+    function list(collectionId: string): Promise<AdminCardsResponse>;
+    /** Recompute one card now (the card's "refresh" button). Rate-limited per card. */
+    function refresh(collectionId: string, appId: string, cardId: string): Promise<AdminCard>;
+    /** Save the collection's dashboard layout (order, sizes, hidden cards) — every admin sees it. */
+    function saveLayout(collectionId: string, layout: StudioHomeLayout): Promise<StudioHomeLayout>;
+}

package/dist/api/adminCards.js

@@ -0,0 +1,36 @@
+// src/api/adminCards.ts
+//
+// Admin cards — a collection's dashboard, built from cards its installed apps contribute (plus the
+// platform's own: products, contacts, visitors). See docs/admin-cards.md.
+//
+// One call loads the whole dashboard, served from a cache; stale cards are recomputed in the
+// background and announced over SmartLinks Realtime as a `cards` change event:
+//
+//   const { cards } = await adminCards.list(collectionId)
+//   realtime.onChange({ collectionId }, { type: 'cards' }, () => reload())
+//
+// Endpoints: /admin/collection/:collectionId/cards
+import { request, post, put } from "../http.js";
+const base = (collectionId) => `/admin/collection/${encodeURIComponent(collectionId)}/cards`;
+export var adminCards;
+(function (adminCards) {
+    /**
+     * 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.
+     */
+    async function list(collectionId) {
+        return request(base(collectionId));
+    }
+    adminCards.list = list;
+    /** Recompute one card now (the card's "refresh" button). Rate-limited per card. */
+    async function refresh(collectionId, appId, cardId) {
+        return post(`${base(collectionId)}/${encodeURIComponent(appId)}/${encodeURIComponent(cardId)}/refresh`, {});
+    }
+    adminCards.refresh = refresh;
+    /** Save the collection's dashboard layout (order, sizes, hidden cards) — every admin sees it. */
+    async function saveLayout(collectionId, layout) {
+        return put(`${base(collectionId)}/layout`, layout);
+    }
+    adminCards.saveLayout = saveLayout;
+})(adminCards || (adminCards = {}));

package/dist/api/index.d.ts

@@ -30,6 +30,7 @@ export { analytics } from "./analytics.js";
 export { functions } from "./functions.js";
 export { location } from "./location.js";
 export * as realtime from "./realtime.js";
+export { adminCards } from "./adminCards.js";
 export { tags } from "./tags.js";
 export { order } from "./order.js";
 export { app } from "./appObjects.js";

package/dist/api/index.js

@@ -33,6 +33,7 @@ export { functions } from "./functions.js";
 export { location } from "./location.js";
 import * as realtime_1 from "./realtime.js";
 export { realtime_1 as realtime };
+export { adminCards } from "./adminCards.js";
 export { tags } from "./tags.js";
 export { order } from "./order.js";
 export { app } from "./appObjects.js";

package/dist/api/integrations.d.ts

@@ -1,4 +1,4 @@
-import type { IntegrationFlow, CreateFlowInput, UpdateFlowInput, ListFlowsQuery, FlowList, RunFlowInput, RunFlowResult, RunFlowSummary, RunFlowEnqueued, RecordTypesResponse, FlowRun, ListRunsQuery, RunList, ListRunItemsQuery, RunItemList, LoggingWindow, SetLoggingInput, InstalledConnector, SaveConnectorInstallationInput, ConnectorConsoleStep } from "../types/integrations.js";
+import type { IntegrationFlow, CreateFlowInput, UpdateFlowInput, ListFlowsQuery, FlowList, RunFlowInput, RunFlowResult, RunFlowSummary, RunFlowEnqueued, RecordTypesResponse, FlowRun, ListRunsQuery, RunList, ListRunItemsQuery, RunItemList, LoggingWindow, SetLoggingInput, InstalledConnector, SaveConnectorInstallationInput, ConnectorConsoleStep, FailedRecordList, FlowHealth, IntegrationHealth, ProductLineage } from "../types/integrations.js";
 export declare namespace integrations {
     /** List flows in a collection. GET /integrations/flows */
     function listFlows(collectionId: string, query?: ListFlowsQuery): Promise<FlowList>;
@@ -53,6 +53,33 @@ export declare namespace integrations {
     function setLogging(collectionId: string, connectionId: string, input?: SetLoggingInput): Promise<{
         window: LoggingWindow;
     }>;
+    /** A flow's failed / dead records. GET /integrations/flows/:id/failed */
+    function listFailed(collectionId: string, flowId: string, query?: {
+        status?: 'failed' | 'dead';
+        limit?: number;
+        cursor?: string;
+    }): Promise<FailedRecordList>;
+    /** Retry failed / dead records now (all of them when `ids` is omitted). POST /integrations/flows/:id/failed/retry */
+    function retryFailed(collectionId: string, flowId: string, ids?: string[]): Promise<{
+        retrying: number;
+    }>;
+    /** Every flow at a glance: paused?, running?, last 24h, backlog. GET /integrations/health */
+    function getHealth(collectionId: string): Promise<IntegrationHealth>;
+    /** One flow's health. GET /integrations/flows/:id/health */
+    function getFlowHealth(collectionId: string, flowId: string): Promise<FlowHealth>;
+    /**
+     * 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
+     */
+    function getProductLineage(collectionId: string, productId: string, opts?: {
+        payload?: boolean;
+    }): Promise<ProductLineage>;
+    /** Resume a flow that paused itself (circuit open): held records go out now. POST /integrations/flows/:id/resume */
+    function resumeFlow(collectionId: string, flowId: string): Promise<{
+        resumed: boolean;
+    }>;
     /** Cancel enhanced logging now. DELETE /integrations/logging/:connectionId */
     function cancelLogging(collectionId: string, connectionId: string): Promise<{
         canceled: boolean;

package/dist/api/integrations.js

@@ -130,6 +130,45 @@ export var integrations;
         return post(`/admin/collection/${enc(collectionId)}/integrations/logging/${enc(connectionId)}`, input);
     }
     integrations.setLogging = setLogging;
+    // --- Failed records + resume -----------------------------------------------
+    // A failed record is retried on its own with backoff; a permanent failure, or one out of attempts, is
+    // 'dead' and waits for someone to retry it (or for the record to change).
+    /** A flow's failed / dead records. GET /integrations/flows/:id/failed */
+    async function listFailed(collectionId, flowId, query = {}) {
+        return request(`${base(collectionId)}/${enc(flowId)}/failed${encodeQuery(query)}`);
+    }
+    integrations.listFailed = listFailed;
+    /** Retry failed / dead records now (all of them when `ids` is omitted). POST /integrations/flows/:id/failed/retry */
+    async function retryFailed(collectionId, flowId, ids) {
+        return post(`${base(collectionId)}/${enc(flowId)}/failed/retry`, ids ? { ids } : {});
+    }
+    integrations.retryFailed = retryFailed;
+    // --- Health + lineage ---------------------------------------------------------
+    /** Every flow at a glance: paused?, running?, last 24h, backlog. GET /integrations/health */
+    async function getHealth(collectionId) {
+        return request(`/admin/collection/${enc(collectionId)}/integrations/health`);
+    }
+    integrations.getHealth = getHealth;
+    /** One flow's health. GET /integrations/flows/:id/health */
+    async function getFlowHealth(collectionId, flowId) {
+        return request(`${base(collectionId)}/${enc(flowId)}/health`);
+    }
+    integrations.getFlowHealth = getFlowHealth;
+    /**
+     * 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
+     */
+    async function getProductLineage(collectionId, productId, opts = {}) {
+        return request(`/admin/collection/${enc(collectionId)}/integrations/lineage/product/${enc(productId)}${opts.payload ? '?payload=1' : ''}`);
+    }
+    integrations.getProductLineage = getProductLineage;
+    /** Resume a flow that paused itself (circuit open): held records go out now. POST /integrations/flows/:id/resume */
+    async function resumeFlow(collectionId, flowId) {
+        return post(`${base(collectionId)}/${enc(flowId)}/resume`, {});
+    }
+    integrations.resumeFlow = resumeFlow;
     /** Cancel enhanced logging now. DELETE /integrations/logging/:connectionId */
     async function cancelLogging(collectionId, connectionId) {
         return del(`/admin/collection/${enc(collectionId)}/integrations/logging/${enc(connectionId)}`);

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.58  |  Generated: 2026-10-13T14:08:01.791Z
+Version: 2.0.62  |  Generated: 2026-10-13T20:05:22.753Z
 
 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;
@@ -2915,6 +3023,8 @@ interface AppConnectorDeclaration {
   }
   panels?: ConnectorPanel[]
   aiGuide?: string
+  recordId?: string
+  limits?: { requestsPerSecond?: number }
 }
 ```
 
@@ -3008,7 +3118,15 @@ interface ConnectorSendInput {
 **ConnectorSendResult** (interface)
 ```typescript
 interface ConnectorSendResult {
-  results: Array<{ index: number; ok: boolean; status?: number; error?: string; externalId?: string }>
+  results: Array<{
+  index: number
+  ok: boolean
+  status?: number
+  error?: string
+  externalId?: string
+  retryable?: boolean
+  retryAfterSeconds?: number
+  }>
 }
 ```
 
@@ -7108,6 +7226,102 @@ interface IntegrationFlow {
   lastPollAt?: string | null
   lastCursor?: string | null
   totalSynced?: number | null
+  circuitOpenedAt?: string | null
+  circuitProbeAt?: string | null
+  circuitReason?: string | null
+}
+```
+
+**FailedRecord** (interface)
+```typescript
+interface FailedRecord {
+  id: string
+  entityId?: string | null
+  externalId?: string
+  status: 'failed' | 'dead'
+  attempts: number
+  nextAttemptAt?: string | null
+  lastError?: string | null
+  updatedAt?: string
+}
+```
+
+**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 {
+  direction: FlowDirection
+  items: FailedRecord[]
+  nextCursor: string | null
 }
 ```
 
@@ -7161,6 +7375,7 @@ interface RunFlowSummary {
   created?: number
   updated?: number
   skipped?: number
+  held?: number
   status: RunStatus
   runId?: string
 }
@@ -10283,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>`
@@ -11704,6 +11930,26 @@ Is enhanced logging active for a connection? GET /integrations/logging/:connecti
 **setLogging**(collectionId: string, connectionId: string, input: SetLoggingInput = {}) → `Promise<`
 Enable enhanced logging. POST /integrations/logging/:connectionId (omit ttlMinutes = until cancelled)
 
+**listFailed**(collectionId: string,
+    flowId: string,
+    query: { status?: 'failed' | 'dead'; limit?: number; cursor?: string } = {}) → `Promise<FailedRecordList>`
+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
+
 **cancelLogging**(collectionId: string, connectionId: string) → `Promise<`
 Cancel enhanced logging now. DELETE /integrations/logging/:connectionId
 

package/dist/docs/admin-cards.md

@@ -0,0 +1,167 @@
+# 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
+```
+
+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/dist/docs/connectors.md

@@ -90,6 +90,8 @@ Types: `AppConnectorDeclaration` and friends in `@proveanything/smartlinks` (`sr
 | `functions` | Which of this app's server functions implement each step (below). Fill in only what applies. |
 | `panels[]` | Provider-specific screens the console mounts (an API explorer, a status page). |
 | `aiGuide` | A guide the mapping assistant reads: the provider's quirks, required fields, good defaults. |
+| `recordId` | Path of the provider's own id in a fetched record (e.g. `gtin`). Inbound records are landed and matched by it, so a re-import updates the same product instead of creating another. Default `id`; a flow can override it (`config.upsert.externalIdPath`). |
+| `limits` | `{ requestsPerSecond }` toward the provider, enforced across every SmartLinks worker. |
 
 ---
 
@@ -112,9 +114,12 @@ declare the provider's hosts (`network:<host>`) and the secrets it reads (`secre
 | `send` | Every outbound run | `ConnectorSendInput` `{ installation, payloads }` | `ConnectorSendResult` `{ results: [{ index, ok, status, error, externalId }] }` |
 
 **How a run flows:**
-- **Inbound:** `fetch` (paged) → `shape` → core maps the documents with the flow's mapping → upsert.
+- **Inbound:** `fetch` (paged; every record is landed as received) → `shape` → core maps the documents
+  with the flow's mapping → upsert, matched by `recordId`. Unchanged records aren't processed again; a
+  changed flow configuration replays the landed records without fetching.
 - **Outbound:** gather the SmartLinks records → core maps them to the provider's fields → `serialize`
-  → `send` (or a generic transport).
+  → `send` (or a generic transport). A record identical to its last successful delivery isn't sent again.
+- Large runs are processed in short slices that resume after an interruption; there's no record cap.
 
 **What happens when a step is left out:**
 - **No `shape`:** core maps the provider records as they come.