@foir/sdk 0.19.0 → 0.21.0

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, 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

@@ -155,10 +155,10 @@ export type FoirOperationGeneratedModule<S extends FoirSchemaDefinition = FoirSc
  * const foir = createFoirClient({ apiUrl, dispatch, generated });
  * ```
  *
- * The endpoint calls Foir AS the operation, with the capabilities the operation
+ * 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
- * capabilities, and it reads the organization and the customer from the
+ * grants, and it reads the organization and the customer 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.
@@ -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;

package/dist/index.js

@@ -94,6 +94,27 @@ function isValidHostMessage(data) {
   return true;
 }
 
+// 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}`;
+}
+
 // src/client/platform-client.ts
 var PlatformClientError = class extends Error {
   constructor(message, status, response) {
@@ -107,6 +128,9 @@ var PlatformClientError = class extends Error {
 };
 function createPlatformClient(options) {
   const { apiUrl, apiKey } = options;
+  if (foirKeyKind(apiKey) === "admin") {
+    throw new PlatformClientError(adminKeyRefusal("createPlatformClient"));
+  }
   return {
     async query(query, variables) {
       const res = await fetch(apiUrl, {

package/dist/next.js

@@ -20,6 +20,26 @@ function createFoirCookieAdapter(store, opts = {}) {
 // 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"]
+];
+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 isPublishableFoirKey(apiKey) {
+  return foirKeyKind(apiKey) === "publishable";
+}
+
 // src/graphql/cdn-route.ts
 import { print } from "graphql";
 
@@ -123,6 +143,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"
@@ -739,10 +781,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;
@@ -783,7 +822,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" };
@@ -921,6 +960,9 @@ var AUTH_OPS = {
   // Post-credential self reads.
   currentUser: "currentUser",
   myProviderToken: "myProviderToken",
+  // What the calling credential may do, and for a signed-in customer the roles
+  // they hold. `./access` reads it.
+  whoami: "whoami",
   // Methods.
   customerLogin: "customerLogin",
   customerRegister: "customerRegister",

package/dist/placement/index.d.ts

@@ -5,8 +5,9 @@
  * reaches a cross-site frame, so the console hands the page a short-lived token
  * instead, by message, to your placement's origin only. The token is the
  * operator looking at the page, acting through your app at the level your app
- * is installed at, carrying the scopes your placement declares that this
- * operator holds. Your page runs no login of its own.
+ * is installed at, carrying what your placement declares and this operator
+ * holds, as grants in the permission catalogue's names. Your page runs no
+ * login of its own.
  *
  * ```ts
  * import { connectPlacement, FOIR_CONSOLE_ORIGINS } from '@foir/sdk/placement';
@@ -15,7 +16,7 @@
  *   apiUrl: 'https://api.foir.dev',
  *   consoleOrigins: FOIR_CONSOLE_ORIGINS.production,
  * });
- * if (session.can('records:write:preorder')) showEditButtons();
+ * if (session.can('records:write.all:preorder')) showEditButtons();
  * const data = await session.request('{ preorders { items { id } } }');
  * ```
  *
@@ -52,14 +53,21 @@ export interface PlacementGrant {
     expiresAt: string;
     /** The organisation the page acts at: your app's install. Empty for the project. */
     orgId: string;
-    /** What the token carries. */
-    grantedScopes: string[];
-    /** What your placement declares that this operator does not hold, and why. */
-    withheld: {
-        scope: string;
+    /**
+     * What the token carries: the grants your placement declares that this
+     * operator holds, in the permission catalogue's names. A grant the operator
+     * holds part of is carried as that part, so ask with `can` and not by
+     * looking for a spelling here.
+     */
+    grants: string[];
+    /** Each grant your placement declares that the token does not carry whole, and why. */
+    withheldGrants: {
+        grant: string;
         reason: string;
     }[];
 }
+/** What a console sends with a token. A list it does not send is an empty one. */
+type PlacementGrantMessage = Pick<PlacementGrant, 'accessToken' | 'expiresAt' | 'orgId'> & Partial<Pick<PlacementGrant, 'grants' | 'withheldGrants'>>;
 /** How the console looks, for an embedded page to match. */
 export interface PlacementAppearance {
     /**
@@ -71,7 +79,7 @@ export interface PlacementAppearance {
 /** A message the console sends an embedded page. */
 export type PlacementHostMessage = {
     type: typeof PLACEMENT_MESSAGE.token;
-    grant: PlacementGrant;
+    grant: PlacementGrantMessage;
 } | {
     type: typeof PLACEMENT_MESSAGE.refused;
     reason: string;
@@ -138,8 +146,14 @@ export interface PlacementSession {
      * older than this). Kept current as the operator changes it.
      */
     readonly appearance: PlacementAppearance | null;
-    /** Whether the token carries this scope, to hide or grey out what the operator cannot do. */
-    can(scope: string): boolean;
+    /**
+     * Whether the token covers this grant, to hide or grey out what the operator
+     * cannot do. It answers as Foir's API would: a grant for every model covers
+     * the same grant for one, and one for every owner's rows covers a person's
+     * own. `can('records:read.all:order')` is true for a token that carries
+     * `records:read.all`.
+     */
+    can(grant: string): boolean;
     /** A GraphQL request to Foir's API as the operator, through your app. */
     request<TResult = unknown>(document: string | {
         toString(): string;
@@ -156,3 +170,4 @@ export interface PlacementSession {
  * console gives no token, or when none arrives in time.
  */
 export declare function connectPlacement(options: ConnectPlacementOptions): Promise<PlacementSession>;
+export {};