@marinoscar/platform-contract 0.0.0-stage → 0.1.0-next.3

package/dist/cjs/doctor/schemas.js

@@ -0,0 +1,183 @@
+"use strict";
+// =============================================================================
+// The Doctor's wire shapes (issue #634; moved here from
+// `@marinoscar/platform-api/doctor` by #701)
+// =============================================================================
+//
+// ALWAYS A 200 FOR AN AUTHORIZED CALLER. A failing check is a row with
+// `status: 'fail'`, never an error status: the report is read precisely when
+// something is wrong, and a 500 or a 503 would withhold the list of what.
+//
+// Every nullable field is present on every row (`null` rather than absent), so
+// a client renders one shape without optional-chaining through it.
+//
+// ⚠ OpenAPI is generated from these schemas (nestjs-zod, through the DTOs of
+// `@marinoscar/platform-api/doctor`). Field order, `.describe()` texts and the
+// order of the status enum are part of the published document: change them
+// only as a deliberate API change.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supportBundleSchema = exports.supportBundleSectionResultSchema = exports.doctorQuerySchema = exports.doctorReportSchema = exports.doctorCheckReportSchema = exports.doctorStatusSchema = void 0;
+const zod_1 = require("zod");
+const constants_js_1 = require("./constants.js");
+/**
+ * A check's status on the wire.
+ *
+ * The enum lists the values in the order the OpenAPI document has always
+ * published (`pass, warn, fail, skip`), which is not the severity order of
+ * {@link DOCTOR_STATUSES}; rank statuses with {@link DOCTOR_STATUS_RANK}.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.doctorStatusSchema = zod_1.z
+    .enum(['pass', 'warn', 'fail', 'skip'])
+    .describe('`pass` — verified healthy. `warn` — works, but needs attention. `fail` — broken. ' +
+    '`skip` — not evaluated: a check it depends on did not pass, or the capability is ' +
+    'intentionally switched off.');
+/**
+ * One row of the report, as `GET /api/admin/doctor` returns it.
+ *
+ * Fields: `id` (stable dotted id, `storage.bucket`), `category` (`core`,
+ * `auth`, ...; an app may add its own), `label`, `settingsPath` (the web route
+ * that fixes it, or `null`), `status`, `detail` (one line: what was found),
+ * `remedy` (set on `warn` and `fail`, otherwise `null`), `error` (the
+ * underlying probe error, or `null`), `data` (small scalar facts, never secret
+ * material, or `null`) and `durationMs` (0 when skipped without running).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.doctorCheckReportSchema = zod_1.z.object({
+    /** Stable dotted id, e.g. `storage.bucket`. */
+    id: zod_1.z.string(),
+    /** `core`, `auth`, `storage`, ... — a fork may add its own. */
+    category: zod_1.z.string(),
+    /** Short human label: "Object storage bucket". */
+    label: zod_1.z.string(),
+    /** The web route that fixes this check, when there is one. */
+    settingsPath: zod_1.z.string().nullable(),
+    /** `pass`, `warn`, `fail` or `skip`. */
+    status: exports.doctorStatusSchema,
+    /** One line: what was found. */
+    detail: zod_1.z.string(),
+    /** What to do about a `warn` or `fail`. Always set on those two. */
+    remedy: zod_1.z.string().nullable(),
+    /** The underlying error message, when a probe failed. */
+    error: zod_1.z.string().nullable(),
+    /** Small scalar facts: counts, versions, latencies. Never secret material. */
+    data: zod_1.z.record(zod_1.z.string(), zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean(), zod_1.z.null()])).nullable(),
+    /** How long this check took; 0 when it was skipped without running. */
+    durationMs: zod_1.z.number().int(),
+});
+/**
+ * The whole report, as `GET /api/admin/doctor` returns it: `verdict` (the
+ * worst status in `checks`, `skip` when none ran), `generatedAt` (ISO 8601; a
+ * cached report keeps its original time), `durationMs` (wall time of the run)
+ * and `checks` (sorted by category, configured order first, then registration
+ * order).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.doctorReportSchema = zod_1.z.object({
+    /** The worst status in `checks` (`pass < skip < warn < fail`); `skip` when none ran. */
+    verdict: exports.doctorStatusSchema,
+    /** When this report was produced. A cached report keeps its original time. */
+    generatedAt: zod_1.z.iso.datetime(),
+    /** Wall time of the whole run. */
+    durationMs: zod_1.z.number().int(),
+    /** Sorted by category (shipped order first), then registration order. */
+    checks: zod_1.z.array(exports.doctorCheckReportSchema),
+});
+// The query's `'true' | 'false'` parameter, typed through its named entries.
+const booleanStringSchema = zod_1.z.enum(['true', 'false']);
+/**
+ * `GET /api/admin/doctor` query: `category` (a lowercase identifier; only the
+ * checks in that category, plus, unreported, whatever they depend on) and
+ * `refresh` (`'true'` bypasses the 15-second report cache).
+ *
+ * `refresh` is `z.enum(['true','false']).transform(...)` and NOT
+ * `z.coerce.boolean()`: every query parameter is a string and
+ * `Boolean('false')` is `true`.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.doctorQuerySchema = zod_1.z.object({
+    /** Only the checks in this category (plus, unreported, whatever they depend on). */
+    category: zod_1.z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9_-]{0,63}$/, 'category must be a lowercase identifier')
+        .optional(),
+    /** `true` bypasses the 15-second report cache. */
+    refresh: booleanStringSchema
+        .transform((value) => value === 'true')
+        .optional(),
+});
+const statusEnumMatchesConstants = true;
+const queryInputMatchesSchema = true;
+void statusEnumMatchesConstants;
+void queryInputMatchesSchema;
+// -----------------------------------------------------------------------------
+// The support bundle (issue #772): the envelope `GET /api/admin/doctor/support-bundle`
+// returns. Each section's `data` is validated by that section's own strict
+// schema on the server (`@marinoscar/platform-api/doctor`), so here it stays
+// `unknown`.
+// -----------------------------------------------------------------------------
+/**
+ * One section of a bundle. `truncated: true` with `data: null` means the
+ * section was larger than its size cap and its data was dropped.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+exports.supportBundleSectionResultSchema = zod_1.z.discriminatedUnion('status', [
+    zod_1.z.object({
+        /** Collected. */
+        status: zod_1.z.literal('ok'),
+        /** The section's data, validated by its strict schema and redacted; `null` when truncated. */
+        data: zod_1.z.unknown().describe("The section's data, already validated by its strict schema and redacted."),
+        /** `true` when a size cap dropped the data. */
+        truncated: zod_1.z.boolean().optional().describe('`true` when a size cap dropped the data (`data` is then `null`).'),
+    }),
+    zod_1.z.object({
+        /** Not collected. */
+        status: zod_1.z.literal('omitted'),
+        /** Why: a missing permission, a capability switched off. */
+        reason: zod_1.z.string().describe('Why the section was not collected (a missing permission, a capability switched off).'),
+    }),
+    zod_1.z.object({
+        /** Collected, but dropped. */
+        status: zod_1.z.literal('error'),
+        /** One redacted line saying why. */
+        error: zod_1.z.string().describe('One redacted line: a throw, a timeout or a schema violation. Never the raw value.'),
+    }),
+]);
+/**
+ * The support bundle: what `GET /api/admin/doctor/support-bundle` returns as a
+ * JSON attachment.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+exports.supportBundleSchema = zod_1.z.object({
+    /** The bundle format version, {@link SUPPORT_BUNDLE_VERSION}. */
+    bundleVersion: zod_1.z.literal(constants_js_1.SUPPORT_BUNDLE_VERSION).describe('The bundle format version.'),
+    /** When the bundle was built (ISO 8601, UTC). */
+    generatedAt: zod_1.z.string().describe('When the bundle was built (ISO 8601, UTC).'),
+    /** The central redaction pass. */
+    redaction: zod_1.z
+        .object({
+        /** The rule set applied, {@link SUPPORT_BUNDLE_REDACTION_RULES}. */
+        rules: zod_1.z.literal(constants_js_1.SUPPORT_BUNDLE_REDACTION_RULES).describe('The redaction rule set applied.'),
+        /** How many values the pass replaced. */
+        replacements: zod_1.z.number().int().describe('How many values the redaction pass replaced.'),
+    })
+        .describe('The central redaction pass, applied on top of every section schema.'),
+    /** One result per registered section, keyed by section id. */
+    sections: zod_1.z
+        .record(zod_1.z.string(), exports.supportBundleSectionResultSchema)
+        .describe('One entry per registered section, keyed by section id.'),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/cjs/doctor/schemas.js.map

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

