JavaScript SDK

npm install risicare

import { init } from 'risicare';
 
init(config?: RisicareConfig): void

import { enable, disable, isEnabled } from 'risicare';
 
enable(): void
disable(): void
isEnabled(): boolean

import { flush, shutdown } from 'risicare';
 
flush(timeoutMs?: number): Promise<boolean>     // default 5000
shutdown(timeoutMs?: number): Promise<void>     // default 5000

import { getMetrics } from 'risicare';
 
getMetrics(): {
  sdkState: 'running' | 'shutdown' | 'uninitialised';
  exportedSpans: number;
  droppedSpans: number;
  droppedSpansByReason: {
    queue_full: number;
    transport_refused: number;
    shutdown_residue: number;
    unacknowledged: number;
  };
  rejectedSpans: number;
  failedScores: number;
  failedExports: number;
  maskErrors?: number;        // absent when sdkState is 'uninitialised'
  queueSize: number;
  queueCapacity: number;
  queueUtilization: number;
}

import { getTraceContent } from 'risicare';
 
getTraceContent(): boolean

import { reportError } from 'risicare';
 
try {
    const result = await llm.invoke(query);
} catch (error) {
    reportError(error);          // Records and classifies the error
    return fallbackResponse;
}

import { score } from 'risicare';
 
score('4bf92f3577b34da6a3ce929d0e0e4736', 'factual_accuracy', 0.92, {
    comment: 'Verified against source documents',
});

import { patchOpenAI } from 'risicare/openai';
import { patchAnthropic } from 'risicare/anthropic';
import { patchGroq } from 'risicare/groq';
import OpenAI from 'openai';
 
const openai = patchOpenAI(new OpenAI());
// All chat.completions.create and embeddings.create calls are now traced

import { patchOpenAI } from 'risicare/openai';
import OpenAI from 'openai';
 
// DeepSeek via OpenAI-compatible API — auto-detected as "deepseek"
const deepseek = patchOpenAI(new OpenAI({
    baseURL: 'https://api.deepseek.com/v1',
    apiKey: process.env.DEEPSEEK_API_KEY,
}));

import { generateText, streamText, generateObject } from 'ai';
import { patchVercelAI } from 'risicare/vercel-ai';
 
const { tracedGenerateText, tracedStreamText, tracedGenerateObject } = patchVercelAI();
const generate = tracedGenerateText(generateText);
const stream = tracedStreamText(streamText);
const genObject = tracedGenerateObject(generateObject);

import { RisicareCallbackHandler } from 'risicare/langchain';
 
const handler = new RisicareCallbackHandler();
const result = await chain.invoke(input, { callbacks: [handler] });

import { instrumentLangGraph } from 'risicare/langgraph';
 
const tracedGraph = instrumentLangGraph(compiledGraph);
const result = await tracedGraph.invoke(input);

import { patchInstructor } from 'risicare/instructor';
 
const patchedClient = patchInstructor(instructorClient);
const result = await patchedClient.chat.completions.create({
  model: 'gpt-4o',
  response_model: { schema: MySchema, name: 'MySchema' },
  messages: [{ role: 'user', content: 'Extract the data' }],
});

import { Settings } from 'llamaindex';
import { RisicareLlamaIndexHandler } from 'risicare/llamaindex';
 
const handler = new RisicareLlamaIndexHandler();
for (const name of RisicareLlamaIndexHandler.EVENT_NAMES) {
  Settings.callbackManager.on(name as any, (e: any) => handler.onEvent(e));
}
 
// Provider spans are suppressed only inside withSuppression():
const result = await handler.withSuppression(() => queryEngine.query({ query: '...' }));

import { tracedStream } from 'risicare';
 
const stream = tracedStream(asyncIterable, { name: 'llm-stream' });
for await (const chunk of stream) {
    handleChunk(chunk);
}
// Span automatically records stream.chunk_count and stream.completed

import { suppressProviderInstrumentation, isProviderInstrumentationSuppressed } from 'risicare';
 
await suppressProviderInstrumentation(async () => {
    // Provider patches are suppressed inside this scope
    await client.chat.completions.create(/* ... */);
});

import { agent } from 'risicare';
 
agent<T extends (...args: any[]) => any>(
  options: {
    name?: string;
    role?: string;  // any string; canonical values are the AgentRole enum
    agentType?: string;
    version?: number;
    metadata?: Record<string, unknown>;
  },
  fn: T
): T

import { session } from 'risicare';
 
session<T extends (...args: any[]) => any>(
  optionsOrResolver: SessionOptions | ((...args: any[]) => SessionOptions),
  fn: T
): T
 
interface SessionOptions {
  sessionId: string;
  userId?: string;
}

import { traceThink, traceDecide, traceAct, traceObserve } from 'risicare';
 
// Bare form with an anonymous function — the span is named `phase:think`.
// With a named function, the span is `<phase>:<function>`, for example `think:analyzeQuery`.
const analyzeBare = traceThink(async () => { /* ... */ });
 
// Named form — explicit span name
const analyze = traceThink('analyze-query', async () => { /* ... */ });
 
// All four phases support both forms
const choose = traceDecide('choose-action', async () => { /* ... */ });
const execute = traceAct('execute-tool', async () => { /* ... */ });
const check = traceObserve('check-result', async () => { /* ... */ });
 
// Nothing is traced until the wrappers are invoked:
await analyze();
await choose();
await execute();
await check();

