@morsehq-dev/sdk 0.4.0-rc.1

package/dist/index.d.cts

@@ -0,0 +1,464 @@
+import { R as RunHandle, a as RunOptions, b as SpanOptions, S as SpanHandle } from './tracing-BYAqjT5Q.cjs';
+export { C as ContextSegment, S as SpanData, a as SpanStatus, b as SpanType } from './spans-DZtMuBvc.cjs';
+export { AnthropicClientLike, AnthropicContentBlockParam, AnthropicMessageCreateParams, AnthropicMessageParam, AnthropicMessageResponse, AnthropicTextBlockParam, AnthropicToolParam, AnthropicToolResultBlockParam, AnthropicToolUseBlockParam, AnthropicUsage, InstrumentAnthropicOptions, MAX_SEGMENT_CONTENT_BYTES, extractAnthropicSegments, instrumentAnthropic, isAnthropicWrapped, uninstallAnthropic, wrapAnthropic } from './anthropic/index.cjs';
+
+/** Public SDK option. Mirrors `redaction` in `init()`. */
+interface RedactionOptions {
+    /** Master switch. Default: `true`. */
+    enabled?: boolean;
+    /** Pattern keys to selectively disable (mandatory keys rejected). */
+    disabledPatterns?: string[];
+    /** Customer-supplied regex strings (ECMAScript syntax). */
+    extraPatterns?: string[];
+}
+/** Validated, frozen config fed into `redactString` / `redactValue`. */
+interface RedactionConfig {
+    enabled: boolean;
+    /** Keys actually applied, in stable order. */
+    enabledPatterns: ReadonlySet<string>;
+    /** Custom compiled regexes — applied last, with `[REDACTED:custom]`. */
+    extraCompiled: readonly RegExp[];
+}
+
+interface BatchTransportOptions {
+    endpoint: string;
+    apiKey: string;
+    /** Max wait between flushes, in seconds. Default: 2.0. */
+    flushIntervalSeconds?: number;
+    /** Max events per batch. Default: 100. */
+    maxBatchSize?: number;
+    /** Max queued events before drop. Default: 10_000. */
+    maxQueueSize?: number;
+    /** Timeout for the underlying fetch, in ms. Default: 5_000. */
+    fetchTimeoutMs?: number;
+    /**
+     * Pluggable fetch implementation. Defaults to `globalThis.fetch`.
+     * Useful for tests.
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Wire shape for a single log record. Mirrors the Python SDK payload at
+ * `apps/sdk/python/src/morse/client.py:191-211` and the backend
+ * `SimpleLogsIngestController.ingest` contract
+ * (`apps/api/apps/logs/controllers.py:66-134`).
+ */
+interface LogRecordPayload {
+    timestamp: string;
+    severity: string;
+    service_name: string;
+    body: string;
+    attributes: Record<string, unknown>;
+    trace_id: string | null;
+    span_id: string | null;
+}
+type TelemetryEvent = {
+    traces: unknown[];
+} | {
+    logs: LogRecordPayload[];
+} | Record<string, unknown>;
+/**
+ * Quota / rate-limit state parsed from a 429 batch-POST response.
+ *
+ * Mirrors Python's `transport.py::BatchTransport._record_quota_state` /
+ * `quota_state()` (TQE-04 / MHQ-676) field-for-field, camelCased per this
+ * codebase's convention (`received_at` -> `receivedAt`, etc.). Two known
+ * body shapes:
+ *
+ *   - `event_limit_exceeded` (traces controllers) — flat body with
+ *     `current_count` / `limit_count` / `plan_id` / `period_start` /
+ *     `upgrade_url` / `sample_rate_url`.
+ *   - `RATE_LIMIT_INGEST` (ingest rate-limit middleware) — nested
+ *     `{ error: { code, message, details: { limit, plan } } }`.
+ *
+ * Anything else is recorded as `kind: "unknown"` so the state surface
+ * still reflects that ingest is throttled even when the body doesn't
+ * parse into a known shape.
+ */
+interface QuotaState {
+    kind: "event_limit" | "rate_limit" | "unknown";
+    status: number;
+    /** Epoch seconds, matching Python's `time.time()`. */
+    receivedAt: number;
+    message?: string;
+    currentCount?: number;
+    limitCount?: number;
+    planId?: string;
+    periodStart?: string;
+    upgradeUrl?: string;
+    sampleRateUrl?: string;
+    quotaLimit?: number;
+    quotaRemaining?: number;
+    quotaReset?: number;
+    retryAfterSeconds?: number;
+}
+declare class BatchTransport {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly flushIntervalSeconds;
+    private readonly maxBatchSize;
+    private readonly maxQueueSize;
+    private readonly fetchTimeoutMs;
+    private readonly fetchImpl;
+    private queue;
+    private timer;
+    private flushing;
+    private closed;
+    private inflight;
+    constructor(opts: BatchTransportOptions);
+    /** Enqueue an event. Non-blocking. Returns false if the queue is full. */
+    track(event: TelemetryEvent): boolean;
+    /** Block until all currently-queued events have been sent. */
+    flush(): Promise<void>;
+    /** Stop the background timer. After this call, `track()` is a no-op. */
+    shutdown(): Promise<void>;
+    private tick;
+    private sendBatch;
+    private post;
+}
+
+/**
+ * W3C Trace Context propagation — inject and extract `traceparent` headers.
+ *
+ * W3C traceparent format: `{version}-{trace_id}-{span_id}-{flags}`
+ *   - version  : "00" (fixed)
+ *   - trace_id : 32 lowercase hex chars (128-bit)
+ *   - span_id  : 16 lowercase hex chars (64-bit)
+ *   - flags    : "01" (sampled, always set for Morse)
+ *
+ * Example: `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01`
+ *
+ * References:
+ *   https://www.w3.org/TR/trace-context/
+ */
+declare const W3C_TRACEPARENT_HEADER = "traceparent";
+/**
+ * Build a W3C traceparent value from explicit IDs.
+ *
+ * Useful when you have a trace_id / span_id from somewhere other than
+ * the active context (e.g., re-emitting an upstream trace's IDs).
+ */
+declare function formatTraceparent(traceId: string, spanId: string): string;
+/**
+ * Inject the W3C `traceparent` header derived from the active trace
+ * context into the supplied headers object. Mutates and returns the
+ * object for convenience.
+ *
+ * No-op (returns headers unchanged) if no trace is active.
+ *
+ * Accepts both `Headers` (from fetch) and a plain dict.
+ */
+declare function injectTraceparent<T extends HeadersLike>(headers: T): T;
+interface ExtractedContext {
+    traceId: string;
+    parentSpanId: string;
+}
+/**
+ * Parse a W3C traceparent header and return `{ traceId, parentSpanId }`,
+ * or `null` if the header is missing or malformed.
+ *
+ * Validation per W3C §3.2.3:
+ *   - exactly 4 dash-separated fields
+ *   - version === "00"
+ *   - trace_id is 32 lowercase hex chars (and not all-zero)
+ *   - span_id  is 16 lowercase hex chars (and not all-zero)
+ */
+declare function extractTraceparent(headers: HeadersLike | string | null | undefined): ExtractedContext | null;
+/**
+ * Convenience for outbound `fetch`: build a fresh `Headers` object with
+ * the traceparent injected, layered on top of the caller's input.
+ */
+declare function injectIntoRequestInit(init?: RequestInit): RequestInit;
+type HeadersLike = Headers | Record<string, string | string[] | undefined> | {
+    get(name: string): string | null;
+} | {
+    [key: string]: unknown;
+};
+
+/**
+ * Phase 12.5 Tier 1.2 — TypeScript SDK `log()` export.
+ *
+ * Closes the TS side of Feature #4 "Gap A": before this module, customers
+ * using the TS SDK had no way to populate the Logs tab of a trace's
+ * Correlation panel without standing up their own OTel collector. The
+ * Python SDK already had `morse.log(...)` (AGE-240); this is the
+ * cross-language peer.
+ *
+ * Semantics mirror Python's `morse.log()`
+ * (`apps/sdk/python/src/morse/__init__.py:360-411`):
+ *
+ *   - Default severity: "info" (case-normalised to upper on the wire).
+ *   - Default service_name: "morse-sdk-ts" (overridable).
+ *   - Auto-reads the active trace_id + span_id from the SDK's existing
+ *     `node:async_hooks.AsyncLocalStorage` context (re-uses
+ *     `getActiveTraceState()` — the same primitive `run()`/`span()` use).
+ *   - Batched: the record is enqueued on the existing `BatchTransport`,
+ *     which flushes it to `/api/v1/logs/ingest` (derived from the traces
+ *     batch endpoint) on the next tick. NO synchronous fetch per call.
+ *   - Internal errors are absorbed via `absorbErrorsSync` so they never
+ *     propagate into the customer's logging call. Mirrors the Python
+ *     `@absorb_errors` decorator pattern.
+ *
+ * Wire shape: `{ logs: [{ timestamp, severity, service_name, body,
+ * attributes, trace_id, span_id }] }`. See `apps/api/apps/logs/
+ * controllers.py:66-134` for the API contract.
+ */
+/** Log severity — case-insensitive on input, upper-cased on the wire. */
+type LogSeverity = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+/** Options accepted by `log()`. */
+interface LogOptions {
+    /** Default: `"info"`. Upper-cased server-side. */
+    severity?: LogSeverity;
+    /** Free-form structured fields persisted on the record. */
+    attributes?: Record<string, unknown>;
+    /**
+     * Override the auto-detected trace_id. Use only when emitting on
+     * behalf of a known external trace (rare).
+     */
+    traceId?: string;
+    /** Override the auto-detected span_id. Same caveat as `traceId`. */
+    spanId?: string;
+    /** Logical service tag. Default: `"morse-sdk-ts"`. */
+    serviceName?: string;
+}
+/**
+ * Emit a log record correlated to the current trace context.
+ *
+ * Auto-correlates to the surrounding `morse.run()` /
+ * `morse.span()` if one is active. Inside a trace, the record's
+ * `trace_id` + `span_id` are filled in from `AsyncLocalStorage`;
+ * outside a trace, both fields are `null` and the record is still
+ * accepted by the backend (it surfaces in the service-wide Logs view
+ * but not on any individual trace's Correlation panel).
+ *
+ * Non-blocking. Batched alongside trace events on the existing
+ * transport — flushes at the SDK's configured interval (default 2s).
+ * Internal errors are absorbed; this call never throws.
+ *
+ * Silent no-op when the SDK isn't initialised (no `MORSE_API_KEY`
+ * and no explicit `init()` call).
+ *
+ * @example
+ * ```ts
+ * import { init, runTraced, log } from "@morsehq-dev/sdk";
+ *
+ * init({ apiKey: process.env.MORSE_API_KEY });
+ *
+ * await runTraced({ agentName: "lead-qualifier" }, async () => {
+ *   log("starting search", { attributes: { query: "morse" } });
+ *   const results = await search();
+ *   log("search complete", {
+ *     severity: "info",
+ *     attributes: { result_count: results.length },
+ *   });
+ * });
+ * ```
+ */
+declare const log: (message: string, options?: LogOptions | undefined) => void | undefined;
+
+/**
+ * `@morsehq-dev/sdk` — TypeScript SDK for Morse observability.
+ *
+ * V2 module-level singleton API:
+ *
+ * ```ts
+ * import * as morse from "@morsehq-dev/sdk";
+ *
+ * // Three-step zero-setup integration:
+ * //   1. Generate an API key in the Morse dashboard.
+ * //   2. npm install @morsehq-dev/sdk
+ * //   3. Set MORSE_API_KEY in your environment.
+ *
+ * morse.track({ agentId: "lead-qualifier", runData: { success: true } });
+ *
+ * // Or call init() explicitly to override env-var resolution:
+ * morse.init({
+ *   apiKey: "mhq_xxx", // pragma: allowlist secret — placeholder, not a key
+ *   endpoint: "https://api.morsehq.dev/api/v1/traces/batch",
+ *   flushIntervalSeconds: 2,
+ * });
+ * ```
+ *
+ * Non-invasive guarantee: every public function is wrapped with
+ * `absorbErrors`. Telemetry never throws back at the caller; internal
+ * errors are reported out-of-band to Morse's Sentry instance.
+ *
+ * The internal `BatchTransport` and `TraceState` types back the singleton
+ * but are NOT part of the public API. Customers should never reach into
+ * the `_internal` directory.
+ */
+
+declare const version: string;
+/** Options accepted by `init()`. Mirrors Python's `init(...)` kwargs. */
+interface InitOptions {
+    /** API key (starts with "mhq_"). Required if no `MORSE_API_KEY` env var. */
+    apiKey?: string;
+    /** Full ingestion URL. Defaults to the production Railway endpoint. */
+    endpoint?: string;
+    /** Seconds between batch flushes. Default: 2. */
+    flushIntervalSeconds?: number;
+    /**
+     * Client-side PII redaction. Default-on with the canonical eight-pattern
+     * catalogue. Set `enabled: false` to opt out (the server-side mandatory
+     * floor still applies). Mandatory patterns (`api_key_prefixed`, `jwt`,
+     * `credit_card`, `ssn_us`) cannot be added to `disabledPatterns` —
+     * `init()` throws on that.
+     */
+    redaction?: RedactionOptions;
+    /**
+     * INTERNAL USE ONLY — resource-level source label for Morse's own
+     * dogfood emitters. Mirrors the Python SDK's `init(source=...)` kwarg
+     * (PR #90). Accepted values: `"copilot" | "investigator" | "refagent"
+     * | "ui-bot"`. Any other value (including misspellings) is silently
+     * dropped — falls back to the `MORSE_INTERNAL_SOURCE` env var.
+     * Customers should not set this.
+     */
+    source?: string;
+}
+/** Single agent-run payload accepted by `track()`. */
+interface TrackOptions {
+    /** User-defined agent name (e.g., "lead-qualifier"). */
+    agentId: string;
+    /** Run-data dict. Shape mirrors backend Run model. */
+    runData: Record<string, unknown>;
+}
+/** High-level outcome shape accepted by `record()` (V1 ergonomic API). */
+interface RunRecord {
+    agent: string;
+    success?: boolean;
+    outcome?: string;
+    cost?: number;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    durationMs?: number;
+    errorMessage?: string;
+    metadata?: Record<string, unknown>;
+    status?: "completed" | "failed" | "timed_out";
+}
+/**
+ * Initialize the Morse SDK singleton. Call once at application
+ * startup. After this call, `track()`, `batchTrack()`, `run()`, and
+ * `flush()` are wired up to the configured endpoint.
+ *
+ * `endpoint` is optional — when omitted, the SDK resolves in this order:
+ *   1. `MORSE_ENDPOINT` env var (if set)
+ *   2. The default Railway production URL.
+ *
+ * `MORSE_DISABLED=1` overrides everything: `init()` is a no-op.
+ *
+ * Calling `init()` a second time replaces the singleton — the previous
+ * transport is shut down cleanly and a new one is constructed.
+ *
+ * Validation errors (e.g., disabling a mandatory redaction pattern, an
+ * uncompilable extra pattern) are deliberately NOT absorbed — they
+ * propagate as `Error`s so the developer sees the misconfiguration at
+ * application startup. All other errors raised from internal SDK paths
+ * are absorbed via the per-call wrappers downstream.
+ */
+declare function init(options?: InitOptions): void;
+/**
+ * Submit a single agent run to the ingestion endpoint. Non-blocking;
+ * returns immediately. Silently no-ops if the SDK isn't initialised.
+ */
+declare const track: (options: TrackOptions) => void | undefined;
+/** Submit multiple agent runs in bulk. Silently no-ops if uninitialised. */
+declare const batchTrack: (runs: Record<string, unknown>[]) => void | undefined;
+/**
+ * High-level convenience: record an agent outcome with named fields.
+ *
+ * Builds a synthetic single-span `agent`-type trace and submits it through
+ * the same `traces`-shaped emission path `run()`/`span()` use (MHQ-746) —
+ * mirrors Python's `client.py::record()`. The live dev-api backend has no
+ * `runs` ingest route; sending through `state.transport.track()` (the
+ * shape `track()`/`batchTrack()` still use, matching Python's equally
+ * unmigrated `track()`/`batch_track()`) 422s silently. See MHQ-746.
+ */
+declare const record: (rec: RunRecord) => void | undefined;
+/**
+ * Open a traced agent run, executing `fn` inside the trace context.
+ * Mirrors Python's `morse.run(...)` context manager.
+ *
+ * Two overloads are supported:
+ *   - `run(name, fn)` — quick form with default options.
+ *   - `run({ agentName, incomingTraceparent }, fn)` — full options.
+ *
+ * Async callers receive a Promise; sync callers receive the value
+ * directly. The function's return value is forwarded to the caller.
+ */
+declare function run<T>(name: string, fn: (handle: RunHandle) => T): T | undefined;
+declare function run<T>(options: RunOptions, fn: (handle: RunHandle) => T): T | undefined;
+/** Async variant of `run` — exported for callers who want explicit typing. */
+declare function runTraced<T>(options: RunOptions, fn: (handle: RunHandle) => Promise<T>): Promise<T | undefined>;
+/**
+ * Attach cost-attribution dimensions to the active trace (MHQ-751). Call
+ * once per request (e.g. in middleware) to propagate `customerId`,
+ * `feature`, `env`, `team`, etc. to all child spans downstream. Values are
+ * coerced to strings. No-op outside an active trace — never throws.
+ * Mirrors Python's `morse_ai.set_context(**dims)`.
+ */
+declare function setContext(dims: Record<string, unknown>): void;
+/** Start a child span under the active trace. Returns null if no trace. */
+declare function startSpan(options: SpanOptions): SpanHandle | null;
+/** Run `fn` inside a child span. No-op if no trace is active. */
+declare function span<T>(options: SpanOptions, fn: (handle: SpanHandle | null) => T): T;
+/** Async variant of `span`. */
+declare function spanAsync<T>(options: SpanOptions, fn: (handle: SpanHandle | null) => Promise<T>): Promise<T>;
+/** Block until all queued events have been sent. Silent on uninit / errors. */
+declare const flush: () => Promise<void | undefined>;
+/**
+ * Latest ingest quota / rate-limit state observed by the SDK, or `null`.
+ *
+ * TQE-04 (MHQ-676/MHQ-749): when the Morse backend answers a telemetry
+ * batch with HTTP 429 — the monthly event limit (`event_limit_exceeded`)
+ * or the per-second ingest rate limit (`RATE_LIMIT_INGEST`) — the
+ * transport parses the response and stores it. This function exposes
+ * that state so host applications can alert on quota exhaustion instead
+ * of discovering it from missing telemetry. Mirrors Python's
+ * `morse_ai.quota_state()`.
+ *
+ * Returns `null` when the SDK is uninitialized or no 429 has been
+ * observed. The object includes at least `kind` (`"event_limit"`,
+ * `"rate_limit"`, or `"unknown"`), `status`, and `receivedAt` (epoch
+ * seconds); event-limit states add `currentCount` / `limitCount` /
+ * `planId` / `periodStart` / `upgradeUrl`.
+ */
+declare const quotaState: () => QuotaState | null | undefined;
+/** Flush and stop the background transport. Call on app exit. */
+declare const shutdown: () => Promise<void | undefined>;
+/**
+ * Reset the module-level singleton for tests. Customer code must NOT
+ * call this — the singleton is meant to live for the process lifetime.
+ *
+ * @internal
+ */
+declare function _resetForTesting(): void;
+/**
+ * Inject an alternate transport factory for tests (e.g., a mock that
+ * captures sent payloads instead of opening a fetch).
+ *
+ * @internal
+ */
+declare function _setTransportFactoryForTesting(factory: (opts: {
+    apiKey: string;
+    endpoint: string;
+    flushIntervalSeconds: number;
+}) => BatchTransport): void;
+/**
+ * Read the most recently completed trace entry, for test assertions.
+ *
+ * @internal
+ */
+declare function _getLastTraceForTesting(): {
+    trace: unknown;
+    spans: unknown[];
+} | null;
+/**
+ * Read the active trace state, for test assertions.
+ *
+ * @internal
+ */
+declare function _getActiveTraceStateForTesting(): unknown;
+
+export { type InitOptions, type LogOptions, type LogSeverity, type QuotaState, type RedactionConfig, type RedactionOptions, RunHandle, RunOptions, type RunRecord, SpanHandle, SpanOptions, type TrackOptions, W3C_TRACEPARENT_HEADER, _getActiveTraceStateForTesting, _getLastTraceForTesting, _resetForTesting, _setTransportFactoryForTesting, batchTrack, extractTraceparent, flush, formatTraceparent, init, injectIntoRequestInit, injectTraceparent, log, quotaState, record, run, runTraced, setContext, shutdown, span, spanAsync, startSpan, track, version };