Types

type BecauseOptions = {
  apiKey?: string;
  apiUrl?: string;
  debug?: boolean;
};

type TraceOptions = {
  input?: JsonObject;
  metadata?: Metadata;
  retentionPeriod?: RetentionPeriod;
};

type RetentionPeriod = '1d' | '7d' | '30d' | '90d' | '1y';

type IngestResult = {
  traceId: string;
};

type SpanType =
  'message' | 'json' | 'table' | 'http' | 'chart' | 'llm' | 'image' | 'db';

type SpanOptions = {
  metadata?: DbSpanMetadata;
  input?: JsonObject;
  output?: JsonObject;
  alerts?: SpanAlert[];
  durationMs?: number;
  redact?: string[];
};

type DbSpanOptions = {
  metadata?: DbSpanMetadata;
  input?: JsonObject;
  output?: JsonObject;
  durationMs?: number;
};

type DbSpanMetadata = {
  collection?: string;
  table?: string;
  queryType?: 'sql' | 'nosql';
};

type SpanAlert = {
  label?: string;
  level: 'warn' | 'error';
  gt?: number;
  lt?: number;
  checks: SpanAlertCheck[];
};

type SpanAlertCheck = {
  target?: string;
  value: number;
};

type HttpRequestInput = {
  method: HttpMethod;
  url: string;
  headers?: Record<string, string>;
  content_type?: HttpContentType;
  body?: JsonObject | string | null;
};

type HttpResponseOutput = {
  status: number;
  headers?: Record<string, string>;
  content_type?: HttpContentType;
  body?: JsonObject | string | null;
};

type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';

type HttpContentType = 'json' | 'form' | 'text' | null;

type LlmSpanInput = {
  prompt?: string;
  messages?: LlmMessage[];
  provider?: string;
  model?: string;
};

type LlmSpanOutput = {
  response?: string | JsonObject;
};

type LlmMessage = {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string;
};

type ImageSpanData = {
  url: string;
  label?: string;
};

type TableData = TableGroup | { tables: TableGroup[] };

type TableGroup = {
  title?: string;
  columns: TableColumn[];
  rows: unknown[][];
  rowHighlights?: (TableHighlight | null)[];
  cellHighlights?: (TableHighlight | null)[][];
};

type TableColumn =
  | string
  | {
      label: string;
      span?: number;
      highlight?: TableHighlight;
    };

type TableHighlight = 'danger' | 'warn' | 'success' | 'info' | 'muted';

type TableCellSpan = {
  readonly __cellSpan: true;
  readonly span: number;
  readonly value: unknown;
};

type ChartData = ChartGroup | { charts: ChartGroup[] };

type ChartGroup = {
  title?: string;
  type: ChartType;
  labels: string[];
  series: ChartSeries[];
  referenceLines?: ChartReferenceLine[];
};

type ChartType = 'line' | 'bar' | 'pie' | 'scatter';

type ChartSeries = {
  name?: string;
  data: number[];
};

type JsonObject = Record<string, unknown> | unknown[];

type Metadata = Record<string, string | number | boolean | null>;

import { BecauseError } from '@refactorlabs/because';

try {
  await because.startTrace('...', async () => {
    /* ... */
  });
} catch (err) {
  if (err instanceof BecauseError) {
    console.error(err.status, err.message);
  }
}

class BecauseError extends Error {
  readonly status: number;
}