busa-sdk 0.98.0 → 0.99.0

package/dist/airapp.d.ts

@@ -1,4 +1,307 @@
-import { t as BusabaseClient } from "./client-DtzuVlPK.js";
+import { l as BusabaseAirAppRuntimeReport } from "./airapp-node-D2GcMwde.js";
+import { t as BusabaseClient, zt as RecordVO } from "./client-BUzSZV3L.js";
+//#region src/airapp-browser-runtime.d.ts
+/** What the probe resolved to. */
+interface AirAppRuntimeInfo {
+  /**
+   * The engine name the server reported, verbatim (`"browser"`, `"local"`,
+   * `"standalone"`, or one this SDK has never heard of), or `"unknown"` when the
+   * probe did not get an answer.
+   */
+  runtime: string;
+  /** Busabase is hosting this app. Taken from the server's boolean, never derived here. */
+  hosted: boolean;
+  /**
+   * A standalone run is proxying `/api/v1` to a configured Busabase base URL.
+   * A separate axis from `hosted` — "where am I" is not "do I have credentials".
+   */
+  devProxy: boolean;
+  /** `false` when the probe did not answer — the `unknown` outcome. */
+  determined: boolean;
+}
+/** Relative on purpose; see the module comment. */
+declare const AIRAPP_RUNTIME_PATH = "__airapp/runtime";
+/** How long the probe waits before resolving to `unknown`. */
+declare const AIRAPP_RUNTIME_TIMEOUT_MS = 3000;
+/** The `unknown` outcome: the probe did not get a usable answer. */
+declare const AIRAPP_RUNTIME_UNKNOWN: Readonly<AirAppRuntimeInfo>;
+/**
+ * Turn a `__airapp/runtime` body into an {@link AirAppRuntimeInfo}. Anything that
+ * is not an object with a string `runtime` is `unknown`.
+ *
+ * `hosted` is `body.hosted === true` — the server's own answer, read as-is.
+ */
+declare function normalizeAirAppRuntime(body: Partial<BusabaseAirAppRuntimeReport> | unknown): AirAppRuntimeInfo;
+interface DetectAirAppRuntimeOptions {
+  /**
+   * Injected `fetch`. When set, the probe always runs fresh and nothing is
+   * cached — it is a different question from "what did this page's probe say".
+   */
+  fetch?: typeof globalThis.fetch;
+  /** Defaults to {@link AIRAPP_RUNTIME_TIMEOUT_MS}. */
+  timeoutMs?: number;
+}
+/**
+ * Ask the app's own server where it is running. Never rejects: a failed,
+ * non-JSON, or slow probe resolves to {@link AIRAPP_RUNTIME_UNKNOWN}.
+ *
+ * Called without an injected `fetch`, the first call probes and every later call
+ * on the page shares that answer, so the connect gate, the provider, and the
+ * settings panel can each ask without three round trips.
+ *
+ * @example
+ * ```js
+ * // app/js/runtime.js
+ * import { detectAirAppRuntime, shouldUseLocalAirAppGateway } from "../vendor/busabase-airapp.js";
+ *
+ * export const runtime = await detectAirAppRuntime();
+ * export const shouldUseLocalGateway = () => shouldUseLocalAirAppGateway(runtime);
+ * ```
+ */
+declare function detectAirAppRuntime(options?: DetectAirAppRuntimeOptions): Promise<AirAppRuntimeInfo>;
+/**
+ * Whether the app's local `/auth/*` connect gate applies — the predicate for
+ * `createAirAppConnectGate({ shouldGate })`.
+ *
+ * `!hosted`, so `unknown` shows the gate: an unnecessary gate is closed by the
+ * operator, a missing one strands them. Where the app runs never decides whether
+ * a write merges — Busabase decides that from the person's own permission.
+ */
+declare const shouldUseLocalAirAppGateway: (runtime: AirAppRuntimeInfo) => boolean;
+//#endregion
+//#region src/airapp-write-outcome.d.ts
+/**
+ * Did my write land, or is it waiting for someone? — one answer for every write.
+ *
+ * A person's write from an AirApp leaves `autoMerge` unset, so Busabase decides
+ * from that person's own permission: with write access the change lands now,
+ * without it the same change becomes a ChangeRequest for someone who has it.
+ * Both are correct outcomes. The app's job is to say which one happened instead
+ * of assuming either, and the response is the only place that says.
+ *
+ * It says it in three shapes, which is why this module exists:
+ *
+ * - `bases.createChangeRequest` and `records.changeRequest` return either the
+ *   materialized record (`materialized: true`) or the pending ChangeRequest
+ *   (`materialized: false`).
+ * - The bulk endpoints (`createBulkChangeRequest`,
+ *   `createBulkUpdateChangeRequest`) return a ChangeRequest whose `status` is
+ *   `"merged"` when it landed and `"in_review"` when it is waiting.
+ * - An older server may answer with a bare record (`status: "active"`).
+ *
+ * 48 templates each carried `isQueued = (r) => r?.materialized === false ||
+ * r?.status === "in_review"` and their own copy of the user-facing sentence. One
+ * definition here means the next change to either happens once.
+ */
+/** Whether a write landed (`saved`) or is waiting for someone with write access (`queued`). */
+type AirAppWriteStatus = "saved" | "queued";
+/** Every write response, normalized. */
+interface AirAppWriteOutcome {
+  status: AirAppWriteStatus;
+  /**
+   * The record the write created or changed, when the response names one: the
+   * materialized record's id, or for a ChangeRequest its single record target.
+   * Absent for a queued create (the record does not exist yet) and for a bulk
+   * write touching several records — see `recordIds`.
+   */
+  recordId?: string;
+  /** Every record a merged bulk write produced or changed, in operation order. */
+  recordIds?: string[];
+  /** The ChangeRequest the write produced, when the response carries one. */
+  changeRequestId?: string;
+}
+/** The fields of a write response this module reads. Every write response satisfies it. */
+interface AirAppWriteResponseLike {
+  id?: string;
+  status?: string;
+  materialized?: boolean;
+  /** Present on a ChangeRequest; distinguishes one from a record. */
+  operations?: readonly {
+    mergedRecordId?: string | null;
+    targetRecordId?: string | null;
+  }[];
+  primaryOperation?: {
+    mergedRecordId?: string | null;
+    targetRecordId?: string | null;
+  } | null;
+  /** Rides along on a merged create for internal callers; usually stripped by the server. */
+  changeRequestId?: string;
+}
+/**
+ * The templates' `isQueued`, verbatim: the write did not land.
+ *
+ * Kept as its own export because 48 apps already branch on exactly this; for
+ * everything else prefer {@link toAirAppWriteOutcome}.
+ */
+declare const isAirAppWriteQueued: (response: unknown) => boolean;
+/**
+ * Normalize any write response — single create, single update, bulk create, bulk
+ * update — into an {@link AirAppWriteOutcome}.
+ *
+ * `queued` when `materialized === false` or `status === "in_review"` (the
+ * contract's pending branch). Also `queued` for a ChangeRequest in any other
+ * not-merged state (`changes_requested`, `conflict`, …): a fresh write does not
+ * normally come back in one, and if it ever does, "saved" would be a claim the
+ * response does not support. Everything else — a materialized record, a merged
+ * ChangeRequest, a bare record from an older server — is `saved`.
+ */
+declare function toAirAppWriteOutcome(response: unknown): AirAppWriteOutcome;
+/** The sentence an app shows for each outcome. */
+interface AirAppWriteMessages {
+  saved: string;
+  queued: string;
+}
+/**
+ * Default copy. `queued` says *why* it is waiting (no write access here) and
+ * *what happens next* (someone who has it approves) — the two things a person
+ * who just clicked Save needs, so it does not read as "nothing happened".
+ *
+ * Locales outside this table fall back to `en`; an app passes its own strings
+ * through `messages` for those, or to change the wording.
+ */
+declare const AIRAPP_WRITE_MESSAGES: Readonly<Record<string, Readonly<AirAppWriteMessages>>>;
+/**
+ * Pick the closest table entry: exact tag, then Traditional/Simplified Chinese by
+ * script or region, then the bare language, then `en`.
+ */
+declare function resolveAirAppWriteLocale(locale: string | undefined): string;
+interface AirAppWriteMessageOptions {
+  /** BCP 47 tag. Defaults to `navigator.language`, then `en`. */
+  locale?: string;
+  /** The app's own wording; wins over the defaults for whichever keys it sets. */
+  messages?: Partial<AirAppWriteMessages>;
+}
+/**
+ * The sentence to show after a write.
+ *
+ * @example
+ * ```js
+ * const outcome = await records.upsert({ ... });
+ * state.notice = airAppWriteMessage(outcome, { locale: currentLocale() });
+ * ```
+ */
+declare function airAppWriteMessage(outcome: Pick<AirAppWriteOutcome, "status">, options?: AirAppWriteMessageOptions): string;
+//#endregion
+//#region src/airapp-records.d.ts
+type ListRecordsInput = NonNullable<Parameters<BusabaseClient["records"]["list"]>[0]>;
+/** The client surface these helpers need. Both `BusabaseClient` and `Busabase#client` satisfy it. */
+type AirAppRecordsClient = {
+  records: Pick<BusabaseClient["records"], "list" | "get" | "changeRequest">;
+  bases: Pick<BusabaseClient["bases"], "createChangeRequest">;
+};
+/**
+ * A record as these helpers return it: the canonical `RecordVO`, plus `fields` —
+ * its current field values keyed by slug, already pulled out of `headCommit`.
+ * Every copy re-derived that line (`record.headCommit?.payload ||
+ * record.headCommit?.fields || record.fields`); now it is a property.
+ */
+type AirAppRecord = RecordVO & {
+  fields: Record<string, unknown>;
+};
+/** One page of records and the cursor for the next, `null` at the end. */
+interface AirAppRecordPage {
+  records: AirAppRecord[];
+  nextCursor: string | null;
+}
+interface AirAppReadPageInput {
+  baseId: string;
+  /**
+   * The page budget for this one read — the app's declared `readLimit`. Defaults
+   * to 50, the documented interactive budget. One call reads one page; the next
+   * page is a separate call made for a separate user action.
+   */
+  limit?: number;
+  /** The previous page's `nextCursor`. `null`/`undefined`/`""` reads the first page. */
+  cursor?: string | null;
+  /** View filters (a best-effort superset — see `records.list`). */
+  filters?: ListRecordsInput["filters"];
+  /** Exact value comparisons — see `records.list`. */
+  valueFilters?: ListRecordsInput["valueFilters"];
+  /** One number or date field to sort by — see `records.list`. */
+  sort?: ListRecordsInput["sort"];
+}
+interface AirAppFindRecordInput {
+  baseId: string;
+  /** The field to match on, by slug — usually the app's business id (`"contact-id"`). */
+  fieldSlug: string;
+  /** The exact text value to match. */
+  valueText: string;
+}
+interface AirAppCreateRecordInput {
+  baseId: string;
+  /** Field values keyed by field slug, exactly as the Base declares them. */
+  fields: Record<string, unknown>;
+  /** Shown to whoever reviews it if it is queued. */
+  message?: string;
+  /** Dedupes a retried create (after a timeout, say) — see `bases.createChangeRequest`. */
+  idempotencyKey?: string;
+}
+interface AirAppUpdateRecordInput {
+  /** The record to change. */
+  recordId: string;
+  /**
+   * The `headCommitId` the change was made against, for optimistic concurrency:
+   * a record someone else changed in the meantime is not silently overwritten.
+   * Pass the one from the record you read.
+   */
+  baseCommitId?: string;
+  /** The fields to change, keyed by slug. Fields not named keep their value. */
+  fields: Record<string, unknown>;
+  message?: string;
+}
+interface AirAppUpsertRecordInput extends AirAppFindRecordInput {
+  /**
+   * Field values keyed by slug. On a create, the match field is filled in with
+   * `valueText` when `fields` leaves it out — otherwise the record could never
+   * be found by this same upsert again, and every call would create another.
+   */
+  fields: Record<string, unknown>;
+  message?: string;
+}
+/** The outcome of a single write, with the raw response kept for anything app-specific. */
+interface AirAppWriteResult extends AirAppWriteOutcome {
+  /** The server's response, unchanged. */
+  response: unknown;
+}
+/** An upsert's outcome, plus which of the two writes it made. */
+interface AirAppUpsertResult extends AirAppWriteResult {
+  action: "create" | "update";
+}
+interface AirAppRecordsOptions {
+  /**
+   * Recorded as `submittedBy` on creates and `author` on updates, so a reviewer
+   * can see which app proposed the change. Omit to use the server's default.
+   */
+  appId?: string;
+}
+interface AirAppRecords {
+  /** Read one page. Never loops: the next page is the caller's next call. */
+  readPage(input: AirAppReadPageInput): Promise<AirAppRecordPage>;
+  /** The one record whose `fieldSlug` is exactly `valueText`, or `null` when there is none. */
+  findRecord(input: AirAppFindRecordInput): Promise<AirAppRecord | null>;
+  /** Create a record. Permission-aware: never passes `autoMerge`. */
+  createRecord(input: AirAppCreateRecordInput): Promise<AirAppWriteResult>;
+  /** Change a record. Permission-aware: never passes `autoMerge`. */
+  updateRecord(input: AirAppUpdateRecordInput): Promise<AirAppWriteResult>;
+  /**
+   * Update the record whose `fieldSlug` is exactly `valueText`, or create one
+   * when there is none. The update is made against the `headCommitId` it just
+   * read. Permission-aware: never passes `autoMerge`.
+   */
+  upsert(input: AirAppUpsertRecordInput): Promise<AirAppUpsertResult>;
+}
+/** The `fields` property: the record's current values, out of its head commit. */
+declare function airAppRecordFields(record: unknown): Record<string, unknown>;
+/**
+ * Bind the record helpers to one client.
+ *
+ * The client is whatever the app already built — in an AirApp that is
+ * `createBusabaseClient({ baseUrl: window.location.origin })`, authenticated by
+ * the viewer's ambient session when hosted and by the local gateway's proxy when
+ * standalone. These helpers do not care which.
+ */
+declare function createAirAppRecords(client: AirAppRecordsClient, options?: AirAppRecordsOptions): AirAppRecords;
+//#endregion
 //#region src/airapp.d.ts
 type NodeChangeRequestInput = Parameters<BusabaseClient["nodes"]["createChangeRequest"]>[0];
 type NodeOperationInput = NodeChangeRequestInput["operations"][number];
