@every-app/sdk 0.3.0-rc.4 → 0.3.0-rc.6

package/dist/testing/index.js

@@ -0,0 +1,156 @@
+/**
+ * @every-app/sdk/testing — an app's tests, without a Gateway: a signed-in
+ * person for a request, and the tools called the way the Gateway calls them.
+ *
+ *   import { callTool, testContext, testEnv, testRequest } from "@every-app/sdk/testing";
+ *
+ *   const worker = everyApp(handler, { tools });
+ *   const response = await worker.fetch(
+ *     await testRequest("https://todo.test/api/todos", { user: { id: "ana" } }),
+ *     testEnv(),
+ *     testContext(),
+ *   );
+ *   const result = await callTool(worker, "list_todos", {}, { user: { id: "ana" } });
+ *
+ * Identities are signed with the well-known dev keypair, which `everyApp()`
+ * trusts only with `EVERYAPP_DEV` set, as {@link testEnv} sets it: never in a
+ * deployed Worker. For tests only; a Worker never imports this module.
+ */
+import { DEV_ISSUER, DEV_PRIVATE_KEY_PEM, DEV_PUBLIC_KEY_PEM, } from "../dev/keypair.js";
+import { APP_ID_ENV, AUDIENCE_ENV, IDENTITY_DEV_KEY_ID, IDENTITY_HEADER, MCP_DESTRUCTIVE_SCOPE, MCP_READ_SCOPE, MCP_WRITE_SCOPE, SYSTEM_HEADER, TOOLS_CALL_PATH, TOOLS_LIST_PATH, mintIdentityJwt, mintSystemJwt, } from "../internal/index.js";
+import { everyApp } from "../server/everyApp.js";
+export { IDENTITY_HEADER };
+/** The person a test signs in by default: the owner of `org_test`. */
+export const TEST_USER = Object.freeze({
+    id: "user_test",
+    email: "test@example.com",
+    orgId: "org_test",
+    orgRole: "owner",
+});
+/** The app id {@link testEnv} uses when none is given. */
+export const TEST_APP_ID = "test-app";
+/**
+ * The Worker env `everyApp()` needs to trust test identities: the app id,
+ * the dev issuer and key, `EVERYAPP_DEV`, and a `GATEWAY_URL`. `overrides`
+ * adds the app's own bindings (a fake `DB`, a secret) or replaces any of
+ * these.
+ */
+export function testEnv(overrides = {}) {
+    const { appId = TEST_APP_ID, ...rest } = overrides;
+    return {
+        EVERYAPP_APP_ID: appId,
+        EVERYAPP_DEV: "1",
+        EVERYAPP_IDENTITY_ISSUER: DEV_ISSUER,
+        EVERYAPP_IDENTITY_PUBLIC_KEYS: JSON.stringify([DEV_PUBLIC_KEY_PEM]),
+        GATEWAY_URL: "https://gateway.test",
+        ...rest,
+    };
+}
+/**
+ * An `ExecutionContext` for calling a Worker's `fetch` in a test:
+ * `waitUntil` keeps each promise in `waited`, so a test can await them.
+ */
+export function testContext() {
+    const waited = [];
+    return {
+        waited,
+        waitUntil: (promise) => void waited.push(promise),
+        passThroughOnException: () => { },
+        props: {},
+    };
+}
+/** An identity token for `user`, as the Gateway sends in the identity header. */
+export async function mintTestIdentity(options = {}) {
+    const user = { ...TEST_USER, ...options.user };
+    return mintIdentityJwt(DEV_PRIVATE_KEY_PEM, {
+        subject: {
+            sub: user.id,
+            email: user.email,
+            orgId: user.orgId,
+            orgRole: user.orgRole,
+        },
+        audience: options.appId ?? TEST_APP_ID,
+        issuer: DEV_ISSUER,
+        keyId: IDENTITY_DEV_KEY_ID,
+        channel: options.channel,
+        scopes: options.scopes,
+        toolCall: options.toolCall,
+    });
+}
+/**
+ * A request as the Gateway forwards it: `user` signed in (the default
+ * person when left out), or nobody with `user: null`, as on a public route.
+ */
+export async function testRequest(input, init = {}) {
+    const { user, appId, scopes, channel, ...requestInit } = init;
+    const headers = new Headers(requestInit.headers);
+    if (user !== null) {
+        headers.set(IDENTITY_HEADER, await mintTestIdentity({ user, appId, scopes, channel }));
+    }
+    return new Request(input, { ...requestInit, headers });
+}
+/**
+ * Call one tool as the Gateway does for an AI client: a `chan: "mcp"`
+ * identity minted for this call, through the app's tools endpoint, so the
+ * SDK checks the scope, validates input and output and maps errors as it
+ * does deployed. `app` is the Worker `everyApp()` returned, or the
+ * `defineTools()` set alone. The answer is `{ result }`, or `{ error }`
+ * when the SDK refused the call.
+ */
+export async function callTool(app, name, args = {}, options = {}) {
+    const env = options.env ?? testEnv();
+    const callId = crypto.randomUUID();
+    const identity = await mintTestIdentity({
+        user: options.user,
+        appId: audienceOf(env),
+        channel: "mcp",
+        scopes: options.scopes ?? [
+            MCP_READ_SCOPE,
+            MCP_WRITE_SCOPE,
+            MCP_DESTRUCTIVE_SCOPE,
+        ],
+        toolCall: { id: callId, name },
+    });
+    const response = await workerOf(app).fetch(new Request(`https://app.test${TOOLS_CALL_PATH}`, {
+        method: "POST",
+        headers: { [IDENTITY_HEADER]: identity },
+        body: JSON.stringify({ v: 1, name, arguments: args, callId }),
+    }), env, options.ctx ?? testContext());
+    return (await response.json());
+}
+/** The tool catalog, read as the Gateway reads it when the app deploys. */
+export async function listTools(app, options = {}) {
+    const env = options.env ?? testEnv();
+    const token = await mintSystemJwt(DEV_PRIVATE_KEY_PEM, {
+        audience: audienceOf(env),
+        issuer: DEV_ISSUER,
+        purpose: "tools.list",
+        keyId: IDENTITY_DEV_KEY_ID,
+    });
+    const response = await workerOf(app).fetch(new Request(`https://app.test${TOOLS_LIST_PATH}`, {
+        method: "POST",
+        headers: { [SYSTEM_HEADER]: token },
+        body: JSON.stringify({ v: 1 }),
+    }), env, options.ctx ?? testContext());
+    if (!response.ok) {
+        throw new Error(`the tools list answered ${response.status}: ${await response.text()}`);
+    }
+    return (await response.json());
+}
+/** Who the app's identities are minted for: the deployed audience, else the app id. */
+function audienceOf(env) {
+    const values = env;
+    for (const key of [AUDIENCE_ENV, APP_ID_ENV]) {
+        const value = values[key];
+        if (typeof value === "string" && value)
+            return value;
+    }
+    return TEST_APP_ID;
+}
+function workerOf(app) {
+    if ("fetch" in app)
+        return app;
+    return everyApp(() => new Response("Not found", { status: 404 }), {
+        tools: app,
+    });
+}

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@every-app/sdk",
-  "version": "0.3.0-rc.4",
+  "version": "0.3.0-rc.6",
   "license": "MIT",
   "type": "module",
   "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "default": "./dist/server/index.js"
