rastack 0.0.58 → 0.0.59

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

package/dist/external/lambda.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eventToUrl = eventToUrl;
+exports.eventMethod = eventMethod;
+exports.handleLambdaEvent = handleLambdaEvent;
+const handler_1 = require("./handler");
+const route_1 = require("./route");
+const JSON_HEADERS = {
+    "Content-Type": "application/json; charset=utf-8",
+    "Cache-Control": "no-store",
+};
+/** Reconstruct the request URL (path + query) from either payload format. */
+function eventToUrl(event) {
+    if (event.rawPath != null) {
+        const qs = event.rawQueryString ? `?${event.rawQueryString}` : "";
+        return `${event.rawPath}${qs}`;
+    }
+    const path = event.path ?? "/";
+    const search = new URLSearchParams();
+    const multi = event.multiValueQueryStringParameters;
+    if (multi) {
+        for (const [key, values] of Object.entries(multi)) {
+            for (const v of values ?? [])
+                if (v != null)
+                    search.append(key, v);
+        }
+    }
+    else if (event.queryStringParameters) {
+        for (const [key, v] of Object.entries(event.queryStringParameters)) {
+            if (v != null)
+                search.append(key, v);
+        }
+    }
+    const qs = search.toString();
+    return `${path}${qs ? `?${qs}` : ""}`;
+}
+/** The HTTP method from either payload format (defaults to GET). */
+function eventMethod(event) {
+    return (event.requestContext?.http?.method ?? event.httpMethod ?? "GET").toUpperCase();
+}
+/**
+ * Handle one API Gateway event: parse → run the proxy core → serialise. Returns
+ * a proxy-integration result (`statusCode`/`headers`/`body`) for either format.
+ */
+async function handleLambdaEvent(event, bindings, deps) {
+    // Reads are open (viewing is public; the authorizer gated the request); the
+    // proxy only serves GET. Anything else is a fast, cheap rejection.
+    if (eventMethod(event) !== "GET") {
+        return {
+            statusCode: 405,
+            headers: JSON_HEADERS,
+            body: JSON.stringify({ detail: "Method not allowed" }),
+        };
+    }
+    const req = (0, route_1.parseApiPath)(eventToUrl(event));
+    if (!req) {
+        return {
+            statusCode: 404,
+            headers: JSON_HEADERS,
+            body: JSON.stringify({ detail: "Not an /api/{app}/v1/{model}/ route." }),
+        };
+    }
+    const result = await (0, handler_1.handleExternalRequest)(req, bindings, deps);
+    return {
+        statusCode: result.status,
+        headers: { ...JSON_HEADERS, "X-Rastack-Cache": result.cached ? "hit" : "miss" },
+        body: JSON.stringify(result.body),
+    };
+}

package/dist/external/rest.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Build the upstream HTTP request for a REST-backed resource, and pull the item
+ * array out of the response body. Pure string/URL work — no network — so it is
+ * unit-tested directly.
+ */
+import type { RestBinding } from "./types";
+export interface UpstreamRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+}
+/** Build the upstream list request from a rastack list query. */
+export declare function restListRequest(binding: RestBinding, query: Record<string, string[]>, headers: Record<string, string>): UpstreamRequest;
+/** Build the upstream detail request. Throws if the binding has no detail path. */
+export declare function restDetailRequest(binding: RestBinding, id: string, headers: Record<string, string>): UpstreamRequest;
+/** Extract the item array from a REST list body (honours `itemsPath`). */
+export declare function restListItems(binding: RestBinding, body: unknown): unknown;

