zitejs 0.9.138 → 0.10.0-start.1

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

@@ -0,0 +1,64 @@
+import type { User } from "./types.js";
+export type { User, ZiteRequestContext } from "./types.js";
+export { createZiteRouter, type ZiteRouterContext } from "./router.js";
+declare module "@tanstack/start-client-core" {
+    interface ServerFnOptions {
+        /** What this function does, in a sentence. Shown in the editor. */
+        description?: string;
+    }
+}
+declare const STATUS: {
+    readonly BAD_REQUEST: 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;
+/** 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);
+}
+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";
+export declare const isSignInRequired: (error: unknown) => boolean;
+/**
+ * The platform's sign-in page, returning to `redirectTo` (default: the current
+ * page). For guards: `throw redirect({ href: loginHref(), reloadDocument: true })`.
+ */
+export declare function loginHref(redirectTo?: string): string;
+/** What a zitejs middleware means, for describe. Keyed by identity, so composing or re-exporting keeps it. */
+export type ZiteMiddlewareKind = {
+    kind: "signedIn" | "anyone" | "webhook" | "factory";
+} | {
+    kind: "role";
+    role: string;
+};
+/** @internal */
+export declare const ziteMiddlewareKind: (middleware: unknown) => ZiteMiddlewareKind | undefined;
+/** Only signed-in users. Handlers get `context.user: User`. */
+export declare const signedIn: import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, {
+    user: User;
+}>;
+/** Anyone, signed in or not. Handlers get `context.user: User | null`. */
+export declare const anyone: import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, {
+    user: User | null;
+}>;
+/** Webhooks delivered by the platform, which already checked the URL token. */
+export declare const webhook: import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, undefined>;
+/** Signed-in users with this role. */
+export declare const role: (name: string) => import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, readonly [import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, {
+    user: User;
+}>], undefined>;
+declare const compiled: import("@tanstack/react-start").FunctionMiddlewareAfterClient<{}, unknown, undefined, undefined, undefined>;
+declare const builder: import("@tanstack/react-start").ServerFnBuilder<import("@tanstack/react-start").Register, import("@tanstack/react-start").Method, true>;
+type SignedInFn = ReturnType<typeof builder.middleware<readonly [typeof compiled, typeof signedIn]>>;
+type PublicFn = ReturnType<typeof builder.middleware<readonly [typeof compiled, typeof anyone]>>;
+/** A server function only signed-in users can call. */
+export declare const signedInFn: SignedInFn;
+/** A server function anyone can call (external apps only). */
+export declare const publicFn: PublicFn;

package/dist/esm/start/index.js

@@ -0,0 +1,123 @@
+import { createMiddleware, createServerFn } from "@tanstack/react-start";
+import { setResponseStatus } from "@tanstack/react-start/server";
+import { USAGE_TOKEN_QUERY_PARAM } from "../auth/constants.js";
+import { currentHost } from "./host.js";
+import { getHost, inScope, runInScope } from "./scope.js";
+export { createZiteRouter } from "./router.js";
+const STATUS = {
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    CONFLICT: 409,
+    RATE_LIMITED: 429,
+    INTERNAL_ERROR: 500,
+};
+/** 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);
+/** 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;
+/**
+ * The platform's sign-in page, returning to `redirectTo` (default: the current
+ * page). For guards: `throw redirect({ href: loginHref(), reloadDocument: true })`.
+ */
+export function loginHref(redirectTo) {
+    const current = typeof window !== "undefined" ? window.location.href : currentHost()?.url;
+    // Absolute on purpose: better-auth drops a relative callback with an encoded
+    // space, fragment or non-ASCII path, and never checks an absolute one.
+    const target = current ? new URL(redirectTo ?? current, current) : undefined;
+    const params = new URLSearchParams();
+    if (target && !(target.pathname === "/" && !target.search && !target.hash))
+        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.
+    const usageToken = current ? new URL(current).searchParams.get(USAGE_TOKEN_QUERY_PARAM) : null;
+    if (usageToken)
+        params.set(USAGE_TOKEN_QUERY_PARAM, usageToken);
+    const query = params.toString();
+    return query ? `/auth/login?${query}` : "/auth/login";
+}
+const kinds = new WeakMap();
+const tag = (middleware, kind) => {
+    kinds.set(middleware, kind);
+    return middleware;
+};
+/** @internal */
+export const ziteMiddlewareKind = (middleware) => typeof middleware === "object" && middleware !== null ? kinds.get(middleware) : undefined;
+// Identity comes from server-only storage, never TanStack's context, which
+// merges whatever context the browser sends.
+const host = () => {
+    const current = getHost();
+    if (!current)
+        throw new ZiteError("UNAUTHORIZED", "Missing platform context");
+    return current;
+};
+// Server functions report a status through TanStack's error envelope; server
+// routes need a Response. A nested call's failure is the caller's to handle.
+const withStatus = async (isServerFn, fn) => {
+    const nested = inScope();
+    try {
+        return await fn();
+    }
+    catch (error) {
+        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;
+    }
+};
+/** Only signed-in users. Handlers get `context.user: User`. */
+export const signedIn = tag(createMiddleware().server(({ next, serverFnMeta }) => withStatus(!!serverFnMeta, 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 }) => {
+    const { user } = host();
+    return runInScope({ kind: "anyone", user }, () => next({ context: { user } }));
+}), { kind: "anyone" });
+/** Webhooks delivered by the platform, which already checked the URL token. */
+export const webhook = tag(createMiddleware().server(({ next }) => {
+    if (host().invoke?.kind !== "webhook")
+        return new Response("Not found", { status: 404 });
+    return runInScope({ kind: "webhook", user: null }, () => next());
+}), { kind: "webhook" });
+/** Signed-in users with this role. */
+export const role = (name) => tag(createMiddleware()
+    .middleware([signedIn])
+    .server(({ next, context, serverFnMeta }) => withStatus(!!serverFnMeta, async () => {
+    if (!hasRole(context.user, name))
+        throw new ZiteError("FORBIDDEN", `Requires the ${name} role`);
+    return next();
+})), { kind: "role", role: name });
+// TanStack's compiler tags every server function it compiles with an id. A
+// builder it didn't compile (an object property, one returned from a helper)
+// has none and would run its handler wherever it was called, so it fails here.
+const compiled = tag(createMiddleware({ type: "function" }).client(({ next, serverFnMeta }) => {
+    if (!serverFnMeta?.id) {
+        throw new Error("This server function was not compiled by TanStack Start. Assign signedInFn(...)/publicFn(...)" +
+            ".handler(...) directly to its own top-level const, not an object property or a helper's return value.");
+    }
+    return next();
+}), { kind: "factory" });
+// TanStack doesn't export its builder-after-middleware type, so name it through the public builder.
+const builder = createServerFn();
+/** A server function only signed-in users can call. */
+export const signedInFn = createServerFn().middleware([compiled, signedIn]);
+/** A server function anyone can call (external apps only). */
+export const publicFn = createServerFn().middleware([compiled, anyone]);

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

