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

package/dist/server/integrationFetch.js

@@ -1,29 +1,7 @@
-import { ACCOUNT_HEADER, CATALOG, ConfigurationError, GATEWAY_ERROR_HEADER, INTEGRATION_PROXY_PREFIX, OAUTH_TOKEN_BODY_LIMIT, allowedScopes, apiKeyHosts, authorizationFor, capabilitySettings, carriesToken, declaredScopeSets, describeTokenEndpoints, devProviderFile, grantedScopes, heldTokenCallAllowed, injectClientCredentials, integrationProxyPath, oauthClientCredentials, oauthClientOrigin, oauthReadMethods, oauthWriteMethods, providerSettingPrefix, requestedScopes, requestedTokenScopes, resolveDevProvider, rewriteTokenRequestScope, scopeExcess, tokenEndpointFor, tokenGrantType, EMAIL_SENDERS_ENV, chooseEmailProvider, parseEmailList, parseEmailSender, } from "../internal/index.js";
+import { ACCOUNT_HEADER, CATALOG, ConfigurationError, GATEWAY_ERROR_HEADER, INTEGRATION_PROXY_PREFIX, OAUTH_TOKEN_BODY_LIMIT, allowedScopes, apiKeyHosts, authorizationFor, capabilitySettings, carriesToken, declaredScopeSets, describeTokenEndpoints, devProviderFile, grantedScopes, heldTokenCallAllowed, injectClientCredentials, integrationProxyPath, oauthClientCredentials, oauthReadMethods, oauthWriteMethods, providerSettingPrefix, requestedScopes, requestedTokenScopes, resolveDevProvider, rewriteTokenRequestScope, scopeExcess, tokenEndpointFor, tokenGrantType, EMAIL_SENDERS_ENV, chooseEmailProvider, parseEmailList, parseEmailSender, } from "../internal/index.js";
 import { applyAttribution, attributionFor, } from "./attribution.js";
 import { BINDING_ORIGIN, streamingRequest, } from "./gatewayFetch.js";
