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

package/src/plugins/ai-chat/query-keys.ts

@@ -4,8 +4,157 @@ import {
 	type ResourcesDeclaration,
 } from "@btst/stack/plugins/client";
 import type { AiChatApiRouter } from "./api/plugin";
+import type { StackIdentity } from "@btst/stack/context";
 import type { SerializedConversation, SerializedMessage } from "./types";
 
+/** Identity partition for protected AI Chat history caches. */
+export type AiChatIdentityPartition =
+	| Readonly<StackIdentity>
+	| "anonymous"
+	| `pending:${number}`
+	| `error:${number}`;
+
+const referenceObjectTokens = new WeakMap<object, number>();
+const referenceSymbolTokens = new WeakMap<symbol, number>();
+let nextIdentityReferenceToken = 0;
+
+function referenceObjectToken(value: object) {
+	let token = referenceObjectTokens.get(value);
+	if (token === undefined) {
+		token = ++nextIdentityReferenceToken;
+		referenceObjectTokens.set(value, token);
+	}
+	return token;
+}
+
+function referenceSymbolToken(value: symbol) {
+	const registeredKey = Symbol.keyFor(value);
+	if (registeredKey !== undefined) {
+		return `registered:${JSON.stringify(registeredKey)}`;
+	}
+	let token = referenceSymbolTokens.get(value);
+	if (token === undefined) {
+		token = ++nextIdentityReferenceToken;
+		referenceSymbolTokens.set(value, token);
+	}
+	return `local:${token}`;
+}
+
+function stableIdentityValue(
+	value: unknown,
+	seen: Map<object, number>,
+): string {
+	if (value === null) return "null";
+	switch (typeof value) {
+		case "string":
+			return `string:${JSON.stringify(value)}`;
+		case "number":
+			return `number:${Object.is(value, -0) ? "-0" : String(value)}`;
+		case "boolean":
+			return `boolean:${value}`;
+		case "bigint":
+			return `bigint:${value}`;
+		case "undefined":
+			return "undefined";
+		case "symbol":
+			return `symbol:${referenceSymbolToken(value)}`;
+		case "function":
+			return `function:${referenceObjectToken(value)}`;
+	}
+
+	const object = value as object;
+	const reference = seen.get(object);
+	if (reference !== undefined) return `reference:${reference}`;
+	seen.set(object, seen.size);
+	if (value instanceof Date) {
+		const timestamp = value.getTime();
+		return `date:${Number.isNaN(timestamp) ? "invalid" : value.toISOString()}`;
+	}
+	if (value instanceof RegExp) {
+		return `regexp:${JSON.stringify(value.source)}:${value.flags}`;
+	}
+	if (value instanceof Set) {
+		return `set:{${[...value]
+			.map((item) => stableIdentityValue(item, seen))
+			.sort()
+			.join(",")}}`;
+	}
+	if (value instanceof Map) {
+		return `map:{${[...value]
+			.map(
+				([key, item]) =>
+					`${stableIdentityValue(key, seen)}=>${stableIdentityValue(item, seen)}`,
+			)
+			.sort()
+			.join(",")}}`;
+	}
+	if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+		const bytes =
+			value instanceof ArrayBuffer
+				? new Uint8Array(value)
+				: new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+		return `bytes:${value.constructor.name}:${referenceObjectToken(value)}:${[
+			...bytes,
+		]
+			.map((byte) => byte.toString(16).padStart(2, "0"))
+			.join("")}`;
+	}
+	if (Array.isArray(value)) {
+		return `array:${value.length}:[${Array.from(
+			{ length: value.length },
+			(_, index) =>
+				index in value ? stableIdentityValue(value[index], seen) : "array-hole",
+		).join(",")}]`;
+	}
+	const prototype = Object.getPrototypeOf(value);
+	const kind =
+		prototype === Object.prototype || prototype === null
+			? "object"
+			: `object:${value.constructor?.name ?? "unknown"}:${referenceObjectToken(value)}`;
+	return `${kind}:{${Object.keys(value as Record<string, unknown>)
+		.sort()
+		.map(
+			(key) =>
+				`${JSON.stringify(key)}:${stableIdentityValue(
+					(value as Record<string, unknown>)[key],
+					seen,
+				)}`,
+		)
+		.join(",")}}`;
+}
+
+function identityFingerprint(identity: Readonly<StackIdentity>): string {
+	let input: string;
+	try {
+		input = stableIdentityValue(identity, new Map());
+	} catch {
+		// A consumer identity schema can allow values such as proxies or getters
+		// that cannot be inspected. Keep key construction total; the validated id
+		// remains the primary cache partition in this fallback.
+		input = `uninspectable-identity:${referenceObjectToken(identity)}`;
+	}
+	let left = 0x811c9dc5;
+	let right = 0x9e3779b9;
+	for (let index = 0; index < input.length; index++) {
+		const code = input.charCodeAt(index);
+		left = Math.imul(left ^ code, 0x01000193);
+		right = Math.imul(right ^ code, 0x85ebca6b);
+	}
+	return `${(left >>> 0).toString(16).padStart(8, "0")}${(right >>> 0)
+		.toString(16)
+		.padStart(8, "0")}`;
+}
+
+/** @internal Serializable marker that never embeds arbitrary identity metadata. */
+export function aiChatIdentityKey(identityPartition: AiChatIdentityPartition) {
+	return typeof identityPartition === "string"
+		? identityPartition
+		: {
+				id: identityPartition.id,
+				fingerprint: identityFingerprint(identityPartition),
+			};
+}
+
 export type ConversationWithMessages = SerializedConversation & {
 	messages: SerializedMessage[];
 };