@@ -0,0 +1,12 @@
+import { type AnySerializationAdapter } from "@tanstack/react-router";
+import type { SSROption } from "@tanstack/router-core";
+import type { AnyFunctionMiddleware, AnyRequestMiddleware, StartInstance } from "@tanstack/start-client-core";
+import { ZiteError } from "./index.js";
+/**
+ * The start instance every Start app builds with: the platform's middleware and
+ * adapters first, then whatever the app's own `src/start.ts` sets.
+ */
+export declare function createZiteStart<const TAdapters extends ReadonlyArray<AnySerializationAdapter> = [], TDefaultSsr extends SSROption = SSROption, const TRequest extends ReadonlyArray<AnyRequestMiddleware> = [], const TFunction extends ReadonlyArray<AnyFunctionMiddleware> = []>(app?: StartInstance<TAdapters, TDefaultSsr, TRequest, TFunction>): StartInstance<readonly [import("@tanstack/react-router").SerializationAdapter<ZiteError, {
+    code: "BAD_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "RATE_LIMITED" | "INTERNAL_ERROR";
+    message: string;
+}, never>, ...TAdapters], TDefaultSsr, readonly [import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, undefined>, ...TRequest], readonly [import("@tanstack/react-start").FunctionMiddlewareAfterClient<{}, unknown, undefined, undefined, undefined>, import("@tanstack/react-start").FunctionMiddlewareAfterServer<{}, unknown, undefined, undefined, undefined, undefined, undefined>, ...TFunction]>;

