@kubun/store-connector 0.17.1 → 0.18.0

package/lib/api-types.d.ts

@@ -0,0 +1,434 @@
+import type { Kysely } from 'kysely';
+import type { ObservationRecordMethods } from './observation-records.js';
+import type { ConnectorTables } from './tables.js';
+export type SyncStatus = 'idle' | 'syncing' | 'error';
+export type SyncState = {
+    checkpoint: unknown;
+    lastSyncedAt: string;
+    entityCount: number;
+    status: SyncStatus;
+    error?: string;
+    leaseExpiresAt?: number | null;
+    recovery?: unknown;
+    version?: number;
+    incarnation?: string;
+};
+export type SyncStateEntry = SyncState & {
+    connectorName: string;
+    ownerDID: string;
+};
+export type SweepKey = {
+    connectorName: string;
+    ownerDID: string;
+};
+export type SweepReceiptKey = SweepKey & {
+    partition: string;
+    provenance: string;
+};
+export type SweepCandidateKey = SweepReceiptKey & {
+    documentID: string;
+};
+export type SweepReceipt = SweepReceiptKey & {
+    modelID: string;
+    scope: Record<string, string>;
+    keep: Array<string>;
+    sourceFetchHLC: string;
+    predicate: {
+        field: string;
+        from: string | null;
+        to: string | null;
+    } | null;
+    complete: boolean;
+    kind: 'relist' | 'partition-removal';
+};
+export type SweepCandidateInput = {
+    documentID: string;
+    sourceID: string;
+    modelID: string;
+};
+export type SweepCandidate = SweepCandidateKey & SweepCandidateInput & {
+    state: 'pending' | 'present' | 'absent' | 'cancelled' | 'uncertain' | 'applied' | 'refused';
+    attempts: number;
+    applyFailures: number;
+    lastError: string | null;
+    updatedAt: number;
+    nextAttemptAt: number;
+};
+export type SweepOutcomeInput = SweepCandidateKey & {
+    outcome: Exclude<SweepCandidate['state'], 'pending' | 'applied' | 'refused'>;
+    lastError?: string;
+    nextAttemptAt?: number;
+};
+export type SweepApplyFailureInput = SweepCandidateKey & {
+    lastError: string;
+    nextAttemptAt: number;
+};
+export type SyncProgressCASCurrent = {
+    checkpoint: unknown;
+    recovery: unknown;
+    version: number;
+    incarnation: string;
+};
+export type SyncProgressCASResult = {
+    checkpoint: unknown;
+    recovery: unknown;
+    lastSyncedAt: string;
+    entityCount: number;
+    error?: string | null;
+};
+export type SyncProgressRecompute = (current: SyncProgressCASCurrent | null) => SyncProgressCASResult | Promise<SyncProgressCASResult>;
+export type UpdateSyncProgressParams = {
+    connectorName: string;
+    ownerDID: string;
+    recompute: SyncProgressRecompute;
+    options?: {
+        maxRetries?: number;
+    };
+};
+export type EntityTrimInput = {
+    documentID: string;
+    ownerDID: string;
+    connectorName: string;
+    trimmedFields: unknown;
+};
+export type EntityTrimRecord = EntityTrimInput & {
+    updatedAt: number;
+};
+export type PendingAuthRecord = {
+    state: string;
+    codeVerifier: string;
+    provider: string;
+    ownerDID: string;
+    /** The owner's DID in a form that can be encrypted to. See the table type. */
+    ownerWrappableDID?: string | null;
+    /** A recovery recipient's DID in a form that can be encrypted to. See the table type. */
+    controllerWrappableDID?: string | null;
+    createdAt: number;
+    /** The callback's redirect target, needed to complete the token exchange. */
+    redirectURL: string;
+    /** The scopes requested at authorize time. */
+    scopes: Array<string>;
+    /** Whether start-auth requested scopes incrementally. */
+    incremental: boolean;
+    expiresAt: number;
+};
+export type ConnectorOperationOp = 'create' | 'update';
+export type ConnectorOperationState = 'attempted' | 'committed' | 'reconcile_only' | 'dead';
+export type ClaimOperationInput = {
+    callerDID: string;
+    operationID: string;
+    ownerDID: string;
+    connectorName: string;
+    model: string;
+    op: ConnectorOperationOp;
+    accountKey: string;
+    target: string;
+    sourceID: string | null;
+    deterministicEventID: string;
+    payloadHash: string;
+    reissueIntent: unknown;
+    /**
+     * The provider's conditional-write token (e.g. an ETag) of the state the
+     * write is based on, pinned for every attempt of the operation. Captured
+     * state rather than part of the envelope: a replay never compares it.
+     */
+    providerEtag?: string | null;
+    /**
+     * The document the operation writes, when it is known before any provider
+     * I/O (an update's target, a create whose provider id is predetermined).
+     * Recorded on the first claim only; like `providerEtag`, a replay never
+     * compares it. Finalize records the document the write actually projected
+     * into, which takes precedence.
+     */
+    documentID?: string | null;
+    leaseToken: string;
+    leaseExpiresAt: number;
+};
+export type RecordOperationInput = {
+    callerDID: string;
+    operationID: string;
+    fromState: ConnectorOperationState;
+    toState: Exclude<ConnectorOperationState, 'committed'>;
+    version: number;
+    leaseToken: string;
+    providerEtag?: string | null;
+    nextAttemptAt?: number | null;
+    kind?: string | null;
+    httpStatus?: number | null;
+    /**
+     * Whether this transition consumes a recovery attempt (default `true`).
+     * `false` records a failure's classification against an attempt already
+     * consumed earlier in the same recovery pass.
+     */
+    countAttempt?: boolean;
+    /**
+     * Gives back the attempt this recovery pass consumed (`attempts - 1`), for a
+     * pass that turned out never to reach the provider. Takes precedence over
+     * `countAttempt`.
+     */
+    refundAttempt?: boolean;
+    /**
+     * Marks the `nextAttemptAt` this records as a deferral that lapses on its
+     * own (see `DeferReason`). Omitted clears any earlier mark.
+     */
+    deferReason?: DeferReason;
+    /**
+     * With `refundAttempt`: the marker of the run asking (see
+     * `markSendStarted`). The refund is refused when a different run started
+     * a provider write in this attempt, including when this run marked too.
+     */
+    sendMarker?: string;
+};
+/**
+ * A deferral that lapses on its own: `'offline'` — the device was offline,
+ * made due again on reconnect (`resumeOfflineDeferred`); `'auth'` — the
+ * owner's credential could not authorize the write (none stored, or refused by
+ * the provider), made due again once the owner authorizes
+ * (`resumeAuthDeferred`).
+ */
+export type DeferReason = 'offline' | 'auth';
+export type FinalizeOperationInput = {
+    key: {
+        callerDID: string;
+        operationID: string;
+    };
+    version: number;
+    leaseToken: string;
+    documentID: string;
+    resultEntity: unknown;
+    watchIdentity: ProjectionWatchIdentity;
+    currentWinnerDigest: string | null;
+};
+export type ConnectorOperation = {
+    callerDID: string;
+    operationID: string;
+    /**
+     * Opaque random key assigned when the operation was first claimed: its
+     * public identity, unlike `operationID`, which is the caller's idempotency
+     * key.
+     */
+    nodeKey: string;
+    ownerDID: string;
+    connectorName: string;
+    model: string;
+    op: ConnectorOperationOp;
+    accountKey: string;
+    target: string;
+    sourceID: string | null;
+    deterministicEventID: string;
+    payloadHash: string;
+    reissueIntent: unknown;
+    providerEtag: string | null;
+    documentID: string | null;
+    resultEntity: unknown;
+    state: ConnectorOperationState;
+    attempts: number;
+    nextAttemptAt: number | null;
+    lastKind: string | null;
+    lastHTTPStatus: number | null;
+    version: number;
+    incarnation: string | null;
+    leaseToken: string | null;
+    leaseExpiresAt: number | null;
+    createdAt: number;
+    updatedAt: number;
+};
+export type AcquireLeaseParams = {
+    callerDID: string;
+    operationID: string;
+    token: string;
+    expiresAt: number;
+};
+export type RenewLeaseParams = {
+    callerDID: string;
+    operationID: string;
+    token: string;
+    expiresAt: number;
+};
+export type ReleaseLeaseParams = {
+    callerDID: string;
+    operationID: string;
+    token: string;
+};
+export type ProjectionWatchIdentity = {
+    ownerDID: string;
+    connectorName: string;
+    model: string;
+    accountKey: string;
+    sourceID: string;
+};
+export type ProjectionWatchVerificationStatus = 'pending_verification' | 'verified' | 'repair_failed';
+export type ProjectionWatch = {
+    ownerDID: string;
+    connectorName: string;
+    model: string;
+    accountKey: string;
+    sourceID: string;
+    documentID: string;
+    verifiedStateDigest: string | null;
+    observedWinnerDigest: string | null;
+    verificationStatus: ProjectionWatchVerificationStatus;
+    verificationAttempts: number;
+    repairGeneration: number;
+    nextAttemptAt: number | null;
+    version: number;
+    createdAt: number;
+    updatedAt: number;
+};
+/**
+ * Filters for `listTrackedOperations`, all optional and combined with AND. An
+ * empty `states` or `documentIDs` list matches nothing.
+ */
+export type TrackedOperationFilter = {
+    nodeKey?: string;
+    callerDID?: string;
+    operationID?: string;
+    /** Operations the DID claimed as caller, or owns as credential owner. */
+    visibleTo?: string;
+    connectorName?: string;
+    states?: Array<ConnectorOperationState>;
+    /** Operations linked to one of these documents. */
+    documentIDs?: Array<string>;
+};
+export type ArmWatchReason = 'finalize' | 'ingress' | 'manual';
+export type ArmWatchOutcome = 'opened' | 'coalesced' | 'noop';
+export type ArmWatchOptions = {
+    triggeringWinner?: string;
+    dueAt: number;
+};
+export type RecordVerificationInput = {
+    fetchedDigest: string | null;
+    generation: number;
+    maxAttempts: number;
+    dueAt: number;
+    claimedUntil?: number;
+};
+export type RecordVerificationOutcome = 'verified' | 'pending' | 'repair_failed' | 'stale-generation' | 'stale-claim';
+/**
+ * Reads a document's current winner state digest (`W`) INSIDE the caller's
+ * transaction — wraps `readWinnerStateDigest(tx, documentID)`
+ * (exported from `@kubun/store-graph`). Graph and connector tables share one
+ * DB/connection via the KubunDB coordinator, so the wired implementation
+ * must be invoked with the `tx` handed to this callback, never a top-level
+ * `db` — passing the top-level db would nest a transaction and, on SQLite's
+ * single connection, deadlock.
+ */
+export type ReadWinner = (documentID: string, tx: Kysely<ConnectorTables>) => Promise<string>;
+/**
+ * Batch sibling of `ReadWinner`: the winner digests of many documents in one
+ * pass. A document whose winner cannot be read is absent from the map, where
+ * `ReadWinner` would throw.
+ */
+export type ReadWinners = (documentIDs: ReadonlyArray<string>, tx: Kysely<ConnectorTables>) => Promise<Map<string, string>>;
+export type ConnectorStoreDeps = {
+    now?: () => number;
+    /**
+     * Required by `armWatch`'s `'ingress'`/`'manual'` reasons and by
+     * `recordVerification`; a caller that reaches either without it gets a clear
+     * throw rather than a silent no-op. The connector plugin passes one over
+     * `readWinnerStateDigest`; tests pass a scripted fake so the CAS interleaves
+     * are deterministic.
+     */
+    readWinner?: ReadWinner;
+    /**
+     * The source of every random id the store mints: an operation's node key and
+     * a sync state's incarnation. The connector plugin passes its runtime's
+     * `getRandomID`.
+     */
+    getRandomID: () => string;
+};
+export type ConnectorStoreAPI = ObservationRecordMethods & {
+    recordRelistReceipt(receipt: SweepReceipt, candidates: Array<SweepCandidateInput>): Promise<void>;
+    listSweepReceipts(key: SweepKey): Promise<Array<SweepReceipt>>;
+    listSweepCandidates(key: SweepKey & {
+        dueAt?: number;
+    }): Promise<Array<SweepCandidate>>;
+    recordSweepOutcome(input: SweepOutcomeInput): Promise<void>;
+    /** Returns true only when this failure transitions the candidate to refused. */
+    recordSweepApplyFailure(input: SweepApplyFailureInput): Promise<boolean>;
+    markSweepCandidateApplied(key: SweepCandidateKey): Promise<void>;
+    commitSweepCheckpoint(key: SweepReceiptKey): Promise<boolean>;
+    getSweepCheckpoint(key: SweepKey & {
+        partition: string;
+    }): Promise<string | null>;
+    getSyncState(connectorName: string, ownerDID: string): Promise<SyncState | null>;
+    setSyncState(connectorName: string, ownerDID: string, state: SyncState): Promise<void>;
+    updateSyncProgress(params: UpdateSyncProgressParams): Promise<void>;
+    deleteSyncState(connectorName: string, ownerDID: string): Promise<void>;
+    listSyncStatesForConnector(connectorName: string): Promise<Array<SyncStateEntry>>;
+    getEntityTrim(documentID: string): Promise<EntityTrimRecord | null>;
+    setEntityTrim(input: EntityTrimInput): Promise<void>;
+    clearEntityTrim(documentID: string): Promise<void>;
+    hasDocumentConnectorWork(documentID: string): Promise<boolean>;
+    sweepDocumentRows(documentID: string): Promise<void>;
+    createPendingAuth(record: PendingAuthRecord): Promise<void>;
+    getPendingAuth(state: string): Promise<PendingAuthRecord | null>;
+    consumePendingAuth(state: string): Promise<PendingAuthRecord | null>;
+    deleteExpiredPendingAuth(cutoffMs: number): Promise<void>;
+    claimOperation(input: ClaimOperationInput): Promise<{
+        status: 'claimed';
+        record: ConnectorOperation;
+    } | {
+        status: 'exists';
+        record: ConnectorOperation;
+    } | {
+        status: 'conflict';
+    }>;
+    acquireLease(params: AcquireLeaseParams): Promise<boolean>;
+    renewLease(params: RenewLeaseParams): Promise<boolean>;
+    releaseLease(params: ReleaseLeaseParams): Promise<boolean>;
+    getOperation(callerDID: string, operationID: string): Promise<ConnectorOperation | null>;
+    listTrackedOperations(filter: TrackedOperationFilter): Promise<Array<ConnectorOperation>>;
+    hasNewerOperationOnDocument(callerDID: string, operationID: string): Promise<boolean>;
+    markSendStarted(params: {
+        callerDID: string;
+        operationID: string;
+        leaseToken: string;
+        marker: string;
+    }): Promise<boolean>;
+    deferOperation(params: {
+        callerDID: string;
+        operationID: string;
+        nextAttemptAt: number;
+        leaseToken?: string;
+        reason?: DeferReason;
+    }): Promise<boolean>;
+    recordOperation(input: RecordOperationInput): Promise<boolean>;
+    finalizeOperationAndArmWatch(input: FinalizeOperationInput): Promise<boolean>;
+    getWatch(identity: ProjectionWatchIdentity): Promise<ProjectionWatch | null>;
+    getWatchByDocument(documentID: string): Promise<ProjectionWatch | null>;
+    listWatchesByDocuments(documentIDs: Array<string>): Promise<Array<ProjectionWatch>>;
+    armWatch(identity: ProjectionWatchIdentity, reason: ArmWatchReason, opts: ArmWatchOptions): Promise<ArmWatchOutcome>;
+    deferWatch(identity: ProjectionWatchIdentity, opts: {
+        generation: number;
+        nextAttemptAt: number;
+        reason?: DeferReason;
+        claimedUntil: number;
+    }): Promise<boolean>;
+    resumeOfflineDeferred(now: number): Promise<void>;
+    resumeAuthDeferred(params: {
+        now: number;
+        ownerDID: string;
+        connectorNames: Array<string>;
+    }): Promise<void>;
+    claimWatchAttempt(identity: ProjectionWatchIdentity, opts: {
+        generation: number;
+        now: number;
+        until: number;
+    }): Promise<boolean>;
+    recordVerification(identity: ProjectionWatchIdentity, input: RecordVerificationInput): Promise<RecordVerificationOutcome>;
+    requestRepull(identity: ProjectionWatchIdentity, opts: {
+        dueAt: number;
+    }): Promise<void>;
+    listDueOperations(now: number, opts: {
+        readWinner: ReadWinner;
+        readWinners?: ReadWinners;
+    }): Promise<{
+        operations: Array<ConnectorOperation>;
+        watches: Array<ProjectionWatch>;
+    }>;
+    collectFinishedOperations(params: {
+        before: number;
+        limit: number;
+    }): Promise<number>;
+};