package/dist/cjs/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The npm name of this package, which holds Zod DTOs and types shared by the platform API and web packages.
+ *
+ * The root entry exports only this name, so the smoke imports in CI have
+ * something to load end to end. Every slice is a subpath export
+ * (`@marinoscar/platform-contract/<slice>`, the first being `./doctor`) and is
+ * deliberately not re-exported here: a consumer loads only the slices it
+ * imports, and importing the root never loads zod.
+ *
+ * @stability experimental
+ */
+export declare const PLATFORM_PACKAGE: "@marinoscar/platform-contract";
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAG,+BAAwC,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLATFORM_PACKAGE = void 0;
+/**
+ * The npm name of this package, which holds Zod DTOs and types shared by the platform API and web packages.
+ *
+ * The root entry exports only this name, so the smoke imports in CI have
+ * something to load end to end. Every slice is a subpath export
+ * (`@marinoscar/platform-contract/<slice>`, the first being `./doctor`) and is
+ * deliberately not re-exported here: a consumer loads only the slices it
+ * imports, and importing the root never loads zod.
+ *
+ * @stability experimental
+ */
+exports.PLATFORM_PACKAGE = '@marinoscar/platform-contract';
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;GAUG;AACU,QAAA,gBAAgB,GAAG,+BAAwC,CAAC"}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/telemetry/assistant.d.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+import { type TelemetryAssistantConfidence, type TelemetryAssistantReportStatus, type TelemetryAssistantSeverity, type TelemetryAssistantToolName } from './constants.js';
+/**
+ * One earlier turn of the conversation: `role` (`user` or `assistant`) and
+ * `content` (at most {@link TELEMETRY_ASSISTANT_HISTORY_CONTENT_MAX} characters).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+export declare const telemetryAssistantTurnSchema: z.ZodObject<{
+    role: z.ZodEnum<import("./constants.js").TelemetryEnumEntries<"user" | "assistant">>;
+    content: z.ZodString;
+}, z.core.$strip>;
+/**
+ * One earlier turn of the conversation.
+ *
+ * @stability stable
+ */
+export type TelemetryAssistantTurn = z.infer<typeof telemetryAssistantTurnSchema>;
+/**
+ * `POST /api/admin/telemetry/assistant/stream` body: `question` (trimmed,
+ * 1..{@link TELEMETRY_ASSISTANT_QUESTION_MAX} characters) and an optional
+ * `history` (oldest first, at most {@link TELEMETRY_ASSISTANT_HISTORY_MAX_TURNS}).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+export declare const telemetryAssistantRequestSchema: z.ZodObject<{
+    question: z.ZodString;
+    history: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<import("./constants.js").TelemetryEnumEntries<"user" | "assistant">>;
+        content: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * The `POST /api/admin/telemetry/assistant/stream` body.
+ *
+ * @stability stable
+ */
+export type TelemetryAssistantRequest = z.infer<typeof telemetryAssistantRequestSchema>;
+/**
+ * `event: step` — one tool call the assistant made.
+ *
+ * @stability stable
+ */
+export interface TelemetryAssistantStepEvent {
+    /** 0-based, across the whole turn. */
+    index: number;
+    /** The tool called. */
+    tool: TelemetryAssistantToolName;
+    /** `group` is `metrics_overview`'s metric group (#603). */
+    input?: {
+        /** `describe_table`: the table. */
+        table?: string;
+        /** `run_query`: the statement. */
+        sql?: string;
+        /** The window an overview tool looked at. */
+        window?: string;
+        /** `get_trace`: the trace. */
+        traceId?: string;
+        /** `metrics_overview`: the metric group. */
+        group?: string;
+    };
+    /** `run_query` / `get_trace` only: rows the call returned (up to the row cap). */
+    rowCount?: number;
+    /** `run_query` / `get_trace` only: more rows matched than the row cap allowed. */
+    truncated?: boolean;
+    /** Wall time of the call. */
+    durationMs: number;
+    /** Why the call failed; the model was told the same and may retry. */
+    error?: string;
+    /** The model's interim reasoning for the round this call belongs to; only on the FIRST call of a round. Bounded to 1000 chars. */
+    thought?: string;
+}
+/**
+ * One finding of a report.
+ *
+ * @stability stable
+ */
+export interface TelemetryAssistantFinding {
+    /** One line naming the finding. */
+    title: string;
+    /** How bad it is. */
+    severity: TelemetryAssistantSeverity;
+    /** What in the data shows it. */
+    evidence: string;
+    /** Index into `report.queries` of the query that shows this finding. */
+    queryIndex?: number;
+}
+/**
+ * A supporting query of a report, which the user can re-run.
+ *
+ * @stability stable
+ */
+export interface TelemetryAssistantQuery {
+    /** What the query shows. */
+    title: string;
+    /** The statement. */
+    sql: string;
+}
+/**
+ * The investigation's structured result.
+ *
+ * @stability stable
+ */
+export interface TelemetryAssistantReport {
+    /** The outcome. */
+    status: TelemetryAssistantReportStatus;
+    /** A short summary. */
+    summary: string;
+    /** What was found, most important first. */
+    findings: TelemetryAssistantFinding[];
+    /** The root cause, or null when none was established. */
+    rootCause: string | null;
+    /** How sure the report is. */
+    confidence: TelemetryAssistantConfidence;
+    /** What to do next. */
+    recommendations: string[];
+    /** Supporting queries the user can re-run (at most 5); the first is the most useful. */
+    queries: TelemetryAssistantQuery[];
+}
+/**
+ * `event: answer` — the final answer.
+ *
+ * @stability stable
+ */
+export interface TelemetryAssistantAnswerEvent {
+    /** Back-compat: queries[0].sql, or null. */
+    sql: string | null;
+    /** Back-compat: the report summary (or the raw text when the model did not return a report). */
+    explanation: string;
+    /** The structured report, or null when the model gave no parseable one. */
+    report: TelemetryAssistantReport | null;
+}
+/**
+ * `event: error` — the turn failed after the stream opened.
+ *
+ * @stability stable
+ */
+export interface TelemetryAssistantErrorEvent {
+    /** A stable error code. */
+    code: string;
+    /** A message for the user. */
+    message: string;
+}
+/**
+ * Every event of the stream, by name, with its payload.
+ *
+ * @stability stable
+ */
+export interface TelemetryAssistantEventMap {
+    /** One tool call. */
+    step: TelemetryAssistantStepEvent;
+    /** The final answer. */
+    answer: TelemetryAssistantAnswerEvent;
+    /** The turn failed. */
+    error: TelemetryAssistantErrorEvent;
+    /** The stream ends. */
+    done: Record<string, never>;
+}
+/**
+ * The name of a stream event.
+ *
+ * @stability stable
+ */
+export type TelemetryAssistantEventName = keyof TelemetryAssistantEventMap;
+/**
+ * A function that writes one stream event (the server's side of the stream).
+ *
+ * @stability stable
+ */
+export type TelemetryAssistantEmit = <E extends TelemetryAssistantEventName>(event: E, data: TelemetryAssistantEventMap[E]) => void;
+//# sourceMappingURL=assistant.d.ts.map

