@palbase/backend 17.3.0 → 18.0.0

package/dist/openapi/index.d.cts

@@ -0,0 +1,170 @@
+import { OpenApiGeneratorV31 } from '@asteasolutions/zod-to-openapi';
+import { ZodTypeAny } from 'zod';
+import { A as AuthSpec, R as RateLimitConfig } from '../endpoint-B0LpZixz.cjs';
+import { P as ParamMeta, T as ThrowDescriptor, U as UploadConfig } from '../registry-Cw0YEYCg.cjs';
+
+/** A controller class (constructor). Kept loose — the only contract is that it
+ * is a `@Controller`-decorated class, asserted via {@link isController}. */
+type ControllerClass = abstract new (...args: never[]) => object;
+/** A controller module loaded from a `controllers/*.controller.ts` file. */
+interface LoadedController {
+    /** Path relative to projectRoot, posix-normalised. */
+    relativePath: string;
+    /** The default-exported `@Controller` class. */
+    controller: ControllerClass;
+}
+/** The zod schemas one route declares, split by request source. Each is present
+ * only when the matching parameter decorator (`@Body`/`@QueryParams`/`@Headers`) is. */
+interface RouteInputSchemas {
+    body?: ZodTypeAny;
+    query?: ZodTypeAny;
+    /** A single `params` schema, when one is declared (currently only via
+     * individual `@Param("id")` decorators — collected into `pathParams`). */
+    params?: ZodTypeAny;
+    headers?: ZodTypeAny;
+}
+/** One flattened route: the HTTP verb, the FULL path (basePath + subpath), the
+ * dotted operationId inputs (controllerName + fnName), the resolved effective
+ * auth, the per-source input schemas, the named path params, the return
+ * schema, and the rate limit. */
+interface FlatRoute {
+    method: string;
+    /** basePath + subpath, collapsed (the full route path). */
+    fullPath: string;
+    /** The controller method name — the method-name half of the dotted
+     * operationId `<controllerName>.<fnName>`; also the worker dispatch key. */
+    fnName: string;
+    /** The dotted-operationId namespace derived from the controller CLASS name
+     * (MembersController → "members"). "" when the derivation is empty — the
+     * operationId then falls back to the flat verb-prefixed form. */
+    controllerName: string;
+    /** Resolved auth: route option ?? controller default ?? true (secure). */
+    effectiveAuth: AuthSpec;
+    /** All parameter metas for this route (ordered by index). */
+    params: ParamMeta[];
+    /** zod schemas split by request source (body/query/params/headers). */
+    inputSchemas: RouteInputSchemas;
+    /** Named path params (`@Param("id")` → `"id"`), in declaration order. */
+    pathParams: string[];
+    /** The response zod schema (named by the method's return type), if any. */
+    returnSchema?: ZodTypeAny;
+    /** Per-route rate limit, if declared. */
+    rateLimit?: RateLimitConfig;
+    /** Inferred throw descriptors (recordThrows — the stager's throw analysis),
+     * if any. Resolved against the error registry at emission time. */
+    throws?: ThrowDescriptor[];
+    /** Direct-storage upload config — present ONLY on `@Upload` routes. Its
+     * presence MARKS this as an upload route through openapi + codegen (the bytes
+     * go client→storage; the method body is the completion handler). */
+    uploadConfig?: UploadConfig;
+}
+/**
+ * Flatten a `@Controller` class into its route entries. The full path is
+ * `basePath + subpath`; the operationId is the DOTTED
+ * `<controllerName>.<fnName>` id (PlacesController.importNearby →
+ * places.importNearby) — matching the Go runtime (extract_meta.js derives the
+ * namespace from the class name; generator.go joins). Effective auth resolves
+ * the cascade (route ?? controller default ?? secure-by-default).
+ */
+declare function flattenController(controller: ControllerClass): FlatRoute[];
+/** The operationId for a route — exposed so callers (convert/aggregate)
+ * derive it consistently. Dotted `<controllerName>.<fnName>` (members.getUser)
+ * when the namespace is derivable; flat verb-prefixed fallback otherwise —
+ * byte-for-byte identical to the Go runtime's operationID() in
+ * `internal/openapi/generator.go`. */
+declare function operationIdFor(route: FlatRoute): string;
+/** Discover controller files under projectRoot (sorted, deterministic). */
+declare function discoverControllerFiles(projectRoot: string): Promise<string[]>;
+/** Error thrown when a controller module fails to import or does not
+ * default-export a `@Controller` class. */
+declare class ControllerLoadError extends Error {
+    readonly relativePath: string;
+    readonly cause?: unknown | undefined;
+    constructor(relativePath: string, message: string, cause?: unknown | undefined);
+}
+/** Load every discovered controller module, returning its `@Controller` class. */
+declare function loadControllers(absolutePaths: string[], projectRoot: string, options?: {
+    timeoutMs?: number;
+}): Promise<LoadedController[]>;
+
+interface AggregateOptions {
+    /** Pre-loaded controllers (test-only — bypass dynamic import). When
+     * provided, controller discovery is skipped. */
+    loadedControllers?: LoadedController[];
+    /** Document version stamped onto the spec. Defaults to `0.0.0`. */
+    version?: string;
+    /** OpenAPI `info.title`. Defaults to `Palbase Backend`. */
+    title?: string;
+    /** Per-controller import timeout. */
+    timeoutMs?: number;
+}
+interface AggregateResult {
+    /** Final OpenAPI 3.2 document, ready to JSON.stringify. */
+    document: ReturnType<OpenApiGeneratorV31["generateDocument"]>;
+    /** Number of routes registered. */
+    endpointCount: number;
+    /** Set of operationIds (handy for collision-detection tests). */
+    operationIds: string[];
+}
+/**
+ * Run the full pipeline: discover controllers → load → flatten → convert →
+ * emit.
+ *
+ * Throws a ControllerLoadError on a single bad file. Throws a plain Error if
+ * two routes derive the same operationId — collisions are caught after sort()
+ * so the error message is deterministic.
+ */
+declare function aggregateOpenAPI(projectRoot: string, options?: AggregateOptions): Promise<AggregateResult>;
+
+/**
+ * Derive the dotted-operationId NAMESPACE from a controller CLASS name: strip
+ * ONE trailing "Controller" suffix (case-sensitive), then lower-case the first
+ * letter. MembersController → "members", UserProfileController →
+ * "userProfile", Members → "members". Returns "" when the derivation is empty
+ * (a class named exactly "Controller", or an anonymous class) — callers then
+ * fall back to the flat verb-prefixed id. Byte-for-byte identical to
+ * `deriveControllerName` in the Go runtime's extract_meta.js.
+ */
+declare function deriveControllerName(className: string): string;
+/**
+ * Derive the FLAT, verb-prefixed FALLBACK operationId for a route from its
+ * HTTP method + FULL path — used only when the dotted
+ * `<controllerName>.<fnName>` id cannot be derived (empty controllerName).
+ * Byte-for-byte identical to the Go runtime's `flatOperationID(method, path)`
+ * in `internal/openapi/generator.go`:
+ *
+ *   lower(method) + Capitalize(seg) for each path segment,
+ *   with `{param}` → `ByParam`.
+ *
+ * Examples: (POST, /places/import) → "postPlacesImport";
+ *           (GET,  /todos/{id})    → "getTodosById".
+ */
+declare function deriveControllerOperationId(method: string, fullPath: string): string;
+/**
+ * Join a controller `basePath` with a route `subpath` into the full route path.
+ * Collapses duplicate slashes and a trailing `/` so `("/places", "/")` →
+ * `/places` and `("/", "/")` → `/`.
+ */
+declare function joinControllerPath(basePath: string, subpath: string): string;
+
+declare const ERROR_ENVELOPE_REF = "PalbaseErrorEnvelope";
+/** OpenAPI security-scheme name for the bearer token every authed route uses. */
+declare const BEARER_SCHEME = "PalbaseBearer";
+
+/**
+ * True when the effective auth requires a token. The cascade is resolved by the
+ * caller (route ?? controller default ?? true) into a single `AuthSpec`; this
+ * collapses it to a boolean.
+ *
+ * | AuthSpec               | required |
+ * |------------------------|----------|
+ * | `true`                 | true     |
+ * | `false`                | false    |
+ * | `{ required: true }`   | true     |
+ * | `{ required: false }`  | false    |
+ * | `{ role: "admin" }`    | true     |
+ * | `{}`                   | true     |
+ */
+declare function isAuthEffectivelyRequired(auth: AuthSpec): boolean;
+
+export { type AggregateOptions, type AggregateResult, BEARER_SCHEME, type ControllerClass, ControllerLoadError, ERROR_ENVELOPE_REF, type FlatRoute, type LoadedController, type RouteInputSchemas, aggregateOpenAPI, deriveControllerName, deriveControllerOperationId, discoverControllerFiles, flattenController, isAuthEffectivelyRequired, joinControllerPath, loadControllers, operationIdFor };

