@kubun/connector 0.16.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/models/cluster.js

@@ -7,5 +7,5 @@ const graph = GraphModel.fromClusters({
     clusters: connectorClusters
 });
 export const connectorModelIDs = {
-    ExternalEntity: graph.aliases.ExternalEntity
+    ExternalEntity: graph.aliasID('ExternalEntity')
 };

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.16.0",
+  "version": "0.17.1",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,9 +15,9 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/credential-types": "^0.16.0",
-    "@kubun/protocol": "^0.16.0",
-    "@kubun/scalars": "^0.16.0",
+    "@kubun/credential-types": "^0.17.0",
+    "@kubun/protocol": "^0.17.0",
+    "@kubun/scalars": "^0.17.0",
     "json-schema-typed": "^8.0.2"
   },
   "publishConfig": {
@@ -26,8 +26,8 @@
   "scripts": {
     "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
     "build:clean": "del lib",
-    "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
-    "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
+    "build:js": "del 'lib/**/*.js' && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del 'lib/**/*.d.ts' 'lib/**/*.d.ts.map' && tsc --emitDeclarationOnly --skipLibCheck",
     "build:types:ci": "tsc --emitDeclarationOnly --declarationMap false",
     "test": "pnpm run test:types && pnpm run test:unit",
     "test:types": "tsc --noEmit -p tsconfig.test.json",