@marinoscar/platform-api 0.1.0-next.3 → 0.1.0-next.4

package/dist/host/metrics/platform-app-metrics.d.ts

@@ -0,0 +1,42 @@
+import type { AppMetricDef } from '../../otel-core/index';
+import { DB_BACKUP_APP_METRICS } from '../../db-backup/index';
+import { NODES_APP_METRICS } from '../../nodes/index';
+export declare const JOB_DURATION_BUCKETS_S: readonly [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 120, 300, 600, 1800, 3600];
+export declare const AI_DURATION_BUCKETS_S: readonly [0.1, 0.25, 0.5, 1, 2, 5, 10, 20, 30, 60, 120, 300];
+export declare const JOB_EXECUTOR_VALUES: readonly ["server", "node"];
+/** `JobSettleOutcome` values, mirrored so this file does not import the queue. */
+export declare const JOB_SETTLE_OUTCOME_VALUES: readonly ["succeeded", "failed", "retry-scheduled", "rate-limit-deferred", "claim-lost", "write-failed"];
+export declare const JOB_REAP_OUTCOME_VALUES: readonly ["requeued", "failed"];
+/** The queue statuses the depth gauge reports (terminal rows are history, not depth). */
+export declare const JOB_DEPTH_STATUS_VALUES: readonly ["pending", "running"];
+export declare const BACKUP_OUTCOME_VALUES: readonly ["completed", "failed"];
+export declare const AUTH_LOGIN_OUTCOME_VALUES: readonly ["success", "allowlist_rejected", "disabled", "no_organization"];
+export declare const AUTH_REFRESH_OUTCOME_VALUES: readonly ["success", "invalid", "reuse_detected", "expired", "user_inactive", "device_revoked", "no_organization"];
+export declare const AI_STATUS_VALUES: readonly ["succeeded", "failed", "cancelled"];
+export declare const NOTIFICATION_OUTCOME_VALUES: readonly ["sent", "failed", "rate_limited", "error"];
+/**
+ * A platform metric's code key: the queue's, the backups' (declared by the
+ * db-backup slice), sign-in's, AI's, notifications' and the node fleet's
+ * (declared by the nodes slice).
+ *
+ * @stability experimental
+ */
+export type PlatformAppMetricKey = 'jobsEnqueued' | 'jobsClaimed' | 'jobsSettled' | 'jobsDuration' | 'jobsReaped' | 'jobsQueueDepth' | 'jobsOldestPendingAge' | (typeof DB_BACKUP_APP_METRICS)[number]['key'] | 'authLogins' | 'authRefreshes' | 'aiRequests' | 'aiTokens' | 'aiDuration' | 'notificationDeliveries' | (typeof NODES_APP_METRICS)[number]['key'];
+/**
+ * One of the platform's metric declarations.
+ *
+ * @stability experimental
+ */
+export interface PlatformAppMetricDef extends AppMetricDef {
+    /** The metric's code key. */
+    readonly key: PlatformAppMetricKey;
+}
+/**
+ * The platform's `app.*` metrics: the queue, backups, sign-in, AI,
+ * notifications and the node fleet, in declaration order. Registered (with the
+ * event bus's three) by {@link registerPlatformHostAppMetrics}.
+ *
+ * @stability experimental
+ */
+export declare const PLATFORM_APP_METRICS: readonly PlatformAppMetricDef[];
+//# sourceMappingURL=platform-app-metrics.d.ts.map

package/dist/host/metrics/platform-app-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-app-metrics.d.ts","sourceRoot":"","sources":["../../../src/host/metrics/platform-app-metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAqBtD,eAAO,MAAM,sBAAsB,mFAAoF,CAAC;AACxH,eAAO,MAAM,qBAAqB,8DAA+D,CAAC;AAIlG,eAAO,MAAM,mBAAmB,6BAA8B,CAAC;AAC/D,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,0GAO5B,CAAC;AACX,eAAO,MAAM,uBAAuB,iCAAkC,CAAC;AACvE,yFAAyF;AACzF,eAAO,MAAM,uBAAuB,iCAAkC,CAAC;AACvE,eAAO,MAAM,qBAAqB,kCAAmC,CAAC;AAGtE,eAAO,MAAM,yBAAyB,2EAA4E,CAAC;AACnH,eAAO,MAAM,2BAA2B,oHAU9B,CAAC;AACX,eAAO,MAAM,gBAAgB,+CAAgD,CAAC;AAC9E,eAAO,MAAM,2BAA2B,sDAAuD,CAAC;AAmJhG;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC5B,cAAc,GACd,aAAa,GACb,aAAa,GACb,cAAc,GACd,YAAY,GACZ,gBAAgB,GAChB,sBAAsB,GACtB,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAC7C,YAAY,GACZ,eAAe,GACf,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,wBAAwB,GACxB,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,6BAA6B;IAC7B,QAAQ,CAAC,GAAG,EAAE,oBAAoB,CAAC;CACpC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,oBAAoB,EAA6B,CAAC"}

