@proveanything/smartlinks 2.0.60 → 2.0.63

package/dist/openapi.yaml

@@ -4417,6 +4417,65 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/collection/{collectionId}/integrations/health:
+    get:
+      tags:
+        - integrations
+      summary: "Every flow at a glance: paused?, running?, last 24h, backlog."
+      operationId: integrations_getHealth
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/IntegrationHealth"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /admin/collection/{collectionId}/integrations/lineage/product/{productId}:
+    get:
+      tags:
+        - integrations
+      summary: "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)."
+      operationId: integrations_getProductLineage
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: productId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProductLineage"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /admin/collection/{collectionId}/integrations/record-types:
     get:
       tags:
@@ -15474,6 +15533,212 @@ components:
       name: X-API-Key
       description: API key for server-to-server calls
   schemas:
+    AdminCardRefresh:
+      type: object
+      properties:
+        on:
+          type: array
+          items:
+            $ref: "#/components/schemas/AdminCardRefreshOn"
+        maxAge:
+          type: object
+          additionalProperties: true
+    AdminCardDeclaration:
+      type: object
+      properties:
+        id:
+          type: string
+        title:
+          type: string
+        description:
+          type: string
+        kind:
+          type: string
+          enum:
+            - data
+            - component
+        function:
+          type: string
+        component:
+          type: string
+        sizes:
+          type: array
+          items:
+            $ref: "#/components/schemas/AdminCardSize"
+        priority:
+          type: number
+        levels:
+          type: array
+          items:
+            type: string
+            enum:
+              - collection
+        refresh:
+          $ref: "#/components/schemas/AdminCardRefresh"
+      required:
+        - id
+        - title
+    AppManifestAdminCards:
+      type: object
+      properties:
+        cards:
+          type: array
+          items:
+            $ref: "#/components/schemas/AdminCardDeclaration"
+        files:
+          type: object
+          additionalProperties: true
+        js:
+          type: object
+          additionalProperties: true
+        css:
+          type: string
+      required:
+        - cards
+        - js
+    AdminCardAction:
+      type: object
+      properties:
+        label:
+          type: string
+        path:
+          type: string
+        url:
+          type: string
+      required:
+        - label
+    AdminCardPayload:
+      type: object
+      properties:
+        title:
+          type: string
+        value:
+          type: object
+          additionalProperties: true
+        label:
+          type: string
+        unit:
+          type: string
+        trend:
+          type: object
+          additionalProperties: true
+        status:
+          type: object
+          additionalProperties: true
+        progress:
+          type: object
+          additionalProperties: true
+        items:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        todo:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        actions:
+          type: array
+          items:
+            $ref: "#/components/schemas/AdminCardAction"
+        empty:
+          type: object
+          additionalProperties: true
+    AdminCard:
+      type: object
+      properties:
+        key:
+          type: string
+        appId:
+          type: string
+        cardId:
+          type: string
+        title:
+          type: string
+        description:
+          type: string
+        kind:
+          type: string
+          enum:
+            - data
+            - component
+        sizes:
+          type: array
+          items:
+            $ref: "#/components/schemas/AdminCardSize"
+        size:
+          $ref: "#/components/schemas/AdminCardSize"
+        priority:
+          type: number
+        state:
+          $ref: "#/components/schemas/AdminCardState"
+        payload:
+          $ref: "#/components/schemas/AdminCardPayload"
+        computedAt:
+          type: number
+        error:
+          type: string
+        component:
+          type: object
+          additionalProperties: true
+      required:
+        - key
+        - appId
+        - cardId
+        - title
+        - kind
+        - sizes
+        - size
+        - priority
+        - state
+        - payload
+        - computedAt
+    StudioHomeLayout:
+      type: object
+      properties:
+        version:
+          type: object
+          additionalProperties: true
+        cards:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+      required:
+        - version
+        - cards
+    AdminCardsResponse:
+      type: object
+      properties:
+        cards:
+          type: array
+          items:
+            $ref: "#/components/schemas/AdminCard"
+        hidden:
+          type: array
+          items:
+            $ref: "#/components/schemas/AdminCard"
+        layout:
+          $ref: "#/components/schemas/StudioHomeLayout"
+      required:
+        - cards
+        - hidden
+        - layout
+    AdminCardSize:
+      type: string
+      enum:
+        - small
+        - medium
+        - wide
+        - full
+    AdminCardRefreshOn:
+      type: object
+      additionalProperties: true
+    AdminCardState:
+      type: string
+      enum:
+        - fresh
     ContentPart:
       type: object
       properties:
