theokit 0.48.13 → 0.50.0

package/dist/server/define/index.d.ts

@@ -1,65 +1,16 @@
+import { R as RouteConfig } from '../../route-config-Cm_ZMA1C.js';
 import { z } from 'zod';
 import { W as WebSocketHandler, b as WebSocketLike } from '../../define-websocket-DzPn1sR6.js';
 export { a as WebSocketHandlerWeb } from '../../define-websocket-DzPn1sR6.js';
 import { b as ToolTransform, C as CustomTool } from '../../define-agent-tool-cRuSpidb.js';
 export { D as DefineAgentToolSpec, T as ToolContextMessage, a as ToolHandlerContext, c as applyTransform } from '../../define-agent-tool-cRuSpidb.js';
-import { f as OnRequestHook, i as PreHandlerHook, g as OnResponseHook, O as OnErrorHook, T as TheoPlugin } from '../../plugin-types-D69-lJZ9.js';
+import { R as RoutePolicy } from '../../route-policy-BxOycCDq.js';
+export { A as AccessDecision, b as RoutePolicyInput, a as RouteSubject, e as evaluateRoutePolicy, r as requireOwner, s as subjectFromContext } from '../../route-policy-BxOycCDq.js';
+import { c as OnRequestHook, f as PreHandlerHook, d as OnResponseHook, O as OnErrorHook, T as TheoPlugin } from '../../plugin-types-BUVfUQ0V.js';
 import { WireChunk } from '@theokit/presenter/wire';
 import { IncomingMessage } from 'node:http';
 export { H as HEALTH_PATH, a as HealthRouteConfig, b as READY_PATH, c as ReadyRouteConfig, d as ReservedResponse, R as ReservedRoutes, e as defineHealthRoute, f as defineReadyRoute, s as serveReservedRoute } from '../../health-route-C0hk64_U.js';
 
