@foir/sdk 0.11.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.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";
@@ -119,6 +124,7 @@ function refuseCredentialHeaders(extra) {
     }
   }
 }
+var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
 function buildFoirHeaders(input) {
   const headers = {
     "Content-Type": "application/json"
@@ -143,6 +149,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)) {
@@ -158,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;
@@ -190,6 +219,9 @@ 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) {
@@ -314,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;
@@ -819,6 +851,12 @@ 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;
@@ -851,6 +889,7 @@ async function resolveFoirAuth(config) {
       bearerToken,
       orgId: config.orgId,
       orgUrl: config.orgUrl,
+      visitorAddress: await resolveVisitorAddress(config),
       extra: config.headers
     }),
     key: { apiKey: config.apiKey, bearerToken }
@@ -874,7 +913,33 @@ 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 { headers, key } = await resolveFoirAuth(config);
@@ -923,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 {
@@ -1137,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 };
@@ -1197,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");
@@ -1235,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) {
@@ -1454,6 +1567,8 @@ function trimSlash(s) {
 }
 export {
   AUTH_OPS,
+  FoirAuthDowngradedError,
+  FoirSessionExpiredError,
   authedOp,
   authedRequest,
   clearSession,
@@ -1488,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";
@@ -131,6 +136,7 @@ function refuseCredentialHeaders(extra) {
     }
   }
 }