package/dist/cjs/telemetry/assistant.d.ts.map

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

package/dist/cjs/telemetry/assistant.js

@@ -0,0 +1,43 @@
+"use strict";
+// =============================================================================
+// POST /api/admin/telemetry/assistant/stream (issue #536; moved here from the
+// API's `telemetry/dto/telemetry-assistant.dto.ts` by #702)
+// =============================================================================
+//
+// The request body is a zod schema. The response is a `text/event-stream`;
+// its frame payloads are the binding web ↔ API contract and are TYPES (the
+// API writes them, nothing parses them on the server), as they always were.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.telemetryAssistantRequestSchema = exports.telemetryAssistantTurnSchema = void 0;
+const zod_1 = require("zod");
+const constants_js_1 = require("./constants.js");
+const enum_js_1 = require("./enum.js");
+/**
+ * One earlier turn of the conversation: `role` (`user` or `assistant`) and
+ * `content` (at most {@link TELEMETRY_ASSISTANT_HISTORY_CONTENT_MAX} characters).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryAssistantTurnSchema = zod_1.z.object({
+    /** Who wrote the turn. */
+    role: (0, enum_js_1.wireEnum)(constants_js_1.TELEMETRY_ASSISTANT_TURN_ROLES),
+    /** The turn's text. */
+    content: zod_1.z.string().max(constants_js_1.TELEMETRY_ASSISTANT_HISTORY_CONTENT_MAX),
+});
+/**
+ * `POST /api/admin/telemetry/assistant/stream` body: `question` (trimmed,
+ * 1..{@link TELEMETRY_ASSISTANT_QUESTION_MAX} characters) and an optional
+ * `history` (oldest first, at most {@link TELEMETRY_ASSISTANT_HISTORY_MAX_TURNS}).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryAssistantRequestSchema = zod_1.z.object({
+    /** The new question, in natural language. */
+    question: zod_1.z.string().trim().min(1).max(constants_js_1.TELEMETRY_ASSISTANT_QUESTION_MAX),
+    /** Earlier turns of this conversation, oldest first. */
+    history: zod_1.z.array(exports.telemetryAssistantTurnSchema).max(constants_js_1.TELEMETRY_ASSISTANT_HISTORY_MAX_TURNS).optional(),
+});
+//# sourceMappingURL=assistant.js.map