package/dist/external/rest.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Build the upstream HTTP request for a REST-backed resource, and pull the item
+ * array out of the response body. Pure string/URL work — no network — so it is
+ * unit-tested directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restListRequest = restListRequest;
+exports.restDetailRequest = restDetailRequest;
+exports.restListItems = restListItems;
+const util_1 = require("./util");
+/** The rastack→upstream default query-param names, before a binding overrides them. */
+const DEFAULT_QUERY_MAP = {
+    page: "page",
+    page_size: "per_page",
+    search: "q",
+    order_by: "sort",
+};
+/** Build the upstream list request from a rastack list query. */
+function restListRequest(binding, query, headers) {
+    const map = { ...DEFAULT_QUERY_MAP, ...(binding.queryMap ?? {}) };
+    const search = new URLSearchParams();
+    for (const key of ["page", "page_size", "search", "order_by"]) {
+        const value = (0, util_1.firstParam)(query, key);
+        if (value != null && value !== "")
+            search.set(map[key], value);
+    }
+    const qs = search.toString();
+    return {
+        url: `${binding.baseUrl}${binding.listPath}${qs ? `?${qs}` : ""}`,
+        method: "GET",
+        headers,
+    };
+}
+/** Build the upstream detail request. Throws if the binding has no detail path. */
+function restDetailRequest(binding, id, headers) {
+    if (!binding.detailPath) {
+        throw new Error(`REST binding ${binding.app}.${binding.model} has no detailPath.`);
+    }
+    const path = binding.detailPath.replace(/\{id\}/g, encodeURIComponent(id));
+    return { url: `${binding.baseUrl}${path}`, method: "GET", headers };
+}
+/** Extract the item array from a REST list body (honours `itemsPath`). */
+function restListItems(binding, body) {
+    return (0, util_1.getPath)(body, binding.itemsPath);
+}

package/dist/external/route.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parse the rastack REST path both the mini `rastack dev` service and the
+ * deployed Lambda receive into a {@link RastackRequest}. The contract is fixed:
+ *
+ *   /api/{app}/v1/{model}/            → list
+ *   /api/{app}/v1/{model}/{id}/       → detail
+ *
+ * Kept pure and separate from the servers so it is tested without a socket.
+ */
+import type { RastackRequest } from "./handler";
+/** Parse a request URL (path + optional query) into a rastack request, or null. */
+export declare function parseApiPath(url: string): RastackRequest | null;

package/dist/external/route.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Parse the rastack REST path both the mini `rastack dev` service and the
+ * deployed Lambda receive into a {@link RastackRequest}. The contract is fixed:
+ *
+ *   /api/{app}/v1/{model}/            → list
+ *   /api/{app}/v1/{model}/{id}/       → detail
+ *
+ * Kept pure and separate from the servers so it is tested without a socket.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseApiPath = parseApiPath;
+/** Parse a request URL (path + optional query) into a rastack request, or null. */
+function parseApiPath(url) {
+    const [rawPath, rawQuery = ""] = url.split("?");
+    const segments = rawPath.split("/").filter(Boolean); // api, {app}, v1, {model}, [id]
+    if (segments.length < 4 || segments[0] !== "api" || segments[2] !== "v1") {
+        return null;
+    }
+    const app = decodeURIComponent(segments[1]);
+    const model = decodeURIComponent(segments[3]);
+    const id = segments[4] ? decodeURIComponent(segments[4]) : undefined;
+    const query = {};
+    for (const pair of rawQuery.split("&")) {
+        if (!pair)
+            continue;
+        const eq = pair.indexOf("=");
+        const key = decodeURIComponent(eq === -1 ? pair : pair.slice(0, eq));
+        const value = decodeURIComponent(eq === -1 ? "" : pair.slice(eq + 1)).replace(/\+/g, " ");
+        (query[key] ?? (query[key] = [])).push(value);
+    }
+    return { app, model, id, query };
+}