@@ -24,27 +28,29 @@
       "types": "./dist/dev/index.d.ts",
       "default": "./dist/dev/index.js"
     },
+    "./tanstack-start": {
+      "types": "./dist/tanstack-start/index.d.ts",
+      "default": "./dist/tanstack-start/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "tsc -p tsconfig.build.json",
-    "types:check": "tsc --noEmit",
-    "format:check": "prettier --check .",
-    "format:write": "prettier . --write",
-    "test": "vitest run --silent",
-    "test:watch": "vitest",
-    "check:esm-relative-imports": "node ./scripts/check-esm-relative-imports.mjs"
-  },
   "dependencies": {
     "jose": "^6.2.5"
   },
+  "peerDependencies": {
+    "@tanstack/react-start": "^1.168.61"
+  },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20251014.0",
+    "@tanstack/react-start": "1.168.61",
     "@types/node": "^22.18.13",
     "prettier": "^3.6.2",
     "typescript": "^5.9.3",
@@ -52,5 +58,21 @@
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.2.6",
     "zod": "^4.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-start": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "tsc -p tsconfig.build.json",
+    "types:check": "tsc --noEmit",
+    "format:check": "prettier --check .",
+    "format:write": "prettier . --write",
+    "test": "vitest run --silent",
+    "test:watch": "vitest",
+    "check:esm-relative-imports": "node ./scripts/check-esm-relative-imports.mjs",
+    "catalog:update": "UPDATE_CATALOG=1 vitest run src/cloudflare/catalogSettings.test.ts --silent"
   }
-}
+}