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

package/dist/server/webhooks.js

@@ -0,0 +1,205 @@
+/**
+ * `verifyWebhook()`: check an inbound provider webhook on a route the
+ * manifest declares `public`, the way the provider signs it.
+ *
+ * The Gateway forwards a public route's body and headers untouched and
+ * verifies nothing (landing-page/content/agent/manifest.md, "Why a route is
+ * public"): the app checks the provider's signature itself, with the signing
+ * secret it declares in `secrets`. Every app that takes a webhook would
+ * otherwise write this HMAC code again, and the easy mistakes (a `===`
+ * compare, no timestamp window, verifying a re-serialized body, reading an
+ * unbounded body first) are the ones that matter. Proposed in
+ * docs/design/2026-11-birds-forcing-function.md (limitation 6).
+ *
+ * Supported signing schemes:
+ *  - `slack`: `X-Slack-Signature: v0=<hex>` over `v0:<timestamp>:<body>`,
+ *    with `X-Slack-Request-Timestamp` inside the tolerance;
+ *  - `github`: `X-Hub-Signature-256: sha256=<hex>` over the body. GitHub
+ *    signs no timestamp, so a replay is the receiver's to drop: dedupe on
+ *    `deliveryId` (`X-GitHub-Delivery`);
+ *  - `everyapp`: a Gateway's own event delivery, `X-EveryApp-Signature:
+ *    t=<seconds>,v1=<hex>` over `<t>.<body>` (the same check as the
+ *    Gateway's `verifyEventSignature`), deduped on `X-EveryApp-Event-Id`.
+ *
+ * WebCrypto only. The compare is `crypto.subtle.verify`, constant time.
+ * Several secrets may be given, so a secret rotates without a gap.
+ */
+import { EVENT_HEADERS, EVENT_SIGNATURE_TOLERANCE_SECONDS, eventSigningInput, parseEventSignature, } from "../internal/events.js";
+/** The default body limit: well above Slack's payloads and most of GitHub's (whose cap is 25 MB). */
+export const WEBHOOK_MAX_BYTES_DEFAULT = 5 * 1024 * 1024;
+const HEX_SHA256 = /^[0-9a-f]{64}$/i;
+const MAX_EVENT_SIGNATURES = 4;
+const encoder = new TextEncoder();
+/**
+ * Verify `request` as a `provider` webhook signed with `secret`. Reads the
+ * body (at most `maxBytes`) and returns it on success; never throws for a
+ * bad delivery, so a handler answers `401` on `{ ok: false }`. Throws a
+ * `TypeError` only for a programming error: an unknown `provider`, or a
+ * `toleranceSeconds` or `maxBytes` that is negative, NaN or infinite.
+ *
+ * ```ts
+ * const check = await verifyWebhook(request, { provider: "slack", secret: env.SLACK_SIGNING_SECRET });
+ * if (!check.ok) return new Response(null, { status: 401 });
+ * const params = new URLSearchParams(check.body);
+ * ```
+ */
+export async function verifyWebhook(request, options) {
+    const secrets = (typeof options.secret === "string" ? [options.secret] : options.secret).filter((secret) => typeof secret === "string" && secret.length > 0);
+    if (secrets.length === 0)
+        return refused("no_secret");
+    // A NaN or infinite tolerance or limit would quietly turn the window or the
+    // read bound off (every comparison with NaN is false): refuse the call.
+    const tolerance = checkedOption("toleranceSeconds", options.toleranceSeconds, EVENT_SIGNATURE_TOLERANCE_SECONDS);
+    const maxBytes = checkedOption("maxBytes", options.maxBytes, WEBHOOK_MAX_BYTES_DEFAULT);
+    const signed = readSignature(request.headers, options.provider);
+    if (!signed.ok)
+        return signed;
+    if (signed.timestamp !== null) {
+        const nowSeconds = Math.floor((options.now ?? new Date()).getTime() / 1000);
+        if (Math.abs(nowSeconds - signed.timestamp) > tolerance) {
+            return refused("expired");
+        }
+    }
+    const bytes = await readBody(request, maxBytes);
+    if (bytes === "unreadable")
+        return refused("unreadable");
+    if (bytes === null)
+        return refused("too_large");
+    // The HMAC runs over the bytes received, never a decoded and re-encoded copy.
+    const prefix = encoder.encode(signed.prefix);
+    const data = new Uint8Array(new ArrayBuffer(prefix.byteLength + bytes.byteLength));
+    data.set(prefix, 0);
+    data.set(bytes, prefix.byteLength);
+    for (const secret of secrets) {
+        const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+        for (const candidate of signed.digests) {
+            if (await crypto.subtle.verify("HMAC", key, fromHex(candidate), data)) {
+                return {
+                    ok: true,
+                    body: new TextDecoder().decode(bytes),
+                    deliveryId: signed.deliveryId,
+                    timestamp: signed.timestamp,
+                };
+            }
+        }
+    }
+    return refused("mismatch");
+}
+function readSignature(headers, provider) {
+    switch (provider) {
+        case "slack": {
+            const header = headers.get("x-slack-signature");
+            if (!header)
+                return refused("missing_signature");
+            const rawTimestamp = headers.get("x-slack-request-timestamp");
+            const digest = header.startsWith("v0=") ? header.slice(3) : "";
+            if (!HEX_SHA256.test(digest) ||
+                !rawTimestamp ||
+                !/^\d{1,12}$/.test(rawTimestamp)) {
+                return refused("malformed");
+            }
+            return {
+                ok: true,
+                digests: [digest.toLowerCase()],
+                timestamp: Number(rawTimestamp),
+                deliveryId: null,
+                prefix: `v0:${rawTimestamp}:`,
+            };
+        }
+        case "github": {
+            const header = headers.get("x-hub-signature-256");
+            if (!header)
+                return refused("missing_signature");
+            const digest = header.startsWith("sha256=") ? header.slice(7) : "";
+            if (!HEX_SHA256.test(digest))
+                return refused("malformed");
+            return {
+                ok: true,
+                digests: [digest.toLowerCase()],
+                timestamp: null,
+                deliveryId: headers.get("x-github-delivery"),
+                prefix: "",
+            };
+        }
+        case "everyapp": {
+            const header = headers.get(EVENT_HEADERS.signature);
+            if (!header)
+                return refused("missing_signature");
+            const parsed = parseEventSignature(header);
+            // The Gateway sends one v1 (two while a secret rotates): a header with
+            // many isn't one it sent, and each would cost an HMAC per secret.
+            if (!parsed || parsed.v1.length > MAX_EVENT_SIGNATURES) {
+                return refused("malformed");
+            }
+            return {
+                ok: true,
+                digests: parsed.v1,
+                timestamp: parsed.timestamp,
+                deliveryId: headers.get(EVENT_HEADERS.eventId),
+                prefix: eventSigningInput(parsed.timestamp, ""),
+            };
+        }
+        default: {
+            const unknown = provider;
+            throw new TypeError(`verifyWebhook: unknown provider "${String(unknown)}"`);
+        }
+    }
+}
+/** A finite, non-negative option, or its default when not given. */
+function checkedOption(name, value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new TypeError(`verifyWebhook: ${name} must be a finite number of at least 0`);
+    }
+    return value;
+}
+/**
+ * The body's bytes; null once it passes `maxBytes` (read no further);
+ * "unreadable" when it was already consumed or its stream fails.
+ */
+async function readBody(request, maxBytes) {
+    const declared = Number(request.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > maxBytes)
+        return null;
+    if (request.bodyUsed)
+        return "unreadable";
+    if (!request.body)
+        return new Uint8Array(new ArrayBuffer(0));
+    const chunks = [];
+    let total = 0;
+    try {
+        const reader = request.body.getReader();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                return null;
+            }
+            chunks.push(value);
+        }
+    }
+    catch {
+        return "unreadable";
+    }
+    const bytes = new Uint8Array(new ArrayBuffer(total));
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+function fromHex(hex) {
+    const bytes = new Uint8Array(new ArrayBuffer(hex.length / 2));
+    for (let index = 0; index < bytes.length; index += 1) {
+        bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+    }
+    return bytes;
+}
+function refused(reason) {
+    return { ok: false, reason };
+}

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.3.0-rc.1",
+  "version": "0.3.0-rc.11",
   "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,34 +28,51 @@
       "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": {
-    "jose": "^6.2.5"
+    "@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.2.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.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"
   }