-/**
- * core/contracts/route-config.ts
- *
- * Canonical home for `RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>` —
- * the contract shape consumed by `defineRoute()` (server) and
- * `defineCachedRoute()` (cache).
- *
- * Moved here in T2.2 of architecture-cleanup so `cache → core/contracts`
- * is the legal edge (replacing the prior `cache → server` violation).
- *
- * GAP-4 (plan v1.1): the 5-arity generic shape `<TQuery, TBody, TParams, TCtx, TResponse>`
- * MUST be preserved byte-by-byte. Type tests assert this in
- * `tests/unit/route-config-generic-arity.test.ts`.
- */
-
-interface RouteConfig<TQuery extends z.ZodType = z.ZodUndefined, TBody extends z.ZodType = z.ZodUndefined, TParams extends z.ZodType = z.ZodUndefined, TCtx = unknown, TResponse = unknown> {
-    query?: TQuery;
-    body?: TBody;
-    params?: TParams;
-    status?: number;
-    /**
-     * Optional Zod schema for the handler's plain-object return value. When
-     * present, BOTH runtimes (Node `executeRoute` + Web `executeWebRequest`)
-     * validate the handler's plain-object return against it BEFORE serializing.
-     *
-     * A mismatch is a SERVER fault (the handler violated its own declared
-     * contract) → 500 `INTERNAL_SERVER_ERROR`, distinct from the 400 used for
-     * input (`query`/`body`/`params`) validation failures.
-     *
-     * `Response`-instance returns (and `undefined`/`null` → 204) are NOT
-     * validated. This is a plain optional field — runtime validation only; the
-     * handler return type is NOT statically inferred from `response` (YAGNI).
-     */
-    response?: z.ZodType;
-    /**
-     * Opt out of CSRF enforcement for this route. Use for endpoints that
-     * legitimately receive third-party POSTs (Stripe webhooks, GitHub
-     * webhooks, OAuth callbacks). Defaults to enforced per `config.security.csrf`.
-     *
-     * Setting `csrf: false` only disables the per-route check — it does NOT
-     * disable the global mode setting for other routes.
-     */
-    csrf?: false;
-    handler: (ctx: {
-        query: z.infer<TQuery>;
-        body: z.infer<TBody>;
-        params: z.infer<TParams>;
-        request: Request;
-        ctx: TCtx;
-    }) => TResponse | Promise<TResponse>;
-}
-
 /**
  * Action wire-protocol accept mode per plan g3-server-actions-and-useaction
  * v1.2 ADR D1. Default behavior (when omitted) is `'json'`. `'form'` opts the
@@ -95,7 +46,31 @@ interface ActionConfig<TInput extends z.ZodType, TCtx = unknown> {
     }) => unknown;
 }
 
-type MiddlewareHandler = (request: Request, next: (request: Request) => Promise<Response>) => Response | Promise<Response>;
+/**
+ * A middleware, as the framework's own builder produces it (usetheokit/theokit#345).
+ *
+ * `(request, context)`: read the request as a Web `Request`, decorate `context` for the route that
+ * follows, and RETURN a `Response` to answer the request yourself. Returning nothing continues to
+ * the next middleware, and then to the route.
+ *
+ * ## Why not `(request, next) => Response`
+ *
+ * That was this type's first shape, and it described a continuation pipeline nothing in this
+ * repository implements: the file-scan runner runs BEFORE routing, so it has no downstream
+ * `Response` to hand back from `next(request)`. The consequence was measured rather than
+ * theorised — `MiddlewareHandler` had **zero runtime consumers**, while `README.md` documented the
+ * builder that produces it as the way to write middleware. A published builder whose output nothing
+ * can call is worse than a missing one, because it reads as supported.
+ *
+ * This shape is the one that fits the model AND already runs: `executeWebRequest` has invoked
+ * `(request, context) => Response | void` since T3.2 (`http/web-middleware-runner.ts`). Adopting it
+ * here converges two of the three middleware contracts instead of adding a fourth.
+ *
+ * The Express-style `(req, res, next)` export keeps working in `server/middleware/*.ts`. It is
+ * Node-bound — which is why it cannot be the framework's contract — but evicting it would break
+ * every app that has one.
+ */
+type MiddlewareHandler = (request: Request, context: Record<string, unknown>) => Response | undefined | void | Promise<Response | undefined | void>;
 
 /**
  * M31 Phase 3 — `route()`, the fluent builder that replaces `defineRoute({...})`.
@@ -133,6 +108,16 @@ interface RouteBuilder<TQuery extends z.ZodType = z.ZodUndefined, TBody extends
     status(code: number): RouteBuilder<TQuery, TBody, TParams, TCtx, TResponse, THandlerSet>;
     /** Opt out of CSRF enforcement for this route (webhooks / OAuth callbacks). */
     csrf(disabled: false): RouteBuilder<TQuery, TBody, TParams, TCtx, TResponse, THandlerSet>;
+    /**
+     * Declare who may call this route (ADR 0001). Required — the scanner refuses a
+     * route file whose HTTP export declares no policy, and `'public'` is a
+     * declaration rather than a default.
+     *
+     * The policy is evaluated by the Node executor, the Web executor and
+     * `callProcedure` from one implementation, so a browser, a desktop shell and a
+     * terminal all get the same answer.
+     */
+    policy(policy: RoutePolicy<z.infer<TQuery>, z.infer<TBody>, z.infer<TParams>>): RouteBuilder<TQuery, TBody, TParams, TCtx, TResponse, THandlerSet>;
     /**
      * Set the handler. Its `ctx` infers `query/body/params` from the schemas set above. Required
      * before `.build()`.
@@ -151,8 +136,9 @@ interface RouteBuilder<TQuery extends z.ZodType = z.ZodUndefined, TBody extends
     build(...guard: THandlerSet extends true ? [] : [error: MissingHandlerError]): RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>;
 }
 /**
- * Start a fluent route definition. Chain `.query/.body/.params/.response/.status/.csrf` (all
- * optional), then `.handler()` (required) and `.build()` for the `RouteConfig`.
+ * Start a fluent route definition. Chain `.query/.body/.params/.response/.status/.csrf`, declare
+ * `.policy()` (which the route scanner requires), then `.handler()` and `.build()` for the
+ * `RouteConfig`.
  */
 declare function route(): RouteBuilder;
 
