@sezzlee/sdk-nestjs 0.0.0-stage → 0.2.0

package/dist/decorators.js

@@ -0,0 +1,79 @@
+export const hidden = {
+    value: (value) => ({
+        hide: { kind: "constant", value },
+    }),
+    from: (source) => ({
+        hide: { kind: "deferred", source },
+    }),
+    omit: () => ({ hide: { kind: "omit" } }),
+};
+/**
+ * Key-checks a curation against a DTO's own keys.
+ *
+ * Optional: `arguments` accepts a plain record. Reaching for this moves the
+ * `curation_unresolved` diagnostic from startup to compile time, which is where a typo belongs.
+ */
+export function curate(rules) {
+    return rules;
+}
+export const MCP_SELECTION = "sezzlee:selection";
+export function McpVariant(options) {
+    return ((_target, _property, descriptor) => {
+        if (descriptor?.value !== undefined) {
+            appendVariant(descriptor.value, options);
+        }
+    });
+}
+export function McpToolFamily(options) {
+    return ((_target, _property, descriptor) => {
+        if (descriptor?.value !== undefined) {
+            updateCarrier(descriptor.value, (carried) => ({
+                ...carried,
+                family: options,
+            }));
+        }
+    });
+}
+function append(target, marker) {
+    const existing = Reflect.getOwnMetadata(MCP_SELECTION, target) ?? [];
+    Reflect.defineMetadata(MCP_SELECTION, [...existing, marker], target);
+}
+function appendVariant(target, variant) {
+    /**
+     * Prepended, not appended: method decorators evaluate bottom-up, so appending would publish the
+     * variants in the reverse of the order they are written in, and the order is what the catalog
+     * zips names against.
+     */
+    updateCarrier(target, (carried) => ({
+        ...carried,
+        variants: [variant, ...(carried.variants ?? [])],
+    }));
+}
+function updateCarrier(target, update) {
+    const existing = Reflect.getOwnMetadata(MCP_SELECTION, target) ?? [];
+    const carrier = existing.find((marker) => marker.include);
+    const marker = {
+        include: true,
+        options: update(carrier?.options ?? {}),
+    };
+    Reflect.defineMetadata(MCP_SELECTION, carrier === undefined
+        ? [...existing, marker]
+        : existing.map((entry) => (entry === carrier ? marker : entry)), target);
+}
+function decorate(marker) {
+    return ((target, _property, descriptor) => {
+        append(descriptor?.value !== undefined ? descriptor.value : target, marker);
+    });
+}
+export function McpTool(options = {}) {
+    return decorate({ include: true, options });
+}
+export function McpIgnore() {
+    return decorate({ include: false, options: {} });
+}
+export function markersOf(target) {
+    if (target === undefined) {
+        return [];
+    }
+    return (Reflect.getOwnMetadata(MCP_SELECTION, target) ?? []);
+}

package/dist/discovery/body-encoding.d.ts

@@ -0,0 +1,24 @@
+import { type JsonSchemaObject } from "@sezzlee/core";
+import type { McpToolOptions } from "../decorators.js";
+import type { DiscoveryDiagnostic } from "./endpoint-discovery.js";
+export type FileBinding = "single" | "multiple";
+export interface BodyEncodingInput {
+    readonly where: string;
+    readonly controller: NewableFunction;
+    readonly handler: (...args: never[]) => unknown;
+    readonly hints: McpToolOptions;
+    readonly files: readonly FileBinding[];
+    readonly schema: JsonSchemaObject | undefined;
+    readonly report: ((diagnostic: DiscoveryDiagnostic) => void) | undefined;
+}
+/** `objectNotation` is never written: Nest's `qs` reads brackets, and absent means bracket. */
+export interface BodyEncoding {
+    readonly schema: JsonSchemaObject | undefined;
+    readonly contentType?: string;
+}
+/**
+ * Decides the body's media type and completes its schema with the multipart file fields.
+ *
+ * @returns `undefined` when the endpoint has to be dropped; the reason has been reported.
+ */
+export declare function bodyEncodingOf(input: BodyEncodingInput): BodyEncoding | undefined;

package/dist/discovery/body-encoding.js