package/dist/esm/start/instance.js

@@ -0,0 +1,89 @@
+// For the generated `.zite/start.ts` only. Apps put their own options in
+// `src/start.ts`, which the generated instance composes after the platform's.
+import { createCsrfMiddleware, createMiddleware, createStart } from "@tanstack/react-start";
+import { createSerializationAdapter, redirect } from "@tanstack/react-router";
+import { isSignInRequired, loginHref, ZiteError } from "./index.js";
+import { getHost, inScope } from "./scope.js";
+// TanStack drops its default CSRF check once an app has a start instance.
+const csrf = createCsrfMiddleware({ filter: (ctx) => ctx.handlerType === "serverFn" });
+// The host answers a signed-out call with a plain 401, the app with a ZiteError;
+// either way the browser goes to sign in rather than showing an error.
+const signInOn401 = createMiddleware({ type: "function" }).client(async ({ next }) => {
+    try {
+        return await next();
+    }
+    catch (error) {
+        if (!isSignInRequired(error))
+            throw error;
+        const href = loginHref();
+        if (typeof window !== "undefined")
+            window.location.assign(href);
+        throw redirect({ href, reloadDocument: true });
+    }
+});
+const PREVIEW_LIMIT = 8_000;
+const preview = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "object" && value !== null && Symbol.asyncIterator in value)
+        return "[stream]";
+    try {
+        const json = JSON.stringify(value);
+        return json && json.length > PREVIEW_LIMIT ? `${json.slice(0, PREVIEW_LIMIT)}…` : json;
+    }
+    catch {
+        return "[unserializable]";
+    }
+};
+const errorOf = (error) => error instanceof ZiteError
+    ? { code: error.code, message: error.message }
+    : { code: "INTERNAL_ERROR", message: error instanceof Error ? error.message : String(error) };
+// Records each call for the run log. The host's own record of the request is the
+// floor; this adds what only the app sees: decoded input, output and errors.
+const runCapture = createMiddleware({ type: "function" }).server(async ({ next, data, serverFnMeta }) => {
+    const runs = getHost()?.runs;
+    const startedAt = Date.now();
+    const record = (outcome) => runs?.push({
+        fn: serverFnMeta.id,
+        name: serverFnMeta.name,
+        nested: inScope(),
+        startedAt,
+        durationMs: Date.now() - startedAt,
+        input: preview(data),
+        ...("error" in outcome ? { error: errorOf(outcome.error) } : { output: preview(outcome.output) }),
+    });
+    try {
+        const out = await next();
+        const failed = out.error;
+        record(failed === undefined ? { output: out.result } : { error: failed });
+        return out;
+    }
+    catch (error) {
+        record({ error });
+        throw error;
+    }
+});
+/** Carries a ZiteError to the browser as itself, so `instanceof ZiteError` and `.code` work there. */
+const ziteErrorAdapter = createSerializationAdapter({
+    key: "zite-error",
+    test: (value) => value instanceof ZiteError,
+    toSerializable: (error) => ({ code: error.code, message: error.message }),
+    fromSerializable: ({ code, message }) => new ZiteError(code, message),
+});
+/**
+ * The start instance every Start app builds with: the platform's middleware and
+ * adapters first, then whatever the app's own `src/start.ts` sets.
+ */
+export function createZiteStart(app) {
+    return createStart(async () => {
+        const own = app ? await app.getOptions() : undefined;
+        // Spreading the app's optional arrays loses their tuple types, which the
+        // route tree registers for typed context and serialization.
+        return {
+            ...own,
+            requestMiddleware: [csrf, ...(own?.requestMiddleware ?? [])],
+            functionMiddleware: [signInOn401, runCapture, ...(own?.functionMiddleware ?? [])],
+            serializationAdapters: [ziteErrorAdapter, ...(own?.serializationAdapters ?? [])],
+        };
+    });
+}

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

