@kubun/connector 0.17.1 → 0.17.3

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,7 @@
+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, 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';
+export { type FetchOrAbsentOptions, fetchOrAbsent, isNotFoundError, parseMaxAgeDays, type TargetedRead, } from './provider-utils.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,6 @@
+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';
+export { fetchOrAbsent, isNotFoundError, parseMaxAgeDays } from './provider-utils.js';

package/lib/provider-utils.d.ts

@@ -0,0 +1,13 @@
+import type { EntityRecord, ReconcileResult, SyncBoundary } from './types.js';
+export type TargetedRead = {
+    record: EntityRecord;
+    providerETag?: string;
+};
+export type FetchOrAbsentOptions = {
+    sourceID: string;
+    sourceFetchHLC: string;
+    read: () => Promise<TargetedRead>;
+};
+export declare function isNotFoundError(err: unknown): boolean;
+export declare function fetchOrAbsent(options: FetchOrAbsentOptions): Promise<ReconcileResult>;
+export declare function parseMaxAgeDays(boundary: SyncBoundary | undefined): number | null;

package/lib/provider-utils.js

@@ -0,0 +1,29 @@
+export function isNotFoundError(err) {
+    return err?.httpStatus === 404;
+}
+export async function fetchOrAbsent(options) {
+    try {
+        const { record, providerETag } = await options.read();
+        return {
+            present: true,
+            record,
+            sourceFetchHLC: options.sourceFetchHLC,
+            ...providerETag != null ? {
+                providerETag
+            } : {}
+        };
+    } catch (err) {
+        if (isNotFoundError(err)) {
+            return {
+                present: false,
+                sourceID: options.sourceID,
+                sourceFetchHLC: options.sourceFetchHLC
+            };
+        }
+        throw err;
+    }
+}
+export function parseMaxAgeDays(boundary) {
+    const match = boundary?.maxAge != null ? /^P(\d+)D$/i.exec(boundary.maxAge) : null;
+    return match?.[1] != null ? Number.parseInt(match[1], 10) : null;
+}

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 = {
@@ -93,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;
 };
@@ -111,6 +123,11 @@ 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`.
  *
@@ -128,6 +145,8 @@ export type FetchChangesParams = FetchParams & {
 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 = {
@@ -166,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>;
@@ -178,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;
@@ -200,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.1",
+  "version": "0.17.3",
   "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.2",
     "@kubun/scalars": "^0.17.0",
     "json-schema-typed": "^8.0.2"
   },