@foir/sdk 0.8.0 → 0.10.0

package/dist/data.js

@@ -5,11 +5,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);
@@ -17,6 +36,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.
@@ -66,6 +87,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;
@@ -80,14 +104,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 describe2 = (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(describe2).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(describe2).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
       });
     }
   }
@@ -128,6 +183,14 @@ async function hasFoirErrorCode(res, ...codes) {
 }
 
 // src/data/transport.ts
+var FoirSchemaDriftError = class extends FoirRequestError {
+  drift;
+  constructor(message, drift) {
+    super(message);
+    this.name = "FoirSchemaDriftError";
+    this.drift = drift;
+  }
+};
 function foirDataEndpoint(apiUrl, path) {
   return foirApiEndpoint(apiUrl, path);
 }
@@ -139,7 +202,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" };
 }
@@ -152,10 +217,10 @@ async function executeFoirDocument(config, plan) {
   }
   return data[plan.rootField];
 }
-async function executeFoirRawDocument(config, document, mutation, variables) {
-  return await runFoirDocument(config, document, mutation, variables);
+async function executeFoirRawDocument(config, document, mutation, variables, options) {
+  return await runFoirDocument(config, document, mutation, variables, options);
 }
-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);
@@ -163,12 +228,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
   });
@@ -208,7 +275,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 {
@@ -231,6 +298,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 +937,7 @@ var FoirSocketTransport = class {
         apiKey: this.config.apiKey,
         draftChannel: this.config.channel === "draft",
         bearerToken: await resolveBearerToken(this.config),
+        orgId: this.config.orgId,
         extra: this.config.headers
       });
       const { "Content-Type": _contentType, ...params } = headers;
@@ -977,7 +1046,9 @@ var FoirSocketTransport = class {
         return;
       }
       case GQL.error: {
-        const error = new FoirRequestError(`[foir] subscription refused: ${describe(message.payload)}`);
+        const error = new FoirRequestError(`[foir] subscription refused: ${describe(message.payload)}`, {
+          graphQLErrors: graphQLErrorItems(message.payload)
+        });
         if (!message.id) {
           this.failAll(error);
           this.teardownSocket(true);
@@ -1088,6 +1159,21 @@ function defaultWebSocketFactory() {
   }
   return (url, protocols) => new Impl(url, protocols);
 }
+function graphQLErrorItems(payload) {
+  const list = Array.isArray(payload) ? payload : payload == null ? [] : [payload];
+  const items = [];
+  for (const entry of list) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const { message, path, extensions } = entry;
+    if (extensions === void 0 && path === void 0) continue;
+    items.push({
+      message: typeof message === "string" ? message : describe(entry),
+      ...Array.isArray(path) ? { path } : {},
+      ...typeof extensions === "object" && extensions !== null ? { extensions } : {}
+    });
+  }
+  return items.length > 0 ? items : void 0;
+}
 function describe(payload) {
   if (payload == null) return "no reason given";
   if (typeof payload === "string") return payload;
@@ -1133,12 +1219,19 @@ var FoirSubscriptionRouter = class {
     if (method !== "onChange") {
       throw new FoirRequestError(`[foir] ${modelKey}.${method} is not a subscription`);
     }
+    const after = input.after;
+    const args = [{ name: "modelKey", type: "String!" }];
+    const variables = { modelKey };
+    if (typeof after === "number") {
+      args.push({ name: "after", type: "EventSeq" });
+      variables.after = after;
+    }
     return this.open(
       {
         field: "recordChanged",
         operationName: "FoirRecordChanged",
-        args: [{ name: "modelKey", type: "String!" }],
-        variables: { modelKey }
+        args,
+        variables
       },
       input
     );
@@ -1177,7 +1270,7 @@ var FoirSubscriptionRouter = class {
           args: [{ name: "id", type: "String!" }],
           variables: { id }
         },
-        handlers
+        { ...handlers, onData: (event) => handlers.onData(executionEventWithEnumStatus(event)) }
       );
     }
     throw new FoirRequestError(`[foir] ns.${namespace}.${method} is not a subscription`);
@@ -1222,6 +1315,12 @@ var FoirSubscriptionRouter = class {
     };
   }
 };