package/dist/cjs/telemetry/assistant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant.js","sourceRoot":"","sources":["../../../src/telemetry/assistant.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,8EAA8E;AAC9E,4DAA4D;AAC5D,gFAAgF;AAChF,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,4EAA4E;AAC5E,gFAAgF;;;AAEhF,6BAAwB;AAExB,iDASwB;AACxB,uCAAqC;AAErC;;;;;;GAMG;AACU,QAAA,4BAA4B,GAAG,OAAC,CAAC,MAAM,CAAC;IACnD,0BAA0B;IAC1B,IAAI,EAAE,IAAA,kBAAQ,EAAC,6CAA8B,CAAC;IAC9C,uBAAuB;IACvB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,sDAAuC,CAAC;CACjE,CAAC,CAAC;AASH;;;;;;;GAOG;AACU,QAAA,+BAA+B,GAAG,OAAC,CAAC,MAAM,CAAC;IACtD,6CAA6C;IAC7C,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,+CAAgC,CAAC;IACxE,wDAAwD;IACxD,OAAO,EAAE,OAAC,CAAC,KAAK,CAAC,oCAA4B,CAAC,CAAC,GAAG,CAAC,oDAAqC,CAAC,CAAC,QAAQ,EAAE;CACrG,CAAC,CAAC"}

