@superdurable/connectors-sdk 0.0.0-stage → 0.1.1

package/dist/providerhttp/index.d.ts

@@ -0,0 +1,57 @@
+import http from 'node:http';
+
+/** Maximum body retained while extracting safe provider error tokens. */
+declare const MaxErrorBodyBytes: number;
+/** Maximum Retry-After delay, in milliseconds. */
+declare const MaxRetryAfterDelayMs: number;
+/** Response exceeded its caller-owned safety limit. */
+declare class BodyTooLargeError extends Error {
+    /** HTTP status available when a response body was being read. */ readonly status: number | undefined;
+    /** HTTP headers available when a response body was being read. */ readonly headers: http.IncomingHttpHeaders | undefined;
+    constructor(status?: number, headers?: http.IncomingHttpHeaders);
+}
+/** Address policy refused a request before transmission. */
+declare class AddressRefusal extends Error {
+    readonly reason: string;
+    /** Name a nonsecret network policy reason. */
+    constructor(reason: string);
+}
+/** Sanitized transport failure with positive evidence about dispatch. */
+declare class ProviderTransportError extends Error {
+    readonly isProvablyNotSent: boolean;
+    /** True only when the request failed before a usable connection could send HTTP bytes. */
+    constructor(isProvablyNotSent: boolean);
+}
+/** Public-only HTTPS or explicitly owned private-network HTTP. */
+type AddressPolicy = 'publicHTTPS' | 'privateNetworkHTTP';
+/** One bounded provider request; response bodies and URL values never enter errors. */
+interface ProviderRequest {
+    /** Absolute provider URL. */ url: string;
+    /** HTTP method. */ method: string;
+    /** Request headers, including provider credentials when needed. */ headers?: Record<string, string>;
+    /** Caller-encoded request body. */ body?: Uint8Array;
+    /** Maximum response body size in bytes. */ maxResponseBytes: number;
+    /** Network policy checked against all resolved addresses. */ addressPolicy: AddressPolicy;
+    /** Request deadline in milliseconds. */ timeoutMs?: number;
+    /** Caller cancellation. */ signal?: AbortSignal;
+}
+/** Bounded response; redirects remain visible as 3xx responses. */
+interface ProviderResponse {
+    /** Numeric HTTP status. */ status: number;
+    /** Response headers. */ headers: http.IncomingHttpHeaders;
+    /** Bounded response bytes. */ body: Uint8Array;
+}
+/** Parse RFC 9110 delay-seconds or an HTTP-date, capped at one hour. */
+declare function parseRetryAfter(value: string, now?: Date): number;
+/** Validate a provider base URL without echoing input; returns original URL without trailing slashes, unlike Go's parsed rendering. WHATWG numeric loopback shorthands are accepted. */
+declare function validateBaseURL(value: string): string;
+/** Check whether a credential fits one HTTP header without alteration. */
+declare function isHeaderSafeCredential(value: string): boolean;
+/** Read a stream to at most maxBytes. A negative limit throws; Go clamps it to zero. */
+declare function readBoundedBody(body: AsyncIterable<Uint8Array>, maxBytes: number): Promise<Uint8Array>;
+/** Return safe tokens at ordered JSON pointers. Numeric lexemes may normalize through JavaScript Number. */
+declare function readErrorTokens(body: Uint8Array, pointers: readonly string[]): string[];
+/** Send once using pinned, policy-checked DNS results and no redirect replay. */
+declare function sendProviderRequest(request: ProviderRequest): Promise<ProviderResponse>;
+
+export { type AddressPolicy, AddressRefusal, BodyTooLargeError, MaxErrorBodyBytes, MaxRetryAfterDelayMs, type ProviderRequest, type ProviderResponse, ProviderTransportError, isHeaderSafeCredential, parseRetryAfter, readBoundedBody, readErrorTokens, sendProviderRequest, validateBaseURL };

package/dist/providerhttp/index.js

@@ -0,0 +1,26 @@
+import {
+  AddressRefusal,
+  BodyTooLargeError,
+  MaxErrorBodyBytes,
+  MaxRetryAfterDelayMs,
+  ProviderTransportError,
+  isHeaderSafeCredential,
+  parseRetryAfter,
+  readBoundedBody,
+  readErrorTokens,
+  sendProviderRequest,
+  validateBaseURL
+} from "../chunk-2IDXFKMY.js";
+export {
+  AddressRefusal,
+  BodyTooLargeError,
+  MaxErrorBodyBytes,
+  MaxRetryAfterDelayMs,
+  ProviderTransportError,
+  isHeaderSafeCredential,
+  parseRetryAfter,
+  readBoundedBody,
+  readErrorTokens,
+  sendProviderRequest,
+  validateBaseURL
+};

