@foir/sdk 0.20.0 → 0.22.0

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"
@@ -144,8 +166,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;
@@ -153,7 +175,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" } }]
     });
@@ -170,7 +192,7 @@ function reportAuthDowngrade(envelope) {
   if (warnedDowngrade === downgrade.reason) return;
   warnedDowngrade = downgrade.reason;
   console.warn(
-    `[foir] your customer token was ${downgrade.customerToken} (${downgrade.reason}) \u2014 this request was served as ${downgrade.servedAs}, so auth-targeted content resolved to its anonymous variant. ` + (downgrade.reason === "expired" ? "Re-exchange the token and retry." : "Check which credential you are sending.")
+    `[foir] your user token was ${downgrade.userToken} (${downgrade.reason}) \u2014 this request was served as ${downgrade.servedAs}, so auth-targeted content resolved to its anonymous variant. ` + (downgrade.reason === "expired" ? "Re-exchange the token and retry." : "Check which credential you are sending.")
   );
 }
 function refusePrunedDocument(json, options) {
@@ -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) {
@@ -336,7 +383,7 @@ function assertFoirCredential(config) {
   ].filter((name) => loose[name] !== void 0);
   if (keySide.length > 0) {
     throw new FoirRequestError(
-      `[foir] createFoirClient was given \`dispatch\` and ${keySide.map((n) => `\`${n}\``).join(", ")}. A dispatch token and an api key are different actors, and the dispatch token carries its own customer, organization and channel. Pass one credential: \`dispatch\` inside an operation endpoint, \`apiKey\` everywhere else.`
+      `[foir] createFoirClient was given \`dispatch\` and ${keySide.map((n) => `\`${n}\``).join(", ")}. A dispatch token and an api key are different actors, and the dispatch token carries its own user, organization and channel. Pass one credential: \`dispatch\` inside an operation endpoint, \`apiKey\` everywhere else.`
     );
   }
   const dispatch = loose.dispatch;
