@palbase/backend 17.4.0 → 18.0.1

package/dist/registry-3BLYv4si.d.ts

@@ -0,0 +1,338 @@
+import { A as AuthSpec, R as RateLimitConfig } from './endpoint-B0LpZixz.js';
+import { ZodTypeAny } from 'zod';
+
+/**
+ * storage.ts — the storage-buckets config-as-code DSL.
+ *
+ * `defineStorage({ buckets })` is the first MODULE config-as-code surface (the
+ * sibling of `db/schema.ts`'s `defineSchema`). A `config/storage.ts` file
+ * default-exports a `defineStorage(...)` result; on deploy the br-pod evaluates
+ * it to JSON and reconciles the declared buckets against the tenant's live
+ * buckets via the Storage admin API (create missing, update changed; never
+ * auto-delete — dropping a bucket is destructive and warned only).
+ *
+ * Buckets are DECLARATIVE: name + access + size/mime limits. The FILES inside a
+ * bucket are runtime state (uploaded via the SDK), never in git.
+ *
+ * @example
+ * import { defineStorage, bucket } from "@palbase/backend";
+ *
+ * export default defineStorage({
+ *   buckets: {
+ *     avatars: bucket({
+ *       public: true,
+ *       fileSizeLimit: "5MB",
+ *       allowedMimeTypes: ["image/png", "image/jpeg", "image/webp"],
+ *     }),
+ *     invoices: bucket({
+ *       public: false,
+ *       fileSizeLimit: "20MB",
+ *       allowedMimeTypes: ["application/pdf"],
+ *     }),
+ *   },
+ * });
+ *
+ * The returned value is the EXACT JSON shape the runtime's generic config
+ * extractor (`config_extract.js`) emits and the Go apply step parses:
+ *   { __config: "storage", buckets: { avatars: { public, fileSizeLimit, allowedMimeTypes }, ... } }
+ * `fileSizeLimit` is always normalized to a number of bytes (or null when
+ * omitted, meaning "no limit"); the apply step maps it to the Storage API's
+ * `file_size_limit` field. `allowedMimeTypes` is the allowlist or null (any).
+ */
+/** The discriminant written under `__config` so the eval/apply can tell which
+ * module config a `config/*.ts` file describes. Storage is `"storage"`. */
+declare const STORAGE_CONFIG_KIND: "storage";
+/**
+ * The author-facing options for a single bucket.
+ *
+ * - `public`: when true the bucket is served without a signed URL. Defaults to
+ *   `false` (private — signed URLs only).
+ * - `fileSizeLimit`: the per-object upload cap. Accepts a human string
+ *   (`"5MB"`, `"20MB"`, `"1GB"`) or a bare number of BYTES. Omit for no limit.
+ * - `allowedMimeTypes`: an allowlist of MIME types accepted on upload. Omit to
+ *   allow any type. Each entry must look like `type/subtype` (e.g. `image/png`,
+ *   `application/pdf`, or a wildcard `image/*`).
+ */
+interface BucketOptions {
+    public?: boolean;
+    fileSizeLimit?: string | number;
+    allowedMimeTypes?: string[];
+    variants?: Record<string, ImageVariant>;
+}
+/**
+ * One named rendition of an uploaded image — the same three knobs
+ * `getPublicUrl(path, ...)` takes, given a name so the size lives with the
+ * bucket instead of being retyped at every call site.
+ *
+ * At least one of `width` / `height` must be set (a variant that resizes
+ * nothing and converts nothing is a typo, not a variant).
+ */
+interface ImageVariant {
+    width?: number;
+    height?: number;
+    /**
+     * How the source is made to meet the box. Defaults to `"contain"`.
+     *
+     * - `cover` fills the box exactly and crops the overflow from the centre —
+     *   what a square avatar or a grid cell needs.
+     * - `contain` fits the whole picture inside the box, cropping nothing. One
+     *   side may come out smaller than declared.
+     * - `inside` is `contain` that never ENLARGES. Blowing a 100px image up to
+     *   1000px produces a blurry picture that is bigger on the wire.
+     */
+    fit?: "cover" | "contain" | "inside";
+    format?: "webp" | "avif" | "jpeg" | "png";
+    /** Encoder quality, 1–100. Defaults to 85. JPEG only. */
+    quality?: number;
+}
+/**
+ * The compiled, serializable bucket definition — the EXACT shape emitted to
+ * JSON and consumed by the Go apply step.
+ *
+ * - `public`: always present (defaulted to `false`).
+ * - `fileSizeLimit`: bytes as a number, or `null` for "no limit".
+ * - `allowedMimeTypes`: the MIME allowlist, or `null` for "any type".
+ */
+interface BucketDef {
+    public: boolean;
+    fileSizeLimit: number | null;
+    allowedMimeTypes: string[] | null;
+    /** Named renditions, or `null` when none are declared. Rendered AT UPLOAD and
+     * stored as objects of their own, behind immutable URLs. */
+    variants: Record<string, ImageVariant> | null;
+}
+/** A storage config definition: the discriminant + a map of bucket name →
+ * {@link BucketDef}. This is the value `defineStorage` returns and the runtime
+ * config extractor serializes. */
+interface StorageConfig {
+    __config: typeof STORAGE_CONFIG_KIND;
+    buckets: Record<string, BucketDef>;
+}
+/** The author-facing input to `defineStorage`: a `buckets` map whose keys are
+ * the bucket names and whose values are `bucket({...})` builders. */
+interface StorageInput {
+    buckets: Record<string, BucketDef>;
+}
+/**
+ * Parse a `fileSizeLimit` into a number of bytes.
+ *
+ * - A bare number is taken as bytes verbatim (must be a non-negative integer).
+ * - A string is `<number><unit>` (e.g. `"5MB"`, `"1.5GB"`, `"500kb"`); the unit
+ *   is case-insensitive and optional (a bare numeric string = bytes). Binary
+ *   units (1 MB = 1024 squared bytes) to match the Storage module's parser.
+ *
+ * Throws on a negative value, a non-finite number, or an unrecognized unit so a
+ * bad limit fails at config-author time, not silently at deploy.
+ */
+declare function parseFileSizeLimit(input: string | number): number;
+/**
+ * Define a single bucket. The bucket NAME is supplied by the key in
+ * `defineStorage({ buckets: { <name>: bucket({...}) } })`, so `bucket()` takes
+ * only the options.
+ *
+ * Validates eagerly (at config-author time):
+ *  - `fileSizeLimit` parses to a valid non-negative byte count.
+ *  - each `allowedMimeTypes` entry is a `type/subtype` MIME string.
+ *
+ * Returns a normalized {@link BucketDef}: `public` defaulted to `false`,
+ * `fileSizeLimit` as bytes-or-null, `allowedMimeTypes` deduped-or-null.
+ */
+declare function bucket(opts?: BucketOptions): BucketDef;
+/**
+ * Define the storage config for a project. The bucket NAME comes from each
+ * object key (authors never repeat the name). Returns the discriminated
+ * {@link StorageConfig} the runtime config extractor serializes and the Go
+ * apply step reconciles.
+ *
+ * @example
+ * export default defineStorage({
+ *   buckets: { avatars: bucket({ public: true, fileSizeLimit: "5MB" }) },
+ * });
+ */
+declare function defineStorage(input: StorageInput): StorageConfig;
+
+/** 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;
+/**
+ * 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
+ * that PINS the limits so storage itself rejects an over-limit / wrong-type PUT
+ * — the client cannot exceed what it declared.
+ */
+interface UploadConfig {
+    /**
+     * Target bucket NAME. MUST exist in `config/storage.ts` `defineStorage(...)`.
+     *
+     * The bucket is the SINGLE SOURCE OF TRUTH for the size limit + MIME allowlist:
+     * `bucket({ fileSizeLimit, allowedMimeTypes })`. Storage enforces those at the
+     * actual PUT (the only guard a client cannot skip), so `@Upload` deliberately
+     * does NOT take its own `maxSize`/`allowedTypes` — duplicating them here would
+     * let a route declare a tighter limit than its bucket that storage would not
+     * enforce (a real bypass: declare 10 bytes at authorize, then PUT up to the
+     * bucket ceiling straight at the signed URL). One bucket, one limit, enforced.
+     */
+    bucket: string;
+    /**
+     * SERVER-side object key template. The client NEVER chooses the path. Tokens:
+     * `{userId}` (authenticated user id), `{uploadId}` (server-minted), and
+     * `{filename}` (the client-declared filename, sanitized). e.g.
+     * `"{userId}/{uploadId}-{filename}"`.
+     */
+    pathTemplate: string;
+}
+/**
+ * `@Upload(subpath, config)` — declare a direct-storage upload route. The method
+ * body is the completion handler; `config.uploadConfig` drives the authorize
+ * guard + signed-URL pinning.
+ *
+ * @example
+ * ＠Upload("/", { bucket: "docs", pathTemplate: "{userId}/{uploadId}-{filename}" })
+ * async upload(＠UploadedObject() obj: UploadedObject, ＠User() user): Promise<DocResult> { ... }
+ * // The size limit + MIME allowlist come from the "docs" bucket in
+ * // config/storage.ts — storage enforces them at the PUT.
+ */
+declare function Upload(subpath: string, config: UploadConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator;
+/**
+ * The uploaded object, injected into an `@Upload` method body by
+ * `@UploadedObject()` once storage confirms the upload. Bytes are NOT present
+ * (they went straight to storage) — this is the metadata the completion handler
+ * persists.
+ */
+interface UploadedObject {
+    /** Server-minted id correlating authorize ↔ completion (idempotency key). */
+    uploadId: string;
+    /** Final object key in the bucket (rendered from `pathTemplate`). */
+    path: string;
+    /** Bucket the object landed in. */
+    bucket: string;
+    /** Object size in bytes, as reported by storage. */
+    size: number;
+    /** Object MIME type, as reported by storage — detected from the BYTES, not
+     * from the filename or from what the client claimed. */
+    contentType: string;
+    /** SHA-256 of the stored bytes, hex. The same value the object's ETag is
+     * derived from, so a client that has it can tell whether it already holds
+     * these bytes. */
+    checksum: string;
+    /** Pixel width, for an image. Absent otherwise — a PDF has no dimensions,
+     * and reporting 0 would be a measurement rather than an absence. */
+    width?: number;
+    /** Pixel height, for an image. */
+    height?: number;
+    /**
+     * A ~25-byte placeholder the client paints INSTANTLY while the real image
+     * downloads — the thing that replaces a grey skeleton with something already
+     * shaped like the picture. Absent for non-images.
+     *
+     * Persist it beside the object's path: it costs a column and saves a request
+     * per picture on every gallery render.
+     */
+    thumbhash?: string;
+    /**
+     * The renditions the bucket declared, by name, as URLs ready to use.
+     *
+     * Present on the completion input so the handler that stores the row has
+     * everything it needs in one place — asking for them afterwards would be a
+     * second call per upload, and per picture on every read.
+     */
+    variants: Record<string, string>;
+}
+/**
+ * `@UploadedObject()` — inject the uploaded object (`: UploadedObject`) into an
+ * `@Upload` method body (the completion input). Only valid on an `@Upload`
+ * route; the bytes are NOT present (they went directly to storage), this is the
+ * confirmed object's metadata.
+ *
+ * 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;
+/**
+ * Cross-check one `@Upload` route's uploadConfig against the project's
+ * {@link StorageConfig}: the named bucket MUST exist in `defineStorage(...)`.
+ * Throws a precise error so a typo fails at deploy, not at the first user upload.
+ *
+ * That is the ONLY cross-check: the size limit + MIME allowlist live on the
+ * bucket (`bucket({ fileSizeLimit, allowedMimeTypes })`) and are enforced by
+ * storage at the PUT. `@Upload` carries no `maxSize`/`allowedTypes` of its own,
+ * so there is nothing to compare — one bucket, one limit, no drift.
+ *
+ * `routeLabel` is used only for error messages (e.g. `docs.upload`).
+ */
+declare function validateUploadAgainstStorage(uploadConfig: UploadConfig, storage: StorageConfig, routeLabel: string): void;
+
+/** The HTTP verbs a route may declare, upper-cased (the runtime router +
+ * OpenAPI lower-case on their own). */
+type HttpMethodUpper = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "QUERY";
+/** Route-level options accepted by the method decorators (`@Get`/`@Post`/…). */
+interface RouteOptions {
+    /** OVERRIDES the controller-level default auth for this one route. */
+    auth?: AuthSpec;
+    /** Per-route rate limit. */
+    rateLimit?: RateLimitConfig;
+    /** Direct-storage upload config — present ONLY on `@Upload` routes (the
+     * `@Get`/`@Post`/… decorators never set it). Its presence is what MARKS a
+     * route as an upload route through the whole pipeline (registry → flatten →
+     * openapi → codegen). The bytes go client→storage directly; the method body
+     * runs as the completion handler. See {@link UploadConfig} (decorators/upload.ts). */
+    uploadConfig?: UploadConfig;
+}
+/** 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";
+/** 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`. */
+interface ParamMeta {
+    index: number;
+    kind: ParamKind;
+    /** Zod schema for `body`/`query`/`headers` (validation + codegen source). */
+    schema?: ZodTypeAny;
+    /** Path-param name for `@Param("id")`. */
+    name?: string;
+}
+/** One inferred throw site: the error CLASS name (e.g. "TodoLocked") and its
+ * wire code (e.g. "todo_locked"). `status`, `hasData`, and the data JSON schema
+ * are NOT carried here — they resolve from the error registry by `code` at
+ * extract/openapi time (single source of truth). */
+interface ThrowDescriptor {
+    name: string;
+    code: string;
+}
+/** One route's recorded metadata: the verb + subpath + method name + options,
+ * the ordered parameter metas, and the resolved return schema (injected by the
+ * codegen step — see `returnSchema`). */
+interface RouteMeta {
+    method: HttpMethodUpper;
+    subpath: string;
+    fnName: string;
+    options: RouteOptions;
+    params: ParamMeta[];
+    /** Response schema for the route, if any. Derived from the method's RETURN
+     * TYPE by codegen and written here via `recordReturn` (a generated top-level
+     * IIFE injected per controller), not by an author-written decorator. */
+    returnSchema?: ZodTypeAny;
+    /** Error classes this route can throw, if inferred. Derived from the method
+     * body + service call graph by the deploy stager's throw analysis and written
+     * here via `recordThrows` (a generated top-level IIFE injected per controller,
+     * the `recordReturn` twin), not by an author-written decorator. */
+    throws?: ThrowDescriptor[];
+}
+/** Attach the inferred throw descriptors to the route for `fnName` (called by
+ * the stager-injected IIFE that carries the throw analysis result — the
+ * `recordReturn` twin). If the route does not exist yet, the descriptors are
+ * buffered (THROWS_BUFFER) and drained into the route by `recordRoute` when the
+ * method decorator runs. */
+declare function recordThrows(target: object, fnName: string, throws: ThrowDescriptor[]): void;
+/** Read the route metadata for a controller class (the deploy/dispatch entry
+ * point). Applies any buffered return schemas + throw descriptors (for the
+ * recordReturn/recordThrows-runs-before orderings) and returns a defensive copy
+ * so callers cannot mutate the registry.
+ */
+declare function getRoutes(ctor: object): RouteMeta[];
+
+export { type BucketDef as B, type HttpMethodUpper as H, type ImageVariant as I, type ParamMeta as P, type RouteMeta as R, STORAGE_CONFIG_KIND as S, type ThrowDescriptor as T, type UploadConfig as U, type RouteOptions as a, type BucketOptions as b, type ParamKind as c, type StorageConfig as d, type StorageInput as e, Upload as f, UploadedObject as g, bucket as h, defineStorage as i, getRoutes as j, parseFileSizeLimit as p, recordThrows as r, validateUploadAgainstStorage as v };

package/dist/registry-Cw0YEYCg.d.cts

@@ -0,0 +1,338 @@
+import { A as AuthSpec, R as RateLimitConfig } from './endpoint-B0LpZixz.cjs';
+import { ZodTypeAny } from 'zod';
+
+/**
+ * storage.ts — the storage-buckets config-as-code DSL.
+ *
+ * `defineStorage({ buckets })` is the first MODULE config-as-code surface (the
+ * sibling of `db/schema.ts`'s `defineSchema`). A `config/storage.ts` file
+ * default-exports a `defineStorage(...)` result; on deploy the br-pod evaluates
+ * it to JSON and reconciles the declared buckets against the tenant's live
+ * buckets via the Storage admin API (create missing, update changed; never
+ * auto-delete — dropping a bucket is destructive and warned only).
+ *
+ * Buckets are DECLARATIVE: name + access + size/mime limits. The FILES inside a
+ * bucket are runtime state (uploaded via the SDK), never in git.
+ *
+ * @example
+ * import { defineStorage, bucket } from "@palbase/backend";
+ *
+ * export default defineStorage({
+ *   buckets: {
+ *     avatars: bucket({
+ *       public: true,
+ *       fileSizeLimit: "5MB",
+ *       allowedMimeTypes: ["image/png", "image/jpeg", "image/webp"],
+ *     }),
+ *     invoices: bucket({
+ *       public: false,
+ *       fileSizeLimit: "20MB",
+ *       allowedMimeTypes: ["application/pdf"],
+ *     }),
+ *   },
+ * });
+ *
+ * The returned value is the EXACT JSON shape the runtime's generic config
+ * extractor (`config_extract.js`) emits and the Go apply step parses:
+ *   { __config: "storage", buckets: { avatars: { public, fileSizeLimit, allowedMimeTypes }, ... } }
+ * `fileSizeLimit` is always normalized to a number of bytes (or null when
+ * omitted, meaning "no limit"); the apply step maps it to the Storage API's
+ * `file_size_limit` field. `allowedMimeTypes` is the allowlist or null (any).
+ */
+/** The discriminant written under `__config` so the eval/apply can tell which
+ * module config a `config/*.ts` file describes. Storage is `"storage"`. */
+declare const STORAGE_CONFIG_KIND: "storage";
+/**
+ * The author-facing options for a single bucket.
+ *
+ * - `public`: when true the bucket is served without a signed URL. Defaults to
+ *   `false` (private — signed URLs only).
+ * - `fileSizeLimit`: the per-object upload cap. Accepts a human string
+ *   (`"5MB"`, `"20MB"`, `"1GB"`) or a bare number of BYTES. Omit for no limit.
+ * - `allowedMimeTypes`: an allowlist of MIME types accepted on upload. Omit to
+ *   allow any type. Each entry must look like `type/subtype` (e.g. `image/png`,
+ *   `application/pdf`, or a wildcard `image/*`).
+ */
+interface BucketOptions {
+    public?: boolean;
+    fileSizeLimit?: string | number;
+    allowedMimeTypes?: string[];
+    variants?: Record<string, ImageVariant>;
+}
+/**
+ * One named rendition of an uploaded image — the same three knobs
+ * `getPublicUrl(path, ...)` takes, given a name so the size lives with the
+ * bucket instead of being retyped at every call site.
+ *
+ * At least one of `width` / `height` must be set (a variant that resizes
+ * nothing and converts nothing is a typo, not a variant).
+ */
+interface ImageVariant {
+    width?: number;
+    height?: number;
+    /**
+     * How the source is made to meet the box. Defaults to `"contain"`.
+     *
+     * - `cover` fills the box exactly and crops the overflow from the centre —
+     *   what a square avatar or a grid cell needs.
+     * - `contain` fits the whole picture inside the box, cropping nothing. One
+     *   side may come out smaller than declared.
+     * - `inside` is `contain` that never ENLARGES. Blowing a 100px image up to
+     *   1000px produces a blurry picture that is bigger on the wire.
+     */
+    fit?: "cover" | "contain" | "inside";
+    format?: "webp" | "avif" | "jpeg" | "png";
+    /** Encoder quality, 1–100. Defaults to 85. JPEG only. */
+    quality?: number;
+}
+/**
+ * The compiled, serializable bucket definition — the EXACT shape emitted to
+ * JSON and consumed by the Go apply step.
+ *
+ * - `public`: always present (defaulted to `false`).
+ * - `fileSizeLimit`: bytes as a number, or `null` for "no limit".
+ * - `allowedMimeTypes`: the MIME allowlist, or `null` for "any type".
+ */
+interface BucketDef {
+    public: boolean;
+    fileSizeLimit: number | null;
+    allowedMimeTypes: string[] | null;
+    /** Named renditions, or `null` when none are declared. Rendered AT UPLOAD and
+     * stored as objects of their own, behind immutable URLs. */
+    variants: Record<string, ImageVariant> | null;
+}
+/** A storage config definition: the discriminant + a map of bucket name →
+ * {@link BucketDef}. This is the value `defineStorage` returns and the runtime
+ * config extractor serializes. */
+interface StorageConfig {
+    __config: typeof STORAGE_CONFIG_KIND;
+    buckets: Record<string, BucketDef>;
+}
+/** The author-facing input to `defineStorage`: a `buckets` map whose keys are
+ * the bucket names and whose values are `bucket({...})` builders. */
+interface StorageInput {
+    buckets: Record<string, BucketDef>;
+}
+/**
+ * Parse a `fileSizeLimit` into a number of bytes.
+ *
+ * - A bare number is taken as bytes verbatim (must be a non-negative integer).
+ * - A string is `<number><unit>` (e.g. `"5MB"`, `"1.5GB"`, `"500kb"`); the unit
+ *   is case-insensitive and optional (a bare numeric string = bytes). Binary
+ *   units (1 MB = 1024 squared bytes) to match the Storage module's parser.
+ *
+ * Throws on a negative value, a non-finite number, or an unrecognized unit so a
+ * bad limit fails at config-author time, not silently at deploy.
+ */
+declare function parseFileSizeLimit(input: string | number): number;
+/**
+ * Define a single bucket. The bucket NAME is supplied by the key in
+ * `defineStorage({ buckets: { <name>: bucket({...}) } })`, so `bucket()` takes
+ * only the options.
+ *
+ * Validates eagerly (at config-author time):
+ *  - `fileSizeLimit` parses to a valid non-negative byte count.
+ *  - each `allowedMimeTypes` entry is a `type/subtype` MIME string.
+ *
+ * Returns a normalized {@link BucketDef}: `public` defaulted to `false`,
+ * `fileSizeLimit` as bytes-or-null, `allowedMimeTypes` deduped-or-null.
+ */
+declare function bucket(opts?: BucketOptions): BucketDef;
+/**
+ * Define the storage config for a project. The bucket NAME comes from each
+ * object key (authors never repeat the name). Returns the discriminated
+ * {@link StorageConfig} the runtime config extractor serializes and the Go
+ * apply step reconciles.
+ *
+ * @example
+ * export default defineStorage({
+ *   buckets: { avatars: bucket({ public: true, fileSizeLimit: "5MB" }) },
+ * });
+ */
+declare function defineStorage(input: StorageInput): StorageConfig;
+
+/** 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;
+/**
+ * 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
+ * that PINS the limits so storage itself rejects an over-limit / wrong-type PUT
+ * — the client cannot exceed what it declared.
+ */
+interface UploadConfig {
+    /**
+     * Target bucket NAME. MUST exist in `config/storage.ts` `defineStorage(...)`.
+     *
+     * The bucket is the SINGLE SOURCE OF TRUTH for the size limit + MIME allowlist:
+     * `bucket({ fileSizeLimit, allowedMimeTypes })`. Storage enforces those at the
+     * actual PUT (the only guard a client cannot skip), so `@Upload` deliberately
+     * does NOT take its own `maxSize`/`allowedTypes` — duplicating them here would
+     * let a route declare a tighter limit than its bucket that storage would not
+     * enforce (a real bypass: declare 10 bytes at authorize, then PUT up to the
+     * bucket ceiling straight at the signed URL). One bucket, one limit, enforced.
+     */
+    bucket: string;
+    /**
+     * SERVER-side object key template. The client NEVER chooses the path. Tokens:
+     * `{userId}` (authenticated user id), `{uploadId}` (server-minted), and
+     * `{filename}` (the client-declared filename, sanitized). e.g.
+     * `"{userId}/{uploadId}-{filename}"`.
+     */
+    pathTemplate: string;
+}
+/**
+ * `@Upload(subpath, config)` — declare a direct-storage upload route. The method
+ * body is the completion handler; `config.uploadConfig` drives the authorize
+ * guard + signed-URL pinning.
+ *
+ * @example
+ * ＠Upload("/", { bucket: "docs", pathTemplate: "{userId}/{uploadId}-{filename}" })
+ * async upload(＠UploadedObject() obj: UploadedObject, ＠User() user): Promise<DocResult> { ... }
+ * // The size limit + MIME allowlist come from the "docs" bucket in
+ * // config/storage.ts — storage enforces them at the PUT.
+ */
+declare function Upload(subpath: string, config: UploadConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator;
+/**
+ * The uploaded object, injected into an `@Upload` method body by
+ * `@UploadedObject()` once storage confirms the upload. Bytes are NOT present
+ * (they went straight to storage) — this is the metadata the completion handler
+ * persists.
+ */
+interface UploadedObject {
+    /** Server-minted id correlating authorize ↔ completion (idempotency key). */
+    uploadId: string;
+    /** Final object key in the bucket (rendered from `pathTemplate`). */
+    path: string;
+    /** Bucket the object landed in. */
+    bucket: string;
+    /** Object size in bytes, as reported by storage. */
+    size: number;
+    /** Object MIME type, as reported by storage — detected from the BYTES, not
+     * from the filename or from what the client claimed. */
+    contentType: string;
+    /** SHA-256 of the stored bytes, hex. The same value the object's ETag is
+     * derived from, so a client that has it can tell whether it already holds
+     * these bytes. */
+    checksum: string;
+    /** Pixel width, for an image. Absent otherwise — a PDF has no dimensions,
+     * and reporting 0 would be a measurement rather than an absence. */
+    width?: number;
+    /** Pixel height, for an image. */
+    height?: number;
+    /**
+     * A ~25-byte placeholder the client paints INSTANTLY while the real image
+     * downloads — the thing that replaces a grey skeleton with something already
+     * shaped like the picture. Absent for non-images.
+     *
+     * Persist it beside the object's path: it costs a column and saves a request
+     * per picture on every gallery render.
+     */
+    thumbhash?: string;
+    /**
+     * The renditions the bucket declared, by name, as URLs ready to use.
+     *
+     * Present on the completion input so the handler that stores the row has
+     * everything it needs in one place — asking for them afterwards would be a
+     * second call per upload, and per picture on every read.
+     */
+    variants: Record<string, string>;
+}
+/**
+ * `@UploadedObject()` — inject the uploaded object (`: UploadedObject`) into an
+ * `@Upload` method body (the completion input). Only valid on an `@Upload`
+ * route; the bytes are NOT present (they went directly to storage), this is the
+ * confirmed object's metadata.
+ *
+ * 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;
+/**
+ * Cross-check one `@Upload` route's uploadConfig against the project's
+ * {@link StorageConfig}: the named bucket MUST exist in `defineStorage(...)`.
+ * Throws a precise error so a typo fails at deploy, not at the first user upload.
+ *
+ * That is the ONLY cross-check: the size limit + MIME allowlist live on the
+ * bucket (`bucket({ fileSizeLimit, allowedMimeTypes })`) and are enforced by
+ * storage at the PUT. `@Upload` carries no `maxSize`/`allowedTypes` of its own,
+ * so there is nothing to compare — one bucket, one limit, no drift.
+ *
+ * `routeLabel` is used only for error messages (e.g. `docs.upload`).
+ */
+declare function validateUploadAgainstStorage(uploadConfig: UploadConfig, storage: StorageConfig, routeLabel: string): void;
+
+/** The HTTP verbs a route may declare, upper-cased (the runtime router +
+ * OpenAPI lower-case on their own). */
+type HttpMethodUpper = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "QUERY";
+/** Route-level options accepted by the method decorators (`@Get`/`@Post`/…). */
+interface RouteOptions {
+    /** OVERRIDES the controller-level default auth for this one route. */
+    auth?: AuthSpec;
+    /** Per-route rate limit. */
+    rateLimit?: RateLimitConfig;
+    /** Direct-storage upload config — present ONLY on `@Upload` routes (the
+     * `@Get`/`@Post`/… decorators never set it). Its presence is what MARKS a
+     * route as an upload route through the whole pipeline (registry → flatten →
+     * openapi → codegen). The bytes go client→storage directly; the method body
+     * runs as the completion handler. See {@link UploadConfig} (decorators/upload.ts). */
+    uploadConfig?: UploadConfig;
+}
+/** 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";
+/** 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`. */
+interface ParamMeta {
+    index: number;
+    kind: ParamKind;
+    /** Zod schema for `body`/`query`/`headers` (validation + codegen source). */
+    schema?: ZodTypeAny;
+    /** Path-param name for `@Param("id")`. */
+    name?: string;
+}
+/** One inferred throw site: the error CLASS name (e.g. "TodoLocked") and its
+ * wire code (e.g. "todo_locked"). `status`, `hasData`, and the data JSON schema
+ * are NOT carried here — they resolve from the error registry by `code` at
+ * extract/openapi time (single source of truth). */
+interface ThrowDescriptor {
+    name: string;
+    code: string;
+}
+/** One route's recorded metadata: the verb + subpath + method name + options,
+ * the ordered parameter metas, and the resolved return schema (injected by the
+ * codegen step — see `returnSchema`). */
+interface RouteMeta {
+    method: HttpMethodUpper;
+    subpath: string;
+    fnName: string;
+    options: RouteOptions;
+    params: ParamMeta[];
+    /** Response schema for the route, if any. Derived from the method's RETURN
+     * TYPE by codegen and written here via `recordReturn` (a generated top-level
+     * IIFE injected per controller), not by an author-written decorator. */
+    returnSchema?: ZodTypeAny;
+    /** Error classes this route can throw, if inferred. Derived from the method
+     * body + service call graph by the deploy stager's throw analysis and written
+     * here via `recordThrows` (a generated top-level IIFE injected per controller,
+     * the `recordReturn` twin), not by an author-written decorator. */
+    throws?: ThrowDescriptor[];
+}
+/** Attach the inferred throw descriptors to the route for `fnName` (called by
+ * the stager-injected IIFE that carries the throw analysis result — the
+ * `recordReturn` twin). If the route does not exist yet, the descriptors are
+ * buffered (THROWS_BUFFER) and drained into the route by `recordRoute` when the
+ * method decorator runs. */
+declare function recordThrows(target: object, fnName: string, throws: ThrowDescriptor[]): void;
+/** Read the route metadata for a controller class (the deploy/dispatch entry
+ * point). Applies any buffered return schemas + throw descriptors (for the
+ * recordReturn/recordThrows-runs-before orderings) and returns a defensive copy
+ * so callers cannot mutate the registry.
+ */
+declare function getRoutes(ctor: object): RouteMeta[];
+
+export { type BucketDef as B, type HttpMethodUpper as H, type ImageVariant as I, type ParamMeta as P, type RouteMeta as R, STORAGE_CONFIG_KIND as S, type ThrowDescriptor as T, type UploadConfig as U, type RouteOptions as a, type BucketOptions as b, type ParamKind as c, type StorageConfig as d, type StorageInput as e, Upload as f, UploadedObject as g, bucket as h, defineStorage as i, getRoutes as j, parseFileSizeLimit as p, recordThrows as r, validateUploadAgainstStorage as v };

package/dist/test/index.js

@@ -1,3 +1,5 @@
+import "../chunk-7D4SUZUM.js";
+
 // src/test/api.ts
 var TestApiError = class extends Error {
   status;