@foir/sdk 0.11.0 → 0.12.0

package/dist/app.js

@@ -0,0 +1,998 @@
+// src/transport/foir-http.ts
+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);
+    this.name = "FoirRequestError";
+    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.
+   *
+   * 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) {
+      if (this.graphQLErrors?.length || this.prunedSelections?.length) {
+        return this.code === "RATE_LIMITED" || this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
+      }
+      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;
+  }
+};
+var DISPATCH_RESERVED_HEADERS = /* @__PURE__ */ new Set([
+  "x-api-key",
+  "authorization",
+  "x-foir-token",
+  "x-foir-context"
+]);
+function refuseCredentialHeaders(extra) {
+  if (!extra) return;
+  for (const name of Object.keys(extra)) {
+    if (DISPATCH_RESERVED_HEADERS.has(name.toLowerCase())) {
+      throw new FoirRequestError(
+        `[foir] a client built from a dispatch token cannot send "${name}" in \`headers\`. The dispatch token is the credential, and an api key or a bearer beside it would make the request two actors at once. Build a separate client for the other credential.`
+      );
+    }
+  }
+}
+var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
+function buildFoirHeaders(input) {
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (input.dispatchToken !== void 0) {
+    refuseCredentialHeaders(input.extra);
+    headers["X-Foir-Token"] = input.dispatchToken;
+    if (input.dispatchContext) {
+      headers["X-Foir-Context"] = input.dispatchContext;
+    }
+  } else {
+    headers["x-api-key"] = input.apiKey;
+    if (input.draftChannel) {
+      headers["X-Foir-Schema-Channel"] = "draft";
+    }
+    if (input.bearerToken) {
+      headers["Authorization"] = `Bearer ${input.bearerToken}`;
+    }
+    if (input.orgId) {
+      headers["X-Org-Id"] = input.orgId;
+    }
+    if (input.orgUrl) {
+      headers["X-Org-Url"] = input.orgUrl;
+    }
+    if (input.visitorAddress) {
+      headers[FOIR_VISITOR_IP_HEADER] = input.visitorAddress;
+    }
+  }
+  if (input.extra) {
+    for (const [key, value] of Object.entries(input.extra)) {
+      headers[key] = value;
+    }
+  }
+  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");
+  }
+  return base + path;
+}
+var FoirAuthDowngradedError = class extends FoirRequestError {
+  downgrade;
+  constructor(downgrade) {
+    super(
+      `[foir] your customer token was ${downgrade.customerToken} (${downgrade.reason}), so the request was served as ${downgrade.servedAs}`,
+      { graphQLErrors: [{ message: "customer token rejected", extensions: { code: "AUTH_DOWNGRADED" } }] }
+    );
+    this.name = "FoirAuthDowngradedError";
+    this.downgrade = downgrade;
+  }
+};
+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 answeredAnything(data) {
+  return typeof data === "object" && data !== null && Object.values(data).some((value) => value !== null && value !== void 0);
+}
+function readFoirEnvelope(json, options) {
+  if (options?.rejectDowngrade && json.extensions?.auth) {
+    throw new FoirAuthDowngradedError(json.extensions.auth);
+  }
+  reportAuthDowngrade(json);
+  refusePrunedDocument(json, options);
+  if (json.errors?.length) {
+    const msg = json.errors.map((e) => e.message).join("; ");
+    if (answeredAnything(json.data) && !options?.strict) {
+      console.warn(`[foir] GraphQL partial errors (data returned): ${msg}`);
+    } else {
+      throw new FoirRequestError(`[foir] GraphQL errors: ${msg}`, {
+        graphQLErrors: json.errors,
+        partialData: json.data ?? void 0
+      });
+    }
+  }
+  if (!json.data) {
+    throw new FoirRequestError("[foir] empty GraphQL response");
+  }
+  return json.data;
+}
+
+// src/transport/retry.ts
+var DEFAULT_ATTEMPTS = 3;
+var DEFAULT_BASE_DELAY_MS = 200;
+var DEFAULT_MAX_DELAY_MS = 2e4;
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function foirRetryDelayMs(error, attempt, policy = {}) {
+  if (!(error instanceof FoirRequestError) || !error.retryable) return null;
+  const max = policy.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+  const stated = error.retryAfterMs;
+  if (stated !== void 0) return Math.min(stated, max);
+  const base = policy.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  return Math.min(base * 2 ** (attempt - 1), max);
+}
+async function withFoirRetry(fn, policy = {}) {
+  const attempts = Math.max(1, policy.attempts ?? DEFAULT_ATTEMPTS);
+  const sleep = policy.sleep ?? defaultSleep;
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      const delayMs = attempt >= attempts ? null : foirRetryDelayMs(error, attempt, policy);
+      if (delayMs === null) throw error;
+      policy.onRetry?.({ attempt, delayMs, error });
+      await sleep(delayMs);
+    }
+  }
+}
+
+// src/app/errors.ts
+function extensionOf(error, key) {
+  if (!(error instanceof FoirRequestError)) return null;
+  for (const entry of error.graphQLErrors ?? []) {
+    const value = entry.extensions?.[key];
+    if (value && typeof value === "object" && !Array.isArray(value)) return value;
+  }
+  return null;
+}
+function appLookupConflictOf(error) {
+  const conflict = extensionOf(error, "lookupConflict");
+  if (!conflict) return null;
+  const { model, lookup, keyBy } = conflict;
+  if (typeof model !== "string" || typeof lookup !== "string" || !Array.isArray(keyBy)) return null;
+  if (!keyBy.every((field) => typeof field === "string")) return null;
+  return { model, lookup, keyBy };
+}
+function appCustomerUnlinkedOf(error) {
+  const unlinked = extensionOf(error, "customerUnlinked");
+  if (!unlinked) return null;
+  const { model, identityProvider } = unlinked;
+  if (typeof model !== "string" || typeof identityProvider !== "string") return null;
+  return { model, identityProvider };
+}
+function isAppFieldWithheld(error, field) {
+  if (!(error instanceof FoirRequestError)) return false;
+  return (error.prunedSelections ?? []).some((selection) => {
+    if (selection.reason !== "unknown_field") return false;
+    if (field === void 0) return true;
+    const steps = selection.path.split(".");
+    return steps.length === 2 && steps[1] === field;
+  });
+}
+
+// src/app/naming.ts
+function appModelTypeName(modelKey) {
+  return modelKey.split(/[^a-zA-Z0-9]+/).filter((part) => part !== "").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function appModelFieldName(modelKey) {
+  const type = appModelTypeName(modelKey);
+  return type === "" ? "" : type.charAt(0).toLowerCase() + type.slice(1);
+}
+function appSelectorEnumValue(fieldKey) {
+  const cleaned = fieldKey.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+  if (cleaned === "") return "_";
+  return /^[0-9]/.test(cleaned) ? `_${cleaned}` : cleaned;
+}
+function isSelectableFieldKey(fieldKey) {
+  return /^[_A-Za-z][_0-9A-Za-z]*$/.test(fieldKey);
+}
+
+// src/app/client.ts
+var RECORD_ID_FIELD = "_id";
+var RECORD_NATURAL_KEY_FIELD = "_naturalKey";
+var RECORD_OWNER_FIELD = "_ownerId";
+function createAppClient(config) {
+  if (!config.apiUrl) throw new FoirRequestError("[foir] createAppClient needs `apiUrl`, the data API origin");
+  if (!config.dispatch || typeof config.dispatch.token !== "function") {
+    throw new FoirRequestError(
+      "[foir] createAppClient needs `dispatch`, the token to call as: `(await requireScopedToken(request)).dispatch`"
+    );
+  }
+  const endpoint = foirApiEndpoint(config.apiUrl, "/graphql");
+  const doFetch = config.fetch ?? globalThis.fetch;
+  async function send(document, variables) {
+    const token = (await config.dispatch.token())?.trim();
+    if (!token) {
+      throw new FoirRequestError(
+        "[foir] the dispatch token provider returned no token. An app client calls as the token it was built from."
+      );
+    }
+    let res;
+    try {
+      res = await doFetch(endpoint, {
+        ...config.requestInit,
+        method: "POST",
+        headers: buildFoirHeaders({ dispatchToken: token, dispatchContext: config.dispatch.context ?? void 0 }),
+        body: JSON.stringify({ query: document, variables })
+      });
+    } catch (err) {
+      throw new FoirRequestError("[foir] network error", { cause: err });
+    }
+    if (!res.ok) {
+      let errors;
+      try {
+        const body = await res.json();
+        errors = body?.errors?.length ? body.errors : void 0;
+      } catch {
+        errors = void 0;
+      }
+      const detail = errors ? `: ${errors.map((e) => e.message).join("; ")}` : "";
+      throw new FoirRequestError(`[foir] HTTP ${res.status} ${res.statusText}${detail}`, {
+        status: res.status,
+        ...errors ? { graphQLErrors: errors } : {}
+      });
+    }
+    const json = await res.json();
+    return readFoirEnvelope(json, { strict: true });
+  }
+  const run = (document, variables) => withFoirRetry(() => send(document, variables), config.retry);
+  async function field(name, document, variables) {
+    const data = await run(document, variables);
+    if (!(name in data)) {
+      throw new FoirRequestError(`[foir] the response has no "${name}" field`);
+    }
+    return data[name];
+  }
+  const refuse = (message) => {
+    throw new FoirRequestError(`[foir] ${message}`);
+  };
+  async function readOne(model, by, fields) {
+    const byId = "id" in by;
+    const value = byId ? by.id : by.naturalKey;
+    if (value === "") refuse(`a record read on ${model} was given an empty ${byId ? "id" : "natural key"}`);
+    const name = appModelFieldName(model);
+    const selectable = fields.filter(isSelectableFieldKey);
+    let unreadable = fields.filter((key2) => !isSelectableFieldKey(key2));
+    const ask = (selection) => field(
+      name,
+      byId ? `query AppReadRecordById($id: String!) { ${name}(id: $id) { ${[RECORD_ID_FIELD, RECORD_NATURAL_KEY_FIELD, RECORD_OWNER_FIELD, ...selection].join(" ")} } }` : `query AppReadRecord($naturalKey: String!) { ${name}(naturalKey: $naturalKey) { ${[RECORD_ID_FIELD, RECORD_NATURAL_KEY_FIELD, RECORD_OWNER_FIELD, ...selection].join(" ")} } }`,
+      byId ? { id: value } : { naturalKey: value }
+    );
+    let answer;
+    try {
+      answer = await ask(selectable);
+    } catch (error) {
+      if (!(error instanceof FoirRequestError) || isAppFieldWithheld(error, name) || selectable.length === 0) throw error;
+      if (error.retryable || !error.prunedSelections?.length && !error.graphQLErrors?.length) throw error;
+      answer = await ask([]);
+      unreadable = [...fields];
+    }
+    if (!answer) return null;
+    const id = answer[RECORD_ID_FIELD];
+    if (typeof id !== "string" || id === "") refuse(`${name} answered a record carrying no id`);
+    const values = {};
+    if (unreadable.length < fields.length) {
+      for (const key2 of selectable) {
+        const got = answer[key2];
+        if (got !== void 0) values[key2] = got;
+      }
+    }
+    const key = answer[RECORD_NATURAL_KEY_FIELD];
+    const owner = answer[RECORD_OWNER_FIELD];
+    return {
+      id,
+      naturalKey: typeof key === "string" && key !== "" ? key : null,
+      ownerId: typeof owner === "string" && owner !== "" ? owner : null,
+      fields: values,
+      unreadable: [...unreadable]
+    };
+  }
+  return {
+    request: (document, variables) => run(document, variables),
+    async whoami() {
+      const me = await field(
+        "whoami",
+        `query AppWhoami { whoami { credential { app capabilities expiresAt modelConfinement { read write delete publish } } authority { effective } } }`
+      );
+      const models = me.credential?.modelConfinement;
+      return {
+        app: me.credential?.app ?? null,
+        capabilities: me.credential?.capabilities ?? [],
+        models: {
+          read: models?.read ?? [],
+          write: models?.write ?? [],
+          delete: models?.delete ?? [],
+          publish: models?.publish ?? []
+        },
+        effective: me.authority?.effective ?? [],
+        expiresAt: me.credential?.expiresAt ?? null
+      };
+    },
+    install: {
+      async config() {
+        const raw = await field(
+          "integrationConfig",
+          `query AppInstallConfig {
+            integrationConfig {
+              name enabled middlewareUrl targetModels webhookUrl config
+              sources { key model naturalKey mode fields { appField modelField direction } }
+              sinks { key model naturalKey fields { appField modelField direction } }
+            }
+          }`
+        );
+        if (!raw) refuse("the platform answered the install configuration with nothing at all");
+        const got = raw;
+        return {
+          name: got.name ?? "",
+          enabled: got.enabled === true,
+          middlewareUrl: got.middlewareUrl ?? "",
+          targetModels: got.targetModels ?? [],
+          webhookUrl: got.webhookUrl ?? "",
+          settings: got.config ?? {},
+          sources: bindingsOf(got.sources),
+          sinks: bindingsOf(got.sinks)
+        };
+      },
+      async credentials() {
+        const answer = await field("appCredential", "query AppCredential { appCredential { value } }");
+        const decoded = decodeBase64Utf8(answer?.value ?? "");
+        let parsed;
+        try {
+          parsed = JSON.parse(decoded || "{}");
+        } catch {
+          return refuse("the install credential is not the JSON object of fields the platform stores");
+        }
+        const out = {};
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+          for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value === "string") out[key] = value;
+          }
+        }
+        return out;
+      },
+      async writeCredentials(values) {
+        const scalars = {};
+        for (const [key, value] of Object.entries(values)) {
+          if (typeof value === "string" && value !== "") scalars[key] = value;
+        }
+        if (Object.keys(scalars).length === 0) {
+          refuse("a credential write needs at least one non-empty field; the platform refuses an empty one");
+        }
+        await field(
+          "writeAppCredential",
+          "mutation AppWriteCredential($value: String!) { writeAppCredential(value: $value) }",
+          { value: encodeBase64Utf8(JSON.stringify(scalars)) }
+        );
+      },
+      async reportStatus(status) {
+        const input = {};
+        for (const [key, value] of Object.entries(status)) {
+          if (value === void 0) continue;
+          if ((key === "lastSyncAt" || key === "lastErrorAt") && typeof value === "string" && !Number.isFinite(Date.parse(value))) {
+            refuse(`${key} must be an RFC 3339 time`);
+          }
+          input[key] = value;
+        }
+        if (Object.keys(input).length === 0) return;
+        await field(
+          "reportIntegrationStatus",
+          "mutation AppReportStatus($status: IntegrationStatusInput!) { reportIntegrationStatus(status: $status) }",
+          { status: input }
+        );
+      }
+    },
+    records: {
+      async upsert(input) {
+        const { model, naturalKey, data, ownerId, sourceModifiedAt } = input;
+        if (naturalKey === "") refuse(`an upsert on ${model} was given an empty natural key, which would collide every row onto one record`);
+        if (ownerId === "") refuse(`an upsert on ${model} named an empty owner`);
+        const params = ["$modelKey: String!", "$naturalKey: String!", "$data: JSON!"];
+        const args = ["modelKey: $modelKey", "naturalKey: $naturalKey", "data: $data"];
+        const variables = { modelKey: model, naturalKey, data };
+        if (ownerId !== void 0) {
+          params.push("$ownerId: ID");
+          args.push("ownerId: $ownerId");
+          variables.ownerId = ownerId;
+        }
+        const timed = sourceModifiedAt !== void 0;
+        if (timed) {
+          params.push("$sourceModifiedAt: String");
+          args.push("sourceModifiedAt: $sourceModifiedAt");
+          variables.sourceModifiedAt = sourceModifiedAt;
+        }
+        const answer = await field(
+          "upsertRecord",
+          `mutation AppUpsertRecord(${params.join(", ")}) { upsertRecord(${args.join(", ")}) { record created${timed ? " stale" : ""} } }`,
+          variables
+        );
+        const record = answer?.record;
+        if (!record || typeof record !== "object" || Array.isArray(record)) {
+          return refuse(`upsertRecord reported no error and returned no record for "${naturalKey}" on ${model}`);
+        }
+        const written = firstString(record, ["naturalKey", "natural_key"]);
+        if (written !== null && written !== naturalKey) {
+          refuse(`upsertRecord was sent the natural key "${naturalKey}" for ${model} and answered with "${written}"`);
+        }
+        return {
+          record,
+          id: recordIdOf(record),
+          created: answer?.created === true,
+          stale: answer?.stale === true
+        };
+      },
+      read: readOne,
+      async delete(model, id) {
+        if (id === "") refuse(`a record delete on ${model} was given an empty id`);
+        const name = `delete${appModelTypeName(model)}`;
+        const deleted = await field(name, `mutation AppDeleteRecord($id: String!) { ${name}(id: $id) }`, { id });
+        return { deleted: deleted === true };
+      },
+      async refresh(model, idOrKey) {
+        if (idOrKey === "") refuse(`a record refresh on ${model} was given an empty name`);
+        const name = `refresh${appModelTypeName(model)}`;
+        const refreshed = await field(name, `mutation AppRefreshRecord($idOrKey: String!) { ${name}(idOrKey: $idOrKey) }`, { idOrKey });
+        if (typeof refreshed !== "boolean") return refuse(`${name} reported no error and did not say whether it refreshed the record`);
+        return { refreshed };
+      },
+      async rename(model, where, naturalKey) {
+        if (Object.keys(where).length === 0) refuse(`a rename on ${model} named no filter, so it names no one record`);
+        if (naturalKey === "") refuse(`a rename on ${model} was given an empty key`);
+        const type = appModelTypeName(model);
+        const name = `rename${type}`;
+        await field(
+          name,
+          `mutation AppRenameRecord($where: ${type}WhereInput!, $naturalKey: String!) { ${name}(where: $where, naturalKey: $naturalKey) { replayed } }`,
+          { where, naturalKey }
+        );
+      },
+      async updateMany(model, input) {
+        if (Object.keys(input.where).length === 0) refuse(`an update on ${model} named no filter, which would change every record`);
+        if (Object.keys(input.data).length === 0) refuse(`an update on ${model} named nothing to change`);
+        const type = appModelTypeName(model);
+        const name = `updateMany${type}`;
+        const answer = await field(
+          name,
+          `mutation AppUpdateRecords($where: ${type}WhereInput, $data: ${type}UpdateInput!, $idempotencyKey: String) { ${name}(where: $where, data: $data, idempotencyKey: $idempotencyKey) { count ids } }`,
+          { where: input.where, data: input.data, ...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {} }
+        );
+        if (!answer || typeof answer.count !== "number") {
+          return refuse(`${name} reported no error and did not say how many records it updated`);
+        }
+        return { count: answer.count, ids: Array.isArray(answer.ids) ? answer.ids : [] };
+      },
+      async aggregate(model, query) {
+        if (query.groupBy === "") refuse(`a count on ${model} was grouped by an empty field`);
+        const type = appModelTypeName(model);
+        const name = `${appModelFieldName(model)}Aggregate`;
+        const answer = await field(
+          name,
+          `query AppAggregateRecords($where: ${type}WhereInput, $groupBy: ${type}AggregatableField, $limit: Int) { ${name}(where: $where, groupBy: $groupBy, limit: $limit) { groups { key count } truncated } }`,
+          {
+            groupBy: appSelectorEnumValue(query.groupBy),
+            ...query.where && Object.keys(query.where).length > 0 ? { where: query.where } : {},
+            ...query.limit === void 0 ? {} : { limit: query.limit }
+          }
+        );
+        if (!answer || !Array.isArray(answer.groups)) return refuse(`${name} reported no error and returned no groups`);
+        return {
+          groups: answer.groups.map((group) => ({
+            key: typeof group.key === "string" ? group.key : null,
+            count: typeof group.count === "number" ? group.count : 0
+          })),
+          truncated: answer.truncated === true
+        };
+      },
+      customer: {
+        async save(input) {
+          const { model, identity, data, email, sourceModifiedAt } = input;
+          if (identity === "") refuse(`a customer's record on ${model} was saved with no identity`);
+          const variables = { modelKey: model, identity, data };
+          if (email !== void 0 && email !== "") variables.email = email;
+          const timed = sourceModifiedAt !== void 0;
+          if (timed) variables.sourceModifiedAt = sourceModifiedAt;
+          let answer;
+          try {
+            answer = await field(
+              "saveCustomerRecord",
+              timed ? `mutation AppSaveCustomerRecord($modelKey: String!, $identity: String!, $email: String, $data: JSON!, $sourceModifiedAt: String) { saveCustomerRecord(modelKey: $modelKey, identity: $identity, email: $email, data: $data, sourceModifiedAt: $sourceModifiedAt) { record created customerCreated stale } }` : `mutation AppSaveCustomerRecord($modelKey: String!, $identity: String!, $email: String, $data: JSON!) { saveCustomerRecord(modelKey: $modelKey, identity: $identity, email: $email, data: $data) { record created customerCreated } }`,
+              variables
+            );
+          } catch (error) {
+            if (appCustomerUnlinkedOf(error)) return { unlinked: true };
+            throw error;
+          }
+          const record = answer?.record;
+          if (!record || typeof record !== "object" || Array.isArray(record)) {
+            return refuse(`saveCustomerRecord reported no error and returned no record on ${model}`);
+          }
+          return {
+            unlinked: false,
+            record,
+            id: recordIdOf(record),
+            created: answer?.created === true,
+            customerCreated: answer?.customerCreated === true,
+            stale: answer?.stale === true
+          };
+        },
+        async read(model, identity) {
+          if (identity === "") refuse(`a customer's record on ${model} was read with no identity`);
+          const record = await field(
+            "customerRecordByIdentity",
+            `query AppCustomerRecord($modelKey: String!, $identity: String!) { customerRecordByIdentity(modelKey: $modelKey, identity: $identity) }`,
+            { modelKey: model, identity }
+          );
+          if (!record) return null;
+          const id = recordIdOf(record);
+          if (!id) return refuse(`customerRecordByIdentity answered a record with no id on ${model}`);
+          const data = record.data;
+          return {
+            id,
+            naturalKey: firstString(record, ["naturalKey", "natural_key"]),
+            ownerId: typeof record.ownerId === "string" && record.ownerId !== "" ? record.ownerId : null,
+            fields: data && typeof data === "object" && !Array.isArray(data) ? data : {},
+            unreadable: []
+          };
+        },
+        async erase(model, identity) {
+          if (identity === "") refuse(`a customer's record on ${model} was erased with no identity`);
+          const answer = await field(
+            "eraseCustomerRecord",
+            `mutation AppEraseCustomerRecord($modelKey: String!, $identity: String!) { eraseCustomerRecord(modelKey: $modelKey, identity: $identity) { recordDeleted identityRemoved customerDeleted customerKeptBecause } }`,
+            { modelKey: model, identity }
+          );
+          if (!answer) return refuse(`eraseCustomerRecord reported no error and returned no answer on ${model}`);
+          return {
+            recordDeleted: answer.recordDeleted === true,
+            identityRemoved: answer.identityRemoved === true,
+            customerDeleted: answer.customerDeleted === true,
+            customerKeptBecause: answer.customerKeptBecause ?? null
+          };
+        },
+        async identities(model, customerId) {
+          if (customerId === "") refuse(`a customer's identities on ${model} were asked for with no customer`);
+          const answer = await field(
+            "customerIdentitiesById",
+            `query AppCustomerIdentities($modelKey: String!, $customerId: ID!) { customerIdentitiesById(modelKey: $modelKey, customerId: $customerId) }`,
+            { modelKey: model, customerId }
+          );
+          if (!Array.isArray(answer)) return refuse(`customerIdentitiesById reported no error and returned no list on ${model}`);
+          return answer.filter((identity) => typeof identity === "string");
+        }
+      }
+    },
+    customers: {
+      async ensure(email) {
+        const address = email.trim();
+        if (address === "") refuse("a customer was asked for with an empty email");
+        const customer = await field(
+          "createCustomer",
+          `mutation AppEnsureCustomer($input: CreateCustomerInput!) { createCustomer(input: $input) { id email } }`,
+          { input: { email: address, returnExisting: true } }
+        );
+        if (!customer?.id) return refuse("createCustomer reported no error and returned no customer");
+        return { id: customer.id, email: customer.email ?? address };
+      }
+    },
+    notifications: {
+      async send(notification) {
+        if (notification.customerId === "" || notification.title.trim() === "") {
+          refuse("a notification needs a customer and a title");
+        }
+        const input = { customerId: notification.customerId, title: notification.title };
+        if (notification.message !== void 0) input.message = notification.message;
+        if (notification.category !== void 0) input.category = notification.category;
+        if (notification.actionUrl !== void 0) input.actionUrl = notification.actionUrl;
+        if (notification.imageUrl !== void 0) input.imageUrl = notification.imageUrl;
+        if (notification.idempotencyKey !== void 0) input.idempotencyKey = notification.idempotencyKey;
+        if (notification.email) {
+          const email = { body: notification.email.body };
+          if (notification.email.subject !== void 0) email.subject = notification.email.subject;
+          if (notification.email.ctas?.length) email.ctas = notification.email.ctas.map((cta) => ({ label: cta.label, url: cta.url }));
+          input.channels = { email };
+        }
+        const sent = await field(
+          "sendNotification",
+          `mutation AppSendNotification($input: SendNotificationInput!) { sendNotification(input: $input) }`,
+          { input }
+        );
+        if (sent !== true) refuse("sendNotification reported no error and did not say the notification was sent");
+      },
+      async setConsent(change) {
+        if (change.customerId === "" || change.category === "") refuse("a consent change needs a customer and a category");
+        const input = {
+          customerId: change.customerId,
+          category: change.category,
+          channel: change.channel,
+          enabled: change.enabled
+        };
+        if (change.sourceModifiedAt !== void 0) input.sourceModifiedAt = change.sourceModifiedAt;
+        const answer = await field(
+          "setCustomerConsent",
+          `mutation AppSetCustomerConsent($input: SetCustomerConsentInput!) { setCustomerConsent(input: $input) { stale } }`,
+          { input }
+        );
+        if (!answer) return refuse("setCustomerConsent reported no error and answered nothing");
+        return { stale: answer.stale === true };
+      }
+    }
+  };
+}
+function directionOf(raw) {
+  const name = (raw ?? "").replace(/^FIELD_SYNC_DIRECTION_/, "");
+  return name === "SOURCE_ONLY" || name === "BIDIRECTIONAL" ? name : "SINK_ONLY";
+}
+function bindingsOf(raw) {
+  const out = [];
+  for (const binding of raw ?? []) {
+    if (!binding?.key || !binding.model) continue;
+    const fields = [];
+    for (const mapped of binding.fields ?? []) {
+      if (!mapped?.appField || !mapped.modelField) continue;
+      fields.push({ appField: mapped.appField, modelField: mapped.modelField, direction: directionOf(mapped.direction) });
+    }
+    out.push({
+      key: binding.key,
+      model: binding.model,
+      naturalKey: binding.naturalKey ?? "",
+      fields,
+      mode: binding.mode === "REFERENCE" ? "REFERENCE" : "SYNC"
+    });
+  }
+  return out;
+}
+function firstString(record, keys) {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value !== "") return value;
+  }
+  return null;
+}
+function recordIdOf(record) {
+  return firstString(record, ["id", "_id", "recordId", "record_id"]);
+}
+function decodeBase64Utf8(value) {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return new TextDecoder().decode(bytes);
+}
+function encodeBase64Utf8(value) {
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+// src/app/record-key.ts
+var RECORD_KEY_RULE = `a record's key is one URL-safe segment: letters, digits, "-", "_", "." and "~", and never "." or ".."`;
+var RECORD_KEY_PATTERN = /^[A-Za-z0-9._~-]+$/;
+function recordKeyRefusal(key) {
+  if (RECORD_KEY_PATTERN.test(key) && key !== "." && key !== "..") return null;
+  return `record key ${JSON.stringify(key)} is refused: ${RECORD_KEY_RULE}`;
+}
+
+// src/app/dispatch.ts
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var text = (value) => typeof value === "string" && value !== "" ? value : void 0;
+function readAppDispatch(body) {
+  const raw = isObject(body) ? body : {};
+  const trigger = isObject(raw.trigger) ? raw.trigger : {};
+  const executionId = text(raw.executionId) ?? text(raw.execution_id);
+  const operationKey = text(raw.operationKey) ?? text(raw.operation);
+  const triggeredBy = text(raw.triggered_by) ?? text(trigger.type);
+  const callback = readCallback(raw.callback);
+  const continuation = readContinuation(raw.continuation);
+  return {
+    ...executionId === void 0 ? {} : { executionId },
+    ...operationKey === void 0 ? {} : { operationKey },
+    ...triggeredBy === void 0 ? {} : { triggeredBy },
+    input: raw.input ?? null,
+    ...callback === void 0 ? {} : { callback },
+    ...continuation === void 0 ? {} : { continuation },
+    raw
+  };
+}
+function readCallback(value) {
+  if (!isObject(value)) return void 0;
+  const token = text(value.token);
+  if (!token) return void 0;
+  const mutations = isObject(value.mutations) ? value.mutations : {};
+  const signingKey = text(value.signingKey);
+  return {
+    gqlEndpoint: text(value.gqlEndpoint) ?? "",
+    token,
+    expiresAt: text(value.expiresAt) ?? "",
+    mutations: {
+      complete: text(mutations.complete) ?? "",
+      fail: text(mutations.fail) ?? "",
+      progress: text(mutations.progress) ?? "",
+      cancel: text(mutations.cancel) ?? ""
+    },
+    ...Array.isArray(value.causationChain) ? { causationChain: value.causationChain.map(String) } : {},
+    ...signingKey ? { signingKey } : {}
+  };
+}
+function readContinuation(value) {
+  if (!isObject(value)) return void 0;
+  const cursor = text(value.cursor);
+  if (!cursor) return void 0;
+  return { cursor, slice: typeof value.slice === "number" && Number.isInteger(value.slice) ? value.slice : 0 };
+}
+function readCredentialProbe(body) {
+  const raw = isObject(body) ? body : {};
+  const submitted = isObject(raw.values) ? raw.values : {};
+  const values = {};
+  for (const [key, value] of Object.entries(submitted)) {
+    if (value === null || value === void 0 || typeof value === "object") continue;
+    values[key] = String(value);
+  }
+  return { values };
+}
+
+// src/app/ticket.ts
+async function redeemExchangeTicket(options) {
+  if (!options.ticket) throw new FoirRequestError("[foir] redeemExchangeTicket needs the ticket");
+  const doFetch = options.fetch ?? globalThis.fetch;
+  let res;
+  try {
+    res = await doFetch(foirApiEndpoint(options.apiUrl, "/auth/exchange-ticket"), {
+      ...options.requestInit,
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ ticket: options.ticket })
+    });
+  } catch (err) {
+    throw new FoirRequestError("[foir] the exchange ticket could not be redeemed: no answer", { cause: err });
+  }
+  if (!res.ok) {
+    let detail = "";
+    try {
+      detail = (await res.text()).slice(0, 300);
+    } catch {
+    }
+    throw new FoirRequestError(`[foir] the exchange ticket was refused: HTTP ${res.status}${detail ? ` ${detail}` : ""}`, {
+      status: res.status
+    });
+  }
+  const body = await res.json();
+  if (typeof body.token !== "string" || body.token === "") {
+    throw new FoirRequestError("[foir] the exchange ticket was redeemed for nothing: the answer carried no token", {
+      status: res.status
+    });
+  }
+  const token = body.token;
+  return {
+    dispatch: { token: () => token, context: null },
+    expiresAt: typeof body.expires_at === "string" ? body.expires_at : ""
+  };
+}
+
+// src/app/manifest.ts
+var MAX_APP_MANIFEST_BYTES = 256 * 1024;
+async function validateAppManifest(options) {
+  const manifestJson = typeof options.manifest === "string" ? options.manifest : JSON.stringify(options.manifest);
+  if (new TextEncoder().encode(manifestJson).length > MAX_APP_MANIFEST_BYTES) {
+    throw new FoirRequestError(`[foir] a manifest is at most ${MAX_APP_MANIFEST_BYTES} bytes`);
+  }
+  let headers;
+  if (options.dispatch !== void 0) {
+    const token = (await options.dispatch.token())?.trim();
+    if (!token) throw new FoirRequestError("[foir] validateAppManifest: the dispatch token provider returned no token");
+    headers = buildFoirHeaders({ dispatchToken: token, dispatchContext: options.dispatch.context ?? void 0 });
+  } else {
+    if (!options.apiKey) throw new FoirRequestError("[foir] validateAppManifest needs a credential: `apiKey` or `dispatch`");
+    headers = buildFoirHeaders({ apiKey: options.apiKey });
+  }
+  const doFetch = options.fetch ?? globalThis.fetch;
+  let res;
+  try {
+    res = await doFetch(foirApiEndpoint(options.apiUrl, "/graphql"), {
+      ...options.requestInit,
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        query: "query ValidateAppManifest($manifestJson: String!) { validateAppManifest(manifestJson: $manifestJson) { ok issues { severity path message } } }",
+        variables: { manifestJson }
+      })
+    });
+  } catch (err) {
+    throw new FoirRequestError("[foir] network error", { cause: err });
+  }
+  let json;
+  try {
+    json = await res.json();
+  } catch {
+    throw new FoirRequestError(`[foir] HTTP ${res.status} ${res.statusText}`, { status: res.status });
+  }
+  if (!res.ok && !json.errors?.length) {
+    throw new FoirRequestError(`[foir] HTTP ${res.status} ${res.statusText}`, { status: res.status });
+  }
+  const answer = readFoirEnvelope(json, { strict: true }).validateAppManifest;
+  if (!answer || typeof answer.ok !== "boolean") {
+    throw new FoirRequestError("[foir] the platform answered the manifest check with no verdict", { status: res.status });
+  }
+  return {
+    ok: answer.ok,
+    issues: (answer.issues ?? []).map((issue) => ({
+      // An issue the platform did not grade is not one to wave through.
+      severity: issue.severity === "WARNING" ? "WARNING" : "ERROR",
+      path: issue.path ?? "",
+      message: issue.message ?? ""
+    }))
+  };
+}
+
+// src/app/vocabulary.generated.ts
+var APP_HOOK_EVENTS = [
+  "RECORD_CREATED",
+  "RECORD_UPDATED",
+  "RECORD_DELETED",
+  "RECORD_PUBLISHED",
+  "RECORD_UNPUBLISHED",
+  "CUSTOMER_CREATED",
+  "CUSTOMER_UPDATED",
+  "CUSTOMER_DELETED",
+  "CUSTOMER_MERGED",
+  "SESSION_REVOKED",
+  "OPERATION_COMPLETED",
+  "OPERATION_FAILED",
+  "OPERATION_CANCELLED",
+  "OPERATION_TIMED_OUT",
+  "ADMIN_MEMBERSHIP_GRANTED",
+  "ADMIN_MEMBERSHIP_REVOKED",
+  "ADMIN_ROLE_CHANGED",
+  "TENANT_PLAN_CHANGED",
+  "TENANT_SUBSCRIPTION_STATUS_CHANGED",
+  "PROJECT_CREATED",
+  "PROJECT_ARCHIVED",
+  "INVITATION_ACCEPTED",
+  "IMPORT_COMPLETED",
+  "MIGRATION_APPLIED",
+  "BULK_UPDATE_COMPLETED",
+  "BULK_PUBLISH_COMPLETED",
+  "CUSTOMER_PREFERENCE_CHANGED",
+  "ORGANIZATION_CREATED",
+  "ORGANIZATION_UPDATED",
+  "ORGANIZATION_MOVED",
+  "ORGANIZATION_SUSPENDED",
+  "ORGANIZATION_RESUMED",
+  "ORGANIZATION_DELETION_SCHEDULED",
+  "ORGANIZATION_DELETION_CANCELLED",
+  "ORGANIZATION_DELETED",
+  "ORGANIZATION_MEMBER_ADDED",
+  "ORGANIZATION_MEMBER_REMOVED",
+  "ORGANIZATION_MEMBER_ROLE_CHANGED"
+];
+var APP_CAPABILITIES = [
+  "config:read",
+  "secrets:read.app",
+  "secrets:put.app",
+  "secrets:list.app",
+  "secrets:delete.app",
+  "status:write",
+  "files:read",
+  "files:list",
+  "files:write",
+  "customers:write",
+  "notifications:write",
+  "notifications:consent",
+  "operations:complete"
+];
+var APP_RECORD_CAPABILITY_PREFIXES = [
+  "records:read:",
+  "records:write:",
+  "records:delete:",
+  "records:publish:",
+  "records:attribute:"
+];
+export {
+  APP_CAPABILITIES,
+  APP_HOOK_EVENTS,
+  APP_RECORD_CAPABILITY_PREFIXES,
+  FoirRequestError,
+  MAX_APP_MANIFEST_BYTES,
+  RECORD_KEY_RULE,
+  appCustomerUnlinkedOf,
+  appLookupConflictOf,
+  appModelFieldName,
+  appModelTypeName,
+  appSelectorEnumValue,
+  createAppClient,
+  isAppFieldWithheld,
+  readAppDispatch,
+  readCredentialProbe,
+  recordKeyRefusal,
+  redeemExchangeTicket,
+  validateAppManifest
+};