package/lib/api-types.js

@@ -0,0 +1,2 @@
+// --- ConnectorStoreAPI type ---
+export { };

package/lib/api.d.ts

@@ -1,62 +1,6 @@
-import type { Adapter } from '@kubun/db-adapter';
+import { type Adapter } from '@kubun/db-adapter';
 import type { Kysely } from 'kysely';
+import type { ConnectorStoreAPI, ConnectorStoreDeps } from './api-types.js';
 import type { ConnectorTables } from './tables.js';
-export type SyncStatus = 'idle' | 'syncing' | 'error';
-export type SyncState = {
-    checkpoint: unknown;
-    lastSyncedAt: string;
-    entityCount: number;
-    status: SyncStatus;
-    error?: string;
-    leaseExpiresAt?: number | null;
-    recovery?: unknown;
-    version?: number;
-    incarnation?: string;
-};
-export type SyncStateEntry = SyncState & {
-    connectorName: string;
-    ownerDID: string;
-};
-export type SyncProgressCASCurrent = {
-    checkpoint: unknown;
-    recovery: unknown;
-    version: number;
-    incarnation: string;
-};
-export type SyncProgressCASResult = {
-    checkpoint: unknown;
-    recovery: unknown;
-    lastSyncedAt: string;
-    entityCount: number;
-    error?: string | null;
-};
-export type SyncProgressRecompute = (current: SyncProgressCASCurrent | null) => SyncProgressCASResult | Promise<SyncProgressCASResult>;
-export type PendingAuthRecord = {
-    state: string;
-    codeVerifier: string;
-    provider: string;
-    ownerDID: string;
-    /** The owner's DID in a form that can be encrypted to. See the table type. */
-    ownerWrappableDID?: string | null;
-    /** A recovery recipient's DID in a form that can be encrypted to. See the table type. */
-    controllerWrappableDID?: string | null;
-    createdAt: number;
-    /** The callback's redirect target, needed to complete the token exchange. */
-    redirectURL: string;
-    /** The scopes requested at authorize time. */
-    scopes: Array<string>;
-    expiresAt: number;
-};
-export type ConnectorStoreAPI = {
-    getSyncState(connectorName: string, ownerDID: string): Promise<SyncState | null>;
-    setSyncState(connectorName: string, ownerDID: string, state: SyncState): Promise<void>;
-    updateSyncProgress(connectorName: string, ownerDID: string, recompute: SyncProgressRecompute, options?: {
-        maxRetries?: number;
-    }): Promise<void>;
-    deleteSyncState(connectorName: string, ownerDID: string): Promise<void>;
-    listSyncStatesForConnector(connectorName: string): Promise<Array<SyncStateEntry>>;
-    createPendingAuth(record: PendingAuthRecord): Promise<void>;
-    consumePendingAuth(state: string): Promise<PendingAuthRecord | null>;
-    deleteExpiredPendingAuth(cutoffMs: number): Promise<void>;
-};
-export declare function createConnectorStore(db: Kysely<ConnectorTables>, _adapter: Adapter): ConnectorStoreAPI;
+export type * from './api-types.js';
+export declare function createConnectorStore(db: Kysely<ConnectorTables>, adapter: Adapter, deps: ConnectorStoreDeps): ConnectorStoreAPI;