@foir/sdk 0.20.0 → 0.22.0

package/dist/push.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"
@@ -171,8 +217,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;
@@ -180,7 +226,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" } }]
     });
@@ -197,7 +243,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) {
@@ -277,7 +323,7 @@ function isCdnEligible(env, documentText, bearerToken, orgId) {
   if (orgId) return false;
   if (isFoirPreview(env)) return false;
   const apiKey = resolveFoirApiKey(env);
-  if (!apiKey?.startsWith("pk_")) return false;
+  if (!isPublishableFoirKey(apiKey)) return false;
   return !/\bmutation\b/.test(documentText);
 }
 
@@ -290,6 +336,9 @@ async function foirRequest(env, document, variables, options) {
       "[foir] PLATFORM_API_URL or PLATFORM_API_KEY is not set \u2014 add them to .env"
     );
   }
+  if (foirKeyKind(apiKey) === "admin") {
+    throw new FoirRequestError(adminKeyRefusal("foirRequest"));
+  }
   const headers = buildFoirHeaders({
     apiKey,
     draftChannel: isFoirPreview(env),
@@ -852,10 +901,7 @@ function foirDataEndpoint(apiUrl, path) {
   return foirApiEndpoint(apiUrl, path);
 }
 async function resolveVisitorAddress(config) {
-  const source = config.visitor;
-  const value = typeof source === "function" ? await source() : source;
-  const address = value?.trim();
-  return address ? address : void 0;
+  return (await resolveFoirVisitor(config.visitor)).address;
 }
 async function resolveBearerToken(config) {
   const source = config.bearerToken;
@@ -896,7 +942,7 @@ async function resolveFoirAuth(config) {
   };
 }
 function foirRoute(input) {
-  if (!input.apiKey.startsWith("pk_")) return { lane: "origin", reason: "key" };
+  if (!isPublishableFoirKey(input.apiKey)) return { lane: "origin", reason: "key" };
   if (input.bearerToken) return { lane: "origin", reason: "bearer" };
   if (input.orgId || input.orgUrl) return { lane: "origin", reason: "org" };
   if (input.mutation) return { lane: "origin", reason: "operation" };
@@ -1030,42 +1076,63 @@ var AUTH_OPS = {
   authConfig: "authConfig",
   authProviders: "authProviders",
   defaultAuthProvider: "defaultAuthProvider",
-  customerSignupContext: "customerSignupContext",
+  signupContext: "signupContext",
   // Post-credential self reads.
   currentUser: "currentUser",
   myProviderToken: "myProviderToken",
-  // What the calling credential may do, and for a signed-in customer the roles
+  // What the calling credential may do, and for a signed-in user the roles
   // they hold. `./access` reads it.
   whoami: "whoami",
   // Methods.
-  customerLogin: "customerLogin",
-  customerRegister: "customerRegister",
-  customerRequestOTP: "customerRequestOTP",
-  customerLoginOTP: "customerLoginOTP",
+  login: "login",
+  register: "register",
+  requestOTP: "requestOTP",
+  loginWithOTP: "loginWithOTP",
   // Session lifecycle.
-  customerRefreshToken: "customerRefreshToken",
-  customerLogout: "customerLogout",
-  customerJoinWaitlist: "customerJoinWaitlist",
-  // Password management and account lifecycle — the block that had no path.
-  customerRequestPasswordReset: "customerRequestPasswordReset",
-  customerResetPassword: "customerResetPassword",
-  customerUpdatePassword: "customerUpdatePassword",
-  customerVerifyEmail: "customerVerifyEmail",
+  refreshToken: "refreshToken",
+  logout: "logout",
+  joinWaitlist: "joinWaitlist",
+  // Password management and account lifecycle.
+  requestPasswordReset: "requestPasswordReset",
+  resetPassword: "resetPassword",
+  updatePassword: "updatePassword",
+  verifyEmail: "verifyEmail",
   deleteMyAccount: "deleteMyAccount",
-  // The operator's organization context. TWO ops and no third: one to read
-  // which organizations the caller may stand in, one to say which. There is
-  // deliberately no per-call org argument anywhere in this SDK — the claim the
-  // row layer reads is resolved from the caller's own membership row on every
-  // request, so an application that never names an org cannot name the wrong
-  // one.
+  // The user's own profile, and the apps they have agreed may act for them.
+  updateMyProfile: "updateMyProfile",
+  myAuthorizedApps: "myAuthorizedApps",
+  revokeAuthorizedApp: "revokeAuthorizedApp",
+  // Where they are signed in, their personal access tokens, and the
+  // providers they sign in with.
+  mySessions: "mySessions",
+  endMySession: "endMySession",
+  signOutEverywhere: "signOutEverywhere",
+  createPersonalAccessToken: "createPersonalAccessToken",
+  mySignInMethods: "mySignInMethods",
+  connectSignInMethod: "connectSignInMethod",
+  disconnectSignInMethod: "disconnectSignInMethod",
+  // Their second factors. A change needs one proven first, by a step-up.
+  myFactors: "myFactors",
+  beginStepUp: "beginStepUp",
+  completeStepUp: "completeStepUp",
+  beginFactorEnrollment: "beginFactorEnrollment",
+  completeFactorEnrollment: "completeFactorEnrollment",
+  removeFactor: "removeFactor",
+  makeRecoveryCodes: "makeRecoveryCodes",
+  // The organizations the caller may stand in. Nothing selects one: a request
+  // names the organization it acts in (`orgId` or `orgUrl` below), and the
+  // platform checks the caller stands there every time.
   myOrganizations: "myOrganizations",
-  selectMyOrganization: "selectMyOrganization",
   // Founding one. Present in a manifest only when the project opted in.
-  registerOperatorOrganization: "registerOperatorOrganization",
+  registerOrganization: "registerOrganization",
   // External identity providers.
-  customerLoginWithProvider: "customerLoginWithProvider",
-  customerProviderCallback: "customerProviderCallback",
-  customerProviderVerifyOTP: "customerProviderVerifyOTP"
+  loginWithProvider: "loginWithProvider",
+  providerCallback: "providerCallback",
+  providerVerifyOTP: "providerVerifyOTP",
+  // A provider sign-in that names an address somebody already holds, waiting
+  // for the code sent to it.
+  confirmProviderLink: "confirmProviderLink",
+  resendProviderLinkCode: "resendProviderLinkCode"
 };
 function authClientConfig(env, options) {
   const apiKey = resolveFoirApiKey(env);
@@ -1128,32 +1195,32 @@ function stripUndefined(args) {
 // src/auth/auth.ts
 var TOKEN_KEY = "foir:token";
 var REFRESH_KEY = "foir:refreshToken";
-var CUSTOMER_ID_KEY = "foir:customerId";
+var USER_ID_KEY = "foir:userId";
 var EMAIL_KEY = "foir:email";
-async function customerRefreshToken(env, refreshToken) {
-  return authOp(env, AUTH_OPS.customerRefreshToken, { refreshToken });
+async function refreshTokens(env, refreshToken) {
+  return authOp(env, AUTH_OPS.refreshToken, { refreshToken });
 }
 async function saveSession(adapter, result) {
   await adapter.set(TOKEN_KEY, result.token);
   await adapter.set(REFRESH_KEY, result.refreshToken);
-  if (!result.customerId) {
-    return await getSessionCustomer(adapter) ?? { id: "", email: "" };
+  if (!result.userId) {
+    return await getSessionUser(adapter) ?? { id: "", email: "" };
   }
-  await adapter.set(CUSTOMER_ID_KEY, result.customerId);
+  await adapter.set(USER_ID_KEY, result.userId);
   await adapter.set(EMAIL_KEY, result.email);
-  return { id: result.customerId, email: result.email };
+  return { id: result.userId, email: result.email };
 }
 async function clearSession(adapter) {
   await adapter.unset(TOKEN_KEY);
   await adapter.unset(REFRESH_KEY);
-  await adapter.unset(CUSTOMER_ID_KEY);
+  await adapter.unset(USER_ID_KEY);
   await adapter.unset(EMAIL_KEY);
 }
 async function getSessionToken(adapter) {
   return await adapter.get(TOKEN_KEY) ?? null;
 }
-async function getSessionCustomer(adapter) {
-  const id = await adapter.get(CUSTOMER_ID_KEY) ?? null;
+async function getSessionUser(adapter) {
+  const id = await adapter.get(USER_ID_KEY) ?? null;
   const email = await adapter.get(EMAIL_KEY) ?? null;
   if (!id) return null;
   return { id, email: email ?? "" };
@@ -1162,7 +1229,7 @@ async function refreshSession(adapter, env) {
   const refreshToken = await adapter.get(REFRESH_KEY) ?? null;
   if (!refreshToken) return null;
   try {
-    const result = await customerRefreshToken(env, refreshToken);
+    const result = await refreshTokens(env, refreshToken);
     await saveSession(adapter, result);
     return { token: result.token, refreshToken: result.refreshToken };
   } catch {

package/dist/react/FoirFeedback.d.ts

@@ -1,4 +1,4 @@
-import type { FoirCustomerNote, FoirSubject, FoirSubjectRegistry } from '../data';
+import type { FoirUserNote, FoirSubject, FoirSubjectRegistry } from '../data';
 import { type FoirFeedbackClient } from './feedback-notes';
 export type { FoirFeedbackClient } from './feedback-notes';
 export interface FoirFeedbackProps {
@@ -46,7 +46,7 @@ export interface FoirFeedbackProps {
      */
     onSignIn?: () => void;
     /** Called with the note once it is written. */
-    onSubmitted?: (note: FoirCustomerNote) => void;
+    onSubmitted?: (note: FoirUserNote) => void;
     /**
      * Called with anything that failed. The widget also logs it — this is for
      * routing it into your own error reporting, not for making it visible.

package/dist/react/FoirProvider.d.ts

@@ -1,22 +1,22 @@
 import type { ReactNode } from 'react';
-import type { AuthProviderPublic, FoirAccess, FoirCustomer, FoirSessionConfig, SessionAdapter } from '../auth';
+import type { AuthProviderPublic, FoirAccess, FoirUser, FoirSessionConfig, SessionAdapter } from '../auth';
 import type { ProviderCallbackInput, ProviderLoginInput } from '../auth';
 import type { FoirEnv } from '../graphql/foir-request';
 /** Where the session hydration stands. */
 export type FoirStatus = 'loading' | 'authenticated' | 'unauthenticated';
 /**
- * Where reading the signed-in customer's access stands. `idle` until something
+ * Where reading the signed-in user's access stands. `idle` until something
  * asks for it; `unavailable` when the platform could not be asked.
  */
 export type FoirAccessStatus = 'idle' | 'loading' | 'ready' | 'unavailable';
 /** The full context value. Read it through the hooks below, not directly. */
 export interface FoirContextValue {
     status: FoirStatus;
-    customer: FoirCustomer | null;
-    /** The signed-in customer's access, once read. See {@link useFoirAccess}. */
+    user: FoirUser | null;
+    /** The signed-in user's access, once read. See {@link useFoirAccess}. */
     access: FoirAccess | null;
     accessStatus: FoirAccessStatus;
-    /** Ask the platform for the signed-in customer's access, again if it was read before. */
+    /** Ask the platform for the signed-in user's access, again if it was read before. */
     loadAccess(): Promise<void>;
     /** The same, unless a read is already under way: then that one is awaited. */
     ensureAccess(): Promise<void>;
@@ -27,22 +27,22 @@ export interface FoirContextValue {
     signIn(vars: {
         email: string;
         password: string;
-    }): Promise<FoirCustomer>;
+    }): Promise<FoirUser>;
     register(vars: {
         email: string;
         password: string;
-    }): Promise<FoirCustomer>;
+    }): Promise<FoirUser>;
     requestOtp(email: string): Promise<boolean>;
     signInWithOtp(vars: {
         email: string;
         otp: string;
-    }): Promise<FoirCustomer>;
+    }): Promise<FoirUser>;
     /** Start a provider (OAuth/OIDC) login. Redirect providers navigate away. */
     signInWithProvider(providerKey: string, opts?: Omit<ProviderLoginInput, 'providerKey'>): Promise<void>;
     /** Complete a provider login from your callback route (code + state). */
     completeProviderLogin(input: Omit<ProviderCallbackInput, 'providerKey'> & {
         providerKey: string;
-    }): Promise<FoirCustomer>;
+    }): Promise<FoirUser>;
     signOut(): Promise<void>;
     /** Rotate the access token; returns false (and signs out) if it can't. */
     refresh(): Promise<boolean>;
@@ -78,8 +78,8 @@ export interface FoirProviderProps {
     children: ReactNode;
 }
 /**
- * Provides Foir customer auth to a React tree. Hydrates the session on mount,
- * then exposes the current customer and sign-in/out actions through
+ * Provides Foir user auth to a React tree. Hydrates the session on mount,
+ * then exposes the current user and sign-in/out actions through
  * {@link useFoirSession}, {@link useFoirUser}, and {@link useFoirAuth}.
  *
  * Two session models:
@@ -93,14 +93,14 @@ export declare function FoirProvider({ env, adapter, hostedSession, children, }:
 /** The current session state. */
 export interface FoirSession {
     status: FoirStatus;
-    customer: FoirCustomer | null;
+    user: FoirUser | null;
     isLoading: boolean;
     isAuthenticated: boolean;
 }
-/** Read the current session status and customer. */
+/** Read the current session status and user. */
 export declare function useFoirSession(): FoirSession;
-/** The signed-in customer (`{ id, email }`), or null. */
-export declare function useFoirUser(): FoirCustomer | null;
+/** The signed-in user (`{ id, email }`), or null. */
+export declare function useFoirUser(): FoirUser | null;
 /** What {@link useFoirAccess} returns. */
 export interface FoirAccessState {
     /**
@@ -110,17 +110,17 @@ export interface FoirAccessState {
      */
     status: 'loading' | 'ready' | 'unavailable';
     isLoading: boolean;
-    /** The signed-in customer's access, or null: signed out, loading or unavailable. */
+    /** The signed-in user's access, or null: signed out, loading or unavailable. */
     access: FoirAccess | null;
-    /** Whether the customer holds the role with this key. False until known. */
+    /** Whether the user holds the role with this key. False until known. */
     hasRole(key: string): boolean;
-    /** Whether the customer's scopes cover this one. False until known. */
+    /** Whether the user's scopes cover this one. False until known. */
     hasScope(scope: string): boolean;
     /** Ask the platform again, for a role given or taken away since. */
     reload(): Promise<void>;
 }
 /**
- * The roles the signed-in customer holds and the scopes they resolve to, as the
+ * The roles the signed-in user holds and the scopes they resolve to, as the
  * platform resolved them. Read on first use, again when the session refreshes,
  * and whenever `reload` is called.
  *
@@ -133,20 +133,20 @@ export declare function useFoirAuth(): {
     signIn: (vars: {
         email: string;
         password: string;
-    }) => Promise<FoirCustomer>;
+    }) => Promise<FoirUser>;
     register: (vars: {
         email: string;
         password: string;
-    }) => Promise<FoirCustomer>;
+    }) => Promise<FoirUser>;
     requestOtp: (email: string) => Promise<boolean>;
     signInWithOtp: (vars: {
         email: string;
         otp: string;
-    }) => Promise<FoirCustomer>;
+    }) => Promise<FoirUser>;
     signInWithProvider: (providerKey: string, opts?: Omit<ProviderLoginInput, "providerKey">) => Promise<void>;
     completeProviderLogin: (input: Omit<ProviderCallbackInput, "providerKey"> & {
         providerKey: string;
-    }) => Promise<FoirCustomer>;
+    }) => Promise<FoirUser>;
     signOut: () => Promise<void>;
     refresh: () => Promise<boolean>;
     getToken: () => Promise<string | null>;

package/dist/react/SignIn.d.ts

@@ -1,4 +1,4 @@
-import type { FoirCustomer } from '../auth';
+import type { FoirUser } from '../auth';
 export interface SignInProps {
     /** `password` (default) or `otp` (email one-time code). Ignored when `hostedUrl` is set. */
     method?: 'password' | 'otp';
@@ -8,12 +8,12 @@ export interface SignInProps {
     oauth?: boolean;
     /** Navigate here after a successful sign-in. */
     afterSignInUrl?: string;
-    /** Called with the customer on a successful sign-in (before any redirect). */
-    onSignIn?(customer: FoirCustomer): void;
+    /** Called with the user on a successful sign-in (before any redirect). */
+    onSignIn?(user: FoirUser): void;
     className?: string;
 }
 /**
- * A drop-in customer sign-in. Renders an email/password (or OTP) form and,
+ * A drop-in user sign-in. Renders an email/password (or OTP) form and,
  * unless disabled, OAuth provider buttons. Set `hostedUrl` to instead render a
  * button that redirects to a hosted login page. All state is handled through
  * {@link FoirProvider}; on success it calls `onSignIn` and optionally navigates

package/dist/react/UserButton.d.ts

@@ -6,7 +6,7 @@ export interface UserButtonProps {
     className?: string;
 }
 /**
- * A minimal signed-in affordance: the customer's email plus a sign-out button.
+ * A minimal signed-in affordance: the user's email plus a sign-out button.
  * Renders nothing when signed out. Style it via `className` (the default is an
  * unopinionated inline layout).
  */

package/dist/react/feedback-notes.d.ts

@@ -7,7 +7,7 @@
  * shape (see `data/selection.ts`) — so every response here has to be read rather
  * than cast, and reading is the part worth testing on its own.
  */
-import type { FoirCustomerNote, FoirNoteConfig, FoirSubject } from '../data';
+import type { FoirUserNote, FoirNoteConfig, FoirSubject } from '../data';
 import type { FoirScreenCapture } from '../media/screen-capture';
 /**
  * The client the widget needs, and no more of it.
@@ -44,9 +44,9 @@ export interface FoirFeedbackClient {
  * widget can name.
  *
  * The distinction earns its place because the three have different audiences.
- * `signIn` is the visitor's to fix. `scope` is the OPERATOR's — a role that does
+ * `signIn` is the visitor's to fix. `scope` is the PROJECT's: a role that does
  * not grant `notes:create` produces `missing required scope: notes:create`, which
- * reads like a bad API key and is not one; the key is fine and the customer's
+ * reads like a bad API key and is not one; the key is fine and the user's
  * role is short a capability. `other` is everything the widget will not pretend
  * to understand.
  */
@@ -98,4 +98,4 @@ export interface FoirFeedbackSubmission {
  * worse than one that did not arrive: they have no way to tell, and the thing
  * they wrote ("as you can see in the screenshot") stops making sense.
  */
-export declare function submitFeedbackNote(client: FoirFeedbackClient, submission: FoirFeedbackSubmission): Promise<FoirCustomerNote>;
+export declare function submitFeedbackNote(client: FoirFeedbackClient, submission: FoirFeedbackSubmission): Promise<FoirUserNote>;

package/dist/react/index.d.ts

@@ -1,8 +1,8 @@
 /**
- * `@foir/sdk/react` — drop-in React components for Foir customers.
+ * `@foir/sdk/react` — drop-in React components for Foir users.
  *
  * Wrap your app in `<FoirProvider>`, then read the session with
- * `useFoirSession` / `useFoirUser`, ask what the customer may see with
+ * `useFoirSession` / `useFoirUser`, ask what the user may see with
  * `useFoirAccess`, and drive it with `useFoirAuth` — or drop in
  * the `<SignIn>`, `<OAuthButtons>`, and `<UserButton>` components. Built entirely
  * on `@foir/sdk/auth`; `react` is the only peer dependency.
@@ -22,5 +22,5 @@ export type { UserButtonProps } from './UserButton';
 export { FoirFeedback } from './FoirFeedback';
 export type { FoirFeedbackProps, FoirFeedbackClient } from './FoirFeedback';
 export { createLocalStorageAdapter } from './localStorageAdapter';
-export type { FoirAccess, FoirCustomer, SessionAdapter, AuthProviderPublic } from '../auth';
+export type { FoirAccess, FoirUser, SessionAdapter, AuthProviderPublic } from '../auth';
 export type { FoirEnv } from '../graphql/foir-request';