@foir/sdk 0.5.0 → 0.8.0

package/dist/react.js

@@ -12,10 +12,18 @@ import {
 } from "react";
 
 // src/graphql/foir-request.ts
+import { print as print2 } from "graphql";
+
+// src/graphql/cdn-route.ts
 import { print } from "graphql";
+
+// src/transport/foir-http.ts
 function isFoirPreview(env) {
   return env.FOIR_PREVIEW === "true";
 }
+function resolveFoirApiKey(env) {
+  return isFoirPreview(env) ? env.PLATFORM_PREVIEW_API_KEY ?? env.PLATFORM_API_KEY : env.PLATFORM_API_KEY;
+}
 var FoirRequestError = class extends Error {
   /** HTTP status code, when the request failed at the HTTP layer. */
   status;
@@ -29,41 +37,69 @@ var FoirRequestError = class extends Error {
     this.status = options?.status;
     this.graphQLErrors = options?.graphQLErrors;
   }
-};
-async function foirRequest(env, document, variables, options) {
-  const endpoint = env.PLATFORM_API_URL;
-  const apiKey = isFoirPreview(env) ? env.PLATFORM_PREVIEW_API_KEY ?? env.PLATFORM_API_KEY : env.PLATFORM_API_KEY;
-  if (!endpoint || !apiKey) {
-    throw new FoirRequestError(
-      "[foir] PLATFORM_API_URL or PLATFORM_API_KEY is not set \u2014 add them to .env"
-    );
+  /**
+   * The code of the first error, if the response carried one.
+   *
+   * A getter rather than a stored field so it stays correct for an error
+   * constructed anywhere, including by a caller in a test.
+   */
+  get code() {
+    return this.graphQLErrors?.[0]?.extensions?.code;
   }
+  /** The correlation id, if the response carried one. */
+  get requestId() {
+    return this.graphQLErrors?.[0]?.extensions?.requestId;
+  }
+  /**
+   * Whether retrying this request could succeed.
+   *
+   * The 429 is the one that has to be in here and is easy to leave out: it sits
+   * among the 4xx statuses that are otherwise permanent, so a policy written as
+   * "retry 5xx, never retry 4xx" excludes exactly the failure that clears on its
+   * own. A storefront wrote that policy, its key saturated, and every read
+   * failed on the first attempt for an hour.
+   */
+  get retryable() {
+    if (this.status === void 0) return true;
+    if (this.status === 429 || this.code === "RATE_LIMITED") return true;
+    if (this.status >= 500) return true;
+    return this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
+  }
+  /**
+   * How long to wait before retrying, in milliseconds, when the server said.
+   * Undefined when it did not, which means the caller picks its own backoff.
+   */
+  get retryAfterMs() {
+    const seconds = this.graphQLErrors?.[0]?.extensions?.retryAfter;
+    return typeof seconds === "number" && seconds > 0 ? seconds * 1e3 : void 0;
+  }
+};
+function buildFoirHeaders(input) {
   const headers = {
     "Content-Type": "application/json",
-    "x-api-key": apiKey
+    "x-api-key": input.apiKey
   };
-  if (isFoirPreview(env)) {
+  if (input.draftChannel) {
     headers["X-Foir-Schema-Channel"] = "draft";
   }
-  if (options?.bearerToken) {
-    headers["Authorization"] = `Bearer ${options.bearerToken}`;
+  if (input.bearerToken) {
+    headers["Authorization"] = `Bearer ${input.bearerToken}`;
   }
-  let res;
-  try {
-    res = await fetch(endpoint, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({ query: print(document), variables })
-    });
-  } catch (err) {
-    throw new FoirRequestError("[foir] network error", { cause: err });
+  if (input.extra) {
+    for (const [key, value] of Object.entries(input.extra)) {
+      headers[key] = value;
+    }
   }
-  if (!res.ok) {
-    throw new FoirRequestError(`[foir] HTTP ${res.status} ${res.statusText}`, {
-      status: res.status
-    });
+  return headers;
+}
+function foirApiEndpoint(apiUrl, path) {
+  const base = apiUrl.trim().replace(/\/+$/, "").replace(/\/graphql$/i, "");
+  if (!base) {
+    throw new FoirRequestError("[foir] apiUrl is empty \u2014 pass the Foir API origin");
   }
-  const json = await res.json();
+  return base + path;
+}
+function readFoirEnvelope(json) {
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
     if (json.data) {
@@ -80,54 +116,703 @@ async function foirRequest(env, document, variables, options) {
   return json.data;
 }
 
-// src/auth/operations.ts
-import { parse } from "graphql";
-var AUTH_RESULT_FIELDS = "token refreshToken customerId email";
-var CustomerLoginDocument = parse(
-  `mutation CustomerLogin($email: String!, $password: String!) {
-    customerLogin(email: $email, password: $password) { ${AUTH_RESULT_FIELDS} }
-  }`
-);
-var CustomerRegisterDocument = parse(
-  `mutation CustomerRegister($email: String!, $password: String!) {
-    customerRegister(email: $email, password: $password) { ${AUTH_RESULT_FIELDS} }
-  }`
-);
-var CustomerRefreshTokenDocument = parse(
-  `mutation CustomerRefreshToken($refreshToken: String!) {
-    customerRefreshToken(refreshToken: $refreshToken) { ${AUTH_RESULT_FIELDS} }
-  }`
-);
-var CustomerRequestOTPDocument = parse(
-  `mutation CustomerRequestOTP($email: String!) {
-    customerRequestOTP(email: $email)
-  }`
-);
-var CustomerLoginOTPDocument = parse(
-  `mutation CustomerLoginOTP($email: String!, $otp: String!) {
-    customerLoginOTP(email: $email, otp: $otp) { ${AUTH_RESULT_FIELDS} }
-  }`
-);
-var CustomerLoginWithProviderDocument = parse(
-  `mutation CustomerLoginWithProvider($input: ProviderLoginInput!) {
-    customerLoginWithProvider(input: $input) { redirectUrl token }
-  }`
-);
-var CustomerProviderCallbackDocument = parse(
-  `mutation CustomerProviderCallback($input: ProviderCallbackInput!) {
-    customerProviderCallback(input: $input) { ${AUTH_RESULT_FIELDS} }
-  }`
-);
-var CustomerProviderVerifyOTPDocument = parse(
-  `mutation CustomerProviderVerifyOTP($input: ProviderOTPVerifyInput!) {
-    customerProviderVerifyOTP(input: $input) { ${AUTH_RESULT_FIELDS} }
-  }`
-);
-var AuthProvidersDocument = parse(
-  `query AuthProviders {
-    authProviders { key name type isDefault }
-  }`
-);
+// src/transport/persisted-query.ts
+var FOIR_CDN_GRAPHQL_PATH = "/cdn/graphql";
+function persistedQueryExtension(hash) {
+  return { persistedQuery: { version: 1, sha256Hash: hash } };
+}
+function buildCdnUrl(endpoint, apiKey, hash, variables) {
+  const url = new URL(endpoint);
+  url.pathname = url.pathname.replace(/\/graphql\/?$/, "") + FOIR_CDN_GRAPHQL_PATH;
+  url.searchParams.set("key", apiKey);
+  url.searchParams.set("extensions", JSON.stringify(persistedQueryExtension(hash)));
+  if (variables && Object.keys(variables).length > 0) {
+    url.searchParams.set("variables", JSON.stringify(variables));
+  }
+  return url.toString();
+}
+async function documentHash(documentText) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(documentText));
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var PERSISTED_QUERY_NOT_FOUND = "PERSISTED_QUERY_NOT_FOUND";
+var NOT_SHAREABLE = "NOT_SHAREABLE";
+async function hasFoirErrorCode(res, ...codes) {
+  try {
+    const body = await res.clone().json();
+    return body.errors?.some((e) => e.extensions?.code !== void 0 && codes.includes(e.extensions.code)) ?? false;
+  } catch {
+    return false;
+  }
+}
+
+// src/data/document.ts
+function buildPathTrie(paths) {
+  const root = { self: false, children: /* @__PURE__ */ new Map() };
+  for (const path of paths) {
+    let node = root;
+    for (const segment of path.split(".")) {
+      if (!segment) continue;
+      let next = node.children.get(segment);
+      if (!next) {
+        next = { self: false, children: /* @__PURE__ */ new Map() };
+        node.children.set(segment, next);
+      }
+      node = next;
+    }
+    node.self = true;
+  }
+  return root;
+}
+function childFor(node, field) {
+  return node.children.get(field.key) ?? (field.alias ? node.children.get(field.alias) : void 0);
+}
+function segmentFor(node, field) {
+  return node.children.has(field.key) ? field.key : field.alias ?? field.key;
+}
+var PROTECTED_ROOT_FIELD = "_id";
+var MAX_QUERY_COMPLEXITY = 1e4;
+var MAX_EMITTED_FIELDS = 4 * MAX_QUERY_COMPLEXITY;
+var newBudget = () => ({ fields: 0, emitted: 0, stopped: false });
+function charge(ctx, n = 1) {
+  ctx.budget.fields += n;
+  ctx.budget.emitted += n;
+}
+function mayExpand(ctx, depth) {
+  if (depth <= 1) return false;
+  if (ctx.budget.emitted > MAX_EMITTED_FIELDS) {
+    ctx.budget.stopped = true;
+    return false;
+  }
+  return true;
+}
+function printFields(fields, ctx, omit, pick, isRoot, path, depth) {
+  const parts = [];
+  for (const field of fields) {
+    if (field.relation) {
+      const named = pick ? childFor(pick, field) : void 0;
+      if (named) {
+        const segment = segmentFor(pick, field);
+        throw new FoirRequestError(
+          `[foir] pick "${path}${segment}": "${segment}" is a relation, and relations are not part of the default document \u2014 no pick can select one. ` + (path ? (
+            // Nested: there is no `include` form that reaches here at all.
+            // `include` addresses the ROOT model's own relations, and (nested)
+            // a related model's — never one reached through a composite or a
+            // union member. Saying "use include" would send the caller to a
+            // call that refuses them a second time.
+            `A relation at this position cannot be reached by \`include\` either \u2014 that addresses the model's own relations, not one inside a composite or a union member. Read it through the field that owns it, or drop "${path}${segment}" from the pick`
+          ) : `Use include: { ${segment}: true } instead`)
+        );
+      }
+      continue;
+    }
+    const protectedField = isRoot && field.key === PROTECTED_ROOT_FIELD;
+    const omitChild = omit ? childFor(omit, field) : void 0;
+    if (omitChild?.self && !protectedField) continue;
+    let pickChild;
+    if (pick) {
+      pickChild = childFor(pick, field);
+      if (!pickChild && !protectedField) continue;
+      if (pickChild?.self) pickChild = void 0;
+    }
+    const head = field.alias ? `${field.alias}: ${field.key}` : field.key;
+    const childPath = `${path}${pick && childFor(pick, field) ? segmentFor(pick, field) : field.key}.`;
+    if (field.truncated) {
+      if (field.union && mayExpand(ctx, depth)) {
+        const body = printUnion(field.union, ctx, omitChild, pickChild, childPath, depth - 1);
+        if (body) {
+          charge(ctx);
+          parts.push(`${head} ${body}`);
+          continue;
+        }
+      }
+      charge(ctx, 2);
+      parts.push(`${head} { __typename }`);
+      continue;
+    }
+    if (field.model) {
+      const body = printModelTree(field.model, ctx, depth);
+      if (body) {
+        charge(ctx);
+        parts.push(`${head} { ${body} }`);
+      }
+      continue;
+    }
+    if (field.union) {
+      const body = printUnion(field.union, ctx, omitChild, pickChild, childPath, depth);
+      if (body) {
+        charge(ctx);
+        parts.push(`${head} ${body}`);
+      }
+      continue;
+    }
+    if (field.fields?.length) {
+      const body = printFields(field.fields, ctx, omitChild, pickChild, false, childPath, depth);
+      if (body) {
+        charge(ctx);
+        parts.push(`${head} { ${body} }`);
+      }
+      continue;
+    }
+    charge(ctx);
+    parts.push(head);
+  }
+  return parts.join(" ");
+}
+function printModelTree(modelKey, ctx, depth) {
+  const model = ctx.source.models[modelKey];
+  if (!model?.selection) {
+    throw new FoirRequestError(
+      `[foir] the result shape references the model "${modelKey}", which publishes no selection \u2014 re-run \`foir types\``
+    );
+  }
+  const narrowing = ctx.record?.modelKey === modelKey ? ctx.record : void 0;
+  const body = printFields(
+    model.selection.fields,
+    ctx,
+    narrowing?.omit,
+    narrowing?.pick,
+    true,
+    "",
+    depth
+  );
+  const includes = narrowing?.include ? printIncludes(ctx.source, model, modelKey, narrowing.include, ctx, depth) : "";
+  if (!body) {
+    return includes;
+  }
+  return includes ? `${body} ${includes}` : body;
+}
+var NO_FIELDS = { self: false, children: /* @__PURE__ */ new Map() };
+function addressesMembers(node, union) {
+  for (const member of union.members) {
+    if (node.children.has(member.typeName)) return true;
+  }
+  return false;
+}
+function printUnion(unionName, ctx, omit, pick, path, depth) {
+  const union = ctx.unions[unionName];
+  if (!union) {
+    throw new FoirRequestError(
+      `[foir] the selection tree names the union "${unionName}", which is not in selectionUnions \u2014 re-run \`foir types\`, or pass selectionUnions alongside selections`
+    );
+  }
+  const perVariantPick = pick !== void 0 && addressesMembers(pick, union);
+  const perVariantOmit = omit !== void 0 && addressesMembers(omit, union);
+  charge(ctx);
+  const parts = ["__typename"];
+  const chargeBefore = ctx.budget.fields;
+  let widestMember = 0;
+  for (const member of union.members) {
+    let memberPick = pick;
+    if (perVariantPick) {
+      const named = pick.children.get(member.typeName);
+      memberPick = named === void 0 ? NO_FIELDS : named.self ? void 0 : named;
+    }
+    let memberOmit = omit;
+    if (perVariantOmit) {
+      const named = omit.children.get(member.typeName);
+      if (named?.self) continue;
+      memberOmit = named;
+    }
+    const memberPath = perVariantPick ? `${path}${member.typeName}.` : path;
+    const memberStart = ctx.budget.fields;
+    const body = printFields(member.fields, ctx, memberOmit, memberPick, false, memberPath, depth);
+    const memberCost = ctx.budget.fields - memberStart;
+    ctx.budget.fields = memberStart;
+    if (memberCost > widestMember) widestMember = memberCost;
+    if (body) parts.push(`... on ${member.typeName} { ${body} }`);
+  }
+  ctx.budget.fields = chargeBefore + widestMember;
+  return `{ ${parts.join(" ")} }`;
+}
+function printIncludes(source, model, modelKey, include, ctx, depth) {
+  const parts = [];
+  for (const [key, value] of Object.entries(include)) {
+    if (value === void 0 || value === false) continue;
+    const relation = model.relations?.find((r) => r.key === key);
+    if (!relation) {
+      throw new FoirRequestError(
+        `[foir] include "${key}": ${modelKey} has no such relation \u2014 re-run \`foir types\` if the model has changed`
+      );
+    }
+    const nested = value && typeof value === "object" && "include" in value ? value["include"] : void 0;
+    const body = relation.targets?.length ? printPolymorphicRelation(source, relation, ctx, nested, depth) : printRelationTarget(source, relation.target ?? "", ctx, nested, relation.key, depth);
+    charge(ctx, relation.connection ? 1 + CONNECTION_WRAPPER_FIELDS : 1);
+    parts.push(`${key} ${relation.connection ? wrapRelationConnection(body) : `{ ${body} }`}`);
+  }
+  return parts.join(" ");
+}
+var CONNECTION_WRAPPER_FIELDS = 9;
+function wrapRelationConnection(body) {
+  return `{ edges { cursor node { ${body} } } pageInfo { hasNextPage hasPreviousPage startCursor endCursor } totalCount }`;
+}
+function printRelationTarget(source, targetKey, ctx, nested, relationKey, depth) {
+  const target = source.models[targetKey];
+  if (!target?.selection) {
+    throw new FoirRequestError(
+      `[foir] include "${relationKey}": no selection published for its target model "${targetKey}" \u2014 re-run \`foir types\``
+    );
+  }
+  const bare = { source, unions: ctx.unions, budget: ctx.budget };
+  const body = printFields(target.selection.fields, bare, void 0, void 0, true, "", depth);
+  const includes = nested ? printIncludes(source, target, targetKey, nested, bare, depth) : "";
+  return includes ? `${body} ${includes}` : body;
+}
+function printPolymorphicRelation(source, relation, ctx, nested, depth) {
+  charge(ctx);
+  const parts = ["__typename"];
+  const chargeBefore = ctx.budget.fields;
+  let widestTarget = 0;
+  for (const targetKey of relation.targets ?? []) {
+    const target = source.models[targetKey];
+    if (!target?.selection) {
+      throw new FoirRequestError(
+        `[foir] include "${relation.key}": no selection published for its target model "${targetKey}" \u2014 re-run \`foir types\``
+      );
+    }
+    const targetStart = ctx.budget.fields;
+    const body = printRelationTarget(source, targetKey, ctx, nested, relation.key, depth);
+    const targetCost = ctx.budget.fields - targetStart;
+    ctx.budget.fields = targetStart;
+    if (targetCost > widestTarget) widestTarget = targetCost;
+    if (body) parts.push(`... on ${target.typeName} { ${body} }`);
+  }
+  ctx.budget.fields = chargeBefore + widestTarget;
+  return parts.join(" ");
+}
+var GRAPHQL_TYPE_REF = /^\[?\[?[_A-Za-z][_0-9A-Za-z]*!?\]?!?\]?!?$/;
+function buildArguments(args, op, opLabel) {
+  const declared = op.args;
+  const definitions = [];
+  const call = [];
+  const variables = {};
+  for (const name of Object.keys(args).sort()) {
+    const value = args[name];
+    if (value === void 0) continue;
+    if (!declared?.includes(name)) {
+      throw new FoirRequestError(
+        `[foir] ${opLabel} does not take an argument "${name}" \u2014 it takes ${declared?.length ? declared.join(", ") : "no arguments"}`
+      );
+    }
+    const type = op.argTypes?.[name];
+    if (!type) {
+      throw new FoirRequestError(
+        `[foir] ${opLabel}: the manifest publishes no type for the argument "${name}", so it cannot be sent as a variable \u2014 and inferring one from the value would guess wrong on every enum. Re-run \`foir types\` against a server that publishes argTypes, or use foir.raw() with your own variable definitions`
+      );
+    }
+    if (!GRAPHQL_TYPE_REF.test(type)) {
+      throw new FoirRequestError(
+        `[foir] ${opLabel}: the manifest gives the argument "${name}" the type "${type}", which is not a GraphQL type reference`
+      );
+    }
+    definitions.push(`$${name}: ${type}`);
+    call.push(`${name}: $${name}`);
+    variables[name] = toVariableValue(value, `${opLabel} argument "${name}"`);
+  }
+  return {
+    definitions: definitions.length ? `(${definitions.join(", ")})` : "",
+    call: call.length ? `(${call.join(", ")})` : "",
+    variables
+  };
+}
+function toVariableValue(value, label) {
+  if (value === null) return null;
+  const kind = typeof value;
+  if (kind === "string" || kind === "boolean") return value;
+  if (kind === "number") {
+    if (!Number.isFinite(value)) {
+      throw new FoirRequestError(
+        `[foir] ${label} is ${String(value)}, which has no JSON form and cannot be sent`
+      );
+    }
+    return value;
+  }
+  if (kind === "bigint") {
+    const asNumber = Number(value);
+    if (!Number.isSafeInteger(asNumber)) {
+      throw new FoirRequestError(
+        `[foir] ${label} is the bigint ${String(value)}, which is outside the range JSON can carry exactly`
+      );
+    }
+    return asNumber;
+  }
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw new FoirRequestError(`[foir] ${label} is an invalid Date`);
+    }
+    return value.toISOString();
+  }
+  if (Array.isArray(value)) {
+    return value.filter((item) => item !== void 0).map((item, index) => toVariableValue(item, `${label}[${index}]`));
+  }
+  if (kind === "object") {
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      if (child === void 0) continue;
+      out[key] = toVariableValue(child, `${label}.${key}`);
+    }
+    return out;
+  }
+  throw new FoirRequestError(
+    `[foir] ${label} is a ${kind}, which has no JSON form and cannot be sent`
+  );
+}
+function payloadRecordPaths(payload) {
+  if (payload.kind === "record") {
+    return payload.model ? [{ path: [], modelKey: payload.model }] : [];
+  }
+  const found = [];
+  const visit = (fields, prefix) => {
+    for (const field of fields ?? []) {
+      const at = [...prefix, field.alias ?? field.key];
+      if (field.model) found.push({ path: at, modelKey: field.model });
+      visit(field.fields, at);
+    }
+  };
+  visit(payload.fields, []);
+  return found;
+}
+function printPayload(payload, ctx, root, opLabel, depth) {
+  switch (payload.kind) {
+    case "leaf":
+      return void 0;
+    case "record": {
+      if (!payload.model) {
+        throw new FoirRequestError(
+          `[foir] ${opLabel}: the result shape says it is a record but names no model \u2014 re-run \`foir types\``
+        );
+      }
+      return printModelTree(payload.model, ctx, depth);
+    }
+    case "union": {
+      if (!payload.union) {
+        throw new FoirRequestError(
+          `[foir] ${opLabel}: the result shape says it is a union but names none \u2014 re-run \`foir types\``
+        );
+      }
+      return printUnion(payload.union, ctx, root.omit, root.pick, "", depth).slice(2, -2);
+    }
+    case "object": {
+      if (!payload.fields?.length) {
+        throw new FoirRequestError(
+          `[foir] ${opLabel}: the result shape is an object with no fields \u2014 re-run \`foir types\``
+        );
+      }
+      return printFields(payload.fields, ctx, root.omit, root.pick, false, "", depth);
+    }
+    default:
+      throw new FoirRequestError(
+        `[foir] ${opLabel}: the result shape has the kind "${String(payload.kind)}", which this client does not know how to print \u2014 upgrade @foir/sdk`
+      );
+  }
+}
+var DEFAULT_DEPTH = 1;
+function planFoirNamespaceCall(source, call) {
+  const namespace = source.namespaces?.[call.namespace];
+  if (!namespace) {
+    throw new FoirRequestError(
+      `[foir] no namespace "${call.namespace}" in this credential's surface \u2014 re-run \`foir types\``
+    );
+  }
+  const opDef = namespace.ops?.[call.op];
+  if (!opDef) {
+    throw new FoirRequestError(
+      `[foir] the namespace "${call.namespace}" has no op "${call.op}" for this credential \u2014 re-run \`foir types\``
+    );
+  }
+  return planCall(
+    source,
+    opDef,
+    `${call.namespace}.${call.op}`,
+    operationName(call.namespace, call.op),
+    call
+  );
+}
+function planCall(source, opDef, opLabel, name, call) {
+  const payload = opDef.payload;
+  if (!payload) {
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: the manifest publishes no result shape for this op, so there is nothing to print \u2014 and synthesising one client-side is exactly the guess this client refuses to make. Re-run \`foir types\` against a server that publishes op payloads`
+    );
+  }
+  if (payload.error) {
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: the server could not resolve a result shape for this op: ${payload.error}`
+    );
+  }
+  if (call.omit && call.pick) {
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: "omit" and "pick" are mutually exclusive \u2014 pass one or the other`
+    );
+  }
+  if (call.omit?.includes(PROTECTED_ROOT_FIELD)) {
+    throw new FoirRequestError(
+      `[foir] omit "${PROTECTED_ROOT_FIELD}": "${PROTECTED_ROOT_FIELD}" is required for correctness and cannot be removed`
+    );
+  }
+  const depth = call.depth ?? DEFAULT_DEPTH;
+  if (!Number.isInteger(depth) || depth < DEFAULT_DEPTH) {
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: depth must be a whole number of union levels, ${DEFAULT_DEPTH} or more \u2014 got ${String(call.depth)}. ${DEFAULT_DEPTH} is the complete-by-default document; each level above it expands one further union`
+    );
+  }
+  const omit = call.omit?.length ? buildPathTrie(call.omit) : void 0;
+  const pick = call.pick?.length ? buildPathTrie(call.pick) : void 0;
+  const include = call.include && Object.keys(call.include).length ? call.include : void 0;
+  const narrowed = Boolean(omit || pick || include);
+  const recordPaths = payloadRecordPaths(payload);
+  const records = new Set(recordPaths.map((entry) => entry.modelKey));
+  if (records.size > 1 && narrowed) {
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: the result carries records of more than one model (${[...records].sort().join(", ")}), so "include"/"pick"/"omit" do not say which one they mean \u2014 call it without them and narrow with foir.raw()`
+    );
+  }
+  const recordModel = records.size === 1 ? [...records][0] : void 0;
+  if (include && !recordModel) {
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: "include" names relations of a record, and this op returns none`
+    );
+  }
+  const ctx = {
+    source,
+    unions: source.selectionUnions ?? {},
+    record: recordModel ? { modelKey: recordModel, omit, pick, include } : void 0,
+    budget: newBudget()
+  };
+  const root = recordModel ? {} : { omit, pick };
+  const selection = printPayload(payload, ctx, root, opLabel, depth);
+  if (selection === "") {
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: the selection is empty after applying pick/omit \u2014 a GraphQL selection set cannot be empty`
+    );
+  }
+  charge(ctx);
+  if (depth > DEFAULT_DEPTH && (ctx.budget.stopped || ctx.budget.fields > MAX_QUERY_COMPLEXITY)) {
+    const reason = ctx.budget.stopped ? `expands to more than ${MAX_EMITTED_FIELDS} fields to print, which is past what this client will build in one call` : `makes this document select ${ctx.budget.fields} fields, over the server's limit of ${MAX_QUERY_COMPLEXITY}`;
+    throw new FoirRequestError(
+      `[foir] ${opLabel}: depth ${depth} ${reason}. Each level re-expands every stopping point inside the expansion, so spend the level on less: narrow with "pick"/"omit" \u2014 including per-member, pick: { <field>: { on: { <MemberType>: [...] } } } \u2014 or ask for depth ${depth - 1}`
+    );
+  }
+  const args = buildArguments(call.args, opDef, opLabel);
+  const keyword = opDef.mutation ? "mutation" : "query";
+  const body = selection === void 0 ? "" : ` { ${selection} }`;
+  return {
+    document: `${keyword} ${name}${args.definitions} { ${opDef.field}${args.call}${body} }`,
+    variables: args.variables,
+    mutation: opDef.mutation === true,
+    rootField: opDef.field,
+    fields: ctx.budget.fields,
+    records: recordPaths
+  };
+}
+function operationName(scope, op) {
+  const parts = `${scope} ${op}`.split(/[^0-9A-Za-z]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1));
+  const name = parts.join("");
+  return /^[_A-Za-z]/.test(name) ? name : `Foir${name}`;
+}
+
+// src/data/transport.ts
+function foirDataEndpoint(apiUrl, path) {
+  return foirApiEndpoint(apiUrl, path);
+}
+async function resolveBearerToken(config) {
+  const source = config.bearerToken;
+  if (typeof source === "function") return await source() ?? void 0;
+  return source ?? void 0;
+}
+function foirRoute(input) {
+  if (!input.apiKey.startsWith("pk_")) return { lane: "origin", reason: "key" };
+  if (input.bearerToken) return { lane: "origin", reason: "bearer" };
+  if (input.mutation) return { lane: "origin", reason: "operation" };
+  if (input.channel === "draft") return { lane: "origin", reason: "channel" };
+  return { lane: "shared" };
+}
+async function executeFoirDocument(config, plan) {
+  const data = await runFoirDocument(config, plan.document, plan.mutation, plan.variables);
+  if (!(plan.rootField in data)) {
+    throw new FoirRequestError(
+      `[foir] the response has no "${plan.rootField}" field` + (Object.keys(data).length ? ` (got ${Object.keys(data).join(", ")})` : "")
+    );
+  }
+  return data[plan.rootField];
+}
+async function runFoirDocument(config, document2, mutation, variables) {
+  const doFetch = config.fetch ?? globalThis.fetch;
+  const endpoint = foirDataEndpoint(config.apiUrl, "/graphql");
+  const bearerToken = await resolveBearerToken(config);
+  const headers = buildFoirHeaders({
+    apiKey: config.apiKey,
+    draftChannel: config.channel === "draft",
+    bearerToken,
+    extra: config.headers
+  });
+  const hash = await documentHash(document2);
+  const route = foirRoute({
+    apiKey: config.apiKey,
+    bearerToken,
+    mutation,
+    channel: config.channel
+  });
+  const post = (body) => doFetch(endpoint, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    ...config.requestInit
+  });
+  const extensions = persistedQueryExtension(hash);
+  let res;
+  try {
+    if (route.lane === "shared") {
+      res = await doFetch(buildCdnUrl(endpoint, config.apiKey, hash, variables), {
+        method: "GET",
+        headers,
+        ...config.requestInit
+      });
+      if (await hasFoirErrorCode(res, PERSISTED_QUERY_NOT_FOUND, NOT_SHAREABLE)) {
+        res = await post({ query: document2, variables, extensions });
+      }
+    } else {
+      res = await post({ variables, extensions });
+      if (await hasFoirErrorCode(res, PERSISTED_QUERY_NOT_FOUND)) {
+        res = await post({ query: document2, variables, extensions });
+      }
+    }
+  } catch (err) {
+    throw new FoirRequestError("[foir] network error", { cause: err });
+  }
+  if (!res.ok) {
+    const errors = await readErrorBody(res);
+    const detail = errors ? `: ${errors.map((e) => e.message).join("; ")}` : "";
+    throw new FoirRequestError(`[foir] HTTP ${res.status} ${res.statusText}${detail}`, {
+      status: res.status,
+      graphQLErrors: errors
+    });
+  }
+  const json = await res.json();
+  return readFoirEnvelope(json);
+}
+async function readErrorBody(res) {
+  try {
+    const json = await res.json();
+    return json?.errors?.length ? json.errors : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/data/manifest.ts
+async function fetchFoirManifest(config) {
+  const url = foirDataEndpoint(config.apiUrl, "/v1/manifest");
+  const doFetch = config.fetch ?? globalThis.fetch;
+  let res;
+  try {
+    res = await doFetch(url, {
+      method: "GET",
+      headers: buildFoirHeaders({
+        apiKey: config.apiKey,
+        draftChannel: config.channel === "draft",
+        bearerToken: await resolveBearerToken(config),
+        extra: config.headers
+      }),
+      ...config.requestInit
+    });
+  } catch (err) {
+    throw new FoirRequestError("[foir] network error", { cause: err });
+  }
+  if (!res.ok) {
+    throw new FoirRequestError(
+      `[foir] GET /v1/manifest failed: HTTP ${res.status} ${res.statusText}`,
+      { status: res.status }
+    );
+  }
+  return await res.json();
+}
+
+// src/auth/ops.ts
+var AUTH_OPS = {
+  // Pre-credential reads a login screen renders itself from.
+  authConfig: "authConfig",
+  authProviders: "authProviders",
+  defaultAuthProvider: "defaultAuthProvider",
+  customerSignupContext: "customerSignupContext",
+  // Post-credential self reads.
+  currentUser: "currentUser",
+  myProviderToken: "myProviderToken",
+  // Methods.
+  customerLogin: "customerLogin",
+  customerRegister: "customerRegister",
+  customerRequestOTP: "customerRequestOTP",
+  customerLoginOTP: "customerLoginOTP",
+  // 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",
+  deleteMyAccount: "deleteMyAccount",
+  // External identity providers.
+  customerLoginWithProvider: "customerLoginWithProvider",
+  customerProviderCallback: "customerProviderCallback",
+  customerProviderVerifyOTP: "customerProviderVerifyOTP"
+};
+function authClientConfig(env, options) {
+  const apiKey = resolveFoirApiKey(env);
+  if (!apiKey) {
+    throw new FoirRequestError(
+      "[foir] no api key configured: set PLATFORM_API_KEY (or PLATFORM_PREVIEW_API_KEY under FOIR_PREVIEW=true)"
+    );
+  }
+  const apiUrl = env.PLATFORM_API_URL;
+  if (!apiUrl) {
+    throw new FoirRequestError("[foir] no api url configured: set PLATFORM_API_URL");
+  }
+  return {
+    apiUrl,
+    apiKey,
+    channel: isFoirPreview(env) ? "draft" : "published",
+    bearerToken: options?.bearerToken,
+    headers: options?.headers,
+    fetch: options?.fetch
+  };
+}
+var MANIFEST_CACHE_LIMIT = 8;
+var manifestCache = /* @__PURE__ */ new Map();
+function authManifest(config) {
+  const key = `${config.apiUrl}\0${config.apiKey}\0${config.channel ?? "published"}`;
+  const held = manifestCache.get(key);
+  if (held) return held;
+  const pending = fetchFoirManifest(config).catch((err) => {
+    manifestCache.delete(key);
+    throw err;
+  });
+  manifestCache.set(key, pending);
+  while (manifestCache.size > MANIFEST_CACHE_LIMIT) {
+    const oldest = manifestCache.keys().next();
+    if (oldest.done) break;
+    manifestCache.delete(oldest.value);
+  }
+  return pending;
+}
+async function authOp(env, op, args, options) {
+  const config = authClientConfig(env, options);
+  const manifest = await authManifest(config);
+  const plan = planFoirNamespaceCall(manifest, {
+    namespace: "auth",
+    op,
+    args: args ? stripUndefined(args) : {}
+  });
+  return executeFoirDocument(config, plan);
+}
+function stripUndefined(args) {
+  const out = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (value !== void 0) out[key] = value;
+  }
+  return out;
+}
 
 // src/auth/auth.ts
 var TOKEN_KEY = "foir:token";
@@ -135,28 +820,28 @@ var REFRESH_KEY = "foir:refreshToken";
 var CUSTOMER_ID_KEY = "foir:customerId";
 var EMAIL_KEY = "foir:email";
 async function customerLogin(env, vars) {
-  return (await foirRequest(env, CustomerLoginDocument, vars)).customerLogin;
+  return authOp(env, AUTH_OPS.customerLogin, vars);
 }
 async function customerRegister(env, vars) {
-  return (await foirRequest(env, CustomerRegisterDocument, vars)).customerRegister;
+  return authOp(env, AUTH_OPS.customerRegister, vars);
 }
 async function customerRequestOTP(env, email) {
-  return (await foirRequest(env, CustomerRequestOTPDocument, { email })).customerRequestOTP;
+  return authOp(env, AUTH_OPS.customerRequestOTP, { email });
 }
 async function customerLoginOTP(env, vars) {
-  return (await foirRequest(env, CustomerLoginOTPDocument, vars)).customerLoginOTP;
+  return authOp(env, AUTH_OPS.customerLoginOTP, vars);
 }
 async function customerRefreshToken(env, refreshToken) {
-  return (await foirRequest(env, CustomerRefreshTokenDocument, { refreshToken })).customerRefreshToken;
+  return authOp(env, AUTH_OPS.customerRefreshToken, { refreshToken });
 }
 async function customerLoginWithProvider(env, input) {
-  return (await foirRequest(env, CustomerLoginWithProviderDocument, { input })).customerLoginWithProvider;
+  return authOp(env, AUTH_OPS.customerLoginWithProvider, { input });
 }
 async function customerProviderCallback(env, input) {
-  return (await foirRequest(env, CustomerProviderCallbackDocument, { input })).customerProviderCallback;
+  return authOp(env, AUTH_OPS.customerProviderCallback, { input });
 }
 async function getAuthProviders(env) {
-  return (await foirRequest(env, AuthProvidersDocument, {})).authProviders;
+  return authOp(env, AUTH_OPS.authProviders);
 }
 async function saveSession(adapter, result) {
   await adapter.set(TOKEN_KEY, result.token);
@@ -481,7 +1166,7 @@ function FoirProvider({
     },
     [apply, assertTokenMode]
   );
-  const signOut = useCallback(async () => {
+  const signOut2 = useCallback(async () => {
     if (hosted) {
       await hosted.signOut();
       return;
@@ -521,7 +1206,7 @@ function FoirProvider({
       signInWithOtp,
       signInWithProvider,
       completeProviderLogin,
-      signOut,
+      signOut: signOut2,
       refresh,
       getToken,
       getProviders,
@@ -537,7 +1222,7 @@ function FoirProvider({
       signInWithOtp,
       signInWithProvider,
       completeProviderLogin,
-      signOut,
+      signOut2,
       refresh,
       getToken,
       getProviders,
@@ -573,7 +1258,7 @@ function useFoirAuth() {
     signInWithOtp,
     signInWithProvider,
     completeProviderLogin,
-    signOut,
+    signOut: signOut2,
     refresh,
     getToken,
     getProviders,
@@ -586,7 +1271,7 @@ function useFoirAuth() {
     signInWithOtp,
     signInWithProvider,
     completeProviderLogin,
-    signOut,
+    signOut: signOut2,
     refresh,
     getToken,
     getProviders,
@@ -669,6 +1354,7 @@ var inputStyle = {
 var submitStyle = { ...inputStyle, cursor: "pointer", fontWeight: 600 };
 var errorStyle = { color: "#c0392b", fontSize: 13, margin: 0 };
 var dividerStyle = { fontSize: 12, opacity: 0.6, textAlign: "center" };
+var SIGN_IN_FAILED = "Sign-in failed. Please try again.";
 function SignIn({
   method = "password",
   hostedUrl,
@@ -710,7 +1396,8 @@ function SignIn({
         finish(await signIn({ email, password }));
       }
     } catch (err) {
-      setError(err instanceof Error ? err.message : "Sign-in failed");
+      console.error("[foir] sign-in failed", err);
+      setError(SIGN_IN_FAILED);
     } finally {
       setBusy(false);
     }
@@ -765,7 +1452,10 @@ function SignIn({
     ] }),
     oauth && /* @__PURE__ */ jsxs2(Fragment, { children: [
       /* @__PURE__ */ jsx3("div", { "data-foir-divider": true, style: styled ? dividerStyle : void 0, children: "or" }),
-      /* @__PURE__ */ jsx3(OAuthButtons, { returnTo: afterSignInUrl, onError: (err) => setError(err instanceof Error ? err.message : "Sign-in failed") })
+      /* @__PURE__ */ jsx3(OAuthButtons, { returnTo: afterSignInUrl, onError: (err) => {
+        console.error("[foir] provider sign-in failed", err);
+        setError(SIGN_IN_FAILED);
+      } })
     ] })
   ] });
 }
@@ -785,11 +1475,11 @@ var btnStyle2 = {
 };
 function UserButton({ afterSignOut, afterSignOutUrl, className }) {
   const user = useFoirUser();
-  const { signOut } = useFoirAuth();
+  const { signOut: signOut2 } = useFoirAuth();
   if (!user) return null;
   const styled = !className;
   const onSignOut = async () => {
-    await signOut();
+    await signOut2();
     afterSignOut?.();
     if (afterSignOutUrl && typeof window !== "undefined") {
       window.location.assign(afterSignOutUrl);
@@ -800,7 +1490,599 @@ function UserButton({ afterSignOut, afterSignOutUrl, className }) {
     /* @__PURE__ */ jsx4("button", { type: "button", onClick: onSignOut, style: styled ? btnStyle2 : void 0, children: "Sign out" })
   ] });
 }
+
+// src/react/FoirFeedback.tsx
+import {
+  useCallback as useCallback2,
+  useEffect as useEffect3,
+  useRef as useRef2,
+  useState as useState4,
+  useSyncExternalStore
+} from "react";
+
+// src/media/screen-capture.ts
+var DEFAULT_MAX_WIDTH = 1600;
+var DEFAULT_QUALITY = 0.7;
+var CAPTURE_MIME_TYPE = "image/jpeg";
+function isFoirScreenCaptureSupported() {
+  return typeof navigator !== "undefined" && typeof navigator.mediaDevices?.getDisplayMedia === "function";
+}
+async function captureFoirScreen(options = {}) {
+  if (!isFoirScreenCaptureSupported()) {
+    throw new Error(
+      "[foir] this browser cannot capture the screen: navigator.mediaDevices.getDisplayMedia is unavailable. It needs a secure context (https, or localhost) and is absent on iOS. Call isFoirScreenCaptureSupported() before offering capture."
+    );
+  }
+  const maxWidth = options.maxWidth ?? DEFAULT_MAX_WIDTH;
+  const quality = options.quality ?? DEFAULT_QUALITY;
+  let stream;
+  try {
+    stream = await navigator.mediaDevices.getDisplayMedia({
+      video: { displaySurface: "browser" }
+    });
+  } catch (err) {
+    if (isDismissal(err)) return null;
+    throw err;
+  }
+  try {
+    const video = document.createElement("video");
+    video.muted = true;
+    video.playsInline = true;
+    video.srcObject = stream;
+    await waitForMetadata(video);
+    await video.play();
+    const { videoWidth, videoHeight } = video;
+    if (!videoWidth || !videoHeight) {
+      throw new Error(
+        "[foir] the captured stream reported no dimensions, so there is no frame to draw. This is the browser ending the capture before the first frame arrived \u2014 retry it."
+      );
+    }
+    const scale = videoWidth > maxWidth ? maxWidth / videoWidth : 1;
+    const width = Math.round(videoWidth * scale);
+    const height = Math.round(videoHeight * scale);
+    const canvas = document.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) {
+      throw new Error(
+        "[foir] this browser gave no 2d canvas context, so the captured frame cannot be encoded. Nothing was uploaded."
+      );
+    }
+    ctx.drawImage(video, 0, 0, width, height);
+    video.srcObject = null;
+    const dataUrl = canvas.toDataURL(CAPTURE_MIME_TYPE, quality);
+    return {
+      blob: dataUrlToBlob(dataUrl),
+      dataUrl,
+      width,
+      height,
+      mimeType: CAPTURE_MIME_TYPE
+    };
+  } finally {
+    for (const track of stream.getTracks()) track.stop();
+  }
+}
+function isDismissal(err) {
+  const name = err?.name;
+  return name === "NotAllowedError" || name === "AbortError";
+}
+function waitForMetadata(video) {
+  if (video.readyState >= 1) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    video.addEventListener("loadedmetadata", () => resolve(), { once: true });
+    video.addEventListener(
+      "error",
+      () => reject(
+        new Error("[foir] the captured stream failed to load before a frame could be read")
+      ),
+      { once: true }
+    );
+  });
+}
+function dataUrlToBlob(dataUrl) {
+  const comma = dataUrl.indexOf(",");
+  const header = comma === -1 ? "" : dataUrl.slice(0, comma);
+  if (comma === -1 || !header.includes(";base64")) {
+    throw new Error(
+      `[foir] the canvas produced a data URL this build cannot decode (${header || "no header"}). Expected a base64 data URL.`
+    );
+  }
+  const binary = atob(dataUrl.slice(comma + 1));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  const mimeType = header.slice("data:".length, header.indexOf(";"));
+  return new Blob([bytes], { type: mimeType || CAPTURE_MIME_TYPE });
+}
+
+// src/react/feedback-notes.ts
+var SIGN_IN_REFUSALS = ["sign-in required", "unauthorized: no auth"];
+function classifyNotesFault(err) {
+  for (const message of faultMessages(err)) {
+    const lower = message.toLowerCase();
+    if (SIGN_IN_REFUSALS.some((phrase) => lower.includes(phrase))) return { kind: "signIn" };
+    const missing = /missing required scope: ([a-z0-9_:.*-]+)/i.exec(message) ?? /scoped token lacks ([a-z0-9_:.*-]+)/i.exec(message);
+    if (missing?.[1]) return { kind: "scope", scope: missing[1] };
+  }
+  if (err?.status === 401) return { kind: "signIn" };
+  return { kind: "other" };
+}
+function faultMessages(err) {
+  if (!err || typeof err !== "object") return typeof err === "string" ? [err] : [];
+  const out = [];
+  const message = err.message;
+  if (typeof message === "string") out.push(message);
+  const graphQLErrors = err.graphQLErrors;
+  if (Array.isArray(graphQLErrors)) {
+    for (const item of graphQLErrors) {
+      const itemMessage = item?.message;
+      if (typeof itemMessage === "string") out.push(itemMessage);
+    }
+  }
+  return out;
+}
+async function readNoteConfig(client) {
+  const result = await client.ns.notes.noteConfig();
+  const screenshotsEnabled = result?.screenshotsEnabled;
+  if (typeof screenshotsEnabled !== "boolean") {
+    throw new Error(
+      "[foir] noteConfig answered without a boolean `screenshotsEnabled`. The widget reads it to decide whether to offer screenshot capture, and will not guess."
+    );
+  }
+  return { screenshotsEnabled };
+}
+async function submitFeedbackNote(client, submission) {
+  const attachmentFileIds = [];
+  if (submission.screenshot) {
+    attachmentFileIds.push(
+      await uploadFeedbackAttachment(client, submission.screenshot, submission.fetch)
+    );
+  }
+  const args = {
+    subjectType: "record",
+    subjectId: submission.subject.recordId,
+    subjectModelKey: submission.subject.modelKey,
+    body: submission.body
+  };
+  if (attachmentFileIds.length > 0) args.attachmentFileIds = attachmentFileIds;
+  return readCreatedNote(await client.ns.notes.createMyNote(args));
+}
+async function uploadFeedbackAttachment(client, screenshot, fetchImpl = globalThis.fetch) {
+  const files = client.ns.files;
+  if (!files) {
+    throw new Error(
+      "[foir] this client cannot reach the files namespace, so a screenshot cannot be uploaded. Attaching one needs `files:write` on the key and on the signed-in customer's role."
+    );
+  }
+  const ticket = readUploadTicket(
+    await files.createFileUpload({
+      filename: screenshotFilename(screenshot.mimeType),
+      mimeType: screenshot.mimeType,
+      // The blob's own size, never a number computed alongside it: this is what
+      // the plan's per-file limit and the storage allowance are checked against,
+      // and the presigned PUT rejects a body whose length disagrees.
+      size: screenshot.blob.size
+    })
+  );
+  const res = await fetchImpl(ticket.uploadUrl, {
+    method: "PUT",
+    headers: { "Content-Type": screenshot.mimeType },
+    body: screenshot.blob
+  });
+  if (!res.ok) {
+    throw new Error(
+      `[foir] uploading the screenshot failed: HTTP ${res.status} ${res.statusText}. The note was not written.`
+    );
+  }
+  const confirmed = await files.confirmFileUpload({ uploadId: ticket.uploadId });
+  const id = confirmed?.id;
+  if (typeof id !== "string" || id === "") {
+    throw new Error(
+      "[foir] confirmFileUpload answered without a file id, so there is nothing to attach the note to. The note was not written."
+    );
+  }
+  return id;
+}
+function readUploadTicket(result) {
+  const uploadId = result?.uploadId;
+  const uploadUrl = result?.uploadUrl;
+  if (typeof uploadId !== "string" || typeof uploadUrl !== "string" || !uploadId || !uploadUrl) {
+    throw new Error(
+      "[foir] createFileUpload answered without an uploadId and uploadUrl, so the screenshot has nowhere to go. The note was not written."
+    );
+  }
+  return { uploadId, uploadUrl };
+}
+function readCreatedNote(result) {
+  const note = result;
+  if (!note || typeof note.id !== "string" || note.id === "") {
+    throw new Error(
+      "[foir] createMyNote answered with no note. Nothing was saved \u2014 if it had been, the surface would have returned it."
+    );
+  }
+  return {
+    id: note.id,
+    body: typeof note.body === "string" ? note.body : null,
+    subjectType: note.subjectType ?? "record",
+    subjectId: typeof note.subjectId === "string" ? note.subjectId : "",
+    subjectModelKey: typeof note.subjectModelKey === "string" ? note.subjectModelKey : null,
+    parentNoteId: typeof note.parentNoteId === "string" ? note.parentNoteId : null,
+    threadRootId: typeof note.threadRootId === "string" ? note.threadRootId : null,
+    isResolved: note.isResolved === true,
+    attachments: readAttachments(note.attachments),
+    createdAt: typeof note.createdAt === "string" ? note.createdAt : ""
+  };
+}
+function readAttachments(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const item of value) {
+    const a = item;
+    if (!a || typeof a.fileId !== "string") continue;
+    out.push({
+      fileId: a.fileId,
+      filename: typeof a.filename === "string" ? a.filename : "",
+      mimeType: typeof a.mimeType === "string" ? a.mimeType : "",
+      size: typeof a.size === "number" ? a.size : 0,
+      url: typeof a.url === "string" ? a.url : ""
+    });
+  }
+  return out;
+}
+function screenshotFilename(mimeType) {
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const subtype = mimeType.slice(mimeType.indexOf("/") + 1);
+  const extension = subtype === "jpeg" ? "jpg" : subtype || "bin";
+  return `feedback-${stamp}.${extension}`;
+}
+
+// src/react/FoirFeedback.tsx
+import { Fragment as Fragment2, jsx as jsx5, jsxs as jsxs4 } from "react/jsx-runtime";
+var COPY = {
+  signIn: "Sign in to send feedback.",
+  signInAction: "Sign in",
+  notEnabled: "Feedback is not available on this account.",
+  unavailable: "Feedback is unavailable right now. Please try again later.",
+  noSubject: "There is nothing on this page to give feedback on.",
+  loading: "One moment\u2026",
+  sendFailed: "Your feedback could not be sent. Please try again.",
+  sent: "Thanks. Your feedback has been sent.",
+  send: "Send feedback",
+  sending: "Sending\u2026",
+  capture: "Add a screenshot",
+  capturing: "Choose what to share\u2026",
+  captureFailed: "The screenshot could not be taken. You can still send your feedback.",
+  screenshotAlt: "The screenshot that will be sent with your feedback",
+  removeScreenshot: "Remove screenshot",
+  about: "About"
+};
+var stackStyle = { display: "flex", flexDirection: "column", gap: 10 };
+var panelStyle = {
+  ...stackStyle,
+  maxWidth: 340,
+  padding: 16,
+  borderRadius: 8,
+  border: "1px solid currentColor",
+  font: "inherit"
+};
+var buttonStyle = {
+  padding: "8px 10px",
+  borderRadius: 6,
+  border: "1px solid currentColor",
+  background: "transparent",
+  font: "inherit",
+  cursor: "pointer"
+};
+var submitStyle2 = { ...buttonStyle, fontWeight: 600 };
+var textareaStyle = {
+  padding: "8px 10px",
+  borderRadius: 6,
+  border: "1px solid currentColor",
+  background: "transparent",
+  font: "inherit",
+  minHeight: 96,
+  resize: "vertical"
+};
+var headingStyle = { margin: 0, fontSize: 15, fontWeight: 600 };
+var subjectStyle = { margin: 0, fontSize: 13, opacity: 0.75 };
+var noteStyle = { margin: 0, fontSize: 13 };
+var errorStyle2 = { margin: 0, fontSize: 13, color: "#c0392b" };
+var previewStyle = {
+  display: "block",
+  width: "100%",
+  height: 96,
+  objectFit: "cover",
+  objectPosition: "top",
+  borderRadius: 6,
+  border: "1px solid currentColor"
+};
+function FoirFeedback({
+  client,
+  subjects,
+  subject,
+  label,
+  triggerLabel = "Feedback",
+  title = "Send feedback",
+  placeholder = "What would you like to tell us?",
+  defaultOpen = false,
+  onSignIn,
+  onSubmitted,
+  onError,
+  className
+}) {
+  const [open, setOpen] = useState4(defaultOpen);
+  const [probe, setProbe] = useState4({ status: "loading" });
+  const [body, setBody] = useState4("");
+  const [screenshot, setScreenshot] = useState4(null);
+  const [capturing, setCapturing] = useState4(false);
+  const [busy, setBusy] = useState4(false);
+  const [failure, setFailure] = useState4(null);
+  const [sent, setSent] = useState4(false);
+  const onErrorRef = useRef2(onError);
+  onErrorRef.current = onError;
+  const resolved = useResolvedSubject(subjects, subject);
+  const styled = !className;
+  useNoSubjectNotice(open, resolved, subjects !== void 0, subject !== void 0);
+  useEffect3(() => {
+    if (!open) return;
+    let cancelled = false;
+    setProbe({ status: "loading" });
+    void (async () => {
+      try {
+        const config = await readNoteConfig(client);
+        if (!cancelled) {
+          setProbe({ status: "ready", screenshotsEnabled: config.screenshotsEnabled });
+        }
+      } catch (err) {
+        if (cancelled) return;
+        const fault = classifyNotesFault(err);
+        reportFault(fault, err, "the notes surface could not be read");
+        onErrorRef.current?.(err);
+        setProbe({ status: "blocked", fault });
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [open, client]);
+  const capture = useCallback2(async () => {
+    setFailure(null);
+    setCapturing(true);
+    try {
+      const still = await captureFoirScreen();
+      if (still) setScreenshot(still);
+    } catch (err) {
+      console.error("[foir] <FoirFeedback>: capturing the screen failed", err);
+      onErrorRef.current?.(err);
+      setFailure(COPY.captureFailed);
+    } finally {
+      setCapturing(false);
+    }
+  }, []);
+  const onSubmit = async (event) => {
+    event.preventDefault();
+    const prose = body.trim();
+    if (!resolved || !prose || busy) return;
+    setBusy(true);
+    setFailure(null);
+    try {
+      const note = await submitFeedbackNote(client, {
+        subject: resolved,
+        body: prose,
+        screenshot
+      });
+      setBody("");
+      setScreenshot(null);
+      setSent(true);
+      onSubmitted?.(note);
+    } catch (err) {
+      const fault = classifyNotesFault(err);
+      reportFault(fault, err, "sending feedback failed");
+      onErrorRef.current?.(err);
+      setFailure(failureCopy(fault));
+    } finally {
+      setBusy(false);
+    }
+  };
+  const toggle = () => {
+    if (open) {
+      setOpen(false);
+      return;
+    }
+    setSent(false);
+    setFailure(null);
+    setOpen(true);
+  };
+  const subjectName = resolved ? label ?? resolved.label : void 0;
+  return /* @__PURE__ */ jsxs4("div", { className, "data-foir-feedback": true, children: [
+    /* @__PURE__ */ jsx5(
+      "button",
+      {
+        type: "button",
+        "data-foir-feedback-trigger": true,
+        "aria-expanded": open,
+        onClick: toggle,
+        style: styled ? buttonStyle : void 0,
+        children: triggerLabel
+      }
+    ),
+    open && /* @__PURE__ */ jsxs4(
+      "section",
+      {
+        "data-foir-feedback-panel": true,
+        "aria-label": title,
+        style: styled ? panelStyle : void 0,
+        children: [
+          /* @__PURE__ */ jsx5("h2", { "data-foir-feedback-title": true, style: styled ? headingStyle : void 0, children: title }),
+          subjectName && /* @__PURE__ */ jsxs4("p", { "data-foir-feedback-subject": true, style: styled ? subjectStyle : void 0, children: [
+            COPY.about,
+            ": ",
+            subjectName
+          ] }),
+          probe.status === "loading" && /* @__PURE__ */ jsx5(
+            "p",
+            {
+              role: "status",
+              "data-foir-feedback-status": true,
+              style: styled ? noteStyle : void 0,
+              children: COPY.loading
+            }
+          ),
+          probe.status === "blocked" && /* @__PURE__ */ jsx5(BlockedNotice, { fault: probe.fault, onSignIn, styled }),
+          probe.status === "ready" && !resolved && /* @__PURE__ */ jsx5(
+            "p",
+            {
+              role: "status",
+              "data-foir-feedback-status": true,
+              style: styled ? noteStyle : void 0,
+              children: COPY.noSubject
+            }
+          ),
+          probe.status === "ready" && resolved && /* @__PURE__ */ jsxs4("form", { onSubmit, style: styled ? stackStyle : void 0, children: [
+            /* @__PURE__ */ jsx5(
+              "textarea",
+              {
+                "data-foir-feedback-body": true,
+                "aria-label": placeholder,
+                placeholder,
+                required: true,
+                value: body,
+                disabled: busy,
+                onChange: (event) => {
+                  setBody(event.target.value);
+                  if (sent) setSent(false);
+                },
+                style: styled ? textareaStyle : void 0
+              }
+            ),
+            probe.screenshotsEnabled && isFoirScreenCaptureSupported() && /* @__PURE__ */ jsx5(Fragment2, { children: screenshot ? /* @__PURE__ */ jsxs4(Fragment2, { children: [
+              /* @__PURE__ */ jsx5(
+                "img",
+                {
+                  "data-foir-feedback-screenshot": true,
+                  src: screenshot.dataUrl,
+                  alt: COPY.screenshotAlt,
+                  style: styled ? previewStyle : void 0
+                }
+              ),
+              /* @__PURE__ */ jsx5(
+                "button",
+                {
+                  type: "button",
+                  "data-foir-feedback-remove": true,
+                  onClick: () => setScreenshot(null),
+                  disabled: busy,
+                  style: styled ? buttonStyle : void 0,
+                  children: COPY.removeScreenshot
+                }
+              )
+            ] }) : /* @__PURE__ */ jsx5(
+              "button",
+              {
+                type: "button",
+                "data-foir-feedback-capture": true,
+                onClick: () => void capture(),
+                disabled: busy || capturing,
+                style: styled ? buttonStyle : void 0,
+                children: capturing ? COPY.capturing : COPY.capture
+              }
+            ) }),
+            failure && /* @__PURE__ */ jsx5("p", { role: "alert", "data-foir-feedback-error": true, style: styled ? errorStyle2 : void 0, children: failure }),
+            sent && !failure && /* @__PURE__ */ jsx5(
+              "p",
+              {
+                role: "status",
+                "data-foir-feedback-status": true,
+                style: styled ? noteStyle : void 0,
+                children: COPY.sent
+              }
+            ),
+            /* @__PURE__ */ jsx5(
+              "button",
+              {
+                type: "submit",
+                "data-foir-feedback-submit": true,
+                disabled: busy || body.trim() === "",
+                style: styled ? submitStyle2 : void 0,
+                children: busy ? COPY.sending : COPY.send
+              }
+            )
+          ] })
+        ]
+      }
+    )
+  ] });
+}
+function BlockedNotice({
+  fault,
+  onSignIn,
+  styled
+}) {
+  if (fault.kind === "signIn") {
+    return /* @__PURE__ */ jsxs4(Fragment2, { children: [
+      /* @__PURE__ */ jsx5("p", { role: "status", "data-foir-feedback-status": true, style: styled ? noteStyle : void 0, children: COPY.signIn }),
+      onSignIn && /* @__PURE__ */ jsx5(
+        "button",
+        {
+          type: "button",
+          "data-foir-feedback-signin": true,
+          onClick: onSignIn,
+          style: styled ? submitStyle2 : void 0,
+          children: COPY.signInAction
+        }
+      )
+    ] });
+  }
+  return /* @__PURE__ */ jsx5("p", { role: "status", "data-foir-feedback-status": true, style: styled ? noteStyle : void 0, children: fault.kind === "scope" ? COPY.notEnabled : COPY.unavailable });
+}
+function failureCopy(fault) {
+  if (fault.kind === "signIn") return COPY.signIn;
+  if (fault.kind === "scope") return COPY.notEnabled;
+  return COPY.sendFailed;
+}
+function reportFault(fault, err, action) {
+  if (fault.kind === "scope") {
+    console.error(
+      `[foir] <FoirFeedback>: the API refused with "missing required scope: ${fault.scope}". This is not a bad API key: the key reached the surface. The signed-in CUSTOMER's role does not grant ${fault.scope}, and a new project's default customer role does not carry the notes scopes. Add it to the role that customer holds, or to the project's default customer role, and this works with no code change.`,
+      err
+    );
+    return;
+  }
+  if (fault.kind === "other") {
+    console.error(`[foir] <FoirFeedback>: ${action}`, err);
+  }
+}
+function useResolvedSubject(subjects, override) {
+  const subscribe = useCallback2(
+    (listener) => subjects?.subscribe(listener) ?? (() => {
+    }),
+    [subjects]
+  );
+  const snapshot = useCallback2(() => subjects?.subject(), [subjects]);
+  const serverSnapshot = useCallback2(() => void 0, []);
+  const fetched = useSyncExternalStore(subscribe, snapshot, serverSnapshot);
+  if (override !== void 0) return override ?? void 0;
+  return fetched;
+}
+function useNoSubjectNotice(open, resolved, hasRegistry, hasOverride) {
+  const announced = useRef2(false);
+  useEffect3(() => {
+    if (process.env.NODE_ENV === "production") return;
+    if (!open || resolved || announced.current) return;
+    announced.current = true;
+    if (!hasRegistry && !hasOverride) {
+      console.info(
+        "[foir] <FoirFeedback>: no `subjects` registry and no `subject` prop, so this widget can never know what a comment is about. Build one with createFoirSubjectRegistry(), pass it to createFoirClient({ subjects }), and pass the same object here."
+      );
+      return;
+    }
+    console.info(
+      "[foir] <FoirFeedback>: nothing to comment on. Every record this page fetched arrived inside a list or a search result, and the registry deliberately does not promote one of those to be the subject. Read one record by name, or pass the `subject` prop."
+    );
+  }, [open, resolved, hasRegistry, hasOverride]);
+}
 export {
+  FoirFeedback,
   FoirProvider,
   OAuthButtons,
   SignIn,