@superdurable/connectors-sdk 0.0.0-stage → 0.1.0

package/dist/chunk-KD5DYYSU.js

@@ -0,0 +1,93 @@
+import {
+  ConnectionRefSchema,
+  OperationRefSchema,
+  deriveCallID
+} from "./chunk-SOXYPIMO.js";
+
+// src/credentials.ts
+function createCall(context, connection, operation, options = {}) {
+  if (!context?.flowId) throw new TypeError("Dex Flow ID is required");
+  if (!context.stepExecutionId) throw new TypeError("connector operations require a Dex Step execution; RPC invocation is not allowed");
+  ConnectionRefSchema.parse(connection);
+  OperationRefSchema.parse(operation);
+  const call = { context, id: deriveCallID(context.flowId, context.stepExecutionId, operation), connection, operation };
+  const textWriter = options.textStream?.bufferedText(context, options.textOptions);
+  let sequence = 0;
+  Object.defineProperty(call, "context", { value: context, enumerable: false });
+  Object.defineProperties(call, {
+    reportProgress: { value: (progress) => {
+      if (!options.progressStream) return;
+      if (progress.percent !== void 0 && (!Number.isFinite(progress.percent) || progress.percent < 0 || progress.percent > 1)) throw new RangeError("connector progress percent must be between 0 and 1");
+      options.progressStream.write(context, { ...progress, callId: call.id, attempt: context.attempt, sequence: ++sequence });
+    }, enumerable: false },
+    writeText: { value: (value) => {
+      textWriter?.write(value);
+    }, enumerable: false },
+    hasProgressStream: { value: () => options.progressStream !== void 0, enumerable: false },
+    hasTextStream: { value: () => textWriter !== void 0, enumerable: false }
+  });
+  return call;
+}
+async function resolveCredential(provider, call, driver, signal) {
+  if (!provider) throw new TypeError("credential provider is required");
+  if (!driver) throw new TypeError("credential refresh driver is required");
+  if ("resolveWithRefresh" in provider && typeof provider.resolveWithRefresh === "function") {
+    return provider.resolveWithRefresh(call, driver, signal);
+  }
+  if (signal && "resolveContext" in provider && typeof provider.resolveContext === "function") {
+    return provider.resolveContext(call, signal);
+  }
+  return provider.resolve(call, signal);
+}
+async function resolveCredentialAfterRejection(provider, call, driver, signal) {
+  if (!provider) throw new TypeError("credential provider is required");
+  if (!driver) throw new TypeError("credential refresh driver is required");
+  if (!("resolveAfterRejection" in provider) || typeof provider.resolveAfterRejection !== "function") {
+    throw new TypeError("credential provider does not support refresh after rejection");
+  }
+  return provider.resolveAfterRejection(call, driver, signal);
+}
+var StaticCredentialProvider = class {
+  #credentials;
+  /** Capture all connection values during construction. */
+  constructor(entries) {
+    this.#credentials = new Map(Array.from(entries, ([connection, credential]) => [JSON.stringify([connection.provider, connection.name]), credential]));
+  }
+  /** Return the configured credential or reject a missing connection. */
+  async resolve(call) {
+    const key = JSON.stringify([call.connection.provider, call.connection.name]);
+    if (!this.#credentials.has(key)) throw new Error("connection is not configured");
+    return this.#credentials.get(key);
+  }
+  /** Static credentials never expire and therefore do not call the driver. */
+  async resolveWithRefresh(call) {
+    return this.resolve(call);
+  }
+};
+var SecretString = class {
+  #value;
+  /** Hold one private value outside default stringification and inspection. */
+  constructor(value) {
+    this.#value = value;
+  }
+  /** Reveal only at the provider request boundary. */
+  reveal() {
+    return this.#value;
+  }
+  /** Return a fixed redaction for accidental string formatting. */
+  toString() {
+    return "[REDACTED]";
+  }
+  /** Reject accidental JSON persistence. */
+  toJSON() {
+    throw new TypeError("connector secrets cannot be serialized");
+  }
+};
+
+export {
+  createCall,
+  resolveCredential,
+  resolveCredentialAfterRejection,
+  StaticCredentialProvider,
+  SecretString
+};

package/dist/chunk-SOXYPIMO.js

@@ -0,0 +1,179 @@
+// src/errors.ts
+import { z } from "zod";
+var FailureKindSchema = z.enum([
+  "VALIDATION",
+  "AUTHENTICATION",
+  "AUTHORIZATION",
+  "NOT_FOUND",
+  "CONFLICT",
+  "RATE_LIMIT",
+  "QUOTA_EXHAUSTED",
+  "AVAILABILITY",
+  "PROVIDER_REJECTION",
+  "TRANSPORT",
+  "RESPONSE_TOO_LARGE",
+  "PROTOCOL",
+  "LOCAL_DEFECT"
+]);
+var FailureSchema = z.strictObject({ kind: FailureKindSchema, provider: z.string().min(1), operation: z.string().min(1), message: z.string().min(1) });
+var RetryError = class extends Error {
+  /** Validated provider fact behind the retry request. */
+  failure;
+  /** Provider-requested retry delay in milliseconds; zero uses the Step policy. */
+  retryAfterMs;
+  constructor(failure, retryAfterMs = 0) {
+    const validated = FailureSchema.parse(failure);
+    super(`connector ${validated.provider} ${validated.operation} retry (${validated.kind}): ${validated.message}`);
+    this.name = "RetryError";
+    this.failure = validated;
+    this.retryAfterMs = retryAfterMs;
+  }
+};
+var ReauthorizationRequiredError = class extends Error {
+  constructor() {
+    super("connector reauthorization is required");
+    this.name = "ReauthorizationRequiredError";
+  }
+};
+
+// src/types.ts
+import { z as z2 } from "zod";
+import { createHash } from "crypto";
+var CallIDSchema = z2.uuid();
+var CallIDNamespace = "63281a42-70ad-5bc3-a289-728819af723f";
+var ConnectionRefSchema = z2.strictObject({ provider: z2.string().refine((value) => value.trim().length > 0), name: z2.string().refine((value) => value.trim().length > 0) });
+var OperationRefSchema = z2.strictObject({ connectorId: z2.string().regex(/^[a-z][a-z0-9-]{1,62}$/), operationId: z2.string().regex(/^[a-z][A-Za-z0-9]+$/) });
+function deriveCallID(flowId, stepExecutionId, operation) {
+  OperationRefSchema.parse(operation);
+  const namespace = CallIDNamespace;
+  const fields = [flowId, stepExecutionId, operation.connectorId, operation.operationId];
+  const payload = Buffer.concat(fields.flatMap((field) => {
+    const encoded = Buffer.from(field, "utf8");
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(encoded.length);
+    return [length, encoded];
+  }));
+  return CallIDSchema.parse(uuidSHA1(namespace, payload));
+}
+function defaultIdempotencyKey(callId) {
+  return callId;
+}
+function uuidSHA1(namespace, name) {
+  const namespaceBytes = Buffer.from(namespace.replaceAll("-", ""), "hex");
+  const digest = createHash("sha1").update(namespaceBytes).update(name).digest();
+  digest[6] = (digest[6] ?? 0) & 15 | 80;
+  digest[8] = (digest[8] ?? 0) & 63 | 128;
+  const hex = digest.subarray(0, 16).toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+var DefectBranchID = "defect";
+var UncertainBranchID = "uncertain";
+var BranchDefinitionSchema = z2.strictObject({ id: z2.string().min(1), description: z2.string(), optional: z2.boolean().optional() });
+var StepDefaultsWireSchema = z2.strictObject({
+  executeMethodTimeout: z2.number().int().nonnegative(),
+  heartbeatTimeout: z2.number().int().nonnegative().optional(),
+  executeRetry: z2.strictObject({ InitialInterval: z2.number().int().nonnegative(), BackoffCoefficient: z2.number().positive(), MaximumInterval: z2.number().int().nonnegative(), MaximumAttempts: z2.number().int().nonnegative(), TotalDuration: z2.number().int().nonnegative() }).optional(),
+  executeDurability: z2.number().int()
+});
+var QueryDefinitionWireSchema = z2.strictObject({ operation: OperationRefSchema, branches: z2.array(BranchDefinitionSchema).nullable(), stepDefaults: StepDefaultsWireSchema });
+var MutationDefinitionWireSchema = QueryDefinitionWireSchema;
+var ReceiptSchema = z2.strictObject({
+  callId: CallIDSchema,
+  idempotencyKey: z2.string().optional(),
+  provider: z2.string().min(1),
+  providerObjectId: z2.string().optional(),
+  providerRequestId: z2.string().optional(),
+  observedAt: z2.iso.datetime({ offset: true }),
+  metadata: z2.record(z2.string(), z2.string()).optional()
+});
+function zeroReceipt() {
+  return { callId: "", provider: "", observedAt: "0001-01-01T00:00:00Z" };
+}
+var QueryResultSchema = (valueSchema) => z2.strictObject({ branch: z2.string().min(1), value: valueSchema, receipt: ReceiptSchema, failure: FailureSchema.optional() });
+var MutationResultSchema = QueryResultSchema;
+function newQueryBranch(branch, value, receipt = {}, failure) {
+  return failure === void 0 ? { kind: "branch", branch, value, receipt } : { kind: "branch", branch, value, receipt, failure };
+}
+function newQueryRetry(failure, retryAfterMs = 0) {
+  validateRetryDelay(retryAfterMs);
+  return { kind: "retry", failure: FailureSchema.parse(failure), retryAfterMs };
+}
+function newMutationBranch(branch, value, receipt = {}, failure) {
+  return newQueryBranch(branch, value, receipt, failure);
+}
+function newMutationRetry(failure, retryAfterMs = 0) {
+  return newQueryRetry(failure, retryAfterMs);
+}
+function newMutationUncertain(value, failure, receipt = {}) {
+  return { kind: "uncertain", value, failure: FailureSchema.parse(failure), receipt };
+}
+function defaultConnectorStepExecuteRetryPolicy() {
+  return { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e5, maximumAttempts: 0, totalDurationMs: 36e5 };
+}
+function retryPolicyToGoWire(policy) {
+  return {
+    InitialInterval: policy.initialIntervalMs * 1e6,
+    BackoffCoefficient: policy.backoffCoefficient,
+    MaximumInterval: policy.maximumIntervalMs * 1e6,
+    MaximumAttempts: policy.maximumAttempts,
+    TotalDuration: policy.totalDurationMs * 1e6
+  };
+}
+var ConnectorUIBindingSchema = z2.strictObject({ port: z2.string().regex(/^[a-z][A-Za-z0-9]*$/), jsonPointer: z2.string().regex(/^\/(?:[^~]|~[01])*$/) });
+var ConnectorUIUnitSchema = z2.strictObject({
+  id: z2.string().regex(/^[a-z][A-Za-z0-9]*$/),
+  unitId: z2.string().regex(/^[a-z][A-Za-z0-9]*$/),
+  label: z2.string().refine((value) => value.trim().length > 0),
+  description: z2.string().refine((value) => value.trim().length > 0),
+  required: z2.boolean(),
+  bindings: z2.array(ConnectorUIBindingSchema).min(1)
+}).superRefine((unit, context) => {
+  if (new Set(unit.bindings.map((binding) => binding.port)).size !== unit.bindings.length) context.addIssue({ code: "custom", message: "duplicate UI port" });
+});
+var ConnectorConfigurationUISchema = z2.strictObject({ units: z2.array(ConnectorUIUnitSchema) }).superRefine((ui, context) => {
+  if (new Set(ui.units.map((unit) => unit.id)).size !== ui.units.length) context.addIssue({ code: "custom", message: "duplicate UI unit ID" });
+});
+var ConnectorConfigurationRefSchema = z2.strictObject({
+  connectorId: OperationRefSchema.shape.connectorId,
+  connectionName: z2.string().refine((value) => value.trim().length > 0),
+  operationId: OperationRefSchema.shape.operationId,
+  flowType: z2.string().refine((value) => value.trim().length > 0),
+  stepType: z2.string().refine((value) => value.trim().length > 0)
+});
+function validateRetryDelay(delayMs) {
+  if (!Number.isSafeInteger(delayMs) || delayMs < 0) throw new RangeError("retry delay must be a non-negative integer in milliseconds");
+}
+
+export {
+  FailureKindSchema,
+  FailureSchema,
+  RetryError,
+  ReauthorizationRequiredError,
+  CallIDSchema,
+  CallIDNamespace,
+  ConnectionRefSchema,
+  OperationRefSchema,
+  deriveCallID,
+  defaultIdempotencyKey,
+  DefectBranchID,
+  UncertainBranchID,
+  BranchDefinitionSchema,
+  StepDefaultsWireSchema,
+  QueryDefinitionWireSchema,
+  MutationDefinitionWireSchema,
+  ReceiptSchema,
+  zeroReceipt,
+  QueryResultSchema,
+  MutationResultSchema,
+  newQueryBranch,
+  newQueryRetry,
+  newMutationBranch,
+  newMutationRetry,
+  newMutationUncertain,
+  defaultConnectorStepExecuteRetryPolicy,
+  retryPolicyToGoWire,
+  ConnectorUIBindingSchema,
+  ConnectorUIUnitSchema,
+  ConnectorConfigurationUISchema,
+  ConnectorConfigurationRefSchema
+};

package/dist/connectormock/index.d.ts

@@ -0,0 +1,181 @@
+import { z } from 'zod';
+import { F as Failure, B as BranchID, C as Call, M as MutationAttempt, Q as QueryAttempt, U as UncertainBranchID, a as CallID } from '../credentials-vrvW0d4j.js';
+import { Q as QueryDefinition, M as Mutation, a as MutationDefinition, b as Query } from '../operation-Ca8rfacf.js';
+import '@superdurable/dex';
+
+/** One answered mock call, including input only in test memory. */
+interface MockCall<Input> extends RecordedCall {
+    /** Provider-safe idempotency key selected by the SDK. */ idempotencyKey?: string;
+    /** Input observed by the mock. */ input: Input;
+}
+/** Constructor-injected checks for a scripted connector operation. */
+interface MockOptions<Input, Output> {
+    /** Return a safe failure to select defect before case selection. */ requestCheck?: (input: Input) => Failure | undefined;
+    /** Validate a selected success branch against the request. */ answerCheck?: {
+        branch: BranchID;
+        check: (input: Input, output: Output) => void;
+    };
+    /** Receive scripting mistakes and unscripted-call reports. */ onFailure?: (message: string) => void;
+}
+interface Rule<Input, Output> {
+    matches: (input: Input) => boolean;
+    response: Case<Output>;
+}
+declare class Script<Input, Output> {
+    readonly rules: Rule<Input, Output>[];
+    readonly queue: Case<Output>[];
+    defaults: Case<Output>[];
+    defaultCount: number;
+    nextScripted(input: Input): Case<Output> | undefined;
+    nextDefault(): Case<Output> | undefined;
+}
+/** Per-Flow script whose longer matching prefixes take precedence. */
+declare class FlowScript<Input, Output> {
+    #private;
+    /** Capture one Flow prefix and its owning operation. */
+    constructor(owner: ScriptedOperation<Input, Output>, script: Script<Input, Output>);
+    /** Queue one case per matching call. */
+    respond(...cases: Case<Output>[]): this;
+    /** Use a persistent input predicate before queued cases. */
+    when(matches: (input: Input) => boolean, response: Case<Output>): this;
+    /** Replace fallback cases; the last case repeats. */
+    default(...cases: Case<Output>[]): this;
+}
+interface ResolvedCase<Output> {
+    response: Case<Output>;
+    branch?: BranchID;
+    isReplay?: boolean;
+    isUnscripted?: boolean;
+}
+/** Shared script, call log, and idempotency memory for one operation mock. */
+declare class ScriptedOperation<Input, Output> {
+    #private;
+    /** Validate the real operation definition and capture test checks. */
+    constructor(definition: QueryDefinition, isMutation: boolean, options?: MockOptions<Input, Output>);
+    /** Queue cases on the unscoped script. */
+    respond(...cases: Case<Output>[]): this;
+    /** Add a persistent input predicate on the unscoped script. */
+    when(matches: (input: Input) => boolean, response: Case<Output>): this;
+    /** Replace unscoped fallback cases; the last repeats. */
+    default(...cases: Case<Output>[]): this;
+    /** Require a Respond or When case for every call, ignoring all defaults. */
+    strict(): this;
+    /** Select a script by exact Flow ID or prefix; longest prefixes win. */
+    forFlow(flowIdOrPrefix: string): FlowScript<Input, Output>;
+    /** Copy answered calls in answer order, including retries and replays. */
+    calls(): MockCall<Input>[];
+    /** Copy scripting errors; callers can assert after a real Flow completes. */
+    failures(): string[];
+    /** Throw after integration verification if a script was invalid or unscripted. */
+    assertNoFailures(): void;
+    /** Add validated ordered responses to a script. */
+    addResponses(script: Script<Input, Output>, cases: readonly Case<Output>[]): void;
+    /** Add a validated persistent predicate to a script. */
+    addRule(script: Script<Input, Output>, matches: (input: Input) => boolean, response: Case<Output>): void;
+    /** Replace a script's fallback cases. */
+    setDefaults(script: Script<Input, Output>, cases: readonly Case<Output>[]): void;
+    /** Answer one real SDK invocation and record its safe outcome. */
+    answer(call: Call, input: Input, idempotencyKey: string): ResolvedCase<Output>;
+}
+/** Scripted query that implements the same invoke contract as a provider query. */
+declare class MockQuery<Input, Output> extends ScriptedOperation<Input, Output> implements Query<Input, Output> {
+    #private;
+    /** Construct from the real query definition. */
+    constructor(definition: QueryDefinition, options?: MockOptions<Input, Output>);
+    /** Return the real query definition. */ definition(): QueryDefinition;
+    /** Answer one query call from the script. */
+    invoke(call: Call, input: Input): QueryAttempt<Output>;
+}
+/** Scripted mutation with provider-like terminal idempotency replay. */
+declare class MockMutation<Input, Output> extends ScriptedOperation<Input, Output> implements Mutation<Input, Output> {
+    #private;
+    /** Construct from the real mutation definition. */
+    constructor(definition: MutationDefinition, options?: MockOptions<Input, Output>);
+    /** Return the real mutation definition. */ definition(): MutationDefinition;
+    /** Use the stable SDK call ID as the provider deduplication key. */ idempotencyKey(callId: string): string;
+    /** Answer one mutation call and remember terminal outcomes by key. */
+    invoke(call: Call, input: Input): MutationAttempt<Output>;
+}
+/** Construct a scripted query from a real operation definition. */
+declare function newQuery<Input, Output>(definition: QueryDefinition, options?: MockOptions<Input, Output>): MockQuery<Input, Output>;
+/** Construct a scripted mutation from a real operation definition. */
+declare function newMutation<Input, Output>(definition: MutationDefinition, options?: MockOptions<Input, Output>): MockMutation<Input, Output>;
+
+/** Environment variable that enables the test harness call report. */
+declare const ReportDirectoryEnvironment = "DEX_CONNECTOR_MOCK_REPORT_DIR";
+/** Report file consumed by the connector test harness. */
+declare const ReportFileName = "connector-calls.json";
+/** One scripted provider outcome independent of a Dex Step. */
+type Case<T> = {
+    readonly kind: 'branch';
+    readonly branch: BranchID;
+    readonly value: T;
+    readonly failure?: Failure;
+} | {
+    readonly kind: 'retry';
+    readonly failure: Failure;
+    readonly retryAfterMs: number;
+} | {
+    readonly kind: 'uncertain';
+    readonly branch: typeof UncertainBranchID;
+    readonly value: T;
+    readonly failure: Failure;
+};
+/** Construct a terminal branch case. */
+declare function branchCase<T>(branch: BranchID, value: T, failure?: Failure): Case<T>;
+/** Construct a retry case; another scripted case answers the next attempt. */
+declare function retryCase<T>(failure: Failure, retryAfterMs?: number): Case<T>;
+/** Construct an unsafe, unconfirmable mutation case. */
+declare function uncertainCase<T>(value: T, failure: Failure): Case<T>;
+/** One provider call answered by a mock, with Go-compatible report fields. */
+declare const RecordedCallSchema: z.ZodObject<{
+    connectorId: z.ZodString;
+    operationId: z.ZodString;
+    connectionName: z.ZodString;
+    flowId: z.ZodString;
+    callId: z.ZodUUID;
+    branch: z.ZodOptional<z.ZodString>;
+    retry: z.ZodOptional<z.ZodBoolean>;
+    replay: z.ZodOptional<z.ZodBoolean>;
+    unscripted: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/** One fixture-backed provider call. */
+type RecordedCall = z.infer<typeof RecordedCallSchema> & {
+    callId: CallID;
+};
+/** Wire format of the mock call report. */
+declare const ReportRowSchema: z.ZodObject<{
+    connection: z.ZodString;
+    operation: z.ZodString;
+    branch: z.ZodOptional<z.ZodString>;
+    connectorId: z.ZodString;
+    flowId: z.ZodOptional<z.ZodString>;
+    callId: z.ZodOptional<z.ZodString>;
+    retry: z.ZodOptional<z.ZodBoolean>;
+    replay: z.ZodOptional<z.ZodBoolean>;
+    unscripted: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/** Wire format of the complete mock call report. */
+declare const CallReportSchema: z.ZodObject<{
+    calls: z.ZodArray<z.ZodObject<{
+        connection: z.ZodString;
+        operation: z.ZodString;
+        branch: z.ZodOptional<z.ZodString>;
+        connectorId: z.ZodString;
+        flowId: z.ZodOptional<z.ZodString>;
+        callId: z.ZodOptional<z.ZodString>;
+        retry: z.ZodOptional<z.ZodBoolean>;
+        replay: z.ZodOptional<z.ZodBoolean>;
+        unscripted: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Safe report of connector mock calls. */
+type CallReport = z.infer<typeof CallReportSchema>;
+/** Decode one strict JSON fixture and validate it against the output schema. */
+declare function decodeOutput<T>(encoded: string, outputSchema: z.ZodType<T>): T;
+/** Load a private test fixture from disk and validate its complete shape. */
+declare function loadOutputFixture<T>(path: string, outputSchema: z.ZodType<T>): Promise<T>;
+/** Decode a Go-compatible call report without exposing test input values. */
+declare function decodeCallReport(encoded: string): CallReport;
+
+export { type CallReport, CallReportSchema, type Case, FlowScript, type MockCall, MockMutation, type MockOptions, MockQuery, type RecordedCall, RecordedCallSchema, ReportDirectoryEnvironment, ReportFileName, ReportRowSchema, branchCase, decodeCallReport, decodeOutput, loadOutputFixture, newMutation, newQuery, retryCase, uncertainCase };