package/dist/external/service.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The mini local proxy service — the "lambda you run while iterating".
+ *
+ * `rastack dev` already serves the app + admin over WASM for the stack's *own*
+ * resources. This adds the other half for **external** resources: a request
+ * handler it mounts under `/api/`, so `useData("github.repo")` works locally,
+ * cached, before any real Lambda is deployed. It is a thin adapter over the pure
+ * {@link handleExternalRequest} core — parse the path, resolve dev auth from env
+ * vars, run the handler, serialise JSON — reused verbatim by the deployed Lambda
+ * (which swaps the env-var auth for Secrets Manager and the Map cache for a
+ * shared store).
+ */
+import { type ProxyCache } from "./cache";
+import { type HandlerDeps } from "./handler";
+import type { FetchLike, ResourceBinding, ResourceResolver } from "./types";
+export interface ExternalService {
+    /** True when the path is an `/api/{app}/v1/{model}/` route this service owns. */
+    handles(url: string): boolean;
+    /**
+     * Handle a request. Returns the HTTP status, JSON body string, and whether it
+     * was a cache hit (for a dev-log line). Returns `null` when the path isn't an
+     * API route, so the caller falls through to its other handlers.
+     */
+    serve(url: string): Promise<{
+        status: number;
+        json: string;
+        cached: boolean;
+    } | null>;
+}
+export interface ServiceOptions {
+    bindings: ResourceBinding[];
+    /** Injected fetch; defaults to the global `fetch` (Node 18+/browsers). */
+    fetch?: FetchLike;
+    cache?: ProxyCache;
+    now?: () => number;
+    /** Per-app upstream auth headers. In dev, typically read from `process.env`. */
+    authHeaders?: HandlerDeps["authHeaders"];
+    /** Named resolvers for `resolver`-transport bindings (e.g. an AWS resolver). */
+    resolvers?: Record<string, ResourceResolver>;
+}
+/**
+ * Read a dev token for an app from the environment, e.g. `GITHUB_TOKEN`,
+ * `EXPO_TOKEN`. Returns a Bearer header when present, else nothing (public
+ * endpoints still work; private ones 401 with a clear upstream message). This is
+ * the *only* place a raw token is read locally — production reads Secrets Manager
+ * in the Lambda instead, and no token is ever sent to the client.
+ */
+export declare function envAuthHeaders(env?: Record<string, string | undefined>): NonNullable<HandlerDeps["authHeaders"]>;
+/** Create the mini external-API service `rastack dev` mounts. */
+export declare function createExternalService(opts: ServiceOptions): ExternalService;

package/dist/external/service.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * The mini local proxy service — the "lambda you run while iterating".
+ *
+ * `rastack dev` already serves the app + admin over WASM for the stack's *own*
+ * resources. This adds the other half for **external** resources: a request
+ * handler it mounts under `/api/`, so `useData("github.repo")` works locally,
+ * cached, before any real Lambda is deployed. It is a thin adapter over the pure
+ * {@link handleExternalRequest} core — parse the path, resolve dev auth from env
+ * vars, run the handler, serialise JSON — reused verbatim by the deployed Lambda
+ * (which swaps the env-var auth for Secrets Manager and the Map cache for a
+ * shared store).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envAuthHeaders = envAuthHeaders;
+exports.createExternalService = createExternalService;
+const cache_1 = require("./cache");
+const handler_1 = require("./handler");
+const route_1 = require("./route");
+/**
+ * Read a dev token for an app from the environment, e.g. `GITHUB_TOKEN`,
+ * `EXPO_TOKEN`. Returns a Bearer header when present, else nothing (public
+ * endpoints still work; private ones 401 with a clear upstream message). This is
+ * the *only* place a raw token is read locally — production reads Secrets Manager
+ * in the Lambda instead, and no token is ever sent to the client.
+ */
+function envAuthHeaders(env = process.env) {
+    return (app) => {
+        const token = env[`${app.toUpperCase()}_TOKEN`];
+        return token ? { Authorization: `Bearer ${token}` } : {};
+    };
+}
+/** Create the mini external-API service `rastack dev` mounts. */
+function createExternalService(opts) {
+    const deps = {
+        fetch: opts.fetch ?? globalThis.fetch,
+        cache: opts.cache ?? (0, cache_1.memoryCache)(),
+        now: opts.now ?? (() => Date.now()),
+        authHeaders: opts.authHeaders ?? envAuthHeaders(),
+        resolvers: opts.resolvers,
+    };
+    if (!deps.fetch) {
+        throw new Error("createExternalService needs a `fetch` (none on globalThis).");
+    }
+    return {
+        handles: (url) => (0, route_1.parseApiPath)(url) !== null,
+        async serve(url) {
+            const req = (0, route_1.parseApiPath)(url);
+            if (!req)
+                return null;
+            const result = await (0, handler_1.handleExternalRequest)(req, opts.bindings, deps);
+            return {
+                status: result.status,
+                json: JSON.stringify(result.body),
+                cached: result.cached,
+            };
+        },
+    };
+}