+var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
 function buildFoirHeaders(input) {
   const headers = {
     "Content-Type": "application/json"
@@ -155,6 +161,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)) {
@@ -163,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;
@@ -195,6 +224,9 @@ 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) {
@@ -353,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;
@@ -406,7 +438,9 @@ function createFoirContentClient(config) {
 }
 export {
   FOIR_CDN_BASE,
+  FoirAuthDowngradedError,
   FoirRequestError,
+  FoirSessionExpiredError,
   absolutiseFoirMediaUrl,
   createFoirContentClient,
   foirRequest,

package/dist/data/index.d.ts

@@ -81,5 +81,5 @@ export type { FoirConnection, FoirFieldsShape, FoirModelDefinition, FoirNamespac
 export type { FoirInclude, FoirModelOperation, FoirNamespaceOperation, FoirOmittableKey, FoirOpResult, FoirQuery, FoirRecordResult, FoirWriteResult, } from './selection';
 export { FoirDecimal, decimal } from './decimal';
 export type { FoirDecimalDivOptions, FoirDecimalInput, FoirDecimalRounding, } from './decimal';
-export { FoirRequestError } from '../transport/foir-http';
-export type { FoirEnv, FoirGraphQLErrorItem, FoirTokenProvider, FoirAuthDowngrade, } from '../transport/foir-http';
+export { FoirRequestError, FoirAuthDowngradedError, FoirSessionExpiredError, FOIR_VISITOR_IP_HEADER, } from '../transport/foir-http';
+export type { FoirEnv, FoirGraphQLErrorItem, FoirTokenProvider, FoirAuthDowngrade, FoirVisitorSource, } from '../transport/foir-http';

package/dist/data/transport.d.ts

@@ -60,7 +60,7 @@
  * with more force here — this client is per-credential, so anything cached
  * across instances is cached across tenants.
  */
-import { FoirRequestError, type FoirTokenProvider } from '../transport/foir-http';
+import { FoirRequestError, type FoirTokenProvider, type FoirVisitorSource } from '../transport/foir-http';
 import type { FoirDocumentPlan, FoirNamespaceSelections, FoirSelections, FoirSelectionUnions } from './document';
 import type { FoirSchemaDefinition } from './schema';
 import type { FoirSubjectRegistry } from './subjects';
@@ -211,6 +211,18 @@ export interface FoirKeyClientConfig<S extends FoirSchemaDefinition = FoirSchema
      * per-request; a bare string is used as-is.
      */
     bearerToken?: string | FoirTokenProvider;
+    /**
+     * Renew the customer bearer when an answer comes back served without it
+     * because it expired. Resolve the new token, or null when the session is
+     * over. It is called at most once per request, and one call is shared by the
+     * client's requests that find the bearer lapsed at the same time.
+     *
+     * With it, such a request is asked again with the new token, and fails with
+     * `FoirSessionExpiredError` when there is none. Without it, the request fails
+     * with `FoirAuthDowngradedError`. Either way it is never handed the signed-out
+     * answer as though it were the signed-in one.
+     */
+    refreshBearer?: () => Promise<string | null>;
     /**
      * The organization every request from this client acts in, sent as
      * `X-Org-Id`.
@@ -246,6 +258,24 @@ export interface FoirKeyClientConfig<S extends FoirSchemaDefinition = FoirSchema
      * appear.
      */
     orgId?: string;
+    /**
+     * The address of the visitor a server rendering pages is calling for, or a
+     * function resolving it for each request, sent as `X-Foir-Visitor-IP`. The
+     * public API's per-visitor limit then applies to that visitor rather than to
+     * your server, which otherwise counts as one visitor for every page it
+     * renders.
+     *
+     * Give it the address your host guarantees: the one its edge sets and a
+     * visitor cannot. A header a visitor can write lets them name a fresh address
+     * per request, which is exactly what the limit exists to stop. The docs list
+     * the value for each common host.
+     *
+     * A secret key only, and one holding `visitors:forward`: the API refuses the
+     * header, naming the permission, from any other. A client built from a public
+     * key is refused `visitor` here, because a browser already calls as its own
+     * visitor and a public key cannot hold the permission.
+     */
+    visitor?: FoirVisitorSource;
     /**
      * The organization every request from this client acts in, named by the
      * address of the page it is for, sent as `X-Org-Url`.
@@ -483,7 +513,7 @@ export interface FoirKeyClientConfig<S extends FoirSchemaDefinition = FoirSchema
  * (a customer bearer, an organization, a channel), and the subscription socket,
  * which only a key can open.
  */
-type FoirKeySideOption = 'apiKey' | 'dispatch' | 'channel' | 'bearerToken' | 'orgId' | 'orgUrl' | 'wsUrl' | 'webSocketImpl' | 'reconnect' | 'connectionParams';
+type FoirKeySideOption = 'apiKey' | 'dispatch' | 'channel' | 'bearerToken' | 'refreshBearer' | 'orgId' | 'orgUrl' | 'visitor' | 'wsUrl' | 'webSocketImpl' | 'reconnect' | 'connectionParams';
 /**
  * A client that calls Foir AS an operation, from inside the endpoint the
  * operation dispatched to. See {@link FoirDispatchCredential}.
@@ -513,8 +543,10 @@ export interface FoirDispatchClientConfig<S extends FoirSchemaDefinition = FoirS
     apiKey?: never;
     channel?: never;
     bearerToken?: never;
+    refreshBearer?: never;
     orgId?: never;
     orgUrl?: never;
+    visitor?: never;
     wsUrl?: never;
     webSocketImpl?: never;
     reconnect?: never;

package/dist/data.js

@@ -62,7 +62,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";
@@ -92,6 +97,7 @@ function refuseCredentialHeaders(extra) {
     }
   }
 }
+var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
 function buildFoirHeaders(input) {
   const headers = {
     "Content-Type": "application/json"
@@ -116,6 +122,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)) {
@@ -131,6 +140,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;
@@ -163,6 +192,9 @@ 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) {
@@ -224,6 +256,12 @@ var FoirSchemaDriftError = class extends FoirRequestError {
 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;
@@ -256,6 +294,7 @@ async function resolveFoirAuth(config) {
       bearerToken,
       orgId: config.orgId,
       orgUrl: config.orgUrl,
+      visitorAddress: await resolveVisitorAddress(config),
       extra: config.headers
     }),
     key: { apiKey: config.apiKey, bearerToken }
@@ -270,6 +309,11 @@ function assertFoirCredential(config) {
         "[foir] createFoirClient needs both apiUrl and apiKey (or, inside an operation endpoint, apiUrl and dispatch)"
       );
     }
+    if (loose.visitor !== void 0 && !loose.apiKey.startsWith("sk_")) {
+      throw new FoirRequestError(
+        "[foir] createFoirClient: `visitor` names the visitor a server calls for, and only a secret key holding visitors:forward may send it. A public key already calls as its visitor, and cannot hold the permission. Drop `visitor`, or build this client from your server's secret key."
+      );
+    }
     if (operation !== void 0) {
       throw new FoirRequestError(
         `[foir] createFoirClient: the module passed as \`generated\` was generated for operation "${operation}" (\`foir types --operation ${operation}\`), so its types are what that operation's dispatch token is served, and this client holds an api key, which is served its own surface. Generate the key's types with \`foir types\`, or build this client from the dispatch token inside the operation's endpoint.`
@@ -280,8 +324,10 @@ function assertFoirCredential(config) {
   const keySide = [
     "apiKey",
     "bearerToken",
+    "refreshBearer",
     "orgId",
     "orgUrl",
+    "visitor",
     "channel",
     "wsUrl",
     "webSocketImpl",
@@ -347,7 +393,33 @@ async function executeFoirDocument(config, plan) {
 async function executeFoirRawDocument(config, document, mutation, variables, options) {
   return await runFoirDocument(config, document, mutation, variables, options);
 }
+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 { headers, key } = await resolveFoirAuth(config);
@@ -396,7 +468,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 {
@@ -2190,9 +2262,12 @@ function decimal(value) {
   return new FoirDecimal(value);
 }
 export {
+  FOIR_VISITOR_IP_HEADER,
+  FoirAuthDowngradedError,
   FoirDecimal,
   FoirRequestError,
   FoirSchemaDriftError,
+  FoirSessionExpiredError,
   FoirSocketTransport,
   createFoirClient,
   createFoirClientFromEnv,