package/dist/host/metrics/platform-app-metrics.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLATFORM_APP_METRICS = exports.NOTIFICATION_OUTCOME_VALUES = exports.AI_STATUS_VALUES = exports.AUTH_REFRESH_OUTCOME_VALUES = exports.AUTH_LOGIN_OUTCOME_VALUES = exports.BACKUP_OUTCOME_VALUES = exports.JOB_DEPTH_STATUS_VALUES = exports.JOB_REAP_OUTCOME_VALUES = exports.JOB_SETTLE_OUTCOME_VALUES = exports.JOB_EXECUTOR_VALUES = exports.AI_DURATION_BUCKETS_S = exports.JOB_DURATION_BUCKETS_S = void 0;
+const index_1 = require("../../db-backup/index");
+const index_2 = require("../../nodes/index");
+// =============================================================================
+// The platform's `app.*` metrics (issue #680)
+// =============================================================================
+//
+// Pure data, registered by `registerPlatformHostAppMetrics()` (./register.ts;
+// moved from the reference app by #867). Exactly the names, units,
+// descriptions and bucket boundaries the API exported before the registry
+// (pinned by `app-metrics.service.spec.ts` and
+// `nodes/node-fleet-metrics.service.spec.ts`): a name or unit is the GreptimeDB
+// table name, so changing one orphans every dashboard query that reads it.
+//
+// The declared `attributes` are the label keys each typed method of
+// `AppMetricsService` emits (and what the generic `add`/`record` would admit
+// for the metric). Gauges declare theirs for documentation: their callbacks
+// bound their own labels.
+// =============================================================================
+// ---- Histogram buckets, in the instrument's unit -----------------------------
+exports.JOB_DURATION_BUCKETS_S = [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 120, 300, 600, 1800, 3600];
+exports.AI_DURATION_BUCKETS_S = [0.1, 0.25, 0.5, 1, 2, 5, 10, 20, 30, 60, 120, 300];
+// ---- Enumerated attribute values (the typed methods check against these) ----
+exports.JOB_EXECUTOR_VALUES = ['server', 'node'];
+/** `JobSettleOutcome` values, mirrored so this file does not import the queue. */
+exports.JOB_SETTLE_OUTCOME_VALUES = [
+    'succeeded',
+    'failed',
+    'retry-scheduled',
+    'rate-limit-deferred',
+    'claim-lost',
+    'write-failed',
+];
+exports.JOB_REAP_OUTCOME_VALUES = ['requeued', 'failed'];
+/** The queue statuses the depth gauge reports (terminal rows are history, not depth). */
+exports.JOB_DEPTH_STATUS_VALUES = ['pending', 'running'];
+exports.BACKUP_OUTCOME_VALUES = ['completed', 'failed'];
+// `no_organization` (PP-6.2, #722): a multi-org sign-in refused for having no
+// active membership. Never an org id: org goes on spans and logs, not labels.
+exports.AUTH_LOGIN_OUTCOME_VALUES = ['success', 'allowlist_rejected', 'disabled', 'no_organization'];
+exports.AUTH_REFRESH_OUTCOME_VALUES = [
+    'success',
+    'invalid',
+    'reuse_detected',
+    'expired',
+    'user_inactive',
+    'device_revoked',
+    // PP-6.4 (#724): the refresh token's organization membership is no longer
+    // active (removed or suspended). Never the org id itself.
+    'no_organization',
+];
+exports.AI_STATUS_VALUES = ['succeeded', 'failed', 'cancelled'];
+exports.NOTIFICATION_OUTCOME_VALUES = ['sent', 'failed', 'rate_limited', 'error'];
+const free = { kind: 'free' };
+const oneOf = (...values) => ({ kind: 'enum', values });
+const JOB_SETTLED_ATTRIBUTES = {
+    job_type: free,
+    outcome: oneOf(...exports.JOB_SETTLE_OUTCOME_VALUES),
+    // `unknown` when the executor is not recorded.
+    executor: oneOf(...exports.JOB_EXECUTOR_VALUES, 'unknown'),
+};
+const AI_REQUEST_ATTRIBUTES = {
+    provider: free,
+    model: free,
+    operation: free,
+    status: oneOf(...exports.AI_STATUS_VALUES),
+    key_source: free,
+    // #739: the registered AI feature (`registerAiFeature`), bounded by that
+    // registry; `none` for a call that named no feature.
+    feature: free,
+};
+const PLATFORM_APP_METRIC_DEFS = [
+    // ---- Jobs ----
+    {
+        key: 'jobsEnqueued',
+        name: 'app.jobs.enqueued',
+        kind: 'counter',
+        unit: '{job}',
+        description: 'Jobs inserted into the queue (dedup hits excluded).',
+        attributes: { job_type: free },
+    },
+    {
+        key: 'jobsClaimed',
+        name: 'app.jobs.claimed',
+        kind: 'counter',
+        unit: '{job}',
+        description: 'Jobs claimed by an executor.',
+        attributes: { job_type: free, executor: oneOf(...exports.JOB_EXECUTOR_VALUES) },
+    },
+    {
+        key: 'jobsSettled',
+        name: 'app.jobs.settled',
+        kind: 'counter',
+        unit: '{job}',
+        description: 'Executor reports settled by the terminal state machine, by outcome.',
+        attributes: JOB_SETTLED_ATTRIBUTES,
+    },
+    {
+        key: 'jobsDuration',
+        name: 'app.jobs.duration',
+        kind: 'histogram',
+        unit: 's',
+        description: 'Run time of one job attempt, from claim to settlement.',
+        buckets: exports.JOB_DURATION_BUCKETS_S,
+        attributes: JOB_SETTLED_ATTRIBUTES,
+    },
+    {
+        key: 'jobsReaped',
+        name: 'app.jobs.reaped',
+        kind: 'counter',
+        unit: '{job}',
+        description: 'Abandoned running jobs recovered by the lease reaper.',
+        attributes: { outcome: oneOf(...exports.JOB_REAP_OUTCOME_VALUES), job_type: free },
+    },
+    {
+        key: 'jobsQueueDepth',
+        name: 'app.jobs.queue.depth',
+        kind: 'gauge',
+        unit: '{job}',
+        description: 'Jobs currently pending or running, by type and status.',
+        attributes: { job_type: free, status: oneOf(...exports.JOB_DEPTH_STATUS_VALUES) },
+    },
+    {
+        key: 'jobsOldestPendingAge',
+        name: 'app.jobs.oldest_pending.age',
+        kind: 'gauge',
+        unit: 's',
+        description: 'Age of the oldest runnable pending job, by type.',
+        attributes: { job_type: free },
+    },
+    // ---- Database backup (declared by the db-backup slice since #740) ----
+    ...index_1.DB_BACKUP_APP_METRICS,
+    // ---- Auth ----
+    {
+        key: 'authLogins',
+        name: 'app.auth.logins',
+        kind: 'counter',
+        unit: '{login}',
+        description: 'Interactive sign-in attempts, by provider and outcome.',
+        attributes: { provider: free, outcome: oneOf(...exports.AUTH_LOGIN_OUTCOME_VALUES) },
+    },
+    {
+        key: 'authRefreshes',
+        name: 'app.auth.refreshes',
+        kind: 'counter',
+        unit: '{refresh}',
+        description: 'Refresh-token rotations, by outcome.',
+        attributes: { outcome: oneOf(...exports.AUTH_REFRESH_OUTCOME_VALUES) },
+    },
+    // ---- AI ----
+    {
+        key: 'aiRequests',
+        name: 'app.ai.requests',
+        kind: 'counter',
+        unit: '{request}',
+        description: 'AI provider round-trips, by provider, model, operation and status.',
+        attributes: AI_REQUEST_ATTRIBUTES,
+    },
+    {
+        key: 'aiTokens',
+        name: 'app.ai.tokens',
+        kind: 'counter',
+        unit: '{token}',
+        description: 'AI tokens reported by the provider, by token_type (input|output).',
+        attributes: { provider: free, model: free, operation: free, token_type: oneOf('input', 'output') },
+    },
+    {
+        key: 'aiDuration',
+        name: 'app.ai.request.duration',
+        kind: 'histogram',
+        unit: 's',
+        description: 'Latency of one AI provider round-trip.',
+        buckets: exports.AI_DURATION_BUCKETS_S,
+        attributes: AI_REQUEST_ATTRIBUTES,
+    },
+    // ---- Notifications ----
+    {
+        key: 'notificationDeliveries',
+        name: 'app.notifications.deliveries',
+        kind: 'counter',
+        unit: '{delivery}',
+        description: 'Notification delivery attempts, by channel, event and outcome.',
+        attributes: { channel: free, event: free, outcome: oneOf(...exports.NOTIFICATION_OUTCOME_VALUES) },
+    },
+    // ---- Worker-node fleet gauges (#606) ----
+    // Declared by the nodes slice (`@marinoscar/platform-api/nodes`, #734),
+    // which creates them (`NodeFleetMetrics`); spread here so the order and
+    // the `PlatformAppMetricKey` union are unchanged.
+    ...index_2.NODES_APP_METRICS,
+];
+/**
+ * The platform's `app.*` metrics: the queue, backups, sign-in, AI,
+ * notifications and the node fleet, in declaration order. Registered (with the
+ * event bus's three) by {@link registerPlatformHostAppMetrics}.
+ *
+ * @stability experimental
+ */
+exports.PLATFORM_APP_METRICS = PLATFORM_APP_METRIC_DEFS;
+const platformKeysComplete = true;
+void platformKeysComplete;
+//# sourceMappingURL=platform-app-metrics.js.map