@@ -26,15 +175,40 @@ export const aiChatResources = {
 		queries: {
 			list: {
 				path: "/chat/conversations",
-				key: () => ["all"],
-				select: (data: any): SerializedConversation[] => data ?? [],
+				key: (identityPartition?: AiChatIdentityPartition) =>
+					identityPartition === undefined
+						? ["all"]
+						: ["all", { identity: aiChatIdentityKey(identityPartition) }],
+				select: (
+					data: any,
+					_identityPartition?: AiChatIdentityPartition,
+				): SerializedConversation[] => data ?? [],
+				skip: (identityPartition?: AiChatIdentityPartition) =>
+					identityPartition !== undefined &&
+					typeof identityPartition === "string" &&
+					(identityPartition.startsWith("pending:") ||
+						identityPartition.startsWith("error:")),
 			},
 			detail: {
 				path: "/chat/conversations/:id",
-				params: (id: string) => ({ id }),
-				key: (id: string) => [id],
-				select: (data: any): ConversationWithMessages | null => data,
-				skip: (id: string) => !id,
+				params: (id: string, _identityPartition?: AiChatIdentityPartition) => ({
+					id,
+				}),
+				key: (id: string, identityPartition?: AiChatIdentityPartition) =>
+					identityPartition === undefined
+						? [id]
+						: [id, { identity: aiChatIdentityKey(identityPartition) }],
+				select: (
+					data: any,
+					_id?: string,
+					_identityPartition?: AiChatIdentityPartition,
+				): ConversationWithMessages | null => data,
+				skip: (id: string, identityPartition?: AiChatIdentityPartition) =>
+					!id ||
+					(identityPartition !== undefined &&
+						typeof identityPartition === "string" &&
+						(identityPartition.startsWith("pending:") ||
+							identityPartition.startsWith("error:"))),
 			},
 		},
 		mutations: {
@@ -43,7 +217,7 @@ export const aiChatResources = {
 				method: "POST" as const,
 				input: (input: CreateConversationInput) => ({ body: input }),
 				select: (data: any): SerializedConversation | null => data,
-				invalidates: ["conversations.list"],
+				refresh: false,
 			},
 			rename: {
 				path: "@put/chat/conversations/:id",
@@ -53,30 +227,14 @@ export const aiChatResources = {
 					body: { title: input.title },
 				}),
 				select: (data: any): SerializedConversation | null => data,
-				invalidates: ["conversations.list"],
-				setData: {
-					args: (result: SerializedConversation | null) =>
-						result?.id ? [result.id] : null,
-					updater: (
-						previous: unknown,
-						result: SerializedConversation | null,
-					) =>
-						previous && result
-							? { ...(previous as ConversationWithMessages), ...result }
-							: previous,
-				},
+				refresh: false,
 			},
 			delete: {
 				path: "@delete/chat/conversations/:id",
 				method: "DELETE" as const,
 				input: (input: { id: string }) => ({ params: { id: input.id } }),
 				select: (data: any): { success: boolean } => data,
-				invalidates: ["conversations.list"],
-				removeData: {
-					args: (_result: { success: boolean }, input: { id: string }) => [
-						input.id,
-					],
-				},
+				refresh: false,
 			},
 		},
 	},