package/dist/cjs/telemetry/config.d.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+/**
+ * `PUT /api/admin/telemetry/config` body: the stored namespace, with
+ * `instanceId` optional (absent keeps the stored value).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+export declare const updateTelemetryConfigSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    retentionDays: z.ZodNumber;
+    query: z.ZodObject<{
+        maxRows: z.ZodNumber;
+        timeoutSeconds: z.ZodNumber;
+    }, z.core.$strip>;
+    assistant: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        provider: z.ZodNullable<z.ZodString>;
+        modelId: z.ZodNullable<z.ZodString>;
+        shareResults: z.ZodBoolean;
+        maxResultRowsToModel: z.ZodNumber;
+        maxSteps: z.ZodNumber;
+    }, z.core.$strip>;
+    instanceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * The `PUT /api/admin/telemetry/config` body.
+ *
+ * @stability stable
+ */
+export type UpdateTelemetryConfigInput = z.infer<typeof updateTelemetryConfigSchema>;
+/**
+ * `GET /api/admin/telemetry/config` (and the `PUT` response): the stored
+ * namespace plus `available`, `retentionApplicable`, `instanceIdDefault`,
+ * `instanceIdEffective`, `version` (send it back as `If-Match`), `updatedAt`
+ * and `updatedBy`.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+export declare const telemetryConfigResponseSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    retentionDays: z.ZodNumber;
+    instanceId: z.ZodNullable<z.ZodString>;
+    query: z.ZodObject<{
+        maxRows: z.ZodNumber;
+        timeoutSeconds: z.ZodNumber;
+    }, z.core.$strip>;
+    assistant: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        provider: z.ZodNullable<z.ZodString>;
+        modelId: z.ZodNullable<z.ZodString>;
+        shareResults: z.ZodBoolean;
+        maxResultRowsToModel: z.ZodNumber;
+        maxSteps: z.ZodNumber;
+    }, z.core.$strip>;
+    available: z.ZodBoolean;
+    retentionApplicable: z.ZodBoolean;
+    instanceIdDefault: z.ZodString;
+    instanceIdEffective: z.ZodString;
+    version: z.ZodNumber;
+    updatedAt: z.ZodNullable<z.ZodISODateTime>;
+    updatedBy: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        email: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * `GET /api/admin/telemetry/config`.
+ *
+ * @stability stable
+ */
+export type TelemetryConfigResponse = z.infer<typeof telemetryConfigResponseSchema>;
+/**
+ * `GET /api/telemetry/config`: the feature flag every signed-in client reads
+ * (`available`, `enabled`, `assistantEnabled`).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+export declare const telemetryPublicConfigSchema: z.ZodObject<{
+    available: z.ZodBoolean;
+    enabled: z.ZodBoolean;
+    assistantEnabled: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * `GET /api/telemetry/config`.
+ *
+ * @stability stable
+ */
+export type TelemetryPublicConfig = z.infer<typeof telemetryPublicConfigSchema>;
+//# sourceMappingURL=config.d.ts.map

