@palbase/backend 23.0.0 → 23.1.0

package/dist/{registry-DY3d9l1k.d.ts → registry-B3niOVYp.d.ts}

@@ -1,12 +1,12 @@
-import { A as AuthSpec, R as RateLimitConfig } from './endpoint-BavvbW4P.js';
+import { A as AuthSpec, R as RateLimitConfig } from './endpoint-CVWXh6oG.js';
 import { ZodTypeAny } from 'zod';
 import { PalbaseBucketName } from './stack.js';
 
 /** A legacy method decorator (`experimentalDecorators`): `(prototype, name,
  * descriptor)`. */
-type MethodDecorator = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+type MethodDecorator$1 = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
 /** A legacy parameter decorator: `(prototype, name, paramIndex)`. */
-type ParameterDecorator = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
+type ParameterDecorator$1 = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
 /**
  * Direct-storage upload settings for an `@Upload` route. The br-pod validates an
  * authorize request against these (size/type), then mints a signed upload URL
@@ -51,7 +51,7 @@ interface UploadConfig {
  * // The size limit + MIME allowlist come from the "docs" bucket ON THE STACK
  * // — storage enforces them at the PUT.
  */
-declare function Upload(subpath: string, config: UploadConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator;
+declare function Upload(subpath: string, config: UploadConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator$1;
 /**
  * The uploaded object, injected into an `@Upload` method body by
  * `@UploadedObject()` once storage confirms the upload. Bytes are NOT present
@@ -106,7 +106,94 @@ interface UploadedObject {
  * Co-located with the {@link UploadedObject} TYPE so a single exported name
  * `UploadedObject` carries BOTH the decorator value and the type annotation.
  */
-declare function UploadedObject(): ParameterDecorator;
+declare function UploadedObject(): ParameterDecorator$1;
+
+/** A legacy method decorator (`experimentalDecorators`): `(prototype, name,
+ * descriptor)`. */
+type MethodDecorator = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/** A legacy parameter decorator: `(prototype, name, paramIndex)`. */
+type ParameterDecorator = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * Settings for an `@Sse` route.
+ *
+ * EMPTY in v1, and deliberately so: the pipeline keys off this object's
+ * PRESENCE, not its contents (see the file header). Declaring the type now means
+ * a later setting arrives as a field on an existing marker rather than as a
+ * second marker nothing downstream reads.
+ */
+interface SseConfig {
+    /**
+     * The shape of ONE frame — what a single `out.write(value)` carries.
+     *
+     * REQUIRED, not optional, and that is the whole point. An `@Sse` handler
+     * returns `Promise<void>`, so the codegen-injected `recordReturn` has no type
+     * to record and nothing downstream can infer what a frame is. A route without
+     * this declares a stream whose element type is unknown, and every generated
+     * client from that contract is opaque — which is precisely the failure
+     * `x-palbase-sse` exists to prevent. Making it optional would have left that
+     * failure one forgotten field away.
+     *
+     * Measured live on a real pushed stack (2026-08-29): the contract gate refused
+     * the deploy with "2 untyped response(s) — every generated client from it is
+     * opaque", naming both routes that omitted it.
+     */
+    frame: ZodTypeAny;
+}
+/**
+ * The writer injected by `@SseOut()`. Each `write` emits ONE SSE `data:` frame
+ * carrying `value` JSON-encoded.
+ *
+ * The FIRST `write` is load-bearing beyond its frame: it settles the request's
+ * database transaction. A streaming response may run for minutes, and the
+ * handler runs inside the request's transaction — holding one open for the life
+ * of a stream exhausts the connection pool, a failure invisible to a unit test
+ * that only dies under load. So the first frame is the point at which the
+ * request phase is declared over, and database access after it is refused by
+ * name rather than silently run against a settled transaction.
+ *
+ * The practical rule for a handler: do the database work BEFORE the first write.
+ */
+interface SseWriter {
+    write(value: unknown): void;
+}
+/**
+ * `@Sse(subpath, config)` — declare a streaming route.
+ *
+ * @example
+ * ＠Sse("/chat", { frame: ChatFrame })
+ * async chat(＠Body() b: ChatInput, ＠SseOut() out: SseWriter, ＠Signal() signal: AbortSignal) {
+ *   const stream = await openai.chat.completions.create(
+ *     { model: "gpt-5.6", messages: b.messages, stream: true },
+ *     { signal },
+ *   );
+ *   for await (const chunk of stream) out.write(chunk);
+ * }
+ * // The client disconnects → `signal` aborts → the provider stops being pulled.
+ * // The signal is a plain AbortSignal, so it goes wherever the provider takes
+ * // one: `{ signal }` for the OpenAI and Anthropic SDKs, `abortSignal:` for the
+ * // Vercel AI SDK, `fetch(url, { signal })` for a raw call.
+ */
+declare function Sse(subpath: string | undefined, config: SseConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator;
+/**
+ * `@SseOut()` — inject the frame writer (`: SseWriter`) into an `@Sse` method
+ * body. Only meaningful on an `@Sse` route.
+ */
+declare function SseOut(): ParameterDecorator;
+/**
+ * `@Signal()` — inject the request's `AbortSignal`, which enters the aborted
+ * state when the client disconnects.
+ *
+ * NOT derivable from `@Req()`: `PBRequest` carries only request-scoped data —
+ * the typed input, route/query params, headers, the authenticated user, calling
+ * client metadata, trace ids, and the declared error throwers — and no signal
+ * (endpoint.ts:358-363).
+ *
+ * Measured 2026-08-29 on Bun: an infinite producer guarded by this signal
+ * stopped four frames after the client was killed, and the handler's `finally`
+ * ran. It is the same mechanism a NestJS handler reaches through
+ * `req.on("close")`.
+ */
+declare function Signal(): ParameterDecorator;
 
 /** The HTTP verbs a route may declare, upper-cased (the runtime router +
  * OpenAPI lower-case on their own). */
@@ -123,11 +210,18 @@ interface RouteOptions {
      * openapi → codegen). The bytes go client→storage directly; the method body
      * runs as the completion handler. See {@link UploadConfig} (decorators/upload.ts). */
     uploadConfig?: UploadConfig;
+    /** Streaming config — present ONLY on `@Sse` routes (the `@Get`/`@Post`/…
+     * decorators never set it). Its presence is what MARKS a route as a streaming
+     * route through the whole pipeline (registry → flatten → openapi → codegen),
+     * exactly as `uploadConfig` does for uploads — never a special HTTP verb. An
+     * `@Sse` route registers POST like any input-bearing route, so the verb cannot
+     * carry the distinction. See {@link SseConfig} (decorators/sse.ts). */
+    sseConfig?: SseConfig;
 }
 /** The kind of value a parameter decorator injects. Drives both dispatch
  * (which request slice to inject) and codegen (which OpenAPI parameter source a
  * schema-bearing kind maps to). */
-type ParamKind = "body" | "query" | "param" | "headers" | "user" | "optionalUser" | "client" | "requestId" | "traceId" | "req" | "uploadedObject";
+type ParamKind = "body" | "query" | "param" | "headers" | "user" | "optionalUser" | "client" | "requestId" | "traceId" | "req" | "uploadedObject" | "sseOut" | "signal";
 /** One parameter decorator's recorded metadata. `index` is the parameter
  * position esbuild/tsc preserve; `schema` is present for the schema-bearing
  * kinds (`body`/`query`/`headers`); `name` is the path-param name for `param`. */
@@ -179,4 +273,4 @@ declare function recordThrows(target: object, fnName: string, throws: ThrowDescr
  */
 declare function getRoutes(ctor: object): RouteMeta[];
 
-export { type HttpMethodUpper as H, type ParamMeta as P, type RouteMeta as R, type ThrowDescriptor as T, type UploadConfig as U, type RouteOptions as a, type ParamKind as b, Upload as c, UploadedObject as d, getRoutes as g, recordThrows as r };
+export { type HttpMethodUpper as H, type ParamMeta as P, type RouteMeta as R, type SseConfig as S, type ThrowDescriptor as T, type UploadConfig as U, type RouteOptions as a, type ParamKind as b, Signal as c, Sse as d, SseOut as e, type SseWriter as f, Upload as g, UploadedObject as h, getRoutes as i, recordThrows as r };

package/dist/{registry-C3H2uPeZ.d.cts → registry-CqPK2Qby.d.cts}

@@ -1,12 +1,12 @@
-import { A as AuthSpec, R as RateLimitConfig } from './endpoint-i8TTCohk.cjs';
+import { A as AuthSpec, R as RateLimitConfig } from './endpoint-c9h5jriX.cjs';
 import { ZodTypeAny } from 'zod';
 import { PalbaseBucketName } from './stack.cjs';
 
 /** A legacy method decorator (`experimentalDecorators`): `(prototype, name,
  * descriptor)`. */
-type MethodDecorator = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+type MethodDecorator$1 = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
 /** A legacy parameter decorator: `(prototype, name, paramIndex)`. */
-type ParameterDecorator = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
+type ParameterDecorator$1 = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
 /**
  * Direct-storage upload settings for an `@Upload` route. The br-pod validates an
  * authorize request against these (size/type), then mints a signed upload URL
@@ -51,7 +51,7 @@ interface UploadConfig {
  * // The size limit + MIME allowlist come from the "docs" bucket ON THE STACK
  * // — storage enforces them at the PUT.
  */
-declare function Upload(subpath: string, config: UploadConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator;
+declare function Upload(subpath: string, config: UploadConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator$1;
 /**
  * The uploaded object, injected into an `@Upload` method body by
  * `@UploadedObject()` once storage confirms the upload. Bytes are NOT present
@@ -106,7 +106,94 @@ interface UploadedObject {
  * Co-located with the {@link UploadedObject} TYPE so a single exported name
  * `UploadedObject` carries BOTH the decorator value and the type annotation.
  */
-declare function UploadedObject(): ParameterDecorator;
+declare function UploadedObject(): ParameterDecorator$1;
+
+/** A legacy method decorator (`experimentalDecorators`): `(prototype, name,
+ * descriptor)`. */
+type MethodDecorator = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/** A legacy parameter decorator: `(prototype, name, paramIndex)`. */
+type ParameterDecorator = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * Settings for an `@Sse` route.
+ *
+ * EMPTY in v1, and deliberately so: the pipeline keys off this object's
+ * PRESENCE, not its contents (see the file header). Declaring the type now means
+ * a later setting arrives as a field on an existing marker rather than as a
+ * second marker nothing downstream reads.
+ */
+interface SseConfig {
+    /**
+     * The shape of ONE frame — what a single `out.write(value)` carries.
+     *
+     * REQUIRED, not optional, and that is the whole point. An `@Sse` handler
+     * returns `Promise<void>`, so the codegen-injected `recordReturn` has no type
+     * to record and nothing downstream can infer what a frame is. A route without
+     * this declares a stream whose element type is unknown, and every generated
+     * client from that contract is opaque — which is precisely the failure
+     * `x-palbase-sse` exists to prevent. Making it optional would have left that
+     * failure one forgotten field away.
+     *
+     * Measured live on a real pushed stack (2026-08-29): the contract gate refused
+     * the deploy with "2 untyped response(s) — every generated client from it is
+     * opaque", naming both routes that omitted it.
+     */
+    frame: ZodTypeAny;
+}
+/**
+ * The writer injected by `@SseOut()`. Each `write` emits ONE SSE `data:` frame
+ * carrying `value` JSON-encoded.
+ *
+ * The FIRST `write` is load-bearing beyond its frame: it settles the request's
+ * database transaction. A streaming response may run for minutes, and the
+ * handler runs inside the request's transaction — holding one open for the life
+ * of a stream exhausts the connection pool, a failure invisible to a unit test
+ * that only dies under load. So the first frame is the point at which the
+ * request phase is declared over, and database access after it is refused by
+ * name rather than silently run against a settled transaction.
+ *
+ * The practical rule for a handler: do the database work BEFORE the first write.
+ */
+interface SseWriter {
+    write(value: unknown): void;
+}
+/**
+ * `@Sse(subpath, config)` — declare a streaming route.
+ *
+ * @example
+ * ＠Sse("/chat", { frame: ChatFrame })
+ * async chat(＠Body() b: ChatInput, ＠SseOut() out: SseWriter, ＠Signal() signal: AbortSignal) {
+ *   const stream = await openai.chat.completions.create(
+ *     { model: "gpt-5.6", messages: b.messages, stream: true },
+ *     { signal },
+ *   );
+ *   for await (const chunk of stream) out.write(chunk);
+ * }
+ * // The client disconnects → `signal` aborts → the provider stops being pulled.
+ * // The signal is a plain AbortSignal, so it goes wherever the provider takes
+ * // one: `{ signal }` for the OpenAI and Anthropic SDKs, `abortSignal:` for the
+ * // Vercel AI SDK, `fetch(url, { signal })` for a raw call.
+ */
+declare function Sse(subpath: string | undefined, config: SseConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator;
+/**
+ * `@SseOut()` — inject the frame writer (`: SseWriter`) into an `@Sse` method
+ * body. Only meaningful on an `@Sse` route.
+ */
+declare function SseOut(): ParameterDecorator;
+/**
+ * `@Signal()` — inject the request's `AbortSignal`, which enters the aborted
+ * state when the client disconnects.
+ *
+ * NOT derivable from `@Req()`: `PBRequest` carries only request-scoped data —
+ * the typed input, route/query params, headers, the authenticated user, calling
+ * client metadata, trace ids, and the declared error throwers — and no signal
+ * (endpoint.ts:358-363).
+ *
+ * Measured 2026-08-29 on Bun: an infinite producer guarded by this signal
+ * stopped four frames after the client was killed, and the handler's `finally`
+ * ran. It is the same mechanism a NestJS handler reaches through
+ * `req.on("close")`.
+ */
+declare function Signal(): ParameterDecorator;
 
 /** The HTTP verbs a route may declare, upper-cased (the runtime router +
  * OpenAPI lower-case on their own). */
@@ -123,11 +210,18 @@ interface RouteOptions {
      * openapi → codegen). The bytes go client→storage directly; the method body
      * runs as the completion handler. See {@link UploadConfig} (decorators/upload.ts). */
     uploadConfig?: UploadConfig;
+    /** Streaming config — present ONLY on `@Sse` routes (the `@Get`/`@Post`/…
+     * decorators never set it). Its presence is what MARKS a route as a streaming
+     * route through the whole pipeline (registry → flatten → openapi → codegen),
+     * exactly as `uploadConfig` does for uploads — never a special HTTP verb. An
+     * `@Sse` route registers POST like any input-bearing route, so the verb cannot
+     * carry the distinction. See {@link SseConfig} (decorators/sse.ts). */
+    sseConfig?: SseConfig;
 }
 /** The kind of value a parameter decorator injects. Drives both dispatch
  * (which request slice to inject) and codegen (which OpenAPI parameter source a
  * schema-bearing kind maps to). */
-type ParamKind = "body" | "query" | "param" | "headers" | "user" | "optionalUser" | "client" | "requestId" | "traceId" | "req" | "uploadedObject";
+type ParamKind = "body" | "query" | "param" | "headers" | "user" | "optionalUser" | "client" | "requestId" | "traceId" | "req" | "uploadedObject" | "sseOut" | "signal";
 /** One parameter decorator's recorded metadata. `index` is the parameter
  * position esbuild/tsc preserve; `schema` is present for the schema-bearing
  * kinds (`body`/`query`/`headers`); `name` is the path-param name for `param`. */
@@ -179,4 +273,4 @@ declare function recordThrows(target: object, fnName: string, throws: ThrowDescr
  */
 declare function getRoutes(ctor: object): RouteMeta[];
 
-export { type HttpMethodUpper as H, type ParamMeta as P, type RouteMeta as R, type ThrowDescriptor as T, type UploadConfig as U, type RouteOptions as a, type ParamKind as b, Upload as c, UploadedObject as d, getRoutes as g, recordThrows as r };
+export { type HttpMethodUpper as H, type ParamMeta as P, type RouteMeta as R, type SseConfig as S, type ThrowDescriptor as T, type UploadConfig as U, type RouteOptions as a, type ParamKind as b, Signal as c, Sse as d, SseOut as e, type SseWriter as f, Upload as g, UploadedObject as h, getRoutes as i, recordThrows as r };