@@ -0,0 +1,17 @@
+import { type AnyRoute, type RouterConstructorOptions, type RouterHistory } from "@tanstack/react-router";
+import type { User } from "./types.js";
+/** The router context every Zite app's root route declares: `createRootRouteWithContext<ZiteRouterContext>()`. */
+export type ZiteRouterContext = {
+    user: User | null;
+};
+type Dehydrated = {
+    user: User | null;
+};
+type ZiteRouterOptions<TRouteTree extends AnyRoute> = Omit<RouterConstructorOptions<TRouteTree, "never", false, RouterHistory, Dehydrated>, "context" | "dehydrate" | "hydrate">;
+/**
+ * The router for `src/router.tsx`. The signed-in user is in `context.user`: on
+ * the server from the platform, in the browser from the page it rendered, so
+ * no request asks for it again.
+ */
+export declare function createZiteRouter<TRouteTree extends AnyRoute>(options: ZiteRouterOptions<TRouteTree>): import("@tanstack/router-core").RouterCore<TRouteTree, "never", false, RouterHistory, Dehydrated>;
+export {};

package/dist/esm/start/router.js

@@ -0,0 +1,34 @@
+import { createElement as h } from "react";
+import { createRouter, Link, useRouter, } from "@tanstack/react-router";
+import { currentHost } from "./host.js";
+const box = { maxWidth: 480, margin: "15vh auto", padding: 24, fontFamily: "system-ui, sans-serif", textAlign: "center" };
+function ZiteErrorComponent({ error }) {
+    const router = useRouter();
+    const message = error instanceof Error && error.name === "ZiteError" ? error.message : "Something went wrong.";
+    return h("div", { role: "alert", style: box }, h("p", { style: { fontWeight: 600 } }, message), h("button", { type: "button", onClick: () => router.invalidate() }, "Try again"));
+}
+function ZiteNotFound() {
+    return h("div", { style: box }, h("p", { style: { fontWeight: 600 } }, "Page not found"), h(Link, { to: "/" }, "Go home"));
+}
+/**
+ * The router for `src/router.tsx`. The signed-in user is in `context.user`: on
+ * the server from the platform, in the browser from the page it rendered, so
+ * no request asks for it again.
+ */
+export function createZiteRouter(options) {
+    const context = { user: currentHost()?.user ?? null };
+    const router = createRouter({
+        defaultPreload: "intent",
+        defaultPreloadStaleTime: 0,
+        scrollRestoration: true,
+        defaultErrorComponent: ZiteErrorComponent,
+        defaultNotFoundComponent: ZiteNotFound,
+        ...options,
+        context,
+        dehydrate: () => ({ user: context.user }),
+        hydrate: (dehydrated) => {
+            context.user = dehydrated.user;
+        },
+    });
+    return router;
+}

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

@@ -0,0 +1,15 @@
+import type { User, ZiteRequestContext } from "./types.js";
+export type AccessKind = "signedIn" | "anyone" | "webhook" | "workflow";
+export type AccessScope = {
+    kind: AccessKind;
+    user: User | null;
+};
+export declare const runInScope: <T>(scope: AccessScope, fn: () => T) => T;
+/** True inside another server function's scope, i.e. a nested server-side call. */
+export declare const inScope: () => boolean;
+export declare class NoAccessDecisionError extends Error {
+    constructor(what: string);
+}
+export declare const requireScope: (what: string) => AccessScope;
+export declare const runWithHost: <T>(host: ZiteRequestContext, fn: () => T) => T;
+export declare const getHost: () => ZiteRequestContext | undefined;

package/dist/esm/start/scope.js

