@superdurable/connectors-sdk 0.0.0-stage → 0.1.0

package/dist/credentials-vrvW0d4j.d.ts

@@ -0,0 +1,445 @@
+import { z } from 'zod';
+import { AsyncContext, Stream, BufferedTextStreamOptions } from '@superdurable/dex';
+
+/** Provider or local fact independent of retry policy. */
+declare const FailureKindSchema: z.ZodEnum<{
+    VALIDATION: "VALIDATION";
+    AUTHENTICATION: "AUTHENTICATION";
+    AUTHORIZATION: "AUTHORIZATION";
+    NOT_FOUND: "NOT_FOUND";
+    CONFLICT: "CONFLICT";
+    RATE_LIMIT: "RATE_LIMIT";
+    QUOTA_EXHAUSTED: "QUOTA_EXHAUSTED";
+    AVAILABILITY: "AVAILABILITY";
+    PROVIDER_REJECTION: "PROVIDER_REJECTION";
+    TRANSPORT: "TRANSPORT";
+    RESPONSE_TOO_LARGE: "RESPONSE_TOO_LARGE";
+    PROTOCOL: "PROTOCOL";
+    LOCAL_DEFECT: "LOCAL_DEFECT";
+}>;
+/** Provider-neutral failure category. */
+type FailureKind = z.infer<typeof FailureKindSchema>;
+/** Secret-safe failure that may be persisted in a Flow. */
+declare const FailureSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        VALIDATION: "VALIDATION";
+        AUTHENTICATION: "AUTHENTICATION";
+        AUTHORIZATION: "AUTHORIZATION";
+        NOT_FOUND: "NOT_FOUND";
+        CONFLICT: "CONFLICT";
+        RATE_LIMIT: "RATE_LIMIT";
+        QUOTA_EXHAUSTED: "QUOTA_EXHAUSTED";
+        AVAILABILITY: "AVAILABILITY";
+        PROVIDER_REJECTION: "PROVIDER_REJECTION";
+        TRANSPORT: "TRANSPORT";
+        RESPONSE_TOO_LARGE: "RESPONSE_TOO_LARGE";
+        PROTOCOL: "PROTOCOL";
+        LOCAL_DEFECT: "LOCAL_DEFECT";
+    }>;
+    provider: z.ZodString;
+    operation: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strict>;
+/** Safe provider failure without secret-bearing details. */
+type Failure = z.infer<typeof FailureSchema>;
+/** The only connector error that requests a Dex Step retry. */
+declare class RetryError extends Error {
+    /** Validated provider fact behind the retry request. */
+    readonly failure: Failure;
+    /** Provider-requested retry delay in milliseconds; zero uses the Step policy. */
+    readonly retryAfterMs: number;
+    constructor(failure: Failure, retryAfterMs?: number);
+}
+/** Terminal credential failure requiring interactive authorization. */
+declare class ReauthorizationRequiredError extends Error {
+    constructor();
+}
+
+/** Stable UUID for one provider call across Dex retries. */
+declare const CallIDSchema: z.ZodUUID;
+/** Stable UUID identity for one provider call. */
+type CallID = z.infer<typeof CallIDSchema>;
+/** UUIDv5 namespace shared with sdkgo for call derivation. */
+declare const CallIDNamespace = "63281a42-70ad-5bc3-a289-728819af723f";
+/** Provider-safe stable deduplication key. */
+type IdempotencyKey = string;
+/** Logical credential reference safe to persist in a Flow. */
+declare const ConnectionRefSchema: z.ZodObject<{
+    provider: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strict>;
+/** Logical credential identity safe for Flow state. */
+type ConnectionRef = z.infer<typeof ConnectionRefSchema>;
+/** Stable manifest identity of a connector operation. */
+declare const OperationRefSchema: z.ZodObject<{
+    connectorId: z.ZodString;
+    operationId: z.ZodString;
+}, z.core.$strict>;
+/** Manifest operation identity. */
+type OperationRef = z.infer<typeof OperationRefSchema>;
+/** Derive the Go-compatible UUIDv5 identity from one Dex Step execution. */
+declare function deriveCallID(flowId: string, stepExecutionId: string, operation: OperationRef): CallID;
+/** Provider key fallback for an empty operation-specific idempotency key. */
+declare function defaultIdempotencyKey(callId: CallID): IdempotencyKey;
+/** Stable operation-defined process route. */
+type BranchID = string;
+/** Standard route for local connector defects. */
+declare const DefectBranchID: BranchID;
+/** Optional route for an unsafe, unconfirmable mutation outcome. */
+declare const UncertainBranchID: BranchID;
+/** One declared operation route; only the happy path is required. */
+declare const BranchDefinitionSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodString;
+    optional: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/** One declared operation branch. */
+type BranchDefinition = z.infer<typeof BranchDefinitionSchema>;
+/** Go-compatible Step defaults wire form; durations are nanoseconds. */
+declare const StepDefaultsWireSchema: z.ZodObject<{
+    executeMethodTimeout: z.ZodNumber;
+    heartbeatTimeout: z.ZodOptional<z.ZodNumber>;
+    executeRetry: z.ZodOptional<z.ZodObject<{
+        InitialInterval: z.ZodNumber;
+        BackoffCoefficient: z.ZodNumber;
+        MaximumInterval: z.ZodNumber;
+        MaximumAttempts: z.ZodNumber;
+        TotalDuration: z.ZodNumber;
+    }, z.core.$strict>>;
+    executeDurability: z.ZodNumber;
+}, z.core.$strict>;
+/** Wire defaults with durations in nanoseconds. */
+type StepDefaultsWire = z.infer<typeof StepDefaultsWireSchema>;
+/** Query operation definition shared with connector manifests. */
+declare const QueryDefinitionWireSchema: z.ZodObject<{
+    operation: z.ZodObject<{
+        connectorId: z.ZodString;
+        operationId: z.ZodString;
+    }, z.core.$strict>;
+    branches: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        optional: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    stepDefaults: z.ZodObject<{
+        executeMethodTimeout: z.ZodNumber;
+        heartbeatTimeout: z.ZodOptional<z.ZodNumber>;
+        executeRetry: z.ZodOptional<z.ZodObject<{
+            InitialInterval: z.ZodNumber;
+            BackoffCoefficient: z.ZodNumber;
+            MaximumInterval: z.ZodNumber;
+            MaximumAttempts: z.ZodNumber;
+            TotalDuration: z.ZodNumber;
+        }, z.core.$strict>>;
+        executeDurability: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** Query definition wire value. */
+type QueryDefinitionWire = z.infer<typeof QueryDefinitionWireSchema>;
+/** Mutation operation definition shared with connector manifests. */
+declare const MutationDefinitionWireSchema: z.ZodObject<{
+    operation: z.ZodObject<{
+        connectorId: z.ZodString;
+        operationId: z.ZodString;
+    }, z.core.$strict>;
+    branches: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        optional: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    stepDefaults: z.ZodObject<{
+        executeMethodTimeout: z.ZodNumber;
+        heartbeatTimeout: z.ZodOptional<z.ZodNumber>;
+        executeRetry: z.ZodOptional<z.ZodObject<{
+            InitialInterval: z.ZodNumber;
+            BackoffCoefficient: z.ZodNumber;
+            MaximumInterval: z.ZodNumber;
+            MaximumAttempts: z.ZodNumber;
+            TotalDuration: z.ZodNumber;
+        }, z.core.$strict>>;
+        executeDurability: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** Mutation definition wire value. */
+type MutationDefinitionWire = QueryDefinitionWire;
+/** Safe provider correlation data, never credential material. */
+declare const ReceiptSchema: z.ZodObject<{
+    callId: z.ZodUUID;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    provider: z.ZodString;
+    providerObjectId: z.ZodOptional<z.ZodString>;
+    providerRequestId: z.ZodOptional<z.ZodString>;
+    observedAt: z.ZodISODateTime;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+/** Safe provider correlation receipt. */
+type Receipt = z.infer<typeof ReceiptSchema>;
+/** Receipt fields an operation may supply before the SDK fills call metadata. */
+type ReceiptDraft = Partial<Receipt>;
+/** Go-compatible JSON representation of sdkgo.Receipt{} before call completion. */
+declare function zeroReceipt(): ReceiptDraft;
+/** Validated terminal query result with Go-compatible JSON field names. */
+declare const QueryResultSchema: <T>(valueSchema: z.ZodType<T>) => z.ZodObject<{
+    branch: z.ZodString;
+    value: z.ZodType<T, unknown, z.core.$ZodTypeInternals<T, unknown>>;
+    receipt: z.ZodObject<{
+        callId: z.ZodUUID;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+        provider: z.ZodString;
+        providerObjectId: z.ZodOptional<z.ZodString>;
+        providerRequestId: z.ZodOptional<z.ZodString>;
+        observedAt: z.ZodISODateTime;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>;
+    failure: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            VALIDATION: "VALIDATION";
+            AUTHENTICATION: "AUTHENTICATION";
+            AUTHORIZATION: "AUTHORIZATION";
+            NOT_FOUND: "NOT_FOUND";
+            CONFLICT: "CONFLICT";
+            RATE_LIMIT: "RATE_LIMIT";
+            QUOTA_EXHAUSTED: "QUOTA_EXHAUSTED";
+            AVAILABILITY: "AVAILABILITY";
+            PROVIDER_REJECTION: "PROVIDER_REJECTION";
+            TRANSPORT: "TRANSPORT";
+            RESPONSE_TOO_LARGE: "RESPONSE_TOO_LARGE";
+            PROTOCOL: "PROTOCOL";
+            LOCAL_DEFECT: "LOCAL_DEFECT";
+        }>;
+        provider: z.ZodString;
+        operation: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Terminal query value and its selected branch. */
+type QueryResult<T> = {
+    branch: BranchID;
+    value: T;
+    receipt: Receipt;
+    failure?: Failure;
+};
+/** Validated terminal mutation result with Go-compatible JSON field names. */
+declare const MutationResultSchema: <T>(valueSchema: z.ZodType<T>) => z.ZodObject<{
+    branch: z.ZodString;
+    value: z.ZodType<T, unknown, z.core.$ZodTypeInternals<T, unknown>>;
+    receipt: z.ZodObject<{
+        callId: z.ZodUUID;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+        provider: z.ZodString;
+        providerObjectId: z.ZodOptional<z.ZodString>;
+        providerRequestId: z.ZodOptional<z.ZodString>;
+        observedAt: z.ZodISODateTime;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>;
+    failure: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            VALIDATION: "VALIDATION";
+            AUTHENTICATION: "AUTHENTICATION";
+            AUTHORIZATION: "AUTHORIZATION";
+            NOT_FOUND: "NOT_FOUND";
+            CONFLICT: "CONFLICT";
+            RATE_LIMIT: "RATE_LIMIT";
+            QUOTA_EXHAUSTED: "QUOTA_EXHAUSTED";
+            AVAILABILITY: "AVAILABILITY";
+            PROVIDER_REJECTION: "PROVIDER_REJECTION";
+            TRANSPORT: "TRANSPORT";
+            RESPONSE_TOO_LARGE: "RESPONSE_TOO_LARGE";
+            PROTOCOL: "PROTOCOL";
+            LOCAL_DEFECT: "LOCAL_DEFECT";
+        }>;
+        provider: z.ZodString;
+        operation: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Terminal mutation value and its selected branch. */
+type MutationResult<T> = QueryResult<T>;
+/** One query invocation outcome; only constructors create valid attempts. */
+type QueryAttempt<T> = {
+    readonly kind: 'branch';
+    readonly branch: BranchID;
+    readonly value: T;
+    readonly receipt: ReceiptDraft;
+    readonly failure?: Failure;
+} | {
+    readonly kind: 'retry';
+    readonly failure: Failure;
+    readonly retryAfterMs: number;
+};
+/** One mutation invocation outcome; uncertainty is reserved for unsafe, unconfirmable writes. */
+type MutationAttempt<T> = QueryAttempt<T> | {
+    readonly kind: 'uncertain';
+    readonly value: T;
+    readonly receipt: ReceiptDraft;
+    readonly failure: Failure;
+};
+/** Construct a terminal query branch. */
+declare function newQueryBranch<T>(branch: BranchID, value: T, receipt?: ReceiptDraft, failure?: Failure): QueryAttempt<T>;
+/** Construct a retryable query failure with an optional provider delay in milliseconds. */
+declare function newQueryRetry<T>(failure: Failure, retryAfterMs?: number): QueryAttempt<T>;
+/** Construct a terminal mutation branch. */
+declare function newMutationBranch<T>(branch: BranchID, value: T, receipt?: ReceiptDraft, failure?: Failure): MutationAttempt<T>;
+/** Construct a retryable mutation failure when repeating the effect is safe. */
+declare function newMutationRetry<T>(failure: Failure, retryAfterMs?: number): MutationAttempt<T>;
+/** Construct an uncertain mutation only after proving repeat and read-back are unsafe. */
+declare function newMutationUncertain<T>(value: T, failure: Failure, receipt?: ReceiptDraft): MutationAttempt<T>;
+/** Dex Execute retry policy using millisecond durations. */
+interface RetryPolicy {
+    /** Delay before the first retry. */ initialIntervalMs: number;
+    /** Multiplier applied between attempts. */ backoffCoefficient: number;
+    /** Maximum delay between attempts. */ maximumIntervalMs: number;
+    /** Zero means unlimited attempts within total duration. */ maximumAttempts: number;
+    /** Overall bound including the first attempt. */ totalDurationMs: number;
+}
+/** Return a fresh one-hour connector retry policy. */
+declare function defaultConnectorStepExecuteRetryPolicy(): RetryPolicy;
+/** Encode the retry policy in Dex Go's nanosecond JSON wire form. */
+declare function retryPolicyToGoWire(policy: RetryPolicy): Record<string, number>;
+/** Connector-owned UI binding from a unit port to configuration JSON. */
+declare const ConnectorUIBindingSchema: z.ZodObject<{
+    port: z.ZodString;
+    jsonPointer: z.ZodString;
+}, z.core.$strict>;
+/** Bind a UI port to a configuration JSON pointer. */
+type ConnectorUIBinding = z.infer<typeof ConnectorUIBindingSchema>;
+/** Reusable connector UI unit with contextual guidance and ordered bindings. */
+declare const ConnectorUIUnitSchema: z.ZodObject<{
+    id: z.ZodString;
+    unitId: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodString;
+    required: z.ZodBoolean;
+    bindings: z.ZodArray<z.ZodObject<{
+        port: z.ZodString;
+        jsonPointer: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Contextual connector UI unit. */
+type ConnectorUIUnit = z.infer<typeof ConnectorUIUnitSchema>;
+/** Ordered connector-owned UI units composed by Dex Web. */
+declare const ConnectorConfigurationUISchema: z.ZodObject<{
+    units: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        unitId: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodString;
+        required: z.ZodBoolean;
+        bindings: z.ZodArray<z.ZodObject<{
+            port: z.ZodString;
+            jsonPointer: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Ordered connector UI configuration. */
+type ConnectorConfigurationUI = z.infer<typeof ConnectorConfigurationUISchema>;
+/** Stable Flow and Step use that owns one operation configuration. */
+declare const ConnectorConfigurationRefSchema: z.ZodObject<{
+    connectorId: z.ZodString;
+    connectionName: z.ZodString;
+    operationId: z.ZodString;
+    flowType: z.ZodString;
+    stepType: z.ZodString;
+}, z.core.$strict>;
+/** Stable Flow and Step configuration owner. */
+type ConnectorConfigurationRef = z.infer<typeof ConnectorConfigurationRefSchema>;
+
+/** Provider-safe progress before Dex identity and sequence are added. */
+interface Progress {
+    /** Provider-specific stable phase. */ phase: string;
+    /** Optional safe progress text. */ message?: string;
+    /** Optional inclusive fraction from zero to one. */ percent?: number;
+    /** Optional provider-owned monotonic sequence. */ providerSequence?: number;
+}
+/** Structured best-effort Dex Stream message. */
+interface ProgressUpdate extends Progress {
+    /** Stable connector call ID. */ callId: CallID;
+    /** One-based Dex Execute attempt. */ attempt: number;
+    /** Connector-assigned monotonic sequence within this attempt. */ sequence: number;
+}
+/** Optional application-owned Streams for one connector invocation. */
+interface CallProgressOptions {
+    /** Registered structured progress Stream. */ progressStream?: Stream<ProgressUpdate>;
+    /** Registered string Stream for ordered buffered text. */ textStream?: Stream<string>;
+    /** Flush interval and soft UTF-8 batch limit for text. */ textOptions?: BufferedTextStreamOptions;
+}
+/** Provider-safe call metadata with its live, non-serializable Dex Step context. */
+interface Call {
+    /** Active Dex Execute context; Step factories attach it as a non-enumerable field. */ context: AsyncContext;
+    /** Stable identity across retries. */ id: CallID;
+    /** Provider deduplication key, when available. */ idempotencyKey?: string;
+    /** Logical named connection. */ connection: ConnectionRef;
+    /** Manifest operation identity. */ operation: OperationRef;
+    /** Append structured progress when a Stream is configured. */ reportProgress(progress: Progress): void;
+    /** Append text in order when a buffered Stream is configured. */ writeText(value: string): void;
+    /** Whether structured progress output is configured. */ hasProgressStream(): boolean;
+    /** Whether buffered text output is configured. */ hasTextStream(): boolean;
+}
+/** Bind a live Dex Execute context to a stable, provider-safe call identity. */
+declare function createCall(context: AsyncContext, connection: ConnectionRef, operation: OperationRef, options?: CallProgressOptions): Call;
+/** Resolve a credential at call time outside durable Flow state. */
+interface CredentialProvider<C> {
+    /** Return current credentials, honoring cancellation. */
+    resolve(call: Call, signal?: AbortSignal): Promise<C>;
+}
+/** Resolve credentials outside a Dex Step, such as for a Trigger source. */
+interface ContextCredentialProvider<C> extends CredentialProvider<C> {
+    /** Return current credentials under an explicit cancellation signal. */
+    resolveContext(call: Call, signal: AbortSignal): Promise<C>;
+}
+/** Current private material and decision time for a refresh driver. */
+interface CredentialRefreshState<C> {
+    /** Current connector-specific credential. */ credentials: C;
+    /** Known access credential expiry. */ expiresAt?: Date;
+    /** Captured decision time. */ now: Date;
+}
+/** Complete replacement credential and mandatory access expiry. */
+interface CredentialRefreshResult<C> {
+    /** Complete replacement, retaining omitted renewal material. */ credentials: C;
+    /** Replacement access expiry. */ expiresAt: Date;
+}
+/** Connector-specific provider refresh contract; persistence belongs to the host. */
+interface CredentialRefreshDriver<C> {
+    /** Decide deterministically whether a credential needs provider renewal. */
+    refreshRequired(state: CredentialRefreshState<C>): boolean;
+    /** Make one provider refresh request after the host admits it durably. */
+    refresh(state: CredentialRefreshState<C>, signal: AbortSignal): Promise<CredentialRefreshResult<C>>;
+}
+/** Host adapter that refreshes and persists a connection atomically. */
+interface RefreshingCredentialProvider<C> extends CredentialProvider<C> {
+    /** Serialize refresh for one connection, reload state, and persist replacement. */
+    resolveWithRefresh(call: Call, driver: CredentialRefreshDriver<C>, signal?: AbortSignal): Promise<C>;
+}
+/** Host adapter for one explicit provider authentication rejection. */
+interface RejectedCredentialRefreshingProvider<C> {
+    /** Force one coordinated refresh after the provider rejects an access token. */
+    resolveAfterRejection(call: Call, driver: CredentialRefreshDriver<C>, signal?: AbortSignal): Promise<C>;
+}
+/** Resolve through host refresh support, then context-aware or ordinary lookup. */
+declare function resolveCredential<C>(provider: CredentialProvider<C>, call: Call, driver: CredentialRefreshDriver<C>, signal?: AbortSignal): Promise<C>;
+/** Force one coordinated refresh after a provider authentication rejection. */
+declare function resolveCredentialAfterRejection<C>(provider: CredentialProvider<C>, call: Call, driver: CredentialRefreshDriver<C>, signal?: AbortSignal): Promise<C>;
+/** In-memory named credentials for examples and tests; never persisted by this class. */
+declare class StaticCredentialProvider<C> implements RefreshingCredentialProvider<C> {
+    #private;
+    /** Capture all connection values during construction. */
+    constructor(entries: Iterable<readonly [ConnectionRef, C]>);
+    /** Return the configured credential or reject a missing connection. */
+    resolve(call: Call): Promise<C>;
+    /** Static credentials never expire and therefore do not call the driver. */
+    resolveWithRefresh(call: Call): Promise<C>;
+}
+/** Wrap a secret that cannot be serialized or printed. */
+declare class SecretString {
+    #private;
+    /** Hold one private value outside default stringification and inspection. */
+    constructor(value: string);
+    /** Reveal only at the provider request boundary. */
+    reveal(): string;
+    /** Return a fixed redaction for accidental string formatting. */
+    toString(): string;
+    /** Reject accidental JSON persistence. */
+    toJSON(): never;
+}
+
+export { StaticCredentialProvider as $, type MutationDefinitionWire as A, type BranchID as B, type Call as C, DefectBranchID as D, MutationDefinitionWireSchema as E, type Failure as F, MutationResultSchema as G, OperationRefSchema as H, type IdempotencyKey as I, type Progress as J, type QueryDefinitionWire as K, QueryDefinitionWireSchema as L, type MutationAttempt as M, QueryResultSchema as N, type OperationRef as O, type ProgressUpdate as P, type QueryAttempt as Q, ReauthorizationRequiredError as R, type Receipt as S, type ReceiptDraft as T, UncertainBranchID as U, ReceiptSchema as V, type RefreshingCredentialProvider as W, type RejectedCredentialRefreshingProvider as X, RetryError as Y, type RetryPolicy as Z, SecretString as _, type CallID as a, type StepDefaultsWire as a0, StepDefaultsWireSchema as a1, createCall as a2, defaultConnectorStepExecuteRetryPolicy as a3, defaultIdempotencyKey as a4, deriveCallID as a5, newMutationBranch as a6, newMutationRetry as a7, newMutationUncertain as a8, newQueryBranch as a9, newQueryRetry as aa, resolveCredential as ab, resolveCredentialAfterRejection as ac, retryPolicyToGoWire as ad, zeroReceipt as ae, type MutationResult as b, type QueryResult as c, type ConnectorConfigurationUI as d, type ConnectionRef as e, type BranchDefinition as f, BranchDefinitionSchema as g, CallIDNamespace as h, CallIDSchema as i, type CallProgressOptions as j, ConnectionRefSchema as k, type ConnectorConfigurationRef as l, ConnectorConfigurationRefSchema as m, ConnectorConfigurationUISchema as n, type ConnectorUIBinding as o, ConnectorUIBindingSchema as p, type ConnectorUIUnit as q, ConnectorUIUnitSchema as r, type ContextCredentialProvider as s, type CredentialProvider as t, type CredentialRefreshDriver as u, type CredentialRefreshResult as v, type CredentialRefreshState as w, type FailureKind as x, FailureKindSchema as y, FailureSchema as z };

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import { C as Call, b as MutationResult, c as QueryResult, d as ConnectorConfigurationUI, e as ConnectionRef, P as ProgressUpdate } from './credentials-vrvW0d4j.js';
+export { f as BranchDefinition, g as BranchDefinitionSchema, B as BranchID, a as CallID, h as CallIDNamespace, i as CallIDSchema, j as CallProgressOptions, k as ConnectionRefSchema, l as ConnectorConfigurationRef, m as ConnectorConfigurationRefSchema, n as ConnectorConfigurationUISchema, o as ConnectorUIBinding, p as ConnectorUIBindingSchema, q as ConnectorUIUnit, r as ConnectorUIUnitSchema, s as ContextCredentialProvider, t as CredentialProvider, u as CredentialRefreshDriver, v as CredentialRefreshResult, w as CredentialRefreshState, D as DefectBranchID, F as Failure, x as FailureKind, y as FailureKindSchema, z as FailureSchema, I as IdempotencyKey, M as MutationAttempt, A as MutationDefinitionWire, E as MutationDefinitionWireSchema, G as MutationResultSchema, O as OperationRef, H as OperationRefSchema, J as Progress, Q as QueryAttempt, K as QueryDefinitionWire, L as QueryDefinitionWireSchema, N as QueryResultSchema, R as ReauthorizationRequiredError, S as Receipt, T as ReceiptDraft, V as ReceiptSchema, W as RefreshingCredentialProvider, X as RejectedCredentialRefreshingProvider, Y as RetryError, Z as RetryPolicy, _ as SecretString, $ as StaticCredentialProvider, a0 as StepDefaultsWire, a1 as StepDefaultsWireSchema, U as UncertainBranchID, a2 as createCall, a3 as defaultConnectorStepExecuteRetryPolicy, a4 as defaultIdempotencyKey, a5 as deriveCallID, a6 as newMutationBranch, a7 as newMutationRetry, a8 as newMutationUncertain, a9 as newQueryBranch, aa as newQueryRetry, ab as resolveCredential, ac as resolveCredentialAfterRejection, ad as retryPolicyToGoWire, ae as zeroReceipt } from './credentials-vrvW0d4j.js';
+import { M as Mutation, b as Query } from './operation-Ca8rfacf.js';
+export { a as MutationDefinition, Q as QueryDefinition, S as StepDefaults, v as validateMutationDefinition, c as validateQueryDefinition } from './operation-Ca8rfacf.js';
+import { StepTarget, Step, Codec, Attribute, Stream, BufferedTextStreamOptions, StepOptions, AsyncContext, StepDecision, StepRef } from '@superdurable/dex';
+import 'zod';
+
+/** Invoke a query once and validate its provider-safe terminal result. */
+declare function runQuery<Input, Output>(operation: Query<Input, Output>, call: Call, input: Input): Promise<QueryResult<Output>>;
+/** Invoke a mutation once with its stable key and validate the classified outcome. */
+declare function runMutation<Input, Output>(operation: Mutation<Input, Output>, call: Call, input: Input): Promise<MutationResult<Output>>;
+
+/** Stable Dex authoring metadata for one Connector Step. */
+interface StepAnnotations {
+    /** Lowercase stable group identifier. */ groupId: string;
+    /** Human-readable group label. */ groupLabel: string;
+    /** One-sentence Step explanation. */ explanation: string;
+}
+/** Typed branch destination, including a registered Step instance or StepRef. */
+interface BranchTarget<Result> {
+    /** Declared operation branch. */ branch: string;
+    /** Destination; an omitted target is allowed only for an optional branch. */ target?: StepTarget<Result>;
+}
+/** Bind one declared branch to a registered Step destination. */
+declare function goToBranch<Result>(branch: string, target?: StepTarget<Result>): BranchTarget<Result>;
+/** Address a registered Step by stable type without constructing its implementation. */
+declare function stepRef(stepType: string): StepRef;
+/** Configure an advanced generic Query Step; operation-specific generated factories are preferred. */
+interface QueryStepConfig<StepInput, OperationInput, Output> {
+    /** Stable Dex Step type. */ stepType: string;
+    /** Group and explanation metadata. */ annotations: StepAnnotations;
+    /** Optional Connector Studio configuration UI. */ configurationUI?: ConnectorConfigurationUI;
+    /** Read-only provider operation. */ operation: Query<OperationInput, Output>;
+    /** Logical credential selection. */ connection: ConnectionRef;
+    /** Map the application's Step input to operation input. */ mapToOperationInput(input: StepInput): OperationInput;
+    /** Routes for every required branch and selected optional branches. */ branches: readonly BranchTarget<QueryResult<Output>>[];
+    /** Optional terminal result Attribute registered in the Flow schema. */ resultAttribute?: Attribute<QueryResult<Output>>;
+    /** Optional structured progress Stream registered in the Flow schema. */ progressStream?: Stream<ProgressUpdate>;
+    /** Optional buffered text Stream registered in the Flow schema. */ textStream?: Stream<string>;
+    /** Optional text batch sizing and flush interval. */ textOptions?: BufferedTextStreamOptions;
+    /** Optional codec for non-object Step input. */ inputCodec?: Codec<StepInput>;
+    /** Execute-only Dex options overriding manifest defaults. */ stepOptionsOverride?: StepOptions;
+}
+/** Configure an advanced generic Mutation Step. */
+interface MutationStepConfig<StepInput, OperationInput, Output> extends Omit<QueryStepConfig<StepInput, OperationInput, Output>, 'operation' | 'branches' | 'resultAttribute'> {
+    /** Provider write operation. */ operation: Mutation<OperationInput, Output>;
+    /** Routes for every required branch and selected optional branches. */ branches: readonly BranchTarget<MutationResult<Output>>[];
+    /** Optional terminal result Attribute registered in the Flow schema. */ resultAttribute?: Attribute<MutationResult<Output>>;
+}
+/** Query Step that invokes one provider operation per Dex Execute attempt. */
+declare class QueryStep<StepInput, OperationInput, Output> implements Step<StepInput> {
+    #private;
+    readonly inputCodec?: Codec<StepInput>;
+    /** Validate static wiring before registering the Step in a Flow. */
+    constructor(configuration: QueryStepConfig<StepInput, OperationInput, Output>);
+    /** Stable Dex Step type. */ getStepType(): string;
+    /** Isolated Execute options, including connector retry defaults. */ getStepOptions(): StepOptions;
+    /** Group metadata for Connector Studio. */ annotations(): StepAnnotations;
+    /** Isolated connector UI composition. */ configurationUI(): ConnectorConfigurationUI;
+    /** Invoke, persist the optional terminal Attribute, and route the selected branch. */
+    execute(context: AsyncContext, input: StepInput): Promise<StepDecision>;
+}
+/** Mutation Step that keeps stable provider identity across Dex retries. */
+declare class MutationStep<StepInput, OperationInput, Output> implements Step<StepInput> {
+    #private;
+    readonly inputCodec?: Codec<StepInput>;
+    /** Validate static wiring before registering the Step in a Flow. */
+    constructor(configuration: MutationStepConfig<StepInput, OperationInput, Output>);
+    /** Stable Dex Step type. */ getStepType(): string;
+    /** Isolated Execute options, including connector retry defaults. */ getStepOptions(): StepOptions;
+    /** Group metadata for Connector Studio. */ annotations(): StepAnnotations;
+    /** Isolated connector UI composition. */ configurationUI(): ConnectorConfigurationUI;
+    /** Invoke, persist the optional terminal Attribute, and route the selected branch. */
+    execute(context: AsyncContext, input: StepInput): Promise<StepDecision>;
+}
+/** Construct a Query Step after validating its static routing. */
+declare function newQueryStep<StepInput, OperationInput, Output>(configuration: QueryStepConfig<StepInput, OperationInput, Output>): QueryStep<StepInput, OperationInput, Output>;
+/** Construct a Mutation Step after validating its static routing. */
+declare function newMutationStep<StepInput, OperationInput, Output>(configuration: MutationStepConfig<StepInput, OperationInput, Output>): MutationStep<StepInput, OperationInput, Output>;
+
+export { type BranchTarget, Call, ConnectionRef, ConnectorConfigurationUI, Mutation, MutationResult, MutationStep, type MutationStepConfig, ProgressUpdate, Query, QueryResult, QueryStep, type QueryStepConfig, type StepAnnotations, goToBranch, newMutationStep, newQueryStep, runMutation, runQuery, stepRef };