rastack 0.0.58 → 0.0.59

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.59](https://github.com/theserverkid/reactapistack/compare/v0.0.58...v0.0.59) (2026-07-18)
+
+
+### Bug Fixes
+
+* **ci:** valid pnpm-workspace.yaml (pnpm 11 moved overrides/onlyBuiltDependencies out of package.json); fixes ERR_PNPM_INVALID_WORKSPACE_CONFIGURATION ([b739531](https://github.com/theserverkid/reactapistack/commit/b739531a34d323afd2a0df3394d95563cfa175a0))
+* **hooks:** type the query compat layer against @tanstack/react-query v5, drop the dead react-query v3 dependency ([6642bc6](https://github.com/theserverkid/reactapistack/commit/6642bc68c917465bd763deaf4a5696983e1dde45))
+* **pkg:** add files allowlist so npm publishes only the framework surface (root-package layout no longer leaks engine/web/docs) ([a6bc9ee](https://github.com/theserverkid/reactapistack/commit/a6bc9ee93d794628be42bac14eef12575a5cdfba))
+
 ### [0.0.58](https://github.com/theserverkid/reactapistack/compare/v0.0.57...v0.0.58) (2026-07-18)
 
 ### [0.0.57](https://github.com/theserverkid/reactapistack/compare/v0.0.56...v0.0.57) (2026-07-18)

package/README.md

@@ -0,0 +1,190 @@
+# React API Stack
+
+**A full-stack framework on top of object storage. Scale to millions.**
+
+React API Stack is not a UI library and not "just" an API package — it is the
+**whole vertical**: the API exposure surface, the database storage layer, and the
+devops that ships them. You author **one TypeScript resource** and the framework
+derives everything from the React data hooks at the top to the Parquet files on
+S3 at the bottom, with a stateless Rust API in between.
+
+```
+            ┌─────────────────────────────────────────────┐
+            │                React / Expo                  │   API EXPOSURE
+            │   useData(Airport) / useForm(Flight)         │   SURFACE
+            └───────────────────────▲─────────────────────┘
+                                    │  your types, resolved via the manifest
+            ┌───────────────────────┴─────────────────────┐
+            │   TypeScript resources → `rastack compile`       │   API EXPOSURE
+            │   FK inferred from types → manifest+OpenAPI  │   SURFACE
+            └───────────────────────▲─────────────────────┘
+                                    │  schema.rastack.json (manifest)
+            ┌───────────────────────┴─────────────────────┐
+            │        Rust API (rastack-server, axum)           │   API + ADMIN
+            │  manifest-driven CRUD · FK validation ·      │
+            │  Django-admin-style /admin DB browser        │
+            └───────────────────────▲─────────────────────┘
+                                    │  object_store
+            ┌───────────────────────┴─────────────────────┐
+            │     Apache Iceberg tables on S3 (Parquet)    │   DATABASE
+            │   snapshots · ACID on object storage         │   STORAGE
+            └───────────────────────▲─────────────────────┘
+                                    │
+            ┌───────────────────────┴─────────────────────┐
+            │     AWS Lambda (stateless) + S3 (state)      │   DEVOPS
+            │   compute/storage separation, IaC, scale-to- │
+            │   zero — modelled on SurrealDB's Gen-3        │
+            └─────────────────────────────────────────────┘
+```
+
+## The three surfaces, one framework
+
+| Surface | What it is | Package(s) |
+| --- | --- | --- |
+| **API exposure** | TypeScript resources → `rastack compile` (FK inferred from types) → manifest + OpenAPI → pass your type to `useData` / `useForm` (typed TanStack Query hooks, no codegen) | the repo root, published as `rastack` (npm) — `components/`, `hooks/`, `theme/`, … |
+| **Database storage** | A stateless Rust API that stores every model as an Apache Iceberg table on object storage — snapshots, ACID on S3, columnar Parquet | `engine/` (`serve/rastack-server`) |
+| **DevOps** | Serverless Rust on AWS Lambda + S3: stateless compute, state in object storage, infrastructure-as-code, scale-to-zero — driven by `rastack init` / `deploy` / `ci` | `deploy/cloudformation/`, `examples/serverless/` |
+
+## Install the CLI
+
+One command, no clone — installs the `rastack` CLI into a per-user dir
+(`~/.rastack`, no sudo), the way you'd install Poetry or rustup. Node.js is the
+only prerequisite.
+
+```bash
+# macOS / Linux
+curl -fsSL https://reactapistack.com/setup.sh | sh
+
+# Windows (PowerShell) — from cmd, prefix with: powershell -c "…"
+irm https://reactapistack.com/setup.ps1 | iex
+```
+
+Prefer a package manager, or adding it to a single project? `npm install -g rastack`
+(global CLI) or `npm install -D rastack` (project dependency) work too. Pin a
+version with `RASTACK_VERSION=x.y.z` before the installer.
+
+## Author once, compile the rest
+
+```ts
+// resources/airports.ts
+import { resource, s } from "rastack/define";
+
+export const Airport = resource("airports", "airport", {
+  code: s.string({ maxLength: 3, unique: true }),
+  name: s.string({ maxLength: 120 }),
+});
+
+export const Terminal = resource("airports", "terminal", {
+  airport: s.ref(() => Airport),   // ← foreign key, detected from the type
+  label: s.string({ maxLength: 20 }),
+});
+```
+
+```bash
+rastack compile resources .rastack # TS → schema.rastack.json + openapi.json (FK detected)
+rastack dev                        # the app + admin, in-browser over the WASM engine
+rastack admin                      # Django-admin-style DB browser
+```
+
+```tsx
+// Then just pass your type to the hooks — nothing is generated into your repo.
+const airports = useData(Airport);
+<DataTable query={airports} />
+
+const form = useForm(Flight, { id });
+form.transition("board");          // a typed, state-machine-safe save
+```
+
+The compile step runs a real TypeScript type checker and infers relationships
+straight from the field types — see
+[docs/compile-and-relations.md](docs/compile-and-relations.md); the hooks
+resolve your types against the compiled manifest at runtime — see
+[docs/typed-hooks.md](docs/typed-hooks.md). Resources can declare **state
+transitions** (`scheduled → boarding → departed`), compiled into the manifest
+and enforced on every write surface — an illegal jump is a 400 from the form,
+the importer, the server, and the in-browser WASM engine alike.
+
+## Ship it — one command per stage
+
+The DevOps surface is a CLI too. A new repo is scaffolded, configured, and
+deployed with three commands, and GitHub Actions stays a one-liner because the
+pipeline lives in the CLI, not the YAML:
+
+```bash
+rastack init                       # template .github/workflows + .rastack/deploy.json
+rastack deploy                     # configure the deployment; print the stack launch command
+rastack ci deploy                  # what CI runs: build the arm64 Lambda, bake the JWKS, ship the code
+```
+
+`init` scaffolds the base GitHub Actions and a deploy config (defaulting the
+GitHub coordinates from your `origin` remote); `deploy` fills that config in and
+prints the one-time `aws cloudformation deploy` plus the repo Variables to wire;
+`ci` runs the build/deploy pipeline so a workflow is just
+`run: rastack ci deploy` (`rastack ci --plan deploy` prints every step). Full
+guide: **[docs/serverless-deploy.md](docs/serverless-deploy.md)**.
+
+## Run the whole API in the browser
+
+The Rust API is stateless compute over object storage, so it also compiles to
+**WebAssembly and runs entirely in the browser** — no server, no network. One
+setting on the React provider picks where the API runs; the hooks never
+change:
+
+```tsx
+// Local-first dev: the entire API in the browser, over the data/ Iceberg files.
+<RAStackProvider mode="local" manifest={schema} warehouseBaseUrl="/data/warehouse/">
+  <App />
+</RAStackProvider>
+
+// Production: the same code on AWS Lambda + S3.
+<RAStackProvider mode="remote" baseURL="https://api.example.com">…</RAStackProvider>
+
+// Client-only, reading and writing S3 directly.
+<RAStackProvider mode="s3" manifest={schema} warehouseBaseUrl="https://bucket.s3.amazonaws.com/warehouse/">…</RAStackProvider>
+```
+
+`local` and `s3` run the same `rastack-api-core` request logic (CRUD, foreign-key
+validation, DRF-shaped lists) that Lambda runs — and, because Arrow/Parquet
+compile to WebAssembly, the browser reads and writes the **same Parquet Iceberg
+files** the server does. The local database is just a committed directory of
+those files under `data/`. Full guide:
+**[docs/local-wasm-dev.md](docs/local-wasm-dev.md)**.
+
+## Why "on top of object storage"?
+
+Traditional stacks pin you to a server-bound RDBMS. React API Stack instead puts
+**S3 at the bottom of the stack as the system of record** and runs the API as
+**stateless, elastic compute** on top — the same compute/storage-separation
+principle behind [SurrealDB's Gen-3 architecture](https://surrealdb.com/platform/surrealds).
+That gives you:
+
+- **Scale to millions** — compute scales horizontally and independently of data;
+  storage is S3's 11-nines durability and effectively unbounded capacity.
+- **Scale to zero** — when no requests are in flight, no compute runs and you pay
+  only for object storage.
+- **No vendor lock-in** — data lives in open Apache Iceberg / Parquet, readable by
+  Spark, DuckDB, Trino, and Polars.
+
+## Start here
+
+- **[docs/compile-and-relations.md](docs/compile-and-relations.md)** — the
+  TypeScript-first compile step and foreign-key inference.
+- **[docs/typed-hooks.md](docs/typed-hooks.md)** — pass your type to
+  `useData` / `useForm`, and state transitions as typesafe backend functions.
+- **[docs/architecture.md](docs/architecture.md)** — the full serverless,
+  object-storage architecture and how the three surfaces compose.
+- **[docs/local-wasm-dev.md](docs/local-wasm-dev.md)** — running the whole API in
+  the browser via WebAssembly, and the `RAStackProvider` mode switch.
+- **[engine/](engine/)** — the Rust engine: `core/` (manifest, Iceberg storage, request brain) and `serve/` (axum API, server binary, wasm).
+- **[examples/serverless/](examples/serverless/)** — Lambda + S3 + IaC.
+- **[CLAUDE.md](CLAUDE.md)** — codebase guide for contributors.
+- **Building with an LLM?** The documentation site is mirrored as plain Markdown
+  for agents — [reactapistack.com/llms.txt](https://reactapistack.com/llms.txt)
+  (curated index), [llms-full.txt](https://reactapistack.com/llms-full.txt)
+  (every page in one file), or any page at `/docs/<slug>.md`.
+
+> **Performance note.** Apache Iceberg over S3 is currently the portable,
+> correct-by-default storage path, not the fastest one. S3 first-byte latency
+> dominates small OLTP reads. The roadmap closes this with a custom S3 backend
+> fronted by a DynamoDB metadata/cache layer (and optionally EFS for hot IO) —
+> see [docs/architecture.md](docs/architecture.md#performance-roadmap).

package/dist/deploy/ci.js

@@ -50,7 +50,7 @@ function stackOutput(cfg, outputKey, literal) {
 }
 /** The Lambda staging directory `cargo lambda build` writes the binary into. */
 function stageDir(cfg) {
-    return `rust/target/lambda/${cfg.lambda.bin}`;
+    return `engine/target/lambda/${cfg.lambda.bin}`;
 }
 /** `check` — validate the resource graph and compile the manifest. A CI gate. */
 function checkSteps(cfg, bin) {
@@ -76,7 +76,7 @@ function buildSteps(cfg, opts = {}) {
         {
             name: "Cross-build the Lambda binary",
             run: `cargo lambda build --release ${archFlag} --bin ${cfg.lambda.bin} --features ${cfg.lambda.features}`,
-            cwd: "rust",
+            cwd: "engine",
         },
         {
             name: "Bake the Cognito JWKS into the bundle",

package/dist/deploy/io.js

@@ -85,8 +85,8 @@ function resolveDeployAsset(relPath, cwd = process.cwd()) {
     const candidates = [
         // Installed package: dist/deploy/io.js → dist/templates/cloudformation/…
         path.join(__dirname, "..", "templates", "cloudformation", relPath),
-        // Running from TS source: tools/src/deploy/io.ts → repo-root deploy/…
-        path.join(__dirname, "..", "..", "..", "deploy", "cloudformation", relPath),
+        // Running from TS source: src/deploy/io.ts → repo-root deploy/…
+        path.join(__dirname, "..", "..", "deploy", "cloudformation", relPath),
         // Invoked inside the framework repo itself (cwd is the repo root).
         path.join(cwd, "deploy", "cloudformation", relPath),
     ];

package/dist/dev/harness.d.ts

@@ -74,7 +74,7 @@ export declare function contentType(filePath: string): string;
  * Ordered directories to look for the prebuilt wasm bundle (`rastack_wasm.js` +
  * `rastack_wasm_bg.wasm`). The bundle is shipped inside the package
  * (`dist/wasm/`, copied at build), so `rastack dev` works from any repo with no
- * cargo; the repo-local `tools/wasm/` (from a source build) and a sibling of the
+ * cargo; the repo-local `wasm/` (from a source build) and a sibling of the
  * running module are fallbacks for development. `dirnameDir` is the directory of
  * the compiled `rastack-dev.js` (`dist/`), so `../wasm` and `./wasm` cover both
  * `dist/rastack-dev.js` → `dist/wasm` and `dist/dev/…` layouts.

package/dist/dev/harness.js

@@ -171,7 +171,7 @@ function contentType(filePath) {
  * Ordered directories to look for the prebuilt wasm bundle (`rastack_wasm.js` +
  * `rastack_wasm_bg.wasm`). The bundle is shipped inside the package
  * (`dist/wasm/`, copied at build), so `rastack dev` works from any repo with no
- * cargo; the repo-local `tools/wasm/` (from a source build) and a sibling of the
+ * cargo; the repo-local `wasm/` (from a source build) and a sibling of the
  * running module are fallbacks for development. `dirnameDir` is the directory of
  * the compiled `rastack-dev.js` (`dist/`), so `../wasm` and `./wasm` cover both
  * `dist/rastack-dev.js` → `dist/wasm` and `dist/dev/…` layouts.
@@ -180,7 +180,6 @@ function wasmBundleCandidates(dirnameDir, cwd = process.cwd()) {
     return [
         path.join(dirnameDir, "wasm"),
         path.join(dirnameDir, "..", "wasm"),
-        path.join(cwd, "tools", "wasm"),
         path.join(cwd, "wasm"),
     ];
 }

package/dist/external/cache.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The proxy's response cache — the reason `all API calls are proxied in Lambda`.
+ *
+ * A tiny pure abstraction (`get`/`set` over string keys) so the *same* handler
+ * runs against an in-memory `Map` (the mini `rastack dev` service, a warm Lambda
+ * container) or a shared store (DynamoDB/ElastiCache in production) with no code
+ * change. Freshness and ETag bookkeeping are pure functions here; the transport
+ * (conditional `If-None-Match` requests) lives in the handler.
+ */
+export interface CacheEntry {
+    /** The normalised rastack response body that was cached. */
+    value: unknown;
+    /** Epoch ms the entry was (re)validated. */
+    storedAt: number;
+    /** The upstream ETag, if any, for conditional revalidation. */
+    etag?: string;
+}
+export interface ProxyCache {
+    get(key: string): CacheEntry | undefined;
+    set(key: string, entry: CacheEntry): void;
+    delete(key: string): void;
+}
+/** An in-memory cache — the default for `rastack dev` and warm Lambda containers. */
+export declare function memoryCache(): ProxyCache;
+/** A stable cache key for a request (order-independent over query params). */
+export declare function cacheKey(app: string, model: string, id: string | undefined, query: Record<string, string[]>): string;
+/** Whether an entry is still within its TTL (and so served without an upstream call). */
+export declare function isFresh(entry: CacheEntry, ttlMs: number, now: number): boolean;

package/dist/external/cache.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * The proxy's response cache — the reason `all API calls are proxied in Lambda`.
+ *
+ * A tiny pure abstraction (`get`/`set` over string keys) so the *same* handler
+ * runs against an in-memory `Map` (the mini `rastack dev` service, a warm Lambda
+ * container) or a shared store (DynamoDB/ElastiCache in production) with no code
+ * change. Freshness and ETag bookkeeping are pure functions here; the transport
+ * (conditional `If-None-Match` requests) lives in the handler.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memoryCache = memoryCache;
+exports.cacheKey = cacheKey;
+exports.isFresh = isFresh;
+/** An in-memory cache — the default for `rastack dev` and warm Lambda containers. */
+function memoryCache() {
+    const store = new Map();
+    return {
+        get: (key) => store.get(key),
+        set: (key, entry) => void store.set(key, entry),
+        delete: (key) => void store.delete(key),
+    };
+}
+/** A stable cache key for a request (order-independent over query params). */
+function cacheKey(app, model, id, query) {
+    const params = Object.keys(query)
+        .sort()
+        .map((k) => `${k}=${[...query[k]].sort().join(",")}`)
+        .join("&");
+    return `${app}.${model}/${id ?? "list"}?${params}`;
+}
+/** Whether an entry is still within its TTL (and so served without an upstream call). */
+function isFresh(entry, ttlMs, now) {
+    return now - entry.storedAt < ttlMs;
+}

package/dist/external/envelope.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Normalise an upstream response into rastack's REST contract — the DRF-shaped
+ * list envelope and bare detail object the typed hooks and `<DataTable>` expect,
+ * identical to what the Rust API and the WASM/local engine emit.
+ *
+ * External APIs rarely page the way rastack does (GitHub uses `per_page` + Link
+ * headers; a GraphQL list just returns an array), so the envelope is synthesised
+ * from what we have: the page the client asked for and the number of items this
+ * page actually returned. `count`/`last` are best-effort when the upstream total
+ * is unknown — enough for the pager to advance while there is a full page.
+ */
+export interface ListEnvelope {
+    results: Record<string, unknown>[];
+    pagination: {
+        current: number;
+        last: number;
+        next: number | null;
+        previous: number | null;
+        page_size: number;
+        /** Best-effort total; equals what we can prove when the upstream omits it. */
+        count: number;
+    };
+}
+export interface NormalizeOptions {
+    page: number;
+    pageSize: number;
+    primaryKey: string;
+    fields?: string[];
+    /** A known upstream total, if the transport could determine one. */
+    totalCount?: number;
+}
+/** Shape a page of upstream items into the list envelope. */
+export declare function toListEnvelope(items: unknown, opts: NormalizeOptions): ListEnvelope;
+/** Shape a single upstream object into a rastack detail row. */
+export declare function toDetail(item: unknown, primaryKey: string, fields?: string[]): Record<string, unknown> | null;

package/dist/external/envelope.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Normalise an upstream response into rastack's REST contract — the DRF-shaped
+ * list envelope and bare detail object the typed hooks and `<DataTable>` expect,
+ * identical to what the Rust API and the WASM/local engine emit.
+ *
+ * External APIs rarely page the way rastack does (GitHub uses `per_page` + Link
+ * headers; a GraphQL list just returns an array), so the envelope is synthesised
+ * from what we have: the page the client asked for and the number of items this
+ * page actually returned. `count`/`last` are best-effort when the upstream total
+ * is unknown — enough for the pager to advance while there is a full page.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toListEnvelope = toListEnvelope;
+exports.toDetail = toDetail;
+const util_1 = require("./util");
+/** Shape a page of upstream items into the list envelope. */
+function toListEnvelope(items, opts) {
+    const rows = (Array.isArray(items) ? items : [])
+        .filter((r) => !!r && typeof r === "object")
+        .map((r) => (0, util_1.projectFields)((0, util_1.ensureId)(r, opts.primaryKey), opts.fields));
+    const { page, pageSize } = opts;
+    // A full page implies there may be more; a short page is the last one.
+    const hasMore = rows.length >= pageSize;
+    const count = opts.totalCount ?? (page - 1) * pageSize + rows.length;
+    const last = opts.totalCount
+        ? Math.max(1, Math.ceil(opts.totalCount / pageSize))
+        : hasMore
+            ? page + 1
+            : page;
+    return {
+        results: rows,
+        pagination: {
+            current: page,
+            last,
+            next: page < last ? page + 1 : null,
+            previous: page > 1 ? page - 1 : null,
+            page_size: pageSize,
+            count,
+        },
+    };
+}
+/** Shape a single upstream object into a rastack detail row. */
+function toDetail(item, primaryKey, fields) {
+    if (!item || typeof item !== "object")
+        return null;
+    return (0, util_1.projectFields)((0, util_1.ensureId)(item, primaryKey), fields);
+}

package/dist/external/graphql.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Build the upstream request for a GraphQL-backed resource (Expo's API is
+ * GraphQL, for instance), and pull the item array / detail object out of the
+ * `data` payload. A GraphQL call is always a POST of `{ query, variables }`; the
+ * rastack list params map onto the query's variables (`page_size` → `first`,
+ * etc.), so the same `/api/{app}/v1/{model}/` contract fronts a GraphQL API with
+ * no client awareness that it isn't REST.
+ */
+import type { GraphQLBinding } from "./types";
+export interface GraphQLRequest {
+    url: string;
+    method: "POST";
+    headers: Record<string, string>;
+    body: string;
+}
+/** Build the GraphQL list request. */
+export declare function graphqlListRequest(binding: GraphQLBinding, query: Record<string, string[]>, headers: Record<string, string>): GraphQLRequest;
+/** Build the GraphQL detail request. Throws if the binding has no detail query. */
+export declare function graphqlDetailRequest(binding: GraphQLBinding, id: string, headers: Record<string, string>): GraphQLRequest;
+/** A GraphQL response is `{ data, errors }`; surface errors, else return `data`. */
+export declare function graphqlData(body: unknown): unknown;
+/** Extract the item array from a GraphQL list response. */
+export declare function graphqlListItems(binding: GraphQLBinding, body: unknown): unknown;
+/** Extract the detail object from a GraphQL detail response. */
+export declare function graphqlDetailItem(binding: GraphQLBinding, body: unknown): unknown;

package/dist/external/graphql.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Build the upstream request for a GraphQL-backed resource (Expo's API is
+ * GraphQL, for instance), and pull the item array / detail object out of the
+ * `data` payload. A GraphQL call is always a POST of `{ query, variables }`; the
+ * rastack list params map onto the query's variables (`page_size` → `first`,
+ * etc.), so the same `/api/{app}/v1/{model}/` contract fronts a GraphQL API with
+ * no client awareness that it isn't REST.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.graphqlListRequest = graphqlListRequest;
+exports.graphqlDetailRequest = graphqlDetailRequest;
+exports.graphqlData = graphqlData;
+exports.graphqlListItems = graphqlListItems;
+exports.graphqlDetailItem = graphqlDetailItem;
+const util_1 = require("./util");
+function buildVariables(binding, query, id) {
+    const vars = { ...(binding.variables ?? {}) };
+    const map = binding.variableMap ?? {};
+    const put = (rastackKey, raw) => {
+        const name = map[rastackKey];
+        if (!name || raw == null || raw === "")
+            return;
+        // page_size / page are numbers in GraphQL land; coerce when they parse.
+        const num = Number(raw);
+        vars[name] = Number.isFinite(num) && /^\d+$/.test(raw) ? num : raw;
+    };
+    put("page", (0, util_1.firstParam)(query, "page"));
+    put("page_size", (0, util_1.firstParam)(query, "page_size"));
+    put("search", (0, util_1.firstParam)(query, "search"));
+    put("order_by", (0, util_1.firstParam)(query, "order_by"));
+    if (id != null && map.id)
+        vars[map.id] = id;
+    return vars;
+}
+/** Build the GraphQL list request. */
+function graphqlListRequest(binding, query, headers) {
+    return {
+        url: binding.baseUrl,
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...headers },
+        body: JSON.stringify({
+            query: binding.listQuery,
+            variables: buildVariables(binding, query),
+        }),
+    };
+}
+/** Build the GraphQL detail request. Throws if the binding has no detail query. */
+function graphqlDetailRequest(binding, id, headers) {
+    if (!binding.detailQuery) {
+        throw new Error(`GraphQL binding ${binding.app}.${binding.model} has no detailQuery.`);
+    }
+    return {
+        url: binding.baseUrl,
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...headers },
+        body: JSON.stringify({
+            query: binding.detailQuery,
+            variables: buildVariables(binding, {}, id),
+        }),
+    };
+}
+/** A GraphQL response is `{ data, errors }`; surface errors, else return `data`. */
+function graphqlData(body) {
+    const payload = body;
+    if (payload?.errors && payload.errors.length) {
+        throw new Error(`GraphQL error: ${payload.errors.map((e) => e.message ?? "unknown").join("; ")}`);
+    }
+    return payload?.data;
+}
+/** Extract the item array from a GraphQL list response. */
+function graphqlListItems(binding, body) {
+    return (0, util_1.getPath)(graphqlData(body), binding.itemsPath);
+}
+/** Extract the detail object from a GraphQL detail response. */
+function graphqlDetailItem(binding, body) {
+    return (0, util_1.getPath)(graphqlData(body), binding.detailPath ?? binding.itemsPath);
+}

package/dist/external/handler.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The proxy core — one pure(ish) function from a rastack request to a rastack
+ * response, given the bindings and injected effects (`fetch`, cache, clock,
+ * auth). This is the "work" the user's Lambda does; the mini service inside
+ * `rastack dev` and the deployed Lambda are both thin adapters that parse an
+ * HTTP request into {@link RastackRequest}, call {@link handleExternalRequest},
+ * and serialise the result.
+ *
+ * Responsibilities, in order:
+ *   1. Resolve the binding for `app.model` (404 if none — not an external model).
+ *   2. Serve a fresh cache entry without any upstream call (the cache is the
+ *      whole point of the proxy).
+ *   3. Otherwise call the upstream (REST or GraphQL), using a conditional
+ *      `If-None-Match` when we hold an ETag so a `304` costs no rate-limit.
+ *   4. Normalise into the DRF envelope / detail row, cache it, and return it.
+ *
+ * Auth (the GitHub/Expo token from Secrets Manager in prod, an env var in dev)
+ * is injected by `deps.authHeaders`, so **no credential is ever hard-coded here**.
+ */
+import { type ProxyCache } from "./cache";
+import { type FetchLike, type ResourceBinding, type ResourceResolver } from "./types";
+export interface RastackRequest {
+    app: string;
+    model: string;
+    /** Present for a detail request (`/…/{model}/{id}/`). */
+    id?: string;
+    query: Record<string, string[]>;
+}
+export interface RastackResponse {
+    status: number;
+    body: unknown;
+    /** Whether this response was served from cache without an upstream call. */
+    cached: boolean;
+}
+export interface HandlerDeps {
+    fetch: FetchLike;
+    cache: ProxyCache;
+    now: () => number;
+    /**
+     * Resolve upstream auth/headers for an app — e.g. `{ Authorization: "Bearer …" }`.
+     * Reads Secrets Manager in the Lambda; reads env vars in `rastack dev`.
+     */
+    authHeaders?: (app: string) => Record<string, string> | Promise<Record<string, string>>;
+    /**
+     * Named resolvers for {@link ResolverBinding}s — the app plugs in transports
+     * the core doesn't ship (e.g. an AWS SDK resolver), keeping the core
+     * dependency-free.
+     */
+    resolvers?: Record<string, ResourceResolver>;
+}
+/** Handle one rastack request against the external bindings. */
+export declare function handleExternalRequest(req: RastackRequest, bindings: ResourceBinding[], deps: HandlerDeps): Promise<RastackResponse>;