@@ -0,0 +1,58 @@
+// Server-only. Only zitejs's access middleware opens an access scope, and the
+// platform transport refuses calls outside one, so code with no access decision
+// can't reach data, integrations or email however it was written.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { HOST_STORE_KEY } from "./host.js";
+// Keyed on globalThis so two copies of zitejs in one bundle share the stores.
+const stores = globalThis;
+const scopeStorage = (stores[Symbol.for("zitejs:access-scope")] ??=
+    new AsyncLocalStorage());
+const hostStorage = (stores[HOST_STORE_KEY] ??=
+    new AsyncLocalStorage());
+const isAsyncIterable = (value) => typeof value === "object" &&
+    value !== null &&
+    Symbol.asyncIterator in value &&
+    !(value instanceof ReadableStream);
+// TanStack resumes a streamed async generator from its serializer, outside the
+// middleware's async context, so each step re-enters the scope it started in.
+const rescope = (scope, source) => (async function* () {
+    const iterator = source[Symbol.asyncIterator]();
+    try {
+        while (true) {
+            const step = await scopeStorage.run(scope, () => iterator.next());
+            if (step.done)
+                return step.value;
+            yield step.value;
+        }
+    }
+    finally {
+        await scopeStorage.run(scope, async () => iterator.return?.());
+    }
+})();
+const rescopeResult = (scope, out) => {
+    const result = out?.result;
+    return isAsyncIterable(result) ? { ...out, result: rescope(scope, result) } : out;
+};
+export const runInScope = (scope, fn) => {
+    const out = scopeStorage.run(scope, fn);
+    return (out instanceof Promise
+        ? out.then((value) => rescopeResult(scope, value))
+        : rescopeResult(scope, out));
+};
+/** True inside another server function's scope, i.e. a nested server-side call. */
+export const inScope = () => scopeStorage.getStore() !== undefined;
+export class NoAccessDecisionError extends Error {
+    constructor(what) {
+        super(`${what} ran outside an access decision. Define server functions with signedInFn or publicFn, ` +
+            "and give server routes signedIn, anyone or webhook middleware. Loaders get data by calling a server function.");
+        this.name = "NoAccessDecisionError";
+    }
+}
+export const requireScope = (what) => {
+    const scope = scopeStorage.getStore();
+    if (!scope)
+        throw new NoAccessDecisionError(what);
+    return scope;
+};
+export const runWithHost = (host, fn) => hostStorage.run(host, fn);
+export const getHost = () => hostStorage.getStore();

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

@@ -0,0 +1,47 @@
+import { type AccessKind } from "./scope.js";
+import type { RunRecord, ZiteRequestContext } from "./types.js";
+export { runWithHost } from "./scope.js";
+export { describeApp } from "./describe.js";
+export type { RunRecord } from "./types.js";
+export type PlatformCallInput = {
+    integrationId: string;
+    className: string;
+    methodName: string;
+    params: unknown;
+    access: AccessKind;
+    userId: string | null;
+    requestId: string;
+};
+/** The `ZITE` service binding the host's Platform entrypoint gives every app script. */
+export type PlatformBinding = {
+    call(call: PlatformCallInput): Promise<unknown>;
+    /** One batch per request, after its response has ended. */
+    runs(batch: {
+        requestId: string;
+        runs: RunRecord[];
+    }): Promise<void>;
+};
+/**
+ * Routes every zitejs data, integration and email call through `call`, and only
+ * inside an access scope. The access kind travels with the call so the platform
+ * can record what a page read and, later, narrow anonymous reads.
+ */
+export declare function installPlatformTransport(call: (input: PlatformCallInput) => Promise<unknown>): void;
+/** The host's `x-zite-*` headers. Only the host can set them: the front strips them from public traffic. */
+export declare function hostContextFromRequest(request: Request): ZiteRequestContext;
+/** Every server function TanStack compiled, written in by `zite()` at build. Empty in dev, where TanStack doesn't call its id hook. */
+export declare const builtFunctionIds: () => string[];
+type Fetch = (request: Request, ...rest: unknown[]) => Promise<Response> | Response;
+/**
+ * The fetch handler of a Start app's server entry. Describe calls get the app's
+ * description; everything else runs TanStack with the host's identity in
+ * server-only storage. Platform calls go to the `ZITE` binding from the Worker's
+ * env, or to `platform` when a test or local dev supplies one.
+ */
+export declare function createZiteFetch(options: {
+    handler: {
+        fetch: Fetch;
+    };
+    getRouter: () => unknown;
+    platform?: PlatformBinding;
+}): Fetch;

package/dist/esm/start/server.js

