@btst/stack 3.0.0-rc.1 → 3.0.0-rc.3

package/dist/shared/stack.BPLykw4s.d.ts

@@ -0,0 +1,436 @@
+import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
+import { OperationHttpError, DeepReadonly, Operation, OperationData } from '@btst/stack/plugins/api';
+import { PermissionFactsFor } from '@btst/stack/authorization';
+import { StackIdentity } from '@btst/stack/context';
+import { z } from 'zod';
+import { mediaPermissions } from '../plugins/media/permissions.js';
+import { S as SerializedAsset, a as SerializedFolder } from './stack.DjGixVx3.js';
+import { b as S3UploadToken, a as StorageAdapter } from './stack.DVEjWKCT.js';
+import * as better_call from 'better-call';
+import { QueryClient } from '@tanstack/react-query';
+import { M as MediaEndpointPartition } from './stack.BMmvEBH_.js';
+
+declare const AssetListQuerySchema: z.ZodObject<{
+    folderId: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+    offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+declare const createAssetSchema: z.ZodObject<{
+    filename: z.ZodString;
+    originalName: z.ZodString;
+    mimeType: z.ZodString;
+    size: z.ZodNumber;
+    url: z.ZodURL;
+    folderId: z.ZodOptional<z.ZodString>;
+    alt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const updateAssetSchema: z.ZodObject<{
+    alt: z.ZodOptional<z.ZodString>;
+    folderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+declare const createFolderSchema: z.ZodObject<{
+    name: z.ZodString;
+    parentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const uploadTokenRequestSchema: z.ZodObject<{
+    filename: z.ZodString;
+    mimeType: z.ZodString;
+    size: z.ZodNumber;
+    folderId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
+/** Runtime input for one asset operation. */
+declare const AssetIdOperationInputSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/** Runtime input for an asset update operation. */
+declare const UpdateAssetOperationInputSchema: z.ZodObject<{
+    id: z.ZodString;
+    data: z.ZodObject<{
+        alt: z.ZodOptional<z.ZodString>;
+        folderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Runtime input for one folder operation. */
+declare const FolderIdOperationInputSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/** Runtime input for a folder collection operation. */
+declare const FolderListOperationInputSchema: z.ZodObject<{
+    parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** Runtime input for a direct file upload operation. */
+declare const DirectUploadOperationInputSchema: z.ZodObject<{
+    filename: z.ZodString;
+    mimeType: z.ZodString;
+    size: z.ZodNumber;
+    contentBase64: z.ZodString;
+    folderId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Runtime input for the Vercel Blob token and callback operation. */
+declare const VercelBlobOperationInputSchema: z.ZodObject<{
+    body: z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodLiteral<"blob.generate-client-token">;
+        payload: z.ZodObject<{
+            pathname: z.ZodString;
+            multipart: z.ZodBoolean;
+            clientPayload: z.ZodNullable<z.ZodString>;
+            callbackUrl: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodCustom<{
+        type: "blob.upload-completed";
+        payload: {
+            blob: {
+                url: string;
+                pathname: string;
+            };
+            tokenPayload?: string | null | undefined;
+        };
+    }, {
+        type: "blob.upload-completed";
+        payload: {
+            blob: {
+                url: string;
+                pathname: string;
+            };
+            tokenPayload?: string | null | undefined;
+        };
+    }>, z.ZodObject<{
+        pathname: z.ZodString;
+        clientPayload: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>]>;
+}, z.core.$strip>;
+type LibraryReadFacts = PermissionFactsFor<typeof mediaPermissions.library.read>;
+type AssetUpdateFacts = PermissionFactsFor<typeof mediaPermissions.asset.update>;
+type AssetDeleteFacts = PermissionFactsFor<typeof mediaPermissions.asset.delete>;
+type AssetUploadFacts = PermissionFactsFor<typeof mediaPermissions.asset.upload>;
+type FolderCreateFacts = PermissionFactsFor<typeof mediaPermissions.folder.create>;
+type FolderDeleteFacts = PermissionFactsFor<typeof mediaPermissions.folder.delete>;
+/** An authorized, row-filtered page of Media assets. */
+interface MediaAssetListResult {
+    readonly items: readonly SerializedAsset[];
+    readonly total: number;
+    readonly limit?: number;
+    readonly offset?: number;
+}
+/** Complete Media operation inventory shared by every server transport. */
+type MediaOperations = {
+    readonly listAssets: Operation<typeof AssetListQuerySchema, typeof mediaPermissions.library.read, MediaAssetListResult>;
+    readonly createAsset: Operation<typeof createAssetSchema, typeof mediaPermissions.asset.upload, SerializedAsset>;
+    readonly updateAsset: Operation<typeof UpdateAssetOperationInputSchema, typeof mediaPermissions.asset.update, SerializedAsset>;
+    readonly deleteAsset: Operation<typeof AssetIdOperationInputSchema, typeof mediaPermissions.asset.delete, {
+        readonly success: true;
+    }>;
+    readonly listFolders: Operation<typeof FolderListOperationInputSchema, typeof mediaPermissions.library.read, readonly SerializedFolder[]>;
+    readonly createFolder: Operation<typeof createFolderSchema, typeof mediaPermissions.folder.create, SerializedFolder>;
+    readonly deleteFolder: Operation<typeof FolderIdOperationInputSchema, typeof mediaPermissions.folder.delete, {
+        readonly success: true;
+    }>;
+    readonly uploadDirect: Operation<typeof DirectUploadOperationInputSchema, typeof mediaPermissions.asset.upload, SerializedAsset>;
+    readonly uploadToken: Operation<typeof uploadTokenRequestSchema, typeof mediaPermissions.asset.upload, S3UploadToken>;
+    readonly uploadVercelBlob: Operation<typeof VercelBlobOperationInputSchema, typeof mediaPermissions.asset.upload, OperationData>;
+};
+/** A domain/HTTP failure raised after Media authorization succeeds. */
+declare class MediaOperationError extends OperationHttpError {
+    constructor(statusCode: number, message: string, code: string);
+}
+/** Typed context passed to Media lifecycle hooks after authorization succeeds. */
+interface MediaApiContext<TInput = unknown, TFacts = unknown> {
+    readonly input: DeepReadonly<TInput>;
+    readonly facts: DeepReadonly<TFacts>;
+    readonly identity: DeepReadonly<StackIdentity> | null;
+    readonly request?: Request;
+    readonly headers?: Headers;
+    readonly body?: unknown;
+    readonly params?: unknown;
+    readonly query?: unknown;
+}
+/** Typed post-operation context passed to Media result lifecycle hooks. */
+interface MediaApiResultContext<TInput = unknown, TFacts = unknown, TResult = unknown> extends MediaApiContext<TInput, TFacts> {
+    readonly result: DeepReadonly<TResult>;
+}
+/** Validated input passed to upload lifecycle hooks. */
+type MediaUploadOperationInput = z.output<typeof createAssetSchema> | z.output<typeof DirectUploadOperationInputSchema> | z.output<typeof uploadTokenRequestSchema> | z.output<typeof VercelBlobOperationInputSchema>;
+/** Validated input for upload operations that create an asset result. */
+type MediaUploadResultOperationInput = z.output<typeof createAssetSchema> | z.output<typeof DirectUploadOperationInputSchema>;
+/** Every typed Media lifecycle error context. */
+type MediaOperationHookContext = MediaApiContext<z.output<typeof AssetListQuerySchema>, LibraryReadFacts> | MediaApiContext<z.output<typeof createAssetSchema>, AssetUploadFacts> | MediaApiContext<z.output<typeof UpdateAssetOperationInputSchema>, AssetUpdateFacts> | MediaApiContext<z.output<typeof AssetIdOperationInputSchema>, AssetDeleteFacts> | MediaApiContext<z.output<typeof FolderListOperationInputSchema>, LibraryReadFacts> | MediaApiContext<z.output<typeof createFolderSchema>, FolderCreateFacts> | MediaApiContext<z.output<typeof FolderIdOperationInputSchema>, FolderDeleteFacts> | MediaApiContext<z.output<typeof DirectUploadOperationInputSchema>, AssetUploadFacts> | MediaApiContext<z.output<typeof uploadTokenRequestSchema>, AssetUploadFacts> | MediaApiContext<z.output<typeof VercelBlobOperationInputSchema>, AssetUploadFacts>;
+/** Configuration hooks for the Media operation lifecycle. */
+interface MediaBackendHooks {
+    onBeforeUpload?: (meta: {
+        filename: string;
+        mimeType: string;
+        size?: number;
+    }, context: MediaApiContext<MediaUploadOperationInput, AssetUploadFacts>) => Promise<void> | void;
+    onAfterUpload?: (asset: DeepReadonly<SerializedAsset>, context: MediaApiResultContext<MediaUploadResultOperationInput, AssetUploadFacts, SerializedAsset>) => Promise<void> | void;
+    onBeforeDeleteAsset?: (asset: DeepReadonly<SerializedAsset>, context: MediaApiContext<z.output<typeof AssetIdOperationInputSchema>, AssetDeleteFacts>) => Promise<void> | void;
+    onAfterDeleteAsset?: (assetId: string, context: MediaApiResultContext<z.output<typeof AssetIdOperationInputSchema>, AssetDeleteFacts, {
+        readonly success: true;
+    }>) => Promise<void> | void;
+    onBeforeListAssets?: (filter: z.output<typeof AssetListQuerySchema>, context: MediaApiContext<z.output<typeof AssetListQuerySchema>, LibraryReadFacts>) => Promise<void> | void;
+    onBeforeUpdateAsset?: (asset: DeepReadonly<SerializedAsset>, updates: z.output<typeof updateAssetSchema>, context: MediaApiContext<z.output<typeof UpdateAssetOperationInputSchema>, AssetUpdateFacts>) => Promise<void> | void;
+    onBeforeListFolders?: (filter: {
+        parentId?: string | null;
+    }, context: MediaApiContext<z.output<typeof FolderListOperationInputSchema>, LibraryReadFacts>) => Promise<void> | void;
+    onBeforeCreateFolder?: (input: z.output<typeof createFolderSchema>, context: MediaApiContext<z.output<typeof createFolderSchema>, FolderCreateFacts>) => Promise<void> | void;
+    onBeforeDeleteFolder?: (folder: DeepReadonly<SerializedFolder>, context: MediaApiContext<z.output<typeof FolderIdOperationInputSchema>, FolderDeleteFacts>) => Promise<void> | void;
+    /** Observes failures after authorization without replacing the original error. */
+    onError?: (error: Error, context: MediaOperationHookContext) => Promise<void> | void;
+}
+interface MediaResolverContext {
+    readonly input: unknown;
+    readonly request?: Request;
+    readonly headers?: Headers;
+    readonly body?: unknown;
+    readonly params?: unknown;
+    readonly query?: unknown;
+}
+/** Server-only dependencies and lifecycle configuration for Media operations. */
+interface MediaOperationsConfig {
+    /** Storage provider used for upload initialization, storage effects, and cleanup. */
+    storageAdapter: StorageAdapter;
+    /** Maximum accepted upload size in bytes. */
+    maxFileSizeBytes?: number;
+    /** Optional exact or wildcard MIME allowlist. */
+    allowedMimeTypes?: string[];
+    /** Trusted public URL prefixes accepted during asset finalization. */
+    allowedUrlPrefixes?: string[];
+    /** Post-authorization Media domain lifecycle hooks. */
+    hooks?: MediaBackendHooks;
+    /** Resolve server-only collection scope from validated input/request context. */
+    resolveTenantId?: (context: MediaResolverContext) => Promise<string | null | undefined> | string | null | undefined;
+}
+
+/** Configuration for the Media backend plugin. */
+interface MediaBackendConfig {
+    /** Storage implementation used for upload initialization, writes, and cleanup. */
+    storageAdapter: StorageAdapter;
+    /** Maximum accepted upload size. @default 10485760 */
+    maxFileSizeBytes?: number;
+    /** Optional MIME allowlist, including wildcard forms such as `image/*`. */
+    allowedMimeTypes?: string[];
+    /** Trusted URL prefixes accepted by asset finalization/registration. */
+    allowedUrlPrefixes?: string[];
+    /** Post-authorization domain lifecycle hooks. */
+    hooks?: MediaBackendHooks;
+    /**
+     * Server-only collection scope resolver. Its result is never accepted from a
+     * browser and remains separate from boolean authorization rules.
+     */
+    resolveTenantId?: MediaOperationsConfig["resolveTenantId"];
+}
+/** Raw route key exposed only on `stack.raw.media`. */
+type MediaRouteKey = "library";
+interface MediaPrefetchForRoute {
+    (key: "library", queryClient: QueryClient, endpoint: MediaEndpointPartition): Promise<void>;
+}
+/** Media backend plugin backed by one operation inventory. */
+declare const mediaBackendPlugin: (config: MediaBackendConfig) => _btst_stack_plugins_api.BackendPlugin<{
+    readonly listAssets: better_call.StrictEndpoint<"/media/assets", {
+        requireRequest: true;
+    } & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            folderId?: string | undefined;
+            mimeType?: string | undefined;
+            query?: string | undefined;
+            offset?: unknown;
+            limit?: unknown;
+        }, {
+            folderId?: string | undefined;
+            mimeType?: string | undefined;
+            query?: string | undefined;
+            offset?: unknown;
+            limit?: unknown;
+        }>;
+    }, {
+        readonly items: readonly {
+            readonly createdAt: string;
+            readonly folderId?: string | undefined;
+            readonly mimeType: string;
+            readonly id: string;
+            readonly tenantId?: string | null | undefined;
+            readonly filename: string;
+            readonly originalName: string;
+            readonly size: number;
+            readonly url: string;
+            readonly alt?: string | undefined;
+        }[];
+        readonly total: number;
+        readonly limit?: number | undefined;
+        readonly offset?: number | undefined;
+    }>;
+    readonly createAsset: better_call.StrictEndpoint<"/media/assets", {
+        requireRequest: true;
+    } & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<{
+            filename: string;
+            originalName: string;
+            mimeType: string;
+            size: number;
+            url: string;
+            folderId?: string | undefined;
+            alt?: string | undefined;
+        }, {
+            filename: string;
+            originalName: string;
+            mimeType: string;
+            size: number;
+            url: string;
+            folderId?: string | undefined;
+            alt?: string | undefined;
+        }>;
+    }, {
+        readonly createdAt: string;
+        readonly folderId?: string | undefined;
+        readonly mimeType: string;
+        readonly id: string;
+        readonly tenantId?: string | null | undefined;
+        readonly filename: string;
+        readonly originalName: string;
+        readonly size: number;
+        readonly url: string;
+        readonly alt?: string | undefined;
+    }>;
+    readonly updateAsset: better_call.StrictEndpoint<"/media/assets/:id", {
+        requireRequest: true;
+    } & {
+        method: "PATCH";
+        body: better_call.StandardSchemaV1<{
+            alt?: string | undefined;
+            folderId?: string | null | undefined;
+        }, {
+            alt?: string | undefined;
+            folderId?: string | null | undefined;
+        }>;
+    }, {
+        readonly createdAt: string;
+        readonly folderId?: string | undefined;
+        readonly mimeType: string;
+        readonly id: string;
+        readonly tenantId?: string | null | undefined;
+        readonly filename: string;
+        readonly originalName: string;
+        readonly size: number;
+        readonly url: string;
+        readonly alt?: string | undefined;
+    }>;
+    readonly deleteAsset: better_call.StrictEndpoint<"/media/assets/:id", {
+        requireRequest: true;
+    } & {
+        method: "DELETE";
+        body: better_call.StandardSchemaV1<unknown, unknown>;
+    }, {
+        readonly success: true;
+    }>;
+    readonly listFolders: better_call.StrictEndpoint<"/media/folders", {
+        requireRequest: true;
+    } & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            parentId: string | null | undefined;
+        } | {
+            parentId?: string | undefined;
+        }, {
+            parentId: string | null | undefined;
+        } | {
+            parentId?: string | undefined;
+        }>;
+    }, readonly {
+        readonly createdAt: string;
+        readonly id: string;
+        readonly parentId?: string | undefined;
+        readonly tenantId?: string | null | undefined;
+        readonly name: string;
+    }[]>;
+    readonly createFolder: better_call.StrictEndpoint<"/media/folders", {
+        requireRequest: true;
+    } & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<{
+            name: string;
+            parentId?: string | undefined;
+        }, {
+            name: string;
+            parentId?: string | undefined;
+        }>;
+    }, {
+        readonly createdAt: string;
+        readonly id: string;
+        readonly parentId?: string | undefined;
+        readonly tenantId?: string | null | undefined;
+        readonly name: string;
+    }>;
+    readonly deleteFolder: better_call.StrictEndpoint<"/media/folders/:id", {
+        requireRequest: true;
+    } & {
+        method: "DELETE";
+        body: better_call.StandardSchemaV1<unknown, unknown>;
+    }, {
+        readonly success: true;
+    }>;
+    readonly uploadDirect: better_call.StrictEndpoint<"/media/upload", {
+        metadata: {
+            allowedMediaTypes: string[];
+        };
+        requireRequest: true;
+    } & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<unknown, unknown>;
+    }, {
+        readonly createdAt: string;
+        readonly folderId?: string | undefined;
+        readonly mimeType: string;
+        readonly id: string;
+        readonly tenantId?: string | null | undefined;
+        readonly filename: string;
+        readonly originalName: string;
+        readonly size: number;
+        readonly url: string;
+        readonly alt?: string | undefined;
+    }>;
+    readonly uploadToken: better_call.StrictEndpoint<"/media/upload/token", {
+        requireRequest: true;
+    } & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<{
+            filename: string;
+            mimeType: string;
+            size: number;
+            folderId?: string | undefined;
+        }, {
+            filename: string;
+            mimeType: string;
+            size: number;
+            folderId?: string | undefined;
+        }>;
+    }, {
+        readonly type: "presigned-url";
+        readonly payload: {
+            readonly uploadUrl: string;
+            readonly publicUrl: string;
+            readonly key: string;
+            readonly method: "PUT";
+            readonly headers: {
+                readonly [x: string]: string;
+            };
+        };
+    }>;
+    readonly uploadVercelBlob: better_call.StrictEndpoint<"/media/upload/vercel-blob", {
+        requireRequest: true;
+    } & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<unknown, unknown>;
+    }, OperationData>;
+}, {
+    prefetchForRoute: MediaPrefetchForRoute;
+}, MediaOperations, "media">;
+type MediaApiRouter = ReturnType<ReturnType<typeof mediaBackendPlugin>["routes"]>;
+
+export { AssetIdOperationInputSchema as A, DirectUploadOperationInputSchema as D, FolderIdOperationInputSchema as F, UpdateAssetOperationInputSchema as U, VercelBlobOperationInputSchema as V, FolderListOperationInputSchema as c, MediaOperationError as d, mediaBackendPlugin as m };
+export type { MediaApiRouter as M, MediaBackendConfig as a, MediaRouteKey as b, MediaApiContext as e, MediaApiResultContext as f, MediaBackendHooks as g, MediaOperationHookContext as h, MediaOperations as i, MediaUploadOperationInput as j, MediaUploadResultOperationInput as k };

package/dist/shared/{stack.aqVZ6PEW.d.mts → stack.BRvqQWGt.d.cts}

@@ -1,5 +1,43 @@
+import { QueryClient } from '@tanstack/react-query';
 import { ComponentType } from 'react';
 
+/**
+ * Minimal structural view of a route returned by
+ * `createClientStack(...).router.getRoute(path)`. The framework entry
+ * factories only need these three fields.
+ */
+interface StackRouteLike {
+    PageComponent?: ComponentType<any> | undefined;
+    loader?: ((...args: any[]) => unknown) | undefined;
+    meta?: ((...args: any[]) => any) | undefined;
+}
+/**
+ * Minimal structural view of the object returned by `createClientStack`.
+ * Any concrete `ClientStack<TRoutes>` is assignable to this shape.
+ */
+interface StackClientLike {
+    router: {
+        getRoute: (path: string, queryParams?: Record<string, string | string[]>) => (StackRouteLike & Record<string, any>) | null | undefined;
+    };
+}
+/**
+ * Consumer-provided factory that returns the stack client for a given
+ * QueryClient (per-request on the server, singleton on the client).
+ */
+type GetStackClient = (queryClient: QueryClient) => StackClientLike;
+/**
+ * Consumer-provided resolver for lifecycle phases that can await request-aware
+ * stack client creation.
+ */
+type ResolveStackClient<TContext> = (queryClient: QueryClient, context: TContext) => StackClientLike | PromiseLike<StackClientLike>;
+/**
+ * A framework-agnostic BTST API handler, as returned by
+ * `createBackendHandler(...).handler`.
+ */
+type StackRequestHandler = (request: Request) => Response | Promise<Response>;
+
+/** Join a resolved site base path to an application route without `//`. */
+declare function joinBasePath(basePath: string, path: string): string;
 /**
  * Framework routing primitives shared by all plugins.
  *
@@ -64,4 +102,5 @@ interface StackApiConfig {
     basePath: string;
 }
 
-export type { StackRouterConfig as S, StackApiConfig as a, StackRouter as b };
+export { joinBasePath as j };
+export type { GetStackClient as G, ResolveStackClient as R, StackRequestHandler as S, StackRouterConfig as a, StackRouter as b, StackApiConfig as c, StackClientLike as d };

package/dist/shared/{stack.aqVZ6PEW.d.cts → stack.BRvqQWGt.d.mts}

@@ -1,5 +1,43 @@
+import { QueryClient } from '@tanstack/react-query';
 import { ComponentType } from 'react';
 
+/**
+ * Minimal structural view of a route returned by
+ * `createClientStack(...).router.getRoute(path)`. The framework entry
+ * factories only need these three fields.
+ */
+interface StackRouteLike {
+    PageComponent?: ComponentType<any> | undefined;
+    loader?: ((...args: any[]) => unknown) | undefined;
+    meta?: ((...args: any[]) => any) | undefined;
+}
+/**
+ * Minimal structural view of the object returned by `createClientStack`.
+ * Any concrete `ClientStack<TRoutes>` is assignable to this shape.
+ */
+interface StackClientLike {
+    router: {
+        getRoute: (path: string, queryParams?: Record<string, string | string[]>) => (StackRouteLike & Record<string, any>) | null | undefined;
+    };
+}
+/**
+ * Consumer-provided factory that returns the stack client for a given
+ * QueryClient (per-request on the server, singleton on the client).
+ */
+type GetStackClient = (queryClient: QueryClient) => StackClientLike;
+/**
+ * Consumer-provided resolver for lifecycle phases that can await request-aware
+ * stack client creation.
+ */
+type ResolveStackClient<TContext> = (queryClient: QueryClient, context: TContext) => StackClientLike | PromiseLike<StackClientLike>;
+/**
+ * A framework-agnostic BTST API handler, as returned by
+ * `createBackendHandler(...).handler`.
+ */
+type StackRequestHandler = (request: Request) => Response | Promise<Response>;
+
+/** Join a resolved site base path to an application route without `//`. */
+declare function joinBasePath(basePath: string, path: string): string;
 /**
  * Framework routing primitives shared by all plugins.
  *
@@ -64,4 +102,5 @@ interface StackApiConfig {
     basePath: string;
 }
 
-export type { StackRouterConfig as S, StackApiConfig as a, StackRouter as b };
+export { joinBasePath as j };
+export type { GetStackClient as G, ResolveStackClient as R, StackRequestHandler as S, StackRouterConfig as a, StackRouter as b, StackApiConfig as c, StackClientLike as d };

package/dist/shared/{stack.aqVZ6PEW.d.ts → stack.BRvqQWGt.d.ts}

@@ -1,5 +1,43 @@
+import { QueryClient } from '@tanstack/react-query';
 import { ComponentType } from 'react';
 
+/**
+ * Minimal structural view of a route returned by
+ * `createClientStack(...).router.getRoute(path)`. The framework entry
+ * factories only need these three fields.
+ */
+interface StackRouteLike {
+    PageComponent?: ComponentType<any> | undefined;
+    loader?: ((...args: any[]) => unknown) | undefined;
+    meta?: ((...args: any[]) => any) | undefined;
+}
+/**
+ * Minimal structural view of the object returned by `createClientStack`.
+ * Any concrete `ClientStack<TRoutes>` is assignable to this shape.
+ */
+interface StackClientLike {
+    router: {
+        getRoute: (path: string, queryParams?: Record<string, string | string[]>) => (StackRouteLike & Record<string, any>) | null | undefined;
+    };
+}
+/**
+ * Consumer-provided factory that returns the stack client for a given
+ * QueryClient (per-request on the server, singleton on the client).
+ */
+type GetStackClient = (queryClient: QueryClient) => StackClientLike;
+/**
+ * Consumer-provided resolver for lifecycle phases that can await request-aware
+ * stack client creation.
+ */
+type ResolveStackClient<TContext> = (queryClient: QueryClient, context: TContext) => StackClientLike | PromiseLike<StackClientLike>;
+/**
+ * A framework-agnostic BTST API handler, as returned by
+ * `createBackendHandler(...).handler`.
+ */
+type StackRequestHandler = (request: Request) => Response | Promise<Response>;
+
+/** Join a resolved site base path to an application route without `//`. */
+declare function joinBasePath(basePath: string, path: string): string;
 /**
  * Framework routing primitives shared by all plugins.
  *
@@ -64,4 +102,5 @@ interface StackApiConfig {
     basePath: string;
 }
 
-export type { StackRouterConfig as S, StackApiConfig as a, StackRouter as b };
+export { joinBasePath as j };
+export type { GetStackClient as G, ResolveStackClient as R, StackRequestHandler as S, StackRouterConfig as a, StackRouter as b, StackApiConfig as c, StackClientLike as d };

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

@@ -0,0 +1,23 @@
+import { AnyAuthorizationContract } from '../authorization/index.cjs';
+import { M as MaybePromise } from './stack.CKXzdGiJ.cjs';
+
+/** Schema-bound identity source accepted at a framework serialization seam. */
+interface FrameworkIdentitySource<TContract extends AnyAuthorizationContract, TContext> {
+    readonly contract: TContract;
+    getIdentity(context: TContext): MaybePromise<unknown>;
+}
+/** Schema-bound identity source for frameworks that expose request headers only. */
+interface HeadersFrameworkIdentitySource<TContract extends AnyAuthorizationContract> {
+    readonly contract: TContract;
+    getIdentityFromHeaders(context: {
+        headers: Headers;
+    }): MaybePromise<unknown>;
+}
+declare const initialIdentitySnapshot: unique symbol;
+/** A schema-validated, JSON-safe identity envelope produced on the server. */
+interface InitialIdentitySnapshot<TIdentity> {
+    readonly initialIdentity: TIdentity | null;
+    readonly [initialIdentitySnapshot]: true;
+}
+
+export type { FrameworkIdentitySource as F, HeadersFrameworkIdentitySource as H, InitialIdentitySnapshot as I };

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

@@ -0,0 +1,47 @@
+/**
+ * Shared auth contract types used by both the client provider
+ * (`@btst/stack/context`) and the backend (`@btst/stack/api`).
+ *
+ * This module is runtime-safe so it can be imported from server and client
+ * code alike without pulling in either implementation.
+ */
+/**
+ * The identity of the current user as resolved by an auth provider.
+ * Extra provider-specific fields are allowed.
+ */
+interface StackIdentity {
+    /** Unique user id */
+    id: string;
+    /** Display name */
+    name?: string;
+    /** Email address */
+    email?: string;
+    /** Avatar image URL */
+    image?: string;
+    /** Additional provider-specific fields */
+    [key: string]: unknown;
+}
+/**
+ * Browser authorization adapter accepted by `StackProvider`.
+ *
+ * Applications create this value with `createClientAuth()`. Permission checks
+ * use plugin-owned schema-backed descriptors; there is no open string callback.
+ */
+interface StackClientAuth {
+    readonly mode: "one-rule";
+    readonly contract: {
+        parseIdentity(identity: unknown): StackIdentity | null;
+    };
+    /** Resolve the current browser identity. */
+    getIdentity: () => Promise<StackIdentity | null> | StackIdentity | null;
+    /** Runtime hook used by descriptor-aware built-in plugin gates. */
+    readonly usePermission: (permission: unknown) => {
+        readonly can: boolean;
+        readonly isPending: boolean;
+        readonly error?: Error;
+    };
+    /** Optional login target used by descriptor-aware route gates. */
+    readonly loginPath?: string;
+}
+
+export type { StackClientAuth as S, StackIdentity as a };