@btst/stack 4.5.1 → 5.0.0

package/dist/shared/stack.mRRyZBUg.d.cts

@@ -0,0 +1,613 @@
+import { Route, createRouter } from '@btst/yar';
+import { QueryClient } from '@tanstack/react-query';
+import { DBAdapter, DbPlugin, DatabaseDefinition } from '@btst/db';
+import { Endpoint, Router } from 'better-call';
+import { ServerAuth } from '../authorization/server.cjs';
+import { z } from 'zod';
+import { AnyPermissionDescriptor, PermissionRequestFor, PermissionFactsFor, PermissionInputFor, PermissionRequest, AnyAuthorization, AuthorizationPermissionRequest } from '../authorization/index.cjs';
+import { a as StackIdentity } from './stack.BYMentwB.cjs';
+import { M as MaybePromise } from './stack.CKXzdGiJ.cjs';
+
+/** Whether a request operation requires identity authorization. */
+type OperationAccess = "authorized" | "public";
+/** How an operation result crosses the lifecycle boundary. */
+type OperationResultMode = "immutable" | "passthrough";
+/**
+ * A domain failure that is safe for an HTTP operation route to expose.
+ * Identity, rule, fact, and ordinary execution errors are intentionally not
+ * converted at the transport boundary.
+ */
+declare class OperationHttpError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly issues?: readonly unknown[];
+    constructor(statusCode: number, message: string, code: string, issues?: readonly unknown[]);
+}
+/** Plain values accepted at the immutable operation lifecycle boundary. */
+type OperationData = string | number | boolean | bigint | null | undefined | readonly OperationData[] | {
+    readonly [key: string]: OperationData;
+};
+/** Recursively readonly data exposed by an authorized operation lifecycle. */
+type DeepReadonly<T> = T extends (...args: any[]) => unknown ? T : T extends readonly unknown[] ? {
+    readonly [TKey in keyof T]: DeepReadonly<T[TKey]>;
+} : T extends object ? {
+    readonly [TKey in keyof T]: DeepReadonly<T[TKey]>;
+} : T;
+/** Validated input, trusted facts, and resolved identity passed through an operation. */
+interface OperationContext<TInput, TFacts> {
+    readonly input: DeepReadonly<TInput>;
+    readonly facts: DeepReadonly<TFacts>;
+    readonly identity: DeepReadonly<StackIdentity> | null;
+    readonly request?: Request;
+}
+/** Context available after an authorized operation enters its lifecycle. */
+interface OperationErrorContext<TInput, TFacts> extends OperationContext<TInput, TFacts> {
+    readonly error: unknown;
+}
+/** A validated plugin operation shared by every server transport. */
+interface Operation<TInputSchema extends z.ZodTypeAny = z.ZodTypeAny, TPermission extends AnyPermissionDescriptor = AnyPermissionDescriptor, TResult = unknown, TPassthroughResult extends boolean = false> {
+    readonly input: TInputSchema;
+    readonly permission: TPermission;
+    readonly access: OperationAccess;
+    readonly resultMode: TPassthroughResult extends true ? "passthrough" : "immutable";
+}
+/** Any plugin operation, for generic stack composition. */
+type AnyOperation = Operation<z.ZodTypeAny, AnyPermissionDescriptor, any, false> | Operation<z.ZodTypeAny, AnyPermissionDescriptor, any, true>;
+/** Named operations exposed by a backend plugin. */
+type OperationRecord = Record<string, AnyOperation>;
+type OperationInput<TOperation extends AnyOperation> = TOperation extends Operation<infer TInputSchema, any, any, any> ? z.input<TInputSchema> : never;
+type OperationTransportResult<TOperation extends AnyOperation> = TOperation extends Operation<any, any, infer TResult, infer TPassthroughResult> ? TPassthroughResult extends true ? TResult : DeepReadonly<TResult> : never;
+/** Infer the permission request enforced by an operation. */
+type OperationPermissionRequest<TOperation extends AnyOperation> = TOperation extends Operation<any, infer TPermission, any, any> ? PermissionRequestFor<TPermission> : never;
+/** Convert operation definitions into their bound callable application API. */
+type OperationApi<TOperations extends OperationRecord> = {
+    [TKey in keyof TOperations]: (input: OperationInput<TOperations[TKey]>) => Promise<OperationTransportResult<TOperations[TKey]>>;
+};
+/** One request-bound operation plus its endpoint-binding helper. */
+type RouteOperation<TOperation extends AnyOperation> = {
+    (input: OperationInput<TOperation>, request: Request): Promise<OperationTransportResult<TOperation>>;
+    /** Generate an endpoint handler that always executes this exact operation. */
+    route<TContext extends {
+        readonly request: Request;
+        readonly error: (...args: any[]) => Error;
+    }>(resolveInput: (context: TContext) => MaybePromise<OperationInput<TOperation>>): (context: TContext) => Promise<OperationTransportResult<TOperation>>;
+};
+/** Operations bound to an HTTP transport; every call requires its request. */
+type RouteOperationApi<TOperations extends OperationRecord> = {
+    [TKey in keyof TOperations]: RouteOperation<TOperations[TKey]>;
+};
+/** Shared configuration shape for immutable and passthrough operations. */
+type OperationConfig<TInputSchema extends z.ZodTypeAny, TPermission extends AnyPermissionDescriptor, TExecute extends (ctx: OperationContext<z.output<TInputSchema>, PermissionFactsFor<TPermission>>) => MaybePromise<unknown>, TResult> = {
+    input: [z.output<TInputSchema>] extends [OperationData] ? TInputSchema : never;
+    permission: [PermissionFactsFor<TPermission>] extends [OperationData] ? TPermission : never;
+    /**
+     * Explicitly bypass request identity authorization for this one operation.
+     * Validation, trusted fact derivation, lifecycle hooks, and execution still run.
+     * @default "authorized"
+     */
+    access?: OperationAccess;
+    facts: (ctx: {
+        readonly input: DeepReadonly<z.output<TInputSchema>>;
+        readonly request?: Request;
+    }) => MaybePromise<PermissionInputFor<TPermission>>;
+    /**
+     * Derive any compound permission checks from validated input and trusted
+     * primary facts after request execution authorizes the primary permission.
+     * Every returned request is authorized before lifecycle hooks run; trusted
+     * execution skips only the evaluations.
+     */
+    additionalPermissions?: (ctx: {
+        readonly input: DeepReadonly<z.output<TInputSchema>>;
+        readonly facts: DeepReadonly<PermissionFactsFor<TPermission>>;
+        readonly request?: Request;
+    }) => MaybePromise<readonly PermissionRequest<string, any>[]>;
+    before?: (ctx: OperationContext<z.output<TInputSchema>, PermissionFactsFor<TPermission>>) => MaybePromise<void>;
+    execute: TExecute;
+    after?: (ctx: OperationContext<z.output<TInputSchema>, PermissionFactsFor<TPermission>> & {
+        readonly result: TResult;
+    }) => MaybePromise<void>;
+    onError?: (ctx: OperationErrorContext<z.output<TInputSchema>, PermissionFactsFor<TPermission>>) => MaybePromise<void>;
+};
+/**
+ * Define validation, trusted fact derivation, authorization, lifecycle hooks,
+ * and execution once so transports cannot accidentally bypass the pipeline.
+ *
+ * The operation descriptor deliberately has no public `run()` method. Stack
+ * composition binds it to HTTP, `forRequest().operations`, and the explicit
+ * `trusted` namespace so callers cannot forge a trusted execution flag.
+ */
+declare function defineOperation<const TInputSchema extends z.ZodTypeAny, const TPermission extends AnyPermissionDescriptor, const TExecute extends (ctx: OperationContext<z.output<TInputSchema>, PermissionFactsFor<TPermission>>) => MaybePromise<OperationData>>(config: {
+    input: [z.output<TInputSchema>] extends [OperationData] ? TInputSchema : never;
+    permission: [PermissionFactsFor<TPermission>] extends [OperationData] ? TPermission : never;
+    /**
+     * Explicitly bypass request identity authorization for this one operation.
+     * Validation, trusted fact derivation, lifecycle hooks, and execution still run.
+     * @default "authorized"
+     */
+    access?: OperationAccess;
+    facts: (ctx: {
+        readonly input: DeepReadonly<z.output<TInputSchema>>;
+        readonly request?: Request;
+    }) => MaybePromise<PermissionInputFor<TPermission>>;
+    additionalPermissions?: (ctx: {
+        readonly input: DeepReadonly<z.output<TInputSchema>>;
+        readonly facts: DeepReadonly<PermissionFactsFor<TPermission>>;
+        readonly request?: Request;
+    }) => MaybePromise<readonly PermissionRequest<string, any>[]>;
+    before?: (ctx: OperationContext<z.output<TInputSchema>, PermissionFactsFor<TPermission>>) => MaybePromise<void>;
+    execute: TExecute;
+    after?: (ctx: OperationContext<z.output<TInputSchema>, PermissionFactsFor<TPermission>> & {
+        readonly result: DeepReadonly<Awaited<ReturnType<TExecute>>>;
+    }) => MaybePromise<void>;
+    onError?: (ctx: OperationErrorContext<z.output<TInputSchema>, PermissionFactsFor<TPermission>>) => MaybePromise<void>;
+}): Operation<TInputSchema, TPermission, Awaited<ReturnType<TExecute>>>;
+/**
+ * Define an operation whose transport-native result must retain its runtime
+ * identity (for example a streaming `Response`). Input, facts, identity,
+ * authorization, and lifecycle ordering remain identical to `defineOperation`;
+ * only the result skips recursive freezing.
+ */
+declare function definePassthroughOperation<const TInputSchema extends z.ZodTypeAny, const TPermission extends AnyPermissionDescriptor, const TExecute extends (ctx: OperationContext<z.output<TInputSchema>, PermissionFactsFor<TPermission>>) => MaybePromise<unknown>>(config: OperationConfig<TInputSchema, TPermission, TExecute, Awaited<ReturnType<TExecute>>>): Operation<TInputSchema, TPermission, Awaited<ReturnType<TExecute>>, true>;
+
+/** A true infrastructure route that intentionally bypasses business operations. */
+interface InfrastructureRouteDeclaration {
+    /** Infrastructure access is explicit and currently limited to public metadata. */
+    readonly access: "public";
+    /** Why this route cannot use the business-operation pipeline. */
+    readonly rationale: string;
+}
+/** Narrow route-key allowlist for a backend plugin's infrastructure handlers. */
+type InfrastructureRouteInventory = Readonly<Record<string, InfrastructureRouteDeclaration>>;
+/** Safe authorization metadata for one composed HTTP endpoint. */
+interface ComposedEndpointInventoryEntry {
+    readonly pluginKey: string;
+    readonly pluginName: string;
+    readonly routeKey: string;
+    readonly method: string;
+    readonly path: string;
+    readonly source: "operation" | "infrastructure";
+    readonly access: "permission" | "public";
+    readonly permissionId?: string;
+}
+
+/** An absolute origin plus the path mounted below that origin. */
+interface ClientLocation {
+    /** Absolute HTTP(S) origin, without a pathname. */
+    baseURL: string;
+    /** Mount path below the origin, normalized with a leading slash. */
+    basePath: string;
+}
+/** Shared API transport configured once for a request or browser stack. */
+interface ClientApiConfig extends ClientLocation {
+    /**
+     * Per-request server headers. Browser-created stacks reject this field so a
+     * request cookie or authorization value cannot enter the provider projection.
+     */
+    headers?: HeadersInit;
+}
+/** A same-origin endpoint replacement that inherits the configured origin. */
+interface ClientPathEndpointOverride {
+    /** Replacement path on the inherited top-level origin. */
+    basePath: string;
+    /** A path-only replacement cannot partially replace the origin. */
+    baseURL?: never;
+}
+/** A complete endpoint replacement. A new origin never inherits only a path. */
+interface ClientAbsoluteEndpointOverride extends ClientLocation {
+}
+/** A location override must replace a path, or an origin and path together. */
+type ClientLocationOverride = ClientPathEndpointOverride | ClientAbsoluteEndpointOverride;
+/**
+ * Per-plugin API replacement. Headers and credentials declared here are
+ * deliberately browser-safe and are the only transport additions projected to
+ * the provider. Server request headers are resolved independently.
+ */
+type ClientApiEndpointOverride = ClientLocationOverride & {
+    /** Explicit browser-safe headers used in both server and browser transports. */
+    browserHeaders?: HeadersInit;
+    /** Explicit browser Fetch credentials behavior for this endpoint. */
+    credentials?: RequestCredentials;
+};
+/**
+ * Stack-owned endpoint replacements for one registered client plugin. An empty
+ * object inherits both top-level locations unchanged.
+ */
+interface ClientPluginEndpointOverride {
+    /** Optional replacement for the plugin's BTST API endpoint. */
+    api?: ClientApiEndpointOverride;
+    /** Optional replacement for the plugin's rendered/public site location. */
+    site?: ClientLocationOverride;
+}
+/** Effective API transport captured by a resolved plugin definition. */
+interface ResolvedClientApi extends ClientLocation {
+    /** Effective request headers for this stack instance. Never provider-facing. */
+    headers?: Headers;
+    /** Explicit browser-safe cross-origin credentials behavior. */
+    credentials?: RequestCredentials;
+}
+/** Shared runtime supplied when a client plugin definition is expanded. */
+interface ResolvedClientPluginRuntime<TId extends string = string> {
+    /** Stable programmatic identifier bound by client-stack registration. */
+    id: TId;
+    /** Effective API endpoint and request-specific transport values. */
+    api: ResolvedClientApi;
+    /** Effective public site location for routes, metadata, and sitemap output. */
+    site: ClientLocation;
+    /** The one React Query client shared by every client-stack consumer. */
+    queryClient: QueryClient;
+}
+/** Provider-safe API transport; it can contain only explicitly public headers. */
+interface ClientProviderApi extends ClientLocation {
+    /** Explicit browser-safe endpoint headers; never server request headers. */
+    browserHeaders?: Headers;
+    /** Explicit browser Fetch credentials behavior for this endpoint. */
+    credentials?: RequestCredentials;
+}
+/** Provider-safe endpoint view for one registered plugin. */
+interface ClientProviderPluginRuntime<TId extends string = string, TConfig extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
+    /** Stable programmatic identifier bound by client-stack registration. */
+    id: TId;
+    /** Provider-safe effective API endpoint for this plugin. */
+    api: ClientProviderApi;
+    /** Effective site location for this plugin. */
+    site: ClientLocation;
+    /**
+     * Browser-safe plugin factory values exposed to components. Never contains
+     * request headers, secrets, or server-only objects.
+     */
+    config?: TConfig;
+}
+/**
+ * Context passed to backend plugins during route creation
+ * Provides access to all registered plugins for introspection (used by openAPI plugin)
+ */
+interface StackContext {
+    /** All registered backend plugins */
+    plugins: Record<string, BackendPlugin<any, any, any>>;
+    /** The API base path (e.g., "/api/data") */
+    basePath: string;
+    /** The database adapter */
+    adapter: DBAdapter;
+    /** The server-side auth provider, when configured on `createBackendStack()` */
+    auth?: ServerAuth<AnyAuthorization>;
+    /** Routes already constructed for each plugin, used by introspection plugins. */
+    pluginRoutes: Record<string, Record<string, Endpoint>>;
+    /** Validated, safe metadata for every operation-first/infrastructure route. */
+    readonly endpointInventory?: readonly ComposedEndpointInventoryEntry[];
+}
+/**
+ * Context passed to client plugins during route creation
+ * Provides access to all registered plugins for introspection (used by routeDocs plugin)
+ */
+interface ClientStackContext<TPlugins extends Record<string, ClientPlugin<any, any>> = Record<string, ClientPlugin<any, any>>> {
+    /** All registered client plugins */
+    plugins: TPlugins;
+    /** The base path for the client (e.g., "/app") */
+    basePath?: string;
+}
+/**
+ * Backend plugin definition
+ * Defines API routes and data access for a feature
+ *
+ * Note: Each plugin defines its own schema using createDbPlugin().
+ * BTST composes all plugin schemas together at runtime using Better DB's .use() method.
+ * You can optionally provide a base schema via the dbSchema config option.
+ *
+ * @template TRoutes - The exact shape of routes this plugin provides (preserves keys and endpoint types)
+ * @template TRaw - The shape of the lower-level server surface exposed via `createBackendStack().raw`.
+ *   Defaults to `never` so that plugins without a `raw` factory are excluded from the
+ *   `createBackendStack().raw` namespace entirely, preventing accidental access of `undefined` at runtime.
+ */
+interface BackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>, TRaw extends Record<string, (...args: any[]) => any> = never, TOperations extends OperationRecord = never, TId extends string = string> {
+    /** Canonical stable programmatic identifier. */
+    readonly id: TId;
+    /**
+     * Create API endpoints for this plugin
+     * Returns an object with named endpoints that will be composed into the router
+     *
+     * @param adapter - Better DB adapter instance with methods:
+     *   create, update, updateMany, delete, deleteMany, findOne, findMany, count
+     * @param context - Stack context with access to all plugins (for introspection)
+     * @param operations - Request-bound operations declared by this plugin. When
+     *   the plugin declares operations, create every business endpoint with an
+     *   `operations.operationKey.route(ctx => input)` handler.
+     */
+    routes(adapter: DBAdapter, context: StackContext | undefined, operations: [TOperations] extends [never] ? Record<string, never> : RouteOperationApi<TOperations>): TRoutes;
+    dbPlugin: DbPlugin;
+    /**
+     * Optional factory that returns narrow lower-level helpers bound to the adapter.
+     * The returned object is merged into `createBackendStack().raw.<pluginName>.*` for deliberate
+     * lower-level or SSG data access without authorization or lifecycle composition.
+     *
+     * @param adapter - The adapter instance shared with `routes`
+     */
+    raw?: (adapter: DBAdapter) => TRaw;
+    /**
+     * Define operations shared by HTTP, request-scoped, and trusted calls.
+     * When present, every composed route must resolve to a same-key operation,
+     * an explicit operationRouteMap entry, or an infrastructure declaration.
+     */
+    operations?: (adapter: DBAdapter, context?: StackContext) => TOperations;
+    /**
+     * Explicit declarations for true infrastructure routes that cannot use a
+     * business operation. When present, all other routes must have same-key
+     * operations and stale declarations fail stack composition.
+     */
+    infrastructureRoutes?: InfrastructureRouteInventory;
+    /** Explicit route-key to operation-key mapping when their public names differ. */
+    operationRouteMap?: Readonly<Record<string, string>>;
+}
+/**
+ * Frontend plugin definition
+ * Defines pages, components, loaders, and React Query hooks for a feature
+ *
+ * @template TOverrides - The shape of overridable components/functions this plugin requires
+ * Example: { Link: ComponentType<{href: string}>, navigate: (path: string) => void }
+ * @template TRoutes - The exact shape of routes this plugin provides (preserves keys and route types)
+ */
+interface ClientPlugin<TOverrides = Record<string, never>, TRoutes extends Record<string, Route> = Record<string, Route>, TId extends string = string> {
+    /** Canonical stable programmatic identifier. */
+    readonly id: TId;
+    /**
+     * Define routes (pages) for this plugin
+     * Returns yar routes that will be composed into the router
+     *
+     * @param context - Optional context with access to all plugins (for introspection)
+     */
+    routes: (context?: ClientStackContext) => TRoutes;
+    /**
+     * Optional sitemap generator for this plugin. Should return absolute URLs.
+     * Implementations can call their own API endpoints to include dynamic routes.
+     */
+    sitemap?: () => Promise<Sitemap> | Sitemap;
+}
+/**
+ * Runtime-independent client plugin definition. The definition remains safe to
+ * import on the server and is expanded against one resolved stack runtime.
+ */
+interface ClientPluginDefinition<TOverrides = Record<string, never>, TRoutes extends Record<string, Route> = Record<string, Route>, TId extends string = string, TProviderConfig extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>, TApiRuntimeFrom extends string = never> {
+    /** Canonical stable programmatic identifier. */
+    readonly id: TId;
+    /**
+     * Optional programmatic ID whose effective API transport this definition
+     * consumes. The dependent plugin may still resolve its own site endpoint.
+     */
+    readonly apiRuntimeFrom?: TApiRuntimeFrom;
+    /**
+     * Small, browser-safe subset of factory values needed by components through
+     * `useStack().plugins[id].config`. Do not include secrets, request headers,
+     * server-only objects, or shared API/site/query runtime.
+     */
+    providerConfig?: TProviderConfig;
+    /** Expand plugin-specific options against one resolved stack runtime. */
+    resolve: (runtime: ResolvedClientPluginRuntime<TId>) => Omit<ClientPlugin<TOverrides, TRoutes, TId>, "id">;
+}
+/** Runtime-independent client plugin registration resolved by the client stack. */
+type ClientPluginRegistration<TOverrides = Record<string, never>, TRoutes extends Record<string, Route> = Record<string, Route>, TId extends string = string, TProviderConfig extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>, TApiRuntimeFrom extends string = never> = ClientPluginDefinition<TOverrides, TRoutes, TId, TProviderConfig, TApiRuntimeFrom>;
+/**
+ * Utility type that maps each plugin key to the return type of its `raw` factory.
+ * Plugin keys whose `TRaw` resolves to `never` (i.e. plugins with no `raw` factory)
+ * are excluded from the resulting type via key remapping, preventing TypeScript from
+ * suggesting callable functions on what is actually `undefined` at runtime.
+ */
+type PluginRaw<TPlugins extends Record<string, BackendPlugin<any, any, any>>> = {
+    [K in keyof TPlugins as _RawOf<TPlugins[K]> extends never ? never : K]: _RawOf<TPlugins[K]>;
+};
+/** @internal Extract the TRaw parameter from a BackendPlugin type. */
+type _RawOf<T> = T extends BackendPlugin<infer _TRoutes, infer TRaw, infer _TOps> ? TRaw : never;
+type _OperationsOf<T> = T extends BackendPlugin<infer _TRoutes, infer _TRaw, infer TOperations> ? TOperations : never;
+/** Bound operation APIs, keyed by their registered backend plugin IDs. */
+type PluginOperations<TPlugins extends Record<string, BackendPlugin<any, any, any>>> = {
+    [K in keyof TPlugins as _OperationsOf<TPlugins[K]> extends never ? never : K]: OperationApi<_OperationsOf<TPlugins[K]>>;
+};
+type _OperationPermissionRequests<T> = T extends OperationRecord ? OperationPermissionRequest<T[keyof T]> : never;
+/** Permission requests required by all operations in a plugin map. */
+type PluginOperationPermissionRequests<TPlugins extends Record<string, BackendPlugin<any, any, any>>> = {
+    [K in keyof TPlugins]: _OperationPermissionRequests<_OperationsOf<TPlugins[K]>>;
+}[keyof TPlugins];
+type _RequestWithId<TRequest, TId> = TRequest extends {
+    readonly id: TId;
+} ? TRequest : never;
+type _RequestFacts<TRequest> = TRequest extends {
+    readonly facts: infer TFacts;
+} ? TFacts : never;
+type _IncompatibleOperationRequests<TOperationRequest, TAuthorizationRequest> = TOperationRequest extends {
+    readonly id: infer TId;
+} ? _RequestWithId<TAuthorizationRequest, TId> extends infer TRegistered ? [TRegistered] extends [never] ? TOperationRequest : [_RequestFacts<TOperationRequest>] extends [
+    _RequestFacts<TRegistered>
+] ? [_RequestFacts<TRegistered>] extends [
+    _RequestFacts<TOperationRequest>
+] ? never : TOperationRequest : TOperationRequest : TOperationRequest : TOperationRequest;
+/**
+ * Reject server adapters whose registered catalogs do not cover every
+ * operation descriptor in the composed stack.
+ */
+type CompatibleStackAuth<TPlugins extends Record<string, BackendPlugin<any, any, any>>, TAuth extends ServerAuth<AnyAuthorization> | undefined> = TAuth extends ServerAuth<infer TAuthorization extends AnyAuthorization> ? _IncompatibleOperationRequests<PluginOperationPermissionRequests<TPlugins>, AuthorizationPermissionRequest<TAuthorization>> extends never ? TAuth : never : TAuth;
+/**
+ * Configuration for creating the backend stack
+ */
+interface BackendStackConfig<TPlugins extends Record<string, BackendPlugin<any, any, any>> = Record<string, BackendPlugin<any, any, any>>, TAuth extends ServerAuth<AnyAuthorization> | undefined = ServerAuth<AnyAuthorization> | undefined> {
+    basePath: string;
+    dbSchema?: DatabaseDefinition;
+    plugins: TPlugins & MatchingPluginRegistrations<TPlugins>;
+    adapter: (db: DatabaseDefinition) => DBAdapter;
+    /**
+     * Server authorization created by `createServerAuth()`. When set,
+     * request operations evaluate their schema-backed permission after trusted
+     * facts are derived. When omitted, request operations remain permissive;
+     * use `trusted` to make trusted intent explicit.
+     */
+    auth?: TAuth;
+}
+type AnyClientPluginRegistration = ClientPluginRegistration<any, any, any, any, any>;
+/** @internal Extract a plugin's required canonical ID. */
+type _DeclaredPluginId<TPlugin> = TPlugin extends {
+    readonly id: infer TId extends string;
+} ? TId : never;
+/** @internal Extract browser-safe plugin-specific factory values. */
+type _ClientProviderConfig<TPlugin> = TPlugin extends ClientPluginDefinition<any, any, any, infer TProviderConfig, any> ? TProviderConfig : Readonly<Record<string, never>>;
+/** @internal Extract a plugin definition's API-runtime dependency. */
+type _ClientApiRuntimeSource<TPlugin> = TPlugin extends {
+    readonly apiRuntimeFrom: infer TSource extends string;
+} ? TSource : never;
+/** Reject a registration key that differs from a plugin's declared canonical ID. */
+type MatchingPluginRegistrations<TPlugins extends Record<string, unknown>> = {
+    [K in keyof TPlugins]: string extends _DeclaredPluginId<TPlugins[K]> ? TPlugins[K] : K extends _DeclaredPluginId<TPlugins[K]> ? _DeclaredPluginId<TPlugins[K]> extends K ? TPlugins[K] : never : never;
+};
+/** Stack-owned endpoint replacements, limited to registered plugin keys. */
+type ClientPluginEndpointOverrides<TPlugins extends Record<string, AnyClientPluginRegistration>> = Partial<{
+    [K in keyof TPlugins]: [_ClientApiRuntimeSource<TPlugins[K]>] extends [never] ? ClientPluginEndpointOverride : {
+        /** API transport is inherited from the declared source plugin. */
+        api?: never;
+        /** Rendered/public pages may still have a plugin-specific location. */
+        site?: ClientLocationOverride;
+    };
+}>;
+/** Canonical shared runtime configured once for the complete client stack. */
+interface ResolvedClientStackConfig<TPlugins extends Record<string, AnyClientPluginRegistration> = Record<string, AnyClientPluginRegistration>> {
+    /** Shared BTST API endpoint and optional request-specific server headers. */
+    api: ClientApiConfig;
+    /** Shared location of plugin-rendered public pages. */
+    site: ClientLocation;
+    /** The one React Query client used by loaders, hydration, and browser hooks. */
+    queryClient: QueryClient;
+    /** Runtime-independent plugin registrations. */
+    plugins: TPlugins & MatchingPluginRegistrations<TPlugins>;
+    /** Explicit endpoint replacements keyed by a registered plugin ID. */
+    endpoints?: ClientPluginEndpointOverrides<TPlugins>;
+}
+/** Canonical configuration for a resolved client stack. */
+type ClientStackConfig<TPlugins extends Record<string, AnyClientPluginRegistration> = Record<string, AnyClientPluginRegistration>> = ResolvedClientStackConfig<TPlugins>;
+/**
+ * Utility type to extract override types from plugins
+ * Maps plugin IDs to their override types
+ */
+declare const requiredClientPluginOverrides: unique symbol;
+/** @internal Marks a client plugin's entire provider override block as required. */
+type RequiredClientPluginOverrides<TOverrides> = TOverrides & {
+    readonly [requiredClientPluginOverrides]: true;
+};
+type _DeclaredPluginOverrides<TPlugin> = TPlugin extends ClientPlugin<infer TOverrides, any, any> ? TOverrides : TPlugin extends ClientPluginDefinition<infer TOverrides, any, any, any, any> ? TOverrides : never;
+type _PublicPluginOverrides<TOverrides> = Omit<TOverrides, typeof requiredClientPluginOverrides>;
+type InferPluginOverrides<TPlugins extends Record<string, AnyClientPluginRegistration>> = {
+    [K in keyof TPlugins]: _PublicPluginOverrides<_DeclaredPluginOverrides<TPlugins[K]>>;
+};
+type _HasNoConfigurableOverrides<TOverrides> = [TOverrides] extends [never] ? true : [keyof TOverrides] extends [never] ? true : TOverrides extends Record<string, never> ? true : false;
+type _RequiresProviderOverrideBlock<TPlugin> = 0 extends 1 & _DeclaredPluginOverrides<TPlugin> ? false : [_DeclaredPluginOverrides<TPlugin>] extends [
+    {
+        readonly [requiredClientPluginOverrides]: true;
+    }
+] ? true : false;
+/**
+ * Provider overrides inferred from registered client definitions. Plugins with
+ * no configurable fields are omitted rather than requiring empty blocks.
+ */
+type InferredPluginOverrides<TPlugins extends Record<string, AnyClientPluginRegistration>> = keyof _ConfigurablePluginOverrides<TPlugins> extends never ? Record<string, never> : _ConfigurablePluginOverrides<TPlugins>;
+type _ConfigurablePluginOverrides<TPlugins extends Record<string, AnyClientPluginRegistration>> = _RequiredConfigurablePluginOverrides<TPlugins> & _OptionalConfigurablePluginOverrides<TPlugins>;
+type _RequiredConfigurablePluginOverrides<TPlugins extends Record<string, AnyClientPluginRegistration>> = {
+    [K in keyof TPlugins as _HasNoConfigurableOverrides<InferPluginOverrides<TPlugins>[K]> extends true ? never : _RequiresProviderOverrideBlock<TPlugins[K]> extends true ? K : never]-?: InferPluginOverrides<TPlugins>[K];
+};
+type _OptionalConfigurablePluginOverrides<TPlugins extends Record<string, AnyClientPluginRegistration>> = {
+    [K in keyof TPlugins as _HasNoConfigurableOverrides<InferPluginOverrides<TPlugins>[K]> extends true ? never : _RequiresProviderOverrideBlock<TPlugins[K]> extends true ? never : K]?: InferPluginOverrides<TPlugins>[K];
+};
+/**
+ * Type for the pluginOverrides prop in StackContext
+ * Allows partial overrides per plugin
+ */
+type PluginOverrides<TPlugins extends Record<string, AnyClientPluginRegistration>> = {
+    [K in keyof TPlugins]?: Partial<InferPluginOverrides<TPlugins>[K]>;
+};
+/**
+ * Extract all routes from all client plugins, merging them into a single record
+ */
+type PluginRoutes<TPlugins extends Record<string, AnyClientPluginRegistration>> = MergeAllPluginRoutes<TPlugins>;
+/**
+ * Prefix all backend plugin route keys with the canonical plugin ID
+ * Example: { messages: { list: Endpoint } } => { messages_list: Endpoint }
+ */
+type PrefixedPluginRoutes<TPlugins extends Record<string, BackendPlugin<any, any, any>>> = UnionToIntersection<{
+    [PluginKey in keyof TPlugins]: TPlugins[PluginKey] extends BackendPlugin<infer TRoutes, any, any> ? {
+        [RouteKey in keyof TRoutes as `${PluginKey & string}_${RouteKey & string}`]: TRoutes[RouteKey];
+    } : never;
+}[keyof TPlugins]> extends infer U ? U extends Record<string, Endpoint> ? U : Record<string, Endpoint> : Record<string, Endpoint>;
+/**
+ * Result of creating the backend stack
+ */
+interface BackendStack<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>, TRaw extends Record<string, Record<string, (...args: any[]) => any>> = Record<string, Record<string, (...args: any[]) => any>>, TOperations extends Record<string, Record<string, (...args: any[]) => any>> = Record<string, Record<string, (...args: any[]) => any>>> {
+    handler: (request: Request) => Promise<Response>;
+    router: Omit<Router, "endpoints"> & {
+        endpoints: TRoutes;
+    };
+    dbSchema: DatabaseDefinition;
+    /** The database adapter shared across all plugins */
+    adapter: DBAdapter;
+    /** Narrow lower-level/SSG helpers that bypass operation composition. */
+    raw: TRaw;
+    /** User/request-scoped operations with automatic authorization. */
+    forRequest: (request: Request) => {
+        operations: TOperations;
+    };
+    /** Trusted operations that retain validation and lifecycle hooks. */
+    trusted: TOperations;
+}
+/**
+ * Helper type to extract routes from a client plugin
+ */
+type ExtractPluginRoutes<T> = T extends ClientPluginDefinition<any, infer TRoutes, any, any, any> ? TRoutes : never;
+/**
+ * Helper type to merge all routes from all plugins into a single record
+ */
+type MergeAllPluginRoutes<TPlugins extends Record<string, AnyClientPluginRegistration>> = UnionToIntersection<{
+    [K in keyof TPlugins]: ExtractPluginRoutes<TPlugins[K]>;
+}[keyof TPlugins]> extends infer U ? U extends Record<string, Route> ? U : Record<string, Route> : Record<string, Route>;
+/**
+ * Utility type to convert union to intersection
+ */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Result of creating the client stack
+ */
+interface ClientStack<TRoutes extends Record<string, Route> = Record<string, Route>> {
+    /** Resolved plugin definitions for intentional client-side introspection. */
+    context: ClientStackContext;
+    router: ReturnType<typeof createRouter<TRoutes, {}>>;
+    generateSitemap: () => Promise<Sitemap>;
+}
+declare const resolvedClientStackPlugins: unique symbol;
+/** Browser-safe runtime passed to `StackProvider` by the next composition slice. */
+interface ClientProviderProjection<TPlugins extends Record<string, AnyClientPluginRegistration> = Record<string, AnyClientPluginRegistration>> {
+    /** Shared provider-safe API location. Never contains request headers. */
+    api: ClientLocation;
+    /** Shared provider-safe site location. */
+    site: ClientLocation;
+    /** The one React Query client supplied to the client stack. */
+    queryClient: QueryClient;
+    /** Effective provider-safe endpoint values for every registered plugin. */
+    plugins: {
+        [K in keyof TPlugins]: ClientProviderPluginRuntime<[
+            _DeclaredPluginId<TPlugins[K]>
+        ] extends [never] ? K & string : _DeclaredPluginId<TPlugins[K]>, _ClientProviderConfig<TPlugins[K]>>;
+    };
+}
+/** Canonical client stack with a browser-safe provider projection. */
+interface ResolvedClientStack<TRoutes extends Record<string, Route> = Record<string, Route>, TPlugins extends Record<string, AnyClientPluginRegistration> = Record<string, AnyClientPluginRegistration>> extends ClientStack<TRoutes> {
+    /** @internal Type-only registration map used for provider inference. */
+    readonly [resolvedClientStackPlugins]?: TPlugins;
+    /** Browser-safe projection for provider and browser resource consumers. */
+    provider: ClientProviderProjection<TPlugins>;
+}
+/** Registered plugin definitions carried by a resolved client stack type. */
+type RegisteredClientPlugins<TStack> = TStack extends ResolvedClientStack<any, infer TPlugins> ? TPlugins : never;
+/**
+ * Minimal sitemap entry shape aligned with Next.js MetadataRoute.Sitemap
+ */
+type SitemapEntry = {
+    url: string;
+    lastModified?: string | Date;
+    changeFrequency?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+    priority?: number;
+};
+type Sitemap = Array<SitemapEntry>;
+
+export { OperationHttpError as i, defineOperation as n, definePassthroughOperation as o };
+export type { AnyOperation as A, BackendPlugin as B, ClientPlugin as C, DeepReadonly as D, ClientPluginEndpointOverride as E, ClientPluginEndpointOverrides as F, ClientProviderApi as G, ClientProviderPluginRuntime as H, InfrastructureRouteDeclaration as I, ClientProviderProjection as J, ClientStack as K, ClientStackContext as L, ResolvedClientApi as M, ResolvedClientStackConfig as N, OperationRecord as O, PluginOverrides as P, SitemapEntry as Q, RequiredClientPluginOverrides as R, StackContext as S, InferredPluginOverrides as T, RegisteredClientPlugins as U, PrefixedPluginRoutes as V, BackendStackConfig as W, CompatibleStackAuth as X, BackendStack as Y, PluginRaw as Z, PluginOperations as _, ComposedEndpointInventoryEntry as a, InfrastructureRouteInventory as b, Operation as c, OperationAccess as d, OperationApi as e, OperationContext as f, OperationData as g, OperationErrorContext as h, OperationPermissionRequest as j, OperationResultMode as k, RouteOperation as l, RouteOperationApi as m, ClientPluginDefinition as p, ClientPluginRegistration as q, ResolvedClientPluginRuntime as r, Sitemap as s, PluginRoutes as t, ClientStackConfig as u, ResolvedClientStack as v, ClientApiConfig as w, ClientApiEndpointOverride as x, ClientLocation as y, ClientLocationOverride as z };