@@ -0,0 +1,81 @@
+import { describeApp } from "./describe.js";
+import { getHost, requireScope, runWithHost } from "./scope.js";
+export { runWithHost } from "./scope.js";
+export { describeApp } from "./describe.js";
+/**
+ * Routes every zitejs data, integration and email call through `call`, and only
+ * inside an access scope. The access kind travels with the call so the platform
+ * can record what a page read and, later, narrow anonymous reads.
+ */
+export function installPlatformTransport(call) {
+    const sdkCall = (integrationId, className, methodName, params) => {
+        const scope = requireScope(`${className}.${methodName}`);
+        return call({
+            integrationId,
+            className,
+            methodName,
+            params,
+            access: scope.kind,
+            userId: scope.user?.id ?? null,
+            requestId: getHost()?.requestId ?? "",
+        });
+    };
+    globalThis.__wrapSdkCall = sdkCall;
+}
+const decodeUser = (value) => JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(value.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0))));
+/** The host's `x-zite-*` headers. Only the host can set them: the front strips them from public traffic. */
+export function hostContextFromRequest(request) {
+    const { headers } = request;
+    const user = headers.get("x-zite-user");
+    const [kind, name = ""] = headers.get("x-zite-invoke")?.split(":") ?? [];
+    return {
+        requestId: headers.get("x-zite-request-id") ?? crypto.randomUUID(),
+        url: request.url,
+        user: user ? decodeUser(user) : null,
+        invoke: kind === "webhook" || kind === "describe" || kind === "workflow" ? { kind, name } : null,
+        runs: [],
+    };
+}
+/** Every server function TanStack compiled, written in by `zite()` at build. Empty in dev, where TanStack doesn't call its id hook. */
+export const builtFunctionIds = () => "__ZITE_FN_IDS__".split(",").filter((id) => id && !id.startsWith("__ZITE"));
+// Server functions also run while a streamed page renders, so the run log is
+// complete only once the body has been read to the end.
+const onBodyEnd = (response, done) => {
+    if (!response.body) {
+        done();
+        return response;
+    }
+    return new Response(response.body.pipeThrough(new TransformStream({ flush: done })), response);
+};
+/**
+ * The fetch handler of a Start app's server entry. Describe calls get the app's
+ * description; everything else runs TanStack with the host's identity in
+ * server-only storage. Platform calls go to the `ZITE` binding from the Worker's
+ * env, or to `platform` when a test or local dev supplies one.
+ */
+export function createZiteFetch(options) {
+    let binding = options.platform;
+    // Fails closed: no binding means no platform access, never a fallback.
+    const platform = () => {
+        if (!binding)
+            throw new Error("The Zite platform binding is missing");
+        return binding;
+    };
+    installPlatformTransport((call) => platform().call(call));
+    return async (request, ...rest) => {
+        binding ??= rest[0]?.ZITE;
+        if (request.headers.get("x-zite-invoke") === "describe") {
+            return Response.json(await describeApp({ fnIds: builtFunctionIds(), getRouter: options.getRouter, request }));
+        }
+        const host = hostContextFromRequest(request);
+        const response = await runWithHost(host, () => options.handler.fetch(request));
+        return onBodyEnd(response, () => {
+            if (!host.runs.length || !binding)
+                return;
+            const flushed = binding.runs({ requestId: host.requestId, runs: host.runs }).catch((error) => {
+                console.error("[zite] couldn't record runs", error);
+            });
+            rest[1]?.waitUntil(flushed);
+        });
+    };
+}

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

@@ -0,0 +1,32 @@
+export type User = {
+    id: string;
+    email: string;
+    name: string;
+    roles: ReadonlyArray<string>;
+};
+/** One server function call, as the platform's run log shows it. Input and output are truncated JSON. */
+export type RunRecord = {
+    fn: string;
+    name?: string;
+    nested: boolean;
+    startedAt: number;
+    durationMs: number;
+    input?: string;
+    output?: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+};
+/** What the host resolved for this request. Set by the generated server entry, never by the browser. */
+export type ZiteRequestContext = {
+    requestId: string;
+    url: string;
+    user: User | null;
+    invoke: {
+        kind: "webhook" | "describe" | "workflow";
+        name: string;
+    } | null;
+    /** Filled by run capture, flushed to the platform once the response ends. */
+    runs: RunRecord[];
+};

package/dist/esm/start/types.js

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

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

@@ -0,0 +1,9 @@
+import type { PluginOption } from "vite";
+export type ZiteOptions = {
+    /** A server entry the caller owns, relative to the app root. By default zite() writes the platform's. */
+    serverEntry?: string;
+    /** Build for Cloudflare Workers, the target the platform deploys. Defaults to true; false builds for Node. */
+    cloudflare?: boolean;
+};
+/** The one plugin a Zite app's `vite.config.ts` uses. */
+export declare function zite(options?: ZiteOptions): PluginOption[];