@foir/sdk 0.20.0 → 0.22.0

package/dist/server/events-client.d.ts

@@ -18,12 +18,12 @@
  * ```
  *
  * ---------------------------------------------------------------------------
- * OPERATOR SURFACE. This is not a customer-facing capability.
+ * PROJECT SURFACE. Your app's users do not reach it.
  * ---------------------------------------------------------------------------
  *
  * DECIDED 2026-08-04. The event log is reachable by an `sk_` api key
- * and by an admin session. It is NOT reachable by a customer token, there is no
- * customer lane for it on api-public, and a `pk_` key can never be minted
+ * and by a console session. It is NOT reachable by a user token, there is no
+ * user lane for it on api-public, and a `pk_` key can never be minted
  * holding `events:read` at all.
  *
  * The reason is a predicate asymmetry rather than a policy preference.
@@ -31,7 +31,7 @@
  * owner, admin_owner, access_mode, grantee, comp_parent, read_borrow and
  * slice_parent terms on top of it. A containment-only read over the log
  * therefore describes rows whose underlying records the same caller could not
- * read — and every row carries `actor`, naming which OTHER customer acted. In a
+ * read — and every row carries `actor`, naming which OTHER user acted. In a
  * project with owner confinement that is a per-record activity feed of other
  * people's actions.
  *
@@ -51,13 +51,13 @@
  *      built the client.
  *
  *   3. **There is no `bearerToken` option, and an `Authorization` header is
- *      refused.** On api-public a request presenting `sk_` plus a customer
- *      bearer resolves the CUSTOMER as the authority, and `events` is stripped
- *      from every customer authority upstream — so attaching a signed-in
- *      shopper's token to an operator read turns a working call into a 403 that
+ *      refused.** On api-public a request presenting `sk_` plus a user
+ *      bearer resolves the USER as the authority, and `events` is stripped
+ *      from every user authority upstream — so attaching a signed-in
+ *      shopper's token to a project read turns a working call into a 403 that
  *      reads like a scope problem. Refusing it here says what actually happened.
  *
- * Widening this later is easy. Teaching customers a capability they do not have
+ * Widening this later is easy. Teaching users a capability they do not have
  * is a support burden that cannot be retracted.
  *
  * ---------------------------------------------------------------------------
@@ -79,7 +79,7 @@ export declare const FOIR_EVENTS_PATH = "/v1/events";
 /**
  * The scope an `sk_` key must hold. Never mintable on a `pk_` — `events` is
  * absent from the platform's `publicSafeScopeResources` — and never present in a
- * customer's resolved authority.
+ * user's resolved authority.
  */
 export declare const FOIR_EVENTS_SCOPE = "events:read";
 /**
@@ -91,9 +91,9 @@ export declare const FOIR_EVENTS_SCOPE = "events:read";
 export declare const FOIR_EVENTS_RETENTION_DAYS = 90;
 /** Who caused an event. `null` when the emit site attributed nobody. */
 export interface FoirEventActor {
-    /** e.g. `"customer"`, `"admin"`, `"api_key"`, `"system"`. */
+    /** e.g. `"user"`, `"api_key"`, `"system"`. */
     kind?: string;
-    /** e.g. `"customer:cus_123"`. */
+    /** e.g. `"user:usr_123"`. */
     ref?: string;
     [key: string]: unknown;
 }
@@ -119,7 +119,7 @@ export interface FoirEvent {
      * The event's own flat keys, plus `state` and `stateSchema`.
      *
      * `state` is the resource AS OF the event — self-contained, not a pointer to
-     * current state — for the customer, session, operation and workspace-plane
+     * current state — for the user, session, operation and workspace-plane
      * families. It is null for `record.*` events, deliberately and permanently:
      * `events.view` is plain tenant/project containment while `record.view`
      * carries owner, grant, borrow and per-field terms, so a copy of record data
@@ -200,15 +200,15 @@ export interface FoirEventsClientConfig {
      */
     apiUrl: string;
     /**
-     * An `sk_` secret key holding `events:read`.
+     * An admin key holding `events:read`.
      *
-     * A `pk_` key is refused here rather than at the server — see the operator
-     * note at the top of this file.
+     * A publishable or a server key is refused here rather than at the server:
+     * see the note at the top of this file.
      */
     apiKey: string;
     /**
-     * Extra headers. An `Authorization` header is refused: a customer bearer
-     * flips api-public's resolved authority to the customer, and no customer
+     * Extra headers. An `Authorization` header is refused: a user bearer
+     * flips api-public's resolved authority to the user, and no user
      * authority can contain `events:read`.
      */
     headers?: Readonly<Record<string, string>>;

package/dist/server/operation-types.d.ts

@@ -147,17 +147,17 @@ export interface OperationContext {
     /** Project ID */
     projectId: string;
     /**
-     * The principal that started the run. Always present, and the empty string
-     * when the run has none, as a hook's run does.
+     * Who started the run. Always present, and the empty string when nobody
+     * did, as for a hook's run.
      */
-    userId: string;
+    actorId: string;
     /**
-     * The customer the run acts for, when it acts for one: the signed-in
-     * customer who ran it, or the owner of the record whose event fired the
-     * hook. The dispatch token carries the same customer, so a client built from
-     * it acts for them too.
+     * The user the run acts for, when it acts for one: the signed-in user who
+     * ran it, or the owner of the record whose event fired the hook. The
+     * dispatch token carries the same user, so a client built from it acts for
+     * them too.
      */
-    customerId?: string;
+    userId?: string;
     /** When the platform built this body, RFC 3339 in UTC to the second. */
     timestamp: string;
 }

package/dist/server/require-scoped-token.d.ts

@@ -120,12 +120,12 @@ export interface ScopedTokenIngress {
      */
     orgId: string | null;
     /**
-     * The customer the run acts for, when it acts for one: the signed-in
-     * customer who ran the operation, or the owner of the record whose event
+     * The user the run acts for, when it acts for one: the signed-in
+     * user who ran the operation, or the owner of the record whose event
      * fired it. Verified with the rest of the token, so it is the one to trust
      * over anything in the input.
      */
-    customerId?: string;
+    userId?: string;
     /** When the token stops being accepted. There is no refresh: finish, or report, before it. */
     expiresAt: Date;
     /** The token's own id (`jti`). The run's id on a dispatch that carries no other. */

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

@@ -25,7 +25,7 @@ export declare class ServerClientError extends Error {
  *
  * const client = createServerClient({
  *   baseUrl: 'https://api.example.com',
- *   apiKey: 'sk_project_xxx',
+ *   apiKey: process.env.FOIR_ADMIN_KEY!, // foir_adm_...
  * });
  *
  * const { data } = await client.query('query { models { items { key } } }');

package/dist/server/types.d.ts

@@ -16,7 +16,7 @@ export interface ServerClientOptions {
     configKey?: string;
 }
 /**
- * Where an editor iframe should appear in the admin record editor.
+ * Where an editor iframe should appear in the console's record editor.
  */
 export interface EditorPlacement {
     /** 'main-editor' replaces / augments the content tab; 'sidebar' renders in the sidebar. */

package/dist/server/verify-scoped-token.d.ts

@@ -28,8 +28,7 @@ export interface ScopedTokenClaims {
      * What the token carries, as grants in the permission catalogue's names:
      * `records:read:<model>`, `records:write:<model>`,
      * `records:create:<model>`, `users:create` and the rest. It is the whole of
-     * what the token may do. A token minted before a token said its grants is
-     * read as what its older claims were worth, as the platform reads it, so
+     * what the token may do. A token that does not say its grants is refused, so
      * this is always set.
      */
     grants: Array<string>;
@@ -39,32 +38,9 @@ export interface ScopedTokenClaims {
     iat: number;
     ctx?: Record<string, string>;
     /**
-     * The same grants in the names a token said them with before it said its
-     * grants. They never say more than {@link ScopedTokenClaims.grants}, and
-     * can say less: a grant the older names had no word for is left out.
-     *
-     * @deprecated Read {@link ScopedTokenClaims.grants}. The platform stops
-     * sending this once no token minted before is live.
-     */
-    cap?: Array<string>;
-    /**
-     * The models the older `records:read` marker in
-     * {@link ScopedTokenClaims.cap} was for.
-     *
-     * @deprecated Read {@link recordsReadModels}.
-     */
-    rrm?: Array<string>;
-    /**
-     * The models the older `records:write` marker in
-     * {@link ScopedTokenClaims.cap} was for.
-     *
-     * @deprecated Read {@link recordsWriteModels}.
-     */
-    rwm?: Array<string>;
-    /**
-     * The customer the token acts for, when it acts for one: the signed-in
-     * customer who ran the operation, or the owner of the record whose event
-     * fired it. `requireScopedToken` answers it as `customerId`.
+     * The user the token acts for, when it acts for one: the signed-in
+     * user who ran the operation, or the owner of the record whose event
+     * fired it. `requireScopedToken` answers it as `userId`.
      */
     cid?: string;
 }

package/dist/server.js

@@ -74,10 +74,10 @@ async function verifyWebhookSignature(payload, signature, secret) {
 
 // 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, [], []],
@@ -93,8 +93,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, [], []],
@@ -151,7 +151,8 @@ 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:stand", false, [], []],
+  ["project:manage", false, [], ["project:stand", "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:setup", "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, [], []],
@@ -164,12 +165,14 @@ var GRANT_TABLE = [
   ["usage:read", false, [], []],
   ["controlkeys:read", false, [], []],
   ["controlkeys:write", false, [], []],
+  ["tenantsigninproviders:read", false, [], []],
+  ["tenantsigninproviders: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", "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", "tenantsigninproviders:read", "tenantsigninproviders:write", "apps:install"]],
   ["platform:read", false, [], []],
-  ["platform:manage", false, [], ["tenant:manage", "platform:read", "platform:create_workspace", "users:setup"]],
+  ["platform:manage", false, [], ["tenant:manage", "platform:read", "platform:create_workspace"]],
   ["platform:create_workspace", false, [], []],
   ["users:read", false, ["own", "named", "all"], []],
   ["users:write", false, ["own", "all"], []],
@@ -231,49 +234,6 @@ function parseGrant(s) {
   return null;
 }
 
-// src/server/older-claims.generated.ts
-var OLDER_CLAIM_TARGET = "{target}";
-var OLDER_CAPABILITY_GRANTS = {
-  "config:read": ["appconfig:read"],
-  "customers:read": ["users:read.all"],
-  "customers:read:identity": ["identities:read"],
-  "customers:read:named": ["users:read.named"],
-  "customers:write": ["users:create"],
-  "embeddings:read": ["embeddings:read"],
-  "embeddings:write": ["embeddings:write"],
-  "files:delete": ["files:delete"],
-  "files:list": ["files:read"],
-  "files:read": ["files:read"],
-  "files:write": ["files:write"],
-  "notifications:consent": ["notifications:consent"],
-  "notifications:read": ["notifications:read"],
-  "notifications:write": ["notifications:write.named"],
-  "operations:complete": ["operations:complete"],
-  "records:attribute": ["records:attribute"],
-  "records:attribute:{target}": ["records:attribute:{target}"],
-  "records:delete": [],
-  "records:delete:{target}": ["records:delete:{target}"],
-  "records:publish": [],
-  "records:publish:{target}": ["records:publish:{target}"],
-  "records:read": [],
-  "records:read:{target}": ["records:read:{target}"],
-  "records:write": [],
-  "records:write:{target}": ["records:write.all:{target}", "records:create:{target}"],
-  "secrets:delete.app": ["appsecrets:delete"],
-  "secrets:delete.customer": ["usersecrets:delete"],
-  "secrets:delete.project": ["secrets:delete"],
-  "secrets:list.app": ["appsecrets:list"],
-  "secrets:list.customer": ["usersecrets:list"],
-  "secrets:list.project": ["secrets:list"],
-  "secrets:put.app": ["appsecrets:put"],
-  "secrets:put.customer": ["usersecrets:put"],
-  "secrets:put.project": ["secrets:put"],
-  "secrets:read.app": ["appsecrets:read"],
-  "secrets:read.customer": ["usersecrets:read"],
-  "secrets:read.project": ["secrets:read"],
-  "status:write": ["status:write"]
-};
-
 // src/server/verify-scoped-token.ts
 var JWKS_CACHE_TTL_MS = 5 * 60 * 1e3;
 function getCache() {
@@ -349,49 +309,9 @@ function recordsWriteModels(claims) {
 function recordsCreateModels(claims) {
   return modelsFor(claims, "records:create");
 }
-var OLDER_RECORD_LANES = [
-  ["records:read", "rrm"],
-  ["records:write", "rwm"],
-  ["records:delete", "rdm"],
-  ["records:publish", "rpm"]
-];
 function strings(value) {
   return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
 }
-function worthBefore(capability) {
-  if (Object.hasOwn(OLDER_CAPABILITY_GRANTS, capability)) return OLDER_CAPABILITY_GRANTS[capability] ?? [];
-  for (const [form, grants] of Object.entries(OLDER_CAPABILITY_GRANTS)) {
-    if (!form.endsWith(OLDER_CLAIM_TARGET)) continue;
-    const prefix = form.slice(0, -OLDER_CLAIM_TARGET.length);
-    if (capability.startsWith(prefix) && capability.length > prefix.length) {
-      const model = capability.slice(prefix.length);
-      return grants.map((grant) => grant.replace(OLDER_CLAIM_TARGET, model));
-    }
-  }
-  return [];
-}
-var OLDER_WRITE = "records:write";
-var OLDER_DELETE = "records:delete";
-var OLDER_CREATE = "customers:write";
-function grantsOfOlderClaims(payload) {
-  const cap = strings(payload.cap);
-  const written = new Set(cap.includes(OLDER_WRITE) ? strings(payload.rwm) : []);
-  const grants = [];
-  for (const [marker, claim] of OLDER_RECORD_LANES) {
-    if (!cap.includes(marker)) continue;
-    for (const model of strings(payload[claim])) {
-      if (marker !== OLDER_WRITE && written.has(model)) grants.push(`${marker}.all:${model}`);
-      else grants.push(...worthBefore(`${marker}:${model}`));
-    }
-  }
-  for (const capability of cap) {
-    if (!OLDER_RECORD_LANES.some(([marker]) => marker === capability)) grants.push(...worthBefore(capability));
-  }
-  if (cap.includes(OLDER_CREATE) && cap.includes(OLDER_DELETE) && strings(payload.rdm).length > 0) {
-    grants.push("identities:delete");
-  }
-  return grants;
-}
 async function verifyScopedToken(token, jwksUrl, options) {
   return verifyWithKeys(token, () => loadJwks(jwksUrl), void 0, options);
 }
@@ -432,10 +352,7 @@ async function verifyWithKeys(token, loadKeys, refetchForUnknownKid, options) {
   } catch {
     throw new Error("unreadable token payload");
   }
-  const claims = {
-    ...payload,
-    grants: "grants" in payload ? strings(payload.grants) : grantsOfOlderClaims(payload)
-  };
+  const claims = { ...payload, grants: strings(payload.grants) };
   const now = Math.floor((options?.now?.() ?? Date.now()) / 1e3);
   if (claims.iss !== expectedIssuer) throw new Error(`bad iss ${claims.iss}`);
   if (typeof claims.exp !== "number" || claims.exp < now) {
@@ -444,6 +361,7 @@ async function verifyWithKeys(token, loadKeys, refetchForUnknownKid, options) {
   if (typeof claims.nbf === "number" && claims.nbf > now + 30) {
     throw new Error("token not yet valid");
   }
+  if (!("grants" in payload)) throw new Error("the token says no grants");
   return claims;
 }
 function parseContextHeader(raw) {
@@ -662,7 +580,7 @@ async function requireScopedToken(request, options) {
     // header, so the client presents exactly what this guard accepted.
     dispatch: { token: () => token, context: rawContext },
     orgId: typeof level === "string" ? level : null,
-    ...typeof claims.cid === "string" && claims.cid !== "" ? { customerId: claims.cid } : {},
+    ...typeof claims.cid === "string" && claims.cid !== "" ? { userId: claims.cid } : {},
     expiresAt: new Date(claims.exp * 1e3),
     tokenId: claims.jti
   };
@@ -724,9 +642,9 @@ async function readDispatch(request) {
   if (!isObject(context)) refuse(`body.context is ${describe(context)}, expected an object`);
   requireString(context, "tenantId", "body.context");
   requireString(context, "projectId", "body.context");
-  requireString(context, "userId", "body.context", true);
+  requireString(context, "actorId", "body.context", true);
   requireString(context, "timestamp", "body.context");
-  if (context.customerId !== void 0) requireString(context, "customerId", "body.context");
+  if (context.userId !== void 0) requireString(context, "userId", "body.context");
   const input = body.input;
   if (input !== null && !isObject(input)) {
     refuse(`body.input is ${describe(input)}, expected an object`);
@@ -879,6 +797,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"
@@ -925,8 +865,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;
@@ -934,7 +874,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" } }]
     });
@@ -1096,12 +1036,26 @@ async function hmacSha256Hex(secret, body) {
   return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+// 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;
+}
+
 // src/data/transport.ts
 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;
@@ -1180,7 +1134,7 @@ var FoirSocketTransport = class {
   constructor(config) {
     if (config.dispatch !== void 0) {
       throw new FoirRequestError(
-        "[foir] a client built from a dispatch token cannot subscribe. The subscription socket authenticates an api key, an admin token or a customer bearer, and has no path for a dispatch token. Queries and mutations made as the operation go to /graphql and work as they are."
+        "[foir] a client built from a dispatch token cannot subscribe. The subscription socket authenticates an api key, a console token or a user bearer, and has no path for a dispatch token. Queries and mutations made as the operation go to /graphql and work as they are."
       );
     }
     this.config = config;
@@ -1538,17 +1492,18 @@ function assertOperatorKey(apiKey) {
   const key = apiKey?.trim() ?? "";
   if (!key) {
     throw new FoirRequestError(
-      `[foir] createEventsClient: apiKey is empty \u2014 pass an sk_ secret key holding ${FOIR_EVENTS_SCOPE}.`
+      `[foir] createEventsClient: apiKey is empty. Pass an admin key holding ${FOIR_EVENTS_SCOPE}.`
     );
   }
-  if (key.startsWith("pk_")) {
+  const kind = foirKeyKind(key);
+  if (kind === "publishable" || kind === "server") {
     throw new FoirRequestError(
-      `[foir] createEventsClient: the event log is an OPERATOR surface and a public (pk_) key can never hold ${FOIR_EVENTS_SCOPE} \u2014 it is not mintable on a public key. Use an sk_ secret key from a server-side runtime; a pk_ key is embeddable in browser bundles, and the log names which customer acted on records the bundle's reader cannot themselves read.`
+      `[foir] createEventsClient: the event log is a project surface and a ${kind} key can never hold ${FOIR_EVENTS_SCOPE}: it is not mintable on an app's key. Use an admin key from a machine of your own. The log names which user acted on records that whoever reads an app's key cannot themselves read.`
     );
   }
-  if (!key.startsWith("sk_")) {
+  if (kind === void 0) {
     throw new FoirRequestError(
-      `[foir] createEventsClient: apiKey must be an sk_ secret key, got a key starting "${key.slice(0, 4)}". The event log is reachable by an sk_ api key or an admin session only.`
+      `[foir] createEventsClient: apiKey must be an admin key, got a key starting "${key.slice(0, 4)}". The event log is reachable by an admin key or a console session only.`
     );
   }
   return key;
@@ -1558,7 +1513,7 @@ function assertNoBearer(headers) {
   for (const name of Object.keys(headers)) {
     if (name.toLowerCase() === "authorization") {
       throw new FoirRequestError(
-        `[foir] createEventsClient: an Authorization header is not accepted. A customer bearer makes the customer the resolved authority on api-public, and no customer authority can contain ${FOIR_EVENTS_SCOPE}. The sk_ key alone is the credential for this surface.`
+        `[foir] createEventsClient: an Authorization header is not accepted. A user bearer makes the user the resolved authority on api-public, and no user authority can contain ${FOIR_EVENTS_SCOPE}. The sk_ key alone is the credential for this surface.`
       );
     }
   }