zitejs 0.10.0-start.6 → 0.10.0-start.7

package/dist/esm/integrations/rules.js

@@ -44,15 +44,43 @@ const FIELDS_BY_TYPE = {
     jira: extras("cloudId", "siteUrl"),
     typeform: extras(),
     apollo: extras(),
+    clay: extras(),
     attio: extras(),
     granola: extras(),
+    clickup: extras(),
     dropbox: extras(),
+    // Every path is https://{subdomain}.zendesk.com/api/v2/..., and a token is
+    // only valid on the account it was issued for, so the subdomain travels with
+    // it rather than being configured per app.
+    zendesk: extras("subdomain"),
+    // Smartsheet's US, EU, AU and Gov regions are separate, and a token is only
+    // valid on its own region's host, so the host travels with it.
+    smartsheet: extras("apiBaseUrl"),
     // The IAM key alone reaches nothing: every call needs the region and the
     // bucket, and S3-compatible providers need the endpoint too.
     amazonS3: extras("keyId", "region", "bucket", "endpoint", "pathPrefix"),
     // The SQL API lives on each account's own host, and the token is pinned to
     // one role; the warehouse is optional and falls back to the user's default.
     snowflake: extras("accountUrl", "role", "warehouse"),
+    // A statement is addressed by workspace host and SQL warehouse, and the token
+    // derives neither.
+    databricks: extras("host", "warehouseId"),
+    // Cloud Confluence is addressed through api.atlassian.com by cloud id, the
+    // same as Jira; the site URL is only for links a human will click.
+    confluence: extras("cloudId", "siteUrl"),
+    // OAuth returns a per-company api_domain alongside the token, so there is no
+    // one host to call.
+    pipedrive: extras("apiBaseUrl"),
+    // Shopify has no global API host: every call goes to the store's own domain
+    // under a pinned API version. The storefront pair is the shopper-facing API,
+    // which installs predating those scopes do not have.
+    shopify: extras("shopDomain", "apiBaseUrl", "storefrontApiUrl", "storefrontAccessToken"),
+    sharepoint: extras(),
+    excel: extras(),
+    x: extras(),
+    zoomMeetings: extras(),
+    // Every request names the workspace in an Account-Id header beside the key.
+    smartsuite: extras("workspaceId"),
 };
 /** Per service type: `accessToken`, then its extra labels sorted (Salesforce `instanceUrl`). */
 export const CREDENTIAL_FIELDS = FIELDS_BY_TYPE;
@@ -65,6 +93,7 @@ export const OPTIONAL_CREDENTIAL_FIELDS = {
     // Only S3-compatible providers set an endpoint, and a prefix is opt-in.
     amazonS3: ["endpoint", "pathPrefix"],
     snowflake: ["warehouse"],
+    shopify: ["storefrontApiUrl", "storefrontAccessToken"],
 };
 /**
  * Types the runtime never serves: those with a generated client (Airtable, email,

package/dist/esm/integrations/rules.test.js

@@ -16,6 +16,7 @@ describe("CREDENTIAL_FIELDS", () => {
         ]);
         expect(CREDENTIAL_FIELDS.jira).toEqual(["accessToken", "cloudId", "siteUrl"]);
         expect(CREDENTIAL_FIELDS.granola).toEqual(["accessToken"]);
+        expect(CREDENTIAL_FIELDS.smartsheet).toEqual(["accessToken", "apiBaseUrl"]);
     });
     it("has no type the runtime never serves", () => {
         for (const type of NON_CREDENTIAL_SERVICE_TYPES) {

package/dist/esm/start/authHooks.d.ts

@@ -0,0 +1,7 @@
+export declare const AUTH_HOOK_NAMES: readonly ["beforeSignUp", "beforeSignIn", "afterSignUp", "afterSignIn", "verifySession"];
+export type AuthHookName = (typeof AUTH_HOOK_NAMES)[number];
+type AuthHook = (input: unknown) => unknown;
+export declare const isAuthHookName: (name: string) => name is AuthHookName;
+/** The hooks the app's `zite.auth.ts` defines, by name. */
+export declare function loadAuthHooks(): Promise<Partial<Record<AuthHookName, AuthHook>>>;
+export {};

package/dist/esm/start/authHooks.js

