@iterant/site-runtime 3.3.0 → 3.4.0

package/docs/runtime-contract.md

@@ -50,7 +50,7 @@ runtime and says so.
 
 <!-- generated: available libraries -->
 
-_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.3.0._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.4.0._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -259,6 +259,37 @@ additive platform-side field can never fail an already-pinned repo's build.
 "The one `@source` line" below does not grow: the component ships no utility
 classes, only a scoped style block on the data attribute.
 
+### Reading the brand Database (3.4.0)
+
+A page can render rows the customer maintains in the brand Database, read at
+request time:
+
+```ts
+import { readDatabase } from "@iterant/site-runtime/database";
+
+const { rows, total } = await readDatabase("articles", {
+  sort: [{ column: "published_at", dir: "desc" }],
+  limit: 20,
+});
+```
+
+Server side only (a page's frontmatter, an SSR route). The site holds no
+database binding and writes no SQL: it names a table and the platform decides
+what that means. A table is invisible until the platform grants it site read,
+and the grant carries the filter that says which rows are public (a blog
+publishes `status = published`) plus an optional list of readable fields. A
+narrower `filter` here can only narrow that further. The platform's own row
+columns (`_id`, `_created_at`, `_updated_at`, `_v`) are not part of a grant
+unless it says so, so a page that keys rows by `_id` needs the grant to publish
+it; without that they are neither readable, filterable nor sortable.
+
+Nothing is configured in the repo. A published site gets the endpoint and the
+token from the platform-generated publish gate; `astro dev` gets them from
+`ITERANT_SITE_DB_URL` and `ITERANT_SITE_DB_TOKEN`, which the platform sets on
+the dev server. A site with neither, an ungranted table and an unreachable
+platform all read as `{rows: [], total: 0}` with a console warning: a listing
+that renders empty beats a build that dies on a database blip.
+
 ### Choosing a shell (3.2.0)
 
 A repo may own more than one frame. A replicated site whose second page carried

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "type": "module",
   "description": "The platform layer every Iterant brand site runs on: content grammar, collection schemas, SEO head and JSON-LD, layout core, Astro config preset, dev integrations and the verify gates.",
   "scripts": {
@@ -31,6 +31,7 @@
     "!scripts/check-fixture.mjs",
     "!scripts/check-packed.mjs",
     "!scripts/generate-kit-table.mjs",
+    "!scripts/packed-content.mjs",
     "!src/lib/__fixtures__"
   ],
   "exports": {
@@ -38,6 +39,7 @@
     "./content": "./src/content/collections.ts",
     "./content/schema": "./src/content/schema.ts",
     "./content-values": "./src/lib/content-values.ts",
+    "./database": "./src/lib/database.ts",
     "./markdown": "./src/lib/markdown.ts",
     "./locales": "./src/lib/locales.ts",
     "./hreflang": "./src/lib/hreflang.ts",
@@ -112,8 +114,6 @@
     "@types/node": "24.3.1",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
-    "@workspace/eslint-config": "workspace:*",
-    "@workspace/typescript-config": "workspace:*",
     "typescript": "5.9.2",
     "vitest": "^4.0.13",
     "wrangler": "^4.107.0"

package/src/index.ts

@@ -12,6 +12,7 @@ export * from "./lib/bespoke-pages";
 export * from "./lib/chrome-schemas";
 export * from "./lib/content-paths";
 export * from "./lib/content-values";
+export * from "./lib/database";
 export * from "./lib/hreflang";
 export * from "./lib/locales";
 export * from "./version";

package/src/lib/database.ts

@@ -0,0 +1,155 @@
+// Reading the brand's Database from a page, at request time (epic DBX, decision
+// DBX-D11).
+//
+// A published site holds no database binding and composes no SQL. It asks the
+// platform's public read route for rows of ONE table, and the platform decides
+// what that means: the table has to carry a `site_read` grant, the grant's
+// filters are added server side, and its column allowlist is what comes back.
+// So a page cannot read a draft by asking differently, and nothing here needs to
+// know how the data is stored.
+//
+// Where the endpoint and token come from: the publish gate, a module the
+// platform generates on every publish and puts in front of Astro's entry. It
+// assigns them to `globalThis.__ITERANT_SITE_DB__` at module scope. In `astro
+// dev` there is no gate, so the pair arrives as environment variables instead.
+//
+// Every failure answers with no rows and a console warning, never a throw: a
+// listing that renders empty is a page the customer can still see, and a build
+// that fails on a database blip is not.
+
+const GLOBAL_KEY = "__ITERANT_SITE_DB__";
+
+const URL_ENV = "ITERANT_SITE_DB_URL";
+
+const TOKEN_ENV = "ITERANT_SITE_DB_TOKEN";
+
+/** How long one read may take before the page renders without it. */
+const TIMEOUT_MS = 10_000;
+
+export type DatabaseFilterOp =
+  | "eq"
+  | "ne"
+  | "contains"
+  | "gt"
+  | "lt"
+  | "isnull";
+
+export type DatabaseFilter = {
+  column: string;
+  op: DatabaseFilterOp;
+  value?: string | number | boolean | null;
+};
+
+export type DatabaseSort = {
+  column: string;
+  dir: "asc" | "desc";
+};
+
+export type DatabaseQuery = {
+  /** Columns to read. Omitted means every column the grant allows. */
+  select?: string[];
+  /** Narrows the granted rows further. It can never widen them. */
+  filter?: DatabaseFilter[];
+  sort?: DatabaseSort[];
+  /** Rows per page, up to the platform's own ceiling of 200. */
+  limit?: number;
+  offset?: number;
+};
+
+export type DatabaseRow = Record<string, string | number | null>;
+
+export type DatabaseResult = {
+  rows: DatabaseRow[];
+  /** Every row matching the query, not just this page. */
+  total: number;
+};
+
+type SiteDatabaseHandoff = {
+  /** The complete read endpoint, brand and all. The site never assembles a
+   *  platform URL of its own. */
+  url: string;
+  token: string;
+};
+
+const EMPTY: DatabaseResult = { rows: [], total: 0 };
+
+function fromEnvironment(): SiteDatabaseHandoff | null {
+  const environment = (
+    globalThis as { process?: { env?: Record<string, string | undefined> } }
+  ).process?.env;
+  const url = environment?.[URL_ENV];
+  const token = environment?.[TOKEN_ENV];
+  return url && token ? { url, token } : null;
+}
+
+function handoff(): SiteDatabaseHandoff | null {
+  const baked = (globalThis as Record<string, unknown>)[GLOBAL_KEY];
+  if (baked && typeof baked === "object") {
+    const { url, token } = baked as Partial<SiteDatabaseHandoff>;
+    if (typeof url === "string" && typeof token === "string") {
+      return { url, token };
+    }
+  }
+  return fromEnvironment();
+}
+
+function warn(message: string, detail?: unknown): DatabaseResult {
+  console.warn(`[site-runtime] readDatabase: ${message}`, detail ?? "");
+  return EMPTY;
+}
+
+/**
+ * Read rows of one granted table.
+ *
+ * ```ts
+ * const { rows } = await readDatabase("articles", {
+ *   sort: [{ column: "published_at", dir: "desc" }],
+ *   limit: 20,
+ * });
+ * ```
+ *
+ * Call it in a page's frontmatter (server side). The rows are read on every
+ * request, so publishing a row shows it on the next page load with no rebuild.
+ */
+export async function readDatabase(
+  table: string,
+  query: DatabaseQuery = {},
+): Promise<DatabaseResult> {
+  const pair = handoff();
+  if (!pair) {
+    return warn(
+      `no database is connected to this site, so "${table}" read as empty. ` +
+        `A published site gets its connection from the publish gate; ` +
+        `a dev server gets it from ${URL_ENV} and ${TOKEN_ENV}.`,
+    );
+  }
+  let response: Response;
+  try {
+    response = await fetch(pair.url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${pair.token}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ table, ...query }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (error) {
+    return warn(`"${table}" could not be reached`, error);
+  }
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    return warn(`"${table}" answered ${response.status}`, detail.slice(0, 400));
+  }
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch (error) {
+    return warn(`"${table}" answered with a body that is not JSON`, error);
+  }
+  const page = body as Partial<DatabaseResult>;
+  if (!Array.isArray(page.rows)) {
+    return warn(`"${table}" answered without rows`, body);
+  }
+  return { rows: page.rows, total: Number(page.total ?? page.rows.length) };
+}