package/dist/host/metrics/platform-app-metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-app-metrics.js","sourceRoot":"","sources":["../../../src/host/metrics/platform-app-metrics.ts"],"names":[],"mappings":"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"}

package/dist/host/metrics/register.d.ts

@@ -0,0 +1,22 @@
+import { type AppMetricDef } from '../../otel-core/index';
+/**
+ * Registers the platform's app metrics ({@link PLATFORM_APP_METRICS}, then the
+ * event bus's `app.event_bus.*` counters) once, then each list in
+ * `appMetrics`, in order. Idempotent for the platform's own: a second call
+ * registers only the lists it is given. Call it before bootstrap (the registry
+ * freezes after); `PlatformHostCoreModule.forRoot()` calls it with no lists.
+ *
+ * @param appMetrics - further declarations (a slice's, the app's own), registered after the platform's.
+ * @throws RegistryError on a duplicate key or name, or a declaration the registry refuses.
+ *
+ * @example
+ * ```ts
+ * // apps/api/src/common/otel/app-metric.manifest.ts
+ * registerPlatformHostAppMetrics(ORGANIZATIONS_APP_METRICS, SHARING_APP_METRICS, APP_METRICS);
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function registerPlatformHostAppMetrics(...appMetrics: ReadonlyArray<readonly AppMetricDef[]>): void;
+//# sourceMappingURL=register.d.ts.map

package/dist/host/metrics/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/host/metrics/register.ts"],"names":[],"mappings":"AAaA,OAAO,EAAyC,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAIjG;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,UAAU,EAAE,aAAa,CAAC,SAAS,YAAY,EAAE,CAAC,GAAG,IAAI,CAM1G"}

package/dist/host/metrics/register.js

@@ -0,0 +1,46 @@
+"use strict";
+// =============================================================================
+// Registering the platform's app metrics (issue #867; registry #680)
+// =============================================================================
+//
+// The app-metric registry (`@marinoscar/platform-api/otel-core`) is a static
+// registry: filled before bootstrap, frozen after. The reference app used to
+// register the platform's 31 metrics and the event bus's three from its own
+// manifest; the host slice owns both declarations now, so it registers them.
+// `PlatformHostCoreModule.forRoot()` calls this; an app's manifest may call it
+// first to fix the order explicitly (platform first, then the slices' and its
+// own with `registerAppMetrics`), so a key or name collision names the app.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPlatformHostAppMetrics = registerPlatformHostAppMetrics;
+const index_1 = require("../../otel-core/index");
+const event_bus_metrics_1 = require("../event-bus/event-bus.metrics");
+const platform_app_metrics_1 = require("./platform-app-metrics");
+/**
+ * Registers the platform's app metrics ({@link PLATFORM_APP_METRICS}, then the
+ * event bus's `app.event_bus.*` counters) once, then each list in
+ * `appMetrics`, in order. Idempotent for the platform's own: a second call
+ * registers only the lists it is given. Call it before bootstrap (the registry
+ * freezes after); `PlatformHostCoreModule.forRoot()` calls it with no lists.
+ *
+ * @param appMetrics - further declarations (a slice's, the app's own), registered after the platform's.
+ * @throws RegistryError on a duplicate key or name, or a declaration the registry refuses.
+ *
+ * @example
+ * ```ts
+ * // apps/api/src/common/otel/app-metric.manifest.ts
+ * registerPlatformHostAppMetrics(ORGANIZATIONS_APP_METRICS, SHARING_APP_METRICS, APP_METRICS);
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+function registerPlatformHostAppMetrics(...appMetrics) {
+    if (!index_1.appMetricRegistry.has(platform_app_metrics_1.PLATFORM_APP_METRICS[0].key)) {
+        (0, index_1.registerAppMetrics)(platform_app_metrics_1.PLATFORM_APP_METRICS);
+        (0, index_1.registerAppMetrics)(event_bus_metrics_1.EVENT_BUS_APP_METRICS);
+    }
+    for (const list of appMetrics)
+        (0, index_1.registerAppMetrics)(list);
+}
+//# sourceMappingURL=register.js.map

package/dist/host/metrics/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../src/host/metrics/register.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,qEAAqE;AACrE,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,4EAA4E;AAC5E,6EAA6E;AAC7E,+EAA+E;AAC/E,8EAA8E;AAC9E,4EAA4E;AAC5E,gFAAgF;;AAyBhF,wEAMC;AA7BD,iDAAiG;AACjG,sEAAuE;AACvE,iEAA8D;AAE9D;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,8BAA8B,CAAC,GAAG,UAAkD;IAClG,IAAI,CAAC,yBAAiB,CAAC,GAAG,CAAC,2CAAoB,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;QACxD,IAAA,0BAAkB,EAAC,2CAAoB,CAAC,CAAC;QACzC,IAAA,0BAAkB,EAAC,yCAAqB,CAAC,CAAC;IAC5C,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,UAAU;QAAE,IAAA,0BAAkB,EAAC,IAAI,CAAC,CAAC;AAC1D,CAAC"}

package/dist/host/openapi/data-envelope.d.ts

@@ -0,0 +1,7 @@
+import { MutableDocument } from './types';
+/**
+ * Wraps every documented 2xx JSON response in the envelope the global
+ * interceptor produces.
+ */
+export declare function applyDataEnvelope(document: MutableDocument): MutableDocument;
+//# sourceMappingURL=data-envelope.d.ts.map

