@forge-sdk/telemetry

import * as api from '@forge-sdk/telemetry';

export interface AuditEntry {
  /** Sequential index in the trail (0-based). */
  readonly index: number;
  /** The audit event. */
  readonly event: AuditEvent;
}

export class AuditTrail {
  constructor(agentDid: string);
  append(event: AuditEvent): void;
  entries(): readonly AuditEntry[];
  len(): number;
  isEmpty(): boolean;
  last(): AuditEntry | undefined;
  agentDid(): string;
  filterByKind(kind: AuditEventKindType): AuditEntry[];
}

export interface CompletedSpan {
  /** The unique identifier for this span. */
  readonly spanId: SpanId;
  /** The span name (e.g., "anvil.generate", "anvil.tool.invoke"). */
  readonly name: string;
  /** Key-value attributes associated with this span. */
  readonly attributes: ReadonlyArray<readonly [string, string]>;
  /** ISO 8601 timestamp of when the span was started. */
  readonly startTime: string;
  /** ISO 8601 timestamp of when the span was ended. */
  readonly endTime: string;
  /** The agent's OAS DID, if available. */
  readonly agentDid: string | undefined;
}

export interface SpanCollector {
  /** Record a completed span. */
  recordSpan(span: CompletedSpan): void;
  /** Retrieve all recorded spans. */
  spans(): CompletedSpan[];
  /** Clear all recorded spans. */
  clear(): void;
  /** Number of recorded spans. */
  len(): number;
  /** Returns true if no spans have been recorded. */
  isEmpty(): boolean;
}

export class NoopCollector implements SpanCollector {
  recordSpan(_span: CompletedSpan): void;
  spans(): CompletedSpan[];
  clear(): void;
  len(): number;
  isEmpty(): boolean;
}

export class InMemoryCollector implements SpanCollector {
  recordSpan(span: CompletedSpan): void;
  spans(): CompletedSpan[];
  clear(): void;
  len(): number;
  isEmpty(): boolean;
}

export class InMemoryTelemetry implements TelemetryContract {
  constructor(agentDid?: string);
  startSpan(name: string, attributes: ReadonlyArray<readonly [string, string]>): SpanId;
  endSpan(spanId: SpanId): void;
  emitEvent(event: AuditEvent): void;
  flush(): void;
  completedSpans(): CompletedSpan[];
  events(): AuditEvent[];
  clear(): void;
  spanCount(): number;
  eventCount(): number;
}

export const AuditEventKind /* type inferred in source */;

export type AuditEventKindType =
  (typeof AuditEventKind)[keyof typeof AuditEventKind];

export class SpanId {
  readonly value: string;
  static generate(): SpanId;
  static fromString(id: string): SpanId;
  toString(): string;
}

export class AuditEvent {
  readonly kind: AuditEventKindType;
  readonly agentDid: string;
  readonly timestamp: string;
  readonly details: Record<string, unknown>;
  readonly signature: string | undefined;
  static create(
    kind: AuditEventKindType,
    agentDid: string,
    details: Record<string, unknown>
  ): AuditEvent;
  withSignature(signature: string): AuditEvent;
  isSigned(): boolean;
  toJSON(): Record<string, unknown>;
}

export interface TelemetryContract {
  /**
   * Start a new span with the given name and attributes.
   *
   * @param name - The span name (use dotted notation, e.g., "anvil.generate").
   * @param attributes - Key-value pairs of span attributes.
   * @returns A unique SpanId for the started span.
   */
  startSpan(name: string, attributes: ReadonlyArray<readonly [string, string]>): SpanId;

  /**
   * End a previously started span.
   *
   * @param spanId - The ID returned by startSpan.
   */
  endSpan(spanId: SpanId): void;

  /**
   * Emit an audit event for the agent's audit trail.
   *
   * @param event - The audit event to record.
   */
  emitEvent(event: AuditEvent): void;

  /**
   * Flush any buffered telemetry data to the backend.
   *
   * @throws {TelemetryError} If the flush operation fails.
   */
  flush(): void;
}

export class NoopTelemetry implements TelemetryContract {
  startSpan(_name: string, _attributes: ReadonlyArray<readonly [string, string]>): SpanId;
  endSpan(_spanId: SpanId): void;
  emitEvent(_event: AuditEvent): void;
  flush(): void;
}

export const TelemetryErrorCode /* type inferred in source */;

export type TelemetryErrorCodeType =
  (typeof TelemetryErrorCode)[keyof typeof TelemetryErrorCode];

export class TelemetryError extends Error {
  readonly code: TelemetryErrorCodeType;
  static spanNotFound(spanId: string): TelemetryError;
  static spanAlreadyClosed(spanId: string): TelemetryError;
  static auditEntryInvalid(reason: string): TelemetryError;
  static auditTrailCorrupted(index: number, reason: string): TelemetryError;
  static flushFailed(reason: string): TelemetryError;
  static collectorFull(capacity: number): TelemetryError;
  static exportFailed(reason: string): TelemetryError;
}

export {
  AuditEventKind,
  type AuditEventKindType,
  SpanId,
  AuditEvent,
  type TelemetryContract,
  NoopTelemetry,
} from './contract.js';

export {
  type CompletedSpan,
  type SpanCollector,
  NoopCollector,
  InMemoryCollector,
  InMemoryTelemetry,
} from './collector.js';

export { type AuditEntry, AuditTrail } from './audit.js';

export {
  TelemetryErrorCode,
  type TelemetryErrorCodeType,
  TelemetryError,
} from './error.js';