@glassflow-ai/rius 0.1.0 → 0.2.1

package/dist/index.d.cts

@@ -5,6 +5,11 @@ import { SpanExporter } from '@opentelemetry/sdk-trace-base';
 type Mask = (value: unknown, context?: {
     key: string;
 }) => unknown;
+/**
+ * Configuration shared by every client. Each option can also come from a
+ * `RIUS_*` environment variable; explicit options win over the environment,
+ * which wins over defaults.
+ */
 interface RiusOptions {
     endpoint?: string;
     apiKey?: string;
@@ -13,12 +18,29 @@ interface RiusOptions {
     sampleRate?: number;
     captureContent?: boolean;
     mask?: Mask;
+    /** Seconds between agent-lifetime heartbeat pings. */
+    heartbeatInterval?: number;
+    heartbeat?: boolean;
+    agentName?: string;
+    partialSpans?: boolean;
+    /** Seconds to debounce a pending-span snapshot after span start. */
+    partialSpansDelay?: number;
 }
 
+type HeartbeatTransport = (payload: Record<string, unknown>, timeoutMs: number) => Promise<void>;
+
+/** Options accepted by {@link init}, extending the shared configuration. */
 interface InitOptions extends RiusOptions {
     /** Inject an exporter instead of OTLP. The test seam; prefer this to mocking. */
     spanExporter?: SpanExporter;
+    /** Override the heartbeat HTTP transport. The test seam; prefer this to mocking fetch. */
+    heartbeatTransport?: HeartbeatTransport;
 }
+/**
+ * Handle over a configured tracer pipeline, returned by {@link init}.
+ * Exposes the lifecycle operations (`flush`, `shutdown`) and `ready`, which
+ * resolves with the auto-instrumentations that attached.
+ */
 declare class RiusClient {
     private readonly provider;
     private readonly health?;
@@ -30,13 +52,37 @@ declare class RiusClient {
     /**
      * Drains and tears down the provider, then releases the global registration
      * so a later init() can reconfigure the SDK.
+     *
+     * The heartbeat's final `stopped: true` ping is sent before the provider
+     * shuts down, so the backend hears "stopped" while the trace pipeline can
+     * still export it. Idempotent: `sender.stop()` no-ops on a second call, and
+     * the `beforeExit` listener is removed here so repeated init/shutdown
+     * cycles never leak listeners.
      */
     shutdown(): Promise<void>;
 }
+/**
+ * Initialize the SDK: build a tracer pipeline that exports OTLP traces and
+ * enable every bundled auto-instrumentation whose package is installed.
+ *
+ * Call it once, as early as possible in your process. A second call while a
+ * client is active logs a warning and returns the existing client unchanged;
+ * `shutdown()` releases the slot. `init()` is synchronous; await
+ * {@link RiusClient.ready} if instrumentation must be attached before your
+ * first span.
+ *
+ * The SDK installs no process exit hook: short-lived processes must call
+ * {@link RiusClient.flush} before exiting or spans still in the batch queue
+ * are lost.
+ */
 declare function init(options?: InitOptions): RiusClient;
 /** The SDK tracer. Scope name is wire-visible; do not parameterize it. */
 declare function getTracer(): Tracer;
 
+/**
+ * Observation kind. Values are OpenInference `openinference.span.kind`
+ * values, the taxonomy the platform's agent analytics group by.
+ */
 declare enum SpanKind {
     AGENT = "AGENT",
     LLM = "LLM",
@@ -46,6 +92,7 @@ declare enum SpanKind {
     CHAIN = "CHAIN"
 }
 
+/** Options for {@link startSpan} and {@link startAsCurrentSpan}. */
 interface SpanOptions {
     kind?: SpanKind;
     input?: unknown;
@@ -88,6 +135,10 @@ type SpanBody<T> = (observation: Observation) => Promise<T> | T;
 declare function startAsCurrentSpan<T>(name: string, fn: SpanBody<T>): Promise<T>;
 declare function startAsCurrentSpan<T>(name: string, options: SpanOptions, fn: SpanBody<T>): Promise<T>;
 
+/**
+ * Options for {@link startGeneration} and {@link startAsCurrentGeneration}:
+ * the model identity and request parameters an LLM span carries.
+ */
 interface GenerationOptions {
     model?: string;
     provider?: string;
@@ -136,6 +187,7 @@ type GenerationBody<T> = (generation: Generation) => Promise<T> | T;
 declare function startAsCurrentGeneration<T>(name: string, fn: GenerationBody<T>): Promise<T>;
 declare function startAsCurrentGeneration<T>(name: string, options: GenerationOptions, fn: GenerationBody<T>): Promise<T>;
 
+/** Options for {@link observe}. */
 interface ObserveOptions {
     name?: string;
     kind?: SpanKind;

package/dist/index.d.ts

@@ -5,6 +5,11 @@ import { SpanExporter } from '@opentelemetry/sdk-trace-base';
 type Mask = (value: unknown, context?: {
     key: string;
 }) => unknown;
+/**
+ * Configuration shared by every client. Each option can also come from a
+ * `RIUS_*` environment variable; explicit options win over the environment,
+ * which wins over defaults.
+ */
 interface RiusOptions {
     endpoint?: string;
     apiKey?: string;
@@ -13,12 +18,29 @@ interface RiusOptions {
     sampleRate?: number;
     captureContent?: boolean;
     mask?: Mask;
+    /** Seconds between agent-lifetime heartbeat pings. */
+    heartbeatInterval?: number;
+    heartbeat?: boolean;
+    agentName?: string;
+    partialSpans?: boolean;
+    /** Seconds to debounce a pending-span snapshot after span start. */
+    partialSpansDelay?: number;
 }
 
+type HeartbeatTransport = (payload: Record<string, unknown>, timeoutMs: number) => Promise<void>;
+
+/** Options accepted by {@link init}, extending the shared configuration. */
 interface InitOptions extends RiusOptions {
     /** Inject an exporter instead of OTLP. The test seam; prefer this to mocking. */
     spanExporter?: SpanExporter;
+    /** Override the heartbeat HTTP transport. The test seam; prefer this to mocking fetch. */
+    heartbeatTransport?: HeartbeatTransport;
 }
+/**
+ * Handle over a configured tracer pipeline, returned by {@link init}.
+ * Exposes the lifecycle operations (`flush`, `shutdown`) and `ready`, which
+ * resolves with the auto-instrumentations that attached.
+ */
 declare class RiusClient {
     private readonly provider;
     private readonly health?;
@@ -30,13 +52,37 @@ declare class RiusClient {
     /**
      * Drains and tears down the provider, then releases the global registration
      * so a later init() can reconfigure the SDK.
+     *
+     * The heartbeat's final `stopped: true` ping is sent before the provider
+     * shuts down, so the backend hears "stopped" while the trace pipeline can
+     * still export it. Idempotent: `sender.stop()` no-ops on a second call, and
+     * the `beforeExit` listener is removed here so repeated init/shutdown
+     * cycles never leak listeners.
      */
     shutdown(): Promise<void>;
 }
+/**
+ * Initialize the SDK: build a tracer pipeline that exports OTLP traces and
+ * enable every bundled auto-instrumentation whose package is installed.
+ *
+ * Call it once, as early as possible in your process. A second call while a
+ * client is active logs a warning and returns the existing client unchanged;
+ * `shutdown()` releases the slot. `init()` is synchronous; await
+ * {@link RiusClient.ready} if instrumentation must be attached before your
+ * first span.
+ *
+ * The SDK installs no process exit hook: short-lived processes must call
+ * {@link RiusClient.flush} before exiting or spans still in the batch queue
+ * are lost.
+ */
 declare function init(options?: InitOptions): RiusClient;
 /** The SDK tracer. Scope name is wire-visible; do not parameterize it. */
 declare function getTracer(): Tracer;
 
+/**
+ * Observation kind. Values are OpenInference `openinference.span.kind`
+ * values, the taxonomy the platform's agent analytics group by.
+ */
 declare enum SpanKind {
     AGENT = "AGENT",
     LLM = "LLM",
@@ -46,6 +92,7 @@ declare enum SpanKind {
     CHAIN = "CHAIN"
 }
 
+/** Options for {@link startSpan} and {@link startAsCurrentSpan}. */
 interface SpanOptions {
     kind?: SpanKind;
     input?: unknown;
@@ -88,6 +135,10 @@ type SpanBody<T> = (observation: Observation) => Promise<T> | T;
 declare function startAsCurrentSpan<T>(name: string, fn: SpanBody<T>): Promise<T>;
 declare function startAsCurrentSpan<T>(name: string, options: SpanOptions, fn: SpanBody<T>): Promise<T>;
 
+/**
+ * Options for {@link startGeneration} and {@link startAsCurrentGeneration}:
+ * the model identity and request parameters an LLM span carries.
+ */
 interface GenerationOptions {
     model?: string;
     provider?: string;
@@ -136,6 +187,7 @@ type GenerationBody<T> = (generation: Generation) => Promise<T> | T;
 declare function startAsCurrentGeneration<T>(name: string, fn: GenerationBody<T>): Promise<T>;
 declare function startAsCurrentGeneration<T>(name: string, options: GenerationOptions, fn: GenerationBody<T>): Promise<T>;
 
+/** Options for {@link observe}. */
 interface ObserveOptions {
     name?: string;
     kind?: SpanKind;