/**
 * OTLP Channel State Types — Capability descriptor advertised by the agent
 * host on the root channel so clients can discover the URIs of any
 * OpenTelemetry signal channels (`ahp-otlp:` scheme) the host emits.
 *
 * @module channels-otlp/state
 */

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

// ─── TelemetryCapabilities ───────────────────────────────────────────────────

/**
 * OTLP telemetry channels the agent host emits.
 *
 * Each field, when present, is either a literal channel URI or an
 * [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570) URI template
 * a client expands and then subscribes to. Absent fields indicate the host
 * does not emit that signal.
 *
 * Channel URIs use the `ahp-otlp:` scheme. The scheme identifies the
 * protocol (OpenTelemetry over AHP) so clients can recognise the channel
 * type by URI alone; the host is free to choose any authority/path that
 * makes sense for its implementation. Clients MUST treat the URI as
 * opaque (apart from expanding any well-known template variables defined
 * below) and subscribe with the resulting concrete URI.
 *
 * Payloads delivered on these channels are OTLP/JSON values — see
 * [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto)
 * for the wire shapes (`ExportLogsServiceRequest`,
 * `ExportTraceServiceRequest`, `ExportMetricsServiceRequest`).
 *
 * @category Telemetry
 */
export interface TelemetryCapabilities {
  /**
   * Channel URI (or RFC 6570 URI template) for OTLP log records
   * (`otlp/exportLogs` notifications).
   *
   * The following template variables are defined by this protocol; any
   * other variable name MUST be ignored by clients (there is no
   * protocol-defined way to obtain values for unknown variables):
   *
   * | Variables in template | Meaning                                                                                                 |
   * | --------------------- | ------------------------------------------------------------------------------------------------------- |
   * | _(none)_              | The host does not support subscriber-side severity filtering. The template is itself a subscribable URI. |
   * | `{level}`             | Minimum OTLP severity to deliver. Expand to one of the [OTLP `SeverityNumber`](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber) short names (case-insensitive): `trace`, `debug`, `info`, `warn`, `error`, `fatal`. The server delivers log records whose `severityNumber` falls in the corresponding band or above. |
   *
   * Hosts SHOULD honour the expanded `{level}`; clients MUST still filter
   * defensively in case a host ignores the parameter. Hosts that do not
   * advertise `{level}` deliver all severities.
   *
   * Future protocol versions MAY add new well-known variables (e.g. scope
   * or attribute filters).
   */
  logs?: URI;
  /**
   * Channel URI for OTLP spans (`otlp/exportTraces` notifications). No
   * template variables are defined by this protocol version.
   */
  traces?: URI;
  /**
   * Channel URI for OTLP metric data points (`otlp/exportMetrics`
   * notifications). No template variables are defined by this protocol
   * version.
   */
  metrics?: URI;
}
