@foir/sdk 0.10.0 → 0.12.0

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

@@ -30,16 +30,17 @@ export interface FoirEnv {
  * Returns true when `FOIR_PREVIEW=true` is set in the environment.
  *
  * Preview is selected at the environment level, not per-request: load a
- * preview env file that sets `FOIR_PREVIEW=true` + a `sk_…`
- * `PLATFORM_PREVIEW_API_KEY` with `drafts:read` instead of the default env.
+ * preview env file that sets `FOIR_PREVIEW=true` + the preview environment's
+ * own `pk_…` key holding `drafts:read` as `PLATFORM_PREVIEW_API_KEY`, instead
+ * of the default env.
  * The site-wide mode keeps draft semantics consistent — every loader sees
  * the same preview/published view of the world. Intended for non-production
  * surfaces only.
  */
 export declare function isFoirPreview(env: FoirEnv): boolean;
 /**
- * The api key a request should carry for this env: the `sk_` preview key when
- * `FOIR_PREVIEW=true` (it is the one with `drafts:read`), the `pk_` key
+ * The api key a request should carry for this env: the preview key when
+ * `FOIR_PREVIEW=true` (it is the one with `drafts:read`), the production key
  * otherwise. Returns `undefined` when neither is configured, so the caller can
  * raise the "add them to .env" error with its own wording.
  */
@@ -210,6 +211,12 @@ export interface FoirRequestOptions {
      * (e.g. `myProfile`). Used by `@foir/sdk/auth`'s post-login profile fetch.
      */
     bearerToken?: string;
+    /**
+     * Refuse an answer served without the bearer this request sent: throw
+     * {@link FoirAuthDowngradedError} instead of returning the anonymous data.
+     * `authedRequest` sets it, so it can refresh and ask again.
+     */
+    rejectDowngrade?: boolean;
     /**
      * The organization this request acts in, sent as `X-Org-Id`. For a
      * project-scoped key: the server resolves it to an active organization of
@@ -230,6 +237,12 @@ export interface FoirRequestOptions {
      * covers what the request is about.
      */
     orgId?: string;
+    /**
+     * The organization this request acts in, named by the address of the page it
+     * is for, sent as `X-Org-Url`. See `FoirClientConfig.orgUrl` for the full
+     * contract. With `orgId` as well, the two must name the same organization.
+     */
+    orgUrl?: string;
     /**
      * Called with the `X-RateLimit-*` headers of every response, successful or
      * not, and with `undefined` when a response carried none.
@@ -252,7 +265,8 @@ export interface FoirRequestOptions {
  * they would end up accepting subtly different things.
  */
 export type FoirTokenProvider = () => string | null | undefined | Promise<string | null | undefined>;
-export interface FoirHeaderInput {
+/** A request made with an api key, optionally for a signed-in customer. */
+export interface FoirKeyHeaderInput {
     apiKey: string;
     /**
      * Opt into the draft *schema* channel (`X-Foir-Schema-Channel: draft`) so
@@ -270,15 +284,75 @@ export interface FoirHeaderInput {
      * spells the header in `extra` still wins, because `extra` is applied last.
      */
     orgId?: string;
+    /**
+     * The organization the request acts in, named by a page URL (`X-Org-Url`).
+     * Set from `FoirClientConfig.orgUrl` / `FoirRequestOptions.orgUrl`.
+     */
+    orgUrl?: string;
+    /**
+     * The address of the visitor a server rendering pages is calling for
+     * (`X-Foir-Visitor-IP`). Set from `FoirClientConfig.visitor`.
+     */
+    visitorAddress?: string;
+    dispatchToken?: never;
+    dispatchContext?: never;
     /** Caller-supplied extras, applied last so a caller can override. */
     extra?: Readonly<Record<string, string>>;
 }
+/**
+ * A request made AS an operation, with the dispatch token its endpoint was
+ * handed.
+ *
+ * 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
+ * own claims, so none of the key-side inputs has anything to say here.
+ */
+export interface FoirDispatchHeaderInput {
+    /** Sent as `X-Foir-Token`. */
+    dispatchToken: string;
+    /** The dispatch's `X-Foir-Context`, forwarded as it arrived. */
+    dispatchContext?: string;
+    apiKey?: never;
+    draftChannel?: never;
+    bearerToken?: never;
+    orgId?: never;
+    orgUrl?: never;
+    /**
+     * Caller-supplied extras, applied last. They may not name a credential
+     * header: see {@link refuseCredentialHeaders}.
+     */
+    extra?: Readonly<Record<string, string>>;
+}
+export type FoirHeaderInput = FoirKeyHeaderInput | FoirDispatchHeaderInput;
+/**
+ * Refuse extra headers that would add a second credential to a request made as
+ * an operation. Throws naming the header; returns nothing when there is none.
+ */
+export declare function refuseCredentialHeaders(extra: Readonly<Record<string, string>> | undefined): void;
 /**
  * The exact header set every Foir data-plane request carries. Single
  * definition on purpose: `/graphql` and `/cdn/graphql` authenticate identically,
  * and a header that exists on one surface but not the other is a per-surface
  * 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
+ * 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 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
+ * what sits in front of your server. Your host says which one its edge sets and
+ * 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 declare function buildFoirHeaders(input: FoirHeaderInput): Record<string, string>;
 /**
  * Build a `/v1/...` URL from whatever the caller put in `apiUrl`.
@@ -321,6 +395,29 @@ export interface FoirAuthDowngrade {
     /** The authority the request actually ran under. */
     servedAs: string;
 }
+/**
+ * A request that sent a customer 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
+ * anonymous one as though nothing had happened. `downgrade.reason` says whether
+ * refreshing could help: `expired` can be refreshed, `invalid` and
+ * `wrong_project` cannot.
+ */
+export declare class FoirAuthDowngradedError extends FoirRequestError {
+    readonly downgrade: FoirAuthDowngrade;
+    constructor(downgrade: FoirAuthDowngrade);
+}
+/**
+ * The customer'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.
+ */
+export declare class FoirSessionExpiredError extends FoirRequestError {
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
 export interface FoirResponseEnvelope<T> {
     data?: T;
     errors?: Array<FoirGraphQLErrorItem>;
@@ -334,4 +431,5 @@ export interface FoirResponseEnvelope<T> {
 }
 export declare function readFoirEnvelope<T>(json: FoirResponseEnvelope<T>, options?: {
     strict?: boolean;
+    rejectDowngrade?: boolean;
 }): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {
@@ -45,6 +45,18 @@
       "types": "./dist/auth/index.d.ts",
       "import": "./dist/auth.js"
     },
+    "./placement": {
+      "types": "./dist/placement/index.d.ts",
+      "import": "./dist/placement.js"
+    },
+    "./app": {
+      "types": "./dist/app/index.d.ts",
+      "import": "./dist/app.js"
+    },
+    "./app/contract": {
+      "types": "./dist/app/contract/index.d.ts",
+      "import": "./dist/app-contract.js"
+    },
     "./auth/session": {
       "types": "./dist/auth/session-client.d.ts",
       "import": "./dist/auth-session.js"
@@ -107,6 +119,7 @@
     "@graphql-typed-document-node/core": "3.2.0"
   },
   "peerDependencies": {
+    "@bufbuild/protobuf": "^2.12.0",
     "@graphql-codegen/cli": "^5.0.0",
     "@graphql-codegen/client-preset": "^4.0.0",
     "blurhash": "^2.0.0",
@@ -117,6 +130,9 @@
     "yjs": "^13.6.0"
   },
   "peerDependenciesMeta": {
+    "@bufbuild/protobuf": {
+      "optional": true
+    },
     "@graphql-codegen/cli": {
       "optional": true
     },
@@ -143,6 +159,7 @@
     }
   },
   "devDependencies": {
+    "@bufbuild/protobuf": "^2.0.0",
     "@graphql-codegen/cli": "^5.0.7",
     "@testing-library/react": "^16.2.0",
     "@types/react": "^19.2.0",
@@ -159,18 +176,19 @@
     "vitest": "^3.2.4",
     "ws": "^8.18.0",
     "y-websocket": "^3.0.0",
-    "yjs": "^13.6.30"
+    "yjs": "^13.6.30",
+    "@foir/proto-ts": "0.109.0"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "node scripts/clean-dist.mjs && tsup && tsc -p tsconfig.build.json && node scripts/assert-export-types.mjs && node scripts/assert-public-exports.mjs",
+    "build": "node scripts/generate-app-vocabulary.mjs && node scripts/clean-dist.mjs && tsup && tsc -p tsconfig.build.json && node scripts/bundle-app-contract-types.mjs && node scripts/assert-export-types.mjs && node scripts/assert-public-exports.mjs",
     "snapshot:exports": "node scripts/assert-public-exports.mjs --update",
     "dev": "node scripts/dev-watch.mjs",
-    "check-types": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest watch",
+    "check-types": "node scripts/generate-app-vocabulary.mjs && tsc --noEmit",
+    "test": "node scripts/generate-app-vocabulary.mjs && vitest run",
+    "test:watch": "node scripts/generate-app-vocabulary.mjs && vitest watch",
     "release:patch": "pnpm version patch",
     "release:minor": "pnpm version minor",
     "release:major": "pnpm version major"