rastack 0.0.58 → 0.0.59

package/dist/external/types.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findBinding = findBinding;
+/** Look a binding up by `app`/`model`. */
+function findBinding(bindings, app, model) {
+    return bindings.find((b) => b.app === app && b.model === model);
+}

package/dist/external/util.d.ts

@@ -0,0 +1,16 @@
+/** Small pure helpers shared by the proxy core. */
+/**
+ * Read a value at a dot path (`"me.accounts.0.apps"`) out of a JSON value.
+ * Numeric segments index arrays. Returns `undefined` for any missing hop, so
+ * callers can default gracefully rather than throw on a shape they didn't get.
+ */
+export declare function getPath(value: unknown, path: string | undefined): unknown;
+/** Keep only `fields` on a row (plus always its `id`). No-op when unset. */
+export declare function projectFields(row: Record<string, unknown>, fields: string[] | undefined): Record<string, unknown>;
+/**
+ * Ensure a row carries an `id` (the rastack detail-URL key). If the upstream's
+ * identity lives under a different `primaryKey`, mirror it onto `id`.
+ */
+export declare function ensureId(row: Record<string, unknown>, primaryKey: string): Record<string, unknown>;
+/** First value for a key in a parsed query (`{ page: ["2"] }` → `"2"`). */
+export declare function firstParam(query: Record<string, string[]>, key: string): string | undefined;

package/dist/external/util.js

