@vertesia/common 1.5.0-dev.20260807.073259Z → 1.5.0-dev.20260901.005903Z

package/lib/api-contract/index.d.ts

@@ -0,0 +1,186 @@
+import { type JsonObject } from '../api-schemas/adapter.js';
+import { type ApiParameterLocation, type NormalizedApiParameters, type RawApiParameters } from '../api-schemas/parameters.js';
+import type { ApiComponentName, ApiComponentType } from '../api-schemas/registry.js';
+/**
+ * The canonical `components.schemas` for all documented endpoints.
+ *
+ * This exact object is what the OpenAPI spec publishes AND what AJV compiles, so the published
+ * contract and the enforced contract cannot diverge. It is the prebuilt emission of the Zod
+ * registry rather than a live conversion of it — see the module comment.
+ *
+ * Widened on import on purpose: `resolveJsonModule` would otherwise infer the literal type of a
+ * 1187-key document and bake it into this package's `.d.ts`.
+ */
+export declare const ApiSchemaComponents: Readonly<Record<string, JsonObject>>;
+export type { ApiComponentName, ApiComponentType, ApiParameterLocation, NormalizedApiParameters, RawApiParameters };
+/**
+ * A canonical component as a SELF-CONTAINED JSON Schema, for consumers that compile it directly.
+ *
+ * `components` defaults to the generated artifact, which is what a server wants. A GENERATOR must
+ * pass `buildApiSchemaComponents()` instead: the artifact on disk is the previous run's output, so
+ * bundling from it would emit an artifact derived from the last contract rather than the current Zod
+ * schemas — and, run in the wrong order, would leave the two generated files describing different
+ * shapes. Passing the fresh emission makes each generator independent of the others' ordering.
+ *
+ * The published component `$ref`s its neighbours through `#/components/schemas/...`, which resolves
+ * only inside the OpenAPI document. AJV and the Monaco editor need a document they can compile on
+ * its own, so the transitive closure is inlined under `$defs` and the pointers rewritten. Nothing
+ * about the shapes changes — this is a re-rooting of the same objects, plus the removal of the
+ * OpenAPI-only discriminator keywords described below, which is what lets a generated artifact be
+ * compared with the component it came from.
+ */
+export declare function bundleCanonicalComponent(name: ApiComponentName, components?: Readonly<Record<string, JsonObject>>): JsonObject;
+/** The `$ref` pointer for a component, in the same spelling the spec publishes. */
+export declare function apiComponentRef(name: ApiComponentName): string;
+/**
+ * One validation failure, with the undeclared property names kept AS NAMES.
+ *
+ * The structure exists because the rendered line cannot be taken apart again. Property names are
+ * arbitrary JSON strings: `{"customer secret token": 1}` and `{"a, b": 1}` are both valid, so
+ * neither a space nor a comma is a reliable separator once the names have been joined. Any consumer
+ * that needs to shorten the list — the HTTP boundary does, the log does not — has to do it here,
+ * on the array, where a name can be dropped whole.
+ */
+export interface ApiValidationIssue {
+    /**
+     * AJV's `instancePath` for the failing value, with `'/'` substituted for the root.
+     *
+     * Not quite a JSON Pointer: the pointer for a document root is the empty string, which reads as
+     * a missing path in a message. `'/'` is a display sentinel, so treat this as human-facing rather
+     * than as something to resolve against the payload.
+     */
+    path: string;
+    /** AJV's own message, e.g. `must NOT have additional properties`. */
+    message: string;
+    /** Undeclared property names at {@link path}, in the order AJV reported them. */
+    undeclared?: string[];
+    /**
+     * The union candidate this issue is a claim ABOUT, when it is not a fact about the value.
+     *
+     * Set on every issue produced by expanding a failed untagged `oneOf`/`anyOf` — see
+     * {@link collectIssues}. Under such a union each candidate rejects the value for its own
+     * reasons, most of which are irrelevant to the shape the value actually meant, so an issue
+     * carrying a component must be read as "as a `<component>`, this is wrong" and never as
+     * "this is wrong".
+     *
+     * Absent means the opposite and stronger thing: the issue holds against the component the
+     * payload is being validated as, whatever candidate it turns out to be.
+     */
+    component?: string;
+}
+/**
+ * The complete rendering of one issue — every name, no budget.
+ *
+ * This is what gets logged. A caller-facing message renders from {@link ApiValidationIssue} itself
+ * with a length limit rather than shortening this string; see `reportableErrors` in the enforcer.
+ */
+export declare function renderApiValidationIssue(issue: ApiValidationIssue): string;
+/**
+ * Everything in a rendered issue except the property names: `<path> [as <component>]: <message>`.
+ *
+ * Exported because it is not the only renderer. A caller that has to bound the length of a message
+ * cannot use {@link renderApiValidationIssue} — it emits every name — and has to rebuild the line
+ * from {@link ApiValidationIssue} with its own budget for the names. Rebuilding the HEAD too is what
+ * lets the two drift: when `component` was added, the bounded renderer at the HTTP boundary went on
+ * concatenating path and message and silently dropped it, so callers were told
+ * `must NOT have additional properties: to, when` with no sign it was one candidate's claim. There is
+ * one definition of the head so that cannot happen again.
+ */
+export declare function renderApiValidationIssueHead(issue: ApiValidationIssue): string;
+export type ValidateApiPayloadResult<T> = {
+    valid: true;
+    data: T;
+}
+/**
+ * `errors` is the rendered form, complete and ready to log; `issues` is the same failures with
+ * the property names still separable. Shorten from `issues`, never from `errors`.
+ */
+ | {
+    valid: false;
+    errors: string[];
+    issues: ApiValidationIssue[];
+};
+/**
+ * Validates an untyped request body against the component the endpoint publishes.
+ *
+ * Non-mutating by design. AJV's removal modes are never used here: the server would then accept a
+ * body the published schema declares invalid, silently disagreeing with its own spec — and
+ * `removeAdditional: 'all'` additionally empties freeform maps. An undeclared property is reported,
+ * not deleted.
+ *
+ * The component type is handed back only on the `valid` branch, so a body missing required fields
+ * cannot be typed as complete. What the caller does with a failure — reject, or log and continue —
+ * is the endpoint's policy, not this function's.
+ */
+export declare function validateApiRequest<N extends ApiComponentName>(name: N, value: unknown): ValidateApiPayloadResult<ApiComponentType<N>>;
+/**
+ * Validates an already-mapped response against the component it is published as.
+ *
+ * Separate from {@link pruneAndValidateApiResponse} because a resource mapper has already produced
+ * the wire shape: there is nothing to prune, and pruning would only mask a mapper bug. Use this at
+ * the response boundary to detect drift between what the mapper builds and what the spec promises.
+ */
+export declare function validateApiResponse<N extends ApiComponentName>(name: N, value: unknown): ValidateApiPayloadResult<ApiComponentType<N>>;
+/**
+ * Best-effort normalization of a response payload towards the fields its published component
+ * declares. Use this on the response path INSTEAD of an AJV removal mode, which would empty
+ * freeform maps such as `Account.feature_flags`.
+ *
+ * NOT a secret-removal boundary. Ambiguous schema shapes pass values through untouched — see
+ * {@link pruneToSchema} and check a component with {@link findUnprunablePaths} before treating its
+ * output as closed. Fields that must never ship still need an explicit response mapper.
+ *
+ * Never throws and never rejects: an undocumented field is server-side drift, and failing the
+ * response would punish the caller for it.
+ *
+ * Takes a value the caller has already typed as the component. Pruning only REMOVES undeclared
+ * extras, so a conforming input yields a conforming output and the return type is honest. It does
+ * NOT validate, which is why it cannot accept `unknown` — narrowing a payload that is missing
+ * required fields would hand TypeScript a complete `Account` that does not exist at runtime. Use
+ * {@link pruneAndValidateApiResponse} when the payload's shape is not already established.
+ *
+ * Request validation stays separate and non-mutating — pruning a request would make the server
+ * silently disagree with the permissive schema it publishes.
+ */
+export declare function pruneApiResponse<N extends ApiComponentName>(name: N, value: ApiComponentType<N>): ApiComponentType<N>;
+export type PruneAndValidateResult<T> = {
+    valid: true;
+    data: T;
+} | {
+    valid: false;
+    data: unknown;
+    errors: string[];
+    issues: ApiValidationIssue[];
+};
+/**
+ * Prunes an untyped payload and validates the result against the published component.
+ *
+ * The only sound entry point for a payload of unknown shape: the component type is handed back
+ * exclusively on the `valid` branch, so a document missing required fields cannot be typed as
+ * complete. On failure the pruned value is still returned — the caller decides whether to ship it
+ * and log, or fail — which keeps the "never turn drift into a 500" property a policy choice rather
+ * than something baked in here.
+ *
+ */
+export declare function pruneAndValidateApiResponse<N extends ApiComponentName>(name: N, value: unknown): PruneAndValidateResult<ApiComponentType<N>>;
+/**
+ * Paths inside a component where pruning cannot narrow. Empty means no STRUCTURAL gaps for
+ * schema-conforming input — see {@link findUnprunablePaths} for why that is weaker than "nothing
+ * can escape". Anything listed needs an explicit response mapper.
+ */
+export declare function findUnprunableApiPaths(name: ApiComponentName): string[];
+/**
+ * Normalizes raw query or header text into the value a component describes.
+ *
+ * Binds {@link normalizeParameters} to {@link ApiSchemaComponents} — the same objects the OpenAPI
+ * document publishes and {@link validateApiRequest} compiles. That is what keeps the published
+ * parameter and the enforced one the same declaration: the scanner expands this component's
+ * properties into `in: query` parameters, and the coercion below is decided by those same property
+ * schemas, so neither can be changed without changing the other.
+ *
+ * Validate the result with {@link validateApiRequest}, which is non-coercing: everything type-related
+ * has already happened here, so a value this could not coerce is reported against the published
+ * schema rather than by a second rule.
+ */
+export declare function normalizeApiParameters(name: ApiComponentName, raw: RawApiParameters, location: ApiParameterLocation): NormalizedApiParameters;
+//# sourceMappingURL=index.d.ts.map

package/lib/api-contract/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api-contract/index.ts"],"names":[],"mappings":"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"}