@foir/sdk 0.8.0 → 0.10.0

package/dist/auth.js

@@ -11,11 +11,30 @@ function isFoirPreview(env) {
 function resolveFoirApiKey(env) {
   return isFoirPreview(env) ? env.PLATFORM_PREVIEW_API_KEY ?? env.PLATFORM_API_KEY : env.PLATFORM_API_KEY;
 }
+var MALFORMED_PRUNE_REASONS = /* @__PURE__ */ new Set([
+  "unknown_field",
+  "subselections_on_scalar",
+  "missing_subselections"
+]);
 var FoirRequestError = class extends Error {
   /** HTTP status code, when the request failed at the HTTP layer. */
   status;
   /** GraphQL errors, when the request failed with a no-data error envelope. */
   graphQLErrors;
+  /**
+   * The `data` the server did return, when a STRICT read refused a partial
+   * response. Present only on that path: without it, opting into strictness
+   * would trade a silent wrong answer for a thrown one that discards the answer,
+   * and a caller that wants to log what it nearly rendered could not.
+   */
+  partialData;
+  /**
+   * The selections the server stripped, when the refusal was a pruned document
+   * rather than a partial error. Same purpose as `partialData`: a caller that
+   * wants to log what it nearly rendered, or name the offending path in a
+   * developer-facing message, has it without re-parsing anything.
+   */
+  prunedSelections;
   cause;
   constructor(message, options) {
     super(message);
@@ -23,6 +42,8 @@ var FoirRequestError = class extends Error {
     this.cause = options?.cause;
     this.status = options?.status;
     this.graphQLErrors = options?.graphQLErrors;
+    this.partialData = options?.partialData;
+    this.prunedSelections = options?.prunedSelections;
   }
   /**
    * The code of the first error, if the response carried one.
@@ -93,6 +114,9 @@ function buildFoirHeaders(input) {
   if (input.bearerToken) {
     headers["Authorization"] = `Bearer ${input.bearerToken}`;
   }
+  if (input.orgId) {
+    headers["X-Org-Id"] = input.orgId;
+  }
   if (input.extra) {
     for (const [key, value] of Object.entries(input.extra)) {
       headers[key] = value;
@@ -107,14 +131,45 @@ function foirApiEndpoint(apiUrl, path) {
   }
   return base + path;
 }
-function readFoirEnvelope(json) {
+var warnedDowngrade = null;
+function reportAuthDowngrade(envelope) {
+  const downgrade = envelope.extensions?.auth;
+  if (!downgrade) {
+    warnedDowngrade = null;
+    return;
+  }
+  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.")
+  );
+}
+function refusePrunedDocument(json, options) {
+  const selections = json.extensions?.pruned?.selections;
+  if (!selections?.length) return;
+  const describe = (s) => `${s.path}${s.type ? ` on ${s.type}` : ""} (${s.reason})`;
+  const malformed = selections.filter((s) => MALFORMED_PRUNE_REASONS.has(s.reason));
+  if (malformed.length && options?.strict !== false) {
+    throw new FoirRequestError(
+      `[foir] the server could not serve part of this query and returned the rest without it: ${malformed.map(describe).join(", ")}. Those selections do not exist on the schema this project is serving. Pass strict: false to get the partial answer instead of this error.`,
+      { prunedSelections: selections }
+    );
+  }
+  console.warn(
+    `[foir] selections stripped from this query: ${selections.map(describe).join(", ")}`
+  );
+}
+function readFoirEnvelope(json, options) {
+  reportAuthDowngrade(json);
+  refusePrunedDocument(json, options);
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
-    if (json.data) {
+    if (json.data && !options?.strict) {
       console.warn(`[foir] GraphQL partial errors (data returned): ${msg}`);
     } else {
       throw new FoirRequestError(`[foir] GraphQL errors: ${msg}`, {
-        graphQLErrors: json.errors
+        graphQLErrors: json.errors,
+        partialData: json.data ?? void 0
       });
     }
   }
@@ -155,8 +210,9 @@ async function hasFoirErrorCode(res, ...codes) {
 }
 
 // src/graphql/cdn-route.ts
-function isCdnEligible(env, documentText, bearerToken) {
+function isCdnEligible(env, documentText, bearerToken, orgId) {
   if (bearerToken) return false;
+  if (orgId) return false;
   if (isFoirPreview(env)) return false;
   const apiKey = resolveFoirApiKey(env);
   if (!apiKey?.startsWith("pk_")) return false;
@@ -175,12 +231,13 @@ async function foirRequest(env, document, variables, options) {
   const headers = buildFoirHeaders({
     apiKey,
     draftChannel: isFoirPreview(env),
-    bearerToken: options?.bearerToken
+    bearerToken: options?.bearerToken,
+    orgId: options?.orgId
   });
   const documentText = print2(document);
   let res;
   try {
-    if (isCdnEligible(env, documentText, options?.bearerToken)) {
+    if (isCdnEligible(env, documentText, options?.bearerToken, options?.orgId)) {
       const hash = await documentHash(documentText);
       let shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
         method: "GET",
@@ -739,7 +796,9 @@ async function resolveBearerToken(config) {
 function foirRoute(input) {
   if (!input.apiKey.startsWith("pk_")) return { lane: "origin", reason: "key" };
   if (input.bearerToken) return { lane: "origin", reason: "bearer" };
+  if (input.orgId) return { lane: "origin", reason: "org" };
   if (input.mutation) return { lane: "origin", reason: "operation" };
+  if (input.writeToken) return { lane: "origin", reason: "floor" };
   if (input.channel === "draft") return { lane: "origin", reason: "channel" };
   return { lane: "shared" };
 }
@@ -752,7 +811,7 @@ async function executeFoirDocument(config, plan) {
   }
   return data[plan.rootField];
 }
-async function runFoirDocument(config, document, mutation, variables) {
+async function runFoirDocument(config, document, mutation, variables, options) {
   const doFetch = config.fetch ?? globalThis.fetch;
   const endpoint = foirDataEndpoint(config.apiUrl, "/graphql");
   const bearerToken = await resolveBearerToken(config);
@@ -760,12 +819,14 @@ async function runFoirDocument(config, document, mutation, variables) {
     apiKey: config.apiKey,
     draftChannel: config.channel === "draft",
     bearerToken,
+    orgId: config.orgId,
     extra: config.headers
   });
   const hash = await documentHash(document);
   const route = foirRoute({
     apiKey: config.apiKey,
     bearerToken,
+    orgId: config.orgId,
     mutation,
     channel: config.channel
   });
@@ -805,7 +866,7 @@ async function runFoirDocument(config, document, mutation, variables) {
     });
   }
   const json = await res.json();
-  return readFoirEnvelope(json);
+  return readFoirEnvelope(json, options);
 }
 async function readErrorBody(res) {
   try {
@@ -828,6 +889,7 @@ async function fetchFoirManifest(config) {
         apiKey: config.apiKey,
         draftChannel: config.channel === "draft",
         bearerToken: await resolveBearerToken(config),
+        orgId: config.orgId,
         extra: config.headers
       }),
       ...config.requestInit
@@ -869,6 +931,16 @@ var AUTH_OPS = {
   customerUpdatePassword: "customerUpdatePassword",
   customerVerifyEmail: "customerVerifyEmail",
   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.
+  myOrganizations: "myOrganizations",
+  selectMyOrganization: "selectMyOrganization",
+  // Founding one. Present in a manifest only when the project opted in.
+  registerOperatorOrganization: "registerOperatorOrganization",
   // External identity providers.
   customerLoginWithProvider: "customerLoginWithProvider",
   customerProviderCallback: "customerProviderCallback",
@@ -890,6 +962,7 @@ function authClientConfig(env, options) {
     apiKey,
     channel: isFoirPreview(env) ? "draft" : "published",
     bearerToken: options?.bearerToken,
+    orgId: options?.orgId,
     headers: options?.headers,
     fetch: options?.fetch
   };
@@ -998,6 +1071,15 @@ async function customerLogout(env, options) {
 async function deleteMyAccount(env, vars, options) {
   return authOp(env, AUTH_OPS.deleteMyAccount, vars, options);
 }
+async function myOrganizations(env, vars, options) {
+  return authOp(env, AUTH_OPS.myOrganizations, vars ?? {}, options);
+}
+async function selectOrganization(env, vars, options) {
+  return authOp(env, AUTH_OPS.selectMyOrganization, vars, options);
+}
+async function registerOrganization(env, vars, options) {
+  return authOp(env, AUTH_OPS.registerOperatorOrganization, vars, options);
+}
 async function saveSession(adapter, result) {
   await adapter.set(TOKEN_KEY, result.token);
   await adapter.set(REFRESH_KEY, result.refreshToken);
@@ -1111,6 +1193,7 @@ async function requireAdmin(adapter, options) {
 // src/auth/hosted.ts
 var DEFAULT_COOKIE_NAME = "foir_customer_session";
 var DEFAULT_SESSION_PATH = "/session/token";
+var DEFAULT_END_SESSION_PATH = "/session/end-session";
 function hostedLoginUrl(config, returnTo) {
   const dest = new URL(config.loginOrigin);
   if (returnTo && returnTo !== "/") {
@@ -1118,6 +1201,15 @@ function hostedLoginUrl(config, returnTo) {
   }
   return dest.toString();
 }
+function hostedLogoutUrl(config, clientId, returnTo) {
+  const path = config.endSessionPath ?? DEFAULT_END_SESSION_PATH;
+  const dest = new URL(path, config.loginOrigin);
+  dest.searchParams.set("client_id", clientId);
+  if (returnTo) {
+    dest.searchParams.set("post_logout_redirect_uri", returnTo);
+  }
+  return dest.toString();
+}
 async function fetchHostedSession(request, config) {
   const cookieName = config.cookieName ?? DEFAULT_COOKIE_NAME;
   const sessionPath = config.sessionPath ?? DEFAULT_SESSION_PATH;
@@ -1125,25 +1217,48 @@ async function fetchHostedSession(request, config) {
   const match = cookie.match(
     new RegExp(`(?:^|;\\s*)${escapeRegExp(cookieName)}=([^;]+)`)
   );
-  if (!match) return null;
+  if (!match) return { outcome: "signed-out", reason: "no-cookie" };
+  let res;
   try {
-    const res = await fetch(`${config.loginOrigin}${sessionPath}`, {
+    res = await fetch(`${config.loginOrigin}${sessionPath}`, {
       headers: {
         Cookie: `${cookieName}=${match[1]}`,
         "X-Foir-Session": "1"
       }
     });
-    if (!res.ok) return null;
-    const json = await res.json();
-    if (!json.access_token || !json.customer_id) return null;
-    return {
-      token: json.access_token,
-      customerId: json.customer_id,
-      email: json.email ?? ""
-    };
+  } catch (cause) {
+    return { outcome: "unavailable", reason: "network", cause };
+  }
+  if (!res.ok) {
+    if (res.status === 401) {
+      return { outcome: "signed-out", reason: "rejected" };
+    }
+    if (res.status === 403) {
+      return { outcome: "unavailable", reason: "forbidden", httpStatus: res.status };
+    }
+    if (res.status === 429) {
+      return { outcome: "unavailable", reason: "rate-limited", httpStatus: res.status };
+    }
+    return { outcome: "unavailable", reason: "server-error", httpStatus: res.status };
+  }
+  let json;
+  try {
+    json = await res.json();
   } catch {
-    return null;
+    return { outcome: "unavailable", reason: "malformed", httpStatus: res.status };
   }
+  if (!json.access_token || !json.customer_id) {
+    return { outcome: "unavailable", reason: "malformed", httpStatus: res.status };
+  }
+  return {
+    outcome: "active",
+    session: {
+      token: json.access_token,
+      customerId: json.customer_id,
+      email: json.email ?? "",
+      expiresIn: typeof json.expires_in === "number" ? json.expires_in : 0
+    }
+  };
 }
 function escapeRegExp(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -1313,14 +1428,18 @@ export {
   getSessionCustomer,
   getSessionToken,
   hostedLoginUrl,
+  hostedLogoutUrl,
   loginWithOTP,
   loginWithPassword,
+  myOrganizations,
   myProviderToken,
   refreshSession,
+  registerOrganization,
   registerWithPassword,
   requireAdmin,
   requireAuth,
   resetPasswordAndSignIn,
   saveSession,
+  selectOrganization,
   signOut
 };

package/dist/client.js

@@ -11,11 +11,30 @@ function isFoirPreview(env) {
 function resolveFoirApiKey(env) {
   return isFoirPreview(env) ? env.PLATFORM_PREVIEW_API_KEY ?? env.PLATFORM_API_KEY : env.PLATFORM_API_KEY;
 }
+var MALFORMED_PRUNE_REASONS = /* @__PURE__ */ new Set([
+  "unknown_field",
+  "subselections_on_scalar",
+  "missing_subselections"
+]);
 var FoirRequestError = class extends Error {
   /** HTTP status code, when the request failed at the HTTP layer. */
   status;
   /** GraphQL errors, when the request failed with a no-data error envelope. */
   graphQLErrors;
+  /**
+   * The `data` the server did return, when a STRICT read refused a partial
+   * response. Present only on that path: without it, opting into strictness
+   * would trade a silent wrong answer for a thrown one that discards the answer,
+   * and a caller that wants to log what it nearly rendered could not.
+   */
+  partialData;
+  /**
+   * The selections the server stripped, when the refusal was a pruned document
+   * rather than a partial error. Same purpose as `partialData`: a caller that
+   * wants to log what it nearly rendered, or name the offending path in a
+   * developer-facing message, has it without re-parsing anything.
+   */
+  prunedSelections;
   cause;
   constructor(message, options) {
     super(message);
@@ -23,6 +42,8 @@ var FoirRequestError = class extends Error {
     this.cause = options?.cause;
     this.status = options?.status;
     this.graphQLErrors = options?.graphQLErrors;
+    this.partialData = options?.partialData;
+    this.prunedSelections = options?.prunedSelections;
   }
   /**
    * The code of the first error, if the response carried one.
@@ -105,6 +126,9 @@ function buildFoirHeaders(input) {
   if (input.bearerToken) {
     headers["Authorization"] = `Bearer ${input.bearerToken}`;
   }
+  if (input.orgId) {
+    headers["X-Org-Id"] = input.orgId;
+  }
   if (input.extra) {
     for (const [key, value] of Object.entries(input.extra)) {
       headers[key] = value;
@@ -112,14 +136,45 @@ function buildFoirHeaders(input) {
   }
   return headers;
 }
-function readFoirEnvelope(json) {
+var warnedDowngrade = null;
+function reportAuthDowngrade(envelope) {
+  const downgrade = envelope.extensions?.auth;
+  if (!downgrade) {
+    warnedDowngrade = null;
+    return;
+  }
+  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.")
+  );
+}
+function refusePrunedDocument(json, options) {
+  const selections = json.extensions?.pruned?.selections;
+  if (!selections?.length) return;
+  const describe = (s) => `${s.path}${s.type ? ` on ${s.type}` : ""} (${s.reason})`;
+  const malformed = selections.filter((s) => MALFORMED_PRUNE_REASONS.has(s.reason));
+  if (malformed.length && options?.strict !== false) {
+    throw new FoirRequestError(
+      `[foir] the server could not serve part of this query and returned the rest without it: ${malformed.map(describe).join(", ")}. Those selections do not exist on the schema this project is serving. Pass strict: false to get the partial answer instead of this error.`,
+      { prunedSelections: selections }
+    );
+  }
+  console.warn(
+    `[foir] selections stripped from this query: ${selections.map(describe).join(", ")}`
+  );
+}
+function readFoirEnvelope(json, options) {
+  reportAuthDowngrade(json);
+  refusePrunedDocument(json, options);
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
-    if (json.data) {
+    if (json.data && !options?.strict) {
       console.warn(`[foir] GraphQL partial errors (data returned): ${msg}`);
     } else {
       throw new FoirRequestError(`[foir] GraphQL errors: ${msg}`, {
-        graphQLErrors: json.errors
+        graphQLErrors: json.errors,
+        partialData: json.data ?? void 0
       });
     }
   }
@@ -160,8 +215,9 @@ async function hasFoirErrorCode(res, ...codes) {
 }
 
 // src/graphql/cdn-route.ts
-function isCdnEligible(env, documentText, bearerToken) {
+function isCdnEligible(env, documentText, bearerToken, orgId) {
   if (bearerToken) return false;
+  if (orgId) return false;
   if (isFoirPreview(env)) return false;
   const apiKey = resolveFoirApiKey(env);
   if (!apiKey?.startsWith("pk_")) return false;
@@ -214,12 +270,13 @@ async function foirRequest(env, document, variables, options) {
   const headers = buildFoirHeaders({
     apiKey,
     draftChannel: isFoirPreview(env),
-    bearerToken: options?.bearerToken
+    bearerToken: options?.bearerToken,
+    orgId: options?.orgId
   });
   const documentText = print2(document);
   let res;
   try {
-    if (isCdnEligible(env, documentText, options?.bearerToken)) {
+    if (isCdnEligible(env, documentText, options?.bearerToken, options?.orgId)) {
       const hash = await documentHash(documentText);
       let shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
         method: "GET",

package/dist/codegen/block-registry.d.ts

@@ -2,7 +2,7 @@
  * `@foir/sdk/codegen/block-registry` — DEPRECATED alias.
  *
  * `block` was one project's name for a flexible field, never a platform
- * concept (TTS-1391). The plugin moved to `@foir/sdk/codegen/item-registry`;
+ * concept. The plugin moved to `@foir/sdk/codegen/item-registry`;
  * this path re-exports it unchanged so an existing `codegen.ts` keeps working.
  * Repoint the `plugins:` entry when convenient — this will be removed in a
  * future major.

package/dist/codegen/block-scaffold.d.ts

@@ -2,7 +2,7 @@
  * `@foir/sdk/codegen/block-scaffold` — DEPRECATED alias.
  *
  * `block` was one project's name for a flexible field, never a platform
- * concept (TTS-1391). The plugin moved to `@foir/sdk/codegen/item-scaffold`;
+ * concept. The plugin moved to `@foir/sdk/codegen/item-scaffold`;
  * this path re-exports it unchanged so an existing `codegen.ts` keeps working.
  * Repoint the `plugins:` entry when convenient — this will be removed in a
  * future major.

package/dist/codegen/index.d.ts

@@ -6,7 +6,7 @@
  * and item-scaffold plugins are wired by the preset and also available at
  * `@foir/sdk/codegen/item-registry` / `@foir/sdk/codegen/item-scaffold`.
  *
- * The pre-TTS-1391 paths `@foir/sdk/codegen/block-registry` and
+ * The pre-rename paths `@foir/sdk/codegen/block-registry` and
  * `/block-scaffold` still resolve, re-exporting those modules unchanged.
  */
 export { foirCodegen, foirScaffold } from './preset';

package/dist/codegen/item-registry.d.ts

@@ -13,7 +13,7 @@
  * types from the codegen output (`./graphql`) and `ItemComponent` from
  * `@foir/sdk/content`, so it pairs directly with `createContentRenderer`.
  *
- * Reachable at the pre-TTS-1391 path `@foir/sdk/codegen/block-registry` too,
+ * Reachable at the pre-rename path `@foir/sdk/codegen/block-registry` too,
  * which re-exports this module unchanged.
  */
 import type { GraphQLSchema } from 'graphql';

package/dist/codegen/item-scaffold.d.ts

@@ -10,7 +10,7 @@
  * in. Adding a new item type later surfaces as a compile error on
  * `itemRegistry` (via the regenerated `ItemRegistry` type), not here.
  *
- * Reachable at the pre-TTS-1391 path `@foir/sdk/codegen/block-scaffold` too,
+ * Reachable at the pre-rename path `@foir/sdk/codegen/block-scaffold` too,
  * which re-exports this module unchanged.
  */
 import type { GraphQLSchema } from 'graphql';

package/dist/content/content-renderer.d.ts

@@ -15,7 +15,7 @@
  *
  * The "switch" is a typed object lookup. Exhaustiveness is enforced where the
  * registry is BUILT — against the exhaustive `ItemRegistry` type the codegen
- * plugin (EID-92) generates per project, so omitting an item type is a compile
+ * plugin generates per project, so omitting an item type is a compile
  * error there, not a runtime surprise here. The consumer can supply different
  * registries per surface (e.g. web vs email).
  *
@@ -24,8 +24,7 @@
  * A prose field holds ENTRIES. A modeller may name the field `blocks`,
  * `sections`, `modules` or anything else, and this renderer must not care:
  * dispatch is on `__typename` and never on a field name. The `Block*` spellings
- * below are deprecated aliases kept so existing consumers compile — see
- * TTS-1391.
+ * below are deprecated aliases kept so existing consumers compile.
  */
 import { type ReactNode } from 'react';
 import { type PassageLike } from './richtext';
@@ -41,7 +40,7 @@ export interface ItemComponentProps<TItem, TCtx = unknown> {
     /**
      * The same value as `item`.
      *
-     * @deprecated Use `item`. Kept so components scaffolded before TTS-1391
+     * @deprecated Use `item`. Kept so components scaffolded before the rename
      * keep compiling; it is passed on every render and will be removed in a
      * future major.
      */
@@ -67,7 +66,7 @@ export interface EntriesLike {
  * The prose field's entries — the projection wrapper (`{ entries }`), or a
  * plain array — plus the context threaded to every component.
  *
- * `items` is canonical. `blocks` is the pre-TTS-1391 spelling and still
+ * `items` is canonical. `blocks` is the pre-rename spelling and still
  * accepted; passing both is a type error rather than a silent precedence rule,
  * because a caller who set both cannot be told which one this honoured.
  */

package/dist/content/index.d.ts

@@ -9,7 +9,7 @@
 export { createContentRenderer } from './content-renderer';
 export type { ItemLike, EntriesLike, ItemComponent, ItemComponentProps, ItemRegistry, ContentRendererProps, ContentRendererOptions, PassageRunProps, } from './content-renderer';
 /**
- * Pre-TTS-1391 spellings. `Block` was one project's name for a flexible field,
+ * Pre-rename spellings. `Block` was one project's name for a flexible field,
  * never a platform concept; these are kept so existing consumers compile and
  * will be removed in a future major.
  */

package/dist/content/richtext.d.ts

@@ -25,7 +25,7 @@
 import { type ReactNode, type JSX } from 'react';
 /**
  * safeHref allow-lists link schemes so stored prose can't smuggle a
- * `javascript:` (or `data:`/`vbscript:`) URL that executes on click (EID-207).
+ * `javascript:` (or `data:`/`vbscript:`) URL that executes on click.
  * Relative URLs, anchors, and the http(s)/mailto/tel schemes pass; anything
  * else collapses to '#'. Editors are not fully trusted, so this runs on the
  * structured render path, not only the html fallback.