-/**
- * A `fetch` for one of the gateway's capabilities. Call the provider's real
- * URLs (`https://api.dataforseo.com/v3/…`); this sends them over the
- * AppGateway binding, which checks the app's manifest lists the capability,
- * injects the key the gateway holds and forwards the call. The app never
- * sees the key. A refusal the gateway makes itself comes back as a response
- * {@link gatewayRefusal} recognizes; anything else is the provider's answer.
- *
- * For an OAuth client (`linkedin`, `mastodon`, ...) it reaches the
- * provider's token endpoints only, and the gateway puts its client on the
- * request: send the code (or refresh token) without `client_id` or
- * `client_secret`. Build the authorize URL with {@link authorizeUrl} from
- * {@link integrationStatus}, and call the provider's API with the user's
- * token directly.
- *
- * In local dev only, with no binding, the developer's own key or client
- * from `.dev.vars` reaches the provider directly, under the gateway's names:
- * a catalog provider's from the catalog, a provider registered on the
- * gateway from its spec in `.everyapp/providers/<id>.json` (`everyapp
- * provider show <id> --save` writes it), put on the call as the gateway's
- * spec says.
- */
-export function integrationFetch({ env, provider, for: explicitTarget, account, }) {
+export function integrationFetch({ env, provider, for: explicitTarget, account, optional = false, }) {
     const catalogEntry = fetchableCapability(provider);
     const what = `integrationFetch("${provider}")`;
     // Checked now, so a call nobody's fails where the fetch is made; and
@@ -49,6 +27,8 @@ export function integrationFetch({ env, provider, for: explicitTarget, account,
     // endpoint call without the client throws when it is made.
     const decidesLater = integration?.mode === "oauth_client" && integration.flow !== undefined;
     if (!binding && !local && !devToken && integration && !decidesLater) {
+        if (optional)
+            return null;
         const names = [
             ...capabilitySettings(integration),
             ...(integration.mode === "oauth_client" && integration.flow
@@ -81,7 +61,7 @@ export function integrationFetch({ env, provider, for: explicitTarget, account,
             const toApi = integration.flow !== undefined &&
                 upstream.protocol === "https:" &&
                 integration.api.includes(upstream.host) &&
-                !tokenEndpointFor(integration, upstream, binding && integration.hostSetting ? undefined : values);
+                !tokenEndpointFor(integration, upstream);
             if (toApi) {
                 if (binding) {
                     if (account)
@@ -240,12 +220,7 @@ function localCredentials(integration, values) {
  * with the developer's client put on it by the gateway's own rule.
  */
 async function oauthClientCall({ provider, capability, outbound, upstream, headers, values, binding, target, client, }) {
-    // With the binding the gateway resolves the provider's origin (Mastodon's
-    // instance) and refuses any other, so any origin stands in for it here.
-    const settings = binding && capability.hostSetting
-        ? { [capability.hostSetting]: upstream.origin }
-        : values;
-    const endpoint = tokenEndpointFor(capability, upstream, settings);
+    const endpoint = tokenEndpointFor(capability, upstream);
     const method = outbound.method.toUpperCase();
     if (!endpoint || !endpoint.methods.includes(method)) {
         throw new TypeError(`integrationFetch("${provider}") only reaches ${capability.label}'s token endpoints (${describeTokenEndpoints(capability)}), not ${method} ${upstream.origin}${upstream.pathname}. Call its API with the user's token directly.`);
@@ -477,6 +452,9 @@ function devRegisteredProvider(provider, values) {
     const resolved = resolveDevProvider(values, provider);
     if (!resolved.found)
         throw new ConfigurationError(resolved.problem);
+    if (resolved.capability.mode === "ai") {
+        throw new ConfigurationError(`${provider} is an AI provider: list it under providers and call it with createGatewayFetch(), not integrationFetch().`);
+    }
     return resolved.capability;
 }
 /**
@@ -506,6 +484,44 @@ function stringValue(value) {
  * carries its public `clientId` for the authorize URL.
  */
 export async function integrationStatus({ env, provider, for: explicitTarget, }) {
+    const status = await readIntegrationStatus({
+        env,
+        provider,
+        ...(explicitTarget === undefined ? {} : { for: explicitTarget }),
+    });
+    return withSetup(status, String(provider), env);
+}
+/**
+ * `status` with its setup fields: the Gateway's as it sent them, or in
+ * local development (no binding) the `.dev.vars` names a status that
+ * isn't configured lacks.
+ */
+function withSetup(status, provider, values) {
+    const binding = values["EVERY_APP_GATEWAY"];
+    if (binding || !status.requested || status.configured) {
+        return {
+            ...status,
+            settings: Array.isArray(status.settings) ? status.settings : [],
+            setup: typeof status.setup === "string" ? status.setup : null,
+            command: typeof status.command === "string" ? status.command : null,
+        };
+    }
+    const integration = CATALOG.get(provider) ?? devRegisteredProvider(provider, values);
+    const settings = provider === "email"
+        ? ["EMAIL_FROM"]
+        : integration
+            ? [...capabilitySettings(integration)]
+            : [];
+    return {
+        ...status,
+        settings,
+        setup: settings.length
+            ? `${integration?.label ?? provider} isn't set up for local development: set ${settings.join(" and ")} in .dev.vars.`
+            : `${integration?.label ?? provider} isn't set up for local development.`,
+        command: null,
+    };
+}
+async function readIntegrationStatus({ env, provider, for: explicitTarget, }) {
     const target = attributionFor(env, explicitTarget, `integrationStatus("${String(provider)}")`);
     const values = env;
     const binding = values["EVERY_APP_GATEWAY"];
@@ -585,7 +601,6 @@ function devOAuthClientStatus(id, capability, values) {
     const client = values["EVERYAPP_DEV"]
         ? oauthClientCredentials(capability, values)
         : null;
-    const origin = oauthClientOrigin(capability, values);
     const policy = capability.scopePolicy;
     // An entry with a Gateway-owned flow is listed for reading or writing;
     // the app-driven flow alone needs the write grant.
@@ -630,7 +645,6 @@ function devOAuthClientStatus(id, capability, values) {
         configured: Boolean(client),
         ready: Boolean(client) || Boolean(devToken),
         ...(client ? { clientId: client.clientId } : {}),
-        ...(client && origin ? { origin } : {}),
         ...((client || devToken) && grant && asked
             ? {
                 scopeSets: grant.sets,
@@ -672,35 +686,3 @@ function devEmailStatus(values) {
         provider: configured && choice.ok ? choice.provider : null,
     };
 }
-/**
- * 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;
-    constructor({ status, code, message }) {
-        super(message);
-        this.name = "GatewayRefusalError";
-        this.status = status;
-        this.code = code;
-    }
-}
-/**
- * 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);
-    const message = body &&
-        typeof body === "object" &&
-        typeof body.message === "string"
-        ? body.message
-        : `The EveryApp gateway refused the call (${code}).`;
-    return { status: response.status, code, message };
-}

package/dist/server/listMembers.js

@@ -2,7 +2,7 @@ import { ConfigurationError, serviceRoutePath, } from "../internal/index.js";
 import { applyAttribution, attributionFor, isRequest, } from "./attribution.js";
 import { getEveryAppUser } from "./everyApp.js";
 import { BINDING_ORIGIN } from "./gatewayFetch.js";
-import { GatewayRefusalError, gatewayRefusal } from "./integrationFetch.js";
+import { GatewayRefusalError, gatewayRefusal } from "./refusal.js";
 /**
  * The organization's members who can open the app now, through the
  * gateway's `members` capability: people deactivated, removed from the

package/dist/server/refusal.d.ts

@@ -0,0 +1,55 @@
+/** What would make it work, as the Gateway words it. */
+export interface SetupInfo {
+    /** The Gateway settings it needs (`["DATAFORSEO_API_KEY"]`); `[]` when ready or not a setting. */
+    settings: readonly string[];
+    /** One sentence for a person, naming what to set and how; null when ready. */
+    setup: string | null;
+    /** The command an admin runs (`pnpm everyapp configure crm`), or null. */
+    command: string | null;
+}
+/** A refusal the AppGateway binding made itself, not the provider. */
+export interface GatewayRefusal extends SetupInfo {
+    status: number;
+    /** e.g. `capability_not_requested`, `integration_not_configured`. */
+    code: string;
+    message: string;
+}
+/** The refusal codes that mean no model is set up for the call. */
+export declare const AI_NOT_CONFIGURED_CODES: readonly string[];
+/**
+ * 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 declare class GatewayRefusalError extends Error implements GatewayRefusal {
+    readonly status: number;
+    readonly code: string;
+    readonly settings: readonly string[];
+    readonly setup: string | null;
+    readonly command: string | null;
+    constructor({ status, code, message, settings, setup, command, }: Pick<GatewayRefusal, "status" | "code" | "message"> & Partial<SetupInfo>);
+}
+/**
+ * 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 declare function gatewayRefusal(response: Response): Promise<GatewayRefusal | null>;
+/**
+ * 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 declare function refusalFromError(error: unknown): GatewayRefusal | 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 declare function isAiNotConfigured(error: unknown): boolean;
+//# sourceMappingURL=refusal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.d.ts","sourceRoot":"","sources":["../../src/server/refusal.ts"],"names":[],"mappings":"AAgBA,wDAAwD;AACxD,MAAM,WAAW,SAAS;IACxB,kGAAkG;IAClG,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,8EAA8E;IAC9E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,sEAAsE;AACtE,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mEAAmE;AACnE,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAGpD,CAAC;AAEF;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAM,YAAW,cAAc;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEpB,EACV,MAAM,EACN,IAAI,EACJ,OAAO,EACP,QAAa,EACb,KAAY,EACZ,OAAc,GACf,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC;CAS5E;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAKhC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAWtE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGzD"}

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.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, attributionFor, } from "./attribution.js";
 import { BINDING_ORIGIN } from "./gatewayFetch.js";
-import { GatewayRefusalError, gatewayRefusal } from "./integrationFetch.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

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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"}