@@ -19648,6 +19913,8 @@ components:
         realtime:
           type: object
           additionalProperties: true
+        adminCards:
+          $ref: "#/components/schemas/AppManifestAdminCards"
         data:
           $ref: "#/components/schemas/AppDataDeclaration"
         headless:
@@ -26345,6 +26612,169 @@ components:
         - id
         - status
         - attempts
+    FlowHealth:
+      type: object
+      properties:
+        flowId:
+          type: string
+        name:
+          type: string
+        direction:
+          $ref: "#/components/schemas/FlowDirection"
+        status:
+          $ref: "#/components/schemas/FlowStatus"
+        paused:
+          type: object
+          additionalProperties: true
+        running:
+          type: object
+          additionalProperties: true
+        lastRun:
+          type: object
+          additionalProperties: true
+        last24h:
+          type: object
+          additionalProperties: true
+        runs:
+          type: number
+        byStatus:
+          type: object
+          additionalProperties:
+            type: number
+        records:
+          type: number
+        delivered:
+          type: number
+        failed:
+          type: number
+        failureRate:
+          type: number
+        avgRunMs:
+          type: number
+        recordsPerSecond:
+          type: number
+        backlog:
+          type: object
+          additionalProperties: true
+        landed:
+          type: number
+        waiting:
+          type: number
+        oldestWaitingSince:
+          type: string
+        retrying:
+          type: number
+        retriesDue:
+          type: number
+        gaveUp:
+          type: number
+      required:
+        - flowId
+        - name
+        - direction
+        - status
+        - paused
+        - running
+        - lastRun
+        - last24h
+        - runs
+        - byStatus
+        - records
+        - delivered
+        - failed
+        - failureRate
+        - avgRunMs
+        - recordsPerSecond
+        - backlog
+        - retrying
+        - retriesDue
+        - gaveUp
+    IntegrationHealth:
+      type: object
+      properties:
+        flows:
+          type: array
+          items:
+            $ref: "#/components/schemas/FlowHealth"
+        summary:
+          type: object
+          additionalProperties: true
+      required:
+        - flows
+        - summary
+    ProductLineage:
+      type: object
+      properties:
+        productId:
+          type: string
+        sources:
+          type: object
+          additionalProperties: true
+        source:
+          type: string
+        externalId:
+          type: string
+        flow:
+          type: object
+          additionalProperties: true
+        fetchedAt:
+          type: string
+        processedAt:
+          type: string
+        processedRunId:
+          type: string
+        status:
+          type: string
+          enum:
+            - sent
+            - failed
+            - dead
+        lastError:
+          type: string
+        currentMapping:
+          type: boolean
+        mapping:
+          type: array
+          items:
+            $ref: "#/components/schemas/FieldMapping"
+        payload: {}
+        deliveries:
+          type: object
+          additionalProperties: true
+        lastSentAt:
+          type: string
+        attempts:
+          type: number
+        nextAttemptAt:
+          type: string
+        lastRunId:
+          type: string
+        recentRuns:
+          type: array
+          items:
+            $ref: "#/components/schemas/FlowRun"
+      required:
+        - productId
+        - sources
+        - source
+        - externalId
+        - flow
+        - fetchedAt
+        - processedAt
+        - processedRunId
+        - status
+        - lastError
+        - currentMapping
+        - mapping
+        - deliveries
+        - flow
+        - status
+        - lastSentAt
+        - attempts
+        - nextAttemptAt
+        - lastError
+        - lastRunId
+        - recentRuns
     FailedRecordList:
       type: object
       properties:

