@foir/sdk 0.9.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);
@@ -1135,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, "\\$&");
@@ -1326,12 +1431,15 @@ export {
   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.

package/dist/data/builtins.d.ts

@@ -20,10 +20,10 @@
  *     `models[key]` would skip them (an inexhaustive union, silently wrong at
  *     runtime) or emit `never`.
  *
- * # These are ONE set, not two (TTS-1391)
+ * # These are ONE set, not two
  *
  * They used to be two: a value object for a plain field, and a separate
- * `<Name>Block` wrapper for the same thing inside a flexible field. TTS-1391
+ * `<Name>Block` wrapper for the same thing inside a flexible field. The rename
  * removed the wrapper — an item IS its value — so a plain `image` field and an
  * `image` inside a flexible field are the SAME GraphQL type, `Image`. There is
  * no `ImageValue` in a real schema and never will be again; the only difference
@@ -78,7 +78,7 @@ export interface Image {
      * `String` on the wire, not `String!`.
      *
      * It was non-null here and nullable on the flexible-field member until
-     * TTS-1391, which is a §5.3.2 response-shape conflict the moment both are one
+     * the rename, which is a §5.3.2 response-shape conflict the moment both are one
      * type. The platform relaxed rather than tightened, because nullable is the
      * honest form — its own public `File` asset type already declares
      * `url: String` — so this follows.
@@ -215,7 +215,7 @@ export interface RecordAncestor {
  * 193 stored reference values carry an id and 92 carry a natural key and no id
  * — so a consumer must handle either.
  *
- * `_id` and `_type` are NOT here, and their absence is the TTS-1391 correction
+ * `_id` and `_type` are NOT here, and their absence is the correction
  * rather than an omission. They were the wrapper's own metadata: `_id` was the
  * ITEM's id (never the target's, which is why `_targetId` exists separately) and
  * `_type` was the union discriminator, reading `"reference"` on every reference
@@ -286,10 +286,10 @@ export interface CollabInfo {
  * The three wrappers below have no replacement, because the things they
  * described no longer exist:
  *
- *   - `MediaBlock` — `media` stopped being a primitive at TTS-1391. It was
+ *   - `MediaBlock` — `media` stopped being a primitive. It was
  *     never in the proto FieldType enum, and it is the one primitive name a
  *     project had also used as a model key.
- *   - `TextBlock` — TTS-1406 removed it. GraphQL requires a union member to be
+ *   - `TextBlock` — removed as well. GraphQL requires a union member to be
  *     an object type and a text item's value is a bare scalar, which is the
  *     whole reason a wrapper existed. An inline model with a text field is how
  *     a text slot is authored.
@@ -367,7 +367,7 @@ export interface FoirDegraded<TTypename extends string = string> {
  * Four because depth is a budget against the server's 10,000-field ceiling and
  * four is past what a generated module usefully describes: on the live dev
  * project `product.findUnique` measures 318 fields at the default, 468 at 2 and
- * 618 at 3. Those levels all fit since TTS-1448 — they read 1,203 / 4,308 /
+ * 618 at 3. Those levels all fit now — they read 1,203 / 4,308 /
  * 13,623 when a union position was charged for every member — so the bound here
  * is about how much generated type surface is worth emitting, not about what
  * the server will run. A call
@@ -429,7 +429,8 @@ export interface FoirUpdateManyPayload {
     ids: string[];
 }
 /**
- * What a note is ABOUT — the closed set the platform's write path enforces.
+ * What a customer's note can be ABOUT: the customer-plane subset of the closed
+ * set the platform's write path enforces.
  *
  * On the wire it is `String!`, not a GraphQL enum, so the manifest publishes no
  * `enumValues` for it and `foir types` cannot generate this union. It is here
@@ -440,10 +441,14 @@ export interface FoirUpdateManyPayload {
  * with a model keyed `file` would make one value mean two things; a note on a
  * record is `'record'` plus the model key on `subjectModelKey`.
  *
- * This mirrors a platform-side set, and the obligation that comes with a mirror
- * (see the file header) applies: a kind added there widens this union in a
- * minor release, and until then a value outside it is a row no writer could
- * have produced.
+ * The platform set also holds `project` and `organization`, and this union
+ * deliberately does not. Both are operator constructs: the platform answers a
+ * note about either through a row policy no customer claim passes, so no note
+ * this surface reads or writes can carry them. This mirrors the part of the
+ * platform set a customer can reach, and the obligation that comes with a mirror
+ * (see the file header) applies: a kind the platform opens to customers widens
+ * this union in a minor release, and until then a value outside it is a row no
+ * customer writer could have produced.
  */
 export type FoirNoteSubjectType = 'record' | 'file' | 'model' | 'operation' | 'schedule' | 'customer';
 /**
@@ -550,6 +555,53 @@ export interface FoirCreateMyNoteArgs {
      */
     attachmentFileIds?: string[];
 }
+/**
+ * `submitAnonymousNote` arguments — feedback from a visitor with no account.
+ *
+ * Present on the project's schema only while the project has opted in
+ * (Notes settings → "Accept anonymous notes"). The feedback widget does NOT
+ * use this: a signed-out visitor there is still asked to sign in, so this
+ * mutation is the only path a visitor's note can take.
+ *
+ * WRITE-ONLY. Nothing reads an anonymous note back on the public plane, which
+ * is why the result is a receipt rather than the note.
+ */
+export interface FoirSubmitAnonymousNoteArgs {
+    /**
+     * Must be `'record'` — the only thing a visitor may write a note about.
+     * Narrower than `FoirCreateMyNoteArgs`, where a customer may also address a
+     * file or a model.
+     */
+    subjectType: 'record';
+    subjectId: string;
+    /**
+     * The record's model key. REQUIRED here, unlike on `createMyNote` where it is
+     * conditional: the subject is always a record on this lane, so the condition
+     * is always met.
+     */
+    subjectModelKey: string;
+    body: string;
+    /**
+     * Optional. Where the operators may reply.
+     *
+     * Captured as typed and NEVER verified — it is not treated as proof of who
+     * wrote the note, and nothing is sent to it to confirm it. Do not build a
+     * flow that assumes the address is reachable.
+     */
+    contactEmail?: string;
+}
+/** What `submitAnonymousNote` returns. */
+export interface FoirAnonymousNoteReceipt {
+    /**
+     * A reference for this submission, to quote when following it up.
+     *
+     * NOT a handle: there is no read that takes it. Showing it to the visitor is
+     * the whole of its purpose.
+     */
+    reference: string;
+    /** When the platform recorded the submission. */
+    submittedAt: string;
+}
 export type FoirDeviceType = 'DESKTOP' | 'MOBILE' | 'TABLET';
 export type FoirPlatformType = 'IOS' | 'ANDROID' | 'WEB';
 /**