@kubun/connector 0.17.0 → 0.17.2

package/lib/authority.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The capability action a caller presents to execute a connector action
+ * (create/update) on a `did:kokuin:` owner's behalf. Gated BEFORE any provider
+ * credential I/O by the plugin-connector execution path — see
+ * `authorizeAction` in `@kubun/engine`.
+ */
+export declare const CONNECTOR_EXECUTE_ACTION = "connector/execute";
+/**
+ * Group-anchored resource specificity tiers for a `connector/execute`
+ * capability, most-specific first: the exact model, any model of the
+ * connector, then any connector in the group. Every tier is anchored to the
+ * group — there is no group-agnostic or global (`*`) tier, so a grant can
+ * never authorize a connector spend outside the group it was issued in.
+ */
+export declare function connectorExecuteResourceTiers(groupID: string, connector: string, model: string): Array<string>;

package/lib/authority.js

@@ -0,0 +1,19 @@
+/**
+ * The capability action a caller presents to execute a connector action
+ * (create/update) on a `did:kokuin:` owner's behalf. Gated BEFORE any provider
+ * credential I/O by the plugin-connector execution path — see
+ * `authorizeAction` in `@kubun/engine`.
+ */ export const CONNECTOR_EXECUTE_ACTION = 'connector/execute';
+/**
+ * Group-anchored resource specificity tiers for a `connector/execute`
+ * capability, most-specific first: the exact model, any model of the
+ * connector, then any connector in the group. Every tier is anchored to the
+ * group — there is no group-agnostic or global (`*`) tier, so a grant can
+ * never authorize a connector spend outside the group it was issued in.
+ */ export function connectorExecuteResourceTiers(groupID, connector, model) {
+    return [
+        `urn:kubun:connector:${groupID}/${connector}/${model}`,
+        `urn:kubun:connector:${groupID}/${connector}/*`,
+        `urn:kubun:connector:${groupID}/*`
+    ];
+}

package/lib/errors.d.ts

@@ -0,0 +1,51 @@
+/** Machine-readable outcome classification for a failed connector action. */
+export type ConnectorErrorKind = 'rejected' | 'unknown';
+export type ConnectorErrorOptions = ErrorOptions & {
+    /** A machine-readable failure code. */
+    code?: string;
+    /** Whether the failure is a definite non-commit or outcome-unknown. */
+    kind?: ConnectorErrorKind;
+    /** The provider's HTTP status, when the failure came from a response. */
+    httpStatus?: number;
+    /** Set when the failure came after a provider write went out. */
+    sent?: boolean;
+};
+/**
+ * A connector failure carrying the fields write-back recovery reads: an
+ * optional `code`, the outcome classification (`kind`), the provider HTTP
+ * status and whether the write already went out (`sent`). A field left unset
+ * reads `undefined`, which recovery treats as unclassified.
+ */
+export declare class ConnectorError extends Error {
+    #private;
+    constructor(message: string, options?: ConnectorErrorOptions);
+    get code(): string | undefined;
+    get kind(): ConnectorErrorKind | undefined;
+    get httpStatus(): number | undefined;
+    get sent(): boolean | undefined;
+}
+/**
+ * Classify an HTTP failure by whether the write definitely did not commit.
+ * A 4xx (except 429 and 412) is a definite non-commit — the request was
+ * rejected and a retry will be rejected the same way. A 429 rate-limit, any
+ * 5xx, and any transport failure are outcome-unknown: the provider may have
+ * accepted the write before the failure surfaced, so a blind retry risks a
+ * duplicate. A 412 (If-Match precondition failed) is also outcome-unknown —
+ * it means the provider record changed under us, so recovery must reconcile
+ * rather than treat it as a terminal rejection.
+ */
+export declare function classifyHTTPStatus(status: number): ConnectorErrorKind;
+/**
+ * The error a connector throws for a failed provider HTTP call, tagged with the
+ * HTTP status and its outcome classification (`kind`) so the caller can tell a
+ * definite rejection from an indeterminate failure.
+ */
+export declare function connectorHTTPError(message: string, status: number): ConnectorError;
+/**
+ * Wraps a failure raised after a handler's provider write already went out
+ * (e.g. the read-back that follows a send). The write may have landed, so the
+ * failure is marked `sent` — never taken for a request that could not have
+ * reached the provider, and so never refunded — and classified `unknown`, never
+ * a definite rejection, whatever the later call's own status was.
+ */
+export declare function markWriteSent(cause: unknown): ConnectorError;

package/lib/errors.js