@@ -314,4 +617,4 @@ declare function resolveAirAppFileAssets(client: AirAppPublishClient, files: Air
  */
 declare function publishAirApp(client: AirAppPublishClient, config: AirAppResourceConfig, files: AirAppFileInput[]): Promise<AirAppPublishResult>;
 //#endregion
-export { AirAppBaseDeclaration, AirAppFieldDeclaration, AirAppFileInput, AirAppFolderDeclaration, AirAppNodeDeclaration, AirAppOwnershipRepair, AirAppProvisionedBase, AirAppProvisioningClient, AirAppPublishClient, AirAppPublishResult, AirAppResourceConfig, AirAppResourceOwnership, AirAppResources, AirAppSetupCode, AirAppSetupError, buildAirAppFileOperations, buildProvisionOperations, inspectProvisionedResources, isNotFound, provisionDeclaredResources, publishAirApp, resolveAirAppFileAssets, resolveProvisionedFolder };
+export { AIRAPP_RUNTIME_PATH, AIRAPP_RUNTIME_TIMEOUT_MS, AIRAPP_RUNTIME_UNKNOWN, AIRAPP_WRITE_MESSAGES, AirAppBaseDeclaration, type AirAppCreateRecordInput, AirAppFieldDeclaration, AirAppFileInput, type AirAppFindRecordInput, AirAppFolderDeclaration, AirAppNodeDeclaration, AirAppOwnershipRepair, AirAppProvisionedBase, AirAppProvisioningClient, AirAppPublishClient, AirAppPublishResult, type AirAppReadPageInput, type AirAppRecord, type AirAppRecordPage, type AirAppRecords, type AirAppRecordsClient, type AirAppRecordsOptions, AirAppResourceConfig, AirAppResourceOwnership, AirAppResources, type AirAppRuntimeInfo, AirAppSetupCode, AirAppSetupError, type AirAppUpdateRecordInput, type AirAppUpsertRecordInput, type AirAppUpsertResult, type AirAppWriteMessageOptions, type AirAppWriteMessages, type AirAppWriteOutcome, type AirAppWriteResponseLike, type AirAppWriteResult, type AirAppWriteStatus, type DetectAirAppRuntimeOptions, airAppRecordFields, airAppWriteMessage, buildAirAppFileOperations, buildProvisionOperations, createAirAppRecords, detectAirAppRuntime, inspectProvisionedResources, isAirAppWriteQueued, isNotFound, normalizeAirAppRuntime, provisionDeclaredResources, publishAirApp, resolveAirAppFileAssets, resolveAirAppWriteLocale, resolveProvisionedFolder, shouldUseLocalAirAppGateway, toAirAppWriteOutcome };

package/dist/airapp.js

@@ -1,4 +1,321 @@
-import { a as uploadAsset, t as APP_ROOT_RESOURCE_KEY } from "./template-CMJMkyse.js";
+import { o as uploadAsset, t as APP_ROOT_RESOURCE_KEY } from "./template-Bnkq4diD.js";
+//#region src/airapp-browser-runtime.ts
+/** Relative on purpose; see the module comment. */
+const AIRAPP_RUNTIME_PATH = "__airapp/runtime";
+/** How long the probe waits before resolving to `unknown`. */
+const AIRAPP_RUNTIME_TIMEOUT_MS = 3e3;
+/** The `unknown` outcome: the probe did not get a usable answer. */
+const AIRAPP_RUNTIME_UNKNOWN = Object.freeze({
+	runtime: "unknown",
+	hosted: false,
+	devProxy: false,
+	determined: false
+});
+/**
+* Turn a `__airapp/runtime` body into an {@link AirAppRuntimeInfo}. Anything that
+* is not an object with a string `runtime` is `unknown`.
+*
+* `hosted` is `body.hosted === true` — the server's own answer, read as-is.
+*/
+function normalizeAirAppRuntime(body) {
+	if (!body || typeof body !== "object") return { ...AIRAPP_RUNTIME_UNKNOWN };
+	const report = body;
+	if (typeof report.runtime !== "string") return { ...AIRAPP_RUNTIME_UNKNOWN };
+	return {
+		runtime: report.runtime,
+		hosted: report.hosted === true,
+		devProxy: report.devProxy === true,
+		determined: true
+	};
+}
+const probe = async (doFetch, timeoutMs) => {
+	const controller = typeof AbortController === "function" ? new AbortController() : void 0;
+	const timer = controller ? globalThis.setTimeout(() => controller.abort(), timeoutMs) : void 0;
+	try {
+		const response = await doFetch(AIRAPP_RUNTIME_PATH, {
+			headers: { accept: "application/json" },
+			...controller ? { signal: controller.signal } : {}
+		});
+		const type = response.headers.get("content-type") || "";
+		if (!response.ok || !type.includes("application/json")) return { ...AIRAPP_RUNTIME_UNKNOWN };
+		return normalizeAirAppRuntime(await response.json());
+	} catch {
+		return { ...AIRAPP_RUNTIME_UNKNOWN };
+	} finally {
+		if (timer !== void 0) globalThis.clearTimeout(timer);
+	}
+};
+/**
+* The page-wide answer lives on a global slot, not in module scope: an app that
+* imports its modules both with and without a `?v=` cache-busting query loads
+* this file as two module records with two scopes. A module-level cache would be
+* filled by one copy and read empty by the other — the bug one template already
+* hit with its own copy of this probe.
+*/
+const SLOT = Symbol.for("busabase-sdk.airapp.runtime");
+const slot = () => {
+	const holder = globalThis;
+	let current = holder[SLOT];
+	if (!current) {
+		current = {};
+		holder[SLOT] = current;
+	}
+	return current;
+};
+/**
+* Ask the app's own server where it is running. Never rejects: a failed,
+* non-JSON, or slow probe resolves to {@link AIRAPP_RUNTIME_UNKNOWN}.
+*
+* Called without an injected `fetch`, the first call probes and every later call
+* on the page shares that answer, so the connect gate, the provider, and the
+* settings panel can each ask without three round trips.
+*
+* @example
+* ```js
+* // app/js/runtime.js
+* import { detectAirAppRuntime, shouldUseLocalAirAppGateway } from "../vendor/busabase-airapp.js";
+*
+* export const runtime = await detectAirAppRuntime();
+* export const shouldUseLocalGateway = () => shouldUseLocalAirAppGateway(runtime);
+* ```
+*/
+function detectAirAppRuntime(options = {}) {
+	const timeoutMs = options.timeoutMs ?? 3e3;
+	if (options.fetch) return probe(options.fetch, timeoutMs);
+	const shared = slot();
+	if (!shared.pending) shared.pending = typeof globalThis.fetch === "function" ? probe(globalThis.fetch.bind(globalThis), timeoutMs) : Promise.resolve({ ...AIRAPP_RUNTIME_UNKNOWN });
+	return shared.pending;
+}
+/**
+* Whether the app's local `/auth/*` connect gate applies — the predicate for
+* `createAirAppConnectGate({ shouldGate })`.
+*
+* `!hosted`, so `unknown` shows the gate: an unnecessary gate is closed by the
+* operator, a missing one strands them. Where the app runs never decides whether
+* a write merges — Busabase decides that from the person's own permission.
+*/
+const shouldUseLocalAirAppGateway = (runtime) => !runtime.hosted;
+//#endregion
+//#region src/airapp-write-outcome.ts
+const isChangeRequestShape = (response) => Array.isArray(response.operations) || "primaryOperation" in response;
+const recordIdsOf = (response, key) => (response.operations ?? []).map((operation) => operation?.[key]).filter((value) => typeof value === "string" && value !== "");
+/**
+* The templates' `isQueued`, verbatim: the write did not land.
+*
+* Kept as its own export because 48 apps already branch on exactly this; for
+* everything else prefer {@link toAirAppWriteOutcome}.
+*/
+const isAirAppWriteQueued = (response) => {
+	const value = response;
+	return value?.materialized === false || value?.status === "in_review";
+};
+/**
+* Normalize any write response — single create, single update, bulk create, bulk
+* update — into an {@link AirAppWriteOutcome}.
+*
+* `queued` when `materialized === false` or `status === "in_review"` (the
+* contract's pending branch). Also `queued` for a ChangeRequest in any other
+* not-merged state (`changes_requested`, `conflict`, …): a fresh write does not
+* normally come back in one, and if it ever does, "saved" would be a claim the
+* response does not support. Everything else — a materialized record, a merged
+* ChangeRequest, a bare record from an older server — is `saved`.
+*/
+function toAirAppWriteOutcome(response) {
+	const value = response ?? {};
+	const changeRequest = isChangeRequestShape(value);
+	if (isAirAppWriteQueued(value) || changeRequest && value.materialized !== true && value.status !== "merged") {
+		const targets = recordIdsOf(value, "targetRecordId");
+		const target = value.primaryOperation?.targetRecordId ?? (targets.length === 1 ? targets[0] : void 0);
+		return {
+			status: "queued",
+			...target ? { recordId: target } : {},
+			...value.id ? { changeRequestId: value.id } : {}
+		};
+	}
+	if (changeRequest) {
+		const merged = recordIdsOf(value, "mergedRecordId");
+		return {
+			status: "saved",
+			...merged.length === 1 ? { recordId: merged[0] } : {},
+			...merged.length ? { recordIds: merged } : {},
+			...value.id ? { changeRequestId: value.id } : {}
+		};
+	}
+	return {
+		status: "saved",
+		...value.id ? { recordId: value.id } : {},
+		...value.changeRequestId ? { changeRequestId: value.changeRequestId } : {}
+	};
+}
+/**
+* Default copy. `queued` says *why* it is waiting (no write access here) and
+* *what happens next* (someone who has it approves) — the two things a person
+* who just clicked Save needs, so it does not read as "nothing happened".
+*
+* Locales outside this table fall back to `en`; an app passes its own strings
+* through `messages` for those, or to change the wording.
+*/
+const AIRAPP_WRITE_MESSAGES = Object.freeze({
+	en: {
+		saved: "Saved.",
+		queued: "Sent for review. You don't have write access here, so this waits until someone who does approves it."
+	},
+	"zh-CN": {
+		saved: "已保存。",
+		queued: "已提交审核。你在这里没有写权限，需要有写权限的人批准后才会生效。"
+	},
+	"zh-TW": {
+		saved: "已儲存。",
+		queued: "已送出審核。你在這裡沒有寫入權限，需要有寫入權限的人核准後才會生效。"
+	},
+	ja: {
+		saved: "保存しました。",
+		queued: "レビューに送信しました。ここでの書き込み権限がないため、書き込み権限のある人が承認するまで反映されません。"
+	}
+});
+/**
+* Pick the closest table entry: exact tag, then Traditional/Simplified Chinese by
+* script or region, then the bare language, then `en`.
+*/
+function resolveAirAppWriteLocale(locale) {
+	if (!locale) return "en";
+	if (AIRAPP_WRITE_MESSAGES[locale]) return locale;
+	const lower = locale.toLowerCase();
+	if (lower.startsWith("zh")) return /-(?:hant|tw|hk|mo)\b/.test(lower) ? "zh-TW" : "zh-CN";
+	const language = lower.split(/[-_]/)[0];
+	return AIRAPP_WRITE_MESSAGES[language] ? language : "en";
+}
+/**
+* The sentence to show after a write.
+*
+* @example
+* ```js
+* const outcome = await records.upsert({ ... });
+* state.notice = airAppWriteMessage(outcome, { locale: currentLocale() });
+* ```
+*/
+function airAppWriteMessage(outcome, options = {}) {
+	const browserLocale = typeof globalThis.navigator === "object" ? globalThis.navigator?.language : void 0;
+	const table = AIRAPP_WRITE_MESSAGES[resolveAirAppWriteLocale(options.locale ?? browserLocale)];
+	const key = outcome.status === "queued" ? "queued" : "saved";
+	return options.messages?.[key] ?? table[key];
+}
+//#endregion
+//#region src/airapp-records.ts
+/** The `fields` property: the record's current values, out of its head commit. */
+function airAppRecordFields(record) {
+	const value = record;
+	const fields = value?.headCommit?.payload ?? value?.headCommit?.fields ?? value?.fields;
+	return fields && typeof fields === "object" && !Array.isArray(fields) ? fields : {};
+}
+const isNotFound$1 = (error) => typeof error === "object" && error !== null && ("code" in error && error.code === "NOT_FOUND" || "status" in error && error.status === 404);
+const withFields = (record) => ({
+	...record,
+	fields: airAppRecordFields(record)
+});
+/**
+* Bind the record helpers to one client.
+*
+* The client is whatever the app already built — in an AirApp that is
+* `createBusabaseClient({ baseUrl: window.location.origin })`, authenticated by
+* the viewer's ambient session when hosted and by the local gateway's proxy when
+* standalone. These helpers do not care which.
+*/
+function createAirAppRecords(client, options = {}) {
+	const { appId } = options;
+	const readPage = async (input) => {
+		const result = await client.records.list({
+			baseId: input.baseId,
+			limit: input.limit ?? 50,
+			...input.cursor ? { cursor: input.cursor } : {},
+			...input.filters ? { filters: input.filters } : {},
+			...input.valueFilters ? { valueFilters: input.valueFilters } : {},
+			...input.sort ? { sort: input.sort } : {}
+		});
+		if (Array.isArray(result)) return {
+			records: result.filter((record) => record?.baseId === input.baseId).map(withFields),
+			nextCursor: null
+		};
+		const page = result;
+		return {
+			records: (page?.records ?? []).map(withFields),
+			nextCursor: page?.nextCursor || null
+		};
+	};
+	const findRecord = async ({ baseId, fieldSlug, valueText }) => {
+		if (!valueText) return null;
+		try {
+			return withFields(await client.records.get({
+				baseId,
+				fieldSlug,
+				valueText
+			}));
+		} catch (error) {
+			if (isNotFound$1(error)) return null;
+			throw error;
+		}
+	};
+	const createRecord = async (input) => {
+		const response = await client.bases.createChangeRequest({
+			baseId: input.baseId,
+			fields: input.fields,
+			...input.message !== void 0 ? { message: input.message } : {},
+			...appId ? { submittedBy: appId } : {},
+			...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}
+		});
+		return {
+			...toAirAppWriteOutcome(response),
+			response
+		};
+	};
+	const updateRecord = async (input) => {
+		const response = await client.records.changeRequest({
+			recordId: input.recordId,
+			operation: "update",
+			fields: input.fields,
+			...input.message !== void 0 ? { message: input.message } : {},
+			...appId ? { author: appId } : {},
+			...input.baseCommitId ? { baseCommitId: input.baseCommitId } : {}
+		});
+		return {
+			...toAirAppWriteOutcome(response),
+			response
+		};
+	};
+	const upsert = async (input) => {
+		if (!input.valueText) throw new Error(`upsert: valueText for ${input.fieldSlug} is empty, so there is no record to match — pass the record's business id`);
+		const existing = await findRecord(input);
+		if (existing) return {
+			...await updateRecord({
+				recordId: existing.id,
+				baseCommitId: existing.headCommitId,
+				fields: input.fields,
+				message: input.message
+			}),
+			action: "update"
+		};
+		const fields = input.fieldSlug in input.fields ? input.fields : {
+			...input.fields,
+			[input.fieldSlug]: input.valueText
+		};
+		return {
+			...await createRecord({
+				baseId: input.baseId,
+				fields,
+				message: input.message
+			}),
+			action: "create"
+		};
+	};
+	return {
+		readPage,
+		findRecord,
+		createRecord,
+		updateRecord,
+		upsert
+	};
+}
+//#endregion
 //#region src/airapp.ts
 /**
 * AirApp resource provisioning — how an app claims (or creates) the Folder and
@@ -545,4 +862,4 @@ async function publishAirApp(client, config, files) {
 	};
 }
 //#endregion
-export { AirAppSetupError, buildAirAppFileOperations, buildProvisionOperations, inspectProvisionedResources, isNotFound, provisionDeclaredResources, publishAirApp, resolveAirAppFileAssets, resolveProvisionedFolder };
+export { AIRAPP_RUNTIME_PATH, AIRAPP_RUNTIME_TIMEOUT_MS, AIRAPP_RUNTIME_UNKNOWN, AIRAPP_WRITE_MESSAGES, AirAppSetupError, airAppRecordFields, airAppWriteMessage, buildAirAppFileOperations, buildProvisionOperations, createAirAppRecords, detectAirAppRuntime, inspectProvisionedResources, isAirAppWriteQueued, isNotFound, normalizeAirAppRuntime, provisionDeclaredResources, publishAirApp, resolveAirAppFileAssets, resolveAirAppWriteLocale, resolveProvisionedFolder, shouldUseLocalAirAppGateway, toAirAppWriteOutcome };