@@ -0,0 +1,10 @@
+import { authHooksModule } from "./authHooksModule.js";
+export const AUTH_HOOK_NAMES = ["beforeSignUp", "beforeSignIn", "afterSignUp", "afterSignIn", "verifySession"];
+export const isAuthHookName = (name) => AUTH_HOOK_NAMES.includes(name);
+/** The hooks the app's `zite.auth.ts` defines, by name. */
+export async function loadAuthHooks() {
+    if (!authHooksModule)
+        return {};
+    const hooks = (await authHooksModule()).default?.hooks ?? {};
+    return Object.fromEntries(AUTH_HOOK_NAMES.flatMap((name) => (typeof hooks[name] === "function" ? [[name, hooks[name]]] : [])));
+}

package/dist/esm/start/authHooksModule.d.ts

@@ -0,0 +1 @@
+export declare const authHooksModule: (() => Promise<Record<string, unknown>>) | null;

package/dist/esm/start/authHooksModule.js

@@ -0,0 +1,3 @@
+// Replaced at build by zite() with a lazy import of the app's `zite.auth.ts`,
+// when it has one. Null wherever the plugin didn't build the app.
+export const authHooksModule = null;

package/dist/esm/start/clientErrorMessage.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/start/clientErrorMessage.test.js

@@ -0,0 +1,105 @@
+// Classic's cases (restly packages/endpoint-setup/src/endpointErrors.test.ts), for the port in errors.ts.
+import { describe, it, expect } from 'vitest';
+import { toClientErrorMessage } from './errors.js';
+describe('toClientErrorMessage', () => {
+    describe('live mode', () => {
+        it('preserves a signal the app throws for its own frontend to parse', () => {
+            // The regression case: apps throw structured messages as control flow
+            // and parse them client-side. Blanking this breaks the app silently.
+            expect(toClientErrorMessage('CLOTHES_CHANGE_PENDING:recAbc,recDef', 'live')).toBe('CLOTHES_CHANGE_PENDING:recAbc,recDef');
+        });
+        it('preserves user-facing copy the app author wrote', () => {
+            const message = 'Registration is missing child information. Please contact team@example.org';
+            expect(toClientErrorMessage(message, 'live')).toBe(message);
+        });
+        it('preserves incidental errors, which are no worse than a generic string', () => {
+            expect(toClientErrorMessage('window is not defined', 'live')).toBe('window is not defined');
+        });
+        it('replaces private-range IP addresses', () => {
+            expect(toClientErrorMessage('connect ECONNREFUSED 10.205.134.213:2507', 'live')).toBe('A service this app depends on is temporarily unavailable. Please try again.');
+        });
+        it('replaces internal service hostnames', () => {
+            expect(toClientErrorMessage('ConnectTimeoutError (attempted address: zite-shard-restly-server:2500, timeout: 10000ms)', 'live')).toBe('A service this app depends on is temporarily unavailable. Please try again.');
+        });
+        it('replaces internal service hostnames with no port, as DNS failures report them', () => {
+            expect(toClientErrorMessage('getaddrinfo ENOTFOUND workflow-runner', 'live')).toBe('A service this app depends on is temporarily unavailable. Please try again.');
+        });
+        it('replaces a portless hostname carrying a pod suffix', () => {
+            expect(toClientErrorMessage('getaddrinfo EAI_AGAIN workflow-runner-3l4c', 'live')).toBe('A service this app depends on is temporarily unavailable. Please try again.');
+        });
+        it('does not match a service name embedded in a longer token', () => {
+            // "app-runner" sits inside this, but it is the app's own resource name.
+            const message = 'Deployment my-app-runner-config failed';
+            expect(toClientErrorMessage(message, 'live')).toBe(message);
+        });
+        it("replaces Zite's AI billing notice, which is addressed to the app owner", () => {
+            expect(toClientErrorMessage('402 AI is paused: your organization is over its AI credit limit. To resume, increase your credits (upgrade your plan) or connect your own AI provider key (BYOK).', 'live')).toBe('AI features are temporarily unavailable. Please contact the app owner.');
+        });
+        it("replaces an upstream provider's billing state", () => {
+            expect(toClientErrorMessage('429 You have no credits remaining. Add credits to continue using the API at https://platform.openai.com/settings/organization/billing/.', 'live')).toBe('AI features are temporarily unavailable. Please contact the app owner.');
+        });
+        it("does not swallow an app's own copy about credits or quotas", () => {
+            // Narrowness check: the billing patterns key on our prefix and on the
+            // provider's URLs, so an app writing about its users' credit stays intact.
+            const message = 'You have exceeded your credit limit for this month.';
+            expect(toClientErrorMessage(message, 'live')).toBe(message);
+        });
+        it('does not treat a public IP as internal', () => {
+            const message = 'Request to 203.0.113.10:443 failed';
+            expect(toClientErrorMessage(message, 'live')).toBe(message);
+        });
+        it('replaces link-local addresses, which reach cloud metadata services', () => {
+            expect(toClientErrorMessage('connect ETIMEDOUT 169.254.169.254:80', 'live')).toBe('A service this app depends on is temporarily unavailable. Please try again.');
+        });
+        it('replaces IPv6 loopback, unique-local and link-local addresses', () => {
+            const unavailable = 'A service this app depends on is temporarily unavailable. Please try again.';
+            expect(toClientErrorMessage('connect ECONNREFUSED ::1', 'live')).toBe(unavailable);
+            expect(toClientErrorMessage('no route to fd12:3456:789a::1', 'live')).toBe(unavailable);
+            // fe80::/10 — the IPv6 counterpart to 169.254, and it turns up in the
+            // same container-networking failures.
+            expect(toClientErrorMessage('connect ETIMEDOUT fe80::1', 'live')).toBe(unavailable);
+            expect(toClientErrorMessage('no route to feba:1234::abcd', 'live')).toBe(unavailable);
+        });
+        it('replaces a bare localhost reference', () => {
+            expect(toClientErrorMessage('connect ECONNREFUSED localhost:2506', 'live')).toBe('A service this app depends on is temporarily unavailable. Please try again.');
+        });
+    });
+    describe('live mode — credentials', () => {
+        it('redacts a secret but keeps the rest of the message', () => {
+            // The whole point of redacting in place: the sentence around the
+            // credential is the app author's and still has to reach the user.
+            expect(toClientErrorMessage('Could not reach the roster database: postgres://svc:hunter2@db.example.com/prod', 'live')).toBe('Could not reach the roster database: postgres://svc:REDACTED@db.example.com/prod');
+        });
+        it('redacts a provider key inside otherwise user-facing copy', () => {
+            expect(toClientErrorMessage('Payment provider rejected the request (sk_live_abcdefghijklmnop1234)', 'live')).toBe('Payment provider rejected the request (REDACTED)');
+        });
+        it('still replaces the message when infrastructure detail survives redaction', () => {
+            // Both concerns in one message: the secret goes, and the internal
+            // hostname then triggers wholesale replacement.
+            expect(toClientErrorMessage('connect ECONNREFUSED base-runner:2500 using api_key=abc123def456', 'live')).toBe('A service this app depends on is temporarily unavailable. Please try again.');
+        });
+    });
+    describe('userFacingMessage', () => {
+        it('prefers the author-written message over the technical one', () => {
+            expect(toClientErrorMessage('Airtable findAll failed for tblIx0DJvbXjjfA42 after 3 retries', 'live', 'We could not load this week’s roster. Please try again shortly.')).toBe('We could not load this week’s roster. Please try again shortly.');
+        });
+        it('keeps the technical message in preview so the developer can debug', () => {
+            expect(toClientErrorMessage('Airtable findAll failed for tblIx0DJvbXjjfA42 after 3 retries', 'preview', 'We could not load this week’s roster.')).toBe('Airtable findAll failed for tblIx0DJvbXjjfA42 after 3 retries');
+        });
+        it('falls back to the thrown message when the author set none', () => {
+            expect(toClientErrorMessage('CLOTHES_CHANGE_PENDING:recAbc', 'live', undefined)).toBe('CLOTHES_CHANGE_PENDING:recAbc');
+        });
+        it('ignores an empty userFacingMessage rather than blanking the response', () => {
+            expect(toClientErrorMessage('Week #11 is now full', 'live', '')).toBe('Week #11 is now full');
+        });
+    });
+    describe('preview mode', () => {
+        it('passes infrastructure detail through so the developer can debug', () => {
+            const message = 'connect ECONNREFUSED 10.205.134.213:2507';
+            expect(toClientErrorMessage(message, 'preview')).toBe(message);
+        });
+    });
+    it('treats an unspecified mode as live', () => {
+        expect(toClientErrorMessage('connect ECONNREFUSED 10.205.134.213:2507', undefined)).toBe('A service this app depends on is temporarily unavailable. Please try again.');
+    });
+});

