@proveanything/smartlinks 2.0.58 → 2.0.62

package/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/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/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.

package/docs/integrations.md

@@ -19,6 +19,25 @@ Provider-specific logic (a provider's payload format, its API, its connect form)
 **connector app**, not in the engine: see **[Connectors](connectors.md)**. A flow uses one with
 `config.connector = { appId }`.
 
+**Reliability.** A record that fails is retried on its own with exponential backoff (honouring the
+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`).
+
+**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
 at rest and resolved server-side only, at execution.

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`)
 
 ---