@proveanything/smartlinks 2.0.58 → 2.0.60

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 } 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,20 @@ 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;
+    }>;
+    /** 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,24 @@ 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;
+    /** 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.60  |  Generated: 2026-10-13T16:25:55.817Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2915,6 +2915,8 @@ interface AppConnectorDeclaration {
   }
   panels?: ConnectorPanel[]
   aiGuide?: string
+  recordId?: string
+  limits?: { requestsPerSecond?: number }
 }
 ```
 
@@ -3008,7 +3010,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 +7118,32 @@ 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
+}
+```
+
+**FailedRecordList** (interface)
+```typescript
+interface FailedRecordList {
+  direction: FlowDirection
+  items: FailedRecord[]
+  nextCursor: string | null
 }
 ```
 
@@ -7161,6 +7197,7 @@ interface RunFlowSummary {
   created?: number
   updated?: number
   skipped?: number
+  held?: number
   status: RunStatus
   runId?: string
 }
@@ -11704,6 +11741,17 @@ 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
+
+**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/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/dist/docs/integrations.md

@@ -19,6 +19,14 @@ 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`). 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.
+
 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/openapi.yaml

@@ -19780,6 +19780,11 @@ components:
             $ref: "#/components/schemas/ConnectorPanel"
         aiGuide:
           type: string
+        recordId:
+          type: string
+        limits:
+          type: object
+          additionalProperties: true
       required:
         - provider
         - directions
@@ -19933,12 +19938,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 +26297,12 @@ components:
           type: string
         totalSynced:
           type: number
+        circuitOpenedAt:
+          type: string
+        circuitProbeAt:
+          type: string
+        circuitReason:
+          type: string
       required:
         - id
         - orgId
@@ -26294,6 +26319,47 @@ 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
+    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 +26431,8 @@ components:
           type: number
         skipped:
           type: number
+        held:
+          type: number
         status:
           $ref: "#/components/schemas/RunStatus"
         runId:

package/dist/types/appManifest.d.ts

@@ -926,6 +926,16 @@ export interface AppConnectorDeclaration {
     panels?: ConnectorPanel[];
     /** Path (under the app's public files) of a guide the AI mapping assistant reads. */
     aiGuide?: string;
+    /**
+     * Path of the provider's own id in a fetched record (e.g. 'gtin', 'item.id'). Inbound records are
+     * landed and matched to SmartLinks entities by it, so a re-import updates rather than duplicates.
+     * Default 'id'; a flow can override it with `config.upsert.externalIdPath`.
+     */
+    recordId?: string;
+    /** Requests per second toward the provider, shared by every SmartLinks worker. */
+    limits?: {
+        requestsPerSecond?: number;
+    };
 }
 /**
  * What every connector function receives about the installation it serves. The engine assembles it
@@ -1008,6 +1018,10 @@ export interface ConnectorSendResult {
         status?: number;
         error?: string;
         externalId?: string;
+        /** Worth retrying? Default: by status (408/425/429/5xx/none yes; other 4xx no). */
+        retryable?: boolean;
+        /** The provider asked to wait this long before retrying (e.g. its Retry-After). */
+        retryAfterSeconds?: number;
     }>;
 }
 export interface ConnectorFetchInput {

package/dist/types/integrations.d.ts

@@ -71,6 +71,32 @@ export interface IntegrationFlow {
     lastPollAt?: string | null;
     lastCursor?: string | null;
     totalSynced?: number | null;
+    /**
+     * Circuit breaker: set while the flow has paused itself because its destination / provider keeps
+     * failing. Nothing is sent or fetched (edits are held as retries) until a probe gets through —
+     * `circuitProbeAt` is the next one — or someone resumes it (`integrations.resumeFlow`).
+     */
+    circuitOpenedAt?: string | null;
+    circuitProbeAt?: string | null;
+    circuitReason?: string | null;
+}
+/** A record that failed: retried on its own with backoff ('failed'), or given up on ('dead'). */
+export interface FailedRecord {
+    /** Outbound: the SmartLinks entity id. Inbound: the landed record's id (pass it to retryFailed). */
+    id: string;
+    entityId?: string | null;
+    /** Inbound: the provider's id for the record. */
+    externalId?: string;
+    status: 'failed' | 'dead';
+    attempts: number;
+    nextAttemptAt?: string | null;
+    lastError?: string | null;
+    updatedAt?: string;
+}
+export interface FailedRecordList {
+    direction: FlowDirection;
+    items: FailedRecord[];
+    nextCursor: string | null;
 }
 export interface CreateFlowInput {
     appId: string;
@@ -109,10 +135,12 @@ export interface RunFlowSummary {
     /** Outbound: records delivered. */
     sent?: number;
     failed: number;
-    /** Inbound: products created / updated, and records the connector skipped. */
+    /** Inbound: products created / updated, and records the connector skipped (outbound: unchanged). */
     created?: number;
     updated?: number;
     skipped?: number;
+    /** Outbound: changes held because the destination is paused (circuit open); sent after it recovers. */
+    held?: number;
     status: RunStatus;
     /** Id of the persisted run row (deep-link into its detail). */
     runId?: string;

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.60  |  Generated: 2026-10-13T16:25:55.817Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2915,6 +2915,8 @@ interface AppConnectorDeclaration {
   }
   panels?: ConnectorPanel[]
   aiGuide?: string
+  recordId?: string
+  limits?: { requestsPerSecond?: number }
 }
 ```
 
@@ -3008,7 +3010,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 +7118,32 @@ 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
+}
+```
+
+**FailedRecordList** (interface)
+```typescript
+interface FailedRecordList {
+  direction: FlowDirection
+  items: FailedRecord[]
+  nextCursor: string | null
 }
 ```
 
@@ -7161,6 +7197,7 @@ interface RunFlowSummary {
   created?: number
   updated?: number
   skipped?: number
+  held?: number
   status: RunStatus
   runId?: string
 }
@@ -11704,6 +11741,17 @@ 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
+
+**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/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,14 @@ 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`). 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.
+
 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/openapi.yaml

@@ -19780,6 +19780,11 @@ components:
             $ref: "#/components/schemas/ConnectorPanel"
         aiGuide:
           type: string
+        recordId:
+          type: string
+        limits:
+          type: object
+          additionalProperties: true
       required:
         - provider
         - directions
@@ -19933,12 +19938,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 +26297,12 @@ components:
           type: string
         totalSynced:
           type: number
+        circuitOpenedAt:
+          type: string
+        circuitProbeAt:
+          type: string
+        circuitReason:
+          type: string
       required:
         - id
         - orgId
@@ -26294,6 +26319,47 @@ 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
+    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 +26431,8 @@ components:
           type: number
         skipped:
           type: number
+        held:
+          type: number
         status:
           $ref: "#/components/schemas/RunStatus"
         runId:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.58",
+  "version": "2.0.60",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",