@@ -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) {
@@ -1358,7 +1411,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;
@@ -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/graphql/content-client.d.ts

@@ -1,19 +1,19 @@
 /**
- * Session-bound content client — forwards the customer bearer on every read
- * when one is available, so auth/segment-targeted variants and customer-scoped
+ * Session-bound content client — forwards the user bearer on every read
+ * when one is available, so auth/segment-targeted variants and user-scoped
  * records resolve out of the box, with no per-query wiring to forget.
  *
  * Resolution keys off the request's principal (see the platform's two-gate
  * model): the `x-api-key` alone resolves the *anonymous baseline*
- * (`context.authStatus = ""`); adding the customer bearer resolves the request
- * as that customer (`context.authStatus = "authenticated"`, `customer_id` set).
+ * (`context.authStatus = ""`); adding the user bearer resolves the request
+ * as that user (`context.authStatus = "authenticated"`, `user_id` set).
  *
  * Caching: an api-key-only read is identical for every anonymous visitor and is
- * shared-cacheable; a bearer-bearing read resolves per-customer and is not.
- * Because the bearer only exists once a customer signs in, anonymous traffic
+ * shared-cacheable; a bearer-bearing read resolves per-user and is not.
+ * Because the bearer only exists once a user signs in, anonymous traffic
  * keeps hitting the shared-cacheable baseline — only signed-in reads become
- * per-customer. Bind this client wherever content is personalized (for most
- * apps, everywhere the customer may be signed in) and use plain `foirRequest`
+ * per-user. Bind this client wherever content is personalized (for most
+ * apps, everywhere the user may be signed in) and use plain `foirRequest`
  * for reads that must stay anonymous regardless of session.
  */
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
@@ -25,9 +25,9 @@ import type { FoirTokenProvider } from '../transport/foir-http';
 export interface FoirContentClientConfig {
     env: FoirEnv;
     /**
-     * Resolves the current customer bearer before every request. When it yields a
+     * Resolves the current user bearer before every request. When it yields a
      * token the token is forwarded, so `authStatus`/segment targeting and
-     * customer-scoped records resolve as that customer; when it yields
+     * user-scoped records resolve as that user; when it yields
      * null/undefined the read hits the anonymous baseline. Omit for a client that
      * is always anonymous (equivalent to calling `foirRequest` directly).
      */
@@ -51,7 +51,7 @@ export interface FoirContentClientConfig {
 }
 export interface FoirContentClient {
     /**
-     * Run a typed document, forwarding the bound customer bearer when available.
+     * Run a typed document, forwarding the bound user bearer when available.
      * An explicit `options.bearerToken` still wins, so a single call can override
      * the bound token (or force anonymous by passing `undefined` — the bound
      * token only fills in when `options.bearerToken` is not supplied).
@@ -60,7 +60,7 @@ export interface FoirContentClient {
 }
 /**
  * Create a {@link FoirContentClient} bound to an env + token source. Every
- * `request` forwards the customer bearer when `getToken` yields one, upgrading
- * that read from the anonymous baseline to the signed-in customer.
+ * `request` forwards the user bearer when `getToken` yields one, upgrading
+ * that read from the anonymous baseline to the signed-in user.
  */
 export declare function createFoirContentClient(config: FoirContentClientConfig): FoirContentClient;

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/live/drift.d.ts

@@ -12,7 +12,7 @@ import type { FoirSchemaDrift } from '../data/transport';
  * Nothing else catches it. The dependency graph is about records, and no record
  * changed. `seq` is about ordering, and nothing is out of order. The entry is
  * fresh, correctly tagged, correctly stamped, and describes a schema that no
- * longer exists — until the tab is reloaded, which on a long-lived admin
+ * longer exists — until the tab is reloaded, which on a long-lived console
  * session can be days.
  *
  * The SDK already detects this: the data client compares the surface version

package/dist/media/screen-capture.d.ts

@@ -6,7 +6,7 @@
  * ---------------------------------------------------------------------------
  *
  * Two surfaces need the same picture: the console's own bug report, and the
- * feedback widget a customer's visitors use (`@foir/sdk/react`). One of those
+ * feedback widget a user's visitors use (`@foir/sdk/react`). One of those
  * ships to npm and the other does not, so the shared half has to sit in the
  * published package — a copy in each would be two answers to "how big is a
  * screenshot", free to drift, and the drift would only show up as an upload the

package/dist/next/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * `@foir/sdk/next` — server-side Foir customer auth for the Next.js App Router
+ * `@foir/sdk/next` — server-side Foir user auth for the Next.js App Router
  * (the BFF pattern): an HttpOnly-cookie session adapter, server-side session
  * helpers, a provider-callback exchange, and a route-protection middleware.
  *
@@ -18,5 +18,5 @@ export { readFoirCacheTags, foirCacheTags, createFoirTaggingFetch, foirTagsForRe
 export type { FoirHeaderSource, FoirCacheTags, FoirCacheTagsOptions, FoirTaggingReport, FoirTaggingFetchOptions, FoirRecordChange, } from './cacheTags';
 export { createFoirMiddleware } from './middleware';
 export type { FoirMiddlewareConfig, FoirMiddlewareRequest } from './middleware';
-export type { FoirCustomer, SessionAdapter } from '../auth';
+export type { FoirUser, SessionAdapter } from '../auth';
 export type { FoirEnv } from '../graphql/foir-request';

package/dist/next/session.d.ts

@@ -1,4 +1,4 @@
-import type { FoirCustomer } from '../auth';
+import type { FoirUser } from '../auth';
 import type { FoirEnv } from '../graphql/foir-request';
 import type { CookieAdapterOptions, FoirCookieStore } from './cookieAdapter';
 /**
@@ -6,14 +6,14 @@ import type { CookieAdapterOptions, FoirCookieStore } from './cookieAdapter';
  * cookie store (`await cookies()` in a route handler / server action, or the
  * read-only `cookies()` in a Server Component for reads).
  *
- * Note on "verification": the customer access token is opaque to your app and
+ * Note on "verification": the user access token is opaque to your app and
  * validated by the Foir API on use, so `getFoirSession` returns the identity
  * stored in the cookies rather than locally verifying a JWT. A rejected/expired
  * bearer surfaces when you call the API (and `@foir/sdk/auth`'s `authedRequest`
  * transparently refreshes it).
  */
-/** The signed-in customer from the session cookies, or null. */
-export declare function getFoirSession(store: FoirCookieStore): Promise<FoirCustomer | null>;
+/** The signed-in user from the session cookies, or null. */
+export declare function getFoirSession(store: FoirCookieStore): Promise<FoirUser | null>;
 /** The current access token from the session cookies, or null. */
 export declare function getFoirToken(store: FoirCookieStore): Promise<string | null>;
 /** Clear the session cookies (sign out). */
@@ -26,9 +26,9 @@ interface PasswordArgs {
     cookieOptions?: CookieAdapterOptions['cookieOptions'];
 }
 /** Password sign-in in a route handler; persists the session to cookies. */
-export declare function foirSignInWithPassword({ env, store, email, password, cookieOptions, }: PasswordArgs): Promise<FoirCustomer>;
-/** Register a customer in a route handler; persists the session to cookies. */
-export declare function foirRegisterWithPassword({ env, store, email, password, cookieOptions, }: PasswordArgs): Promise<FoirCustomer>;
+export declare function foirSignInWithPassword({ env, store, email, password, cookieOptions, }: PasswordArgs): Promise<FoirUser>;
+/** Register a user in a route handler; persists the session to cookies. */
+export declare function foirRegisterWithPassword({ env, store, email, password, cookieOptions, }: PasswordArgs): Promise<FoirUser>;
 /** Complete an OTP sign-in in a route handler; persists the session to cookies. */
 export declare function foirSignInWithOtp({ env, store, email, otp, cookieOptions, }: {
     env: FoirEnv;
@@ -36,11 +36,11 @@ export declare function foirSignInWithOtp({ env, store, email, otp, cookieOption
     email: string;
     otp: string;
     cookieOptions?: CookieAdapterOptions['cookieOptions'];
-}): Promise<FoirCustomer>;
+}): Promise<FoirUser>;
 /**
  * Complete a provider (OAuth/OIDC) login in your callback route handler:
  * exchange the `code` + `state` for tokens and persist them to the session
- * cookies. Returns the customer.
+ * cookies. Returns the user.
  */
 export declare function completeFoirProviderLogin(opts: {
     env: FoirEnv;
@@ -49,5 +49,5 @@ export declare function completeFoirProviderLogin(opts: {
     code?: string;
     state?: string;
     cookieOptions?: CookieAdapterOptions['cookieOptions'];
-}): Promise<FoirCustomer>;
+}): Promise<FoirUser>;
 export {};