@@ -0,0 +1,58 @@
+"use strict";
+/** Small pure helpers shared by the proxy core. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPath = getPath;
+exports.projectFields = projectFields;
+exports.ensureId = ensureId;
+exports.firstParam = firstParam;
+/**
+ * Read a value at a dot path (`"me.accounts.0.apps"`) out of a JSON value.
+ * Numeric segments index arrays. Returns `undefined` for any missing hop, so
+ * callers can default gracefully rather than throw on a shape they didn't get.
+ */
+function getPath(value, path) {
+    if (!path)
+        return value;
+    let cur = value;
+    for (const segment of path.split(".")) {
+        if (cur == null)
+            return undefined;
+        if (Array.isArray(cur)) {
+            const idx = Number(segment);
+            cur = Number.isInteger(idx) ? cur[idx] : undefined;
+        }
+        else if (typeof cur === "object") {
+            cur = cur[segment];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return cur;
+}
+/** Keep only `fields` on a row (plus always its `id`). No-op when unset. */
+function projectFields(row, fields) {
+    if (!fields || !fields.length)
+        return row;
+    const out = {};
+    if ("id" in row)
+        out.id = row.id;
+    for (const f of fields)
+        if (f in row)
+            out[f] = row[f];
+    return out;
+}
+/**
+ * Ensure a row carries an `id` (the rastack detail-URL key). If the upstream's
+ * identity lives under a different `primaryKey`, mirror it onto `id`.
+ */
+function ensureId(row, primaryKey) {
+    if (primaryKey !== "id" && row.id === undefined && row[primaryKey] !== undefined) {
+        return { ...row, id: row[primaryKey] };
+    }
+    return row;
+}
+/** First value for a key in a parsed query (`{ page: ["2"] }` → `"2"`). */
+function firstParam(query, key) {
+    return query[key]?.[0];
+}

package/dist/rastack-dev.js

@@ -311,6 +311,16 @@ async function runMetroMode(args, cwd) {
         return proxyToMetro(req, res, metroPort);
     });
     server.on("upgrade", (req, socket, head) => proxyUpgrade(req, socket, head, metroPort));
+    server.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            console.error(`\n  ✗ Port ${args.port} is already in use — is \`rastack dev\` already running?\n` +
+                `    Stop it, or pick another port: rastack dev --port <n>\n`);
+        }
+        else {
+            console.error(`\n  ✗ dev server error: ${err.message}`);
+        }
+        stop(1);
+    });
     server.listen(args.port, () => {
         const url = `http://localhost:${args.port}`;
         console.log(`  ✓ Metro live on :${metroPort} — fast refresh on`);

package/dist/rastack-wasm-build.d.ts

@@ -5,7 +5,7 @@
  *
  * Pipeline:
  *   1. cargo build -p rastack-wasm --release --target wasm32-unknown-unknown
- *   2. wasm-bindgen --target web  → tools/wasm/rastack_wasm.js + rastack_wasm_bg.wasm
+ *   2. wasm-bindgen --target web  → wasm/rastack_wasm.js + rastack_wasm_bg.wasm
  *   3. wasm-opt -Oz (if available) to shrink the binary
  *
  * This is invoked by the release CI (to bundle a prebuilt engine into the npm

package/dist/rastack-wasm-build.js

@@ -6,7 +6,7 @@
  *
  * Pipeline:
  *   1. cargo build -p rastack-wasm --release --target wasm32-unknown-unknown
- *   2. wasm-bindgen --target web  → tools/wasm/rastack_wasm.js + rastack_wasm_bg.wasm
+ *   2. wasm-bindgen --target web  → wasm/rastack_wasm.js + rastack_wasm_bg.wasm
  *   3. wasm-opt -Oz (if available) to shrink the binary
  *
  * This is invoked by the release CI (to bundle a prebuilt engine into the npm
@@ -23,9 +23,9 @@ exports.buildWasm = buildWasm;
 const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const repoRoot = path_1.default.resolve(__dirname, "..", "..");
-const rustDir = path_1.default.join(repoRoot, "rust");
-const outDir = path_1.default.join(repoRoot, "tools", "wasm");
+const repoRoot = path_1.default.resolve(__dirname, "..");
+const rustDir = path_1.default.join(repoRoot, "engine");
+const outDir = path_1.default.join(repoRoot, "wasm");
 const wasmPath = path_1.default.join(rustDir, "target", "wasm32-unknown-unknown", "release", "rastack_wasm.wasm");
 function run(cmd, args, cwd = repoRoot) {
     // Local build tool: `cmd`/`args` are the fixed toolchain invocations below
@@ -65,7 +65,7 @@ function buildWasm() {
         "--target",
         "wasm32-unknown-unknown",
     ], rustDir);
-    console.log("→ wasm-bindgen → tools/wasm/");
+    console.log("→ wasm-bindgen → wasm/");
     run("wasm-bindgen", [
         "--target",
         "web",
@@ -87,7 +87,7 @@ function buildWasm() {
         console.log("· wasm-opt not found — skipping size optimisation (optional)");
     }
     const size = fs_1.default.statSync(path_1.default.join(outDir, "rastack_wasm_bg.wasm")).size;
-    console.log(`✓ wasm engine built: tools/wasm/ (${(size / 1024).toFixed(0)} KB)`);
+    console.log(`✓ wasm engine built: wasm/ (${(size / 1024).toFixed(0)} KB)`);
 }
 if (require.main === module) {
     buildWasm();

package/external.ts

@@ -0,0 +1,10 @@
+/**
+ * `rastack/external` — the external-API proxy core.
+ *
+ * Serve external REST/GraphQL APIs (GitHub, Expo, AWS) over the rastack
+ * `/api/{app}/v1/{model}/` contract so the normal typed hooks consume them
+ * unchanged. The same core runs in two adapters: the mini service inside
+ * `rastack dev` ({@link createExternalService}) and an AWS Lambda behind API
+ * Gateway ({@link handleLambdaEvent}).
+ */
+export * from "./src/external";

package/hooks/query/delete.ts

@@ -1,6 +1,9 @@
 import { AxiosResponse } from "axios";
-import { UseMutationResult } from "react-query/types/react/types";
-import { useMutation, useQueryClient } from "react-query";
+import {
+  useMutation,
+  useQueryClient,
+  type UseMutationResult,
+} from "@tanstack/react-query";
 import { IDeleteQueryResult } from "./interfaces";
 import { API } from "./api";
 
@@ -15,8 +18,8 @@ export function useDeleteQuery<TResult>({
 }: DeleteQueryProps): IDeleteQueryResult<TResult> {
   const queryClient = useQueryClient();
 
-  return useMutation(
-    async (params: { id?: string }) => {
+  return useMutation({
+    mutationFn: async (params: { id?: string }) => {
       if (params.id === undefined) {
         throw new Error("ID is required for delete operation");
       }
@@ -36,12 +39,10 @@ export function useDeleteQuery<TResult>({
       // assume `.results` exists on an empty body.
       return response.data?.results ?? response.data ?? null;
     },
-    {
-      onSuccess: () => {
-        if (listQueryCacheKey) {
-          queryClient.invalidateQueries(listQueryCacheKey);
-        }
-      },
+    onSuccess: () => {
+      if (listQueryCacheKey) {
+        queryClient.invalidateQueries({ queryKey: [listQueryCacheKey] });
+      }
     },
-  ) as UseMutationResult<TResult>;
+  }) as UseMutationResult<TResult>;
 }

package/hooks/query/fetch.ts

@@ -1,5 +1,5 @@
 import { AxiosResponse } from "axios";
-import { useQuery } from "react-query";
+import { useQuery } from "@tanstack/react-query";
 import { API } from "./api";
 import { stringifyQueryParams } from "./url";
 import { GetQueryOptions, IGetQueryResult } from "./interfaces";
@@ -31,9 +31,9 @@ export function useGetQuery<TParam, TResult>({
 
   const params = options?.params;
 
-  return useQuery(
-    [queryKey, getUrl, params],
-    async () => {
+  return useQuery({
+    queryKey: [queryKey, getUrl, params],
+    queryFn: async () => {
       const urlParams = stringifyQueryParams(pathParameters, params);
       const serverURL = `${getUrl}${urlParams ? `?${urlParams}` : ""}`;
 
@@ -41,8 +41,6 @@ export function useGetQuery<TParam, TResult>({
 
       return response.data;
     },
-    {
-      enabled: isAuthenticated && isRequiredParamsPresent,
-    },
-  );
+    enabled: isAuthenticated && isRequiredParamsPresent,
+  });
 }

package/hooks/query/interfaces.ts

@@ -1,7 +1,4 @@
-import {
-  UseMutationResult,
-  UseQueryResult,
-} from "react-query/types/react/types";
+import { UseMutationResult, UseQueryResult } from "@tanstack/react-query";
 import { ExtractKey } from "../../types";
 
 export interface IPaginationActions {

package/hooks/query/list.ts

@@ -1,5 +1,5 @@
 import { AxiosResponse } from "axios";
-import { useQuery } from "react-query";
+import { useQuery } from "@tanstack/react-query";
 import { useEffect, useState } from "react";
 import {
   IFilterActions,
@@ -125,14 +125,21 @@ export function useGetPaginatedQueryList<TParam, TResult>({
     }
   };
 
-  const query = useQuery<IPaginatedResponse<TResult>>(
-    [queryKey, getUrl, options?.params, serverQueryParamState],
-    fetchData,
-    {
-      enabled: isRequiredQueryParamsPresent && isAuthenticated,
-      onSuccess: options?.onSuccess,
-    },
-  );
+  const query = useQuery<IPaginatedResponse<TResult>>({
+    queryKey: [queryKey, getUrl, options?.params, serverQueryParamState],
+    queryFn: fetchData,
+    enabled: isRequiredQueryParamsPresent && isAuthenticated,
+  });
+
+  // react-query v5 dropped the query-level `onSuccess` callback; mirror it with
+  // an effect so callers that pass `options.onSuccess` keep firing on each new
+  // successful result.
+  useEffect(() => {
+    if (query.isSuccess && query.data) {
+      options?.onSuccess?.(query.data);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [query.isSuccess, query.data]);
 
   // The list envelope is either nested (`{ pagination: { count, last } }`, the
   // Django/DRF-paginated shape) or flat DRF-classic (`{ count, next, previous,

package/hooks/query/update.ts

@@ -1,5 +1,5 @@
 import { AxiosResponse } from "axios";
-import { useMutation, useQueryClient } from "react-query";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { IUpdateQueryResult, WriteQueryVariables } from "./interfaces";
 import { API } from "./api";
 import { stringifyQueryParams } from "./url";
@@ -29,8 +29,9 @@ export function useUpdateQuery<TParams, TPayload, TResult>({
     unknown,
     WriteQueryVariables<TParams, TPayload>,
     unknown
-  >(({ params, payload }) => {
-    return new Promise((resolve, reject) => {
+  >({
+    mutationFn: ({ params, payload }) => {
+      return new Promise((resolve, reject) => {
       let urlType: "put" | "patch" | "post" = "patch";
       let url: string | undefined;
 
@@ -73,16 +74,17 @@ export function useUpdateQuery<TParams, TPayload, TResult>({
       getAPIFunction(urlType, url, payload)
         .then((response: AxiosResponse<TResult>) => {
           if (itemQueryCacheKey) {
-            queryClient.invalidateQueries([itemQueryCacheKey]);
+            queryClient.invalidateQueries({ queryKey: [itemQueryCacheKey] });
           }
           if (listQueryCacheKey) {
-            queryClient.invalidateQueries(listQueryCacheKey);
+            queryClient.invalidateQueries({ queryKey: [listQueryCacheKey] });
           }
           resolve(response.data);
         })
         .catch((error) => {
           reject(error);
         });
-    });
+      });
+    },
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rastack",
-  "version": "0.0.58",
+  "version": "0.0.59",
   "description": "",
   "main": "runtime.ts",
   "types": "runtime.ts",
@@ -11,6 +11,28 @@
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "admin",
+    "auth",
+    "cache",
+    "components",
+    "hooks",
+    "provider",
+    "sync",
+    "theme",
+    "src",
+    "scripts",
+    "dist",
+    "define.ts",
+    "db.ts",
+    "validate.ts",
+    "plugin.ts",
+    "external.ts",
+    "tokens.ts",
+    "types.ts",
+    "runtime.ts",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "format": "prettier --write \"**/*.{ts,tsx,md}\"",
     "build": "tsc && cp src/.prettierrc dist/.prettierrc && node scripts/copy-templates.js && node scripts/build-admin.js && node scripts/copy-wasm.js",
@@ -39,7 +61,6 @@
     "luxon": "^3.7.2",
     "minimatch": "^10.2.5",
     "prettier": "^3.9.5",
-    "react-query": "^3.39.3",
     "typescript": "~5.9.3",
     "usehooks-ts": "^3.1.1"
   },
@@ -47,6 +68,7 @@
     "react": "^19.2.7"
   },
   "devDependencies": {
+    "@testing-library/react-hooks": "8.0.1",
     "@types/jest": "^30.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/mocha": "^10.0.6",

package/scripts/copy-templates.js

@@ -13,7 +13,7 @@
 const fs = require("fs");
 const path = require("path");
 
-const repoRoot = path.resolve(__dirname, "..", "..");
+const repoRoot = path.resolve(__dirname, "..");
 const srcDir = path.join(repoRoot, "deploy", "cloudformation");
 const destDir = path.join(__dirname, "..", "dist", "templates", "cloudformation");
 

package/scripts/copy-wasm.js

@@ -17,7 +17,7 @@ const entry = path.join(src, "rastack_wasm.js");
 
 if (!fs.existsSync(entry)) {
   console.log(
-    "copy-wasm: no prebuilt engine at tools/wasm (skipping — build it with " +
+    "copy-wasm: no prebuilt engine at wasm/ (skipping — build it with " +
       "rastack-wasm-build.js to ship it).",
   );
   process.exit(0);

package/scripts/dev-install.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * dev-install — fast local build + install of the rastack CLI.
+ *
+ * Compiles `src/ → dist/` with the local TypeScript, then merge-copies the fresh
+ * dist over the globally installed copy (`~/.rastack/node_modules/rastack/dist`)
+ * so `rastack` and `ras` on the PATH immediately run the new code. The copy
+ * merges (it never deletes), which preserves the shipped runtime artifacts that
+ * already live there — the wasm engine, the admin bundle, and the templates —
+ * none of which a tsc-only build emits.
+ *
+ * This is the fast local iteration loop; a full `npm run build && npm pack`
+ * publish is unchanged. Usage:
+ *
+ *   node scripts/dev-install.mjs [--prefix <dir>]   # defaults to ~/.rastack
+ */
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const TOOLS = path.resolve(HERE, "..");
+
+function flag(name, fallback) {
+  const i = process.argv.indexOf(name);
+  return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+
+// The install prefix rastack ships into (the hosted installer uses ~/.rastack).
+const prefix = flag("--prefix", path.join(os.homedir(), ".rastack"));
+const target = path.join(prefix, "node_modules", "rastack");
+
+if (!fs.existsSync(target)) {
+  console.error(
+    `  ✗ no rastack install found at ${target}\n` +
+      "    Install it first (hosted installer / npm install -g rastack), or pass --prefix <dir>.",
+  );
+  process.exit(1);
+}
+
+// 1) Compile TypeScript → dist/. Run tsc through node (avoids the Windows .cmd
+//    spawn EINVAL) so this loop is identical on every platform.
+console.log("▸ tsc — compiling src → dist");
+const tscJs = path.join(TOOLS, "node_modules", "typescript", "bin", "tsc");
+execFileSync(process.execPath, [tscJs, "-p", path.join(TOOLS, "tsconfig.json")], {
+  stdio: "inherit",
+  cwd: TOOLS,
+});
+
+// 2) Merge-copy the fresh dist over the global install (never delete → the wasm
+//    engine, admin bundle and templates already there are left untouched).
+console.log(`▸ installing → ${target}`);
+fs.cpSync(path.join(TOOLS, "dist"), path.join(target, "dist"), { recursive: true });
+fs.copyFileSync(path.join(TOOLS, "package.json"), path.join(target, "package.json"));
+
+const version = JSON.parse(
+  fs.readFileSync(path.join(target, "package.json"), "utf-8"),
+).version;
+console.log(
+  `  ✓ installed rastack ${version} — \`rastack\` and \`ras\` now run this local build`,
+);

package/src/deploy/ci.ts

@@ -83,7 +83,7 @@ function stackOutput(
 
 /** The Lambda staging directory `cargo lambda build` writes the binary into. */
 function stageDir(cfg: DeployConfig): string {
-  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. */
@@ -118,7 +118,7 @@ export function buildSteps(
     {
       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/src/deploy/io.ts

@@ -39,8 +39,8 @@ export function resolveDeployAsset(
   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/src/dev/harness.ts

@@ -155,7 +155,7 @@ export 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.
@@ -167,7 +167,6 @@ export function wasmBundleCandidates(
   return [
     path.join(dirnameDir, "wasm"),
     path.join(dirnameDir, "..", "wasm"),
-    path.join(cwd, "tools", "wasm"),
     path.join(cwd, "wasm"),
   ];
 }

package/src/external/cache.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 function memoryCache(): ProxyCache {
+  const store = new Map<string, CacheEntry>();
+  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). */
+export function cacheKey(
+  app: string,
+  model: string,
+  id: string | undefined,
+  query: Record<string, string[]>,
+): string {
+  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). */
+export function isFresh(entry: CacheEntry, ttlMs: number, now: number): boolean {
+  return now - entry.storedAt < ttlMs;
+}

package/src/external/envelope.ts

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ */
+
+import { ensureId, projectFields } from "./util";
+
+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 function toListEnvelope(
+  items: unknown,
+  opts: NormalizeOptions,
+): ListEnvelope {
+  const rows = (Array.isArray(items) ? items : [])
+    .filter((r): r is Record<string, unknown> => !!r && typeof r === "object")
+    .map((r) => projectFields(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. */
+export function toDetail(
+  item: unknown,
+  primaryKey: string,
+  fields?: string[],
+): Record<string, unknown> | null {
+  if (!item || typeof item !== "object") return null;
+  return projectFields(ensureId(item as Record<string, unknown>, primaryKey), fields);
+}