@foir/sdk 0.11.0 → 0.13.0

package/dist/server.js

@@ -117,15 +117,17 @@ async function loadJwks(jwksUrl) {
   return keys;
 }
 function parseSubject(sub) {
-  const parts = sub.split("|");
-  if (parts.length !== 3) {
-    throw new Error(`malformed sub: expected 3 pipe-delimited segments, got ${parts.length}`);
+  const first = sub.indexOf("|");
+  const second = first === -1 ? -1 : sub.indexOf("|", first + 1);
+  if (first === -1 || second === -1) {
+    throw new Error("malformed sub: expected <tenant>|<project>|<app>");
   }
-  const [tenantId, projectId, appName] = parts;
-  if (!tenantId || !projectId || !appName) {
-    throw new Error("malformed sub: empty segment");
+  const tenantId = sub.slice(0, first);
+  const projectId = sub.slice(first + 1, second);
+  if (!tenantId || !projectId) {
+    throw new Error("malformed sub: empty tenant or project");
   }
-  return { tenantId, projectId, appName };
+  return { tenantId, projectId, appName: sub.slice(second + 1) };
 }
 function recordsReadModels(claims) {
   return claims.rrm ?? [];
@@ -134,16 +136,25 @@ function recordsWriteModels(claims) {
   return claims.rwm ?? [];
 }
 async function verifyScopedToken(token, jwksUrl, options) {
+  return verifyWithKeys(token, () => loadJwks(jwksUrl), void 0, options);
+}
+async function verifyWithKeys(token, loadKeys, refetchForUnknownKid, options) {
   const expectedIssuer = options?.expectedIssuer ?? "foir-platform";
   const parts = token.split(".");
   if (parts.length !== 3) throw new Error("malformed token");
   const [rawHeader, rawPayload, rawSig] = parts;
-  const header = JSON.parse(
-    new TextDecoder().decode(base64UrlDecode(rawHeader))
-  );
-  if (header.alg !== "EdDSA") throw new Error(`unexpected alg ${header.alg}`);
-  if (!header.kid) throw new Error("missing kid");
-  const keys = await loadJwks(jwksUrl);
+  let header;
+  try {
+    header = JSON.parse(new TextDecoder().decode(base64UrlDecode(rawHeader)));
+  } catch {
+    throw new Error("unreadable token header");
+  }
+  if (header.alg !== "EdDSA") throw new Error(`unexpected alg ${String(header.alg)}`);
+  if (typeof header.kid !== "string" || !header.kid) throw new Error("missing kid");
+  let keys = await loadKeys();
+  if (!keys.has(header.kid) && refetchForUnknownKid) {
+    keys = await refetchForUnknownKid() ?? keys;
+  }
   const key = keys.get(header.kid);
   if (!key) throw new Error(`unknown kid ${header.kid}`);
   const signingInput = new TextEncoder().encode(`${rawHeader}.${rawPayload}`);
@@ -158,10 +169,13 @@ async function verifyScopedToken(token, jwksUrl, options) {
     )
   );
   if (!ok) throw new Error("signature invalid");
-  const claims = JSON.parse(
-    new TextDecoder().decode(base64UrlDecode(rawPayload))
-  );
-  const now = Math.floor(Date.now() / 1e3);
+  let claims;
+  try {
+    claims = JSON.parse(new TextDecoder().decode(base64UrlDecode(rawPayload)));
+  } catch {
+    throw new Error("unreadable token payload");
+  }
+  const now = Math.floor((options?.now?.() ?? Date.now()) / 1e3);
   if (claims.iss !== expectedIssuer) throw new Error(`bad iss ${claims.iss}`);
   if (typeof claims.exp !== "number" || claims.exp < now) {
     throw new Error("token expired");
@@ -183,35 +197,174 @@ function parseContextHeader(raw) {
   }
   return out;
 }
+var ScopedTokenUnavailableError = class extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "ScopedTokenUnavailableError";
+    if (options?.cause !== void 0) this.cause = options.cause;
+  }
+};
+var VERIFIER_TTL_MS = 60 * 60 * 1e3;
+var VERIFIER_TIMEOUT_MS = 5e3;
+var KID_MISS_COOLDOWN_MS = 6e4;
+var FAILURE_COOLDOWN_MS = 6e4;
+function createScopedTokenVerifier(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const now = options.now ?? Date.now;
+  const timeoutMs = options.timeoutMs ?? VERIFIER_TIMEOUT_MS;
+  const ttlMs = options.ttlMs ?? VERIFIER_TTL_MS;
+  let cache;
+  let inFlight;
+  let lastKidMissRefetch = 0;
+  let nextAttemptAt = 0;
+  let staleServes = 0;
+  let refetchFailures = 0;
+  let notModified = 0;
+  async function fetchKeys(held) {
+    try {
+      const headers = { accept: "application/json" };
+      if (held?.etag) headers["if-none-match"] = held.etag;
+      const res = await doFetch(options.jwksUrl, {
+        ...options.requestInit,
+        headers,
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      if (res.status === 304 && held) {
+        notModified += 1;
+        nextAttemptAt = 0;
+        cache = { ...held, fetchedAt: now() };
+        return cache;
+      }
+      if (!res.ok) throw new Error(`jwks fetch ${res.status}`);
+      const doc = await res.json();
+      const keys2 = /* @__PURE__ */ new Map();
+      for (const jwk of doc.keys ?? []) {
+        if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || !jwk.kid || !jwk.x) continue;
+        const raw = base64UrlDecode(jwk.x);
+        keys2.set(
+          jwk.kid,
+          await crypto.subtle.importKey(
+            "raw",
+            raw.buffer.slice(raw.byteOffset, raw.byteOffset + raw.byteLength),
+            { name: "Ed25519" },
+            false,
+            ["verify"]
+          )
+        );
+      }
+      if (keys2.size === 0) throw new Error("jwks carried no Ed25519 keys");
+      nextAttemptAt = 0;
+      cache = { keys: keys2, fetchedAt: now(), etag: res.headers.get("etag") ?? void 0 };
+      return cache;
+    } catch (error) {
+      refetchFailures += 1;
+      nextAttemptAt = now() + FAILURE_COOLDOWN_MS;
+      if (held) {
+        staleServes += 1;
+        try {
+          options.onStale?.({ error, ageMs: now() - held.fetchedAt, staleServes });
+        } catch {
+        }
+        return held;
+      }
+      throw new ScopedTokenUnavailableError(
+        `the JWKS could not be read and no keys are held: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  function keys(force) {
+    const held = cache;
+    const at = now();
+    if (!force && held && at - held.fetchedAt < ttlMs) return Promise.resolve(held);
+    if (at < nextAttemptAt && !inFlight) {
+      if (held) {
+        staleServes += 1;
+        return Promise.resolve(held);
+      }
+      return Promise.reject(
+        new ScopedTokenUnavailableError(
+          `the JWKS could not be read and no keys are held; the next attempt is in ${Math.ceil((nextAttemptAt - at) / 1e3)}s`
+        )
+      );
+    }
+    inFlight ??= fetchKeys(held).finally(() => {
+      inFlight = void 0;
+    });
+    return inFlight;
+  }
+  return {
+    verify(token) {
+      return verifyWithKeys(
+        token,
+        async () => (await keys(false)).keys,
+        async () => {
+          const at = now();
+          if (at - lastKidMissRefetch < KID_MISS_COOLDOWN_MS) return null;
+          lastKidMissRefetch = at;
+          return (await keys(true)).keys;
+        },
+        { expectedIssuer: options.expectedIssuer, now }
+      );
+    },
+    async warm() {
+      try {
+        await keys(false);
+      } catch {
+      }
+    },
+    stats() {
+      return {
+        keyCount: cache?.keys.size ?? 0,
+        ageMs: cache ? now() - cache.fetchedAt : null,
+        staleServes,
+        refetchFailures,
+        notModified
+      };
+    }
+  };
+}
 
 // src/server/require-scoped-token.ts
-var TOKEN_HEADER = "X-Foir-Token";
-var CONTEXT_HEADER = "X-Foir-Context";
+var FOIR_TOKEN_HEADER = "X-Foir-Token";
+var FOIR_CONTEXT_HEADER = "X-Foir-Context";
+var TOKEN_HEADER = FOIR_TOKEN_HEADER;
+var CONTEXT_HEADER = FOIR_CONTEXT_HEADER;
 var DEFAULT_JWKS_URL = "https://api.foir.dev/.well-known/jwks.json";
 var ScopedTokenError = class extends Error {
   status;
-  constructor(message, status) {
+  /**
+   * Why, for a route that answers the cases differently: `missing` (the
+   * request carried no token at all, so it did not come from the platform),
+   * `invalid` (a token that does not verify), `forbidden` (a valid token for
+   * another tenant or project) and `unavailable` (the token could not be
+   * checked).
+   */
+  reason;
+  constructor(message, status, reason) {
     super(message);
     this.name = "ScopedTokenError";
     this.status = status;
+    this.reason = reason ?? (status === 403 ? "forbidden" : status === 503 ? "unavailable" : "invalid");
   }
 };
+var LEVEL_CLAIM = "org_id";
 async function requireScopedToken(request, options) {
   const token = request.headers.get(TOKEN_HEADER);
   if (!token) {
     throw new ScopedTokenError(
       `missing ${TOKEN_HEADER} header \u2014 this route only accepts platform-dispatched requests`,
-      401
+      401,
+      "missing"
     );
   }
   let claims;
   try {
-    claims = await verifyScopedToken(
-      token,
-      options?.jwksUrl ?? DEFAULT_JWKS_URL,
-      options
-    );
+    claims = options?.verifier ? await options.verifier.verify(token) : await verifyScopedToken(token, options?.jwksUrl ?? DEFAULT_JWKS_URL, options);
   } catch (err) {
+    if (err instanceof ScopedTokenUnavailableError) {
+      throw new ScopedTokenError(`the scoped token could not be checked: ${err.message}`, 503);
+    }
     throw new ScopedTokenError(
       `invalid scoped token: ${err instanceof Error ? err.message : String(err)}`,
       401
@@ -239,13 +392,18 @@ async function requireScopedToken(request, options) {
     );
   }
   const rawContext = request.headers.get(CONTEXT_HEADER);
+  const level = claims.ctx?.[LEVEL_CLAIM];
   return {
     claims,
     subject,
     context: parseContextHeader(rawContext),
     // The token handed over is the one verified above, not a fresh read of the
     // header, so the client presents exactly what this guard accepted.
-    dispatch: { token: () => token, context: rawContext }
+    dispatch: { token: () => token, context: rawContext },
+    orgId: typeof level === "string" ? level : null,
+    ...typeof claims.cid === "string" && claims.cid !== "" ? { customerId: claims.cid } : {},
+    expiresAt: new Date(claims.exp * 1e3),
+    tokenId: claims.jti
   };
 }
 
@@ -313,7 +471,7 @@ async function readDispatch(request) {
     refuse(`body.input is ${describe(input)}, expected an object`);
   }
   const payload = { ...body, input: input ?? {} };
-  for (const block of ["content", "record", "triggerContext", "callback"]) {
+  for (const block of ["content", "record", "triggerContext", "callback", "continuation"]) {
     const value = payload[block];
     if (value === void 0) continue;
     if (value === null) {
@@ -322,107 +480,37 @@ async function readDispatch(request) {
     }
     if (!isObject(value)) refuse(`body.${block} is ${describe(value)}, expected an object`);
   }
-  return payload;
-}
-
-// src/server/callback-client.ts
-function createCallbackClient(callback, opts) {
-  const { executionId, signingSecret } = opts;
-  const fetchImpl = opts.fetch ?? globalThis.fetch;
-  if (!fetchImpl) {
-    throw new Error(
-      "createCallbackClient: no fetch available; pass opts.fetch on runtimes without a global fetch"
-    );
-  }
-  if (!executionId) throw new Error("createCallbackClient: executionId is required");
-  if (!signingSecret) throw new Error("createCallbackClient: signingSecret is required");
-  if (!callback?.token || !callback?.gqlEndpoint || !callback?.mutations) {
-    throw new Error("createCallbackClient: callback block is missing required fields");
-  }
-  const post = async (mutationName, fields, variables) => {
-    const query = `mutation ${mutationName}Mutation($id: String!${fieldArgsForMutation(mutationName, variables)}) { ${mutationName}(id: $id${fieldArgsCallSite(mutationName, variables)}) { ${fields} } }`;
-    const body = JSON.stringify({
-      query,
-      variables: { id: executionId, ...variables }
-    });
-    const signature = await hmacSha256Hex(signingSecret, body);
-    const resp = await fetchImpl(callback.gqlEndpoint, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${callback.token}`,
-        "X-Foir-Signature": `sha256=${signature}`
-      },
-      body
-    });
-    if (!resp.ok) {
-      throw new Error(`callback ${mutationName} failed with HTTP ${resp.status}: ${await resp.text()}`);
-    }
-    const json = await resp.json();
-    if (json.errors?.length) {
-      throw new Error(`callback ${mutationName} GraphQL error: ${json.errors[0].message}`);
+  if (isObject(payload.continuation)) {
+    requireString(payload.continuation, "cursor", "body.continuation");
+    if (typeof payload.continuation.slice !== "number") {
+      refuse(`body.continuation.slice is ${describe(payload.continuation.slice)}, expected a number`);
     }
-    const out = json.data?.[mutationName];
-    if (!out) {
-      throw new Error(`callback ${mutationName} returned no data`);
-    }
-    return out;
-  };
-  return {
-    complete: (result) => post(callback.mutations.complete, "status cancelled", { result }),
-    fail: (code, message, options = {}) => post(callback.mutations.fail, "status cancelled", {
-      code,
-      message,
-      retryable: options.retryable,
-      details: options.details
-    }),
-    progress: (update) => post(callback.mutations.progress, "status cancelled applied", {
-      pct: update.pct,
-      message: update.message,
-      metadata: update.metadata
-    }),
-    cancel: () => post(callback.mutations.cancel, "status cancelled", {})
-  };
-}
-function fieldArgsForMutation(mutationName, vars) {
-  const parts = [];
-  for (const key of Object.keys(vars)) {
-    if (vars[key] === void 0) continue;
-    parts.push(`, $${key}: ${graphQLTypeFor(mutationName, key)}`);
   }
-  return parts.join("");
-}
-function fieldArgsCallSite(_mutationName, vars) {
-  const parts = [];
-  for (const key of Object.keys(vars)) {
-    if (vars[key] === void 0) continue;
-    parts.push(`, ${key}: $${key}`);
-  }
-  return parts.join("");
-}
-function graphQLTypeFor(mutationName, key) {
-  if (key === "code" || key === "message") return "String!";
-  if (key === "pct") return "Int";
-  if (key === "retryable") return "Boolean";
-  if (key === "details" || key === "metadata") return "JSON";
-  if (key === "result") {
-    const base = mutationName.replace(/^complete/, "").replace(/Execution$/, "");
-    return `${base}ExecutionResultInput!`;
-  }
-  if (key === "message") return "String";
-  return "String";
+  return payload;
 }
-async function hmacSha256Hex(secret, body) {
-  const enc = new TextEncoder();
-  const key = await crypto.subtle.importKey(
-    "raw",
-    enc.encode(secret),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["sign"]
-  );
-  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(body));
-  return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+
+// src/server/continue-run.ts
+var CONTINUATION_MEDIA_TYPE = "application/vnd.foir.continuation+json";
+var MAX_CONTINUATION_CURSOR_BYTES = 16 * 1024;
+var MAX_CONTINUATION_DELAY_MS = 15 * 60 * 1e3;
+function continueRun(continuation) {
+  const { cursor, delayMs, progressPct } = continuation;
+  if (typeof cursor !== "string" || cursor === "") {
+    throw new TypeError("continueRun: a continuation carries the cursor the next slice resumes from");
+  }
+  if (new TextEncoder().encode(cursor).length > MAX_CONTINUATION_CURSOR_BYTES) {
+    throw new RangeError(`continueRun: a cursor is at most ${MAX_CONTINUATION_CURSOR_BYTES} bytes`);
+  }
+  if (delayMs !== void 0 && !(Number.isInteger(delayMs) && delayMs >= 0 && delayMs <= MAX_CONTINUATION_DELAY_MS)) {
+    throw new RangeError(`continueRun: delayMs is a whole number of milliseconds from 0 to ${MAX_CONTINUATION_DELAY_MS}`);
+  }
+  if (progressPct !== void 0 && !(Number.isInteger(progressPct) && progressPct >= 0 && progressPct <= 100)) {
+    throw new RangeError("continueRun: progressPct is a whole percentage from 0 to 100");
+  }
+  return new Response(JSON.stringify(continuation), {
+    status: 200,
+    headers: { "Content-Type": CONTINUATION_MEDIA_TYPE }
+  });
 }
 
 // src/transport/foir-http.ts
@@ -478,7 +566,12 @@ var FoirRequestError = class extends Error {
    * failed on the first attempt for an hour.
    */
   get retryable() {
-    if (this.status === void 0) return true;
+    if (this.status === void 0) {
+      if (this.graphQLErrors?.length || this.prunedSelections?.length) {
+        return this.code === "RATE_LIMITED" || this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
+      }
+      return true;
+    }
     if (this.status === 429 || this.code === "RATE_LIMITED") return true;
     if (this.status >= 500) return true;
     return this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
@@ -524,6 +617,7 @@ function refuseCredentialHeaders(extra) {
     }
   }
 }
+var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
 function buildFoirHeaders(input) {
   const headers = {
     "Content-Type": "application/json"
@@ -548,6 +642,9 @@ function buildFoirHeaders(input) {
     if (input.orgUrl) {
       headers["X-Org-Url"] = input.orgUrl;
     }
+    if (input.visitorAddress) {
+      headers[FOIR_VISITOR_IP_HEADER] = input.visitorAddress;
+    }
   }
   if (input.extra) {
     for (const [key, value] of Object.entries(input.extra)) {
@@ -563,8 +660,188 @@ function foirApiEndpoint(apiUrl, path) {
   }
   return base + path;
 }
+var FoirAuthDowngradedError = class extends FoirRequestError {
+  downgrade;
+  constructor(downgrade) {
+    super(
+      `[foir] your customer token was ${downgrade.customerToken} (${downgrade.reason}), so the request was served as ${downgrade.servedAs}`,
+      { graphQLErrors: [{ message: "customer token rejected", extensions: { code: "AUTH_DOWNGRADED" } }] }
+    );
+    this.name = "FoirAuthDowngradedError";
+    this.downgrade = downgrade;
+  }
+};
+var FoirSessionExpiredError = class extends FoirRequestError {
+  constructor(options) {
+    super("[foir] the customer session has expired and could not be refreshed: sign in again", {
+      cause: options?.cause,
+      graphQLErrors: [{ message: "session expired", extensions: { code: "SESSION_EXPIRED" } }]
+    });
+    this.name = "FoirSessionExpiredError";
+  }
+};
+
+// src/transport/retry.ts
+var DEFAULT_ATTEMPTS = 3;
+var DEFAULT_BASE_DELAY_MS = 200;
+var DEFAULT_MAX_DELAY_MS = 2e4;
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function foirRetryDelayMs(error, attempt, policy = {}) {
+  if (!(error instanceof FoirRequestError) || !error.retryable) return null;
+  const max = policy.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+  const stated = error.retryAfterMs;
+  if (stated !== void 0) return Math.min(stated, max);
+  const base = policy.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  return Math.min(base * 2 ** (attempt - 1), max);
+}
+async function withFoirRetry(fn, policy = {}) {
+  const attempts = Math.max(1, policy.attempts ?? DEFAULT_ATTEMPTS);
+  const sleep = policy.sleep ?? defaultSleep;
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      const delayMs = attempt >= attempts ? null : foirRetryDelayMs(error, attempt, policy);
+      if (delayMs === null) throw error;
+      policy.onRetry?.({ attempt, delayMs, error });
+      await sleep(delayMs);
+    }
+  }
+}
+
+// src/server/callback-client.ts
+function createCallbackClient(callback, opts) {
+  const { executionId } = opts;
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  if (!fetchImpl) {
+    throw new Error(
+      "createCallbackClient: no fetch available; pass opts.fetch on runtimes without a global fetch"
+    );
+  }
+  if (!executionId) throw new Error("createCallbackClient: executionId is required");
+  if (!callback?.token || !callback?.mutations) {
+    throw new Error("createCallbackClient: callback block is missing required fields");
+  }
+  if (!callback.gqlEndpoint && !opts.apiUrl) {
+    throw new Error(
+      "createCallbackClient: nowhere to report to. The dispatch named no callback.gqlEndpoint and no apiUrl was passed."
+    );
+  }
+  const endpoint = callback.gqlEndpoint || foirApiEndpoint(opts.apiUrl ?? "", "/graphql");
+  const signingSecret = opts.signingSecret || callback.signingKey;
+  if (!signingSecret) {
+    throw new Error(
+      "createCallbackClient: nothing to sign with. The dispatch carried no callback.signingKey and no signingSecret was passed."
+    );
+  }
+  const post = async (mutationName, fields, variables) => {
+    const query = `mutation ${mutationName}Mutation($id: String!${fieldArgsForMutation(mutationName, variables)}) { ${mutationName}(id: $id${fieldArgsCallSite(mutationName, variables)}) { ${fields} } }`;
+    const body = JSON.stringify({
+      query,
+      variables: { id: executionId, ...variables }
+    });
+    const signature = await hmacSha256Hex(signingSecret, body);
+    return withFoirRetry(async () => {
+      let resp;
+      try {
+        resp = await fetchImpl(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${callback.token}`,
+            "X-Foir-Signature": `sha256=${signature}`
+          },
+          body,
+          ...opts.signal ? { signal: opts.signal } : {}
+        });
+      } catch (err) {
+        if (opts.signal?.aborted) throw err;
+        throw new FoirRequestError(`callback ${mutationName} got no answer`, { cause: err });
+      }
+      if (!resp.ok) {
+        throw new FoirRequestError(
+          `callback ${mutationName} failed with HTTP ${resp.status}: ${await resp.text()}`,
+          { status: resp.status }
+        );
+      }
+      const json = await resp.json();
+      if (json.errors?.length) {
+        throw new FoirRequestError(`callback ${mutationName} GraphQL error: ${json.errors[0].message}`, {
+          status: resp.status,
+          graphQLErrors: json.errors
+        });
+      }
+      const out = json.data?.[mutationName];
+      if (!out) {
+        throw new FoirRequestError(`callback ${mutationName} returned no data`, { status: resp.status });
+      }
+      return out;
+    }, opts.retry);
+  };
+  return {
+    complete: (result) => post(callback.mutations.complete, "status cancelled", { result }),
+    fail: (code, message, options = {}) => post(callback.mutations.fail, "status cancelled", {
+      code,
+      message,
+      retryable: options.retryable,
+      details: options.details
+    }),
+    progress: (update) => post(callback.mutations.progress, "status cancelled applied", {
+      pct: update.pct,
+      message: update.message,
+      metadata: update.metadata
+    }),
+    cancel: () => post(callback.mutations.cancel, "status cancelled", {})
+  };
+}
+function fieldArgsForMutation(mutationName, vars) {
+  const parts = [];
+  for (const key of Object.keys(vars)) {
+    if (vars[key] === void 0) continue;
+    parts.push(`, $${key}: ${graphQLTypeFor(mutationName, key)}`);
+  }
+  return parts.join("");
+}
+function fieldArgsCallSite(_mutationName, vars) {
+  const parts = [];
+  for (const key of Object.keys(vars)) {
+    if (vars[key] === void 0) continue;
+    parts.push(`, ${key}: $${key}`);
+  }
+  return parts.join("");
+}
+function graphQLTypeFor(mutationName, key) {
+  if (key === "code" || key === "message") return "String!";
+  if (key === "pct") return "Int";
+  if (key === "retryable") return "Boolean";
+  if (key === "details" || key === "metadata") return "JSON";
+  if (key === "result") {
+    const base = mutationName.replace(/^complete/, "").replace(/Execution$/, "");
+    return `${base}ExecutionResultInput!`;
+  }
+  if (key === "message") return "String";
+  return "String";
+}
+async function hmacSha256Hex(secret, body) {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(body));
+  return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
 
 // src/data/transport.ts
+async function resolveVisitorAddress(config) {
+  const source = config.visitor;
+  const value = typeof source === "function" ? await source() : source;
+  const address = value?.trim();
+  return address ? address : void 0;
+}
 async function resolveBearerToken(config) {
   const source = config.bearerToken;
   if (typeof source === "function") return await source() ?? void 0;
@@ -597,6 +874,7 @@ async function resolveFoirAuth(config) {
       bearerToken,
       orgId: config.orgId,
       orgUrl: config.orgUrl,
+      visitorAddress: await resolveVisitorAddress(config),
       extra: config.headers
     }),
     key: { apiKey: config.apiKey, bearerToken }
@@ -1222,16 +1500,26 @@ function asEventsSocketError(error, requestedCursor) {
   return error;
 }
 export {
+  CONTINUATION_MEDIA_TYPE,
+  FOIR_CONTEXT_HEADER,
   FOIR_EVENTS_PATH,
   FOIR_EVENTS_RETENTION_DAYS,
   FOIR_EVENTS_SCOPE,
+  FOIR_TOKEN_HEADER,
+  FoirAuthDowngradedError,
   FoirEventCursorExpiredError,
   FoirRequestError,
+  FoirSessionExpiredError,
+  MAX_CONTINUATION_CURSOR_BYTES,
+  MAX_CONTINUATION_DELAY_MS,
   OperationPayloadError,
   ScopedTokenError,
+  ScopedTokenUnavailableError,
   ServerClientError,
+  continueRun,
   createCallbackClient,
   createEventsClient,
+  createScopedTokenVerifier,
   createServerClient,
   isFoirEventCursorExpired,
   isFoirForbidden,