import { traceMessage, traceDelegate, traceCoordinate } from 'risicare';
 
traceMessage<T extends (...args: any[]) => any>(
  options: { to: string },
  fn: T
): T
 
traceDelegate<T extends (...args: any[]) => any>(
  options: { to: string },
  fn: T
): T
 
traceCoordinate<T extends (...args: any[]) => any>(
  options: { participants: string[] },
  fn: T
): T

import { getCurrentContext } from 'risicare';
 
// Returns a plain object snapshot. session/agent/span are either an
// object or null; phase is a SemanticPhase or null.
getCurrentContext(): {
  session: { sessionId: string; userId?: string } | null;
  agent: {
    agentId: string;
    agentName?: string;
    agentRole?: string;
    agentType?: string;
  } | null;
  span: { spanId: string; traceId: string } | null;
  phase: SemanticPhase | null;
}

import {
  getCurrentTraceId,
  getCurrentSpanId,
  getCurrentAgentId,
  getCurrentSessionId,
} from 'risicare';
 
getCurrentTraceId(): string | undefined
getCurrentSpanId(): string | undefined
getCurrentAgentId(): string | undefined
getCurrentSessionId(): string | undefined

import { injectTraceContext, extractTraceContext } from 'risicare';
 
injectTraceContext(headers: Record<string, string>): Record<string, string>
 
// Always returns a record (never undefined). When the incoming headers
// carry a Risicare tracestate it includes traceId, parentSpanId, flags,
// and any propagated sessionId / agentId.
extractTraceContext(headers: Record<string, string>): Record<string, string | undefined>

import { getTraceContext } from 'risicare';
 
getTraceContext(): TraceContext   // { traceId, spanId, sessionId?, agentId? }

import { withSession, withAgent, withPhase } from 'risicare';
import { SemanticPhase } from 'risicare';
 
withSession(options: { sessionId: string; userId?: string }, fn: () => T): T
withAgent(options: { name?: string; role?: string; agentType?: string }, fn: () => T): T
withPhase(phase: SemanticPhase, fn: () => T): T

import {
  verifyWebhookSignature,
  WebhookVerificationError,
  DEFAULT_TIMESTAMP_TOLERANCE_S,   // 300 (seconds)
} from 'risicare';
 
verifyWebhookSignature(
  payload: Uint8Array | ArrayBuffer | string,   // raw request body bytes
  headers: Headers | Map<string, string> | Record<string, string | string[] | undefined>,
  secret: string,
  opts?: { toleranceS?: number },               // default 300s skew window
): void   // returns undefined on success; throws on any failure

import express from 'express';
import { verifyWebhookSignature, WebhookVerificationError } from 'risicare';
 
const app = express();
app.post('/risicare-webhook', express.raw({ type: '*/*' }), (req, res) => {
  try {
    verifyWebhookSignature(req.body, req.headers, process.env.WEBHOOK_SECRET!);
  } catch (e) {
    if (e instanceof WebhookVerificationError) {
      return res.status(401).send(e.message);
    }
    throw e;
  }
  // ... process the verified event ...
  res.status(200).end();
});

import {
  registerSpan,
  getSpanById,
  unregisterSpan,
} from 'risicare';
 
registerSpan(span: Span, ttlMs?: number): void
getSpanById(spanId: string): Span | undefined
unregisterSpan(spanId: string): void

interface RisicareConfig {
  apiKey?: string;
  projectId?: string;  // DEPRECATED — emits console.warn. Will be removed in v1.0.
  endpoint?: string;     // default 'https://ingest.risicare.ai' (spans)
  apiEndpoint?: string;  // default 'https://api.risicare.ai' (scores)
  environment?: string;
  serviceName?: string;
  serviceVersion?: string;
  enabled?: boolean;
  traceContent?: boolean;
  compress?: boolean;
  sampleRate?: number;
  batchSize?: number;
  batchTimeoutMs?: number;
  maxQueueSize?: number;
  debug?: boolean;
  fixRuntime?: boolean;  // default false since 0.7.0
  metadata?: Record<string, unknown>;
  mask?: (key: string, value: unknown) => unknown;
}

interface TraceContext {
  traceId: string;
  spanId: string;
  sessionId?: string;
  agentId?: string;
}

class Span {
  traceId: string;
  spanId: string;
  name: string;
  kind: SpanKind;
  startTime: string;        // ISO 8601 timestamp
  endTime?: string;         // ISO 8601 timestamp, set on end()
  attributes: Record<string, unknown>;
  events: SpanEvent[];
  status: SpanStatus;
 
  setAttribute(key: string, value: unknown): this;
  addEvent(name: string, attributes?: Record<string, unknown>): this;
  setStatus(status: SpanStatus, message?: string): this;
  end(): void;
}

enum SpanKind {
  INTERNAL = 'internal',
  SERVER = 'server',
  CLIENT = 'client',
  PRODUCER = 'producer',
  CONSUMER = 'consumer',
  AGENT = 'agent',
  LLM_CALL = 'llm_call',
  TOOL_CALL = 'tool_call',
  RETRIEVAL = 'retrieval',
  DECISION = 'decision',
  DELEGATION = 'delegation',
  COORDINATION = 'coordination',
  MESSAGE = 'message',
  THINK = 'think',
  DECIDE = 'decide',
  OBSERVE = 'observe',
  REFLECT = 'reflect',
}

enum SpanStatus {
  UNSET = 'unset',
  OK = 'ok',
  ERROR = 'error',
}