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

package/dist/server/toolsEndpoint.js

@@ -0,0 +1,237 @@
+/**
+ * The app side of the internal tools contract (../internal/tools.ts).
+ *
+ * `everyApp()` answers the two reserved paths here, before any app code runs
+ * and whether or not the app defines tools:
+ *
+ *  - `/__everyapp/tools/list` needs the gateway's system token for this app
+ *    (purpose "tools.list"). It describes tools; it never runs them.
+ *  - `/__everyapp/tools/call` needs an identity token minted for this exact
+ *    call: `chan: "mcp"` plus a `tc` claim naming the tool and call id. The
+ *    token's scopes must include the scope the tool's risk requires; `*` does
+ *    not count, because the ToolBus only ever mints explicit scopes.
+ *
+ * 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, 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, {
+        status,
+        headers: { "cache-control": "no-store", ...headers },
+    });
+}
+function toolsError(status, code, message, extra = {}) {
+    return toolsJson(status, {
+        v: TOOLS_PROTOCOL_VERSION,
+        error: {
+            code,
+            message,
+            ...(extra.issues ? { issues: extra.issues } : {}),
+        },
+    }, extra.headers);
+}
+async function readJsonBody(request) {
+    try {
+        return await request.json();
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+let emptyCatalog;
+/**
+ * The app's catalog, or the contract's "misconfigured" answer when it can't
+ * be built at all, so the deploy shows the developer what to fix. (A single
+ * tool that can't be described is left out of the catalog with a warning.)
+ */
+async function catalogOrError(toolSet) {
+    try {
+        return await catalogFor(toolSet);
+    }
+    catch (error) {
+        console.error(error);
+        return toolsError(500, "misconfigured", error instanceof Error ? error.message : String(error));
+    }
+}
+function catalogFor(toolSet) {
+    if (toolSet)
+        return toolSetInternals(toolSet).catalog();
+    // An app without tools still answers the contract, with an empty catalog,
+    // so the gateway can tell "no tools" from "no contract".
+    emptyCatalog ??= catalogHash({ tools: [] }).then((hash) => ({
+        tools: [],
+        hash,
+        warnings: [],
+    }));
+    return emptyCatalog;
+}
+/**
+ * Answer a request to the reserved tools paths, or return null for any other
+ * path so the app's own handler runs.
+ */
+export async function handleToolsRequest(request, env, ctx, options) {
+    const { pathname } = new URL(request.url);
+    if (pathname !== TOOLS_LIST_PATH && pathname !== TOOLS_CALL_PATH) {
+        return null;
+    }
+    if (request.method !== "POST") {
+        return toolsError(405, "method_not_allowed", "Use POST.", {
+            headers: { allow: "POST" },
+        });
+    }
+    let verify;
+    try {
+        verify = resolveVerifyOptions(options.identity);
+    }
+    catch (error) {
+        if (error instanceof ConfigurationError) {
+            console.error(error);
+            return toolsError(500, "misconfigured", error.message);
+        }
+        throw error;
+    }
+    return pathname === TOOLS_LIST_PATH
+        ? listTools(request, verify, options)
+        : callTool(request, env, ctx, verify, options);
+}
+async function listTools(request, verify, options) {
+    try {
+        await verifySystemJwt(request.headers.get(SYSTEM_HEADER) ?? "", {
+            ...verify,
+            purpose: "tools.list",
+        });
+    }
+    catch (error) {
+        if (error instanceof IdentityError) {
+            return toolsError(401, "unauthenticated", error.message);
+        }
+        throw error;
+    }
+    const body = await readJsonBody(request);
+    if (!isPlainObject(body) || body.v !== TOOLS_PROTOCOL_VERSION) {
+        return toolsError(400, "invalid_request", `Expected {"v":${TOOLS_PROTOCOL_VERSION}}.`);
+    }
+    const catalog = await catalogOrError(options.toolSet);
+    if (catalog instanceof Response)
+        return catalog;
+    const response = {
+        v: TOOLS_PROTOCOL_VERSION,
+        sdk: SDK_VERSION,
+        hash: catalog.hash,
+        ...(catalog.instructions !== undefined
+            ? { instructions: catalog.instructions }
+            : {}),
+        tools: catalog.tools,
+        ...(catalog.warnings.length > 0 ? { warnings: catalog.warnings } : {}),
+    };
+    return toolsJson(200, response);
+}
+function parseCallRequest(body) {
+    if (!isPlainObject(body) || body.v !== TOOLS_PROTOCOL_VERSION)
+        return null;
+    const { name, callId } = body;
+    const args = body.arguments ?? {};
+    if (typeof name !== "string" || !name)
+        return null;
+    if (typeof callId !== "string" || !callId)
+        return null;
+    if (!isPlainObject(args))
+        return null;
+    return { v: TOOLS_PROTOCOL_VERSION, name, arguments: args, callId };
+}
+async function callTool(request, env, ctx, verify, options) {
+    let user, expiresAt;
+    try {
+        ({ 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) {
+            return toolsError(401, "unauthenticated", error.message);
+        }
+        throw error;
+    }
+    if (user.channel !== "mcp" || !user.toolCall) {
+        return toolsError(403, "forbidden", "Tool calls need an identity the gateway minted for this call.");
+    }
+    const call = parseCallRequest(await readJsonBody(request));
+    if (!call) {
+        return toolsError(400, "invalid_request", `Expected {"v":${TOOLS_PROTOCOL_VERSION},"name","arguments","callId"}.`);
+    }
+    if (call.name !== user.toolCall.name || call.callId !== user.toolCall.id) {
+        return toolsError(403, "forbidden", "The identity was minted for a different tool call.");
+    }
+    const tool = options.toolSet
+        ? toolSetInternals(options.toolSet).tool(call.name)
+        : undefined;
+    if (!tool) {
+        return toolsError(404, "unknown_tool", `Unknown tool: ${call.name}`);
+    }
+    const scope = requiredScopeForRisk(tool.risk);
+    if (!user.scopes.includes(scope)) {
+        return toolsError(403, "forbidden", `Calling ${call.name} needs the ${scope} scope.`);
+    }
+    const input = await validateWithSchema(tool.input, call.arguments);
+    if (!input.ok) {
+        return toolsError(400, "invalid_arguments", `Invalid arguments for ${call.name}: ${input.issues
+            .map((issue) => issue.path?.length
+            ? `${issue.path.join(".")}: ${issue.message}`
+            : issue.message)
+            .join("; ")}`, { issues: input.issues });
+    }
+    // The hash only lets the gateway notice a newer catalog: a catalog that
+    // can't be built is logged here, and doesn't stop this tool from running.
+    const hash = await catalogFor(options.toolSet).then((catalog) => catalog.hash, (error) => {
+        console.error(error);
+        return "";
+    });
+    let result;
+    try {
+        // 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) {
+        if (error instanceof ToolError) {
+            result = {
+                content: [{ type: "text", text: error.message }],
+                isError: true,
+            };
+        }
+        else {
+            console.error(`[everyapp] tool "${call.name}" failed (ref ${call.callId}):`, error);
+            result = {
+                content: [
+                    {
+                        type: "text",
+                        text: `Internal error in ${options.appId} (ref ${call.callId})`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    return toolsJson(200, {
+        v: TOOLS_PROTOCOL_VERSION,
+        catalogHash: hash,
+        result,
+    });
+}

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

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@every-app/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0-rc.10",
   "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"
@@ -11,34 +15,64 @@
     "./internal": {
       "types": "./dist/internal/index.d.ts",
       "default": "./dist/internal/index.js"
-    }
+    },
+    "./cloudflare": {
+      "types": "./dist/cloudflare/index.d.ts",
+      "default": "./dist/cloudflare/index.js"
+    },
+    "./cloudflare/sentinel": {
+      "types": "./dist/cloudflare/sentinel.d.ts",
+      "default": "./dist/cloudflare/sentinel.js"
+    },
+    "./dev": {
+      "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"
   ],
+  "dependencies": {
+    "jose": "^6.2.5"
+  },
   "peerDependencies": {
-    "jose": "^6.0.0"
+    "@tanstack/react-start": "^1.168.61"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20251014.0",
+    "@tanstack/react-start": "1.168.61",
     "@types/node": "^22.18.13",
-    "jose": "^6.0.12",
     "prettier": "^3.6.2",
     "typescript": "^5.9.3",
-    "vite": "^7.1.2",
+    "vite": "^7.3.7",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.2.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",
-    "build:prepublish": "pnpm install --ignore-scripts && npm run types:check && npm run build",
     "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"
+    "check:esm-relative-imports": "node ./scripts/check-esm-relative-imports.mjs",
+    "catalog:update": "UPDATE_CATALOG=1 vitest run src/cloudflare/catalogSettings.test.ts --silent"
   }
 }