+function executionEventWithEnumStatus(event) {
+  if (event === null || typeof event !== "object") return event;
+  const status = event.status;
+  if (typeof status !== "string") return event;
+  return { ...event, status: status.toUpperCase() };
+}
 function findSubscription(manifest, field) {
   const found = manifest.subscriptions?.find((s) => s.field === field);
   if (found) return found;
@@ -1369,6 +1468,9 @@ function recordsAt(value, path) {
 }
 
 // src/data/client.ts
+function graphql(document) {
+  return document;
+}
 var NON_MODEL_PROPS = /* @__PURE__ */ new Set([
   "then",
   "catch",
@@ -1500,19 +1602,26 @@ function resolveGeneratedConfig(config) {
       `[foir] createFoirClient: \`generated.foirSelectionUnions["${name}"]\` has no \`members\`. A tree that names this union would print an empty selection set. Re-run \`foir types\`.`
     );
   }
+  const subscriptions = generated["foirSubscriptions"];
+  if (subscriptions !== void 0 && !Array.isArray(subscriptions)) {
+    throw new FoirRequestError(
+      "[foir] createFoirClient: `generated.foirSubscriptions` is not an array of subscription descriptors. Re-run `foir types`."
+    );
+  }
   return {
     ...config,
     schemaVersion: config.schemaVersion ?? version,
     selections: config.selections ?? selections,
     namespaceSelections: config.namespaceSelections ?? namespaceSelections,
-    selectionUnions: config.selectionUnions ?? selectionUnions
+    selectionUnions: config.selectionUnions ?? selectionUnions,
+    subscriptions: config.subscriptions ?? subscriptions
   };
 }
 function announceFallback(config) {
   if (config.generated !== void 0 || config.selections !== void 0) return;
   if (config.announceManifestFallback === false) return;
   console.info(
-    "[foir] no generated module passed, so this client fetches `GET /v1/manifest` once at first use and prints from the trees it publishes. That works \u2014 it is what makes a zero-codegen start possible \u2014 but it puts a round trip in front of the first query on every cold start. Run `foir types`, then `import * as generated from './foir.generated'` and pass `generated`. Silence this with `announceManifestFallback: false`."
+    "[foir] no generated module passed, so this client fetches `GET /v1/manifest` once at first use and prints from the trees it publishes. That works \u2014 it is what makes a zero-codegen start possible \u2014 but it puts a round trip in front of the first query on every cold start. Run `foir types`, then `import * as generated from './foir.generated'` and pass `generated`. Silence this with `announceManifestFallback: false`.\n[foir] A subscribe-only client can now take that advice too: `foir types` emits `foirSubscriptions` alongside the model trees, so a generated client prints its subscribe document from the module and makes no request at all. Weigh the module against one fetch behind a socket that lives for the whole session \u2014 on a phone the fallback may still be the better trade."
   );
 }
 function createFoirClient(clientConfig) {
@@ -1522,6 +1631,7 @@ function createFoirClient(clientConfig) {
   const config = resolveGeneratedConfig(clientConfig);
   announceFallback(config);
   let driftChecked = false;
+  let detectedDrift;
   let manifestOnce;
   const manifest = () => {
     if (!manifestOnce) {
@@ -1542,6 +1652,16 @@ function createFoirClient(clientConfig) {
     }
     return manifest();
   };
+  const sameSurface = (a, b) => {
+    const stable = (v) => {
+      if (Array.isArray(v)) return v.map(stable);
+      if (v && typeof v === "object") {
+        return Object.keys(v).sort().map((k) => [k, stable(v[k])]);
+      }
+      return v;
+    };
+    return JSON.stringify(stable(a)) === JSON.stringify(stable(b));
+  };
   const maybeCheckDrift = () => {
     const generated = config.schemaVersion;
     if (driftChecked) return;
@@ -1550,11 +1670,15 @@ function createFoirClient(clientConfig) {
     driftChecked = true;
     void manifest().then((served) => {
       if (served.schemaVersion === generated) return;
+      if (sameSurface(config.selections, served.models) && sameSurface(config.namespaceSelections ?? {}, served.namespaces ?? {}) && sameSurface(config.selectionUnions ?? {}, served.selectionUnions ?? {})) {
+        return;
+      }
       const drift = {
         generated,
         server: served.schemaVersion,
         channel: served.channel
       };
+      detectedDrift = drift;
       if (config.onSchemaDrift) {
         config.onSchemaDrift(drift);
         return;
@@ -1565,7 +1689,15 @@ function createFoirClient(clientConfig) {
     }).catch(() => {
     });
   };
+  const assertNoStaleSelections = (what) => {
+    if (config.strictSchemaDrift === false || !detectedDrift) return;
+    throw new FoirSchemaDriftError(
+      `[foir] refusing ${what}: types were generated from schemaVersion ${detectedDrift.generated}, the server is serving ${detectedDrift.server} (${detectedDrift.channel}). The selection trees this client prints from are the ones that version published, so a field added since is not requested at all. Re-run \`foir types\`. Set \`strictSchemaDrift: false\` to warn instead.`,
+      detectedDrift
+    );
+  };
   const runModel = async (model, op, query) => {
+    assertNoStaleSelections(`${model}.${op}`);
     const { args, include, omit, pick, depth } = splitQuery(query);
     const plan = planFoirModelCall(await selectionSource(), {
       model,
@@ -1582,6 +1714,7 @@ function createFoirClient(clientConfig) {
     return result;
   };
   const runNamespace = async (namespace, op, query) => {
+    assertNoStaleSelections(`ns.${namespace}.${op}`);
     const { args, include, omit, pick, depth } = splitQuery(query);
     const plan = planFoirNamespaceCall(await selectionSource(), {
       namespace,
@@ -1597,11 +1730,18 @@ function createFoirClient(clientConfig) {
     maybeCheckDrift();
     return result;
   };
+  const subscriptionManifest = () => {
+    if (!config.subscriptions) return manifest();
+    return Promise.resolve({
+      subscriptions: config.subscriptions,
+      selectionUnions: config.selectionUnions
+    });
+  };
   const subscriptions = /* @__PURE__ */ (() => {
     const held = { router: null };
     return {
       get() {
-        held.router ??= new FoirSubscriptionRouter(config, manifest);
+        held.router ??= new FoirSubscriptionRouter(config, subscriptionManifest);
         return held.router;
       },
       dispose() {
@@ -1629,7 +1769,7 @@ function createFoirClient(clientConfig) {
       return opProxy({ namespace });
     }
   });
-  const raw = async (document, variables) => {
+  const raw = async (document, variables, options) => {
     if (typeof document !== "string" || !document.trim()) {
       throw new FoirRequestError("[foir] raw() takes a GraphQL document string");
     }
@@ -1637,7 +1777,8 @@ function createFoirClient(clientConfig) {
       config,
       document,
       isFoirMutationDocument(document),
-      variables
+      variables,
+      options
     );
     maybeCheckDrift();
     return result;
@@ -1666,16 +1807,236 @@ function createFoirClientFromEnv(env, overrides) {
     channel: isFoirPreview(env) ? "draft" : "published"
   });
 }
+
+// src/data/decimal.ts
+var DECIMAL_PATTERN = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+var MAX_SCALE = 1e3;
+function pow10(n) {
+  return 10n ** BigInt(n);
+}
+function divRound(numerator, denominator, rounding) {
+  if (denominator === 0n) throw new RangeError("FoirDecimal: division by zero");
+  const negative = numerator < 0n !== denominator < 0n;
+  const n = numerator < 0n ? -numerator : numerator;
+  const d = denominator < 0n ? -denominator : denominator;
+  let quotient = n / d;
+  const remainder = n % d;
+  if (remainder !== 0n && rounding !== "down") {
+    const doubled = remainder * 2n;
+    if (doubled > d) {
+      quotient += 1n;
+    } else if (doubled === d) {
+      if (rounding === "half-up" || quotient % 2n === 1n) quotient += 1n;
+    }
+  }
+  return negative ? -quotient : quotient;
+}
+function parse(input) {
+  const text = input.trim();
+  if (!DECIMAL_PATTERN.test(text)) {
+    throw new TypeError(
+      `FoirDecimal: ${JSON.stringify(input)} is not a decimal. Expected a numeric string such as "19.99".`
+    );
+  }
+  const [mantissa, exponentText] = text.split(/[eE]/);
+  const exponent = exponentText ? Number(exponentText) : 0;
+  const negative = mantissa.startsWith("-");
+  const unsigned = negative || mantissa.startsWith("+") ? mantissa.slice(1) : mantissa;
+  const [integerPart = "", fractionPart = ""] = unsigned.split(".");
+  let units = BigInt(`${integerPart || "0"}${fractionPart}`);
+  let scale = fractionPart.length - exponent;
+  if (scale < 0) {
+    units *= pow10(-scale);
+    scale = 0;
+  }
+  if (scale > MAX_SCALE) {
+    throw new RangeError(`FoirDecimal: scale ${scale} exceeds the maximum of ${MAX_SCALE}`);
+  }
+  return { units: negative ? -units : units, scale };
+}
+var FoirDecimal = class _FoirDecimal {
+  // Not `readonly` only so `#of` can populate a fresh instance without going
+  // back through the string parser. Never mutated after construction, and
+  // `#`-private so immutability is not part of the public contract to keep.
+  #units;
+  #scale;
+  constructor(value) {
+    if (value instanceof _FoirDecimal) {
+      this.#units = value.#units;
+      this.#scale = value.#scale;
+      return;
+    }
+    if (typeof value === "bigint") {
+      this.#units = value;
+      this.#scale = 0;
+      return;
+    }
+    if (typeof value !== "string") {
+      throw new TypeError(
+        `FoirDecimal: refusing to construct from ${typeof value}. A JavaScript number is a float and may already have lost precision \u2014 pass the string, or use FoirDecimal.fromNumber() to accept that loss explicitly.`
+      );
+    }
+    const { units, scale } = parse(value);
+    this.#units = units;
+    this.#scale = scale;
+  }
+  /**
+   * Build a decimal from a JavaScript number, accepting the precision that
+   * number may already have lost.
+   *
+   * Deliberately not the constructor. It is for interop — a value read from a
+   * third-party JSON API that emitted a float — and naming it at every call
+   * site is the point. `fromNumber(0.1 + 0.2)` gives `0.30000000000000004`,
+   * because that is genuinely the value it was handed.
+   */
+  static fromNumber(value) {
+    if (!Number.isFinite(value)) {
+      throw new RangeError(`FoirDecimal: ${value} is not a finite number`);
+    }
+    return new _FoirDecimal(value.toPrecision(17));
+  }
+  /** `true` if `value` parses as a decimal. Does not throw. */
+  static isDecimalString(value) {
+    return typeof value === "string" && DECIMAL_PATTERN.test(value.trim());
+  }
+  /** Decimal places carried by this value. `19.90` has scale 2. */
+  get scale() {
+    return this.#scale;
+  }
+  /** Re-express at `scale`, rounding away any digits that no longer fit. */
+  rescale(scale, rounding = "half-up") {
+    if (!Number.isInteger(scale) || scale < 0 || scale > MAX_SCALE) {
+      throw new RangeError(`FoirDecimal: scale must be an integer in 0..${MAX_SCALE}, got ${scale}`);
+    }
+    if (scale === this.#scale) return this;
+    const units = scale > this.#scale ? this.#units * pow10(scale - this.#scale) : divRound(this.#units, pow10(this.#scale - scale), rounding);
+    return _FoirDecimal.#of(units, scale);
+  }
+  add(other) {
+    const [a, b, scale] = _FoirDecimal.#align(this, other);
+    return _FoirDecimal.#of(a + b, scale);
+  }
+  sub(other) {
+    const [a, b, scale] = _FoirDecimal.#align(this, other);
+    return _FoirDecimal.#of(a - b, scale);
+  }
+  /** Exact: scales add, so `1.10 × 1.10` is `1.2100` rather than `1.21`. */
+  mul(other) {
+    const rhs = new _FoirDecimal(other);
+    return _FoirDecimal.#of(this.#units * rhs.#units, this.#scale + rhs.#scale);
+  }
+  /** The only inexact operation — see {@link FoirDecimalDivOptions}. */
+  div(other, options = {}) {
+    const { scale = 20, rounding = "half-even" } = options;
+    if (!Number.isInteger(scale) || scale < 0 || scale > MAX_SCALE) {
+      throw new RangeError(`FoirDecimal: scale must be an integer in 0..${MAX_SCALE}, got ${scale}`);
+    }
+    const rhs = new _FoirDecimal(other);
+    const numerator = this.#units * pow10(rhs.#scale + scale);
+    const denominator = rhs.#units * pow10(this.#scale);
+    return _FoirDecimal.#of(divRound(numerator, denominator, rounding), scale);
+  }
+  abs() {
+    return this.#units < 0n ? _FoirDecimal.#of(-this.#units, this.#scale) : this;
+  }
+  neg() {
+    return _FoirDecimal.#of(-this.#units, this.#scale);
+  }
+  isZero() {
+    return this.#units === 0n;
+  }
+  isNegative() {
+    return this.#units < 0n;
+  }
+  /** `-1`, `0` or `1`. Use this rather than `<`, which throws. */
+  cmp(other) {
+    const [a, b] = _FoirDecimal.#align(this, other);
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+  /** Numeric equality: `1.0` equals `1.00`. Scale is display, not identity. */
+  equals(other) {
+    return this.cmp(other) === 0;
+  }
+  /**
+   * Fixed-place string, rounding `half-up` by default because this is the
+   * display operation and that is what a person means by "to 2dp".
+   */
+  toFixed(places, rounding = "half-up") {
+    return this.rescale(places, rounding).toString();
+  }
+  /**
+   * The canonical wire form, preserving scale. Never exponent notation, so the
+   * output always parses back to an equal value.
+   */
+  toString() {
+    const negative = this.#units < 0n;
+    const digits = (negative ? -this.#units : this.#units).toString();
+    if (this.#scale === 0) return negative ? `-${digits}` : digits;
+    const padded = digits.padStart(this.#scale + 1, "0");
+    const integerPart = padded.slice(0, padded.length - this.#scale);
+    const fractionPart = padded.slice(padded.length - this.#scale);
+    return `${negative ? "-" : ""}${integerPart}.${fractionPart}`;
+  }
+  /** `JSON.stringify` emits the canonical string, not an object. Pinned by test. */
+  toJSON() {
+    return this.toString();
+  }
+  /**
+   * Explicitly lossy — this is the boundary back into float, and naming it is
+   * the point. Fine for a chart axis; never for money you will add up.
+   */
+  toNumber() {
+    return Number(this.toString());
+  }
+  /**
+   * Answers the `'string'` hint so template literals work, and throws on every
+   * other hint so `+`, `<` and `Number()` fail loudly instead of silently
+   * concatenating or truncating.
+   */
+  [Symbol.toPrimitive](hint) {
+    if (hint === "string") return this.toString();
+    throw new TypeError(
+      hint === "number" ? "FoirDecimal: cannot be coerced to a number implicitly. Use .toNumber() to accept the precision loss, or .cmp() to compare." : "FoirDecimal: cannot be coerced implicitly. Use .add() / .sub() / .mul() / .div() for arithmetic, .cmp() to compare, or .toString() for text."
+    );
+  }
+  get [Symbol.toStringTag]() {
+    return "FoirDecimal";
+  }
+  /** Skip parsing when the units are already known to be well-formed. */
+  static #of(units, scale) {
+    const instance = new _FoirDecimal(0n);
+    instance.#units = units;
+    instance.#scale = scale;
+    return instance;
+  }
+  /** Bring two values to a common scale so their units can be compared. */
+  static #align(left, right) {
+    const rhs = new _FoirDecimal(right);
+    const scale = Math.max(left.#scale, rhs.#scale);
+    return [
+      left.#units * pow10(scale - left.#scale),
+      rhs.#units * pow10(scale - rhs.#scale),
+      scale
+    ];
+  }
+};
+function decimal(value) {
+  return new FoirDecimal(value);
+}
 export {
+  FoirDecimal,
   FoirRequestError,
+  FoirSchemaDriftError,
   FoirSocketTransport,
   createFoirClient,
   createFoirClientFromEnv,
   createFoirSubjectRegistry,
+  decimal,
   fetchFoirManifest,
   foirDataEndpoint,
   foirRoute,
   foirSocketEndpoint,
+  graphql,
   planFoirModelCall,
   planFoirNamespaceCall,
   printSubscriptionDocument,

package/dist/graphql/cdn-route.d.ts

@@ -21,6 +21,6 @@ export { buildCdnUrl, documentHash, hasFoirErrorCode, NOT_SHAREABLE, PERSISTED_Q
  * `/graphql` when it does — but every condition checked here is one round trip
  * saved.
  */
-export declare function isCdnEligible(env: FoirEnv, documentText: string, bearerToken?: string): boolean;
+export declare function isCdnEligible(env: FoirEnv, documentText: string, bearerToken?: string, orgId?: string): boolean;
 /** Print a document once, so eligibility and the URL agree on the same text. */
 export declare function printDocument<TData, TVariables>(document: TypedDocumentNode<TData, TVariables>): string;

package/dist/graphql/foir-request.d.ts

@@ -24,7 +24,7 @@
  */
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { type FoirEnv, type FoirRequestOptions } from '../transport/foir-http';
-export { FoirRequestError, isFoirPreview, isFoirRateLimited, isFoirUnauthenticated, isFoirForbidden, isFoirNotFound, readFoirRateLimit, type FoirEnv, type FoirErrorCode, type FoirErrorExtensions, type FoirGraphQLErrorItem, type FoirRateLimitSnapshot, type FoirRequestOptions, } from '../transport/foir-http';
+export { FoirRequestError, isFoirPreview, isFoirRateLimited, isFoirUnauthenticated, isFoirForbidden, isFoirNotFound, readFoirRateLimit, type FoirEnv, type FoirErrorCode, type FoirErrorExtensions, type FoirGraphQLErrorItem, type FoirRateLimitSnapshot, type FoirRequestOptions, type FoirAuthDowngrade, } from '../transport/foir-http';
 export { withFoirRetry, foirRetryDelayMs, type FoirRetryPolicy, } from '../transport/retry';
 /** Default Foir CDN origin used to absolutise relative media URLs. */
 export declare const FOIR_CDN_BASE = "https://cdn.foir.dev/";