@@ -0,0 +1,211 @@
+import { isJsonMediaType, jsonMediaType, multipartMediaType, textMediaType, urlEncodedMediaType, } from "@sezzlee/core";
+function mediaTypeOf(value) {
+    return (value.split(";")[0] ?? "").trim().toLowerCase();
+}
+function declaredConsumes(controller, handler) {
+    const read = (target) => Reflect.getMetadata("swagger/apiConsumes", target);
+    const declared = read(handler) ?? read(controller);
+    return Array.isArray(declared)
+        ? declared
+            .filter((entry) => typeof entry === "string")
+            .map(mediaTypeOf)
+        : [];
+}
+function covers(accepted, mediaType) {
+    if (accepted === mediaType || accepted === "*/*") {
+        return true;
+    }
+    return accepted.endsWith("/*") && mediaType.startsWith(accepted.slice(0, -1));
+}
+/**
+ * Chooses from an `@ApiConsumes` list for an endpoint that binds no file.
+ *
+ * Guard: the choice is what the backend parses, not what the documentation says. Express's
+ * default JSON parser reads `application/json` only and leaves a `+json` body unparsed
+ * (form-body-probe N6), and Nest has no 415 filter, so the JSON family collapses to
+ * `application/json`. Multipart is never chosen here: multer runs only behind a file interceptor,
+ * so without a file binding a multipart body would reach the handler empty while a JSON one binds.
+ */
+function chooseFrom(accepted) {
+    const concrete = accepted.filter((type) => !type.includes("*"));
+    if (accepted.some((type) => covers(type, jsonMediaType) || isJsonMediaType(type))) {
+        return jsonMediaType;
+    }
+    if (concrete.includes(urlEncodedMediaType)) {
+        return urlEncodedMediaType;
+    }
+    if (concrete.includes(textMediaType)) {
+        return textMediaType;
+    }
+    const other = concrete.find((type) => type !== multipartMediaType);
+    return other ?? jsonMediaType;
+}
+function isWritable(mediaType) {
+    return (isJsonMediaType(mediaType) ||
+        mediaType === urlEncodedMediaType ||
+        mediaType === multipartMediaType ||
+        mediaType === textMediaType);
+}
+function fileSchemaOf(declaration) {
+    const part = {
+        type: "string",
+        contentMediaType: declaration.mediaType ?? "application/octet-stream",
+    };
+    const schema = declaration.multiple === true ? { type: "array", items: part } : part;
+    return declaration.description === undefined
+        ? schema
+        : { ...schema, description: declaration.description };
+}
+function isBinary(schema) {
+    return (schema?.type === "string" &&
+        (schema.format === "binary" || schema.contentMediaType !== undefined));
+}
+/**
+ * Reads the file fields `@ApiBody` documents: a body schema property that is `format: "binary"`,
+ * or an array of them. The same metadata `@nestjs/swagger` itself writes, read by key so the SDK
+ * takes no dependency on it.
+ */
+function swaggerFileFields(handler) {
+    const parameters = Reflect.getMetadata("swagger/apiParameters", handler);
+    if (!Array.isArray(parameters)) {
+        return undefined;
+    }
+    const found = {};
+    for (const parameter of parameters) {
+        if (parameter.in !== "body") {
+            continue;
+        }
+        const schema = parameter.schema;
+        const required = new Set(schema?.required ?? []);
+        for (const [name, property] of Object.entries(schema?.properties ?? {})) {
+            const multiple = property.type === "array" && isBinary(property.items);
+            if (!multiple && !isBinary(property)) {
+                continue;
+            }
+            const part = multiple ? property.items : property;
+            found[name] = {
+                ...(multiple ? { multiple: true } : {}),
+                ...(required.has(name) ? { required: true } : {}),
+                ...(property.description === undefined
+                    ? {}
+                    : { description: property.description }),
+                ...(part?.contentMediaType === undefined
+                    ? {}
+                    : { mediaType: part.contentMediaType }),
+            };
+        }
+    }
+    return Object.keys(found).length === 0 ? undefined : found;
+}
+function withFiles(schema, files) {
+    const base = schema ?? { type: "object", properties: {} };
+    const required = [
+        ...(base.required ?? []),
+        ...Object.entries(files)
+            .filter(([, declaration]) => declaration.required === true)
+            .map(([name]) => name),
+    ];
+    const properties = { ...(base.properties ?? {}) };
+    for (const [name, declaration] of Object.entries(files)) {
+        properties[name] = fileSchemaOf(declaration);
+    }
+    return {
+        ...base,
+        type: "object",
+        properties,
+        ...(required.length === 0 ? {} : { required }),
+    };
+}
+/**
+ * Inlines a form body's `$ref` members one level deep.
+ *
+ * The binder hoists every nested DTO into `$defs`, but a form field addresses its members by name
+ * on the wire, so the template needs them in place; a reference left behind would drop the
+ * endpoint as `unsupported_body_shape` for a shape that is perfectly expressible.
+ */
+function inlineReferences(schema) {
+    const defs = schema?.$defs;
+    if (schema === undefined ||
+        defs === undefined ||
+        schema.properties === undefined) {
+        return schema;
+    }
+    const properties = {};
+    for (const [name, property] of Object.entries(schema.properties)) {
+        const reference = /^#\/\$defs\/(.+)$/.exec(property.$ref ?? "")?.[1];
+        const target = reference === undefined ? undefined : defs[reference];
+        properties[name] =
+            target === undefined ? property : structuredClone(target);
+    }
+    const inlined = { ...schema, properties };
+    if (!JSON.stringify(properties).includes('"$ref"')) {
+        delete inlined.$defs;
+    }
+    return inlined;
+}
+/**
+ * Decides the body's media type and completes its schema with the multipart file fields.
+ *
+ * @returns `undefined` when the endpoint has to be dropped; the reason has been reported.
+ */
+export function bodyEncodingOf(input) {
+    const { where, hints, report } = input;
+    const hasFiles = input.files.length > 0;
+    const accepted = declaredConsumes(input.controller, input.handler);
+    let contentType;
+    if (hints.consumes !== undefined) {
+        contentType = mediaTypeOf(hints.consumes);
+        if (accepted.length > 0 &&
+            !accepted.some((type) => covers(type, contentType))) {
+            report?.({
+                code: "content_type_not_accepted",
+                message: `${where} declares consumes '${contentType}', which its @ApiConsumes list (${accepted.join(", ")}) does not accept; endpoint skipped.`,
+            });
+            return undefined;
+        }
+    }
+    else if (hasFiles) {
+        contentType = multipartMediaType;
+    }
+    else {
+        contentType = chooseFrom(accepted);
+    }
+    if (!isWritable(contentType)) {
+        report?.({
+            code: "unsupported_binding",
+            message: `${where} takes a ${contentType} body, which sezzlee has no writer for; endpoint skipped.`,
+        });
+        return undefined;
+    }
+    if (hasFiles && contentType !== multipartMediaType) {
+        report?.({
+            code: "content_type_not_accepted",
+            message: `${where} binds a file, which only multipart/form-data can carry, but declares '${contentType}'; endpoint skipped.`,
+        });
+        return undefined;
+    }
+    if (contentType === multipartMediaType && !hasFiles) {
+        report?.({
+            code: "body_parser_missing",
+            message: `${where} takes a multipart/form-data body, which Nest parses only behind a file interceptor; bind the file with @UploadedFile() or declare another media type. Endpoint skipped.`,
+        });
+        return undefined;
+    }
+    let schema = input.schema;
+    if (hasFiles) {
+        const files = hints.files ?? swaggerFileFields(input.handler);
+        if (files === undefined) {
+            report?.({
+                code: "unresolved_file_field",
+                message: `${where} binds an uploaded file, but its multipart field name cannot be read from a file interceptor. Declare it with @McpTool({ files: { <field>: {} } }) or document it with @ApiBody; endpoint skipped.`,
+            });
+            return undefined;
+        }
+        schema = withFiles(schema, files);
+    }
+    if (contentType === urlEncodedMediaType ||
+        contentType === multipartMediaType) {
+        return { schema: inlineReferences(schema), contentType };
+    }
+    return contentType === jsonMediaType ? { schema } : { schema, contentType };
+}

