@foir/sdk 0.10.0 → 0.12.0

package/dist/auth/auth.d.ts

@@ -213,7 +213,15 @@ export declare function registerOrganization(env: FoirEnv, vars: {
     name: string;
     parentId?: string;
 }, options?: AuthOpOptions): Promise<MyOrganization>;
-/** Persist an auth result to the session; returns the customer identity. */
+/**
+ * Persist an auth result to the session; returns the customer identity.
+ *
+ * A result that names no customer keeps the identity already stored. A refresh
+ * rotates the tokens of a session that already knows who it belongs to, and a
+ * platform that answers a refresh without the customer must not blank that:
+ * {@link requireAuth} reads the stored identity, so a valid token beside an
+ * empty identity reads as signed out.
+ */
 export declare function saveSession(adapter: SessionAdapter, result: CustomerAuthResult): Promise<FoirCustomer>;
 /** Clear all Foir auth keys from the session. */
 export declare function clearSession(adapter: SessionAdapter): Promise<void>;
@@ -262,13 +270,16 @@ export declare function signOut(adapter: SessionAdapter, env: FoirEnv): Promise<
  * or the refresh fails (the session is cleared in that case).
  */
 export declare function refreshSession(adapter: SessionAdapter, env: FoirEnv): Promise<FoirAuthTokens | null>;
+/** {@link refreshSession}, shared by every request of the session that asks while one is running. */
+export declare function refreshSessionOnce(adapter: SessionAdapter, env: FoirEnv): Promise<FoirAuthTokens | null>;
 /**
  * Run a bearer-authed GraphQL operation with refresh-with-retry: uses the
- * stored access token, and on a 401-shaped failure (rejected/expired bearer)
- * attempts a single token refresh and retries once. Any other error — network
- * blips, server errors, validation — propagates without a retry so transient
- * mutation failures can't be duplicated. Throws the original error if there's
- * no refresh path.
+ * stored access token, and when the session lapsed (a 401-shaped failure, or an
+ * answer served without the token) refreshes it once and retries once. Any
+ * other error — network blips, server errors, validation — propagates without a
+ * retry so transient mutation failures can't be duplicated. A 401 with no
+ * refresh path throws the original error; a lapsed session that cannot be
+ * renewed throws {@link FoirSessionExpiredError}.
  */
 export declare function authedRequest<TData, TVariables>(adapter: SessionAdapter, env: FoirEnv, document: TypedDocumentNode<TData, TVariables>, variables?: TVariables): Promise<TData>;
 /**
@@ -299,6 +310,13 @@ export interface RequireAuthOptions {
      * (e.g. `throw redirect(loginUrl)`). Must not return.
      */
     onUnauthenticated: () => never | Promise<never>;
+    /**
+     * The environment to ask when a session holds a token but no identity. With
+     * it, the identity is read once from `currentUser` and saved, rather than a
+     * session whose token verifies being turned away. Without it, such a session
+     * is treated as signed out.
+     */
+    env?: FoirEnv;
 }
 /**
  * Require a signed-in customer. Resolves the {@link FoirUser} via

package/dist/auth/index.d.ts

@@ -10,8 +10,9 @@
  * the caller's own manifest advertises, through the same op transport
  * `@foir/sdk/data` uses, so `graphql` is not on this module's path at all.
  */
-export { customerLogin, customerRegister, customerRequestOTP, customerLoginOTP, customerRefreshToken, customerLoginWithProvider, customerProviderCallback, customerProviderVerifyOTP, getAuthProviders, getAuthConfig, getDefaultAuthProvider, customerSignupContext, customerJoinWaitlist, customerRequestPasswordReset, customerResetPassword, customerUpdatePassword, customerVerifyEmail, currentUser, myProviderToken, customerLogout, deleteMyAccount, myOrganizations, selectOrganization, registerOrganization, saveSession, clearSession, getSessionToken, getSessionCustomer, loginWithPassword, registerWithPassword, loginWithOTP, resetPasswordAndSignIn, refreshSession, signOut, authedRequest, authedOp, requireAuth, requireAdmin, } from './auth';
+export { customerLogin, customerRegister, customerRequestOTP, customerLoginOTP, customerRefreshToken, customerLoginWithProvider, customerProviderCallback, customerProviderVerifyOTP, getAuthProviders, getAuthConfig, getDefaultAuthProvider, customerSignupContext, customerJoinWaitlist, customerRequestPasswordReset, customerResetPassword, customerUpdatePassword, customerVerifyEmail, currentUser, myProviderToken, customerLogout, deleteMyAccount, myOrganizations, selectOrganization, registerOrganization, saveSession, clearSession, getSessionToken, getSessionCustomer, loginWithPassword, registerWithPassword, loginWithOTP, resetPasswordAndSignIn, refreshSession, refreshSessionOnce, signOut, authedRequest, authedOp, requireAuth, requireAdmin, } from './auth';
 export type { FoirAuthTokens, FoirCustomer, FoirUser, SessionAdapter, RequireAuthOptions, RequireAdminOptions, } from './auth';
