@every-app/sdk 0.3.0-rc.1 → 0.3.0-rc.10

package/dist/server/refusal.js

@@ -0,0 +1,193 @@
+/**
+ * The Gateway's own refusals, read the same way wherever they surface: a
+ * `Response` from a gateway fetch ({@link gatewayRefusal}), the error an
+ * SDK helper throws ({@link GatewayRefusalError}), or the error an AI
+ * client throws for a refused call (an OpenAI SDK's `APIError`, ai-sdk's
+ * `APICallError`) ({@link refusalFromError}).
+ *
+ * A refusal that means "not set up" (`integration_not_configured`,
+ * `ai_provider_not_configured`, `ai_default_not_configured`) carries what
+ * to do in the Gateway's words: `settings` (the setting names it needs),
+ * `setup` (one sentence for a person) and `command` (what an admin runs,
+ * `pnpm everyapp configure <app>`, or null). Show them as they are; never
+ * match the message text or hardcode a setting name or a command.
+ */
+import { ConfigurationError, GATEWAY_ERROR_HEADER } from "../internal/index.js";
+/** The refusal codes that mean no model is set up for the call. */
+export const AI_NOT_CONFIGURED_CODES = [
+    "ai_provider_not_configured",
+    "ai_default_not_configured",
+];
+/**
+ * A refusal the AppGateway binding made, thrown: what `sendEmail()` throws
+ * when the gateway won't send (`email_sender_not_allowed`,
+ * `email_budget_exhausted`, ...). The thrown twin of {@link gatewayRefusal}.
+ */
+export class GatewayRefusalError extends Error {
+    status;
+    code;
+    settings;
+    setup;
+    command;
+    constructor({ status, code, message, settings = [], setup = null, command = null, }) {
+        super(message);
+        this.name = "GatewayRefusalError";
+        this.status = status;
+        this.code = code;
+        this.settings = settings;
+        this.setup = setup;
+        this.command = command;
+    }
+}
+/**
+ * The gateway's own refusal in `response`, or null when the response is the
+ * provider's answer (which may be an error of its own). Reads the body only
+ * for a refusal, so call it before reading the body yourself.
+ */
+export async function gatewayRefusal(response) {
+    const code = response.headers.get(GATEWAY_ERROR_HEADER);
+    if (!code)
+        return null;
+    const body = await response.json().catch(() => null);
+    return refusalOf(response.status, code, body);
+}
+/**
+ * The Gateway's refusal behind a thrown error, or null when it isn't one:
+ * a {@link GatewayRefusalError} (`sendEmail()`, `listMembers()`, `emit()`),
+ * an OpenAI SDK `APIError` or an ai-sdk `APICallError` for a call the
+ * Gateway refused (also inside ai-sdk's `RetryError` or an error's
+ * `cause`), or the SDK's local-development `ConfigurationError` for a
+ * missing key, which answers as the deployed refusal would
+ * (`ai_provider_not_configured`, status 503, the `.dev.vars` names).
+ */
+export function refusalFromError(error) {
+    const seen = new Set();
+    let current = error;
+    while (current && typeof current === "object" && !seen.has(current)) {
+        seen.add(current);
+        const found = refusalHere(current);
+        if (found)
+            return found;
+        const record = current;
+        current = record["lastError"] ?? record["cause"];
+    }
+    return null;
+}
+/**
+ * Whether `error` (or a refusal already read) means no model is set up:
+ * `ai_provider_not_configured` or `ai_default_not_configured`, from the
+ * Gateway or, in local development, from the SDK with no key in
+ * `.dev.vars`. Show `refusalFromError(error).setup` to the person.
+ */
+export function isAiNotConfigured(error) {
+    const refusal = isRefusal(error) ? error : refusalFromError(error);
+    return refusal !== null && AI_NOT_CONFIGURED_CODES.includes(refusal.code);
+}
+function isRefusal(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        !(value instanceof Error) &&
+        typeof value.code === "string" &&
+        typeof value.status === "number");
+}
+function refusalHere(error) {
+    // A Response is read with gatewayRefusal(), which can read its body.
+    if (error instanceof Response)
+        return null;
+    if (error instanceof GatewayRefusalError) {
+        return {
+            status: error.status,
+            code: error.code,
+            message: error.message,
+            settings: error.settings,
+            setup: error.setup,
+            command: error.command,
+        };
+    }
+    if (error instanceof ConfigurationError) {
+        if (!error.code)
+            return null;
+        return {
+            status: 503,
+            code: error.code,
+            message: error.message,
+            settings: error.settings,
+            setup: error.message,
+            command: null,
+        };
+    }
+    const record = error;
+    // ai-sdk's APICallError: lowercase header names, the body as text.
+    const responseHeaders = record["responseHeaders"];
+    if (responseHeaders && typeof responseHeaders === "object") {
+        const code = headerOf(responseHeaders, GATEWAY_ERROR_HEADER);
+        if (!code)
+            return null;
+        return refusalOf(numberOf(record["statusCode"]), code, parseJson(record["responseBody"]), messageOf(error));
+    }
+    // An OpenAI SDK APIError: `headers` (Headers or a record), `status`,
+    // and `error`, the body's `error` object (which carries the same fields).
+    const headers = record["headers"];
+    if (headers && typeof headers === "object" && "status" in record) {
+        const code = headerOf(headers, GATEWAY_ERROR_HEADER);
+        if (!code)
+            return null;
+        return refusalOf(numberOf(record["status"]), code, record["error"], messageOf(error));
+    }
+    return null;
+}
+/** A refusal from its status, code and body (the Gateway's `{ code, message, … }`, or OpenAI's `{ error: {…} }`). */
+function refusalOf(status, code, body, fallback) {
+    const top = recordOf(body);
+    const inner = recordOf(top?.["error"]);
+    const field = (name) => top?.[name] ?? inner?.[name];
+    const message = stringOf(top?.["message"]) ??
+        stringOf(inner?.["message"]) ??
+        fallback ??
+        `The EveryApp gateway refused the call (${code}).`;
+    const settings = field("settings");
+    return {
+        status,
+        code,
+        message,
+        settings: Array.isArray(settings)
+            ? settings.filter((name) => typeof name === "string")
+            : [],
+        setup: stringOf(field("setup")) ?? null,
+        command: stringOf(field("command")) ?? null,
+    };
+}
+function headerOf(headers, name) {
+    if (typeof headers.get === "function") {
+        return headers.get(name);
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === name && typeof value === "string")
+            return value;
+    }
+    return null;
+}
+function recordOf(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringOf(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
+function numberOf(value) {
+    return typeof value === "number" ? value : 0;
+}
+function parseJson(value) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+function messageOf(error) {
+    return error instanceof Error && error.message ? error.message : undefined;
+}

package/dist/server/sendEmail.d.ts

@@ -35,5 +35,5 @@ export interface SendEmailOptions {
  * `.dev.vars` it goes out for real through Email Sending's REST API, from
  * the developer's own account.
  */
-export declare function sendEmail({ env, for: target, message, }: SendEmailOptions): Promise<SendEmailResult>;
+export declare function sendEmail({ env, for: explicitTarget, message, }: SendEmailOptions): Promise<SendEmailResult>;
 //# sourceMappingURL=sendEmail.d.ts.map

package/dist/server/sendEmail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sendEmail.d.ts","sourceRoot":"","sources":["../../src/server/sendEmail.ts"],"names":[],"mappings":"AAAA,OAAO,EAeL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAI1B,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,SAAS,CAAC,EAC9B,GAAG,EACH,GAAG,EAAE,MAAM,EACX,OAAO,GACR,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAoB7C"}
+{"version":3,"file":"sendEmail.d.ts","sourceRoot":"","sources":["../../src/server/sendEmail.ts"],"names":[],"mappings":"AAAA,OAAO,EAeL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAQ1B,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,SAAS,CAAC,EAC9B,GAAG,EACH,GAAG,EAAE,cAAc,EACnB,OAAO,GACR,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkB7C"}

package/dist/server/sendEmail.js

@@ -1,7 +1,7 @@
 import { ConfigurationError, EMAIL_SENDERS_ENV, emailDomain, emailProviderRefusal, emailRestBody, emailRestUrl, emailSenderRefusal, parseEmailList, parseEmailSender, parseSendEmailMessage, readEmailRestResponse, senderAllowed, serviceRoutePath, } from "../internal/index.js";
-import { applyAttribution, checkAttribution, } from "./attribution.js";
-import { BINDING_ORIGIN } from "./gatewayFetch.js";
-import { GatewayRefusalError, gatewayRefusal } from "./integrationFetch.js";
+import { applyAttribution, attributionFor, } from "./attribution.js";
+import { BINDING_ORIGIN, gatewayBinding, } from "./gatewayFetch.js";
+import { GatewayRefusalError, gatewayRefusal } from "./refusal.js";
 /**
  * Send an email through the gateway's `email` capability: its sender
  * (EMAIL_FROM) unless `message.from` names an address the installation's
@@ -19,10 +19,10 @@ import { GatewayRefusalError, gatewayRefusal } from "./integrationFetch.js";
  * `.dev.vars` it goes out for real through Email Sending's REST API, from
  * the developer's own account.
  */
-export async function sendEmail({ env, for: target, message, }) {
-    checkAttribution(env, target, "sendEmail");
+export async function sendEmail({ env, for: explicitTarget, message, }) {
+    const target = attributionFor(env, explicitTarget, "sendEmail");
     const values = env;
-    const binding = values["EVERY_APP_GATEWAY"];
+    const binding = gatewayBinding(env);
     if (binding) {
         if (typeof binding.fetch !== "function") {
             throw new ConfigurationError("EVERY_APP_GATEWAY is configured but is not a valid service binding.");
@@ -49,7 +49,7 @@ async function sendThroughGateway(binding, target, message) {
         throw new GatewayRefusalError({
             status: response.status,
             code: "email_send_failed",
-            message: `The Every App gateway answered ${response.status} to the send.`,
+            message: `The EveryApp gateway answered ${response.status} to the send.`,
         });
     }
     return (await response.json());

package/dist/server/toolsEndpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolsEndpoint.d.ts","sourceRoot":"","sources":["../../src/server/toolsEndpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAcL,KAAK,sBAAsB,EAO5B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAOL,KAAK,OAAO,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,EAAE,sBAAsB,CAAC;CAClC;AAoFD;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,oBAAoB,EACzB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAyB1B"}
+{"version":3,"file":"toolsEndpoint.d.ts","sourceRoot":"","sources":["../../src/server/toolsEndpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAcL,KAAK,sBAAsB,EAO5B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAOL,KAAK,OAAO,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,EAAE,sBAAsB,CAAC;CAClC;AAoFD;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,oBAAoB,EACzB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAyB1B"}

package/dist/server/toolsEndpoint.js

@@ -14,7 +14,8 @@
  * The perimeter also refuses these paths from outside and strips inbound
  * `x-everyapp-*` headers, so only the gateway's ToolBus ever reaches them.
  */
-import { ConfigurationError, IDENTITY_HEADER, IdentityError, SYSTEM_HEADER, TOOLS_CALL_PATH, TOOLS_LIST_PATH, TOOLS_PROTOCOL_VERSION, catalogHash, requiredScopeForRisk, resolveVerifyOptions, verifyIdentityJwt, verifySystemJwt, } from "../internal/index.js";
+import { ConfigurationError, IDENTITY_HEADER, IdentityError, SYSTEM_HEADER, TOOLS_CALL_PATH, TOOLS_LIST_PATH, TOOLS_PROTOCOL_VERSION, assertOrganizationPin, catalogHash, requiredScopeForRisk, resolveVerifyOptions, verifyIdentity, verifySystemJwt, } from "../internal/index.js";
+import { serveRequest } from "./context.js";
 import { SDK_VERSION, ToolError, toToolResult, toolSetInternals, validateWithSchema, } from "./tools.js";
 function toolsJson(status, body, headers = {}) {
     return Response.json(body, {
@@ -148,9 +149,12 @@ function parseCallRequest(body) {
     return { v: TOOLS_PROTOCOL_VERSION, name, arguments: args, callId };
 }
 async function callTool(request, env, ctx, verify, options) {
-    let user;
+    let user, expiresAt;
     try {
-        user = await verifyIdentityJwt(request.headers.get(IDENTITY_HEADER) ?? "", verify);
+        ({ user, expiresAt } = await verifyIdentity(request.headers.get(IDENTITY_HEADER) ?? "", verify));
+        // The same pin as the handler path: a call for another organization's
+        // install never runs a tool here.
+        assertOrganizationPin(user, options.identity.organizationId);
     }
     catch (error) {
         if (error instanceof IdentityError) {
@@ -194,13 +198,15 @@ async function callTool(request, env, ctx, verify, options) {
     });
     let result;
     try {
-        const value = await tool.handler(input.value, {
+        // The call runs in the request context like a page would: currentUser()
+        // is the caller, and its Gateway calls are attributed to them.
+        const value = await serveRequest({ request, user, expiresAt }, () => tool.handler(input.value, {
             user,
             env: env,
             ctx,
             request,
             callId: call.callId,
-        });
+        }));
         result = await toToolResult(tool, value);
     }
     catch (error) {

package/dist/tanstack-start/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Puts the person the Gateway signed in on `context.user` (an
+ * `EveryAppUser`), verified from the identity the Gateway sent; throws the
+ * 401 Response when there is none (a public route, anonymous).
+ */
+export declare const ensureUserMiddleware: import("@tanstack/react-start").FunctionMiddlewareAfterServer<{}, unknown, undefined, {
+    user: import("../internal/protocol.js").EveryAppUser;
+}, undefined, undefined, undefined>;
+//# sourceMappingURL=index.d.ts.map

package/dist/tanstack-start/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tanstack-start/index.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;mCAK/B,CAAC"}

package/dist/tanstack-start/index.js

@@ -0,0 +1,29 @@
+/**
+ * @every-app/sdk/tanstack-start — identity for a TanStack Start app's server
+ * functions:
+ *
+ *   import { ensureUserMiddleware } from "@every-app/sdk/tanstack-start";
+ *
+ *   export const getTodos = createServerFn()
+ *     .middleware([ensureUserMiddleware])
+ *     .handler(({ context: { user } }) => listTodos(user.id));
+ *
+ * The SDK lists `@tanstack/react-start` as a peer dependency, so the Start
+ * plugin compiles this module like the app's own: the `.server()` part never
+ * reaches the browser.
+ */
+import { createMiddleware } from "@tanstack/react-start";
+import { getRequest } from "@tanstack/react-start/server";
+import { env } from "cloudflare:workers";
+import { requireEveryAppUser } from "../server/everyApp.js";
+/**
+ * Puts the person the Gateway signed in on `context.user` (an
+ * `EveryAppUser`), verified from the identity the Gateway sent; throws the
+ * 401 Response when there is none (a public route, anonymous).
+ */
+export const ensureUserMiddleware = createMiddleware({
+    type: "function",
+}).server(async ({ next }) => {
+    const user = await requireEveryAppUser(getRequest(), env);
+    return next({ context: { user } });
+});

package/dist/testing/index.d.ts

@@ -0,0 +1,93 @@
+import { IDENTITY_HEADER, type IdentityChannel, type ToolCallResultV1, type ToolsCallResponseV1, type ToolsListResponseV1 } from "../internal/index.js";
+import type { ToolSet } from "../server/tools.js";
+export { IDENTITY_HEADER };
+export type { ToolCallResultV1 as ToolCallResult, ToolsCallResponseV1 as ToolCallResponse, ToolsListResponseV1 as ToolsListResponse, };
+/** The person a test signs in; each field left out takes {@link TEST_USER}'s. */
+export interface TestUser {
+    id?: string;
+    email?: string;
+    orgId?: string;
+    /** `owner`, `admin` or `member`, as the Gateway signs it. */
+    orgRole?: string;
+}
+/** The person a test signs in by default: the owner of `org_test`. */
+export declare const TEST_USER: Readonly<Required<TestUser>>;
+/** The app id {@link testEnv} uses when none is given. */
+export declare const TEST_APP_ID = "test-app";
+/** What an identity is minted for, beside the person. */
+export interface TestIdentityOptions {
+    user?: TestUser;
+    /** The app the identity is for (the token's audience). Default: {@link TEST_APP_ID}. */
+    appId?: string;
+    /** Default `["*"]`: a browser session, which holds every scope. */
+    scopes?: string[];
+    /** Default `"web"`. */
+    channel?: IdentityChannel;
+}
+/**
+ * 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 declare function testEnv<T extends object = Record<never, never>>(overrides?: {
+    appId?: string;
+} & T): {
+    EVERYAPP_APP_ID: string;
+    EVERYAPP_DEV: string;
+    EVERYAPP_IDENTITY_ISSUER: string;
+    EVERYAPP_IDENTITY_PUBLIC_KEYS: string;
+    GATEWAY_URL: string;
+} & Omit<T, "appId">;
+/**
+ * An `ExecutionContext` for calling a Worker's `fetch` in a test:
+ * `waitUntil` keeps each promise in `waited`, so a test can await them.
+ */
+export declare function testContext(): ExecutionContext & {
+    waited: Promise<unknown>[];
+};
+/** An identity token for `user`, as the Gateway sends in the identity header. */
+export declare function mintTestIdentity(options?: TestIdentityOptions & {
+    toolCall?: {
+        id: string;
+        name: string;
+    };
+}): Promise<string>;
+/**
+ * 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 declare function testRequest(input: string | URL, init?: RequestInit & Omit<TestIdentityOptions, "user"> & {
+    user?: TestUser | null;
+}): Promise<Request>;
+/** A Worker as `everyApp()` returns it. */
+export interface TestWorker {
+    fetch(request: Request, env: never, ctx: ExecutionContext): Response | Promise<Response>;
+}
+export interface CallToolOptions {
+    user?: TestUser;
+    /**
+     * The caller's scopes. Default: `mcp:read`, `mcp:write` and
+     * `mcp:destructive`, so every tool may be called; pass fewer to test a
+     * refusal.
+     */
+    scopes?: string[];
+    /** Default: {@link testEnv}() for the worker's app. */
+    env?: object;
+    ctx?: ExecutionContext;
+}
+/**
+ * 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 declare function callTool(app: TestWorker | ToolSet, name: string, args?: Record<string, unknown>, options?: CallToolOptions): Promise<ToolsCallResponseV1>;
+/** The tool catalog, read as the Gateway reads it when the app deploys. */
+export declare function listTools(app: TestWorker | ToolSet, options?: {
+    env?: object;
+    ctx?: ExecutionContext;
+}): Promise<ToolsListResponseV1>;
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"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"}

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,
+    });
+}