package/dist/discovery/diagnostics.d.ts

@@ -0,0 +1,4 @@
+import { type CatalogSeverity, type DiagnosticsOptions } from "@sezzlee/core";
+export { atLeast } from "@sezzlee/core";
+export type { CatalogDiagnostic, CatalogSeverity, DiagnosticsOptions, } from "@sezzlee/core";
+export declare function severityOf(code: string, options?: DiagnosticsOptions): CatalogSeverity;

package/dist/discovery/diagnostics.js

@@ -0,0 +1,49 @@
+import { familySeverities, severityIn, } from "@sezzlee/core";
+import { sdkFamilySeverities } from "../families.js";
+export { atLeast } from "@sezzlee/core";
+const defaults = {
+    ...familySeverities,
+    ...sdkFamilySeverities,
+    name_collision: "fatal",
+    ambiguous_selection: "fatal",
+    invalid_name: "fatal",
+    prm_path_prefixed: "fatal",
+    query_parser_not_extended: "fatal",
+    argument_collision: "endpointDropped",
+    multiple_body_bindings: "endpointDropped",
+    unsupported_binding: "endpointDropped",
+    unsupported_body_shape: "endpointDropped",
+    content_type_not_accepted: "endpointDropped",
+    unresolved_file_field: "endpointDropped",
+    body_parser_missing: "endpointDropped",
+    unsupported_method: "endpointDropped",
+    schema_def_conflict: "endpointDropped",
+    template_rejected: "endpointDropped",
+    duplicate_argument: "endpointDropped",
+    unsupported_object_style: "endpointDropped",
+    unsupported_object_nesting: "endpointDropped",
+    unresolved_query_shape: "endpointDropped",
+    curation_unresolved: "endpointDropped",
+    invalid_fill_constant: "endpointDropped",
+    hidden_required_omitted: "endpointDropped",
+    unknown_fill_source: "endpointDropped",
+    variant_declaration_conflict: "endpointDropped",
+    sealed_curation_overridden: "fatal",
+    ambiguous_curation: "fatal",
+    curated_open_body: "warning",
+    curation_leaks_name: "warning",
+    curation_leaks_name_in_argument: "warning",
+    curation_unused_on_kept_route: "warning",
+    variant_indistinguishable: "warning",
+    route_folded: "warning",
+    optional_body_argument: "warning",
+    synthetic_body_argument: "warning",
+    unflattenable_body_root: "warning",
+    body_field_collision: "warning",
+    unbound_query_object: "warning",
+    unbound_header_object: "warning",
+    query_member_shadowed: "warning",
+};
+export function severityOf(code, options = {}) {
+    return severityIn(defaults, code, options);
+}