package/dist/openapi/index.d.ts

@@ -0,0 +1,170 @@
+import { OpenApiGeneratorV31 } from '@asteasolutions/zod-to-openapi';
+import { ZodTypeAny } from 'zod';
+import { A as AuthSpec, R as RateLimitConfig } from '../endpoint-B0LpZixz.js';
+import { P as ParamMeta, T as ThrowDescriptor, U as UploadConfig } from '../registry-3BLYv4si.js';
+
+/** A controller class (constructor). Kept loose — the only contract is that it
+ * is a `@Controller`-decorated class, asserted via {@link isController}. */
+type ControllerClass = abstract new (...args: never[]) => object;
+/** A controller module loaded from a `controllers/*.controller.ts` file. */
+interface LoadedController {
+    /** Path relative to projectRoot, posix-normalised. */
+    relativePath: string;
+    /** The default-exported `@Controller` class. */
+    controller: ControllerClass;
+}
+/** The zod schemas one route declares, split by request source. Each is present
+ * only when the matching parameter decorator (`@Body`/`@QueryParams`/`@Headers`) is. */
+interface RouteInputSchemas {
+    body?: ZodTypeAny;
+    query?: ZodTypeAny;
+    /** A single `params` schema, when one is declared (currently only via
+     * individual `@Param("id")` decorators — collected into `pathParams`). */
+    params?: ZodTypeAny;
+    headers?: ZodTypeAny;
+}
+/** One flattened route: the HTTP verb, the FULL path (basePath + subpath), the
+ * dotted operationId inputs (controllerName + fnName), the resolved effective
+ * auth, the per-source input schemas, the named path params, the return
+ * schema, and the rate limit. */
+interface FlatRoute {
+    method: string;
+    /** basePath + subpath, collapsed (the full route path). */
+    fullPath: string;
+    /** The controller method name — the method-name half of the dotted
+     * operationId `<controllerName>.<fnName>`; also the worker dispatch key. */
+    fnName: string;
+    /** The dotted-operationId namespace derived from the controller CLASS name
+     * (MembersController → "members"). "" when the derivation is empty — the
+     * operationId then falls back to the flat verb-prefixed form. */
+    controllerName: string;
+    /** Resolved auth: route option ?? controller default ?? true (secure). */
+    effectiveAuth: AuthSpec;
+    /** All parameter metas for this route (ordered by index). */
+    params: ParamMeta[];
+    /** zod schemas split by request source (body/query/params/headers). */
+    inputSchemas: RouteInputSchemas;
+    /** Named path params (`@Param("id")` → `"id"`), in declaration order. */
+    pathParams: string[];
+    /** The response zod schema (named by the method's return type), if any. */
+    returnSchema?: ZodTypeAny;
+    /** Per-route rate limit, if declared. */
+    rateLimit?: RateLimitConfig;
+    /** Inferred throw descriptors (recordThrows — the stager's throw analysis),
+     * if any. Resolved against the error registry at emission time. */
+    throws?: ThrowDescriptor[];
+    /** Direct-storage upload config — present ONLY on `@Upload` routes. Its
+     * presence MARKS this as an upload route through openapi + codegen (the bytes
+     * go client→storage; the method body is the completion handler). */
+    uploadConfig?: UploadConfig;
+}
+/**
+ * Flatten a `@Controller` class into its route entries. The full path is
+ * `basePath + subpath`; the operationId is the DOTTED
+ * `<controllerName>.<fnName>` id (PlacesController.importNearby →
+ * places.importNearby) — matching the Go runtime (extract_meta.js derives the
+ * namespace from the class name; generator.go joins). Effective auth resolves
+ * the cascade (route ?? controller default ?? secure-by-default).
+ */
+declare function flattenController(controller: ControllerClass): FlatRoute[];
+/** The operationId for a route — exposed so callers (convert/aggregate)
+ * derive it consistently. Dotted `<controllerName>.<fnName>` (members.getUser)
+ * when the namespace is derivable; flat verb-prefixed fallback otherwise —
+ * byte-for-byte identical to the Go runtime's operationID() in
+ * `internal/openapi/generator.go`. */
+declare function operationIdFor(route: FlatRoute): string;
+/** Discover controller files under projectRoot (sorted, deterministic). */
+declare function discoverControllerFiles(projectRoot: string): Promise<string[]>;
+/** Error thrown when a controller module fails to import or does not
+ * default-export a `@Controller` class. */
+declare class ControllerLoadError extends Error {
+    readonly relativePath: string;
+    readonly cause?: unknown | undefined;
+    constructor(relativePath: string, message: string, cause?: unknown | undefined);
+}
+/** Load every discovered controller module, returning its `@Controller` class. */
+declare function loadControllers(absolutePaths: string[], projectRoot: string, options?: {
+    timeoutMs?: number;
+}): Promise<LoadedController[]>;
+
+interface AggregateOptions {
+    /** Pre-loaded controllers (test-only — bypass dynamic import). When
+     * provided, controller discovery is skipped. */
+    loadedControllers?: LoadedController[];
+    /** Document version stamped onto the spec. Defaults to `0.0.0`. */
+    version?: string;
+    /** OpenAPI `info.title`. Defaults to `Palbase Backend`. */
+    title?: string;
+    /** Per-controller import timeout. */
+    timeoutMs?: number;
+}
+interface AggregateResult {
+    /** Final OpenAPI 3.2 document, ready to JSON.stringify. */
+    document: ReturnType<OpenApiGeneratorV31["generateDocument"]>;
+    /** Number of routes registered. */
+    endpointCount: number;
+    /** Set of operationIds (handy for collision-detection tests). */
+    operationIds: string[];
+}
+/**
+ * Run the full pipeline: discover controllers → load → flatten → convert →
+ * emit.
+ *
+ * Throws a ControllerLoadError on a single bad file. Throws a plain Error if
+ * two routes derive the same operationId — collisions are caught after sort()
+ * so the error message is deterministic.
+ */
+declare function aggregateOpenAPI(projectRoot: string, options?: AggregateOptions): Promise<AggregateResult>;
+
+/**
+ * Derive the dotted-operationId NAMESPACE from a controller CLASS name: strip
+ * ONE trailing "Controller" suffix (case-sensitive), then lower-case the first
+ * letter. MembersController → "members", UserProfileController →
+ * "userProfile", Members → "members". Returns "" when the derivation is empty
+ * (a class named exactly "Controller", or an anonymous class) — callers then
+ * fall back to the flat verb-prefixed id. Byte-for-byte identical to
+ * `deriveControllerName` in the Go runtime's extract_meta.js.
+ */
+declare function deriveControllerName(className: string): string;
+/**
+ * Derive the FLAT, verb-prefixed FALLBACK operationId for a route from its
+ * HTTP method + FULL path — used only when the dotted
+ * `<controllerName>.<fnName>` id cannot be derived (empty controllerName).
+ * Byte-for-byte identical to the Go runtime's `flatOperationID(method, path)`
+ * in `internal/openapi/generator.go`:
+ *
+ *   lower(method) + Capitalize(seg) for each path segment,
+ *   with `{param}` → `ByParam`.
+ *
+ * Examples: (POST, /places/import) → "postPlacesImport";
+ *           (GET,  /todos/{id})    → "getTodosById".
+ */
+declare function deriveControllerOperationId(method: string, fullPath: string): string;
+/**
+ * Join a controller `basePath` with a route `subpath` into the full route path.
+ * Collapses duplicate slashes and a trailing `/` so `("/places", "/")` →
+ * `/places` and `("/", "/")` → `/`.
+ */
+declare function joinControllerPath(basePath: string, subpath: string): string;
+
+declare const ERROR_ENVELOPE_REF = "PalbaseErrorEnvelope";
+/** OpenAPI security-scheme name for the bearer token every authed route uses. */
+declare const BEARER_SCHEME = "PalbaseBearer";
+
+/**
+ * True when the effective auth requires a token. The cascade is resolved by the
+ * caller (route ?? controller default ?? true) into a single `AuthSpec`; this
+ * collapses it to a boolean.
+ *
+ * | AuthSpec               | required |
+ * |------------------------|----------|
+ * | `true`                 | true     |
+ * | `false`                | false    |
+ * | `{ required: true }`   | true     |
+ * | `{ required: false }`  | false    |
+ * | `{ role: "admin" }`    | true     |
+ * | `{}`                   | true     |
+ */
+declare function isAuthEffectivelyRequired(auth: AuthSpec): boolean;
+
+export { type AggregateOptions, type AggregateResult, BEARER_SCHEME, type ControllerClass, ControllerLoadError, ERROR_ENVELOPE_REF, type FlatRoute, type LoadedController, type RouteInputSchemas, aggregateOpenAPI, deriveControllerName, deriveControllerOperationId, discoverControllerFiles, flattenController, isAuthEffectivelyRequired, joinControllerPath, loadControllers, operationIdFor };