-}
+}

package/dist/server/authorizeUrl.d.ts

@@ -1,43 +0,0 @@
-import { type OAuthClientCapabilityId } from "../internal/index.js";
-import type { OAuthClientIntegrationStatus } from "./integrationFetch.js";
-export interface AuthorizeUrlOptions {
-    /** The OAuth client, as listed in the manifest's `capabilities`. */
-    provider: OAuthClientCapabilityId;
-    /** What `integrationStatus()` answered for it, ready and with its `clientId`. */
-    status: OAuthClientIntegrationStatus;
-    /** One of the redirect URIs the operator registered on the client. */
-    redirectUri: string;
-    /** The app's own anti-forgery value, checked when the person comes back. */
-    state: string;
-    /** PKCE: the S256 challenge of the verifier the app keeps for the exchange. */
-    codeChallenge?: string;
-    /**
-     * The provider's extras (`prompt`, `login_hint`, Google's `hd`). Never
-     * one of the parameters this helper sets (PKCE's and the provider's own
-     * included), nor Google's `include_granted_scopes`.
-     */
-    params?: Record<string, string>;
-}
-/**
- * The provider's authorize URL to send a person to, for a client with
- * scope sets (`google-workspace`, `microsoft-365`, `slack`), built from the
- * capability's status: the registry's authorize endpoint (or the instance
- * the status names), `client_id`, `response_type=code`, `redirect_uri`,
- * `state`, and the scopes the status allows this app, which are exactly
- * what the gateway will let the token carry. Each provider's own needs
- * are added: Google's `access_type=offline` (a refresh token), Microsoft's
- * `response_mode=query`, Slack's comma-joined `scope` and its `user_scope`
- * (the status's `userScopes`, when the app's sets include a user set). With
- * `codeChallenge`, PKCE as S256. The app keeps its `state` and verifier
- * for the callback.
- *
- * A client without scope sets (LinkedIn, Mastodon, ...) is refused: the
- * registry's checklist for one isn't what the gateway holds a token to,
- * so an app builds that URL itself from the status's `clientId`.
- *
- * Throws a `TypeError` naming the fix when the client has no scope sets,
- * when the status isn't ready or has no `clientId`, when the status lacks
- * `scopes`, or when `params` names a parameter the helper sets.
- */
-export declare function authorizeUrl({ provider, status, redirectUri, state, codeChallenge, params, }: AuthorizeUrlOptions): URL;
-//# sourceMappingURL=authorizeUrl.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"authorizeUrl.d.ts","sourceRoot":"","sources":["../../src/server/authorizeUrl.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,QAAQ,EAAE,uBAAuB,CAAC;IAClC,iFAAiF;IACjF,MAAM,EAAE,4BAA4B,CAAC;IACrC,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAgCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,MAAM,EACN,WAAW,EACX,KAAK,EACL,aAAa,EACb,MAAM,GACP,EAAE,mBAAmB,GAAG,GAAG,CA2D3B"}