package/dist/cjs/telemetry/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/telemetry/config.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;iBAGtC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAErF;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqCxC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;;;iBAUtC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}

package/dist/cjs/telemetry/config.js

@@ -0,0 +1,101 @@
+"use strict";
+// =============================================================================
+// /api/admin/telemetry/config and /api/telemetry/config (issue #534; moved
+// here from the API's `telemetry/dto/telemetry-config.dto.ts` by #702)
+// =============================================================================
+//
+// The PUT body IS the stored `telemetry` namespace, so a form can send back
+// exactly what it loaded (minus the provenance fields the response adds).
+// Full replace: `assistant.provider` / `assistant.modelId` sent as `null`
+// clear a stored value.
+//
+// ONE EXCEPTION TO "FULL": `instanceId` (#565) is OPTIONAL in the PUT body.
+// Absent keeps the stored value, `null` returns to the application-slug
+// default, a string overrides it. A client written before it existed must not
+// get a 400, nor silently reset an identity an administrator set, merely by
+// saving the page. The response always carries it, plus `instanceIdDefault` /
+// `instanceIdEffective` so a form can show what `null` currently means.
+//
+// No credential is part of any of these shapes and none may be added.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.telemetryPublicConfigSchema = exports.telemetryConfigResponseSchema = exports.updateTelemetryConfigSchema = void 0;
+const zod_1 = require("zod");
+const settings_js_1 = require("./settings.js");
+/**
+ * `PUT /api/admin/telemetry/config` body: the stored namespace, with
+ * `instanceId` optional (absent keeps the stored value).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.updateTelemetryConfigSchema = settings_js_1.telemetrySettingsSchema.extend({
+    /** Optional here: absent keeps the stored value, `null` returns to the default, a string overrides it. */
+    instanceId: settings_js_1.telemetrySettingsSchema.shape.instanceId.optional(),
+});
+/**
+ * `GET /api/admin/telemetry/config` (and the `PUT` response): the stored
+ * namespace plus `available`, `retentionApplicable`, `instanceIdDefault`,
+ * `instanceIdEffective`, `version` (send it back as `If-Match`), `updatedAt`
+ * and `updatedBy`.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryConfigResponseSchema = settings_js_1.telemetrySettingsSchema.extend({
+    /**
+     * Whether a telemetry store is configured (admin UI or deployment default):
+     * a host and the reader login with its password. While false, `enabled` is
+     * stored but nothing is exported or queryable.
+     */
+    available: zod_1.z.boolean(),
+    /**
+     * Whether the GreptimeDB admin login is configured (admin UI or deployment
+     * default), which retention needs. While false, `retentionDays` is stored
+     * but not applied.
+     */
+    retentionApplicable: zod_1.z.boolean(),
+    /**
+     * What a `null` `instanceId` resolves to: the application slug (`APP_SLUG`,
+     * derived from the product name). Read-only.
+     */
+    instanceIdDefault: zod_1.z.string(),
+    /**
+     * The identifier currently stamped as the `app.instance.id` resource
+     * attribute on exported telemetry: `instanceId` when set, else
+     * `instanceIdDefault`. Read-only.
+     */
+    instanceIdEffective: zod_1.z.string(),
+    /** The system-settings row version — send it back as `If-Match` on `PUT`. `0` when nothing is stored yet. */
+    version: zod_1.z.number().int(),
+    /** When the namespace was last saved, or `null` when nothing is stored yet. */
+    updatedAt: zod_1.z.iso.datetime().nullable(),
+    /** Who saved it last, or `null`. */
+    updatedBy: zod_1.z
+        .object({
+        /** The user's id. */
+        id: zod_1.z.string(),
+        /** The user's email. */
+        email: zod_1.z.string(),
+    })
+        .nullable(),
+});
+/**
+ * `GET /api/telemetry/config`: the feature flag every signed-in client reads
+ * (`available`, `enabled`, `assistantEnabled`).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryPublicConfigSchema = zod_1.z.object({
+    /** A telemetry store is configured (admin UI or deployment default). False hides every telemetry surface. */
+    available: zod_1.z.boolean(),
+    /** `telemetry.enabled` — whether this deployment is currently collecting telemetry. */
+    enabled: zod_1.z.boolean(),
+    /**
+     * `telemetry.assistant.enabled` — whether the telemetry AI assistant is
+     * switched on. Whether the AI platform itself is on is `GET /api/ai/config`.
+     */
+    assistantEnabled: zod_1.z.boolean(),
+});
+//# sourceMappingURL=config.js.map

