@foir/sdk 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -131,14 +131,65 @@ Changes on `dev` that have not been published to npm.
   release that carries `writeNote`. `foir.ns.notes` answers any field the
   platform serves, so the call itself needs no new SDK.
 
+- **A server says where its visitor is** (`@foir/sdk/data`). `visitor` takes
+  an object as well as an address: `{ address, country, latitude, longitude }`,
+  or a function that yields one for each request. The address is sent as
+  `X-Foir-Visitor-IP`, as before. The country and the coordinates are attached
+  to every read, in its `contexts`, so location targeting is decided by where
+  the visitor is and not by where your server is. Coordinates are sent at two
+  decimal places, and latitude and longitude go together or not at all. The
+  visitor is resolved once for a request, so the header and the read name the
+  same one. A string is still the address alone. New type: `FoirVisitor`, and
+  `country` and `location` on `FoirResolveContext`. It needs a key holding
+  `visitors:forward`, and the platform release that takes `contexts.country`
+  and `contexts.location`: an earlier platform refuses a read that names them.
+
 ### Changed
 
+- **Breaking: an app client refuses an admin key** (`@foir/sdk/data`).
+  `createFoirClient` given a key that begins `foir_adm_` throws before any
+  request. An admin key is a machine's own: nobody signs in through it, and an
+  app never holds one. Build the client from a publishable key, or from a
+  server key on the server that renders your pages. A machine that acts for
+  itself uses `createServerClient` from `@foir/sdk/server`. A key minted
+  before a key had a kind (`sk_`) is not refused here.
+- **A key's kind is read from its prefix in one place.** A key is publishable
+  (`foir_pub_`), server (`foir_srv_`) or admin (`foir_adm_`), and a key minted
+  earlier is `pk_`, `sk_` or `tc_`. Only a publishable key, in either format,
+  is named in a URL and takes the shared cache lane. Earlier versions looked
+  for the letters `pk_` alone, so a `foir_pub_` key was sent to the origin and
+  missed the shared cache.
+- **`visitor` takes a server key** (`@foir/sdk/data`). A client that names the
+  visitor it calls for is built from a server key (`foir_srv_`), or from a
+  secret key minted before a key had a kind. Earlier versions looked for the
+  letters `sk_` alone and refused a server key. A publishable key is still
+  refused `visitor`, in either format.
+- **The events client takes an admin key** (`@foir/sdk/server`).
+  `createEventsClient` refuses a publishable key and a server key by name, and
+  takes an admin key (`foir_adm_`) or a secret key minted earlier.
 - **`FOIR_EVENTS_SCOPE` is `events:read`** (`@foir/sdk/server`). It was
   `events:list.project`, the name the event log's permission had when a key
   was written with scopes. A key is made with the permission catalogue's
   names, where it is `events:read`, and that is what a refusal names. A key
   minted under the older name holds `events:read` and needs no change.
 
+### Removed
+
+- **Breaking: `ScopedTokenClaims` has no `cap`, `rrm` or `rwm`**
+  (`@foir/sdk/server`). The platform no longer writes the claims a token
+  carried before it said its grants. Read `grants`, or `recordsReadModels`,
+  `recordsWriteModels` and `recordsCreateModels`.
+- **Breaking: `PlacementGrant` has no `grantedScopes` or `withheld`**
+  (`@foir/sdk/placement`). A console sends what a page's token carries as
+  `grants` and what it was refused as `withheldGrants`, and no longer sends
+  the same two lists under their older names. Read `session.grant.grants`, or
+  ask `session.can`.
+- **Breaking: `verifyScopedToken` refuses a token that does not say its
+  grants** (`@foir/sdk/server`), with `the token says no grants`, as the
+  platform refuses it. It used to read such a token as what its older claims
+  were worth. `requireScopedToken` answers it 401 like any token that does not
+  verify.
+
 ### Deprecated
 
 - **`FoirCreateMyNoteArgs`, `FoirSubmitAnonymousNoteArgs` and

package/dist/auth.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";
 
@@ -125,6 +149,28 @@ function refuseCredentialHeaders(extra) {
   }
 }
 var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
+function sentCoordinate(value) {
+  return Math.round(value * 100) / 100;
+}
+async function resolveFoirVisitor(source) {
+  const value = typeof source === "function" ? await source() : source;
+  if (value === null || value === void 0) return { place: {} };
+  if (typeof value === "string") {
+    const address2 = value.trim();
+    return { address: address2 || void 0, place: {} };
+  }
+  const address = value.address?.trim();
+  const country = value.country?.trim();
+  const place = {};
+  if (country) place.country = country;
+  if (Number.isFinite(value.latitude) && Number.isFinite(value.longitude)) {
+    place.location = {
+      latitude: sentCoordinate(value.latitude),
+      longitude: sentCoordinate(value.longitude)
+    };
+  }
+  return { address: address || void 0, place };
+}
 function buildFoirHeaders(input) {
   const headers = {
     "Content-Type": "application/json"
@@ -277,7 +323,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);
 }
 