package/src/plugins/ai-chat/types.ts

@@ -18,12 +18,14 @@ export type Message = {
 	createdAt: Date;
 };
 
-export interface SerializedConversation
-	extends Omit<Conversation, "createdAt" | "updatedAt"> {
+export type SerializedConversation = Omit<
+	Conversation,
+	"createdAt" | "updatedAt"
+> & {
 	createdAt: string;
 	updatedAt: string;
-}
+};
 
-export interface SerializedMessage extends Omit<Message, "createdAt"> {
+export type SerializedMessage = Omit<Message, "createdAt"> & {
 	createdAt: string;
-}
+};

package/src/plugins/api/create-endpoint.ts

@@ -1,4 +1,5 @@
 import { APIError, createEndpoint as baseCreateEndpoint } from "better-call";
+import { bindRouteOperationEndpoint } from "./operation";
 
 /**
  * Validation issue segment shapes produced by standard-schema validators
@@ -17,7 +18,10 @@ export interface SerializedValidationIssue {
 	path: Array<string | number>;
 }
 
-function serializeIssues(issues: unknown): SerializedValidationIssue[] {
+/** @internal Convert standard-schema/Zod issues to the stable HTTP shape. */
+export function serializeValidationIssues(
+	issues: unknown,
+): SerializedValidationIssue[] {
 	if (!Array.isArray(issues)) return [];
 	return (issues as StandardIssue[])
 		.filter((issue) => typeof issue?.message === "string")
@@ -33,6 +37,28 @@ function serializeIssues(issues: unknown): SerializedValidationIssue[] {
 		}));
 }
 
