@foir/sdk 0.20.0 → 0.22.0

package/dist/client/platform-client.d.ts

@@ -17,7 +17,7 @@ export declare class PlatformClientError extends Error {
  * ```ts
  * const client = createPlatformClient({
  *   apiUrl: 'https://api.example.com/graphql',
- *   apiKey: 'sk_test_...',
+ *   apiKey: 'foir_pub_...', // runs in the browser: a publishable key only
  * });
  *
  * const { data } = await client.query(

package/dist/client.js

@@ -1,6 +1,30 @@
 // src/graphql/foir-request.ts
 import { print as print2 } from "graphql";
 
+// src/transport/key-kind.ts
+var KEY_PREFIXES = [
+  ["foir_pub_", "publishable"],
+  ["foir_srv_", "server"],
+  ["foir_adm_", "admin"],
+  ["pk_", "publishable"],
+  ["sk_", "older"],
+  ["tc_", "older"]
+];
+var FOIR_CREDENTIALS_DOC = "https://docs.foir.dev/credentials";
+function foirKeyKind(apiKey) {
+  if (typeof apiKey !== "string") return void 0;
+  for (const [prefix, kind] of KEY_PREFIXES) {
+    if (apiKey.startsWith(prefix)) return kind;
+  }
+  return void 0;
+}
+function adminKeyRefusal(client) {
+  return `[foir] ${client} was given an admin key. An admin key is a machine's own: nobody signs in through it, and an app never holds one. Build this client from your publishable key, or from your server key on the server that renders your pages. A machine that acts for itself uses createServerClient from @foir/sdk/server. See ${FOIR_CREDENTIALS_DOC}`;
+}
+function isPublishableFoirKey(apiKey) {
+  return foirKeyKind(apiKey) === "publishable";
+}
+
 // src/graphql/cdn-route.ts
 import { print } from "graphql";
 
@@ -176,8 +200,8 @@ 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" } }] }
+      `[foir] your user token was ${downgrade.userToken} (${downgrade.reason}), so the request was served as ${downgrade.servedAs}`,
+      { graphQLErrors: [{ message: "user token rejected", extensions: { code: "AUTH_DOWNGRADED" } }] }
     );
     this.name = "FoirAuthDowngradedError";
     this.downgrade = downgrade;