@@ -342,6 +328,14 @@ declare function tool<TName extends string>(name: TName): ToolBuilder<TName>;
  *     .onRequest((ctx) => { ctx.ctx.requestId = crypto.randomUUID() })
  *     .onResponse((ctx) => { ctx.response.setHeader('x-request-id', String(ctx.ctx.requestId)) })
  *     .build()
+ *
+ * `ctx.request` is a Web `Request`, so `ctx.request.url` is ABSOLUTE. Match a path through `URL`,
+ * never with `startsWith('/…')` — that comparison is false for every real request, and a hook that
+ * never matches looks exactly like one with nothing to say:
+ *
+ *   .onResponse((ctx) => {
+ *     if (new URL(ctx.request.url).pathname.startsWith('/api/')) { … }
+ *   })
  */
 
 /** The fluent plugin builder. `name` is set at entry; every hook is optional and may repeat. */
@@ -408,4 +402,4 @@ interface WebChannelHandler<TMessage = unknown> {
  */
 declare function defineWebChannel<TMessage = unknown>(handler: WebChannelHandler<TMessage>): WebChannelHandler<TMessage>;
 
-export { type ActionAccept, type ActionBuilder, type ActionConfig, type ChannelHandler, CustomTool, type MiddlewareBuilder, type MiddlewareHandler, type PluginBuilder, type RouteBuilder, type RouteConfig, type ToolBuilder, ToolTransform, type WebChannelHandler, type WebSocketBuilder, WebSocketHandler, WebSocketLike, action, defineChannel, defineWebChannel, middleware, plugin, route, tool, uiMessageStreamResponse, websocket };
+export { type ActionAccept, type ActionBuilder, type ActionConfig, type ChannelHandler, CustomTool, type MiddlewareBuilder, type MiddlewareHandler, type PluginBuilder, type RouteBuilder, RouteConfig, RoutePolicy, type ToolBuilder, ToolTransform, type WebChannelHandler, type WebSocketBuilder, WebSocketHandler, WebSocketLike, action, defineChannel, defineWebChannel, middleware, plugin, route, tool, uiMessageStreamResponse, websocket };

package/dist/server/define/index.js

@@ -8,7 +8,13 @@ import {
   tool,
   uiMessageStreamResponse,
   websocket
-} from "../../chunk-J5MXCGKA.js";
+} from "../../chunk-DHAD2O3S.js";
+import "../../chunk-D4VP2QPR.js";
+import {
+  evaluateRoutePolicy,
+  requireOwner,
+  subjectFromContext
+} from "../../chunk-YN4W7LCX.js";
 import {
   HEALTH_PATH,
   READY_PATH,
@@ -29,10 +35,13 @@ export {
   defineHealthRoute,
   defineReadyRoute,
   defineWebChannel,
+  evaluateRoutePolicy,
   middleware,
   plugin,
+  requireOwner,
   route,
   serveReservedRoute,
+  subjectFromContext,
   tool,
   uiMessageStreamResponse,
   websocket

package/dist/server/http/index.d.ts

@@ -1,11 +1,13 @@
-export { B as BATCH_PATH, a as BatchExecuteFn, b as BatchPathConflictError, c as BatchPayload, d as BatchRequestItem, e as BatchResponse, f as BatchResultItem, C as CookieOptions, g as CorsConfig, h as CorsHandler, i as CorsOrigin, j as CorsWebHandler, k as CustomErrorPages, E as ExecuteActionOptions, l as ExecuteRouteContext, H as HandleBatchOptions, M as MAX_ERROR_HTML_BYTES, m as MiddlewareResult, N as NotFoundError, S as STRIPPED_HEADERS, n as SendErrorInput, o as SendErrorOptions, T as TRACE_HEADER, p as TRACE_PARENT_HEADER, q as TheoError, _ as _resetMiddlewareCacheForTests, s as appendCookieToHeaders, t as appendDeleteCookieToHeaders, u as createCorsHandler, v as createCorsWebHandler, w as deleteCookie, x as envelopeCodeToStatus, y as executeAction, z as executeRoute, A as extractTraceId, D as extractTraceIdFromRequest, F as fromUnknown, G as getCookie, I as getCookieFromRequest, J as handleBatchRequest, K as handleRequestError, L as handleWebRequestError, P as loadCustomErrorPages, Q as matchesOrigin, R as parseCookieHeader, U as parseTraceparent, W as runMiddlewareAndContext, X as sendError, Y as sendJson, Z as serializeCookie, $ as serveStaticFile, a0 as serverErrorToEnvelope, a1 as setCookie } from '../../index-BEtEv6ZH.js';
+export { A as ActionError, b as ActionInputError, B as BATCH_PATH, e as BatchExecuteFn, f as BatchPathConflictError, g as BatchPayload, h as BatchRequestItem, i as BatchResponse, j as BatchResultItem, C as CookieOptions, l as CorsConfig, m as CorsHandler, n as CorsOrigin, o as CorsWebHandler, p as CustomErrorPages, E as ExecuteActionOptions, q as ExecuteRouteContext, F as FileTooLargeError, H as HandleBatchOptions, M as MAX_ERROR_HTML_BYTES, r as MiddlewareResult, N as NotFoundError, t as ProcedureInputError, u as ProcedureOutputError, S as STRIPPED_HEADERS, y as SendErrorInput, z as SendErrorOptions, T as TRACE_HEADER, G as TRACE_PARENT_HEADER, I as TheoError, W as W3CTraceContext, _ as _resetMiddlewareCacheForTests, L as appendCookieToHeaders, Q as appendDeleteCookieToHeaders, V as callProcedure, X as createCorsHandler, Y as createCorsWebHandler, Z as createOpenApiHandler, $ as createServerContext, a0 as deleteCookie, a1 as envelopeCodeToStatus, a2 as executeAction, a3 as executeRoute, a4 as executeWebRequest, a5 as extractTraceId, a6 as extractTraceIdFromRequest, a7 as extractUniversalIssues, a8 as extractW3CTraceContext, a9 as fromUnknown, aa as getCookie, ab as getCookieFromRequest, ac as handleBatchRequest, ad as handleRequestError, ae as handleWebRequestError, af as isActionError, ag as isInputError, ah as jsonTransformer, ai as loadCustomErrorPages, aj as matchesOrigin, ak as parseCookieHeader, al as parseRequestBody, am as parseTraceparent, an as parseTraceparentContext, ao as resolveTransformer, ap as runMiddlewareAndContext, aq as sendError, ar as sendJson, as as serializeCookie, at as serveStaticFile, au as serverErrorToEnvelope, av as setCookie, aw as superjsonTransformer, ax as validateRouteInput } from '../../index-CzxtQcnp.js';
 import '../../error-envelope-DG47lt8E.js';
 import 'node:http';
-import '../../plugin-types-D69-lJZ9.js';
-import '../../plugin-runner-BFEcgtmJ.js';
+import '../../plugin-types-BUVfUQ0V.js';
+import '../../plugin-runner-BVMOSxvb.js';
 import '../../job-backend-CgC8Xf33.js';
-import '../../match-CfbEFRG4.js';
+import '../../match-DmGgxjIU.js';
 import 'vite';
-import '../../csrf-BBrEZSBW.js';
+import '../../csrf-Dgot9qSM.js';
 import '../../audit-log-BQWM5YLG.js';
 import 'zod';
+import '../../route-config-Cm_ZMA1C.js';
+import '../../route-policy-BxOycCDq.js';

package/dist/server/http/index.js

@@ -1,34 +1,56 @@
 import {
   MAX_ERROR_HTML_BYTES,
+  ProcedureInputError,
+  ProcedureOutputError,
+  callProcedure,
+  createOpenApiHandler,
   loadCustomErrorPages,
   serveStaticFile
-} from "../../chunk-UW2TEAGR.js";
+} from "../../chunk-ULDCFL2O.js";
 import {
+  jsonTransformer,
+  resolveTransformer,
+  superjsonTransformer
+} from "../../chunk-OGLS76RN.js";
+import {
+  ActionError,
+  ActionInputError,
   BATCH_PATH,
   BatchPathConflictError,
   STRIPPED_HEADERS,
-  TRACE_HEADER,
-  TRACE_PARENT_HEADER,
   _resetMiddlewareCacheForTests,
   createCorsHandler,
   createCorsWebHandler,
+  createServerContext,
   executeAction,
   executeRoute,
-  extractTraceId,
-  extractTraceIdFromRequest,
+  executeWebRequest,
+  extractUniversalIssues,
   handleBatchRequest,
   handleRequestError,
   handleWebRequestError,
+  isActionError,
+  isInputError,
   matchesOrigin,
-  parseTraceparent,
   runMiddlewareAndContext,
   sendError,
-  sendJson
-} from "../../chunk-XALU5LCU.js";
+  sendJson,
+  validateRouteInput
+} from "../../chunk-RWNYIU6A.js";
 import "../../chunk-47FFT43U.js";
