rastack 0.0.57 → 0.0.59

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"),
     ];
 }
@@ -202,13 +201,30 @@ function renderShell(title = "React API Stack — admin") {
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <title>${title}</title>
 <style>
-  html, body { margin: 0; height: 100%; }
+  html, body { margin: 0; height: 100%; background: #F2F5FB;
+    font-family: "Inter", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; }
+  @media (prefers-color-scheme: dark) { html, body { background: #06080F; } }
   #root { min-height: 100%; }
-  .rastack-boot { font: 14px system-ui, sans-serif; padding: 2rem; color: #555; }
+  .rastack-boot { min-height: 100vh; display: flex; flex-direction: column;
+    align-items: center; justify-content: center; gap: 20px; }
+  .rastack-boot-logo { width: 60px; height: 60px; border-radius: 18px; background: #4F6BFF;
+    box-shadow: 0 8px 24px rgba(79,107,255,0.30); animation: rastack-boot-bob 3s ease-in-out infinite; }
+  .rastack-boot-track { position: relative; width: 168px; height: 4px; border-radius: 999px;
+    overflow: hidden; background: rgba(11,16,32,0.10); }
+  @media (prefers-color-scheme: dark) { .rastack-boot-track { background: rgba(233,239,255,0.14); } }
+  .rastack-boot-track::after { content: ""; position: absolute; top: 0; left: -42%; height: 100%;
+    width: 40%; border-radius: inherit; background: linear-gradient(90deg, transparent, #4F6BFF);
+    animation: rastack-boot-slide 1.25s cubic-bezier(0.5,0.1,0.3,1) infinite; }
+  @keyframes rastack-boot-bob { 0%,100% { transform: translateY(0); } 50% { transform: translateY(-3px); } }
+  @keyframes rastack-boot-slide { to { left: 100%; } }
+  @media (prefers-reduced-motion: reduce) {
+    .rastack-boot-logo { animation: none; }
+    .rastack-boot-track::after { animation: none; left: 0; width: 100%; }
+  }
 </style>
 </head>
 <body>
-<div id="root"><div class="rastack-boot">Loading the WASM engine…</div></div>
+<div id="root"><div class="rastack-boot"><div class="rastack-boot-logo"></div><div class="rastack-boot-track"></div></div></div>
 <script src="/dev/admin.js"></script>
 </body>
 </html>

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>;

package/dist/external/handler.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * 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**.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleExternalRequest = handleExternalRequest;
+const cache_1 = require("./cache");
+const envelope_1 = require("./envelope");
+const graphql_1 = require("./graphql");
+const rest_1 = require("./rest");
+const types_1 = require("./types");
+const util_1 = require("./util");
+const DEFAULT_TTL_MS = 60000;
+function pageParams(query) {
+    const page = Math.max(1, parseInt((0, util_1.firstParam)(query, "page") ?? "1", 10) || 1);
+    const pageSize = Math.max(1, parseInt((0, util_1.firstParam)(query, "page_size") ?? "20", 10) || 20);
+    return { page, pageSize };
+}
+async function upstreamHeaders(binding, deps) {
+    const auth = deps.authHeaders ? await deps.authHeaders(binding.app) : {};
+    return { ...(binding.headers ?? {}), ...auth };
+}
+/** Fetch + parse an upstream request, applying a conditional ETag when supplied. */
+async function callUpstream(req, deps, etag) {
+    const headers = { ...req.headers };
+    if (etag)
+        headers["If-None-Match"] = etag;
+    const res = await deps.fetch(req.url, {
+        method: req.method,
+        headers,
+        body: "body" in req ? req.body : undefined,
+    });
+    if (res.status === 304)
+        return { status: 304, body: undefined, etag };
+    const nextEtag = res.headers.get("etag") ?? undefined;
+    const body = res.status === 204 ? null : await res.json();
+    return { status: res.status, body, etag: nextEtag };
+}
+/** Handle one rastack request against the external bindings. */
+async function handleExternalRequest(req, bindings, deps) {
+    const binding = (0, types_1.findBinding)(bindings, req.app, req.model);
+    if (!binding) {
+        return { status: 404, body: { detail: `No external binding for ${req.app}.${req.model}.` }, cached: false };
+    }
+    const ttl = binding.ttlMs ?? DEFAULT_TTL_MS;
+    const pk = binding.primaryKey ?? "id";
+    const key = (0, cache_1.cacheKey)(req.app, req.model, req.id, req.query);
+    const now = deps.now();
+    const hit = deps.cache.get(key);
+    if (hit && (0, cache_1.isFresh)(hit, ttl, now)) {
+        return { status: 200, body: hit.value, cached: true };
+    }
+    const headers = await upstreamHeaders(binding, deps);
+    const isDetail = req.id != null;
+    try {
+        // Resolver transport: no HTTP — call the injected resolver, normalise, cache.
+        if (binding.transport === "resolver") {
+            const resolver = deps.resolvers?.[binding.resolver];
+            if (!resolver) {
+                return {
+                    status: 501,
+                    body: { detail: `No resolver "${binding.resolver}" registered for ${req.app}.${req.model}.` },
+                    cached: false,
+                };
+            }
+            const data = await resolver({ app: req.app, model: req.model, id: req.id, query: req.query });
+            let value;
+            if (isDetail) {
+                value = (0, envelope_1.toDetail)(data, pk, binding.fields);
+                if (value == null)
+                    return { status: 404, body: { detail: "Not found" }, cached: false };
+            }
+            else {
+                const { page, pageSize } = pageParams(req.query);
+                value = (0, envelope_1.toListEnvelope)(data, { page, pageSize, primaryKey: pk, fields: binding.fields });
+            }
+            deps.cache.set(key, { value, storedAt: now });
+            return { status: 200, body: value, cached: false };
+        }
+        // Build the upstream request for this transport + list/detail shape.
+        const upstream = binding.transport === "rest"
+            ? isDetail
+                ? (0, rest_1.restDetailRequest)(binding, req.id, headers)
+                : (0, rest_1.restListRequest)(binding, req.query, headers)
+            : isDetail
+                ? (0, graphql_1.graphqlDetailRequest)(binding, req.id, headers)
+                : (0, graphql_1.graphqlListRequest)(binding, req.query, headers);
+        const result = await callUpstream(upstream, deps, hit?.etag);
+        // A revalidated ETag: refresh the stored timestamp and serve the cache.
+        if (result.status === 304 && hit) {
+            deps.cache.set(key, { ...hit, storedAt: now });
+            return { status: 200, body: hit.value, cached: true };
+        }
+        if (result.status >= 400) {
+            return { status: result.status, body: result.body ?? { detail: "Upstream error." }, cached: false };
+        }
+        // Extract the item(s) for this transport and normalise into the contract.
+        let value;
+        if (isDetail) {
+            const item = binding.transport === "rest"
+                ? result.body
+                : (0, graphql_1.graphqlDetailItem)(binding, result.body);
+            value = (0, envelope_1.toDetail)(item, pk, binding.fields);
+            if (value == null)
+                return { status: 404, body: { detail: "Not found" }, cached: false };
+        }
+        else {
+            const items = binding.transport === "rest"
+                ? (0, rest_1.restListItems)(binding, result.body)
+                : (0, graphql_1.graphqlListItems)(binding, result.body);
+            const { page, pageSize } = pageParams(req.query);
+            value = (0, envelope_1.toListEnvelope)(items, { page, pageSize, primaryKey: pk, fields: binding.fields });
+        }
+        deps.cache.set(key, { value, storedAt: now, etag: result.etag });
+        return { status: 200, body: value, cached: false };
+    }
+    catch (err) {
+        // A stale cache entry is better than a hard failure while iterating.
+        if (hit)
+            return { status: 200, body: hit.value, cached: true };
+        return { status: 502, body: { detail: err.message }, cached: false };
+    }
+}

package/dist/external/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `rastack` external-API proxy core.
+ *
+ * Serves external REST/GraphQL APIs (GitHub, Expo, AWS) over the rastack
+ * `/api/{app}/v1/{model}/` contract so the *normal typed hooks* consume them
+ * unchanged: caches responses, injects auth, and normalises upstream payloads
+ * into the DRF envelope. Transport-agnostic and effect-injected, so the identical
+ * core runs in the deployed Lambda and in the mini service inside `rastack dev`.
+ */
+export * from "./types";
+export * from "./cache";
+export * from "./envelope";
+export * from "./rest";
+export * from "./graphql";
+export * from "./route";
+export * from "./service";
+export * from "./lambda";
+export { handleExternalRequest, type RastackRequest, type RastackResponse, type HandlerDeps, } from "./handler";
+export { getPath } from "./util";

package/dist/external/index.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * `rastack` external-API proxy core.
+ *
+ * Serves external REST/GraphQL APIs (GitHub, Expo, AWS) over the rastack
+ * `/api/{app}/v1/{model}/` contract so the *normal typed hooks* consume them
+ * unchanged: caches responses, injects auth, and normalises upstream payloads
+ * into the DRF envelope. Transport-agnostic and effect-injected, so the identical
+ * core runs in the deployed Lambda and in the mini service inside `rastack dev`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPath = exports.handleExternalRequest = void 0;
+__exportStar(require("./types"), exports);
+__exportStar(require("./cache"), exports);
+__exportStar(require("./envelope"), exports);
+__exportStar(require("./rest"), exports);
+__exportStar(require("./graphql"), exports);
+__exportStar(require("./route"), exports);
+__exportStar(require("./service"), exports);
+__exportStar(require("./lambda"), exports);
+var handler_1 = require("./handler");
+Object.defineProperty(exports, "handleExternalRequest", { enumerable: true, get: function () { return handler_1.handleExternalRequest; } });
+var util_1 = require("./util");
+Object.defineProperty(exports, "getPath", { enumerable: true, get: function () { return util_1.getPath; } });

package/dist/external/lambda.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The AWS Lambda adapter — the deployed twin of the `rastack dev` mini service.
+ *
+ * Both are thin shells over the same pure {@link handleExternalRequest} core:
+ * parse the incoming request into a {@link RastackRequest}, run the handler,
+ * serialise the result. The differences are injected, not branched:
+ *   • **auth** — dev reads `GITHUB_TOKEN` from the environment; the Lambda's
+ *     `deps.authHeaders` reads AWS Secrets Manager (the app supplies that
+ *     closure, so no AWS SDK import leaks into the framework).
+ *   • **cache** — dev uses an in-process `Map`; the Lambda can pass a
+ *     DynamoDB/ElastiCache-backed {@link ProxyCache} for cross-invocation hits.
+ *
+ * Authn/z is handled *in front* by an API Gateway Cognito authorizer, so by the
+ * time an event reaches here the caller's JWT is already verified; this adapter
+ * only serves data. It accepts both API Gateway payload formats (HTTP API v2 and
+ * REST/proxy v1), so it drops into either integration.
+ */
+import { type HandlerDeps } from "./handler";
+import type { ResourceBinding } from "./types";
+/** The subset of an API Gateway event this adapter reads (v1 and v2 tolerant). */
+export interface ApiGatewayEvent {
+    /** HTTP API (payload v2). */
+    rawPath?: string;
+    rawQueryString?: string;
+    requestContext?: {
+        http?: {
+            method?: string;
+        };
+    };
+    /** REST API / proxy (payload v1). */
+    path?: string;
+    httpMethod?: string;
+    queryStringParameters?: Record<string, string | undefined> | null;
+    multiValueQueryStringParameters?: Record<string, string[] | undefined> | null;
+}
+export interface ApiGatewayResult {
+    statusCode: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/** Reconstruct the request URL (path + query) from either payload format. */
+export declare function eventToUrl(event: ApiGatewayEvent): string;
+/** The HTTP method from either payload format (defaults to GET). */
+export declare function eventMethod(event: ApiGatewayEvent): string;
+/**
+ * Handle one API Gateway event: parse → run the proxy core → serialise. Returns
+ * a proxy-integration result (`statusCode`/`headers`/`body`) for either format.
+ */
+export declare function handleLambdaEvent(event: ApiGatewayEvent, bindings: ResourceBinding[], deps: HandlerDeps): Promise<ApiGatewayResult>;