package/dist/cjs/telemetry/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/telemetry/config.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,2EAA2E;AAC3E,uEAAuE;AACvE,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,0EAA0E;AAC1E,wBAAwB;AACxB,EAAE;AACF,4EAA4E;AAC5E,wEAAwE;AACxE,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,wEAAwE;AACxE,EAAE;AACF,sEAAsE;AACtE,gFAAgF;;;AAEhF,6BAAwB;AAExB,+CAAwD;AAExD;;;;;;GAMG;AACU,QAAA,2BAA2B,GAAG,qCAAuB,CAAC,MAAM,CAAC;IACxE,0GAA0G;IAC1G,UAAU,EAAE,qCAAuB,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE;CAChE,CAAC,CAAC;AASH;;;;;;;;GAQG;AACU,QAAA,6BAA6B,GAAG,qCAAuB,CAAC,MAAM,CAAC;IAC1E;;;;OAIG;IACH,SAAS,EAAE,OAAC,CAAC,OAAO,EAAE;IACtB;;;;OAIG;IACH,mBAAmB,EAAE,OAAC,CAAC,OAAO,EAAE;IAChC;;;OAGG;IACH,iBAAiB,EAAE,OAAC,CAAC,MAAM,EAAE;IAC7B;;;;OAIG;IACH,mBAAmB,EAAE,OAAC,CAAC,MAAM,EAAE;IAC/B,6GAA6G;IAC7G,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACzB,+EAA+E;IAC/E,SAAS,EAAE,OAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACtC,oCAAoC;IACpC,SAAS,EAAE,OAAC;SACT,MAAM,CAAC;QACN,qBAAqB;QACrB,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE;QACd,wBAAwB;QACxB,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;KAClB,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC;AASH;;;;;;GAMG;AACU,QAAA,2BAA2B,GAAG,OAAC,CAAC,MAAM,CAAC;IAClD,6GAA6G;IAC7G,SAAS,EAAE,OAAC,CAAC,OAAO,EAAE;IACtB,uFAAuF;IACvF,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE;IACpB;;;OAGG;IACH,gBAAgB,EAAE,OAAC,CAAC,OAAO,EAAE;CAC9B,CAAC,CAAC"}