@@ -0,0 +1,72 @@
+/** Machine-readable outcome classification for a failed connector action. */ /**
+ * A connector failure carrying the fields write-back recovery reads: an
+ * optional `code`, the outcome classification (`kind`), the provider HTTP
+ * status and whether the write already went out (`sent`). A field left unset
+ * reads `undefined`, which recovery treats as unclassified.
+ */ export class ConnectorError extends Error {
+    #code;
+    #kind;
+    #httpStatus;
+    #sent;
+    constructor(message, options = {}){
+        const { code, kind, httpStatus, sent, ...errorOptions } = options;
+        super(message, errorOptions);
+        this.name = 'ConnectorError';
+        this.#code = code;
+        this.#kind = kind;
+        this.#httpStatus = httpStatus;
+        this.#sent = sent;
+    }
+    get code() {
+        return this.#code;
+    }
+    get kind() {
+        return this.#kind;
+    }
+    get httpStatus() {
+        return this.#httpStatus;
+    }
+    get sent() {
+        return this.#sent;
+    }
+}
+/**
+ * Classify an HTTP failure by whether the write definitely did not commit.
+ * A 4xx (except 429 and 412) is a definite non-commit — the request was
+ * rejected and a retry will be rejected the same way. A 429 rate-limit, any
+ * 5xx, and any transport failure are outcome-unknown: the provider may have
+ * accepted the write before the failure surfaced, so a blind retry risks a
+ * duplicate. A 412 (If-Match precondition failed) is also outcome-unknown —
+ * it means the provider record changed under us, so recovery must reconcile
+ * rather than treat it as a terminal rejection.
+ */ export function classifyHTTPStatus(status) {
+    return status >= 400 && status < 500 && status !== 429 && status !== 412 ? 'rejected' : 'unknown';
+}
+/**
+ * The error a connector throws for a failed provider HTTP call, tagged with the
+ * HTTP status and its outcome classification (`kind`) so the caller can tell a
+ * definite rejection from an indeterminate failure.
+ */ export function connectorHTTPError(message, status) {
+    return new ConnectorError(message, {
+        httpStatus: status,
+        kind: classifyHTTPStatus(status)
+    });
+}
+/**
+ * Wraps a failure raised after a handler's provider write already went out
+ * (e.g. the read-back that follows a send). The write may have landed, so the
+ * failure is marked `sent` — never taken for a request that could not have
+ * reached the provider, and so never refunded — and classified `unknown`, never
+ * a definite rejection, whatever the later call's own status was.
+ */ export function markWriteSent(cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const status = cause?.httpStatus;
+    return new ConnectorError(message, {
+        cause,
+        sent: true,
+        kind: 'unknown',
+        ...typeof status === 'number' ? {
+            httpStatus: status
+        } : {}
+    });
+}

package/lib/index.d.ts

@@ -1,4 +1,6 @@
+export { CONNECTOR_EXECUTE_ACTION, connectorExecuteResourceTiers } from './authority.js';
 export { clusterModelURNs, resolveModelID } from './cluster-utils.js';
+export { ConnectorError, type ConnectorErrorKind, type ConnectorErrorOptions, classifyHTTPStatus, connectorHTTPError, markWriteSent, } from './errors.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, ActionTargetResolver, ActionTargetStorage, ActionWriteContext, ActionWriteResult, ClientDataProvider, ClientProviderFactory, ConnectorAuth, ConnectorDefinition, ConnectorSyncEventPayload, CreatedSourceIDPredictor, DataProvider, DeadLetter, DeviceConnectorAuth, DevicePermission, EntityBatch, EntityRecord, FetchChangesParams, FetchedAbsentEntity, FetchedEntity, FetchedPresentEntity, FetchParams, IntentCanonicalizer, IntentComparison, JSONValue, LocalAnnotationMerger, OAuthConnectorAuth, OAuthState, PendingOp, ReconcileResult, Recovery, ResolvedActionTarget, ServerDataProvider, ServerProviderFactory, SyncBoundary, SyncCompleteEvent, SyncErrorEvent, SyncEvent, SyncFailureSample, SyncProgressCASCurrent, SyncProgressCASResult, SyncProgressEvent, SyncProgressRecompute, SyncState, SyncStateEntry, SyncStateStore, SyncStatus, UserSyncPreferences, WebhookParams, WebhookRegistration, WriteAttachment, } from './types.js';

package/lib/index.js

@@ -1,3 +1,5 @@
+export { CONNECTOR_EXECUTE_ACTION, connectorExecuteResourceTiers } from './authority.js';
 export { clusterModelURNs, resolveModelID } from './cluster-utils.js';
+export { ConnectorError, classifyHTTPStatus, connectorHTTPError, markWriteSent } from './errors.js';
 export { connectorClusters, connectorModelIDs } from './models/cluster.js';
 export { externalEntityDefinition } from './models/external-entity.js';

package/lib/types.d.ts