package/dist/types/adminCards.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Admin cards — what an app contributes to a collection's dashboard in Studio (docs/admin-cards.md).
+ *
+ * Two kinds, one contract:
+ * - **data** (the default, any publisher): the app declares the card and an ADMIN server function that
+ *   returns an {@link AdminCardPayload}; Studio draws it. No app code runs in Studio.
+ * - **component** (first-party and approved publishers): a React component from the app's
+ *   `adminCards` bundle, given the same cached payload as its `data` prop.
+ *
+ * Fast by construction: Studio loads every card in ONE request, served from a cache. A card is only
+ * recomputed when something it declares in `refresh.on` changed (or `refresh.maxAge` passed), in the
+ * background, within a time and size budget — so a dashboard never waits on 20 functions.
+ */
+/** Grid widths on a 12-column dashboard: small 3, medium 6, wide 8, full 12. One column on phones. */
+export type AdminCardSize = 'small' | 'medium' | 'wide' | 'full';
+/**
+ * What a card's data depends on — a change of this kind marks it stale. `records` / `records:<type>`
+ * are THIS app's records; the rest are the collection's.
+ */
+export type AdminCardRefreshOn = 'records' | `records:${string}` | 'products' | 'proofs' | 'assets' | 'apps' | 'collection' | 'settings' | `settings:${string}`;
+export interface AdminCardRefresh {
+    /** Recompute when any of these change. Leave out only for data that changes without an event. */
+    on?: AdminCardRefreshOn[];
+    /**
+     * The longest a payload is shown before it's recomputed anyway: seconds, or "30m" / "6h" / "2d".
+     * Default 6h; minimum 1m. Use it for data with no change event (visits, time-based counts).
+     */
+    maxAge?: number | string;
+}
+/** One card an app contributes — `app.manifest.json` → `adminCards.cards[]`. */
+export interface AdminCardDeclaration {
+    /** Unique within the app: letters, digits, `-` and `_`, up to 40. */
+    id: string;
+    /** Shown as the card's heading (the payload may override it). */
+    title: string;
+    /** One line for the "add a card" picker. */
+    description?: string;
+    /** `data` (default) or `component`. */
+    kind?: 'data' | 'component';
+    /**
+     * The ADMIN http server function that returns this card's {@link AdminCardPayload} (a function
+     * declared in `functions.definitions` with `visibility: "admin"`). Required for `data` cards;
+     * optional for `component` cards, whose component then gets the payload as `data`.
+     */
+    function?: string;
+    /** `component` cards: the export name in the `adminCards` bundle. */
+    component?: string;
+    /** Sizes the card supports; the first is its default. Default `["medium"]`. */
+    sizes?: AdminCardSize[];
+    /** Lower comes first when the collection hasn't arranged its dashboard. Default 100. */
+    priority?: number;
+    /** Where the card can appear. Only `collection` (the dashboard) today. */
+    levels?: Array<'collection'>;
+    refresh?: AdminCardRefresh;
+}
+/** `app.manifest.json` → `adminCards`. */
+export interface AppManifestAdminCards {
+    cards: AdminCardDeclaration[];
+    /** The `adminCards` bundle — only when the app has `component` cards. */
+    files?: {
+        js: {
+            umd: string;
+            esm?: string;
+        };
+        css?: string;
+    };
+}
+/** A link from a card into the app's admin (`path`, e.g. "/enquiries?status=new") or elsewhere (`url`). */
+export interface AdminCardAction {
+    label: string;
+    /** A path inside this app's admin. */
+    path?: string;
+    /** An absolute https URL (opens in a new tab). */
+    url?: string;
+}
+/**
+ * What a card's function returns. Every field is optional — return the ones the card needs. Studio
+ * draws them in a fixed, consistent layout; there's no HTML or styling. Max ~8KB as JSON.
+ */
+export interface AdminCardPayload {
+    /** Overrides the declared title (e.g. "3 new enquiries"). */
+    title?: string;
+    /** The headline number or short value. */
+    value?: number | string;
+    /** Shown after/under the value ("enquiries this week"). */
+    label?: string;
+    unit?: string;
+    /** Change against a previous period. `good` says whether this direction is good news (for colour). */
+    trend?: {
+        direction: 'up' | 'down' | 'flat';
+        label?: string;
+        good?: boolean;
+    };
+    /** One status line. `attention` and `error` also surface in the To do strip. */
+    status?: {
+        tone: 'ok' | 'attention' | 'neutral' | 'error';
+        text: string;
+    };
+    /** Setup or completion progress ("4 of 6 steps"). */
+    progress?: {
+        done: number;
+        total: number;
+        label?: string;
+    };
+    /** A short list — at most 5 are shown. */
+    items?: Array<{
+        title: string;
+        subtitle?: string;
+        meta?: string;
+        path?: string;
+    }>;
+    /** Things that need doing — collected into the dashboard's To do strip. */
+    todo?: Array<{
+        text: string;
+        action?: AdminCardAction;
+    }>;
+    /** At most two buttons. */
+    actions?: AdminCardAction[];
+    /** Shown instead of the body when there's nothing yet ("No enquiries yet"). */
+    empty?: {
+        text: string;
+        action?: AdminCardAction;
+    };
+}
+/** How fresh a card's payload is. */
+export type AdminCardState = 
+/** Up to date. */
+'fresh'
+/** The last payload, being recomputed in the background (a newer one arrives by realtime). */
+ | 'stale'
+/** Never computed yet, and not ready in time — it arrives by realtime. */
+ | 'pending'
+/** The last attempt failed; `payload` is the last good one, if any. */
+ | 'error';
+/** One card on the dashboard, as `adminCards.list` returns it — in display order. */
+export interface AdminCard {
+    /** `<appId>:<cardId>` — the key used in the layout. */
+    key: string;
+    /** The contributing app, or `platform` for Studio's own cards (products, contacts, visitors). */
+    appId: string;
+    cardId: string;
+    title: string;
+    description?: string;
+    kind: 'data' | 'component';
+    sizes: AdminCardSize[];
+    /** The size to draw it at (the layout's choice, else the card's default). */
+    size: AdminCardSize;
+    priority: number;
+    state: AdminCardState;
+    payload: AdminCardPayload | null;
+    /** When `payload` was computed (ms since epoch). */
+    computedAt: number | null;
+    /** Why the last attempt failed (state `error`). */
+    error?: string;
+    /** `component` cards: the bundle to load and the export to mount. */
+    component?: {
+        name: string;
+        files: NonNullable<AppManifestAdminCards['files']>;
+    };
+}
+/**
+ * A collection's dashboard layout — the `studioHome` settings group. Owned by the collection (every
+ * admin sees the same dashboard). Cards not listed follow, by priority; installed apps' new cards
+ * appear on their own; cards of uninstalled apps drop out.
+ */
+export interface StudioHomeLayout {
+    version: 1;
+    cards: Array<{
+        key: string;
+        size?: AdminCardSize;
+        hidden?: boolean;
+    }>;
+}
+/** `adminCards.list` → the whole dashboard in one call. */
+export interface AdminCardsResponse {
+    cards: AdminCard[];
+    /** Cards the layout hides (for the "add a card" picker). */
+    hidden: AdminCard[];
+    layout: StudioHomeLayout | null;
+}