+function withValidationIssues(options: any): any {
+	if (!options || typeof options !== "object" || options.onValidationError) {
+		return options;
+	}
+	return {
+		...options,
+		onValidationError: ({
+			message,
+			issues,
+		}: {
+			message: string;
+			issues: unknown;
+		}) => {
+			throw new APIError(400, {
+				message,
+				code: "VALIDATION_ERROR",
+				issues: serializeValidationIssues(issues),
+			});
+		},
+	};
+}
+
 /**
  * Drop-in replacement for better-call's `createEndpoint` that preserves
  * Zod field-level validation issues in error responses.
@@ -54,29 +80,21 @@ export const createEndpoint = ((
 	const isPathForm = typeof pathOrOptions === "string";
 	const options = isPathForm ? handlerOrOptions : pathOrOptions;
 
-	const wrappedOptions =
-		options && typeof options === "object" && !options.onValidationError
-			? {
-					...options,
-					onValidationError: ({
-						message,
-						issues,
-					}: {
-						message: string;
-						issues: unknown;
-					}) => {
-						throw new APIError(400, {
-							message,
-							code: "VALIDATION_ERROR",
-							issues: serializeIssues(issues),
-						});
-					},
-				}
-			: options;
+	const wrappedOptions = withValidationIssues(options);
 
-	return isPathForm
+	const handler = isPathForm ? handlerOrNever : handlerOrOptions;
+	const endpoint = isPathForm
 		? baseCreateEndpoint(pathOrOptions, wrappedOptions, handlerOrNever)
 		: baseCreateEndpoint(wrappedOptions, handlerOrOptions);
+	return bindRouteOperationEndpoint(endpoint, handler);
 }) as typeof baseCreateEndpoint;
 
-createEndpoint.create = baseCreateEndpoint.create;
+createEndpoint.create = ((factoryOptions?: any) => {
+	const create = baseCreateEndpoint.create(factoryOptions);
+	return (path: any, options: any, handler: any) => {
+		return bindRouteOperationEndpoint(
+			create(path, withValidationIssues(options), handler),
+			handler,
+		);
+	};
+}) as typeof baseCreateEndpoint.create;

package/src/plugins/api/endpoint-inventory.ts

@@ -0,0 +1,206 @@
+import type { Endpoint } from "better-call";
+import {
+	getRouteEndpointOperationBinding,
+	type AnyOperation,
+	type OperationRecord,
+} from "./operation";
+
+/** A true infrastructure route that intentionally bypasses business operations. */
+export 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. */
+export type InfrastructureRouteInventory = Readonly<
+	Record<string, InfrastructureRouteDeclaration>
+>;
+
+/** Safe authorization metadata for one composed HTTP endpoint. */
+export 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;
+}
+
+type RuntimeEndpoint = Endpoint & {
+	readonly path?: unknown;
+	readonly options?: { readonly method?: unknown };
+};
+
+function endpointIdentity(endpoint: Endpoint): {
+	method: string;
+	path: string;
+} {
+	const runtimeEndpoint = endpoint as RuntimeEndpoint;
+	const method = runtimeEndpoint.options?.method;
+	return {
+		method: Array.isArray(method)
+			? method.map(String).join("|").toUpperCase()
+			: String(method ?? "GET").toUpperCase(),
+		path:
+			typeof runtimeEndpoint.path === "string"
+				? runtimeEndpoint.path
+				: "<unknown-path>",
+	};
+}
+
+function operationInventoryEntry(
+	pluginKey: string,
+	pluginName: string,
+	routeKey: string,
+	endpoint: Endpoint,
+	operation: AnyOperation,
+): ComposedEndpointInventoryEntry {
+	const identity = endpointIdentity(endpoint);
+	if (operation.access === "public") {
+		return Object.freeze({
+			pluginKey,
+			pluginName,
+			routeKey,
+			...identity,
+			source: "operation" as const,
+			access: "public" as const,
+		});
+	}
+	const permissionId = operation.permission?.id;
+	if (typeof permissionId !== "string" || permissionId.length === 0) {
+		throw new TypeError(
+			`[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) has no stable permission id.`,
+		);
+	}
+	return Object.freeze({
+		pluginKey,
+		pluginName,
+		routeKey,
+		...identity,
+		source: "operation" as const,
+		access: "permission" as const,
+		permissionId,
+	});
+}
+
+/** @internal Validate one plugin's routes and return their safe inventory. */
+export function composeEndpointInventory(
+	pluginKey: string,
+	pluginName: string,
+	routes: Record<string, Endpoint>,
+	operations: OperationRecord,
+	requireCompleteInventory: boolean,
+	infrastructureRoutes?: InfrastructureRouteInventory,
+	operationRouteMap?: Readonly<Record<string, string>>,
+): readonly ComposedEndpointInventoryEntry[] {
+	const strictInventory =
+		requireCompleteInventory ||
+		infrastructureRoutes !== undefined ||
+		operationRouteMap !== undefined;
+	if (!strictInventory) return [];
+
+	const infrastructure = infrastructureRoutes ?? {};
+	const routeMap = operationRouteMap ?? {};
+	for (const routeKey of Object.keys(routeMap).sort()) {
+		if (!Object.hasOwn(routes, routeKey)) {
+			throw new TypeError(
+				`[btst/endpoint-inventory] Plugin "${pluginKey}" operation route mapping "${routeKey}" has no composed endpoint.`,
+			);
+		}
+		const operationKey = routeMap[routeKey];
+		if (
+			typeof operationKey !== "string" ||
+			operationKey.length === 0 ||
+			!Object.hasOwn(operations, operationKey)
+		) {
+			throw new TypeError(
+				`[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" maps to unknown operation "${String(operationKey)}".`,
+			);
+		}
+	}
+	for (const routeKey of Object.keys(infrastructure).sort()) {
+		if (!Object.hasOwn(routes, routeKey)) {
+			throw new TypeError(
+				`[btst/endpoint-inventory] Plugin "${pluginKey}" infrastructure route "${routeKey}" has no composed endpoint.`,
+			);
+		}
+		const declaration = infrastructure[routeKey];
+		if (
+			declaration?.access !== "public" ||
+			typeof declaration.rationale !== "string" ||
+			declaration.rationale.trim().length === 0
+		) {
+			throw new TypeError(
+				`[btst/endpoint-inventory] Plugin "${pluginKey}" infrastructure route "${routeKey}" must declare public access and a rationale.`,
+			);
+		}
+	}
+
+	return Object.freeze(
+		Object.entries(routes).map(([routeKey, endpoint]) => {
+			const operationKey = Object.hasOwn(routeMap, routeKey)
+				? routeMap[routeKey]
+				: routeKey;
+			const operation =
+				typeof operationKey === "string" &&
+				Object.hasOwn(operations, operationKey)
+					? operations[operationKey]
+					: undefined;
+			const infrastructureDeclaration = Object.hasOwn(infrastructure, routeKey)
+				? infrastructure[routeKey]
+				: undefined;
+			const identity = endpointIdentity(endpoint);
+			const binding = getRouteEndpointOperationBinding(endpoint);
+			if (operation && infrastructureDeclaration) {
+				throw new TypeError(
+					`[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) cannot be both operation-backed and infrastructure.`,
+				);
+			}
+			if (operation) {
+				if (binding === undefined) {
+					throw new TypeError(
+						`[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) must use an operations.${operationKey}.route(ctx => input) handler.`,
+					);
+				}
+				if (
+					binding.pluginKey !== pluginKey ||
+					binding.operationKey !== operationKey ||
+					binding.operation !== operation
+				) {
+					throw new TypeError(
+						`[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) maps to operation "${operationKey}" but is bound to "${binding.pluginKey}.${binding.operationKey}".`,
+					);
+				}
+				return operationInventoryEntry(
+					pluginKey,
+					pluginName,
+					routeKey,
+					endpoint,
+					operation,
+				);
+			}
+			if (infrastructureDeclaration) {
+				if (binding !== undefined) {
+					throw new TypeError(
+						`[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) cannot be both operation-backed and infrastructure.`,
+					);
+				}
+				return Object.freeze({
+					pluginKey,
+					pluginName,
+					routeKey,
+					...identity,
+					source: "infrastructure" as const,
+					access: "public" as const,
+				});
+			}
+			throw new TypeError(
+				`[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) has no same-key operation or infrastructure declaration.`,
+			);
+		}),
+	);
+}

