@particle-academy/fancy-connector-core 0.0.0

package/dist/index.cjs

@@ -0,0 +1,1356 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  AMBIGUOUS_REFUSAL: () => AMBIGUOUS_REFUSAL,
+  CONNECTOR_API_VERSION: () => CONNECTOR_API_VERSION,
+  CONNECTOR_MODES: () => CONNECTOR_MODES,
+  ConnectorAmbiguous: () => ConnectorAmbiguous,
+  ConnectorApiMismatch: () => ConnectorApiMismatch,
+  ConnectorAuthError: () => ConnectorAuthError,
+  ConnectorConfigError: () => ConnectorConfigError,
+  ConnectorError: () => ConnectorError,
+  ConnectorIdempotencyExpiredError: () => ConnectorIdempotencyExpiredError,
+  ConnectorModeError: () => ConnectorModeError,
+  ConnectorRateLimited: () => ConnectorRateLimited,
+  ConnectorRequestError: () => ConnectorRequestError,
+  ConnectorTransient: () => ConnectorTransient,
+  ConnectorUnreachable: () => ConnectorUnreachable,
+  DEFAULT_IDEMPOTENCY_WINDOW_SECONDS: () => DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
+  DEFAULT_RETRY: () => DEFAULT_RETRY,
+  FAKE_EPOCH: () => FAKE_EPOCH,
+  MAX_IDEMPOTENCY_KEY_LENGTH: () => MAX_IDEMPOTENCY_KEY_LENGTH,
+  NO_IDEMPOTENCY_KEY_WARNING: () => NO_IDEMPOTENCY_KEY_WARNING,
+  RENDERER_VERSION: () => RENDERER_VERSION,
+  REVIEW_STALE_DAYS: () => REVIEW_STALE_DAYS,
+  SUPPORTED_CONNECTOR_API: () => SUPPORTED_CONNECTOR_API,
+  assertConnectorApi: () => assertConnectorApi,
+  byteRangeOf: () => byteRangeOf,
+  callConnector: () => callConnector,
+  capabilityProblems: () => capabilityProblems,
+  checkAgainstOpenApi: () => checkAgainstOpenApi,
+  checkAgainstRecordedShape: () => checkAgainstRecordedShape,
+  classifyError: () => classifyError,
+  classifyHttp: () => classifyHttp,
+  classifyStatus: () => classifyStatus,
+  classifyThrown: () => classifyThrown,
+  compareShape: () => compareShape,
+  connectionsFor: () => connectionsFor,
+  constantTimeEquals: () => constantTimeEquals,
+  deliver: () => deliver,
+  fakeRequest: () => fakeRequest,
+  fakeValues: () => fakeValues,
+  getConnectionHost: () => getConnectionHost,
+  graphemes: () => graphemes,
+  header: () => header,
+  hmac: () => hmac,
+  httpFailure: () => httpFailure,
+  idempotencyKeyFor: () => idempotencyKeyFor,
+  isEmptyPayload: () => isEmptyPayload,
+  isRemote: () => isRemote,
+  isUnconditionallyRetryable: () => isUnconditionallyRetryable,
+  linkRanges: () => linkRanges,
+  measure: () => measure,
+  payloadHash: () => payloadHash,
+  postChain: () => postChain,
+  probe: () => probe,
+  registerConnectionHost: () => registerConnectionHost,
+  registerTransport: () => registerTransport,
+  render: () => render,
+  reported: () => reported,
+  resetRateState: () => resetRateState,
+  resolveConnection: () => resolveConnection,
+  resolveConnectorMode: () => resolveConnectorMode,
+  respectRate: () => respectRate,
+  runIdentityFrom: () => runIdentityFrom,
+  runKeyFrom: () => runKeyFrom,
+  runProbes: () => runProbes,
+  satisfiesMinimum: () => satisfiesMinimum,
+  seedFrom: () => seedFrom,
+  shapeOf: () => shapeOf,
+  shouldRetry: () => shouldRetry,
+  sliceByteRange: () => sliceByteRange,
+  splitToFit: () => splitToFit,
+  triggerEvent: () => triggerEvent,
+  unchecked: () => unchecked,
+  utf8Length: () => utf8Length,
+  verifyDelivery: () => verifyDelivery,
+  verifyHmac: () => verifyHmac
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/chain.ts
+async function postChain(segments, answering, post) {
+  const posted = [];
+  let root = answering?.root;
+  let parent = answering?.parent;
+  for (const [index, text] of segments.entries()) {
+    let made;
+    try {
+      made = await post(text, root && parent ? { root, parent } : void 0, index);
+    } catch (error) {
+      return { posted, failed: { index, error } };
+    }
+    posted.push(made);
+    root = root ?? made;
+    parent = made;
+  }
+  return { posted };
+}
+
+// src/compat.ts
+var CONNECTOR_API_VERSION = 1;
+var SUPPORTED_CONNECTOR_API = [1];
+var ConnectorApiMismatch = class extends Error {
+  connector;
+  declared;
+  constructor(message, connector, declared) {
+    super(message);
+    this.name = "ConnectorApiMismatch";
+    this.connector = connector;
+    this.declared = declared;
+  }
+};
+function assertConnectorApi(connectorId, declared) {
+  if (SUPPORTED_CONNECTOR_API.includes(declared)) return;
+  const supported = SUPPORTED_CONNECTOR_API.join(", ");
+  throw new ConnectorApiMismatch(
+    declared > CONNECTOR_API_VERSION ? `"${connectorId}" was written against connector API ${declared}, and this core implements ${supported}. The CONNECTOR is newer: upgrade @particle-academy/fancy-connector-core. Vendoring a connector ahead of the core it needs is the one direction that cannot be made to work by trying.` : `"${connectorId}" was written against connector API ${declared}, which is older than anything this core still runs (${supported}). The CONNECTOR is behind: re-vendor it \u2014 \`npx fancy-cli@latest add connector ${connectorId}\` \u2014 which fetches the copy written for this core. Nothing is adapted automatically, because guessing what a two-version-old connector meant is how a connector quietly starts doing something else.`,
+    connectorId,
+    declared
+  );
+}
+function satisfiesMinimum(coreVersion, minimum) {
+  const parts = (value) => value.split(".").slice(0, 3).map((segment) => Number.parseInt(segment, 10) || 0);
+  const [a = 0, b = 0, c = 0] = parts(coreVersion);
+  const [x = 0, y = 0, z = 0] = parts(minimum);
+  if (a !== x) return a > x;
+  if (b !== y) return b > y;
+  return c >= z;
+}
+
+// src/delivery.ts
+var UNREACHABLE_CODES = /* @__PURE__ */ new Set([
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ECONNRESET",
+  "EPIPE",
+  "ERR_SOCKET_CONNECTION_TIMEOUT"
+]);
+var AMBIGUOUS_CODES = /* @__PURE__ */ new Set([
+  "ETIMEDOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_CONNECT_TIMEOUT"
+]);
+var AMBIGUOUS_NAMES = /* @__PURE__ */ new Set(["AbortError", "TimeoutError"]);
+function classifyError(error) {
+  const detail = error instanceof Error ? error.message : String(error);
+  const code = error?.code ?? error?.cause?.code ?? "";
+  const name = error instanceof Error ? error.name : "";
+  if (UNREACHABLE_CODES.has(code)) return { kind: "unreachable", detail: `${code}: ${detail}` };
+  if (AMBIGUOUS_NAMES.has(name) || AMBIGUOUS_CODES.has(code)) {
+    return { kind: "ambiguous", detail: `${name || code}: ${detail}` };
+  }
+  return { kind: "ambiguous", detail };
+}
+function classifyStatus(status, body = "", retryAfterHeader) {
+  const detail = `${status}${body ? `: ${body.slice(0, 200)}` : ""}`;
+  const seconds = retryAfterHeader === void 0 || retryAfterHeader === null ? NaN : Number(retryAfterHeader);
+  if (status === 429 || status >= 500) {
+    return {
+      kind: "refused-explicitly",
+      detail,
+      ...Number.isFinite(seconds) ? { retryAfter: seconds } : {}
+    };
+  }
+  return { kind: "rejected", detail };
+}
+var DEFAULT_RETRY = {
+  attempts: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 8e3,
+  idempotent: false
+};
+function shouldRetry(kind, policy) {
+  if (kind === "rejected") return false;
+  if (kind === "unreachable" || kind === "refused-explicitly") return true;
+  return policy.idempotent;
+}
+function isUnconditionallyRetryable(kind) {
+  return kind === "unreachable" || kind === "refused-explicitly";
+}
+var AMBIGUOUS_REFUSAL = "The request may or may not have gone through, and this connector offers no way to repeat it harmlessly. Refusing to try again \u2014 a duplicate is worse than a call that needs doing by hand. Check the provider before re-running.";
+async function deliver(send, policy = DEFAULT_RETRY, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+  const attempts = [];
+  const budget = Math.max(1, policy.attempts);
+  for (let attempt = 1; attempt <= budget; attempt++) {
+    try {
+      const value = await send(attempt);
+      return { ok: true, value, attempts };
+    } catch (error) {
+      const classified = error.classified ?? classifyError(error);
+      if (!shouldRetry(classified.kind, policy)) {
+        attempts.push({ attempt, kind: classified.kind, detail: classified.detail });
+        return {
+          ok: false,
+          attempts,
+          kind: classified.kind,
+          gaveUp: classified.kind === "ambiguous" ? `${AMBIGUOUS_REFUSAL} (${classified.detail})` : classified.detail
+        };
+      }
+      if (attempt >= budget) {
+        attempts.push({ attempt, kind: classified.kind, detail: classified.detail });
+        return {
+          ok: false,
+          attempts,
+          kind: classified.kind,
+          gaveUp: `Gave up after ${attempt} attempts. ${classified.detail}`
+        };
+      }
+      const backoff = Math.min(policy.baseDelayMs * 2 ** (attempt - 1), policy.maxDelayMs);
+      const waitedMs = classified.retryAfter ? Math.max(backoff, classified.retryAfter * 1e3) : backoff;
+      attempts.push({ attempt, kind: classified.kind, detail: classified.detail, waitedMs });
+      await sleep(waitedMs);
+    }
+  }
+  return { ok: false, attempts, gaveUp: "Exhausted every attempt." };
+}
+var lastCallAt = /* @__PURE__ */ new Map();
+async function respectRate(channel, minIntervalMs, now = () => Date.now(), sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+  if (minIntervalMs <= 0) return { waitedMs: 0 };
+  const previous = lastCallAt.get(channel);
+  const at = now();
+  const waitedMs = previous === void 0 ? 0 : Math.max(0, previous + minIntervalMs - at);
+  if (waitedMs > 0) await sleep(waitedMs);
+  lastCallAt.set(channel, at + waitedMs);
+  return { waitedMs };
+}
+function resetRateState() {
+  lastCallAt.clear();
+}
+
+// src/errors.ts
+var ConnectorError = class extends Error {
+  service;
+  operation;
+  status;
+  providerCode;
+  /**
+   * What kind of failure this is. The primitive every retry decision reads.
+   *
+   * Defaults to `ambiguous` on the base class deliberately: an unclassified
+   * failure must not be assumed safe.
+   */
+  kind = "ambiguous";
+  constructor(message, ctx) {
+    super(message);
+    this.name = new.target.name;
+    this.service = ctx.service;
+    this.operation = ctx.operation;
+    this.status = ctx.status;
+    this.providerCode = ctx.providerCode;
+  }
+  /**
+   * Safe to retry **without knowing anything about the connector**.
+   *
+   * Ambiguous failures answer `false` here even though they may be retryable on
+   * an idempotent connector — ask `shouldRetry(error.kind, { idempotent })` for
+   * that. This getter is the conservative half on purpose.
+   */
+  get retryable() {
+    return isUnconditionallyRetryable(this.kind);
+  }
+  /** The classification, in the shape `deliver()` reads off a thrown error. */
+  get classified() {
+    return { kind: this.kind, detail: this.message };
+  }
+};
+var ConnectorConfigError = class extends ConnectorError {
+  kind = "rejected";
+};
+var ConnectorAuthError = class extends ConnectorError {
+  kind = "rejected";
+};
+var ConnectorRateLimited = class extends ConnectorError {
+  kind = "refused-explicitly";
+  /** Seconds to wait, when the provider said. */
+  retryAfter;
+  constructor(message, ctx) {
+    super(message, ctx);
+    this.retryAfter = ctx.retryAfter;
+  }
+  get classified() {
+    return {
+      kind: this.kind,
+      detail: this.message,
+      ...this.retryAfter === void 0 ? {} : { retryAfter: this.retryAfter }
+    };
+  }
+};
+var ConnectorTransient = class extends ConnectorError {
+  kind = "refused-explicitly";
+};
+var ConnectorUnreachable = class extends ConnectorError {
+  kind = "unreachable";
+};
+var ConnectorAmbiguous = class extends ConnectorError {
+  kind = "ambiguous";
+};
+var ConnectorRequestError = class extends ConnectorError {
+  kind = "rejected";
+};
+function classifyHttp(status, ctx, body, retryAfter) {
+  const detail = body.trim() === "" ? "" : ` \u2014 ${truncate(body, 400)}`;
+  const where = `${ctx.service}.${ctx.operation}`;
+  if (status === 429) {
+    return new ConnectorRateLimited(`${where}: rate limited by the provider${detail}`, {
+      ...ctx,
+      status,
+      ...retryAfter === void 0 ? {} : { retryAfter }
+    });
+  }
+  if (status === 401 || status === 403) {
+    return new ConnectorAuthError(
+      `${where}: the provider rejected the credential (${status})${detail}. Check the credentials and that they match the mode you are running in \u2014 a live key in sandbox, or the reverse, fails exactly like this.`,
+      { ...ctx, status }
+    );
+  }
+  if (status >= 500) {
+    return new ConnectorTransient(`${where}: provider returned ${status}${detail}`, { ...ctx, status });
+  }
+  return new ConnectorRequestError(`${where}: request rejected with ${status}${detail}`, { ...ctx, status });
+}
+function classifyThrown(cause, ctx) {
+  const classified = classifyError(cause);
+  const message = `${ctx.service}.${ctx.operation}: ${classified.detail}`;
+  return classified.kind === "unreachable" ? new ConnectorUnreachable(message, ctx) : new ConnectorAmbiguous(message, ctx);
+}
+function httpFailure(status, body, retryAfter) {
+  const classified = classifyStatus(status, body, retryAfter);
+  const error = new Error(classified.detail);
+  error.classified = classified;
+  return error;
+}
+function truncate(value, max) {
+  return value.length <= max ? value : `${value.slice(0, max)}\u2026`;
+}
+
+// src/faker.ts
+var FAKE_EPOCH = "2026-01-01T00:00:00.000Z";
+function seedFrom(...parts) {
+  const text = parts.map((part) => typeof part === "string" ? part : stableJson(part)).join("|");
+  let hash = 2166136261;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash >>> 0;
+}
+function stableJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${stableJson(v)}`);
+  return `{${entries.join(",")}}`;
+}
+function fakeValues(seed) {
+  let state = seed || 2654435769;
+  const next = () => {
+    state ^= state << 13;
+    state >>>= 0;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    state >>>= 0;
+    return state;
+  };
+  const hex = (length) => {
+    let out = "";
+    while (out.length < length) out += next().toString(16).padStart(8, "0");
+    return out.slice(0, length);
+  };
+  return {
+    hex,
+    id: (prefix) => `${prefix}_fake_${hex(12)}`,
+    int: (min, max) => min + next() % Math.max(1, max - min + 1),
+    pick: (options) => options[next() % options.length],
+    timestamp: (offsetSeconds = 0) => new Date(Date.parse(FAKE_EPOCH) + offsetSeconds * 1e3).toISOString()
+  };
+}
+function fakeRequest(service, operation, config, input) {
+  return { config, input, fake: fakeValues(seedFrom(service, operation, config)) };
+}
+
+// src/mode.ts
+var CONNECTOR_MODES = ["fake", "sandbox", "live"];
+function resolveConnectorMode(inputs) {
+  const { requested, connectionMode, sandbox, hasSandboxCredentials, environment } = inputs;
+  if (requested && requested !== "auto") {
+    if (requested === "sandbox" && sandbox === "none") {
+      throw new ConnectorModeError(
+        `This connector's provider has no sandbox estate, so "sandbox" cannot be honoured. Use "fake" to develop without credentials, or "live" to talk to the provider.`
+      );
+    }
+    return requested;
+  }
+  if (connectionMode) return connectionMode;
+  if (environment.production) return "live";
+  return sandbox !== "none" && hasSandboxCredentials ? "sandbox" : "fake";
+}
+var ConnectorModeError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConnectorModeError";
+  }
+};
+function isRemote(mode) {
+  return mode !== "fake";
+}
+
+// src/connection.ts
+var host = null;
+function registerConnectionHost(next) {
+  host = next;
+  return () => {
+    if (host === next) host = null;
+  };
+}
+function getConnectionHost() {
+  return host;
+}
+function connectionsFor(service) {
+  const current = getConnectionHost();
+  if (!current) return [];
+  return Object.entries(current.connections).filter(([, spec]) => spec.service === service).map(([id, spec]) => ({ id, label: spec.label ?? id }));
+}
+function resolveConnection(options) {
+  const { service, operation, sandbox } = options;
+  const requestedMode = options.requested ?? "auto";
+  if (requestedMode === "sandbox" && sandbox === "none") {
+    throw new ConnectorModeError(
+      `${service} has no sandbox estate, so "sandbox" cannot be honoured. Use "fake" to develop without credentials, or "live" to talk to the provider.`
+    );
+  }
+  const id = options.connectionId?.trim() || service;
+  if (options.credentials) {
+    if (requestedMode === "fake") return { id, service, mode: "fake", credentials: {} };
+    const mode2 = requestedMode === "auto" ? "live" : requestedMode;
+    const missing2 = (options.requires ?? []).filter((key) => !options.credentials?.[key]);
+    if (missing2.length > 0) {
+      throw new ConnectorConfigError(
+        `${service}.${operation} was given credentials with no ${missing2.join(", ")}. Nothing is inferred from an incomplete credential set \u2014 a partial one is a configuration mistake, and quietly falling back to another source is how the wrong account gets written to.`,
+        { service, operation }
+      );
+    }
+    const explicitBase = options.baseUrls?.[mode2];
+    return {
+      id,
+      service,
+      mode: mode2,
+      credentials: options.credentials,
+      ...explicitBase ? { baseUrl: explicitBase } : {}
+    };
+  }
+  const current = getConnectionHost();
+  const spec = current?.connections[id];
+  if (spec && spec.service !== service) {
+    throw new ConnectorConfigError(
+      `connection "${id}" is configured for the "${spec.service}" service, but this node needs "${service}".`,
+      { service, operation }
+    );
+  }
+  if (!current || !spec) {
+    if (requestedMode !== "auto" && requestedMode !== "fake") {
+      throw new ConnectorConfigError(
+        `no "${id}" connection is registered, so ${service}.${operation} cannot run in "${requestedMode}" mode. Call registerConnectionHost({ connections: { ${id}: { service: "${service}", live: { \u2026 } } } }) \u2014 the node has no credentials of its own and must not invent any. Set the node's mode to "fake" to develop without one.`,
+        { service, operation }
+      );
+    }
+    return { id, service, mode: "fake", credentials: {} };
+  }
+  const sandboxCreds = spec.sandbox ?? {};
+  const mode = resolveConnectorMode({
+    requested: requestedMode,
+    connectionMode: spec.mode ?? null,
+    sandbox,
+    hasSandboxCredentials: hasAll(sandboxCreds, options.requires ?? []),
+    environment: current.environment
+  });
+  if (mode === "fake") {
+    return { id, service, mode, credentials: {} };
+  }
+  const credentials = (mode === "sandbox" ? spec.sandbox : spec.live) ?? {};
+  const missing = (options.requires ?? []).filter((key) => !credentials[key]);
+  if (missing.length > 0) {
+    throw new ConnectorConfigError(
+      `connection "${id}" has no ${missing.join(", ")} for ${mode} mode. Set connections.${id}.${mode}.${missing[0]}, or run this node in "fake" mode.`,
+      { service, operation }
+    );
+  }
+  const baseUrl = spec.baseUrl?.[mode] ?? options.baseUrls?.[mode];
+  return { id, service, mode, credentials, ...baseUrl ? { baseUrl } : {} };
+}
+function hasAll(creds, keys) {
+  return keys.length > 0 && keys.every((key) => Boolean(creds[key]));
+}
+
+// src/client.ts
+var registeredTransport = null;
+function registerTransport(next) {
+  registeredTransport = next;
+}
+async function callConnector(service, options) {
+  const config = options.config ?? {};
+  const connection = resolveConnection({
+    service: service.service,
+    operation: options.operation,
+    connectionId: options.connectionId ?? readString(config, "connection"),
+    requested: options.mode ?? readString(config, "mode"),
+    credentials: options.credentials ?? null,
+    sandbox: service.sandbox,
+    baseUrls: service.baseUrls,
+    requires: service.requires
+  });
+  if (connection.mode === "fake") {
+    return {
+      data: service.faker(
+        options.operation,
+        fakeRequest(service.service, options.operation, config, options.input)
+      ),
+      mode: "fake",
+      connection: connection.id
+    };
+  }
+  const ctx = { service: service.service, operation: options.operation };
+  const prepared = await prepare(service, connection, options);
+  const send = options.transport ?? registeredTransport ?? fetchTransport;
+  const outcome = await deliver(
+    async () => {
+      let response;
+      try {
+        response = await send(prepared);
+      } catch (cause) {
+        throw classifyThrown(cause, ctx);
+      }
+      if (response.status < 400) {
+        return response.body.trim() === "" ? null : parseJson(response.body, ctx);
+      }
+      throw classifyHttp(response.status, ctx, response.body, readRetryAfter(response.headers));
+    },
+    {
+      ...DEFAULT_RETRY,
+      attempts: options.attempts ?? DEFAULT_RETRY.attempts,
+      idempotent: options.idempotent ?? false
+    }
+  );
+  if (options.onAttempt) {
+    for (const attempt of outcome.attempts) options.onAttempt(attempt);
+  }
+  if (!outcome.ok) {
+    throw failureFrom(outcome, ctx, options.idempotent ?? false);
+  }
+  return { data: outcome.value, mode: connection.mode, connection: connection.id };
+}
+function failureFrom(outcome, ctx, idempotent) {
+  const last = outcome.attempts.at(-1);
+  const kind = outcome.kind ?? last?.kind ?? "ambiguous";
+  const error = new ConnectorError(outcome.gaveUp ?? `${ctx.service}.${ctx.operation} failed.`, ctx);
+  Object.defineProperty(error, "kind", { value: kind, enumerable: false });
+  Object.defineProperty(error, "attempts", { value: outcome.attempts, enumerable: false });
+  Object.defineProperty(error, "idempotent", { value: idempotent, enumerable: false });
+  return error;
+}
+async function prepare(service, connection, options) {
+  const base = connection.baseUrl ?? service.baseUrls[connection.mode];
+  if (!base) {
+    throw new ConnectorConfigError(
+      `${service.service}: no base URL for "${connection.mode}" mode. The service descriptor must declare one per mode it supports.`,
+      { service: service.service, operation: options.operation }
+    );
+  }
+  const { method, path, query, headers, json, form } = options.request;
+  const url = new URL(path.replace(/^\/+/, ""), base.endsWith("/") ? base : `${base}/`);
+  for (const [key, value] of Object.entries(query ?? {})) {
+    if (value !== void 0) url.searchParams.set(key, String(value));
+  }
+  const prepared = {
+    method,
+    url: url.toString(),
+    headers: { Accept: "application/json", ...headers }
+  };
+  if (form) {
+    prepared.headers["Content-Type"] = "application/x-www-form-urlencoded";
+    prepared.body = encodeForm(form);
+  } else if (json !== void 0) {
+    prepared.headers["Content-Type"] = "application/json";
+    prepared.body = JSON.stringify(json);
+  }
+  if (options.idempotencyKey && service.idempotencyHeader) {
+    prepared.headers[service.idempotencyHeader] = options.idempotencyKey;
+  }
+  await service.authorize(connection.credentials, prepared, connection.mode);
+  return prepared;
+}
+function encodeForm(form) {
+  const pairs = [];
+  const walk = (prefix, value) => {
+    if (value === void 0 || value === null) return;
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => walk(`${prefix}[${index}]`, item));
+      return;
+    }
+    if (typeof value === "object") {
+      for (const [key, nested] of Object.entries(value)) {
+        walk(prefix === "" ? key : `${prefix}[${key}]`, nested);
+      }
+      return;
+    }
+    pairs.push(`${encodeURIComponent(prefix)}=${encodeURIComponent(String(value))}`);
+  };
+  walk("", form);
+  return pairs.join("&");
+}
+var fetchTransport = async (request) => {
+  const globalFetch = globalThis.fetch;
+  if (!globalFetch) {
+    throw new Error(
+      "no global fetch in this runtime \u2014 call registerTransport() with one before running a connector remotely."
+    );
+  }
+  const response = await globalFetch(request.url, {
+    method: request.method,
+    headers: request.headers,
+    ...request.body === void 0 ? {} : { body: request.body }
+  });
+  const headers = {};
+  response.headers.forEach((value, key) => {
+    headers[key.toLowerCase()] = value;
+  });
+  return { status: response.status, headers, body: await response.text() };
+};
+function parseJson(body, ctx) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    const error = new ConnectorError(
+      `${ctx.service}.${ctx.operation}: the provider returned a body that is not JSON.`,
+      ctx
+    );
+    Object.defineProperty(error, "kind", { value: "rejected", enumerable: false });
+    throw error;
+  }
+}
+function readRetryAfter(headers) {
+  const raw = headers["retry-after"];
+  if (!raw) return void 0;
+  const seconds = Number(raw);
+  return Number.isFinite(seconds) ? seconds : void 0;
+}
+function readString(config, key) {
+  const value = config[key];
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+
+// src/drift.ts
+function resolveRef(document, node, depth = 0) {
+  if (depth > 8 || node === null || typeof node !== "object") return node;
+  const ref = node.$ref;
+  if (typeof ref !== "string") return node;
+  if (!ref.startsWith("#/")) return node;
+  let current = document;
+  for (const segment of ref.slice(2).split("/")) {
+    if (current === null || typeof current !== "object") return node;
+    current = current[segment.replace(/~1/g, "/").replace(/~0/g, "~")];
+  }
+  return resolveRef(document, current, depth + 1);
+}
+function propertiesOf(document, schema, depth = 0) {
+  const names = /* @__PURE__ */ new Set();
+  const resolved = resolveRef(document, schema, depth);
+  if (!resolved || typeof resolved !== "object" || depth > 6) return names;
+  const properties = resolveRef(document, resolved.properties, depth + 1);
+  if (properties && typeof properties === "object") {
+    for (const key of Object.keys(properties)) names.add(key);
+  }
+  for (const key of ["items", "additionalProperties"]) {
+    const nested = resolved[key];
+    if (nested) for (const name of propertiesOf(document, nested, depth + 1)) names.add(name);
+  }
+  for (const key of ["allOf", "oneOf", "anyOf"]) {
+    const list = resolved[key];
+    if (Array.isArray(list)) {
+      for (const entry of list) for (const name of propertiesOf(document, entry, depth + 1)) names.add(name);
+    }
+  }
+  return names;
+}
+function requestSchemaOf(document, operation) {
+  const body = resolveRef(document, operation.requestBody);
+  if (!body?.content) return void 0;
+  for (const media of Object.values(body.content)) {
+    if (media?.schema) return media.schema;
+  }
+  return void 0;
+}
+function responseSchemaOf(document, operation) {
+  const responses = resolveRef(document, operation.responses);
+  if (!responses) return void 0;
+  for (const status of Object.keys(responses)) {
+    if (!/^2\d\d$/.test(status) && status !== "default") continue;
+    const response = resolveRef(document, responses[status]);
+    if (!response?.content) continue;
+    for (const media of Object.values(response.content)) {
+      if (media?.schema) return media.schema;
+    }
+  }
+  return void 0;
+}
+function checkAgainstOpenApi(contract, document) {
+  const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const findings = [];
+  if (!document || typeof document !== "object" || !document.paths) {
+    return {
+      connector: contract.connector,
+      checkedAt,
+      outcome: "unchecked",
+      method: "openapi",
+      findings: [
+        {
+          kind: "unreadable-spec",
+          detail: "the document has no `paths`, so it is not an OpenAPI description we can read. Reported as UNCHECKED rather than clean \u2014 a checker that cannot see is not a checker that saw nothing wrong."
+        }
+      ]
+    };
+  }
+  const spec = document;
+  for (const operation of contract.operations) {
+    const path = spec.paths?.[operation.path];
+    if (!path) {
+      findings.push({
+        kind: "missing-operation",
+        operation: operation.operation,
+        detail: `${operation.method} ${operation.path} is not in the spec at all. The path moved or was removed.`
+      });
+      continue;
+    }
+    const method = path[operation.method.toLowerCase()];
+    if (!method) {
+      findings.push({
+        kind: "missing-operation",
+        operation: operation.operation,
+        detail: `${operation.path} exists but no longer accepts ${operation.method}.`
+      });
+      continue;
+    }
+    if (operation.sends?.length) {
+      const accepted = propertiesOf(spec, requestSchemaOf(spec, method));
+      if (accepted.size > 0) {
+        for (const field of operation.sends) {
+          if (!accepted.has(field)) {
+            findings.push({
+              kind: "missing-request-field",
+              operation: operation.operation,
+              detail: `sends \`${field}\`, which the spec no longer lists on ${operation.method} ${operation.path}.`
+            });
+          }
+        }
+      }
+    }
+    if (operation.reads?.length) {
+      const returned = propertiesOf(spec, responseSchemaOf(spec, method));
+      if (returned.size > 0) {
+        for (const field of operation.reads) {
+          if (!returned.has(field)) {
+            findings.push({
+              kind: "missing-response-field",
+              operation: operation.operation,
+              detail: `reads \`${field}\`, which the spec no longer returns from ${operation.method} ${operation.path}. This is the silent kind: the code keeps running and produces nothing.`
+            });
+          }
+        }
+      }
+    }
+  }
+  findings.push(...staleReviewFindings(contract, checkedAt));
+  return {
+    connector: contract.connector,
+    checkedAt,
+    outcome: findings.some((finding) => finding.kind !== "stale-review") ? "drifted" : "clean",
+    method: "openapi",
+    findings
+  };
+}
+function shapeOf(value, prefix = "", depth = 0) {
+  if (depth > 6 || value === null || typeof value !== "object") return prefix ? [prefix] : [];
+  if (Array.isArray(value)) {
+    return value.length === 0 ? [`${prefix}[]`] : shapeOf(value[0], `${prefix}[]`, depth + 1);
+  }
+  const names = [];
+  for (const [key, nested] of Object.entries(value)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    names.push(...shapeOf(nested, path, depth + 1));
+  }
+  return names.sort();
+}
+function checkAgainstRecordedShape(contract, operation, liveResponse) {
+  const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const declared = contract.operations.find((entry) => entry.operation === operation);
+  const present = new Set(shapeOf(liveResponse));
+  const findings = [];
+  for (const field of declared?.reads ?? []) {
+    const found = [...present].some((name) => name === field || name.replace(/\[\]/g, "") === field);
+    if (!found) {
+      findings.push({
+        kind: "missing-response-field",
+        operation,
+        detail: `reads \`${field}\`, which the live response no longer carries. Present instead: ${[...present].slice(0, 20).join(", ")}${present.size > 20 ? ", \u2026" : ""}`
+      });
+    }
+  }
+  findings.push(...staleReviewFindings(contract, checkedAt));
+  return {
+    connector: contract.connector,
+    checkedAt,
+    outcome: findings.some((finding) => finding.kind !== "stale-review") ? "drifted" : "clean",
+    method: "recorded-shape",
+    findings
+  };
+}
+var REVIEW_STALE_DAYS = 180;
+function staleReviewFindings(contract, checkedAt) {
+  const reviewed = Date.parse(contract.reviewedOn);
+  if (!Number.isFinite(reviewed)) {
+    return [{ kind: "stale-review", detail: `reviewedOn "${contract.reviewedOn}" is not a date.` }];
+  }
+  const days = Math.floor((Date.parse(checkedAt) - reviewed) / 864e5);
+  return days > REVIEW_STALE_DAYS ? [
+    {
+      kind: "stale-review",
+      detail: `nobody has read this provider's documentation in ${days} days. Not drift \u2014 an absence of looking, which is the state a silent break grows in.`
+    }
+  ] : [];
+}
+function unchecked(contract) {
+  const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    connector: contract.connector,
+    checkedAt,
+    outcome: "unchecked",
+    method: "none",
+    findings: [
+      {
+        kind: "unreadable-spec",
+        detail: contract.spec.kind === "none" ? contract.spec.note : "no spec document was supplied to the checker, so nothing was compared."
+      },
+      ...staleReviewFindings(contract, checkedAt)
+    ]
+  };
+}
+
+// src/idempotency.ts
+var DEFAULT_IDEMPOTENCY_WINDOW_SECONDS = 24 * 60 * 60;
+var MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+var ConnectorIdempotencyExpiredError = class extends ConnectorConfigError {
+};
+function runIdentityFrom(ctx) {
+  const bag = ctx;
+  return bag?.run ?? null;
+}
+function runKeyFrom(ctx) {
+  const identity = runIdentityFrom(ctx);
+  if (identity) return identity.runKey;
+  const bag = ctx;
+  const seeded = bag?.inputs?.__runKey;
+  return typeof seeded === "string" && seeded.trim() !== "" ? seeded.trim() : null;
+}
+function idempotencyKeyFor(ctx, nodeId, options = {}) {
+  const identity = runIdentityFrom(ctx);
+  const windowSeconds = options.windowSeconds === void 0 ? DEFAULT_IDEMPOTENCY_WINDOW_SECONDS : options.windowSeconds;
+  if (!identity) {
+    const runKey = runKeyFrom(ctx);
+    return runKey === null ? null : fit(`${runKey}:${nodeId}`);
+  }
+  if (!identity.isReplaySafe(windowSeconds, options.now ?? /* @__PURE__ */ new Date())) {
+    throw new ConnectorIdempotencyExpiredError(
+      `attempt ${identity.attempt} of this step began at ${identity.firstAttemptAt}, which is outside the provider's ${windowSeconds}s idempotency window. The provider has forgotten the original key, so resending it and sending a new one would BOTH write twice. Refusing, so a person can reconcile \u2014 check whether the first attempt landed before re-running this workflow.`,
+      {
+        service: options.context?.service ?? "",
+        operation: options.context?.operation ?? "",
+        ...options.context
+      }
+    );
+  }
+  return fit(identity.stepKey(nodeId, options.occurrence));
+}
+var NO_IDEMPOTENCY_KEY_WARNING = "no run identity available, so this write is being sent WITHOUT an idempotency key. A retry would repeat the effect rather than recover from it \u2014 the node is marked unsafe-to-replay, so a durable runner will give it one attempt. Durable runs supply an identity automatically; for a synchronous run, pass `run` in RunOptions.";
+function fit(key) {
+  if (key.length <= MAX_IDEMPOTENCY_KEY_LENGTH) return key;
+  const digest = fnv1a(key);
+  const head = key.slice(0, MAX_IDEMPOTENCY_KEY_LENGTH - digest.length - 1);
+  return `${head}~${digest}`;
+}
+function fnv1a(value) {
+  let hash = 2166136261;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24)) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+
+// src/metrics.ts
+function compareShape(connectorId, declared, produced) {
+  const declaredKeys = new Set((declared ?? []).map((metric) => metric.key));
+  const producedKeys = new Set(Object.keys(produced));
+  const undeclared = [...producedKeys].filter((key) => !declaredKeys.has(key)).sort();
+  const unproduced = [...declaredKeys].filter((key) => !producedKeys.has(key)).sort();
+  if (undeclared.length === 0 && unproduced.length === 0) return null;
+  return { connector: connectorId, undeclared, unproduced };
+}
+function capabilityProblems(connector) {
+  const problems = [];
+  if (connector.capabilities.metrics) {
+    if (!connector.metricShape || connector.metricShape.length === 0) {
+      problems.push(
+        `${connector.id} claims capabilities.metrics but declares no metricShape. A pull will therefore ask it, get nothing, and report nothing \u2014 which reads as "nobody engaged" rather than "not implemented".`
+      );
+    }
+    if (!connector.fetchMetrics) {
+      problems.push(`${connector.id} claims capabilities.metrics but has no fetchMetrics.`);
+    }
+  }
+  if (!connector.capabilities.metrics && connector.metricShape) {
+    problems.push(
+      `${connector.id} declares a metricShape but capabilities.metrics is false. One of the two is wrong, and the shape is the more believable half.`
+    );
+  }
+  if (connector.capabilities.feedback && !connector.fetchFeedback) {
+    problems.push(`${connector.id} claims capabilities.feedback but has no fetchFeedback.`);
+  }
+  if (!connector.capabilities.feedback && connector.fetchFeedback) {
+    problems.push(
+      `${connector.id} implements fetchFeedback but does not claim the capability, so nothing will ever call it.`
+    );
+  }
+  for (const metric of connector.metricShape ?? []) {
+    if (metric.means.trim().length < 10) {
+      problems.push(`${connector.id}.${metric.key} does not say what it means.`);
+    }
+  }
+  if (connector.delivery.idempotent && connector.delivery.why.trim().length < 10) {
+    problems.push(
+      `${connector.id} declares idempotent: true with no reason. That is the one claim whose failure is a public duplicate, so it has to name the mechanism rather than restate the flag.`
+    );
+  }
+  if (connector.delivery.minIntervalMs > 0 && !connector.delivery.citation && connector.delivery.rateSource === "documented") {
+    problems.push(
+      `${connector.id} calls its rate limit "documented" but cites nothing. A number nobody can source gets quoted as a platform fact; label it self-imposed or cite it.`
+    );
+  }
+  return problems;
+}
+function reported(values) {
+  const out = {};
+  for (const [key, value] of Object.entries(values)) {
+    if (typeof value === "number" && Number.isFinite(value)) out[key] = value;
+  }
+  return out;
+}
+
+// src/probe.ts
+async function probe(spec) {
+  let response;
+  try {
+    response = await spec.request();
+  } catch (error) {
+    const classified2 = classifyError(error);
+    if (classified2.kind === "unreachable") {
+      return { connector: spec.connector, outcome: "skip", detail: `offline \u2014 ${classified2.detail}` };
+    }
+    return {
+      connector: spec.connector,
+      outcome: "fail",
+      detail: `the request failed before any status arrived \u2014 ${classified2.detail}`,
+      kind: classified2.kind
+    };
+  }
+  const { status, body } = response;
+  if (spec.authStatuses.includes(status)) {
+    return {
+      connector: spec.connector,
+      outcome: "pass",
+      status,
+      detail: `${status} \u2014 the provider refused an invalid credential, which proves host, path, method and error handling. ${spec.why}`
+    };
+  }
+  if (status < 400) {
+    return {
+      connector: spec.connector,
+      outcome: "fail",
+      status,
+      detail: `${status} \u2014 the provider ACCEPTED a deliberately invalid credential. Either the credential is reaching nothing (wrong header, wrong field) or this endpoint does not authenticate. Neither is safe to ship.`
+    };
+  }
+  const classified = classifyStatus(status, body);
+  return {
+    connector: spec.connector,
+    outcome: "fail",
+    status,
+    kind: classified.kind,
+    detail: `${status} \u2014 expected one of ${spec.authStatuses.join(", ")}. A ${status} here usually means the endpoint moved or the path is wrong, which no amount of local mocking would ever have said. ${body.slice(0, 200)}`
+  };
+}
+async function runProbes(specs) {
+  const results = [];
+  for (const spec of specs) results.push(await probe(spec));
+  const passed = results.filter((result) => result.outcome === "pass").length;
+  const failed = results.filter((result) => result.outcome === "fail").length;
+  const skipped = results.filter((result) => result.outcome === "skip").length;
+  return { results, passed, failed, skipped, ok: failed === 0 };
+}
+
+// src/text.ts
+var encoder = new TextEncoder();
+function graphemes(text) {
+  const Segmenter = Intl.Segmenter;
+  if (!Segmenter) return [...text].length;
+  let count = 0;
+  for (const _ of new Segmenter(void 0, { granularity: "grapheme" }).segment(text)) count++;
+  return count;
+}
+function utf8Length(text) {
+  return encoder.encode(text).length;
+}
+function measure(text, unit) {
+  if (unit === "graphemes") return graphemes(text);
+  if (unit === "utf8-bytes") return utf8Length(text);
+  return text.length;
+}
+function byteRangeOf(text, charIndex, substring) {
+  const byteStart = utf8Length(text.slice(0, charIndex));
+  return { byteStart, byteEnd: byteStart + utf8Length(substring) };
+}
+function sliceByteRange(text, range) {
+  const bytes = encoder.encode(text);
+  return new TextDecoder().decode(bytes.slice(range.byteStart, range.byteEnd));
+}
+function linkRanges(text) {
+  const found = [];
+  for (const match of text.matchAll(/https?:\/\/[^\s]+/g)) {
+    if (match.index === void 0) continue;
+    const url = match[0].replace(/[.,;:!?)\]}'"]+$/, "");
+    found.push({ ...byteRangeOf(text, match.index, url), url });
+  }
+  return found;
+}
+
+// src/render.ts
+var RENDERER_VERSION = "render@1";
+var defaultNumbering = (index, total) => ` (${index}/${total})`;
+var SENTENCE_BOUNDARY = /(?<=[.!?])(?=\s)|(?<=\n)/;
+function splitToFit(text, limit, unit) {
+  const count = (value) => measure(value, unit);
+  const trimmed = text.trim();
+  if (count(trimmed) <= limit) return { parts: trimmed === "" ? [] : [trimmed], problems: [] };
+  const problems = [];
+  const parts = [];
+  const sentences = trimmed.split(SENTENCE_BOUNDARY).filter((part) => part !== "");
+  let current = "";
+  const flush = () => {
+    if (current.trim() !== "") parts.push(current.trim());
+    current = "";
+  };
+  for (const sentence of sentences) {
+    const candidate = current + sentence;
+    if (count(candidate.trim()) <= limit) {
+      current = candidate;
+      continue;
+    }
+    flush();
+    if (count(sentence.trim()) <= limit) {
+      current = sentence;
+      continue;
+    }
+    let buffer = "";
+    for (const word of sentence.split(/(\s+)/)) {
+      if (count((buffer + word).trim()) <= limit) {
+        buffer += word;
+        continue;
+      }
+      if (buffer.trim() !== "") parts.push(buffer.trim());
+      buffer = "";
+      if (count(word.trim()) > limit) {
+        problems.push(
+          `"${word.trim().slice(0, 40)}\u2026" is ${count(word.trim())} ${unit} on its own, longer than one whole message (${limit}). It cannot be split without breaking it, so this needs rewriting rather than adapting.`
+        );
+        continue;
+      }
+      buffer = word;
+    }
+    current = buffer;
+  }
+  flush();
+  return { parts: parts.filter((part) => part !== ""), problems };
+}
+function render(text, rules) {
+  const { limit, unit, label } = rules;
+  const count = (value) => measure(value, unit);
+  const trimmed = text.trim();
+  if (limit === null || count(trimmed) <= limit) {
+    return {
+      segments: [{ text: trimmed, count: count(trimmed), ...rules.links ? { links: linkRanges(trimmed) } : {} }],
+      unit,
+      limit,
+      problems: [],
+      rendererVersion: RENDERER_VERSION
+    };
+  }
+  if (!rules.thread) {
+    return {
+      segments: [{ text: trimmed, count: count(trimmed), ...rules.links ? { links: linkRanges(trimmed) } : {} }],
+      unit,
+      limit,
+      problems: [
+        `${count(trimmed)} ${unit}; ${label}'s limit is ${limit}, and it has no thread mechanism to split into. This needs shortening rather than adapting.`
+      ],
+      rendererVersion: RENDERER_VERSION
+    };
+  }
+  const numbering = rules.numbering ?? defaultNumbering;
+  const first = splitToFit(text, limit, unit);
+  const willNumber = first.parts.length > 1;
+  const suffixCost = willNumber ? count(numbering(99, 99)) : 0;
+  const { parts, problems } = willNumber ? splitToFit(text, limit - suffixCost, unit) : first;
+  const segments = parts.map((part, index) => {
+    const withNumber = parts.length > 1 ? `${part}${numbering(index + 1, parts.length)}` : part;
+    return {
+      text: withNumber,
+      count: count(withNumber),
+      // Computed per segment and never sliced from the original — an offset into
+      // the whole text is meaningless once the text has been split.
+      ...rules.links ? { links: linkRanges(withNumber) } : {}
+    };
+  });
+  const over = segments.filter((segment) => segment.count > limit);
+  if (over.length > 0) {
+    problems.push(
+      `${over.length} segment(s) still exceed ${limit} ${unit} after splitting. That is a renderer defect rather than a content problem \u2014 the split should not produce an over-length message.`
+    );
+  }
+  return { segments, unit, limit, problems, rendererVersion: RENDERER_VERSION };
+}
+async function payloadHash(payload) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new Error(
+      "WebCrypto is not available in this runtime, so a payload hash cannot be computed. Refusing rather than returning a weaker fingerprint that a host would trust equally."
+    );
+  }
+  const canonical = JSON.stringify({
+    // Inside the hash, deliberately — see RENDERER_VERSION.
+    v: payload.rendererVersion,
+    segments: payload.segments.map((segment) => segment.text)
+  });
+  const digest = await subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+  return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function isEmptyPayload(payload) {
+  return payload.segments.every((segment) => segment.text.trim() === "");
+}
+
+// src/webhook.ts
+async function verifyHmac(options) {
+  const { raw, signature, secret, scheme, timestamp } = options;
+  if (!secret) {
+    return { ok: false, reason: "no signing secret configured for this trigger" };
+  }
+  if (!signature) return { ok: false, reason: "delivery carried no signature header" };
+  if (scheme.tolerance !== void 0) {
+    if (!timestamp) return { ok: false, reason: "delivery carried no timestamp header" };
+    const sent = Number(timestamp);
+    if (!Number.isFinite(sent)) return { ok: false, reason: "timestamp header is not a number" };
+    const now = options.now ?? Math.floor(Date.now() / 1e3);
+    if (Math.abs(now - sent) > scheme.tolerance) {
+      return { ok: false, reason: `delivery is outside the ${scheme.tolerance}s replay window` };
+    }
+  }
+  const expected = await hmac(secret, scheme.payload(raw, timestamp), scheme.algorithm, scheme.encoding ?? "hex");
+  return constantTimeEquals(expected, signature) ? { ok: true } : { ok: false, reason: "signature did not match" };
+}
+async function hmac(secret, payload, algorithm, encoding = "hex") {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new Error(
+      "WebCrypto is not available in this runtime, so webhook signatures cannot be verified. Refusing to accept deliveries unverified."
+    );
+  }
+  const encoder2 = new TextEncoder();
+  const key = await subtle.importKey(
+    "raw",
+    encoder2.encode(secret),
+    { name: "HMAC", hash: algorithm },
+    false,
+    ["sign"]
+  );
+  const bytes = new Uint8Array(await subtle.sign("HMAC", key, encoder2.encode(payload)));
+  if (encoding === "base64") {
+    let binary = "";
+    bytes.forEach((byte) => {
+      binary += String.fromCharCode(byte);
+    });
+    return btoa(binary);
+  }
+  return Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function constantTimeEquals(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function header(headers, name) {
+  const wanted = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() !== wanted) continue;
+    return Array.isArray(value) ? value[0] : value;
+  }
+  return void 0;
+}
+
+// src/trigger.ts
+async function verifyDelivery(trigger, delivery, secret, now) {
+  const spec = trigger.verification;
+  if (!spec) {
+    return {
+      ok: false,
+      reason: `${trigger.service}.${trigger.operation} declares no signature scheme, so a delivery cannot be trusted.`
+    };
+  }
+  const rawHeader = header(delivery.headers, spec.signatureHeader);
+  const parsed = spec.parse && rawHeader ? spec.parse(rawHeader) : { signature: rawHeader };
+  const timestamp = parsed.timestamp ?? (spec.timestampHeader ? header(delivery.headers, spec.timestampHeader) : void 0);
+  return verifyHmac({
+    raw: delivery.raw,
+    signature: parsed.signature,
+    secret,
+    scheme: spec.scheme,
+    timestamp,
+    ...now === void 0 ? {} : { now }
+  });
+}
+function triggerEvent(trigger, connection, injected, config) {
+  if (hasDelivery(injected)) return injected;
+  if (connection.mode === "fake") {
+    return trigger.faker(
+      trigger.operation,
+      fakeRequest(trigger.service, trigger.operation, config)
+    );
+  }
+  throw new Error(
+    `${trigger.service}.${trigger.operation}: no event was delivered to this trigger. Its delivery mechanism is "${trigger.delivery}" \u2014 ${trigger.setup} Set the node's mode to "fake" to design against a sample event instead.`
+  );
+}
+function hasDelivery(value) {
+  if (value === void 0 || value === null) return false;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === "object") return Object.keys(value).length > 0;
+  return true;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AMBIGUOUS_REFUSAL,
+  CONNECTOR_API_VERSION,
+  CONNECTOR_MODES,
+  ConnectorAmbiguous,
+  ConnectorApiMismatch,
+  ConnectorAuthError,
+  ConnectorConfigError,
+  ConnectorError,
+  ConnectorIdempotencyExpiredError,
+  ConnectorModeError,
+  ConnectorRateLimited,
+  ConnectorRequestError,
+  ConnectorTransient,
+  ConnectorUnreachable,
+  DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
+  DEFAULT_RETRY,
+  FAKE_EPOCH,
+  MAX_IDEMPOTENCY_KEY_LENGTH,
+  NO_IDEMPOTENCY_KEY_WARNING,
+  RENDERER_VERSION,
+  REVIEW_STALE_DAYS,
+  SUPPORTED_CONNECTOR_API,
+  assertConnectorApi,
+  byteRangeOf,
+  callConnector,
+  capabilityProblems,
+  checkAgainstOpenApi,
+  checkAgainstRecordedShape,
+  classifyError,
+  classifyHttp,
+  classifyStatus,
+  classifyThrown,
+  compareShape,
+  connectionsFor,
+  constantTimeEquals,
+  deliver,
+  fakeRequest,
+  fakeValues,
+  getConnectionHost,
+  graphemes,
+  header,
+  hmac,
+  httpFailure,
+  idempotencyKeyFor,
+  isEmptyPayload,
+  isRemote,
+  isUnconditionallyRetryable,
+  linkRanges,
+  measure,
+  payloadHash,
+  postChain,
+  probe,
+  registerConnectionHost,
+  registerTransport,
+  render,
+  reported,
+  resetRateState,
+  resolveConnection,
+  resolveConnectorMode,
+  respectRate,
+  runIdentityFrom,
+  runKeyFrom,
+  runProbes,
+  satisfiesMinimum,
+  seedFrom,
+  shapeOf,
+  shouldRetry,
+  sliceByteRange,
+  splitToFit,
+  triggerEvent,
+  unchecked,
+  utf8Length,
+  verifyDelivery,
+  verifyHmac
+});
+//# sourceMappingURL=index.cjs.map