@foir/sdk 0.20.0 → 0.22.0

package/dist/transport/foir-http.d.ts

@@ -11,7 +11,7 @@
  *
  * The split exists so the second one is possible. The Foir-specific transport
  * concerns — which api key is in play, the preview schema channel header, the
- * optional customer bearer, and the `FoirRequestError` shape — are identical on
+ * optional user bearer, and the `FoirRequestError` shape — are identical on
  * both, and duplicating them is exactly how the two surfaces would drift. So
  * they live here once and `foir-request.ts` re-exports them unchanged; the only
  * thing that stayed behind is the part that needs `print`.
@@ -206,8 +206,8 @@ export declare function readFoirRateLimit(headers: Headers): FoirRateLimitSnapsh
 export declare function readFoirRetryAfterMs(headers: Headers): number | undefined;
 export interface FoirRequestOptions {
     /**
-     * Customer bearer token. api-public still needs the `x-api-key` to resolve
-     * the project; the bearer adds the customer identity for self-scoped reads
+     * User bearer token. api-public still needs the `x-api-key` to resolve
+     * the project; the bearer adds the user identity for self-scoped reads
      * (e.g. `myProfile`). Used by `@foir/sdk/auth`'s post-login profile fetch.
      */
     bearerToken?: string;
@@ -256,7 +256,7 @@ export interface FoirRequestOptions {
     onRateLimit?: (snapshot: FoirRateLimitSnapshot | undefined) => void;
 }
 /**
- * Supplies the current customer bearer. Sync or async so consumers can read a
+ * Supplies the current user bearer. Sync or async so consumers can read a
  * cookie session (Hydrogen/Remix), a KV store, an in-memory value, etc. Returns
  * the token when signed in, or `null`/`undefined` when signed out.
  *
@@ -265,7 +265,7 @@ export interface FoirRequestOptions {
  * they would end up accepting subtly different things.
  */
 export type FoirTokenProvider = () => string | null | undefined | Promise<string | null | undefined>;
-/** A request made with an api key, optionally for a signed-in customer. */
+/** A request made with an api key, optionally for a signed-in user. */
 export interface FoirKeyHeaderInput {
     apiKey: string;
     /**
@@ -273,8 +273,8 @@ export interface FoirKeyHeaderInput {
      * freshly pushed model changes (new fields, new models) are visible at
      * runtime — otherwise selections on draft-only fields are silently stripped
      * and surface as confusing "fragment never used" errors. The header has no
-     * effect under public keys (the server ignores it), so it is safe to send
-     * whenever the caller is in preview.
+     * effect under an app's key without `drafts:read` (the server ignores it),
+     * so it is safe to send whenever the caller is in preview.
      */
     draftChannel?: boolean;
     bearerToken?: string;
@@ -305,7 +305,7 @@ export interface FoirKeyHeaderInput {
  *
  * The token is the whole credential. api-public takes the scoped path when
  * `X-Foir-Token` is present and never reads `x-api-key` on it, and the
- * organization, the customer and the schema channel all come from the token's
+ * organization, the user and the schema channel all come from the token's
  * own claims, so none of the key-side inputs has anything to say here.
  */
 export interface FoirDispatchHeaderInput {
@@ -337,14 +337,34 @@ export declare function refuseCredentialHeaders(extra: Readonly<Record<string, s
  * authorization difference nobody would notice until it mattered.
  *
  * Two credentials, and a request carries exactly one: an api key (with its
- * optional customer bearer, organization and channel), or an operation's
+ * optional user bearer, organization and channel), or an operation's
  * dispatch token. A dispatch request never writes `x-api-key`.
  */
 /** The header a server names the visitor it calls for in. */
 export declare const FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
 /**
- * The address of the visitor a server rendering pages is calling for, or a
- * function that resolves it for each request.
+ * The visitor a server rendering pages is calling for: who they are to the
+ * per-visitor limits, and where they are to location targeting.
+ *
+ * Each part is what your host says of the visitor, and each is optional. A
+ * part left out is not said: with no address the request counts as your
+ * server's own, and with no country and no coordinates the visitor is one
+ * nobody could place. Where your server is never stands in for where the
+ * visitor is.
+ */
+export interface FoirVisitor {
+    /** The visitor's address, sent as `X-Foir-Visitor-IP`. */
+    address?: string | null;
+    /** The visitor's country, as an ISO 3166-1 alpha-2 code such as `GB`. */
+    country?: string | null;
+    /** The visitor's latitude, in decimal degrees. Sent with `longitude`, or not at all. */
+    latitude?: number | null;
+    /** The visitor's longitude, in decimal degrees. Sent with `latitude`, or not at all. */
+    longitude?: number | null;
+}
+/**
+ * The visitor a server rendering pages is calling for, or a function that
+ * resolves them for each request. A string is the visitor's address alone.
  *
  * The SDK does not read it off a request, because which request header holds
  * the visitor's real address, and whether a visitor can forge it, depends on
@@ -352,7 +372,26 @@ export declare const FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
  * strips; that value, and only that, belongs here. A function that yields
  * nothing sends nothing, and the API counts the request as your server's own.
  */
-export type FoirVisitorSource = string | (() => string | null | undefined | Promise<string | null | undefined>);
+export type FoirVisitorSource = string | FoirVisitor | (() => string | FoirVisitor | null | undefined | Promise<string | FoirVisitor | null | undefined>);
+/** Where a stated visitor is, as a read's `contexts` carries it. */
+export interface FoirVisitorPlace {
+    country?: string;
+    location?: {
+        latitude: number;
+        longitude: number;
+    };
+}
+/** One request's visitor, resolved: the address for the header, and the place for the read. */
+export interface FoirResolvedVisitor {
+    address?: string;
+    place: FoirVisitorPlace;
+}
+/**
+ * Resolve a `visitor` for one request. The provider is called here, once, and
+ * what it yields is used for the header and for the read alike, so the two
+ * never describe different visitors.
+ */
+export declare function resolveFoirVisitor(source: FoirVisitorSource | undefined): Promise<FoirResolvedVisitor>;
 export declare function buildFoirHeaders(input: FoirHeaderInput): Record<string, string>;
 /**
  * Build a `/v1/...` URL from whatever the caller put in `apiUrl`.
@@ -373,7 +412,7 @@ export declare function foirApiEndpoint(apiUrl: string, path: `/${string}`): str
 /**
  * Foir DISCARDED a credential you sent, and served the request without it.
  *
- * A customer JWT is optional: if it fails to verify, the read is served as an
+ * A user JWT is optional: if it fails to verify, the read is served as an
  * ordinary anonymous one rather than refused, because plenty of reads
  * legitimately have nobody signed in. That is the right behaviour and it has a
  * sharp edge — a lapsed token and a genuinely anonymous request produce the
@@ -385,9 +424,9 @@ export declare function foirApiEndpoint(apiUrl: string, path: `/${string}`): str
  */
 export interface FoirAuthDowngrade {
     /** Always `"rejected"`. */
-    customerToken: string;
+    userToken: string;
     /**
-     * `expired` — re-exchange and retry. `invalid` — not a customer token for
+     * `expired` — re-exchange and retry. `invalid` — not a user token for
      * this environment. `wrong_project` — the token and the api-key name
      * different projects.
      */
@@ -396,7 +435,7 @@ export interface FoirAuthDowngrade {
     servedAs: string;
 }
 /**
- * A request that sent a customer token was served without it.
+ * A request that sent a user token was served without it.
  *
  * Thrown only to a caller that asked (`rejectDowngrade`): one that sent the
  * token because it wants the signed-in answer, and would otherwise be handed the
@@ -409,9 +448,9 @@ export declare class FoirAuthDowngradedError extends FoirRequestError {
     constructor(downgrade: FoirAuthDowngrade);
 }
 /**
- * The customer's session is over: its token was rejected and could not be
+ * The user's session is over: its token was rejected and could not be
  * refreshed. It is what a signed-in request gets in place of the anonymous
- * answer. Send the customer to sign in again.
+ * answer. Send the user to sign in again.
  */
 export declare class FoirSessionExpiredError extends FoirRequestError {
     constructor(options?: {

package/dist/transport/key-kind.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The kind a key says it is, by its prefix.
+ *
+ * A key is one of three kinds, chosen by whoever made it. A publishable key
+ * sits in a page or an app. A server key is held by the server that renders an
+ * app's pages. An admin key is a machine's own: a sync job, a pipeline, a tool.
+ * A key says its kind in its first letters, so this is decided without a
+ * request.
+ *
+ * A key minted before a key had a kind says an older type. A `pk_` key is a
+ * publishable key. An `sk_` or a `tc_` key says only that it is not public:
+ * the platform holds it as an admin key, and it is reported here as `older`,
+ * so that a caller who refuses an admin key by name does not refuse a key
+ * whose holder has not yet been able to mint a server key in its place.
+ */
+export type FoirKeyKind = 'publishable' | 'server' | 'admin';
+/** What a key's prefix says of it: its kind, or that it is an older secret. */
+export type FoirKeyPrefixKind = FoirKeyKind | 'older';
+/** Where each credential is for, and which key an app holds. */
+export declare const FOIR_CREDENTIALS_DOC = "https://docs.foir.dev/credentials";
+/**
+ * What a key says of itself by its prefix, or `undefined` for a string that
+ * is no key Fóir made.
+ */
+export declare function foirKeyKind(apiKey: string | null | undefined): FoirKeyPrefixKind | undefined;
+/**
+ * What an app's client says when it is handed an admin key, naming the client
+ * it was handed to. An admin key is a machine's own, so every client an app
+ * builds refuses one before any request, in the same words.
+ *
+ * Only a key that says it is an admin key by its prefix is refused. A key
+ * minted before a key had a kind does not say, and is let through.
+ */
+export declare function adminKeyRefusal(client: string): string;
+/**
+ * Whether a key may be named in a URL. Only a publishable key may: it ships in
+ * the page and is served to every visitor, so naming it discloses nothing. Any
+ * other key would land in access logs, referrer headers and browser history.
+ */
+export declare function isPublishableFoirKey(apiKey: string | null | undefined): boolean;

package/dist/types/index.d.ts

@@ -21,7 +21,7 @@ export interface EditorInit {
     apiUrl: string;
     /** Config connection domain (e.g. my-store.myshopify.com) */
     connectionDomain?: string;
-    /** How this editor is rendered in the admin UI. */
+    /** How this editor is rendered in the console. */
     configMode?: 'editor' | 'sidebar';
     /** Currently selected field keys (sidebar mode). */
     selectedFieldKeys?: string[];
@@ -67,7 +67,7 @@ export interface EditorContextValue {
     resize: (height: number) => void;
     /** Report dirty state (unsaved changes). */
     setDirty: (isDirty: boolean) => void;
-    /** Request the host to navigate to an admin path. */
+    /** Request the host to navigate to a console path. */
     requestNavigate: (path: string) => void;
     /** Request the host to execute a platform operation. Returns the result.
      * `mode` controls whether the platform waits for the operation to complete

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {
@@ -177,8 +177,8 @@
     "ws": "^8.18.0",
     "y-websocket": "^3.0.0",
     "yjs": "^13.6.30",
-    "@foir/access-vocab": "0.0.0",
-    "@foir/proto-ts": "0.109.0"
+    "@foir/proto-ts": "0.109.0",
+    "@foir/access-vocab": "0.0.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/dist/server/older-claims.generated.d.ts

@@ -1,8 +0,0 @@
-/** Stands, below, where a capability or a grant names a model. */
-export declare const OLDER_CLAIM_TARGET = "{target}";
-/**
- * What each capability a token said before it said its grants was worth, as
- * the platform reads one. A capability that was worth nothing is worth nothing
- * here.
- */
-export declare const OLDER_CAPABILITY_GRANTS: Readonly<Record<string, readonly string[]>>;