@proveanything/smartlinks 2.0.58 → 2.0.62

package/dist/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/dist/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`)
 
 ---

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:
@@ -19780,6 +20047,11 @@ components:
             $ref: "#/components/schemas/ConnectorPanel"
         aiGuide:
           type: string
+        recordId:
+          type: string
+        limits:
+          type: object
+          additionalProperties: true
       required:
         - provider
         - directions
@@ -19933,12 +20205,26 @@ components:
       type: object
       properties:
         results:
-          type: array
-          items:
-            type: object
-            additionalProperties: true
+          type: object
+          additionalProperties: true
+        index:
+          type: number
+        ok:
+          type: boolean
+        status:
+          type: number
+        error:
+          type: string
+        externalId:
+          type: string
+        retryable:
+          type: boolean
+        retryAfterSeconds:
+          type: number
       required:
         - results
+        - index
+        - ok
     ConnectorFetchInput:
       type: object
       properties:
@@ -26278,6 +26564,12 @@ components:
           type: string
         totalSynced:
           type: number
+        circuitOpenedAt:
+          type: string
+        circuitProbeAt:
+          type: string
+        circuitReason:
+          type: string
       required:
         - id
         - orgId
@@ -26294,6 +26586,210 @@ components:
         - createdBy
         - createdAt
         - updatedAt
+    FailedRecord:
+      type: object
+      properties:
+        id:
+          type: string
+        entityId:
+          type: string
+        externalId:
+          type: string
+        status:
+          type: string
+          enum:
+            - failed
+            - dead
+        attempts:
+          type: number
+        nextAttemptAt:
+          type: string
+        lastError:
+          type: string
+        updatedAt:
+          type: string
+      required:
+        - 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:
+        direction:
+          $ref: "#/components/schemas/FlowDirection"
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/FailedRecord"
+        nextCursor:
+          type: string
+      required:
+        - direction
+        - items
+        - nextCursor
     CreateFlowInput:
       type: object
       properties:
@@ -26365,6 +26861,8 @@ components:
           type: number
         skipped:
           type: number
+        held:
+          type: number
         status:
           $ref: "#/components/schemas/RunStatus"
         runId: