/**
 * OTLP Channel Notifications — Server → client push of OpenTelemetry data
 * over AHP. One notification method per OTLP signal kind; the params'
 * `payload` field carries an OTLP/JSON `ExportXxxServiceRequest` value
 * verbatim.
 *
 * @module channels-otlp/notifications
 */

import type { URI } from '../common/state.js';

// ─── otlp/exportLogs ─────────────────────────────────────────────────────────

/**
 * Delivers a batch of OTLP log records to a client subscribed to the host's
 * logs channel (advertised on `TelemetryCapabilities.logs`).
 *
 * The `payload` field is an OTLP/JSON `ExportLogsServiceRequest` value
 * verbatim — i.e. an object of shape `{ resourceLogs: ResourceLogs[] }` as
 * defined by [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/logs/v1/logs_service.proto).
 * AHP does not redeclare the OTLP type system; clients SHOULD use an
 * OpenTelemetry SDK or schema to parse it.
 *
 * Like all stateless-channel notifications, this is ephemeral: it is not
 * replayed on reconnect. Subscribers receive only batches emitted after
 * their `subscribe` succeeds.
 *
 * @category Telemetry Notifications
 * @method otlp/exportLogs
 * @direction Server → Client
 * @messageType Notification
 * @version 1
 * @example
 * ```json
 * {
 *   "jsonrpc": "2.0",
 *   "method": "otlp/exportLogs",
 *   "params": {
 *     "channel": "ahp-otlp://logs",
 *     "payload": { "resourceLogs": [ /* OTLP/JSON ResourceLogs * / ] }
 *   }
 * }
 * ```
 */
export interface OtlpExportLogsParams {
  /** Channel URI this notification belongs to (an `ahp-otlp:` URI advertised on `TelemetryCapabilities.logs`). */
  channel: URI;
  /**
   * OTLP/JSON `ExportLogsServiceRequest` value. The top-level field is
   * `resourceLogs: ResourceLogs[]`; nested shapes are defined by
   * opentelemetry-proto and are not redeclared here.
   */
  payload: Record<string, unknown>;
}

// ─── otlp/exportTraces ───────────────────────────────────────────────────────

/**
 * Delivers a batch of OTLP spans to a client subscribed to the host's
 * traces channel (advertised on `TelemetryCapabilities.traces`).
 *
 * The `payload` field is an OTLP/JSON `ExportTraceServiceRequest` value
 * verbatim — i.e. an object of shape `{ resourceSpans: ResourceSpans[] }`
 * as defined by [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/trace/v1/trace_service.proto).
 *
 * @category Telemetry Notifications
 * @method otlp/exportTraces
 * @direction Server → Client
 * @messageType Notification
 * @version 1
 * @example
 * ```json
 * {
 *   "jsonrpc": "2.0",
 *   "method": "otlp/exportTraces",
 *   "params": {
 *     "channel": "ahp-otlp://traces",
 *     "payload": { "resourceSpans": [ /* OTLP/JSON ResourceSpans * / ] }
 *   }
 * }
 * ```
 */
export interface OtlpExportTracesParams {
  /** Channel URI this notification belongs to (an `ahp-otlp:` URI advertised on `TelemetryCapabilities.traces`). */
  channel: URI;
  /**
   * OTLP/JSON `ExportTraceServiceRequest` value. The top-level field is
   * `resourceSpans: ResourceSpans[]`; nested shapes are defined by
   * opentelemetry-proto and are not redeclared here.
   */
  payload: Record<string, unknown>;
}

// ─── otlp/exportMetrics ──────────────────────────────────────────────────────

/**
 * Delivers a batch of OTLP metric data points to a client subscribed to
 * the host's metrics channel (advertised on `TelemetryCapabilities.metrics`).
 *
 * The `payload` field is an OTLP/JSON `ExportMetricsServiceRequest` value
 * verbatim — i.e. an object of shape `{ resourceMetrics: ResourceMetrics[] }`
 * as defined by [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/metrics/v1/metrics_service.proto).
 *
 * @category Telemetry Notifications
 * @method otlp/exportMetrics
 * @direction Server → Client
 * @messageType Notification
 * @version 1
 * @example
 * ```json
 * {
 *   "jsonrpc": "2.0",
 *   "method": "otlp/exportMetrics",
 *   "params": {
 *     "channel": "ahp-otlp://metrics",
 *     "payload": { "resourceMetrics": [ /* OTLP/JSON ResourceMetrics * / ] }
 *   }
 * }
 * ```
 */
export interface OtlpExportMetricsParams {
  /** Channel URI this notification belongs to (an `ahp-otlp:` URI advertised on `TelemetryCapabilities.metrics`). */
  channel: URI;
  /**
   * OTLP/JSON `ExportMetricsServiceRequest` value. The top-level field is
   * `resourceMetrics: ResourceMetrics[]`; nested shapes are defined by
   * opentelemetry-proto and are not redeclared here.
   */
  payload: Record<string, unknown>;
}