package/dist/discovery/endpoint-discovery.d.ts

@@ -0,0 +1,52 @@
+import type { EndpointDescriptor } from "@sezzlee/core";
+import { type McpToolOptions } from "../decorators.js";
+import { type CatalogSeverity } from "./diagnostics.js";
+import { type TypeShapeBinderOptions } from "./type-shape.js";
+export interface RoutePathMetadata {
+    readonly ctrlPath?: string;
+    readonly methodPath?: string;
+    readonly globalPrefix?: string;
+    readonly modulePath?: string;
+    readonly controllerVersion?: unknown;
+    readonly methodVersion?: unknown;
+    readonly versioningOptions?: unknown;
+}
+export interface RoutePaths {
+    create(metadata: RoutePathMetadata, requestMethod?: number): string[];
+}
+/** `RoutePathFactory` reads `getGlobalPrefixOptions()`; with no application there is no exclusion list. */
+export declare function createRoutePaths(applicationConfig?: unknown): RoutePaths;
+export interface DiscoveryDiagnostic {
+    readonly code: string;
+    readonly message: string;
+}
+export interface ControllerCandidate {
+    readonly metatype: NewableFunction;
+    readonly modulePath?: string;
+}
+export interface VisibilityDeclaration {
+    readonly anonymous?: "yes" | "no" | "unknown";
+    readonly policies?: readonly string[];
+}
+export interface DiscoveryOptions {
+    readonly globalPrefix?: string;
+    readonly versioningOptions?: unknown;
+    readonly routePaths?: RoutePaths;
+    readonly schema?: TypeShapeBinderOptions;
+    readonly globalGuards?: readonly unknown[];
+    readonly severity?: (code: string) => CatalogSeverity;
+    readonly report?: (diagnostic: DiscoveryDiagnostic) => void;
+    readonly queryGrouping?: "flatten" | "group";
+}
+export interface DiscoveredEndpoint {
+    readonly descriptor: EndpointDescriptor;
+    readonly controller: NewableFunction;
+    readonly handlerName: string;
+    readonly containerMarkers: readonly boolean[];
+    readonly operationMarkers: readonly boolean[];
+    readonly hints: McpToolOptions;
+}
+export declare function discoverEndpoints(controllers: readonly ControllerCandidate[], options?: DiscoveryOptions): DiscoveredEndpoint[];
+/** `RouterModule` writes the module path under a key scoped to the application instance, falling back to the bare key. */
+export declare function modulePathOf(moduleMetatype: unknown, applicationId: string): string | undefined;
+export declare function normalizeRoute(route: string): string;