@@ -185,7 +209,7 @@ var FoirAuthDowngradedError = class extends FoirRequestError {
 };
 var FoirSessionExpiredError = class extends FoirRequestError {
   constructor(options) {
-    super("[foir] the customer session has expired and could not be refreshed: sign in again", {
+    super("[foir] the user session has expired and could not be refreshed: sign in again", {
       cause: options?.cause,
       graphQLErrors: [{ message: "session expired", extensions: { code: "SESSION_EXPIRED" } }]
     });
@@ -202,7 +226,7 @@ function reportAuthDowngrade(envelope) {
   if (warnedDowngrade === downgrade.reason) return;
   warnedDowngrade = downgrade.reason;
   console.warn(
-    `[foir] your customer token was ${downgrade.customerToken} (${downgrade.reason}) \u2014 this request was served as ${downgrade.servedAs}, so auth-targeted content resolved to its anonymous variant. ` + (downgrade.reason === "expired" ? "Re-exchange the token and retry." : "Check which credential you are sending.")
+    `[foir] your user token was ${downgrade.userToken} (${downgrade.reason}) \u2014 this request was served as ${downgrade.servedAs}, so auth-targeted content resolved to its anonymous variant. ` + (downgrade.reason === "expired" ? "Re-exchange the token and retry." : "Check which credential you are sending.")
   );
 }
 function refusePrunedDocument(json, options) {
@@ -282,7 +306,7 @@ function isCdnEligible(env, documentText, bearerToken, orgId) {
   if (orgId) return false;
   if (isFoirPreview(env)) return false;
   const apiKey = resolveFoirApiKey(env);
-  if (!apiKey?.startsWith("pk_")) return false;
+  if (!isPublishableFoirKey(apiKey)) return false;
   return !/\bmutation\b/.test(documentText);
 }
 
@@ -329,6 +353,9 @@ async function foirRequest(env, document, variables, options) {
       "[foir] PLATFORM_API_URL or PLATFORM_API_KEY is not set \u2014 add them to .env"
     );
   }
+  if (foirKeyKind(apiKey) === "admin") {
+    throw new FoirRequestError(adminKeyRefusal("foirRequest"));
+  }
   const headers = buildFoirHeaders({
     apiKey,
     draftChannel: isFoirPreview(env),

package/dist/codegen/index.js

@@ -15,7 +15,7 @@ function schemaEntry(apiUrl, key) {
         headers: {
           "x-api-key": key ?? "",
           // Read the draft channel so freshly pushed changes are visible
-          // (silently ignored by public keys, which can't see drafts).
+          // (ignored by an app's key that does not hold drafts:read).
           "X-Foir-Schema-Channel": "draft"
         }
       }

package/dist/data/builtins.d.ts

@@ -398,7 +398,7 @@ export type FoirUnexpandedRecord = FoirDegraded;
 export type FoirVisibility = 'PRIVATE' | 'PUBLIC';
 export type FoirAccessLevel = 'READ' | 'WRITE' | 'DELETE';
 export type FoirAccessSource = 'PUBLIC' | 'OWNER' | 'GRANT' | 'ROLE';
-export type FoirGranteeKind = 'CUSTOMER' | 'ADMIN';
+export type FoirGranteeKind = 'USER';
 /** `myAccess` — this principal's effective access to one record. */
 export interface FoirMyAccess {
     access: FoirAccessLevel;
@@ -435,9 +435,9 @@ export interface FoirUpdateManyPayload {
 }
 /**
  * `setOwner`: who the record belongs to after an operation handed it to
- * another customer. It carries the owner and not the record, because the
+ * another user. It carries the owner and not the record, because the
  * operation may have been acting for the previous holder, who can no longer
- * read it. `ownerKind` is always `'customer'` from this op.
+ * read it. `ownerKind` is always `'user'` from this op.
  */
 export interface FoirRecordOwner {
     id: string;
@@ -445,7 +445,7 @@ export interface FoirRecordOwner {
     ownerKind: string;
 }
 /**
- * What a customer's note can be ABOUT: the customer-plane subset of the closed
+ * What a user's note can be ABOUT: the user-plane subset of the closed
  * set the platform's write path enforces.
  *
  * On the wire it is `String!`, not a GraphQL enum, so the manifest publishes no
@@ -458,23 +458,23 @@ export interface FoirRecordOwner {
  * record is `'record'` plus the model key on `subjectModelKey`.
  *
  * The platform set also holds `project` and `organization`, and this union
- * deliberately does not. Both are operator constructs: the platform answers a
- * note about either through a row policy no customer claim passes, so no note
+ * deliberately does not. Both are the project's own constructs: the platform answers a
+ * note about either through a row policy no user claim passes, so no note
  * this surface reads or writes can carry them. This mirrors the part of the
- * platform set a customer can reach, and the obligation that comes with a mirror
- * (see the file header) applies: a kind the platform opens to customers widens
+ * platform set a user can reach, and the obligation that comes with a mirror
+ * (see the file header) applies: a kind the platform opens to users widens
  * this union in a minor release, and until then a value outside it is a row no
- * customer writer could have produced.
+ * user writer could have produced.
  */
-export type FoirNoteSubjectType = 'record' | 'file' | 'model' | 'operation' | 'schedule' | 'customer';
+export type FoirNoteSubjectType = 'record' | 'file' | 'model' | 'operation' | 'schedule' | 'user';
 /**
- * One file the customer submitted with their note.
+ * One file the user submitted with their note.
  *
  * The file's own facts, and nothing about the platform's handling of it: when
  * the link row was written and which retention clock it starts are not the
  * author's business. What is here is enough to render "you sent this".
  */
-export interface FoirCustomerNoteAttachment {
+export interface FoirUserNoteAttachment {
     /** The file's id — the same one `createMyNote` was given. */
     fileId: string;
     filename: string;
@@ -484,15 +484,15 @@ export interface FoirCustomerNoteAttachment {
     url: string;
 }
 /**
- * One note on the customer plane — `foir.ns.notes.myNotes` and
+ * One note on the user plane — `foir.ns.notes.myNotes` and
  * `foir.ns.notes.createMyNote`.
  *
  * Deliberately narrower than the note your team sees in the dashboard. There is
  * no visibility, no resolution note, no mentions and no metadata: those are the
- * project's view of a thread, not the author's, and the customer-facing type
+ * project's view of a thread, not the author's, and the user-facing type
  * does not merely omit them from the document — the surface does not carry them.
  */
-export interface FoirCustomerNote {
+export interface FoirUserNote {
     id: string;
     /** The note's prose. */
     body: string | null;
@@ -507,12 +507,12 @@ export interface FoirCustomerNote {
     /**
      * The files submitted with this note. Empty when there are none.
      *
-     * The one place the customer surface is WIDER than "the author's own prose",
+     * The one place the user surface is WIDER than "the author's own prose",
      * and deliberately: an author who attached a screenshot has to be able to see
      * that it arrived, or the only readings left to them are that it failed
      * silently or that it was taken away.
      */
-    attachments: FoirCustomerNoteAttachment[];
+    attachments: FoirUserNoteAttachment[];
     /** ISO-8601. */
     createdAt: string;
 }
@@ -521,7 +521,7 @@ export interface FoirCustomerNote {
  * — `foir.ns.notes.noteConfig`.
  *
  * Charged `notes:create` rather than `notes:read`, and refused to a caller with
- * no customer session, because the only caller it is useful to is one that can
+ * no user session, because the only caller it is useful to is one that can
  * submit. So a composer can read it as its single readiness probe: an answer
  * means this visitor may write, and a refusal names which half is missing.
  */
@@ -546,16 +546,16 @@ export interface FoirMyNotesArgs {
     threadRootId?: string;
 }
 /**
- * `myNotes` — the notes this customer wrote, plus the replies your team
- * deliberately sent them. Never another customer's, and never an operator's
+ * `myNotes` — the notes this user wrote, plus the replies your team
+ * deliberately sent them. Never another user's, and never your team's
  * internal ones.
  */
-export type FoirMyNotesResult = FoirConnection<FoirCustomerNote>;
+export type FoirMyNotesResult = FoirConnection<FoirUserNote>;
 /**
- * `writeNote` arguments: the one note create, for a signed-in customer and for
+ * `writeNote` arguments: the one note create, for a signed-in user and for
  * a visitor alike. It asks `notes:create` of both.
  *
- * A signed-in customer's note is theirs and comes back in `myNotes`. A
+ * A signed-in user's note is theirs and comes back in `myNotes`. A
  * visitor's, through a key that gives `notes:create` to whoever comes through
  * it, on a project that takes visitors' notes, is nobody's: ask for its `id`
  * and `createdAt` and nothing else, because nothing reads it back.
@@ -584,8 +584,8 @@ export interface FoirWriteNoteArgs {
      */
     attachmentFileIds?: string[];
     /**
-     * Where the operators may reply to a visitor. Refused from a signed-in
-     * customer, whose note has an author.
+     * Where your team may reply to a visitor. Refused from a signed-in
+     * user, whose note has an author.
      *
      * Captured as typed and NEVER verified: it is not treated as proof of who
      * wrote the note, and nothing is sent to it to confirm it. Do not build a
@@ -597,7 +597,7 @@ export interface FoirWriteNoteArgs {
  * `createMyNote` arguments.
  *
  * @deprecated `createMyNote` is the older name of `writeNote` for a signed-in
- * customer. Use `writeNote` and {@link FoirWriteNoteArgs}.
+ * user. Use `writeNote` and {@link FoirWriteNoteArgs}.
  */
 export interface FoirCreateMyNoteArgs {
     subjectType: FoirNoteSubjectType;
@@ -618,62 +618,6 @@ export interface FoirCreateMyNoteArgs {
      */
     attachmentFileIds?: string[];
 }
-/**
- * `submitAnonymousNote` arguments — feedback from a visitor with no account.
- *
- * Present on the project's schema only while the project has opted in
- * (Notes settings → "Accept anonymous notes"). The feedback widget does NOT
- * use this: a signed-out visitor there is still asked to sign in, so this
- * mutation is the only path a visitor's note can take.
- *
- * WRITE-ONLY. Nothing reads an anonymous note back on the public plane, which
- * is why the result is a receipt rather than the note.
- *
- * @deprecated `submitAnonymousNote` is the older name of `writeNote` for a
- * visitor. Use `writeNote` and {@link FoirWriteNoteArgs}, asking for `id` and
- * `createdAt`.
- */
-export interface FoirSubmitAnonymousNoteArgs {
-    /**
-     * Must be `'record'` — the only thing a visitor may write a note about.
-     * Narrower than `FoirCreateMyNoteArgs`, where a customer may also address a
-     * file or a model.
-     */
-    subjectType: 'record';
-    subjectId: string;
-    /**
-     * The record's model key. REQUIRED here, unlike on `createMyNote` where it is
-     * conditional: the subject is always a record on this lane, so the condition
-     * is always met.
-     */
-    subjectModelKey: string;
-    body: string;
-    /**
-     * Optional. Where the operators may reply.
-     *
-     * Captured as typed and NEVER verified — it is not treated as proof of who
-     * wrote the note, and nothing is sent to it to confirm it. Do not build a
-     * flow that assumes the address is reachable.
-     */
-    contactEmail?: string;
-}
-/**
- * What `submitAnonymousNote` returns.
- *
- * @deprecated With the field it answers. `writeNote` answers a visitor with
- * the note's `id` and `createdAt`.
- */
-export interface FoirAnonymousNoteReceipt {
-    /**
-     * A reference for this submission, to quote when following it up.
-     *
-     * NOT a handle: there is no read that takes it. Showing it to the visitor is
-     * the whole of its purpose.
-     */
-    reference: string;
-    /** When the platform recorded the submission. */
-    submittedAt: string;
-}
 export type FoirDeviceType = 'DESKTOP' | 'MOBILE' | 'TABLET';
 export type FoirPlatformType = 'IOS' | 'ANDROID' | 'WEB';
 /**
@@ -694,4 +638,19 @@ export interface FoirResolveContext {
     locale?: string | null;
     platform?: FoirPlatformType | null;
     preview?: boolean | null;
+    /**
+     * The country of the visitor a server is calling for, as an ISO 3166-1
+     * alpha-2 code. Only a key holding `visitors:forward` may say it, and a
+     * client given a `visitor` attaches it to every read, so there is rarely a
+     * reason to write it on one.
+     */
+    country?: string | null;
+    /**
+     * Where the visitor a server is calling for is, in decimal degrees. Only a
+     * key holding `visitors:forward` may say it.
+     */
+    location?: {
+        latitude: number;
+        longitude: number;
+    } | null;
 }

package/dist/data/client.d.ts

@@ -166,7 +166,7 @@ export interface FoirRawOptions {
 }
 export interface FoirClientCore<S extends FoirSchemaDefinition> {
     /**
-     * Non-model root namespaces (`search`, `customers`, `notifications`).
+     * Non-model root namespaces (`search`, `users`, `notifications`).
      * Separate accessor because the addressing has to distinguish a model from a
      * namespace and the client has no runtime schema to disambiguate with.
      */
@@ -181,7 +181,7 @@ export interface FoirClientCore<S extends FoirSchemaDefinition> {
      * hatch that could only say what the JSON op could say would be an escape from
      * nothing. As a document it reaches everything the credential can reach —
      * including the root fields no model or namespace claims (`designTokens`,
-     * `record`, `locales`, `resolvedLocale`, the whole customer-auth mutation
+     * `record`, `locales`, `resolvedLocale`, the whole user-auth mutation
      * set), which the JSON op could not address at all.
      *
      * Returns the whole `data` object rather than a single root field, because a

package/dist/data/decimal.d.ts

@@ -53,7 +53,7 @@
  *
  * TypeScript already rejects `price + tax` at compile time. The throw is for
  * JavaScript callers and for anything that reaches this through `any`, where a
- * silent `"19.992.00"` would otherwise reach a customer. Loud beats quiet: the
+ * silent `"19.992.00"` would otherwise reach a user. Loud beats quiet: the
  * whole reason this type exists is that the float bug was silent.
  *
  * `JSON.stringify` is answered by `toJSON`, so a decimal serialises back to the

package/dist/data/document.d.ts

@@ -51,6 +51,7 @@
  * inferring a literal would reinstate the defect above under a condition no
  * caller can see.
  */
+import { type FoirVisitorPlace } from '../transport/foir-http';
 import type { FoirManifestOp, FoirManifestOpPayload, FoirManifestRelation, FoirManifestSelection, FoirManifestSelectionField, FoirManifestSelectionUnion } from './manifest';
 /**
  * One model, as the printer needs it.
@@ -260,6 +261,19 @@ export declare function planFoirModelCall(source: FoirSelectionSource, call: Foi
  * choose, since only the caller knows which calls are the same one.
  */
 export declare function withCreateIdempotencyKey(source: FoirSelectionSource, model: string, op: string, args: Record<string, unknown>): Record<string, unknown>;
+/**
+ * A read's arguments with where its stated visitor is, when the op takes
+ * `contexts` and the client was given a visitor with a place.
+ *
+ * It is attached here, to every read, and not left to each call: a page
+ * renders with many reads, and one that forgot would be answered as a visitor
+ * nobody could place while the read beside it was not.
+ *
+ * What a call says of the place itself wins, part by part: a caller that
+ * passes `contexts.country` for one read has said something more exact than
+ * the client's visitor.
+ */
+export declare function withStatedVisitor(op: FoirManifestOp | undefined, args: Record<string, unknown>, place: FoirVisitorPlace): Record<string, unknown>;
 /**
  * Turn a namespace call into a document.
  *

package/dist/data/index.d.ts

@@ -59,7 +59,7 @@ export { planFoirModelCall, planFoirNamespaceCall } from './document';
 export type { FoirCall, FoirDocumentPlan, FoirNamespaceCall, FoirNamespaceSelections, FoirRecordPath, FoirSelectionModel, FoirSelectionNamespace, FoirSelections, FoirSelectionSource, FoirSelectionUnions, } from './document';
 export { createFoirSubjectRegistry, recordFoirSubjects } from './subjects';
 export type { FoirSubject, FoirSubjectEntry, FoirSubjectOptions, FoirSubjectOrigin, FoirSubjectRegistry, } from './subjects';
-export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirWriteNoteArgs, FoirSubmitAnonymousNoteArgs, FoirAnonymousNoteReceipt, FoirCustomerNote, FoirCustomerNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirRecordOwner, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
+export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirWriteNoteArgs, FoirUserNote, FoirUserNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirRecordOwner, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
 /**
  * Pre-rename spellings. The `<Name>Block` wrappers and the `<Name>Value`
  * split are the same thing as the types above — an item IS its value — so each
@@ -82,4 +82,4 @@ export type { FoirInclude, FoirModelOperation, FoirNamespaceOperation, FoirOmitt
 export { FoirDecimal, decimal } from './decimal';
 export type { FoirDecimalDivOptions, FoirDecimalInput, FoirDecimalRounding, } from './decimal';
 export { FoirRequestError, FoirAuthDowngradedError, FoirSessionExpiredError, FOIR_VISITOR_IP_HEADER, } from '../transport/foir-http';
-export type { FoirEnv, FoirGraphQLErrorItem, FoirTokenProvider, FoirAuthDowngrade, FoirVisitorSource, } from '../transport/foir-http';
+export type { FoirEnv, FoirGraphQLErrorItem, FoirTokenProvider, FoirAuthDowngrade, FoirVisitor, FoirVisitorSource, } from '../transport/foir-http';

package/dist/data/manifest.d.ts

@@ -303,7 +303,7 @@ export interface FoirManifest {
     composedFor?: string;
     models: Record<string, FoirManifestModel>;
     /**
-     * Keyed by namespace name (`auth`, `customers`, `files`, `notifications`,
+     * Keyed by namespace name (`auth`, `users`, `files`, `notifications`,
      * `operations`, `schedules`, `search`, `secrets`). Deliberately an open
      * record rather than the eight names: a namespace the platform adds must
      * reach the generator, and a closed union would silently drop it.

package/dist/data/schema.d.ts

@@ -272,7 +272,7 @@ export interface FoirModelDefinition {
     readonly ops: Readonly<Record<string, FoirOpDefinition>>;
 }
 /**
- * One op on a non-model namespace (`search`, `customers`, `notifications`).
+ * One op on a non-model namespace (`search`, `users`, `notifications`).
  * Namespaces have no model behind them, so there is no `include`/`omit` and
  * the result type is used verbatim.
  */

package/dist/data/transport.d.ts

@@ -5,12 +5,12 @@
  * Where a call goes
  * ---------------------------------------------------------------------------
  *
- *   read + `pk_` key + no customer bearer + published channel
+ *   read + `pk_` key + no user bearer + published channel
  *     → `GET /cdn/graphql?key=pk_…&extensions={"persistedQuery":{"sha256Hash":…}}`
  *       A shared cache in front of the caller stores the response, because the
  *       request is a GET and the credential is in the URL.
  *
- *   anything else — `sk_`, a customer bearer, a mutation, the draft channel
+ *   anything else — `sk_`, a user bearer, a mutation, the draft channel
  *     → `POST /graphql` with the `x-api-key` header and the APQ body.
  *
  *   a call made AS an operation, with its dispatch token
@@ -158,7 +158,7 @@ export type FoirOperationGeneratedModule<S extends FoirSchemaDefinition = FoirSc
  * The endpoint calls Foir AS the operation, with the grants the operation
  * declared, and holds no key of its own. api-public accepts the token as a
  * caller in its own right: it builds the schema overlay from the token's
- * grants, and it reads the organization and the customer from the
+ * grants, and it reads the organization and the user from the
  * token's claims. So nothing a key client configures beside its key
  * (`bearerToken`, `orgId`, `channel`) means anything here, and none of it is
  * accepted.
@@ -183,7 +183,7 @@ export interface FoirDispatchCredential {
 }
 /**
  * A client that calls Foir with an api key: a storefront's `pk_`, a server's
- * `sk_`, optionally for a signed-in customer.
+ * `sk_`, optionally for a signed-in user.
  */
 export interface FoirKeyClientConfig<S extends FoirSchemaDefinition = FoirSchemaDefinition> {
     /**
@@ -200,19 +200,19 @@ export interface FoirKeyClientConfig<S extends FoirSchemaDefinition = FoirSchema
     dispatch?: never;
     /**
      * Read the draft schema channel (`X-Foir-Schema-Channel: draft`). Needs a key
-     * holding `drafts:read`: a preview environment's own `pk_`, or an `sk_`. A
-     * public key without it is served the published copy; a secret key without
-     * it is refused. Defaults to `'published'`.
+     * holding `drafts:read`: a preview environment's own key. A publishable or
+     * a server key without it is served the published copy. Defaults to
+     * `'published'`.
      */
     channel?: 'published' | 'draft';
     /**
-     * Customer bearer for self-scoped reads (`myProfile`, `myTillyNotes`). A
+     * User bearer for self-scoped reads (`myProfile`, `myTillyNotes`). A
      * function is resolved before every request so a cookie session can be read
      * per-request; a bare string is used as-is.
      */
     bearerToken?: string | FoirTokenProvider;
     /**
-     * Renew the customer bearer when an answer comes back served without it
+     * Renew the user 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.
@@ -247,8 +247,8 @@ export interface FoirKeyClientConfig<S extends FoirSchemaDefinition = FoirSchema
      *
      * A credential already confined to an organization may only name its own
      * (`PERMISSION_DENIED` otherwise), so this cannot steer an organization key
-     * elsewhere. And a request that also carries a customer bearer is refused
-     * unless that customer stands in the named organization. The storefront
+     * elsewhere. And a request that also carries a user bearer is refused
+     * unless that user stands in the named organization. The storefront
      * pattern is still the confined credential, one per organization; this is
      * for the side of the product that holds the project key and has to choose.
      *
@@ -259,21 +259,28 @@ export interface FoirKeyClientConfig<S extends FoirSchemaDefinition = FoirSchema
      */
     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.
+     * The visitor a server rendering pages is calling for, or a function
+     * resolving them for each request: their address, and where they are.
      *
-     * 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.
+     * The address is 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. A string is the
+     * address alone.
      *
-     * 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.
+     * The country and the coordinates are attached to every read, in its
+     * `contexts`, so that location targeting is decided by where the visitor is.
+     * Through a key holding `visitors:forward` the API never uses where the
+     * caller is: a read that says no place is a visitor nobody could place.
+     *
+     * Give it what your host guarantees: the values 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 values for each common host.
+     *
+     * A server key only, and one holding `visitors:forward`: the API refuses the
+     * header, naming the permission, from any other. A client built from a
+     * publishable key is refused `visitor` here, because a browser already calls
+     * as its own visitor and a publishable key cannot hold the permission.
      */
     visitor?: FoirVisitorSource;
     /**
@@ -520,7 +527,7 @@ export interface FoirKeyClientConfig<S extends FoirSchemaDefinition = FoirSchema
 }
 /**
  * The options that belong to a key: the key itself, what it is presented with
- * (a customer bearer, an organization, a channel), and the subscription socket,
+ * (a user bearer, an organization, a channel), and the subscription socket,
  * which only a key can open.
  */
 type FoirKeySideOption = 'apiKey' | 'dispatch' | 'channel' | 'bearerToken' | 'refreshBearer' | 'orgId' | 'orgUrl' | 'visitor' | 'wsUrl' | 'webSocketImpl' | 'reconnect' | 'connectionParams';
@@ -593,7 +600,7 @@ export interface FoirSchemaDrift {
      * way, as paths into the manifest, sorted:
      * `models.order.selection.status`, `models.order.ops.update`,
      * `namespaces.search.ops.searchRecords.args.query`,
-     * `models.order.relations.customer`, `selectionUnions.Block.HeroBlock.title`.
+     * `models.order.relations.user`, `selectionUnions.Block.HeroBlock.title`.
      *
      * `changed` says what moved; this says what BROKE. Empty when the surface
      * only grew, which is the usual drift, and then no typed call is refused.

package/dist/data/ws-transport.d.ts

@@ -43,7 +43,7 @@
  * being replayed after it expired.
  *
  * An operation's dispatch token is not one of them. The server's
- * `connection_init` authenticates a key, an admin token or a customer bearer
+ * `connection_init` authenticates a key, a console token or a user bearer
  * and has no path for a dispatch token, so a client built from one is refused
  * here, by name, rather than opening a socket the server will close as "Not
  * authenticated".