@@ -1,4 +1,4 @@
-import type { Credential } from '@kubun/credential-types';
+import type { Credential, ProviderAccount } from '@kubun/credential-types';
 import type { ClustersRecord } from '@kubun/protocol';
 import type { JSONSchema } from 'json-schema-typed';
 export type OAuthState = {
@@ -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>>;
@@ -48,13 +93,25 @@ export type EntityRecord = Record<string, unknown> & {
     sourceService: string;
     sourceID: string;
 };
+export type FetchedEntity = {
+    present: true;
+    record: EntityRecord;
+    sourceFetchHLC: string;
+} | {
+    present: false;
+    sourceID: string;
+    sourceFetchHLC: string;
+};
+export type FetchedPresentEntity = Extract<FetchedEntity, {
+    present: true;
+}>;
+export type FetchedAbsentEntity = Extract<FetchedEntity, {
+    present: false;
+}>;
 export type EntityBatch = {
     modelID: string;
-    entities: Array<EntityRecord>;
-    deleted?: Array<{
-        sourceService: string;
-        sourceID: string;
-    }>;
+    entities: Array<FetchedPresentEntity>;
+    deleted?: Array<FetchedAbsentEntity>;
     checkpoint?: unknown;
     hasMore: boolean;
 };
@@ -66,9 +123,30 @@ export type FetchParams = {
 export type FetchChangesParams = FetchParams & {
     lastSyncedAt?: Date;
 };
+export type ReconcileResult = (FetchedPresentEntity & {
+    providerETag?: string;
+}) | (FetchedAbsentEntity & {
+    providerETag?: string;
+});
+/**
+ * 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>;
+    fetchEntity(model: string, sourceID: string, snapshot: unknown): Promise<FetchedEntity>;
+    reconcile(model: string, sourceID: string, snapshot: unknown): Promise<ReconcileResult>;
     supportedStrategies: Array<'polling' | 'on-demand'>;
 };
 export type WebhookParams = {
@@ -107,6 +185,20 @@ export type ActionDefinition = {
     output?: JSONSchema.Object;
     entityModel?: string;
     requiresCredential: boolean;
+    recoveryClass: 'reissue-safe' | 'reconcile-only';
+    /**
+     * The field of the target document holding the provider's conditional-write
+     * token (e.g. an ETag) as last fetched. An update pins it on the operation
+     * at claim — read from the local document, never re-fetched before the
+     * write — and hands it to the handler as `ActionWriteContext.providerETag`.
+     */
+    providerETagField?: string;
+    /**
+     * The provider writes only against that token: an update whose target
+     * document holds none is refused before the operation is claimed (a sync
+     * first provides it), rather than claimed and then dead-lettered.
+     */
+    providerETagRequired?: boolean;
 };
 export type ActionResult = {
     raw?: Record<string, unknown>;
@@ -119,21 +211,123 @@ export type WriteAttachment = (input: ReadableStream<Uint8Array>, options?: {
     encrypted?: boolean;
     keyID?: string;
 }) => Promise<string>;
+export type ActionWriteResult = FetchedPresentEntity & {
+    providerETag?: string;
+    localChange?: boolean;
+};
+/** What the write-back layer knows about the operation a write belongs to. */
+export type ActionWriteContext = {
+    /**
+     * The caller-derived deterministic identity of the intent the write carries
+     * (the operation envelope's `deterministicEventID`), the same on every
+     * attempt of the operation. A connector whose provider accepts a
+     * caller-chosen resource id derives that id from it, so a create re-issued
+     * after a lost response collides with its own earlier effect instead of
+     * duplicating it.
+     */
+    deterministicEventID: string;
+    /**
+     * The provider's conditional-write token (e.g. an ETag) for the state the
+     * write is based on, as captured when that state was fetched and pinned on
+     * the operation at claim (see `ActionDefinition.providerETagField`). An
+     * update writes conditionally on it, so a provider change since then fails
+     * the write instead of being overwritten. Absent when unknown.
+     */
+    providerETag?: string | null;
+};
 export type ActionHandler = {
-    create(model: string, params: Record<string, unknown>): Promise<EntityRecord>;
-    update(model: string, sourceID: string, params: Record<string, unknown>, existing?: Record<string, unknown>): Promise<EntityRecord>;
+    create(model: string, params: Record<string, unknown>, context?: ActionWriteContext): Promise<ActionWriteResult>;
+    update(model: string, sourceID: string, params: Record<string, unknown>, existing?: Record<string, unknown>, context?: ActionWriteContext): Promise<ActionWriteResult>;
 };
 export type ActionHandlerFactory = (config: {
     credential: Credential;
     writeAttachment?: WriteAttachment;
+    mintFetchHLC: () => string;
 }) => ActionHandler;
 export type ServerProviderFactory = (config: {
     credential: unknown;
     boundary: SyncBoundary;
+    mintFetchHLC: () => string;
 }) => ServerDataProvider;
 export type ClientProviderFactory = (config: {
     boundary: SyncBoundary;
 }) => ClientDataProvider;
+/** A write's intent and a provider record, in the forms they are compared in. */
+export type IntentComparison = {
+    intent: Record<string, unknown>;
+    record: Record<string, unknown>;
+};
+/**
+ * Brings a write's intent and a provider record into the forms the provider
+ * normalizes to, so a record that holds the intent compares equal field by
+ * field (e.g. a date-time the provider re-renders in another offset). Only an
+ * equivalence the provider guarantees may be folded in: anything looser would
+ * confirm an effect that never happened. `null` means the record cannot hold
+ * the intent at all.
+ */
+export type IntentCanonicalizer = (params: {
+    model: string;
+    op: 'create' | 'update';
+    intent: Record<string, unknown>;
+    record: EntityRecord;
+}) => IntentComparison | null;
+/**
+ * Carries the device-local annotations of an existing document into an
+ * incoming provider record that does not author them — e.g. an imported
+ * attachment's `blob`, nested in attachment metadata the provider does author
+ * — so a later provider write of the entity keeps them. Only local
+ * annotations may be carried over, never a provider-authored value.
+ */
+export type LocalAnnotationMerger = (params: {
+    model: string;
+    incoming: EntityRecord;
+    existing: Record<string, unknown>;
+}) => EntityRecord;
+/** Storage-only reads available to an {@link ActionTargetResolver}. */
+export type ActionTargetStorage = {
+    /**
+     * The acting owner's live documents of one of this connector's models, as
+     * synced to this device (document data only). Never a provider call.
+     */
+    documents(model: string): Promise<Array<Record<string, unknown>>>;
+};
+/** The canonical target of a write and the input it is written with. */
+export type ResolvedActionTarget = {
+    /** The canonical provider target the write lands in (pinned on the operation). */
+    target: string;
+    /** The action input with any alias replaced by what it resolved to. */
+    input: Record<string, unknown>;
+};
+/**
+ * Derives the canonical target of a write from its own action input, before
+ * the operation is claimed and with storage-only access: an alias (a
+ * provider's "primary", say) is resolved from locally synced data, never by a
+ * provider call. The resolved input is what the operation pins and what the
+ * handler writes with. Throws a coded error when the target cannot be
+ * resolved locally.
+ */
+export type ActionTargetResolver = (params: {
+    model: string;
+    op: 'create' | 'update';
+    input: Record<string, unknown>;
+    sourceID?: string;
+    /** The provider account of the stored credential the write will spend. */
+    providerAccount: ProviderAccount;
+    storage: ActionTargetStorage;
+}) => Promise<ResolvedActionTarget>;
+/**
+ * Predicts, from a create's resolved input and its operation's deterministic
+ * event id alone (no storage, no provider call), the provider id the created
+ * entity will be stored under — for a provider whose create inserts under a
+ * caller-chosen id. `null` when the provider assigns the id itself, or when
+ * the input does not determine it. Every attempt of the operation must end
+ * up under the predicted id.
+ */
+export type CreatedSourceIDPredictor = (params: {
+    model: string;
+    input: Record<string, unknown>;
+    deterministicEventID: string;
+}) => string | null;
 export type ConnectorDefinition = {
     name: string;
     version: string;
@@ -141,6 +335,27 @@ export type ConnectorDefinition = {
     syncStrategies: Array<'polling' | 'webhook' | 'on-demand'>;
     actions?: Array<ActionDefinition>;
     actionHandler?: ActionHandlerFactory;
+    /**
+     * How write-back recovery compares an operation's intent against the
+     * provider resource that should hold it. Absent, values compare exactly.
+     */
+    canonicalizeIntent?: IntentCanonicalizer;
+    /**
+     * Applied to every provider record projected onto an existing document
+     * (sync, verification re-pull, an action's write result).
+     */
+    mergeLocalAnnotations?: LocalAnnotationMerger;
+    /**
+     * How a write's canonical target is derived from its input. Absent, the
+     * caller must name it as a generic `input.target`.
+     */
+    resolveActionTarget?: ActionTargetResolver;
+    /**
+     * The provider id a create will be stored under, when the connector chooses
+     * it (see {@link CreatedSourceIDPredictor}). Absent, a create's document is
+     * known only once the write commits.
+     */
+    predictCreatedSourceID?: CreatedSourceIDPredictor;
     serverProvider?: ServerProviderFactory;
     clientProvider?: ClientProviderFactory;
     graphql?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/connector",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,8 +15,8 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/credential-types": "^0.17.0",
-    "@kubun/protocol": "^0.17.0",
+    "@kubun/credential-types": "^0.17.2",
+    "@kubun/protocol": "^0.17.1",
     "@kubun/scalars": "^0.17.0",
     "json-schema-typed": "^8.0.2"
   },