@foir/sdk 0.19.0 → 0.21.0

package/dist/auth/ops.d.ts

@@ -44,6 +44,7 @@ export declare const AUTH_OPS: {
     readonly customerSignupContext: "customerSignupContext";
     readonly currentUser: "currentUser";
     readonly myProviderToken: "myProviderToken";
+    readonly whoami: "whoami";
     readonly customerLogin: "customerLogin";
     readonly customerRegister: "customerRegister";
     readonly customerRequestOTP: "customerRequestOTP";

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),
@@ -679,7 +728,7 @@ function toVariableValue(value, label) {
     return value.toISOString();
   }
   if (Array.isArray(value)) {
-    return value.filter((item) => item !== void 0).map((item, index) => toVariableValue(item, `${label}[${index}]`));
+    return value.filter((item) => item !== void 0).map((item, index2) => toVariableValue(item, `${label}[${index2}]`));
   }
   if (kind === "object") {
     const out = {};
@@ -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" };
@@ -1034,6 +1080,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",
@@ -1357,6 +1406,264 @@ async function requireAdmin(adapter, options) {
   return user;
 }
 
+// src/auth/grant-table.generated.ts
+var GRANT_TABLE = [
+  ["records:read", true, ["own", "all"], []],
+  ["records:create", true, [], []],
+  ["records:write", true, ["own", "all"], []],
+  ["records:delete", true, ["own", "all"], []],
+  ["records:publish", true, ["own", "all"], []],
+  ["records:attribute", true, [], []],
+  ["search:read", true, [], []],
+  ["embeddings:read", false, [], []],
+  ["embeddings:write", false, [], []],
+  ["schemas:read", false, [], []],
+  ["drafts:read", false, [], []],
+  ["files:read", false, ["own", "all"], []],
+  ["files:write", false, ["own", "all"], []],
+  ["files:delete", false, ["own", "all"], []],
+  ["notifications:read", false, ["own", "all"], []],
+  ["notifications:write", false, ["own", "named", "all"], []],
+  ["notifications:consent", false, [], []],
+  ["pushcredentials:read", false, [], []],
+  ["pushcredentials:write", false, [], []],
+  ["notes:read", false, ["own", "all"], []],
+  ["notes:write", false, ["own", "all"], []],
+  ["notes:create", false, [], []],
+  ["approvals:read", false, [], []],
+  ["approvals:write", false, [], []],
+  ["rooms:read", true, [], []],
+  ["rooms:write", true, [], []],
+  ["presence:read", true, [], []],
+  ["operations:read", false, [], []],
+  ["operations:execute", true, [], []],
+  ["operations:write", false, [], []],
+  ["operations:complete", false, [], []],
+  ["status:write", false, [], []],
+  ["appconfig:read", false, [], []],
+  ["schedules:read", false, [], []],
+  ["schedules:write", false, [], []],
+  ["hooks:read", false, [], []],
+  ["hooks:write", false, [], []],
+  ["relyingparties:read", false, [], []],
+  ["relyingparties:write", false, [], []],
+  ["domains:read", false, [], []],
+  ["domains:write", false, [], []],
+  ["secrets:read", false, [], []],
+  ["secrets:list", false, [], []],
+  ["secrets:put", false, [], []],
+  ["secrets:delete", false, [], []],
+  ["appsecrets:read", false, [], []],
+  ["appsecrets:list", false, [], []],
+  ["appsecrets:put", false, [], []],
+  ["appsecrets:delete", false, [], []],
+  ["opsecrets:read", false, [], []],
+  ["opsecrets:write", false, [], []],
+  ["settings:read", false, [], []],
+  ["settings:write", false, [], []],
+  ["designtokens:read", false, [], []],
+  ["designtokens:write", false, [], []],
+  ["models:read", false, [], []],
+  ["models:write", false, [], []],
+  ["configs:read", false, [], []],
+  ["configs:write", false, [], []],
+  ["apps:read", false, [], []],
+  ["apps:write", false, [], []],
+  ["events:read", false, [], []],
+  ["targeting:debug", false, [], []],
+  ["visitors:forward", false, [], []],
+  ["apikeys:read", false, [], []],
+  ["apikeys:write", false, [], []],
+  ["organizations:read", false, [], []],
+  ["organizations:write", false, [], []],
+  ["organizations:create", false, [], []],
+  ["organizations:delete", false, [], []],
+  ["organizations:reach", false, [], []],
+  ["members:read", false, [], []],
+  ["members:write", false, [], []],
+  ["roles:read", false, [], []],
+  ["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.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, [], []],
+  ["tenants:write", false, [], []],
+  ["tenants:delete", false, [], []],
+  ["audit:read", false, [], []],
+  ["export:run", false, [], []],
+  ["billing:read", false, [], []],
+  ["billing:manage", false, [], []],
+  ["usage:read", false, [], []],
+  ["controlkeys:read", false, [], []],
+  ["controlkeys:write", false, [], []],
+  ["tenanthooks:read", false, [], []],
+  ["tenanthooks:write", false, [], []],
+  ["apps:install", false, [], []],
+  ["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, [], []],
+  ["users:read", false, ["own", "named", "all"], []],
+  ["users:write", false, ["own", "all"], []],
+  ["users:setup", false, [], []],
+  ["users:delete", false, ["own", "all"], []],
+  ["users:create", false, [], []],
+  ["identities:read", false, [], []],
+  ["identities:delete", false, [], []],
+  ["usersecrets:read", false, [], []],
+  ["usersecrets:list", false, [], []],
+  ["usersecrets:put", false, [], []],
+  ["usersecrets:delete", false, [], []],
+  ["auth:login_with_foir", false, [], []],
+  ["signinproviders:read", false, [], []],
+  ["signinproviders:write", false, [], []]
+];
+
+// src/auth/grants.ts
+var WILDCARD = "*";
+var RESOURCE_WILDCARD = ":*";
+var index;
+function catalogue() {
+  if (!index) {
+    const byName = new Map(GRANT_TABLE.map((row) => [row[0], row]));
+    const longestFirst = [...byName.keys()].sort(
+      (a, b) => a.length !== b.length ? b.length - a.length : a < b ? -1 : 1
+    );
+    index = { byName, longestFirst };
+  }
+  return index;
+}
+var reachRank = { own: 1, named: 2, all: 3 };
+function hasReach(permission, reach) {
+  const reaches = permission[2];
+  return reaches.length === 0 ? reach === "own" : reaches.includes(reach);
+}
+function resourceOf(name) {
+  const i = name.indexOf(":");
+  return i < 0 ? name : name.slice(0, i);
+}
+function parseGrant(s) {
+  const { byName, longestFirst } = catalogue();
+  for (const name of longestFirst) {
+    if (!s.startsWith(name)) continue;
+    let rest = s.slice(name.length);
+    if (rest !== "" && rest[0] !== "." && rest[0] !== ":") continue;
+    const permission = byName.get(name);
+    let reach = "own";
+    if (rest.startsWith(".")) {
+      const after = rest.slice(1);
+      const colon = after.indexOf(":");
+      const word = colon < 0 ? after : after.slice(0, colon);
+      if (word !== "named" && word !== "all") return null;
+      if (!hasReach(permission, word)) return null;
+      reach = word;
+      rest = after.slice(word.length);
+    }
+    let target = "";
+    if (rest.startsWith(":")) {
+      target = rest.slice(1);
+      if (!permission[1]) return null;
+      if (target === "" || /[: \t\n*]/.test(target)) return null;
+    }
+    return { permission, reach, target };
+  }
+  return null;
+}
+function covers(held, required) {
+  return held.permission === required.permission && reachRank[held.reach] >= reachRank[required.reach] && (held.target === "" || held.target === required.target);
+}
+function resourceWildcard(held) {
+  if (!held.endsWith(RESOURCE_WILDCARD)) return null;
+  const resource = held.slice(0, -RESOURCE_WILDCARD.length);
+  return resource.includes(":") ? null : resource;
+}
+function holdsAt(held, required, depth) {
+  for (const h of held) {
+    if (h === WILDCARD) return true;
+    const resource = resourceWildcard(h);
+    if (resource !== null) {
+      if (resource === resourceOf(required.permission[0])) return true;
+      continue;
+    }
+    const grant = parseGrant(h);
+    if (grant === null) continue;
+    if (covers(grant, required)) return true;
+    const implies = grant.permission[3];
+    if (depth < 4 && implies.length > 0 && holdsAt(implies, required, depth + 1)) return true;
+  }
+  return false;
+}
+function holds(held, required) {
+  const grant = parseGrant(required);
+  return grant !== null && holdsAt(held, grant, 0);
+}
+
+// src/auth/access.ts
+function accessFrom(who) {
+  const customer = who?.credential?.customer;
+  if (!customer?.id) return null;
+  return {
+    customerId: customer.id,
+    roles: Array.isArray(customer.roles) ? [...customer.roles] : null,
+    scopes: [...who?.authority?.effective ?? []]
+  };
+}
+async function customerAccess(env, options) {
+  return accessFrom(await authOp(env, AUTH_OPS.whoami, void 0, options));
+}
+async function getSessionAccess(adapter, env) {
+  if (!await getSessionToken(adapter)) return null;
+  return accessFrom(await authedOp(adapter, env, AUTH_OPS.whoami));
+}
+function hasRole(access, key) {
+  return access?.roles?.includes(key) ?? false;
+}
+function hasScope(access, scope) {
+  return access ? holds(access.scopes, scope) : false;
+}
+var FoirAccessDeniedError = class extends Error {
+  code = "FOIR_ACCESS_DENIED";
+  reason;
+  /** The role that was required, when one was. */
+  role;
+  /** The scope that was required, when one was. */
+  scope;
+  constructor(reason, required) {
+    super(denialMessage(reason, required));
+    this.name = "FoirAccessDeniedError";
+    this.reason = reason;
+    this.role = required.role;
+    this.scope = required.scope;
+  }
+};
+function denialMessage(reason, required) {
+  switch (reason) {
+    case "signed_out":
+      return "[foir] nobody is signed in";
+    case "role_not_held":
+      return `[foir] the signed-in customer does not hold the role "${required.role}"`;
+    case "roles_unknown":
+      return `[foir] the platform did not say which roles the signed-in customer holds, so "${required.role}" could not be checked`;
+    case "scope_not_held":
+      return `[foir] the signed-in customer's scopes do not cover "${required.scope}"`;
+  }
+}
+async function requireRole(adapter, env, key) {
+  const access = await getSessionAccess(adapter, env);
+  if (!access) throw new FoirAccessDeniedError("signed_out", { role: key });
+  if (access.roles === null) throw new FoirAccessDeniedError("roles_unknown", { role: key });
+  if (!access.roles.includes(key)) throw new FoirAccessDeniedError("role_not_held", { role: key });
+  return access;
+}
+async function requireScope(adapter, env, scope) {
+  const access = await getSessionAccess(adapter, env);
+  if (!access) throw new FoirAccessDeniedError("signed_out", { scope });
+  if (!holds(access.scopes, scope)) throw new FoirAccessDeniedError("scope_not_held", { scope });
+  return access;
+}
+
 // src/auth/hosted.ts
 var DEFAULT_COOKIE_NAME = "foir_customer_session";
 var DEFAULT_SESSION_PATH = "/session/token";
@@ -1567,6 +1874,7 @@ function trimSlash(s) {
 }
 export {
   AUTH_OPS,
+  FoirAccessDeniedError,
   FoirAuthDowngradedError,
   FoirSessionExpiredError,
   authedOp,
@@ -1574,6 +1882,7 @@ export {
   clearSession,
   createFoirSessionClient,
   currentUser,
+  customerAccess,
   customerJoinWaitlist,
   customerLogin,
   customerLoginOTP,
@@ -1594,8 +1903,11 @@ export {
   getAuthConfig,
   getAuthProviders,
   getDefaultAuthProvider,
+  getSessionAccess,
   getSessionCustomer,
   getSessionToken,
+  hasRole,
+  hasScope,
   hostedLoginUrl,
   hostedLogoutUrl,
   loginWithOTP,
@@ -1608,6 +1920,8 @@ export {
   registerWithPassword,
   requireAdmin,
   requireAuth,
+  requireRole,
+  requireScope,
   resetPasswordAndSignIn,
   saveSession,
   selectOrganization,

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

@@ -520,7 +520,7 @@ export interface FoirCustomerNote {
  * What a note surface has to know about the project before it renders anything
  * — `foir.ns.notes.noteConfig`.
  *
- * Charged `notes:write` rather than `notes:read`, and refused to a caller with
+ * 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
  * 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.
@@ -551,18 +551,31 @@ export interface FoirMyNotesArgs {
  * internal ones.
  */
 export type FoirMyNotesResult = FoirConnection<FoirCustomerNote>;
-/** `createMyNote` arguments. */
-export interface FoirCreateMyNoteArgs {
+/**
+ * `writeNote` arguments: the one note create, for a signed-in customer 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
+ * 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.
+ *
+ * Served by a data API that has the field. `<FoirFeedback>` still writes
+ * through `createMyNote`, the same create under its older name, which every
+ * data API serves.
+ */
+export interface FoirWriteNoteArgs {
+    /** A visitor may write about a record and nothing else. */
     subjectType: FoirNoteSubjectType;
     subjectId: string;
     /** Required when `subjectType` is `'record'`, refused otherwise. */
     subjectModelKey?: string;
     body: string;
-    /** Reply within an existing thread. */
+    /** Reply within an existing thread. Refused where nobody is signed in. */
     parentNoteId?: string;
     /**
      * Files to submit with this note, already uploaded through
-     * `createFileUpload` / `confirmFileUpload`.
+     * `createFileUpload` / `confirmFileUpload`. Refused where nobody is signed in.
      *
      * A file this caller cannot read is REFUSED and the note is not written. That
      * is not a rough edge to code around: a create that accepted the note and
@@ -570,53 +583,40 @@ export interface FoirCreateMyNoteArgs {
      * screenshot nobody has.
      */
     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.
- */
-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.
+     * Where the operators may reply to a visitor. Refused from a signed-in
+     * customer, whose note has an author.
      *
-     * Captured as typed and NEVER verified — it is not treated as proof of who
+     * 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. */
-export interface FoirAnonymousNoteReceipt {
+/**
+ * `createMyNote` arguments.
+ *
+ * @deprecated `createMyNote` is the older name of `writeNote` for a signed-in
+ * customer. Use `writeNote` and {@link FoirWriteNoteArgs}.
+ */
+export interface FoirCreateMyNoteArgs {
+    subjectType: FoirNoteSubjectType;
+    subjectId: string;
+    /** Required when `subjectType` is `'record'`, refused otherwise. */
+    subjectModelKey?: string;
+    body: string;
+    /** Reply within an existing thread. */
+    parentNoteId?: string;
     /**
-     * A reference for this submission, to quote when following it up.
+     * Files to submit with this note, already uploaded through
+     * `createFileUpload` / `confirmFileUpload`.
      *
-     * NOT a handle: there is no read that takes it. Showing it to the visitor is
-     * the whole of its purpose.
+     * A file this caller cannot read is REFUSED and the note is not written. That
+     * is not a rough edge to code around: a create that accepted the note and
+     * dropped the attachment would leave the author believing they sent a
+     * screenshot nobody has.
      */
-    reference: string;
-    /** When the platform recorded the submission. */
-    submittedAt: string;
+    attachmentFileIds?: string[];
 }
 export type FoirDeviceType = 'DESKTOP' | 'MOBILE' | 'TABLET';
 export type FoirPlatformType = 'IOS' | 'ANDROID' | 'WEB';
@@ -638,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.
  *