@kubun/connector 0.17.0 → 0.17.1

package/lib/index.d.ts

@@ -1,4 +1,4 @@
 export { clusterModelURNs, resolveModelID } from './cluster-utils.js';
 export { connectorClusters, connectorModelIDs } from './models/cluster.js';
 export { externalEntityDefinition } from './models/external-entity.js';
-export type { ActionDefinition, ActionHandler, ActionHandlerFactory, ActionResult, ClientDataProvider, ClientProviderFactory, ConnectorAuth, ConnectorDefinition, ConnectorSyncEventPayload, DataProvider, DeviceConnectorAuth, DevicePermission, EntityBatch, EntityRecord, FetchChangesParams, FetchParams, OAuthConnectorAuth, OAuthState, ServerDataProvider, ServerProviderFactory, SyncBoundary, SyncCompleteEvent, SyncErrorEvent, SyncEvent, SyncFailureSample, SyncProgressEvent, SyncState, SyncStateEntry, SyncStateStore, SyncStatus, UserSyncPreferences, WebhookParams, WebhookRegistration, WriteAttachment, } from './types.js';
+export type { ActionDefinition, ActionHandler, ActionHandlerFactory, ActionResult, ClientDataProvider, ClientProviderFactory, ConnectorAuth, ConnectorDefinition, ConnectorSyncEventPayload, DataProvider, DeadLetter, DeviceConnectorAuth, DevicePermission, EntityBatch, EntityRecord, FetchChangesParams, FetchParams, JSONValue, OAuthConnectorAuth, OAuthState, PendingOp, Recovery, ServerDataProvider, ServerProviderFactory, SyncBoundary, SyncCompleteEvent, SyncErrorEvent, SyncEvent, SyncFailureSample, SyncProgressCASCurrent, SyncProgressCASResult, SyncProgressEvent, SyncProgressRecompute, SyncState, SyncStateEntry, SyncStateStore, SyncStatus, UserSyncPreferences, WebhookParams, WebhookRegistration, WriteAttachment, } from './types.js';

package/lib/types.d.ts

@@ -9,6 +9,37 @@ export type OAuthState = {
     createdAt: number;
 };
 export type SyncStatus = 'idle' | 'syncing' | 'error';
+export type JSONValue = string | number | boolean | null | {
+    [key: string]: JSONValue;
+} | Array<JSONValue>;
+export type PendingOp = {
+    docID: string;
+    kind: 'upsert' | 'delete';
+    payload: JSONValue;
+    attempts: number;
+    firstFailedAt: string;
+    lastError: {
+        code?: string;
+        message: string;
+    };
+};
+export type DeadLetter = {
+    docID: string | null;
+    sourceService: string;
+    sourceID: string;
+    kind: 'upsert' | 'delete';
+    attempts: number;
+    lastError: {
+        code?: string;
+        message: string;
+    };
+    deadLetteredAt: string;
+    reason: 'max-attempts' | 'payload-evicted' | 'unserializable' | 'unaddressable';
+};
+export type Recovery = {
+    pending: Array<PendingOp>;
+    deadLetters: Array<DeadLetter>;
+};
 export type SyncState = {
     checkpoint: unknown;
     lastSyncedAt: string;
@@ -16,19 +47,33 @@ export type SyncState = {
     status: SyncStatus;
     error?: string;
     leaseExpiresAt?: number | null;
+    recovery?: Recovery | null;
+    version?: number;
+    incarnation?: string;
 };
 export type SyncStateEntry = SyncState & {
     connectorName: string;
     ownerDID: string;
 };
+export type SyncProgressCASCurrent = {
+    checkpoint: unknown;
+    recovery: Recovery | null;
+    version: number;
+    incarnation: string;
+};
+export type SyncProgressCASResult = {
+    checkpoint: unknown;
+    recovery: Recovery | null;
+    lastSyncedAt: string;
+    entityCount: number;
+    error?: string | null;
+};
+export type SyncProgressRecompute = (current: SyncProgressCASCurrent | null) => SyncProgressCASResult | Promise<SyncProgressCASResult>;
 export type SyncStateStore = {
     get(connectorName: string, ownerDID: string): Promise<SyncState | null>;
     set(connectorName: string, ownerDID: string, state: SyncState): Promise<void>;
-    updateSyncProgress(connectorName: string, ownerDID: string, progress: {
-        checkpoint: unknown;
-        lastSyncedAt: string;
-        entityCount: number;
-        error?: string;
+    updateSyncProgress(connectorName: string, ownerDID: string, recompute: SyncProgressRecompute, options?: {
+        maxRetries?: number;
     }): Promise<void>;
     delete(connectorName: string, ownerDID: string): Promise<void>;
     listForConnector(connectorName: string): Promise<Array<SyncStateEntry>>;
@@ -66,6 +111,20 @@ export type FetchParams = {
 export type FetchChangesParams = FetchParams & {
     lastSyncedAt?: Date;
 };
+/**
+ * A source of external entities, driven by an opaque `checkpoint`.
+ *
+ * **Replay-stability contract (required).** Re-opening `fetchAll`/`fetchChanges`
+ * from the same `checkpoint` MUST re-emit the same operations — or a superset —
+ * addressed by `sourceService`+`sourceID`; it must never emit a narrower set. The
+ * sync engine advances the connector checkpoint before the durable workflow
+ * checkpoint, so a crash between the two re-drives `fetchChanges`/`fetchAll` from
+ * an older checkpoint; a stable replay makes that re-drive idempotent (imports
+ * upsert by unique key) with no dropped entities. Concretely: a time window MUST
+ * be an absolute bound carried in the checkpoint, never recomputed from `now` on
+ * each call — a `now`-relative window silently narrows on replay. (Server-side
+ * ordering may vary between calls: harmless, since ops are keyed by identity.)
+ */
 export type DataProvider = {
     fetchAll(params: FetchParams): AsyncIterable<EntityBatch>;
     fetchChanges(params: FetchChangesParams): AsyncIterable<EntityBatch>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/connector",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,