package/dist/host/openapi/data-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-envelope.d.ts","sourceRoot":"","sources":["../../../src/host/openapi/data-envelope.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAE,eAAe,EAAoB,MAAM,SAAS,CAAC;AAY5D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,CA2B5E"}

package/dist/host/openapi/data-envelope.js

@@ -0,0 +1,115 @@
+"use strict";
+// =============================================================================
+// The `{ data: … }` response envelope (issue #53)
+// =============================================================================
+//
+// `TransformInterceptor` is registered as a GLOBAL `APP_INTERCEPTOR` in
+// `app.module.ts`, and it wraps every handler return value in
+// `{ data, meta: { timestamp } }` unless the handler already returned an object
+// carrying a `data` key.
+//
+// So the documented shape was not wrong on a handful of endpoints — it was
+// wrong nearly everywhere, because `@ApiResponse({ type: Dto })` describes what
+// the handler returns and the interceptor changes that afterwards. Fixing it by
+// editing every controller would be an error-prone sweep that the next new
+// endpoint immediately reopens.
+//
+// Applying the same transformation to the document that the interceptor applies
+// to the response closes it permanently: a handler documented as returning
+// `Dto` is published as `{ data: Dto }`, and a handler that already returns
+// `{ data: Dto }` is published unchanged, exactly mirroring the interceptor's
+// own passthrough rule (`'data' in data`).
+//
+// WHAT IS DELIBERATELY LEFT ALONE
+//   * Non-2xx responses — errors are written by `HttpExceptionFilter` straight
+//     to the reply, bypassing every interceptor, so they are NOT enveloped.
+//   * Responses with no `application/json` schema — `204` and the OAuth
+//     redirects, which take `@Res()` and write the reply themselves. None of
+//     those declares a JSON schema, so skipping schemaless responses is exactly
+//     the right filter and needs no allowlist.
+//   * Schemas that already carry a `data` property, resolved through `$ref`.
+//   * Attachments: a response that declares a `Content-Disposition` header is
+//     a file the handler writes itself with `@Res()` (bypassing the
+//     interceptor), even when the file is JSON. The Doctor's support bundle
+//     (#772) is the first JSON one; the telemetry export declares the header
+//     too.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyDataEnvelope = applyDataEnvelope;
+const types_1 = require("./types");
+const META_SCHEMA = {
+    type: 'object',
+    description: 'Present when the endpoint supplies it (pagination) or when the global response interceptor ' +
+        'adds it (`{ timestamp }`). Not every response carries one.',
+    additionalProperties: true,
+};
+/**
+ * Wraps every documented 2xx JSON response in the envelope the global
+ * interceptor produces.
+ */
+function applyDataEnvelope(document) {
+    const schemas = (document.components?.schemas ??
+        {});
+    (0, types_1.forEachOperation)(document, (operation) => {
+        for (const [status, response] of Object.entries(operation.responses ?? {})) {
+            if (!/^2\d\d$/.test(status))
+                continue;
+            const json = response?.['content'];
+            const media = json?.['application/json'];
+            const schema = media?.schema;
+            if (!media || !schema)
+                continue;
+            if (declaresDataProperty(schema, schemas))
+                continue;
+            if (isAttachment(response))
+                continue;
+            media.schema = {
+                type: 'object',
+                required: ['data'],
+                properties: { data: schema, meta: META_SCHEMA },
+            };
+        }
+    });
+    return document;
+}
+/** Whether a response declares `Content-Disposition`: a file written with `@Res()`, never enveloped. */
+function isAttachment(response) {
+    const headers = response['headers'];
+    return (!!headers &&
+        typeof headers === 'object' &&
+        Object.keys(headers).some((name) => name.toLowerCase() === 'content-disposition'));
+}
+/**
+ * Whether a schema already describes the envelope.
+ *
+ * `$ref` is followed one level into `components.schemas`, because a DTO named
+ * for the whole envelope (`{ data: … }` as a single declared type) is
+ * indistinguishable from an inner type until it is resolved — and double-
+ * wrapping one would publish `{ data: { data: … } }`, a shape the server never
+ * sends.
+ *
+ * Anything that is not a plain object schema or a resolvable local `$ref`
+ * (`allOf`, `oneOf`, an external ref) is treated as "unknown", and unknown
+ * schemas are left untouched rather than guessed at.
+ */
+function declaresDataProperty(schema, schemas, depth = 0) {
+    if (depth > 2)
+        return true; // Cyclic or unexpectedly deep: do not touch it.
+    const ref = schema['$ref'];
+    if (typeof ref === 'string') {
+        const name = ref.startsWith('#/components/schemas/')
+            ? ref.slice('#/components/schemas/'.length)
+            : null;
+        const target = name ? schemas[name] : undefined;
+        // An unresolvable ref is "unknown" — report true so the caller skips it.
+        return target ? declaresDataProperty(target, schemas, depth + 1) : true;
+    }
+    if (schema['allOf'] || schema['oneOf'] || schema['anyOf'])
+        return true;
+    const properties = schema['properties'];
+    if (properties && typeof properties === 'object') {
+        return 'data' in properties;
+    }
+    return false;
+}
+//# sourceMappingURL=data-envelope.js.map

package/dist/host/openapi/data-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-envelope.js","sourceRoot":"","sources":["../../../src/host/openapi/data-envelope.ts"],"names":[],"mappings":"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"}

package/dist/host/openapi/description.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What {@link buildApiDescription} names.
+ *
+ * @stability experimental
+ */
+export interface ApiDescriptionIdentity {
+    /** The product name. */
+    appName: string;
+    /** The source repository URL (`docs/` is linked under it). */
+    repoUrl: string;
+}
+/**
+ * Builds the Markdown intro.
+ *
+ * @param version - resolved application version, echoed so a reader can tell
+ *   which build they are pointed at without cross-checking `info.version`.
+ * @param identity - the product name and repository URL.
+ * @returns the Markdown.
+ * @stability experimental
+ */
+export declare function buildApiDescription(version: string, identity: ApiDescriptionIdentity): string;
+//# sourceMappingURL=description.d.ts.map

package/dist/host/openapi/description.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"description.d.ts","sourceRoot":"","sources":["../../../src/host/openapi/description.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,sBAAsB,GAAG,MAAM,CAoJ7F"}