package/dist/types/adminCards.js

@@ -0,0 +1,15 @@
+// src/types/adminCards.ts
+/**
+ * Admin cards — what an app contributes to a collection's dashboard in Studio (docs/admin-cards.md).
+ *
+ * Two kinds, one contract:
+ * - **data** (the default, any publisher): the app declares the card and an ADMIN server function that
+ *   returns an {@link AdminCardPayload}; Studio draws it. No app code runs in Studio.
+ * - **component** (first-party and approved publishers): a React component from the app's
+ *   `adminCards` bundle, given the same cached payload as its `data` prop.
+ *
+ * Fast by construction: Studio loads every card in ONE request, served from a cache. A card is only
+ * recomputed when something it declares in `refresh.on` changed (or `refresh.maxAge` passed), in the
+ * background, within a time and size budget — so a dashboard never waits on 20 functions.
+ */
+export {};

package/dist/types/appManifest.d.ts

@@ -2,6 +2,7 @@
 /// <reference types="node" />
 import type { AppDataDeclaration, AppHeadlessDeclaration } from './headless.js';
 import type { RealtimeChannelDeclaration } from './realtime.js';
+import type { AppManifestAdminCards } from './adminCards.js';
 /**
  * A bundle (widget or container) as returned by the collection widgets endpoint.
  *
@@ -817,6 +818,19 @@ export interface AppManifest {
     realtime?: {
         channels: RealtimeChannelDeclaration[];
     };
+    /**
+     * Cards this app adds to the collection's dashboard in Studio. A `data` card names an ADMIN server
+     * function returning an `AdminCardPayload`; Studio draws it, from a cache, recomputing only when
+     * something in `refresh.on` changed. @see AdminCardDeclaration · docs/admin-cards.md
+     *
+     * ```json
+     * "adminCards": { "cards": [
+     *   { "id": "unanswered", "title": "FAQ", "function": "cardUnanswered", "sizes": ["small", "medium"],
+     *     "refresh": { "on": ["records:question"], "maxAge": "1d" } }
+     * ] }
+     * ```
+     */
+    adminCards?: AppManifestAdminCards;
     /**
      * The app's public data model: its data types, how each is stored, fields, examples and read
      * recipes. Required for `headless`. @see AppDataDeclaration · docs/headless-providers.md

package/dist/types/index.d.ts

@@ -25,6 +25,7 @@ export * from "./analytics.js";
 export * from "./location.js";
 export * from "./jobs.js";
 export * from "./realtime.js";
+export * from "./adminCards.js";
 export * from "./tags.js";
 export * from "./navigation.js";
 export * from "./order.js";

package/dist/types/index.js

@@ -27,6 +27,7 @@ export * from "./analytics.js";
 export * from "./location.js";
 export * from "./jobs.js";
 export * from "./realtime.js";
+export * from "./adminCards.js";
 export * from "./tags.js";
 export * from "./navigation.js";
 export * from "./order.js";