-import "../../chunk-KD5G3YXI.js";
-import "../../chunk-FB2HBNIC.js";
-import "../../chunk-OLGPYOLO.js";
+import {
+  FileTooLargeError,
+  TRACE_HEADER,
+  TRACE_PARENT_HEADER,
+  extractTraceId,
+  extractTraceIdFromRequest,
+  extractW3CTraceContext,
+  parseRequestBody,
+  parseTraceparent,
+  parseTraceparentContext
+} from "../../chunk-72DMJBXI.js";
+import "../../chunk-BX6EUYHU.js";
+import "../../chunk-P6OS7652.js";
 import "../../chunk-AVQU5CQF.js";
 import {
   envelopeCodeToStatus
@@ -49,12 +71,20 @@ import {
   serializeCookie,
   setCookie
 } from "../../chunk-4FWBKX6G.js";
+import "../../chunk-ZWN3AODA.js";
+import "../../chunk-D4VP2QPR.js";
+import "../../chunk-YN4W7LCX.js";
 import "../../chunk-XTHN6JBX.js";
 export {
+  ActionError,
+  ActionInputError,
   BATCH_PATH,
   BatchPathConflictError,
+  FileTooLargeError,
   MAX_ERROR_HTML_BYTES,
   NotFoundError,
+  ProcedureInputError,
+  ProcedureOutputError,
   STRIPPED_HEADERS,
   TRACE_HEADER,
   TRACE_PARENT_HEADER,
@@ -62,30 +92,44 @@ export {
   _resetMiddlewareCacheForTests,
   appendCookieToHeaders,
   appendDeleteCookieToHeaders,
+  callProcedure,
   createCorsHandler,
   createCorsWebHandler,
+  createOpenApiHandler,
+  createServerContext,
   deleteCookie,
   envelopeCodeToStatus,
   executeAction,
   executeRoute,
+  executeWebRequest,
   extractTraceId,
   extractTraceIdFromRequest,
+  extractUniversalIssues,
+  extractW3CTraceContext,
   fromUnknown,
   getCookie,
   getCookieFromRequest,
   handleBatchRequest,
   handleRequestError,
   handleWebRequestError,
+  isActionError,
+  isInputError,
+  jsonTransformer,
   loadCustomErrorPages,
   matchesOrigin,
   parseCookieHeader,
+  parseRequestBody,
   parseTraceparent,
+  parseTraceparentContext,
+  resolveTransformer,
   runMiddlewareAndContext,
   sendError,
   sendJson,
   serializeCookie,
   serveStaticFile,
   serverErrorToEnvelope,
-  setCookie
+  setCookie,
+  superjsonTransformer,
+  validateRouteInput
 };
 //# sourceMappingURL=index.js.map