package/dist/esm/start/describe.d.ts

@@ -1,4 +1,5 @@
 import type { ZiteTrigger } from "../backend/index.js";
+import { type AuthHookName } from "./authHooks.js";
 import type { LoadedWorkflow } from "./workflowRun.js";
 import type { WorkflowConfig } from "./workflow.js";
 export type Access = {
@@ -19,9 +20,16 @@ export type DescribedFunction = {
 };
 export type DescribedRoute = {
     path: string;
+    file?: string;
     methods: Record<string, Access>;
     problems: string[];
 };
+/** A route that renders: what the editor's page picker and system map show. */
+export type DescribedPage = {
+    id: string;
+    path: string;
+    file?: string;
+};
 export type DescribedWorkflow = {
     id: string;
     file: string;
@@ -39,24 +47,32 @@ export type DescribedWorkflow = {
 export type Description = {
     functions: DescribedFunction[];
     routes: DescribedRoute[];
+    pages: DescribedPage[];
     workflows: DescribedWorkflow[];
+    /** The hooks the app's `zite.auth.ts` defines. */
+    authHooks: AuthHookName[];
 };
 export declare function describeFunction(id: string, request: Request): Promise<DescribedFunction>;
 type RouteLike = {
+    id: string;
     fullPath: string;
     parentRoute?: RouteLike;
     options?: {
+        path?: string;
+        component?: unknown;
         server?: {
             middleware?: unknown[];
             handlers?: unknown;
         };
     };
 };
-export declare function describeRoutes(routesById: Record<string, RouteLike>): DescribedRoute[];
+export declare function describePages(routesById: Record<string, RouteLike>, files?: Record<string, string>): DescribedPage[];
+export declare function describeRoutes(routesById: Record<string, RouteLike>, files?: Record<string, string>): DescribedRoute[];
 export declare function describeWorkflows(workflows: LoadedWorkflow[]): DescribedWorkflow[];
 export declare function describeApp(opts: {
     fnIds: string[];
     descriptions?: Record<string, string>;
+    routeFiles?: Record<string, string>;
     getRouter: () => unknown;
     request: Request;
     workflows?: LoadedWorkflow[];

package/dist/esm/start/describe.js

@@ -5,6 +5,7 @@ import { createSsrRpc } from "@tanstack/react-start/ssr-rpc";
 import { runWithStartContext } from "@tanstack/start-storage-context";
 import { z } from "zod";
 import { ziteMiddlewareKind } from "./index.js";
+import { loadAuthHooks } from "./authHooks.js";
 const accessOf = (chain, problems) => {
     const kinds = chain.map(ziteMiddlewareKind).filter((k) => !!k);
     const roles = kinds.flatMap((k) => (k.kind === "role" ? [k.role] : []));
@@ -86,6 +87,7 @@ export async function describeFunction(id, request) {
     if (!chain.some((m) => ziteMiddlewareKind(m)?.kind === "factory")) {
         problems.push("raw-server-fn: define it with signedInFn or publicFn from zitejs/start");
     }
+    // TanStack keeps the validator under `inputValidator` up to 1.168 and `validator` from 1.169 (Start 1.0).
     const handlerStep = chain.at(-1);
     return {
         id,
@@ -93,11 +95,24 @@ export async function describeFunction(id, request) {
         file: state.meta?.filename,
         method: state.method,
         access: accessOf(chain, problems),
-        input: jsonSchemaOf(handlerStep?.options?.inputValidator),
+        input: jsonSchemaOf(handlerStep?.options?.validator ?? handlerStep?.options?.inputValidator),
         problems,
     };
 }
-export function describeRoutes(routesById) {
+const ROOT_ROUTE_ID = "__root__";
+// Pathless layouts have no path of their own, and a file with only server handlers is an API route.
+export function describePages(routesById, files = {}) {
+    return Object.values(routesById).flatMap((route) => {
+        const options = route.options ?? {};
+        if (route.id === ROOT_ROUTE_ID || options.path === undefined)
+            return [];
+        if (options.server?.handlers && !options.component)
+            return [];
+        const file = files[route.id];
+        return [{ id: route.id, path: route.fullPath, ...(file && { file }) }];
+    });
+}
+export function describeRoutes(routesById, files = {}) {
     const out = [];
     for (const route of Object.values(routesById)) {
         const server = route.options?.server;
@@ -119,7 +134,8 @@ export function describeRoutes(routesById) {
             methods[method] = accessOf(chain, methodProblems);
             problems.push(...methodProblems.map((p) => `${method}: ${p}`));
         }
-        out.push({ path: route.fullPath, methods, problems });
+        const file = files[route.id];
+        out.push({ path: route.fullPath, ...(file && { file }), methods, problems });
     }
     return out;
 }
@@ -170,6 +186,12 @@ export async function describeApp(opts) {
         const description = opts.descriptions?.[id];
         functions.push(description ? { ...described, description } : described);
     }
-    const router = (await opts.getRouter());
-    return { functions, routes: describeRoutes(router.routesById), workflows: describeWorkflows(opts.workflows ?? []) };
+    const { routesById } = (await opts.getRouter());
+    return {
+        functions,
+        routes: describeRoutes(routesById, opts.routeFiles),
+        pages: describePages(routesById, opts.routeFiles),
+        workflows: describeWorkflows(opts.workflows ?? []),
+        authHooks: Object.keys(await loadAuthHooks()),
+    };
 }

package/dist/esm/start/errors.d.ts

@@ -0,0 +1,46 @@
+import type { HostMode } from "./types.js";
+declare const STATUS: {
+    readonly BAD_REQUEST: 400;
+    readonly INVALID_INPUT: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly CONFLICT: 409;
+    readonly RATE_LIMITED: 429;
+    readonly INTERNAL_ERROR: 500;
+};
+export type ZiteErrorCode = keyof typeof STATUS;
+/** @internal The HTTP status each code answers with. */
+export declare const ZITE_ERROR_STATUS: Readonly<Record<ZiteErrorCode, number>>;
+export declare const isZiteErrorCode: (code: unknown) => code is ZiteErrorCode;
+export type ZiteErrorOptions = {
+    code: ZiteErrorCode;
+    message: string;
+    userFacingMessage?: string;
+};
+/**
+ * Fail with a status: `throw new ZiteError('FORBIDDEN', 'Only the owner can edit this')`. On the live app,
+ * `userFacingMessage` is what users read in place of `message`, which stays for logs and the editor.
+ */
+export declare class ZiteError extends Error {
+    readonly code: ZiteErrorCode;
+    readonly userFacingMessage?: string;
+    constructor(code: ZiteErrorCode, message?: string);
+    constructor(options: ZiteErrorOptions);
+    /** Classic's order, which code written for `zitejs/backend` uses. */
+    constructor(message: string, code?: ZiteErrorCode);
+}
+/**
+ * A ZiteError from any copy of zitejs as this one's. Integration SDKs and code written for classic throw
+ * `zitejs/backend`'s class, which `instanceof` doesn't recognise.
+ */
+export declare const asZiteError: (error: unknown) => ZiteError | undefined;
+/**
+ * What a failure may say to the app's users, as on classic. The message is the app author's, so it passes, with
+ * credentials redacted in place; one naming our infrastructure or billing is replaced whole. Preview is the editor,
+ * which reads it unchanged.
+ */
+export declare function toClientErrorMessage(errorMessage: string, mode: HostMode | undefined, userFacingMessage?: string): string;
+/** A thrown value as the browser receives it: its code, and only the message `toClientErrorMessage` allows. */
+export declare const toClientError: (error: unknown) => ZiteError;
+export {};

package/dist/esm/start/errors.js

@@ -0,0 +1,99 @@
+import { currentHost } from "./host.js";
+import { redactSecrets } from "./redactSecrets.js";
+const STATUS = {
+    BAD_REQUEST: 400,
+    INVALID_INPUT: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    CONFLICT: 409,
+    RATE_LIMITED: 429,
+    INTERNAL_ERROR: 500,
+};
+/** @internal The HTTP status each code answers with. */
+export const ZITE_ERROR_STATUS = STATUS;
+export const isZiteErrorCode = (code) => typeof code === "string" && Object.prototype.hasOwnProperty.call(STATUS, code);
+/**
+ * Fail with a status: `throw new ZiteError('FORBIDDEN', 'Only the owner can edit this')`. On the live app,
+ * `userFacingMessage` is what users read in place of `message`, which stays for logs and the editor.
+ */
+export class ZiteError extends Error {
+    code;
+    userFacingMessage;
+    constructor(first, second) {
+        const options = typeof first === "object"
+            ? first
+            : isZiteErrorCode(first)
+                ? { code: first, message: second ?? first }
+                : { code: isZiteErrorCode(second) ? second : "INTERNAL_ERROR", message: first };
+        super(options.message);
+        this.name = "ZiteError";
+        this.code = options.code;
+        if (options.userFacingMessage)
+            this.userFacingMessage = options.userFacingMessage;
+    }
+}
+/**
+ * A ZiteError from any copy of zitejs as this one's. Integration SDKs and code written for classic throw
+ * `zitejs/backend`'s class, which `instanceof` doesn't recognise.
+ */
+export const asZiteError = (error) => {
+    if (error instanceof ZiteError)
+        return error;
+    if (!(error instanceof Error) || error.name !== "ZiteError")
+        return undefined;
+    const { code, userFacingMessage } = error;
+    if (!isZiteErrorCode(code))
+        return undefined;
+    return new ZiteError({
+        code,
+        message: error.message,
+        ...(typeof userFacingMessage === "string" && { userFacingMessage }),
+    });
+};
+// Ported from restly's packages/endpoint-setup/src/endpointErrors.ts; keep the two in step. The fences are consumed
+// characters rather than lookbehinds, which older Safari can't parse: this module ships to the browser.
+const INTERNAL_SERVICE_NAMES = [
+    "zite-shard-restly-server",
+    "restly-server",
+    "workflow-runner",
+    "base-runner",
+    "app-runner",
+    "utility-service",
+];
+const PRIVATE_IPV4 = String.raw `\b(?:10|127)\.\d{1,3}\.\d{1,3}\.\d{1,3}\b|\b172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}\b|\b192\.168\.\d{1,3}\.\d{1,3}\b|\b169\.254\.\d{1,3}\.\d{1,3}\b`;
+const PRIVATE_IPV6 = String.raw `(?:^|[^\w:])(?:::1|(?:f[cd][0-9a-f]{2}|fe[89ab][0-9a-f]):[0-9a-f:]+)(?![\w:])`;
+const INTERNAL_HOSTNAME = String.raw `(?:^|[^\w.-])(?:${INTERNAL_SERVICE_NAMES.join("|")}|localhost)(?:-\w+)*(?::\d+)?(?![\w.-])`;
+const UNAVAILABLE = "A service this app depends on is temporarily unavailable. Please try again.";
+const AI_UNAVAILABLE = "AI features are temporarily unavailable. Please contact the app owner.";
+const INFRASTRUCTURE_PATTERNS = [
+    { pattern: new RegExp(`${PRIVATE_IPV4}|${PRIVATE_IPV6}|${INTERNAL_HOSTNAME}`, "i"), replacement: UNAVAILABLE },
+    { pattern: /AI is paused: your organization is over its AI credit limit/i, replacement: AI_UNAVAILABLE },
+    {
+        pattern: /platform\.openai\.com\/(?:settings\/organization\/billing|docs\/guides\/error-codes)/i,
+        replacement: AI_UNAVAILABLE,
+    },
+];
+/**
+ * What a failure may say to the app's users, as on classic. The message is the app author's, so it passes, with
+ * credentials redacted in place; one naming our infrastructure or billing is replaced whole. Preview is the editor,
+ * which reads it unchanged.
+ */
+export function toClientErrorMessage(errorMessage, mode, userFacingMessage) {
+    if (mode === "preview")
+        return errorMessage;
+    if (userFacingMessage)
+        return userFacingMessage;
+    const redacted = redactSecrets(errorMessage);
+    for (const { pattern, replacement } of INFRASTRUCTURE_PATTERNS) {
+        if (pattern.test(redacted))
+            return replacement;
+    }
+    return redacted;
+}
+/** A thrown value as the browser receives it: its code, and only the message `toClientErrorMessage` allows. */
+export const toClientError = (error) => {
+    const zite = asZiteError(error);
+    const message = error instanceof Error ? error.message : String(error);
+    return new ZiteError(zite?.code ?? "INTERNAL_ERROR", toClientErrorMessage(message, currentHost()?.mode, zite?.userFacingMessage));
+};

package/dist/esm/start/errors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/start/errors.test.js

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { asZiteError, ZiteError } from "./errors.js";
+describe("ZiteError", () => {
+    it("takes Start's order, classic's order and classic's options", () => {
+        expect(new ZiteError("FORBIDDEN", "Owners only")).toMatchObject({ code: "FORBIDDEN", message: "Owners only" });
+        expect(new ZiteError("NOT_FOUND")).toMatchObject({ code: "NOT_FOUND", message: "NOT_FOUND" });
+        expect(new ZiteError("Owners only", "FORBIDDEN")).toMatchObject({ code: "FORBIDDEN", message: "Owners only" });
+        expect(new ZiteError("Something broke")).toMatchObject({ code: "INTERNAL_ERROR", message: "Something broke" });
+        expect(new ZiteError({ code: "CONFLICT", message: "Row 3 changed", userFacingMessage: "Someone else edited this." }))
+            .toMatchObject({ code: "CONFLICT", message: "Row 3 changed", userFacingMessage: "Someone else edited this." });
+    });
+});
+describe("asZiteError", () => {
+    it("recognises another copy's ZiteError by name and code", () => {
+        const classic = Object.assign(new Error("No such deal"), { name: "ZiteError", code: "NOT_FOUND", userFacingMessage: "Gone." });
+        expect(asZiteError(classic)).toMatchObject({ code: "NOT_FOUND", message: "No such deal", userFacingMessage: "Gone." });
+    });
+    it("refuses anything else", () => {
+        expect(asZiteError(new Error("plain"))).toBeUndefined();
+        expect(asZiteError(Object.assign(new Error("x"), { name: "ZiteError", code: "toString" }))).toBeUndefined();
+        expect(asZiteError({ name: "ZiteError", code: "NOT_FOUND", message: "not an Error" })).toBeUndefined();
+    });
+});

package/dist/esm/start/index.d.ts

@@ -1,5 +1,6 @@
 import type { User } from "./types.js";
-export type { User, ZiteRequestContext } from "./types.js";
+export type { Role, User, ZiteRequestContext } from "./types.js";
+export { ZiteError, ZITE_ERROR_STATUS, type ZiteErrorCode, type ZiteErrorOptions } from "./errors.js";
 export { createZiteRouter, type ZiteRouterContext } from "./router.js";
 export { createWorkflow, type StartProviderTrigger, type StartTrigger, type Workflow, type WorkflowArgs, type WorkflowConfig, } from "./workflow.js";
 export type { ZiteSchedule } from "../schedules/index.js";
@@ -10,24 +11,7 @@ declare module "@tanstack/start-client-core" {
         description?: string;
     }
 }
-declare const STATUS: {
-    readonly BAD_REQUEST: 400;
-    readonly INVALID_INPUT: 400;
-    readonly UNAUTHORIZED: 401;
-    readonly FORBIDDEN: 403;
-    readonly NOT_FOUND: 404;
-    readonly CONFLICT: 409;
-    readonly RATE_LIMITED: 429;
-    readonly INTERNAL_ERROR: 500;
-};
-export type ZiteErrorCode = keyof typeof STATUS;
-/** @internal The HTTP status each code answers with. */
-export declare const ZITE_ERROR_STATUS: Readonly<Record<ZiteErrorCode, number>>;
-/** Fail with a status: `throw new ZiteError('FORBIDDEN', 'Only the owner can edit this')`. */
-export declare class ZiteError extends Error {
-    readonly code: ZiteErrorCode;
-    constructor(code: ZiteErrorCode, message?: string);
-}
+/** By the role's id or its name. */
 export declare const hasRole: (user: User, role: string) => boolean;
 /** The message a server function fails with when it needs a session; the platform's client middleware sends the user to sign in. */
 export declare const SIGN_IN_REQUIRED = "ZITE_SIGN_IN_REQUIRED";

package/dist/esm/start/index.js

@@ -1,32 +1,16 @@
 import { createMiddleware, createServerFn } from "@tanstack/react-start";
 import { setResponseStatus } from "@tanstack/react-start/server";
 import { USAGE_TOKEN_QUERY_PARAM } from "../auth/constants.js";
+import { asZiteError, toClientErrorMessage, ZiteError, ZITE_ERROR_STATUS } from "./errors.js";
 import { currentHost } from "./host.js";
+import { PREVIEW_CLAIM_PARAM, previewClaim } from "./previewClaim.js";
+import { recordRoute } from "./runLog.js";
 import { getHost, inScope, runInScope } from "./scope.js";
+export { ZiteError, ZITE_ERROR_STATUS } from "./errors.js";
 export { createZiteRouter } from "./router.js";
 export { createWorkflow, } from "./workflow.js";
-const STATUS = {
-    BAD_REQUEST: 400,
-    INVALID_INPUT: 400,
-    UNAUTHORIZED: 401,
-    FORBIDDEN: 403,
-    NOT_FOUND: 404,
-    CONFLICT: 409,
-    RATE_LIMITED: 429,
-    INTERNAL_ERROR: 500,
-};
-/** @internal The HTTP status each code answers with. */
-export const ZITE_ERROR_STATUS = STATUS;
-/** Fail with a status: `throw new ZiteError('FORBIDDEN', 'Only the owner can edit this')`. */
-export class ZiteError extends Error {
-    code;
-    constructor(code, message) {
-        super(message ?? code);
-        this.name = "ZiteError";
-        this.code = code;
-    }
-}
-export const hasRole = (user, role) => user.roles.includes(role);
+/** By the role's id or its name. */
+export const hasRole = (user, role) => user.roles.some(({ id, name }) => id === role || name === role);
 /** The message a server function fails with when it needs a session; the platform's client middleware sends the user to sign in. */
 export const SIGN_IN_REQUIRED = "ZITE_SIGN_IN_REQUIRED";
 export const isSignInRequired = (error) => error instanceof Error && error.message === SIGN_IN_REQUIRED;
@@ -44,10 +28,13 @@ export function loginHref(redirectTo) {
         params.set("redirectUrl", target.toString());
     else if (!target && redirectTo)
         params.set("redirectUrl", redirectTo);
-    // The editor preview's sign-in page needs the preview's token.
+    // The editor preview's sign-in page needs the preview's token, and its claim where the frame dropped the cookie.
     const usageToken = current ? new URL(current).searchParams.get(USAGE_TOKEN_QUERY_PARAM) : null;
     if (usageToken)
         params.set(USAGE_TOKEN_QUERY_PARAM, usageToken);
+    const claim = previewClaim();
+    if (claim)
+        params.set(PREVIEW_CLAIM_PARAM, claim);
     const query = params.toString();
     return query ? `/auth/login?${query}` : "/auth/login";
 }
@@ -81,7 +68,7 @@ const validationIssues = (error) => {
     }
 };
 const invalidInput = (issues) => {
-    if (getHost()?.mode === "live")
+    if (getHost()?.mode !== "preview")
         return new ZiteError("INVALID_INPUT", "Invalid input");
     const describe = ({ message, path = [] }) => {
         const at = path.map((segment) => String(typeof segment === "object" ? segment.key : segment)).join(".");
@@ -98,32 +85,37 @@ const withStatus = async (isServerFn, fn) => {
     }
     catch (caught) {
         const issues = validationIssues(caught);
-        const error = issues ? invalidInput(issues) : caught;
-        if (!(error instanceof ZiteError))
-            throw error;
-        if (!isServerFn)
-            return new Response(error.message, { status: STATUS[error.code] });
-        if (!nested)
-            setResponseStatus(STATUS[error.code]);
-        throw error;
+        const error = issues ? invalidInput(issues) : asZiteError(caught);
+        if (!isServerFn) {
+            if (!error)
+                throw caught;
+            const message = toClientErrorMessage(error.message, getHost()?.mode, error.userFacingMessage);
+            return new Response(message, { status: ZITE_ERROR_STATUS[error.code] });
+        }
+        // TanStack answers a failed server function 200, with the error in the body. Redirects and notFound aren't Errors.
+        if (!nested && (error || caught instanceof Error))
+            setResponseStatus(error ? ZITE_ERROR_STATUS[error.code] : 500);
+        throw error ?? caught;
     }
 };
+// A server route's run is recorded around its access decision, so a refusal shows with its status.
+const decide = (serverFnMeta, request, fn) => serverFnMeta ? withStatus(true, fn) : recordRoute(getHost(), request, () => withStatus(false, fn));
 /** Only signed-in users. Handlers get `context.user: User`. */
-export const signedIn = tag(createMiddleware().server(({ next, serverFnMeta }) => withStatus(!!serverFnMeta, async () => {
+export const signedIn = tag(createMiddleware().server(({ next, serverFnMeta, request }) => decide(serverFnMeta, request, async () => {
     const { user } = host();
     if (!user)
         throw new ZiteError("UNAUTHORIZED", SIGN_IN_REQUIRED);
     return runInScope({ kind: "signedIn", user }, () => next({ context: { user } }));
 })), { kind: "signedIn" });
 /** Anyone, signed in or not. Handlers get `context.user: User | null`. */
-export const anyone = tag(createMiddleware().server(({ next, serverFnMeta }) => withStatus(!!serverFnMeta, async () => {
+export const anyone = tag(createMiddleware().server(({ next, serverFnMeta, request }) => decide(serverFnMeta, request, async () => {
     const { user } = host();
     return runInScope({ kind: "anyone", user }, () => next({ context: { user } }));
 })), { kind: "anyone" });
-const webhookMiddleware = (paused) => tag(createMiddleware().server(({ next }) => {
+const webhookMiddleware = (paused) => tag(createMiddleware().server(({ next, request }) => {
     if (host().invoke?.kind !== "webhook")
         return new Response("Not found", { status: 404 });
-    return runInScope({ kind: "webhook", user: null }, () => next());
+    return recordRoute(getHost(), request, async () => runInScope({ kind: "webhook", user: null }, () => next()));
 }), paused ? { kind: "webhook", paused: true } : { kind: "webhook" });
 /**
  * Webhooks delivered by the platform, which already checked the URL token.