package/dist/singledispatch/index.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { C as Call, a as CallID } from '../credentials-vrvW0d4j.js';
+import '@superdurable/dex';
+
+/** The current attempt has no permission to send another provider write. */
+declare class DispatchNotAllowedError extends Error {
+    constructor();
+}
+/** The provider request cannot fit within the protected attempt budget. */
+declare class InsufficientTimeError extends Error {
+    constructor();
+}
+/** A claim heartbeat failed before any provider request was sent. */
+declare class CheckpointError extends Error {
+    constructor();
+}
+/** Sets the fraction of the initial attempt budget available to Dispatch. */
+interface FenceOptions {
+    /** Positive fraction up to 5/6; default is 7/12. */ writeWindowFraction?: number;
+}
+/** One-attempt fence for a non-idempotent provider write. Construct once per Step attempt. */
+declare class Fence {
+    #private;
+    /** Capture the smaller of the configured Execute timeout and the public Dex attempt deadline. */
+    constructor(call: Call, executeTimeoutMs: number, options?: FenceOptions);
+    /** Decide before resolving credentials or performing any provider lookup. */
+    decide(): Decision;
+    /** Record the claim before sending once; repeat it during a long request. */
+    dispatch<Result>(send: (signal: AbortSignal) => Promise<Result> | Result): Promise<Result>;
+    /** Checkpoint a pre-send Retry, permanently forbidding Dispatch in this attempt. */
+    recordNotSent(): Promise<void>;
+    /** Checkpoint positive evidence that the prior request was not processed. */
+    recordCanResend(): Promise<void>;
+    /** Checkpoint an accepted provider resource for read-back after a lost response. */
+    recordProviderId(providerId: string): Promise<void>;
+}
+/** Construct one fence for the current Dex Step attempt. */
+declare function newFence(call: Call, executeTimeoutMs: number, options?: FenceOptions): Fence;
+
+/** Last known write state of one Dex Execute attempt. */
+declare const MarkerStateSchema: z.ZodEnum<{
+    notSent: "notSent";
+    claimed: "claimed";
+    canResend: "canResend";
+}>;
+/** Last known write state of one Dex Execute attempt. */
+type MarkerState = z.infer<typeof MarkerStateSchema>;
+/** Secret-free heartbeat marker shared with the Go single-dispatch fence. */
+declare const MarkerSchema: z.ZodObject<{
+    callId: z.ZodUUID;
+    attempt: z.ZodNumber;
+    state: z.ZodEnum<{
+        notSent: "notSent";
+        claimed: "claimed";
+        canResend: "canResend";
+    }>;
+    providerId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Secret-free heartbeat checkpoint for one call and attempt. */
+type Marker = z.infer<typeof MarkerSchema>;
+/** Action allowed before credentials or provider lookups. */
+type DecisionKind = 'sendAllowed' | 'readBackRequired' | 'failClosed';
+/** Decision from the most recent heartbeat checkpoint. */
+interface Decision {
+    /** Allowed action. */ kind: DecisionKind;
+    /** Prior valid checkpoint, when available. */ marker?: Marker;
+    /** Safe reason for an unreadable or invalid checkpoint. */ error?: Error;
+}
+/** Decide whether this attempt may dispatch from a prior heartbeat value. */
+declare function decideDispatch(callId: CallID, attempt: number, lastHeartbeat: unknown, readError?: Error): Decision;
+
+export { CheckpointError, type Decision, type DecisionKind, DispatchNotAllowedError, Fence, type FenceOptions, InsufficientTimeError, type Marker, MarkerSchema, type MarkerState, MarkerStateSchema, decideDispatch, newFence };

package/dist/singledispatch/index.js

@@ -0,0 +1,178 @@
+import {
+  CallIDSchema
+} from "../chunk-SOXYPIMO.js";
+
+// src/singledispatch/index.ts
+import { z } from "zod";
+
+// src/singledispatch/fence.ts
+var DispatchNotAllowedError = class extends Error {
+  constructor() {
+    super("single dispatch is not allowed for this attempt");
+    this.name = "DispatchNotAllowedError";
+  }
+};
+var InsufficientTimeError = class extends Error {
+  constructor() {
+    super("insufficient attempt time for single dispatch");
+    this.name = "InsufficientTimeError";
+  }
+};
+var CheckpointError = class extends Error {
+  constructor() {
+    super("single-dispatch checkpoint could not be recorded");
+    this.name = "CheckpointError";
+  }
+};
+var Fence = class {
+  #context;
+  #call;
+  #writeDeadline;
+  #minimumRequestTime;
+  #decision;
+  #hasDispatched = false;
+  #hasSendFinished = false;
+  #hasPreSendRetry = false;
+  #hasTerminalRecordPending = false;
+  #marker;
+  /** Capture the smaller of the configured Execute timeout and the public Dex attempt deadline. */
+  constructor(call, executeTimeoutMs, options = {}) {
+    if (!call?.context || !CallIDSchema.safeParse(call.id).success || !Number.isSafeInteger(call.context.attempt) || call.context.attempt < 1 || !Number.isFinite(executeTimeoutMs) || executeTimeoutMs <= 0) throw new TypeError("single dispatch requires a call, positive attempt, and Execute timeout");
+    const fraction = options.writeWindowFraction ?? 7 / 12;
+    if (!Number.isFinite(fraction) || fraction <= 0 || fraction > 5 / 6) throw new RangeError("single-dispatch write window must be within (0, 5/6]");
+    this.#call = call;
+    this.#context = call.context;
+    const now = Date.now();
+    const remaining = this.#context.deadline ? this.#context.deadline.getTime() - now : executeTimeoutMs;
+    const budget = Math.max(0, Math.min(executeTimeoutMs, remaining));
+    this.#writeDeadline = now + budget * fraction;
+    this.#minimumRequestTime = budget / 10;
+  }
+  /** Decide before resolving credentials or performing any provider lookup. */
+  decide() {
+    if (this.#decision) return this.#decision;
+    let last;
+    try {
+      if (this.#context.hasLastHeartbeatValue()) {
+        last = this.#context.getLastHeartbeatValue();
+        if (last === void 0 || last === null) {
+          this.#decision = { kind: "failClosed", error: new TypeError("invalid single-dispatch checkpoint") };
+          return this.#decision;
+        }
+      }
+    } catch (error) {
+      this.#decision = decideDispatch(this.#call.id, this.#context.attempt, void 0, error instanceof Error ? error : new Error("heartbeat checkpoint is unreadable"));
+      return this.#decision;
+    }
+    this.#decision = decideDispatch(this.#call.id, this.#context.attempt, last);
+    return this.#decision;
+  }
+  /** Record the claim before sending once; repeat it during a long request. */
+  async dispatch(send) {
+    if (this.#decision?.kind !== "sendAllowed" || this.#hasDispatched || this.#hasPreSendRetry || typeof send !== "function") throw new DispatchNotAllowedError();
+    if (this.#minimumRequestTime <= 0 || this.#writeDeadline - Date.now() < this.#minimumRequestTime) {
+      try {
+        await this.recordNotSent();
+      } catch (error) {
+        throw new AggregateError([new InsufficientTimeError(), error], "single dispatch has insufficient time and checkpoint failed");
+      }
+      throw new InsufficientTimeError();
+    }
+    this.#hasDispatched = true;
+    const claim = { callId: this.#call.id, attempt: this.#context.attempt, state: "claimed" };
+    try {
+      await this.#record(claim);
+    } catch {
+      this.#hasPreSendRetry = true;
+      try {
+        await this.#context.recordHeartbeat({ callId: this.#call.id, attempt: this.#context.attempt, state: "notSent" });
+      } catch {
+      }
+      throw new CheckpointError();
+    }
+    const requestController = new AbortController();
+    const onCancel = () => requestController.abort(this.#context.cancellationSignal.reason);
+    if (this.#context.cancellationSignal.aborted) onCancel();
+    else this.#context.cancellationSignal.addEventListener("abort", onCancel, { once: true });
+    const timeout = setTimeout(() => requestController.abort(new InsufficientTimeError()), Math.max(0, this.#writeDeadline - Date.now()));
+    let pendingHeartbeat = Promise.resolve();
+    const ticker = setInterval(() => {
+      if (this.#marker?.state !== "claimed" || this.#marker.providerId) return;
+      pendingHeartbeat = pendingHeartbeat.then(async () => {
+        if (this.#marker?.state === "claimed" && !this.#marker.providerId) {
+          try {
+            await this.#context.recordHeartbeat(claim);
+          } catch {
+          }
+        }
+      });
+    }, 5e3);
+    try {
+      return await send(requestController.signal);
+    } finally {
+      clearInterval(ticker);
+      clearTimeout(timeout);
+      this.#context.cancellationSignal.removeEventListener("abort", onCancel);
+      await pendingHeartbeat;
+      this.#hasSendFinished = true;
+    }
+  }
+  /** Checkpoint a pre-send Retry, permanently forbidding Dispatch in this attempt. */
+  async recordNotSent() {
+    if (this.#decision?.kind !== "sendAllowed" || this.#hasDispatched || this.#hasPreSendRetry) throw new DispatchNotAllowedError();
+    this.#hasPreSendRetry = true;
+    await this.#record({ callId: this.#call.id, attempt: this.#context.attempt, state: "notSent" });
+  }
+  /** Checkpoint positive evidence that the prior request was not processed. */
+  async recordCanResend() {
+    if (!this.#hasSendFinished || this.#hasTerminalRecordPending || this.#marker?.state !== "claimed" || this.#marker.providerId) throw new DispatchNotAllowedError();
+    this.#hasTerminalRecordPending = true;
+    try {
+      await this.#record({ callId: this.#call.id, attempt: this.#context.attempt, state: "canResend" });
+    } finally {
+      this.#hasTerminalRecordPending = false;
+    }
+  }
+  /** Checkpoint an accepted provider resource for read-back after a lost response. */
+  async recordProviderId(providerId) {
+    if (!this.#hasSendFinished || this.#hasTerminalRecordPending || this.#marker?.state !== "claimed" || !providerId) throw new DispatchNotAllowedError();
+    this.#hasTerminalRecordPending = true;
+    try {
+      await this.#record({ callId: this.#call.id, attempt: this.#context.attempt, state: "claimed", providerId });
+    } finally {
+      this.#hasTerminalRecordPending = false;
+    }
+  }
+  async #record(marker) {
+    await this.#context.recordHeartbeat(marker);
+    this.#marker = marker;
+  }
+};
+function newFence(call, executeTimeoutMs, options) {
+  return new Fence(call, executeTimeoutMs, options);
+}
+
+// src/singledispatch/index.ts
+var MarkerStateSchema = z.enum(["notSent", "claimed", "canResend"]);
+var MarkerSchema = z.strictObject({ callId: CallIDSchema, attempt: z.number().int().positive(), state: MarkerStateSchema, providerId: z.string().min(1).optional() });
+function decideDispatch(callId, attempt, lastHeartbeat, readError) {
+  if (!CallIDSchema.safeParse(callId).success || !Number.isSafeInteger(attempt) || attempt < 1) return { kind: "failClosed", error: new TypeError("single dispatch requires a call and positive attempt") };
+  if (readError) return { kind: "failClosed", error: readError };
+  if (lastHeartbeat === void 0 || lastHeartbeat === null) return { kind: attempt === 1 ? "sendAllowed" : "readBackRequired" };
+  const parsed = MarkerSchema.safeParse(lastHeartbeat);
+  if (!parsed.success) return { kind: "failClosed", error: new TypeError("invalid single-dispatch checkpoint") };
+  const marker = parsed.data;
+  if (marker.callId !== callId) return { kind: "failClosed", error: new TypeError("foreign single-dispatch checkpoint") };
+  if (marker.attempt === attempt - 1 && (marker.state === "notSent" || marker.state === "canResend") && !marker.providerId) return { kind: "sendAllowed", marker };
+  return { kind: "readBackRequired", marker };
+}
+export {
+  CheckpointError,
+  DispatchNotAllowedError,
+  Fence,
+  InsufficientTimeError,
+  MarkerSchema,
+  MarkerStateSchema,
+  decideDispatch,
+  newFence
+};

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@superdurable/connectors-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Provider-neutral TypeScript contracts for Dex connectors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superdurable/dex-connectors-library.git",
+    "directory": "sdkts"
+  },
+  "type": "module",
+  "engines": {
+    "node": "^22.0.0 || ^24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./providerhttp": {
+      "types": "./dist/providerhttp/index.d.ts",
+      "import": "./dist/providerhttp/index.js"
+    },
+    "./projectconfig": {
+      "types": "./dist/projectconfig/index.d.ts",
+      "import": "./dist/projectconfig/index.js"
+    },
+    "./connectormock": {
+      "types": "./dist/connectormock/index.d.ts",
+      "import": "./dist/connectormock/index.js"
+    },
+    "./oauthtoken": {
+      "types": "./dist/oauthtoken/index.d.ts",
+      "import": "./dist/oauthtoken/index.js"
+    },
+    "./singledispatch": {
+      "types": "./dist/singledispatch/index.d.ts",
+      "import": "./dist/singledispatch/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepack": "npm run build",
+    "build": "tsup src/index.ts src/providerhttp/index.ts src/projectconfig/index.ts src/connectormock/index.ts src/oauthtoken/index.ts src/singledispatch/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src test",
+    "test": "vitest run",
+    "test:package": "node test/pack_smoke.mjs",
+    "test:integration": "npm run build && node test/integ/step_flows.mjs",
+    "check": "npm run typecheck && npm run lint && npm test && npm run build && npm run test:package"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.900.0",
+    "@superdurable/dex": ">=1.28.0",
+    "zod": "^4.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.0.0"
+  }
+}