+export { FoirAuthDowngradedError, FoirSessionExpiredError } from '../graphql/foir-request';
 export { AUTH_OPS } from './ops';
 export type { AuthOpName, AuthOpOptions } from './ops';
 export { hostedLoginUrl, hostedLogoutUrl, fetchHostedSession } from './hosted';

package/dist/auth/ops.d.ts

@@ -81,6 +81,14 @@ export interface AuthOpOptions {
      * already confined to an organization may only name its own.
      */
     orgId?: string;
+    /**
+     * The organization the call acts in, named by the address of the page it is
+     * for, sent as `X-Org-Url`: same contract as `FoirClientConfig.orgUrl`. A
+     * storefront on a path per organization signs its customers in on those
+     * pages, and names the organization the way every other request from them
+     * does.
+     */
+    orgUrl?: string;
     /**
      * `fetch` implementation. Defaults to `globalThis.fetch`. Injectable for
      * tests and for runtimes that hand you a bound `fetch` (Hydrogen/Oxygen).

package/dist/auth.js

@@ -68,7 +68,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";
@@ -103,19 +108,50 @@ function readFoirRetryAfterMs(headers) {
   const seconds = Number(headers.get("Retry-After"));
   return Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : void 0;
 }
+var DISPATCH_RESERVED_HEADERS = /* @__PURE__ */ new Set([
+  "x-api-key",
+  "authorization",
+  "x-foir-token",
+  "x-foir-context"
+]);
+function refuseCredentialHeaders(extra) {
+  if (!extra) return;
+  for (const name of Object.keys(extra)) {
+    if (DISPATCH_RESERVED_HEADERS.has(name.toLowerCase())) {
+      throw new FoirRequestError(
+        `[foir] a client built from a dispatch token cannot send "${name}" in \`headers\`. The dispatch token is the credential, and an api key or a bearer beside it would make the request two actors at once. Build a separate client for the other credential.`
+      );
+    }
+  }
+}
+var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
 function buildFoirHeaders(input) {
   const headers = {
-    "Content-Type": "application/json",
-    "x-api-key": input.apiKey
+    "Content-Type": "application/json"
   };
-  if (input.draftChannel) {
-    headers["X-Foir-Schema-Channel"] = "draft";
-  }
-  if (input.bearerToken) {
-    headers["Authorization"] = `Bearer ${input.bearerToken}`;
-  }
-  if (input.orgId) {
-    headers["X-Org-Id"] = input.orgId;
+  if (input.dispatchToken !== void 0) {
+    refuseCredentialHeaders(input.extra);
+    headers["X-Foir-Token"] = input.dispatchToken;
+    if (input.dispatchContext) {
+      headers["X-Foir-Context"] = input.dispatchContext;
+    }
+  } else {
+    headers["x-api-key"] = input.apiKey;
+    if (input.draftChannel) {
+      headers["X-Foir-Schema-Channel"] = "draft";
+    }
+    if (input.bearerToken) {
+      headers["Authorization"] = `Bearer ${input.bearerToken}`;
+    }
+    if (input.orgId) {
+      headers["X-Org-Id"] = input.orgId;
+    }
+    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)) {
@@ -131,6 +167,26 @@ 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";
+  }
+};
 var warnedDowngrade = null;
 function reportAuthDowngrade(envelope) {
   const downgrade = envelope.extensions?.auth;
@@ -159,12 +215,18 @@ function refusePrunedDocument(json, options) {
     `[foir] selections stripped from this query: ${selections.map(describe).join(", ")}`
   );
 }
+function answeredAnything(data) {
+  return typeof data === "object" && data !== null && Object.values(data).some((value) => value !== null && value !== void 0);
+}
 function readFoirEnvelope(json, options) {
+  if (options?.rejectDowngrade && json.extensions?.auth) {
+    throw new FoirAuthDowngradedError(json.extensions.auth);
+  }
   reportAuthDowngrade(json);
   refusePrunedDocument(json, options);
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
-    if (json.data && !options?.strict) {
+    if (answeredAnything(json.data) && !options?.strict) {
       console.warn(`[foir] GraphQL partial errors (data returned): ${msg}`);
     } else {
       throw new FoirRequestError(`[foir] GraphQL errors: ${msg}`, {
@@ -232,12 +294,13 @@ async function foirRequest(env, document, variables, options) {
     apiKey,
     draftChannel: isFoirPreview(env),
     bearerToken: options?.bearerToken,
-    orgId: options?.orgId
+    orgId: options?.orgId,
+    orgUrl: options?.orgUrl
   });
   const documentText = print2(document);
   let res;
   try {
-    if (isCdnEligible(env, documentText, options?.bearerToken, options?.orgId)) {
+    if (isCdnEligible(env, documentText, options?.bearerToken, options?.orgId ?? options?.orgUrl)) {
       const hash = await documentHash(documentText);
       let shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
         method: "GET",
@@ -283,7 +346,7 @@ async function foirRequest(env, document, variables, options) {
     );
   }
   const json = await res.json();
-  return readFoirEnvelope(json);
+  return readFoirEnvelope(json, { rejectDowngrade: options?.rejectDowngrade });
 }
 async function readErrorEnvelope(res) {
   let errors;
@@ -788,15 +851,54 @@ function operationName(scope, op) {
 function foirDataEndpoint(apiUrl, path) {
   return foirApiEndpoint(apiUrl, path);
 }
+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;
   return source ?? void 0;
 }
+async function resolveDispatchToken(dispatch) {
+  const token = (await dispatch.token())?.trim();
+  if (!token) {
+    throw new FoirRequestError(
+      "[foir] the dispatch token provider returned no token. A client built from a dispatch calls Foir as that operation and holds no other credential. Build it from the token the endpoint was handed: `(await requireScopedToken(request)).dispatch`."
+    );
+  }
+  return token;
+}
+async function resolveFoirAuth(config) {
+  if (config.dispatch !== void 0) {
+    return {
+      headers: buildFoirHeaders({
+        dispatchToken: await resolveDispatchToken(config.dispatch),
+        dispatchContext: config.dispatch.context ?? void 0,
+        extra: config.headers
+      })
+    };
+  }
+  const bearerToken = await resolveBearerToken(config);
+  return {
+    headers: buildFoirHeaders({
+      apiKey: config.apiKey,
+      draftChannel: config.channel === "draft",
+      bearerToken,
+      orgId: config.orgId,
+      orgUrl: config.orgUrl,
+      visitorAddress: await resolveVisitorAddress(config),
+      extra: config.headers
+    }),
+    key: { apiKey: config.apiKey, bearerToken }
+  };
+}
 function foirRoute(input) {
   if (!input.apiKey.startsWith("pk_")) return { lane: "origin", reason: "key" };
   if (input.bearerToken) return { lane: "origin", reason: "bearer" };
-  if (input.orgId) return { lane: "origin", reason: "org" };
+  if (input.orgId || input.orgUrl) return { lane: "origin", reason: "org" };
   if (input.mutation) return { lane: "origin", reason: "operation" };
   if (input.writeToken) return { lane: "origin", reason: "floor" };
   if (input.channel === "draft") return { lane: "origin", reason: "channel" };
@@ -811,25 +913,45 @@ async function executeFoirDocument(config, plan) {
   }
   return data[plan.rootField];
 }
+var renewing = /* @__PURE__ */ new WeakMap();
+function renewBearerOnce(refresh) {
+  const running = renewing.get(refresh);
+  if (running) return running;
+  const next = refresh().finally(() => renewing.delete(refresh));
+  renewing.set(refresh, next);
+  return next;
+}
 async function runFoirDocument(config, document, mutation, variables, options) {
+  try {
+    return await sendFoirDocument(config, document, mutation, variables, options);
+  } catch (err) {
+    const refresh = config.refreshBearer;
+    if (!(err instanceof FoirAuthDowngradedError) || !refresh || err.downgrade.reason === "wrong_project") {
+      throw err;
+    }
+    const token = err.downgrade.reason === "expired" ? await renewBearerOnce(refresh) : null;
+    if (!token) throw new FoirSessionExpiredError({ cause: err });
+    try {
+      return await sendFoirDocument({ ...config, bearerToken: token }, document, mutation, variables, options);
+    } catch (again) {
+      if (again instanceof FoirAuthDowngradedError) throw new FoirSessionExpiredError({ cause: again });
+      throw again;
+    }
+  }
+}
+async function sendFoirDocument(config, document, mutation, variables, options) {
   const doFetch = config.fetch ?? globalThis.fetch;
   const endpoint = foirDataEndpoint(config.apiUrl, "/graphql");
-  const bearerToken = await resolveBearerToken(config);
-  const headers = buildFoirHeaders({
-    apiKey: config.apiKey,
-    draftChannel: config.channel === "draft",
-    bearerToken,
-    orgId: config.orgId,
-    extra: config.headers
-  });
+  const { headers, key } = await resolveFoirAuth(config);
   const hash = await documentHash(document);
-  const route = foirRoute({
-    apiKey: config.apiKey,
-    bearerToken,
+  const sharedKey = key !== void 0 && foirRoute({
+    apiKey: key.apiKey,
+    bearerToken: key.bearerToken,
     orgId: config.orgId,
+    orgUrl: config.orgUrl,
     mutation,
     channel: config.channel
-  });
+  }).lane === "shared" ? key.apiKey : void 0;
   const post = (body) => doFetch(endpoint, {
     method: "POST",
     headers,
@@ -839,8 +961,8 @@ async function runFoirDocument(config, document, mutation, variables, options) {
   const extensions = persistedQueryExtension(hash);
   let res;
   try {
-    if (route.lane === "shared") {
-      res = await doFetch(buildCdnUrl(endpoint, config.apiKey, hash, variables), {
+    if (sharedKey !== void 0) {
+      res = await doFetch(buildCdnUrl(endpoint, sharedKey, hash, variables), {
         method: "GET",
         headers,
         ...config.requestInit
@@ -866,7 +988,7 @@ async function runFoirDocument(config, document, mutation, variables, options) {
     });
   }
   const json = await res.json();
-  return readFoirEnvelope(json, options);
+  return readFoirEnvelope(json, { ...options, rejectDowngrade: Boolean(key?.bearerToken) });
 }
 async function readErrorBody(res) {
   try {
@@ -878,20 +1000,16 @@ async function readErrorBody(res) {
 }
 
 // src/data/manifest.ts
-async function fetchFoirManifest(config) {
-  const url = foirDataEndpoint(config.apiUrl, "/v1/manifest");
+async function fetchFoirManifest(config, options = {}) {
+  const base = foirDataEndpoint(config.apiUrl, "/v1/manifest");
+  const url = options.operation === void 0 ? base : `${base}?operation=${encodeURIComponent(options.operation)}`;
   const doFetch = config.fetch ?? globalThis.fetch;
+  const { headers } = await resolveFoirAuth(config);
   let res;
   try {
     res = await doFetch(url, {
       method: "GET",
-      headers: buildFoirHeaders({
-        apiKey: config.apiKey,
-        draftChannel: config.channel === "draft",
-        bearerToken: await resolveBearerToken(config),
-        orgId: config.orgId,
-        extra: config.headers
-      }),
+      headers,
       ...config.requestInit
     });
   } catch (err) {
@@ -963,6 +1081,7 @@ function authClientConfig(env, options) {
     channel: isFoirPreview(env) ? "draft" : "published",
     bearerToken: options?.bearerToken,
     orgId: options?.orgId,
+    orgUrl: options?.orgUrl,
     headers: options?.headers,
     fetch: options?.fetch
   };
@@ -1083,6 +1202,9 @@ async function registerOrganization(env, vars, options) {
 async function saveSession(adapter, result) {
   await adapter.set(TOKEN_KEY, result.token);
   await adapter.set(REFRESH_KEY, result.refreshToken);
+  if (!result.customerId) {
+    return await getSessionCustomer(adapter) ?? { id: "", email: "" };
+  }
   await adapter.set(CUSTOMER_ID_KEY, result.customerId);
   await adapter.set(EMAIL_KEY, result.email);
   return { id: result.customerId, email: result.email };
@@ -1143,35 +1265,68 @@ function isAuthExpiredError(err) {
     (e) => /authentication required/i.test(e.message)
   );
 }
-async function authedRequest(adapter, env, document, variables) {
-  const token = await getSessionToken(adapter);
-  try {
-    return await foirRequest(env, document, variables, {
-      bearerToken: token ?? void 0
-    });
-  } catch (err) {
-    if (!isAuthExpiredError(err)) throw err;
-    const refreshed = await refreshSession(adapter, env);
-    if (!refreshed) throw err;
-    return foirRequest(env, document, variables, {
-      bearerToken: refreshed.token
-    });
+var refreshing = /* @__PURE__ */ new WeakMap();
+function refreshSessionOnce(adapter, env) {
+  const running = refreshing.get(adapter);
+  if (running) return running;
+  const next = refreshSession(adapter, env).finally(() => refreshing.delete(adapter));
+  refreshing.set(adapter, next);
+  return next;
+}
+function sessionLapse(err) {
+  if (err instanceof FoirAuthDowngradedError) {
+    switch (err.downgrade.reason) {
+      case "expired":
+        return "refresh";
+      case "invalid":
+        return "expired";
+      default:
+        return null;
+    }
   }
+  return isAuthExpiredError(err) ? "refresh" : null;
 }
-async function authedOp(adapter, env, op, args) {
+async function withSessionRefresh(adapter, env, run) {
   const token = await getSessionToken(adapter);
   try {
-    return await authOp(env, op, args, { bearerToken: token ?? void 0 });
+    return await run(token ?? void 0);
   } catch (err) {
-    if (!isAuthExpiredError(err)) throw err;
-    const refreshed = await refreshSession(adapter, env);
-    if (!refreshed) throw err;
-    return authOp(env, op, args, { bearerToken: refreshed.token });
+    const lapse = sessionLapse(err);
+    if (!lapse) throw err;
+    if (lapse === "expired") throw new FoirSessionExpiredError({ cause: err });
+    const refreshed = await refreshSessionOnce(adapter, env);
+    if (!refreshed) {
+      if (err instanceof FoirAuthDowngradedError) throw new FoirSessionExpiredError({ cause: err });
+      throw err;
+    }
+    try {
+      return await run(refreshed.token);
+    } catch (again) {
+      if (again instanceof FoirAuthDowngradedError) throw new FoirSessionExpiredError({ cause: again });
+      throw again;
+    }
   }
 }
+async function authedRequest(adapter, env, document, variables) {
+  return withSessionRefresh(
+    adapter,
+    env,
+    (bearerToken) => foirRequest(env, document, variables, { bearerToken, rejectDowngrade: true })
+  );
+}
+async function authedOp(adapter, env, op, args) {
+  return withSessionRefresh(
+    adapter,
+    env,
+    (bearerToken) => authOp(env, op, args, { bearerToken })
+  );
+}
 async function requireAuth(adapter, options) {
   const token = await getSessionToken(adapter);
-  const customer = await getSessionCustomer(adapter);
+  let customer = await getSessionCustomer(adapter);
+  if (token && !customer && options.env) {
+    customer = await recoverSessionCustomer(adapter, options.env, token);
+  }
   if (!token || !customer) {
     await options.onUnauthenticated();
     throw new Error("[foir] onUnauthenticated must not return");
@@ -1181,6 +1336,18 @@ async function requireAuth(adapter, options) {
   }
   return { id: customer.id, email: customer.email, isAdmin: false };
 }
+async function recoverSessionCustomer(adapter, env, token) {
+  let me;
+  try {
+    me = await currentUser(env, { bearerToken: token });
+  } catch {
+    return null;
+  }
+  if (!me?.id) return null;
+  await adapter.set(CUSTOMER_ID_KEY, me.id);
+  await adapter.set(EMAIL_KEY, me.email);
+  return { id: me.id, email: me.email };
+}
 async function requireAdmin(adapter, options) {
   const user = await requireAuth(adapter, options);
   if (!user.isAdmin) {
@@ -1400,6 +1567,8 @@ function trimSlash(s) {
 }
 export {
   AUTH_OPS,
+  FoirAuthDowngradedError,
+  FoirSessionExpiredError,
   authedOp,
   authedRequest,
   clearSession,
@@ -1434,6 +1603,7 @@ export {
   myOrganizations,
   myProviderToken,
   refreshSession,
+  refreshSessionOnce,
   registerOrganization,
   registerWithPassword,
   requireAdmin,

package/dist/client.js

@@ -68,7 +68,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";
@@ -115,19 +120,50 @@ function readFoirRetryAfterMs(headers) {
   const seconds = Number(headers.get("Retry-After"));
   return Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : void 0;
 }
+var DISPATCH_RESERVED_HEADERS = /* @__PURE__ */ new Set([
+  "x-api-key",
+  "authorization",
+  "x-foir-token",
+  "x-foir-context"
+]);
+function refuseCredentialHeaders(extra) {
+  if (!extra) return;
+  for (const name of Object.keys(extra)) {
+    if (DISPATCH_RESERVED_HEADERS.has(name.toLowerCase())) {
+      throw new FoirRequestError(
+        `[foir] a client built from a dispatch token cannot send "${name}" in \`headers\`. The dispatch token is the credential, and an api key or a bearer beside it would make the request two actors at once. Build a separate client for the other credential.`
+      );
+    }
+  }
+}
+var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
 function buildFoirHeaders(input) {
   const headers = {
-    "Content-Type": "application/json",
-    "x-api-key": input.apiKey
+    "Content-Type": "application/json"
   };
-  if (input.draftChannel) {
-    headers["X-Foir-Schema-Channel"] = "draft";
-  }
-  if (input.bearerToken) {
-    headers["Authorization"] = `Bearer ${input.bearerToken}`;
-  }
-  if (input.orgId) {
-    headers["X-Org-Id"] = input.orgId;
+  if (input.dispatchToken !== void 0) {
+    refuseCredentialHeaders(input.extra);
+    headers["X-Foir-Token"] = input.dispatchToken;
+    if (input.dispatchContext) {
+      headers["X-Foir-Context"] = input.dispatchContext;
+    }
+  } else {
+    headers["x-api-key"] = input.apiKey;
+    if (input.draftChannel) {
+      headers["X-Foir-Schema-Channel"] = "draft";
+    }
+    if (input.bearerToken) {
+      headers["Authorization"] = `Bearer ${input.bearerToken}`;
+    }
+    if (input.orgId) {
+      headers["X-Org-Id"] = input.orgId;
+    }
+    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)) {
@@ -136,6 +172,26 @@ function buildFoirHeaders(input) {
   }
   return headers;
 }
+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";
+  }
+};
 var warnedDowngrade = null;
 function reportAuthDowngrade(envelope) {
   const downgrade = envelope.extensions?.auth;
@@ -164,12 +220,18 @@ function refusePrunedDocument(json, options) {
     `[foir] selections stripped from this query: ${selections.map(describe).join(", ")}`
   );
 }
+function answeredAnything(data) {
+  return typeof data === "object" && data !== null && Object.values(data).some((value) => value !== null && value !== void 0);
+}
 function readFoirEnvelope(json, options) {
+  if (options?.rejectDowngrade && json.extensions?.auth) {
+    throw new FoirAuthDowngradedError(json.extensions.auth);
+  }
   reportAuthDowngrade(json);
   refusePrunedDocument(json, options);
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
-    if (json.data && !options?.strict) {
+    if (answeredAnything(json.data) && !options?.strict) {
       console.warn(`[foir] GraphQL partial errors (data returned): ${msg}`);
     } else {
       throw new FoirRequestError(`[foir] GraphQL errors: ${msg}`, {
@@ -271,12 +333,13 @@ async function foirRequest(env, document, variables, options) {
     apiKey,
     draftChannel: isFoirPreview(env),
     bearerToken: options?.bearerToken,
-    orgId: options?.orgId
+    orgId: options?.orgId,
+    orgUrl: options?.orgUrl
   });
   const documentText = print2(document);
   let res;
   try {
-    if (isCdnEligible(env, documentText, options?.bearerToken, options?.orgId)) {
+    if (isCdnEligible(env, documentText, options?.bearerToken, options?.orgId ?? options?.orgUrl)) {
       const hash = await documentHash(documentText);
       let shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
         method: "GET",
@@ -322,7 +385,7 @@ async function foirRequest(env, document, variables, options) {
     );
   }
   const json = await res.json();
-  return readFoirEnvelope(json);
+  return readFoirEnvelope(json, { rejectDowngrade: options?.rejectDowngrade });
 }
 async function readErrorEnvelope(res) {
   let errors;
@@ -375,7 +438,9 @@ function createFoirContentClient(config) {
 }
 export {
   FOIR_CDN_BASE,
+  FoirAuthDowngradedError,
   FoirRequestError,
+  FoirSessionExpiredError,
   absolutiseFoirMediaUrl,
   createFoirContentClient,
   foirRequest,