package/src/plugins/api/index.ts

@@ -13,6 +13,13 @@
 import type { BackendPlugin } from "../../types";
 import type { Endpoint } from "better-call";
 
+type IdentifiedBackendPlugin<
+	TId extends string,
+	TRoutes extends Record<string, Endpoint>,
+	TRaw extends Record<string, (...args: any[]) => any>,
+	TOperations extends import("./operation").OperationRecord,
+> = BackendPlugin<TRoutes, TRaw, TOperations, TId>;
+
 export type {
 	BackendPlugin,
 	ClientPlugin,
@@ -30,7 +37,30 @@ export { createRouter } from "better-call";
 // Wrapped createEndpoint that preserves Zod validation issues in 400 responses
 export { createEndpoint } from "./create-endpoint";
 export type { SerializedValidationIssue } from "./create-endpoint";
+export type {
+	ComposedEndpointInventoryEntry,
+	InfrastructureRouteDeclaration,
+	InfrastructureRouteInventory,
+} from "./endpoint-inventory";
 export { createDbPlugin } from "@btst/db";
+export {
+	defineOperation,
+	definePassthroughOperation,
+	type AnyOperation,
+	type DeepReadonly,
+	type Operation,
+	type OperationAccess,
+	type OperationApi,
+	type OperationContext,
+	type OperationData,
+	type OperationErrorContext,
+	OperationHttpError,
+	type OperationPermissionRequest,
+	type OperationRecord,
+	type OperationResultMode,
+	type RouteOperation,
+	type RouteOperationApi,
+} from "./operation";
 
 /**
  * Helper to define a backend plugin with full type inference
@@ -38,7 +68,7 @@ export { createDbPlugin } from "@btst/db";
  * @example
  * ```ts
  * const messagesPlugin = defineBackendPlugin({
- *   name: "messages",
+ *   id: "messages",
  *   dbPlugin: createDbPlugin("messages", messagesSchema),
  *   routes: (adapter) => ({
  *     list: endpoint("/messages", { method: "GET" }, async () => { ... }),
@@ -49,11 +79,15 @@ export { createDbPlugin } from "@btst/db";
  * ```
  *
  * @template TRoutes - The exact shape of routes (auto-inferred from routes function)
- * @template TApi - The shape of the server-side api surface (auto-inferred from api factory)
+ * @template TRaw - The narrow lower-level server surface (auto-inferred from the raw factory)
  */
 export function defineBackendPlugin<
+	const TId extends string,
 	TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>,
-	TApi extends Record<string, (...args: any[]) => any> = never,
->(plugin: BackendPlugin<TRoutes, TApi>): BackendPlugin<TRoutes, TApi> {
+	TRaw extends Record<string, (...args: any[]) => any> = never,
+	TOperations extends import("./operation").OperationRecord = never,
+>(
+	plugin: IdentifiedBackendPlugin<TId, TRoutes, TRaw, TOperations>,
+): IdentifiedBackendPlugin<TId, TRoutes, TRaw, TOperations> {
 	return plugin;
 }