package/dist/external/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * External-API bindings — how a rastack `app.model` is served from an upstream
+ * REST or GraphQL API.
+ *
+ * The stack's own resources are served by the Rust API / WASM engine over the
+ * `/api/{app}/v1/{model}/` contract. An **external** resource (a GitHub repo, an
+ * Expo project, an AWS stack) is served by the proxy instead: it speaks the same
+ * contract to the client, and translates each request into an upstream call,
+ * normalises the response into rastack's DRF-shaped envelope, and caches it.
+ *
+ * One {@link ResourceBinding} describes that translation for a single model. The
+ * proxy core ({@link ./handler}) is a pure function of a request + the bindings +
+ * an injected `fetch`/cache, so the *same* logic runs in the deployed Lambda and
+ * in the mini service inside `rastack dev`.
+ */
+/** A minimal `fetch` surface — the global `fetch` satisfies it; tests fake it. */
+export interface FetchResponse {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+export type FetchLike = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<FetchResponse>;
+/** Common binding fields, independent of transport. */
+interface BindingBase {
+    /** The rastack app namespace, e.g. `"github"`. */
+    app: string;
+    /** The rastack model, the `{model}` in `/api/{app}/v1/{model}/`. */
+    model: string;
+    /** The upstream field that is the row's identity. Default `"id"`. */
+    primaryKey?: string;
+    /** Cache TTL in ms for this resource's responses. Default 60_000. */
+    ttlMs?: number;
+    /** Whitelist of upstream fields to project into each row (default: all). */
+    fields?: string[];
+    /** Static headers merged into every upstream request (auth is separate). */
+    headers?: Record<string, string>;
+}
+/** Serve a model from an upstream REST endpoint. */
+export interface RestBinding extends BindingBase {
+    transport: "rest";
+    /** Upstream origin, e.g. `"https://api.github.com"`. */
+    baseUrl: string;
+    /** Path to the list, e.g. `"/user/repos"`. */
+    listPath: string;
+    /** Path to a detail; `{id}` is substituted, e.g. `"/repositories/{id}"`. */
+    detailPath?: string;
+    /**
+     * Map rastack list params (`page`, `page_size`, `search`, `order_by`) to the
+     * upstream's own names (`page`, `per_page`, `q`, `sort`). Unmapped params are
+     * dropped, so the upstream never sees rastack-only query keys.
+     */
+    queryMap?: Partial<Record<"page" | "page_size" | "search" | "order_by", string>>;
+    /** Dot path to the array inside the list response (default: the body *is* the array). */
+    itemsPath?: string;
+}
+/** Serve a model from an upstream GraphQL endpoint. */
+export interface GraphQLBinding extends BindingBase {
+    transport: "graphql";
+    /** The GraphQL endpoint URL, e.g. `"https://api.expo.dev/graphql"`. */
+    baseUrl: string;
+    /** The list query. Variables are filled from {@link variableMap}. */
+    listQuery: string;
+    /** Dot path into `data` to the array, e.g. `"me.accounts.0.apps"`. */
+    itemsPath: string;
+    /** Optional detail query; `$id` variable is bound to the requested id. */
+    detailQuery?: string;
+    /** Dot path into `data` to the detail object. */
+    detailPath?: string;
+    /** Map rastack params to GraphQL variable names (e.g. `page_size` → `first`). */
+    variableMap?: Partial<Record<"page" | "page_size" | "search" | "order_by" | "id", string>>;
+    /** Static variables merged into every query. */
+    variables?: Record<string, unknown>;
+}
+/**
+ * Serve a model from an injected resolver function rather than a plain HTTP
+ * call — for upstreams that need an SDK/signing the proxy core shouldn't import
+ * (AWS SigV4, say). The named resolver is provided via `HandlerDeps.resolvers`,
+ * so the framework stays dependency-free while the app plugs in, e.g., an AWS
+ * CloudFormation resolver. Still consumed through the normal `useData` contract.
+ */
+export interface ResolverBinding extends BindingBase {
+    transport: "resolver";
+    /** Key into `HandlerDeps.resolvers` for the function that produces the data. */
+    resolver: string;
+}
+export type ResourceBinding = RestBinding | GraphQLBinding | ResolverBinding;
+/**
+ * A resolver produces the upstream data for a {@link ResolverBinding}: an array
+ * for a list request, or a single object for a detail request. Normalisation
+ * into the rastack envelope is done by the core, exactly as for HTTP transports.
+ */
+export type ResourceResolver = (args: {
+    app: string;
+    model: string;
+    id?: string;
+    query: Record<string, string[]>;
+}) => Promise<unknown>;
+/** Look a binding up by `app`/`model`. */
+export declare function findBinding(bindings: ResourceBinding[], app: string, model: string): ResourceBinding | undefined;
+export {};