@@ -290,6 +336,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),
@@ -852,10 +901,7 @@ 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;
+  return (await resolveFoirVisitor(config.visitor)).address;
 }
 async function resolveBearerToken(config) {
   const source = config.bearerToken;
@@ -896,7 +942,7 @@ async function resolveFoirAuth(config) {
   };
 }
 function foirRoute(input) {
-  if (!input.apiKey.startsWith("pk_")) return { lane: "origin", reason: "key" };
+  if (!isPublishableFoirKey(input.apiKey)) return { lane: "origin", reason: "key" };
   if (input.bearerToken) return { lane: "origin", reason: "bearer" };
   if (input.orgId || input.orgUrl) return { lane: "origin", reason: "org" };
   if (input.mutation) return { lane: "origin", reason: "operation" };
@@ -1362,10 +1408,10 @@ async function requireAdmin(adapter, options) {
 
 // src/auth/grant-table.generated.ts
 var GRANT_TABLE = [
-  ["records:read", true, ["own", "named", "all"], []],
+  ["records:read", true, ["own", "all"], []],
   ["records:create", true, [], []],
-  ["records:write", true, ["own", "named", "all"], []],
-  ["records:delete", true, ["own", "named", "all"], []],
+  ["records:write", true, ["own", "all"], []],
+  ["records:delete", true, ["own", "all"], []],
   ["records:publish", true, ["own", "all"], []],
   ["records:attribute", true, [], []],
   ["search:read", true, [], []],
@@ -1381,8 +1427,8 @@ var GRANT_TABLE = [
   ["notifications:consent", false, [], []],
   ["pushcredentials:read", false, [], []],
   ["pushcredentials:write", false, [], []],
-  ["notes:read", false, [], []],
-  ["notes:write", false, [], []],
+  ["notes:read", false, ["own", "all"], []],
+  ["notes:write", false, ["own", "all"], []],
   ["notes:create", false, [], []],
   ["approvals:read", false, [], []],
   ["approvals:write", false, [], []],
@@ -1439,7 +1485,7 @@ var GRANT_TABLE = [
   ["roles:write", false, [], []],
   ["projects:read", false, [], []],
   ["projects:write", false, [], []],
-  ["project:manage", false, [], ["records:read.all", "records:create", "records:write.all", "records:delete.all", "records:publish.all", "records:attribute", "search:read", "embeddings:read", "embeddings:write", "schemas:read", "drafts:read", "files:read.all", "files:write.all", "files:delete.all", "users:read.all", "identities:read", "users:create", "identities:delete", "users:write.all", "users:delete.all", "notifications:read.all", "notifications:write.all", "notifications:consent", "pushcredentials:read", "pushcredentials:write", "notes:read", "notes:write", "notes:create", "approvals:read", "approvals:write", "rooms:read", "rooms:write", "presence:read", "operations:read", "operations:execute", "operations:write", "appconfig:read", "schedules:read", "schedules:write", "hooks:read", "hooks:write", "auth:login_with_foir", "relyingparties:read", "relyingparties:write", "domains:read", "domains:write", "secrets:read", "secrets:list", "secrets:put", "secrets:delete", "appsecrets:read", "appsecrets:list", "appsecrets:put", "appsecrets:delete", "usersecrets:read", "usersecrets:list", "usersecrets:put", "usersecrets:delete", "opsecrets:read", "opsecrets:write", "settings:read", "settings:write", "designtokens:read", "designtokens:write", "models:read", "models:write", "configs:read", "configs:write", "signinproviders:read", "signinproviders:write", "apps:read", "apps:write", "events:read", "targeting:debug", "visitors:forward", "apikeys:read", "apikeys:write", "organizations:read", "organizations:create", "organizations:delete", "organizations:write", "organizations:reach", "members:read", "members:write", "roles:read", "roles:write", "projects:read", "projects:write"]],
+  ["project:manage", false, [], ["records:read.all", "records:create", "records:write.all", "records:delete.all", "records:publish.all", "records:attribute", "search:read", "embeddings:read", "embeddings:write", "schemas:read", "drafts:read", "files:read.all", "files:write.all", "files:delete.all", "users:read.all", "identities:read", "users:create", "identities:delete", "users:write.all", "users:delete.all", "notifications:read.all", "notifications:write.all", "notifications:consent", "pushcredentials:read", "pushcredentials:write", "notes:read.all", "notes:write.all", "notes:create", "approvals:read", "approvals:write", "rooms:read", "rooms:write", "presence:read", "operations:read", "operations:execute", "operations:write", "appconfig:read", "schedules:read", "schedules:write", "hooks:read", "hooks:write", "auth:login_with_foir", "relyingparties:read", "relyingparties:write", "domains:read", "domains:write", "secrets:read", "secrets:list", "secrets:put", "secrets:delete", "appsecrets:read", "appsecrets:list", "appsecrets:put", "appsecrets:delete", "usersecrets:read", "usersecrets:list", "usersecrets:put", "usersecrets:delete", "opsecrets:read", "opsecrets:write", "settings:read", "settings:write", "designtokens:read", "designtokens:write", "models:read", "models:write", "configs:read", "configs:write", "signinproviders:read", "signinproviders:write", "apps:read", "apps:write", "events:read", "targeting:debug", "visitors:forward", "apikeys:read", "apikeys:write", "organizations:read", "organizations:create", "organizations:delete", "organizations:write", "organizations:reach", "members:read", "members:write", "roles:read", "roles:write", "projects:read", "projects:write", "audit:read"]],
   ["projects:create", false, [], []],
   ["projects:delete", false, [], []],
   ["tenants:read", false, [], []],
@@ -1455,7 +1501,7 @@ var GRANT_TABLE = [
   ["tenanthooks:read", false, [], []],
   ["tenanthooks:write", false, [], []],
   ["apps:install", false, [], []],
-  ["tenant:manage", false, [], ["project:manage", "projects:create", "projects:delete", "tenants:read", "tenants:write", "tenants:delete", "audit:read", "export:run", "billing:read", "billing:manage", "usage:read", "controlkeys:read", "controlkeys:write", "tenanthooks:read", "tenanthooks:write", "apps:install"]],
+  ["tenant:manage", false, [], ["project:manage", "projects:create", "projects:delete", "tenants:read", "tenants:write", "tenants:delete", "export:run", "billing:read", "billing:manage", "usage:read", "controlkeys:read", "controlkeys:write", "tenanthooks:read", "tenanthooks:write", "apps:install"]],
   ["platform:read", false, [], []],
   ["platform:manage", false, [], ["tenant:manage", "platform:read", "platform:create_workspace", "users:setup"]],
   ["platform:create_workspace", false, [], []],

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";
 
@@ -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

@@ -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/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, 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';
 /**
  * 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/transport.d.ts

@@ -200,9 +200,9 @@ 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';
     /**
@@ -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.
-     *
-     * 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.
+     * The visitor a server rendering pages is calling for, or a function
+     * resolving them for each request: their address, and where they are.
+     *
+     * 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.
+     *
+     * 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;
     /**

package/dist/data.js

@@ -98,6 +98,28 @@ function refuseCredentialHeaders(extra) {
   }
 }
 var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
+function sentCoordinate(value) {
+  return Math.round(value * 100) / 100;
+}
+async function resolveFoirVisitor(source) {
+  const value = typeof source === "function" ? await source() : source;
+  if (value === null || value === void 0) return { place: {} };
+  if (typeof value === "string") {
+    const address2 = value.trim();
+    return { address: address2 || void 0, place: {} };
+  }
+  const address = value.address?.trim();
+  const country = value.country?.trim();
+  const place = {};
+  if (country) place.country = country;
+  if (Number.isFinite(value.latitude) && Number.isFinite(value.longitude)) {
+    place.location = {
+      latitude: sentCoordinate(value.latitude),
+      longitude: sentCoordinate(value.longitude)
+    };
+  }
+  return { address: address || void 0, place };
+}
 function buildFoirHeaders(input) {
   const headers = {
     "Content-Type": "application/json"
@@ -214,6 +236,30 @@ function readFoirEnvelope(json, options) {
   return json.data;
 }
 
+// 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/transport/persisted-query.ts
 var FOIR_CDN_GRAPHQL_PATH = "/cdn/graphql";
 function persistedQueryExtension(hash) {
@@ -257,10 +303,7 @@ 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;
+  return (await resolveFoirVisitor(config.visitor)).address;
 }
 async function resolveBearerToken(config) {
   const source = config.bearerToken;
@@ -309,9 +352,13 @@ 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_")) {
+    const kind = foirKeyKind(loose.apiKey);
+    if (kind === "admin") {
+      throw new FoirRequestError(adminKeyRefusal("createFoirClient"));
+    }
+    if (loose.visitor !== void 0 && kind !== "server" && kind !== "older") {
       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."
+        `[foir] createFoirClient: \`visitor\` names the visitor a server calls for, and only a server key holding visitors:forward may send it. A publishable key already calls as its visitor, and cannot hold the permission. Drop \`visitor\`, or build this client from your server key on the server that renders your pages. See ${FOIR_CREDENTIALS_DOC}`
       );
     }
     if (operation !== void 0) {
@@ -373,7 +420,7 @@ function contextOperation(context) {
   return void 0;
 }
 function foirRoute(input) {
-  if (!input.apiKey.startsWith("pk_")) return { lane: "origin", reason: "key" };
+  if (!isPublishableFoirKey(input.apiKey)) return { lane: "origin", reason: "key" };
   if (input.bearerToken) return { lane: "origin", reason: "bearer" };
   if (input.orgId || input.orgUrl) return { lane: "origin", reason: "org" };
   if (input.mutation) return { lane: "origin", reason: "operation" };
@@ -894,13 +941,19 @@ function planFoirModelCall(source, call) {
   }
   return planCall(source, opDef, `${call.model}.${call.op}`, operationName(model.typeName, call.op), call);
 }
-var CREATING_OPS = /* @__PURE__ */ new Set(["create", "submit"]);
+var CREATING_OPS = /* @__PURE__ */ new Set(["create"]);
 function withCreateIdempotencyKey(source, model, op, args) {
   if (!CREATING_OPS.has(op) || args.idempotencyKey !== void 0) return args;
   const argTypes = source.models[model]?.ops?.[op]?.argTypes;
   if (!argTypes || !("idempotencyKey" in argTypes)) return args;
   return { ...args, idempotencyKey: globalThis.crypto.randomUUID() };
 }
+function withStatedVisitor(op, args, place) {
+  if (place.country === void 0 && place.location === void 0) return args;
+  if (!op?.argTypes || !("contexts" in op.argTypes)) return args;
+  const said = args.contexts ?? {};
+  return { ...args, contexts: { ...place, ...said } };
+}
 function planFoirNamespaceCall(source, call) {
   const namespace = source.namespaces?.[call.namespace];
   if (!namespace) {
@@ -2260,20 +2313,43 @@ function createFoirClient(clientConfig) {
       detectedDrift
     );
   };
+  const visitorOfThisRequest = async () => {
+    if (config.dispatch !== void 0 || config.visitor === void 0) {
+      return { config, place: {} };
+    }
+    const { address, place } = await resolveFoirVisitor(config.visitor);
+    return {
+      config: {
+        ...config,
+        visitor: {
+          address,
+          country: place.country,
+          latitude: place.location?.latitude,
+          longitude: place.location?.longitude
+        }
+      },
+      place
+    };
+  };
   const runModel = async (model, op, query) => {
     assertStillServed(`${model}.${op}`, (served) => served.modelCall(model, op, query?.include));
     const { args, include, omit, pick, depth } = splitQuery(query);
     const source = await selectionSource();
+    const visitor = await visitorOfThisRequest();
     const plan = planFoirModelCall(source, {
       model,
       op,
-      args: withCreateIdempotencyKey(source, model, op, args),
+      args: withStatedVisitor(
+        source.models[model]?.ops?.[op],
+        withCreateIdempotencyKey(source, model, op, args),
+        visitor.place
+      ),
       include,
       omit,
       pick,
       depth
     });
-    const result = await executeFoirDocument(config, plan);
+    const result = await executeFoirDocument(visitor.config, plan);
     recordFoirSubjects(config.subjects, plan, result);
     maybeCheckDrift();
     return result;
@@ -2284,16 +2360,18 @@ function createFoirClient(clientConfig) {
       (served) => served.namespaceCall(namespace, op, query?.include)
     );
     const { args, include, omit, pick, depth } = splitQuery(query);
-    const plan = planFoirNamespaceCall(await selectionSource(), {
+    const source = await selectionSource();
+    const visitor = await visitorOfThisRequest();
+    const plan = planFoirNamespaceCall(source, {
       namespace,
       op,
-      args,
+      args: withStatedVisitor(source.namespaces?.[namespace]?.ops?.[op], args, visitor.place),
       include,
       omit,
       pick,
       depth
     });
-    const result = await executeFoirDocument(config, plan);
+    const result = await executeFoirDocument(visitor.config, plan);
     recordFoirSubjects(config.subjects, plan, result);
     maybeCheckDrift();
     return result;