@cetusai/sdk 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,518 @@
+/**
+ * Base error class for all Songlines SDK errors.
+ *
+ * The SDK never throws — all errors are surfaced via the `onError` callback
+ * configured on the client. This class is provided for type-safe error handling
+ * in the callback.
+ */
+declare class SonglinesError extends Error {
+    readonly code: SonglinesErrorCode;
+    readonly statusCode: number | undefined;
+    readonly retryable: boolean;
+    constructor(message: string, code: SonglinesErrorCode, options?: {
+        statusCode?: number;
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+declare class InvalidConfigError extends SonglinesError {
+    constructor(message: string);
+}
+declare class InvalidApiKeyError extends SonglinesError {
+    constructor();
+}
+declare class NetworkError extends SonglinesError {
+    constructor(message: string, cause?: unknown);
+}
+declare class TimeoutError extends SonglinesError {
+    constructor(timeoutMs: number);
+}
+declare class RateLimitedError extends SonglinesError {
+    readonly retryAfterMs: number | undefined;
+    constructor(retryAfterMs?: number);
+}
+declare class ServerError extends SonglinesError {
+    constructor(statusCode: number, body?: string);
+}
+declare class QueueOverflowError extends SonglinesError {
+    readonly droppedCount: number;
+    constructor(droppedCount: number);
+}
+declare class PartialFailureError extends SonglinesError {
+    readonly accepted: number;
+    readonly failed: number;
+    readonly failedIds: string[];
+    constructor(accepted: number, failed: number, failedIds: string[]);
+}
+
+/**
+ * @songlines/sdk — Core Types
+ *
+ * All public-facing TypeScript types exported from the SDK.
+ * Prompt and completion text are intentionally excluded — the SDK
+ * captures metadata only. No prompt content is ever transmitted.
+ */
+
+type Environment = "production" | "staging" | "development" | "test";
+type RequestStatus = "success" | "error" | "blocked" | "pending";
+interface SonglinesClientConfig {
+    /**
+     * Your Songlines API key. Must start with `sk-sl-`.
+     * Always load from an environment variable — never hardcode.
+     * @example process.env.SONGLINES_API_KEY
+     */
+    apiKey: string;
+    /**
+     * Base URL of the Songlines Control ingest API.
+     * @default "https://api.songlinesai.com"
+     */
+    baseUrl?: string;
+    /**
+     * Deployment environment tag applied to all events from this client instance.
+     * @default "production"
+     */
+    environment?: Environment;
+    /**
+     * Maximum number of events to accumulate before flushing to the API.
+     * @default 10
+     */
+    batchSize?: number;
+    /**
+     * Maximum time in milliseconds to wait before flushing a partial batch.
+     * @default 5000
+     */
+    flushIntervalMs?: number;
+    /**
+     * HTTP request timeout in milliseconds.
+     * @default 10000
+     */
+    timeout?: number;
+    /**
+     * Number of times to retry a failed flush before dropping events.
+     * Uses exponential backoff with jitter.
+     * @default 3
+     */
+    retries?: number;
+    /**
+     * Called when events are dropped due to network failure or queue overflow.
+     * The SDK never throws — all errors are surfaced here.
+     */
+    onError?: (error: SonglinesError) => void;
+    /**
+     * When true, logs internal SDK activity to console.debug.
+     * @default false
+     */
+    debug?: boolean;
+}
+interface TrackAIRequestParams {
+    /**
+     * Caller-generated unique identifier for this request.
+     * Used for idempotency — duplicate IDs within a 24-hour window are ignored.
+     * UUID v4 recommended. If omitted, the SDK generates one automatically.
+     */
+    requestId?: string;
+    /**
+     * Model name exactly as called.
+     * @example "gpt-4o", "claude-3-5-sonnet-20241022", "mistral-large-latest"
+     */
+    model: string;
+    /**
+     * Provider name.
+     * @example "openai", "anthropic", "azure", "bedrock", "mistral", "groq"
+     */
+    provider?: string;
+    /**
+     * Logical workflow or application name. Used for cost attribution and grouping.
+     * @example "invoice-processor", "customer-support", "document-review"
+     */
+    workflow?: string;
+    /**
+     * Step within a multi-step workflow.
+     * @example "extract", "summarise", "classify", "generate"
+     */
+    step?: string;
+    /**
+     * Agent or service identifier for multi-agent architectures.
+     * @example "orchestrator", "researcher", "writer"
+     */
+    agentId?: string;
+    /**
+     * Opaque user identifier. Must not contain PII — use an internal ID or hash.
+     * @example "user_8f3a2b", "team_finance"
+     */
+    user?: string;
+    /**
+     * Number of input (prompt) tokens consumed.
+     */
+    inputTokens: number;
+    /**
+     * Number of output (completion) tokens generated.
+     */
+    outputTokens: number;
+    /**
+     * End-to-end wall time in milliseconds from request dispatch to response received.
+     */
+    latencyMs?: number;
+    /**
+     * Actual cost in USD. If omitted, the SDK estimates cost from built-in model rates.
+     */
+    cost?: number;
+    /**
+     * Request outcome.
+     * @default "success"
+     */
+    status?: RequestStatus;
+    /**
+     * Error message if status is "error".
+     */
+    errorMessage?: string;
+    /**
+     * Timestamp of when the request was made.
+     * @default new Date()
+     */
+    timestamp?: Date;
+    /**
+     * Additional key-value metadata stored alongside the event.
+     * Do not include PII or sensitive data — values are visible in the dashboard.
+     */
+    metadata?: Record<string, string | number | boolean>;
+}
+interface IngestEvent {
+    request_id: string;
+    model: string;
+    provider?: string;
+    workflow?: string;
+    step?: string;
+    agent_id?: string;
+    user?: string;
+    environment: Environment;
+    input_tokens: number;
+    output_tokens: number;
+    latency_ms?: number;
+    status: RequestStatus;
+    error_message?: string;
+    timestamp?: string;
+}
+interface IngestResult {
+    request_id: string;
+    cost: number;
+}
+interface IngestError {
+    request_id: string;
+    error: string;
+}
+interface IngestResponse {
+    accepted: number;
+    failed: number;
+    results: IngestResult[];
+    errors?: IngestError[];
+}
+type SonglinesErrorCode = "INVALID_API_KEY" | "NETWORK_ERROR" | "TIMEOUT" | "RATE_LIMITED" | "SERVER_ERROR" | "INVALID_CONFIG" | "QUEUE_OVERFLOW" | "PARTIAL_FAILURE";
+interface WrapOptions {
+    /**
+     * Workflow name applied to all calls made through this wrapped client.
+     */
+    workflow?: string;
+    /**
+     * Step name applied to all calls made through this wrapped client.
+     */
+    step?: string;
+    /**
+     * Agent ID applied to all calls made through this wrapped client.
+     */
+    agentId?: string;
+    /**
+     * User identifier applied to all calls made through this wrapped client.
+     */
+    user?: string;
+}
+
+/**
+ * @songlines/sdk — Guardrail Evaluation (v0.2.0)
+ *
+ * Provides real-time policy evaluation via the Songlines Gateway API.
+ * Call evaluateGuardrail() before sending a prompt to an LLM to enforce
+ * policies inline — blocking, redacting, or alerting as configured.
+ *
+ * Architecture note: This feature uses the Songlines Gateway / Enforce path,
+ * which is distinct from the Control Ingest API used by trackAIRequest().
+ * The Gateway sits inline in the request path; the Control Ingest API
+ * receives telemetry after the model response.
+ */
+
+/** The outcome of a guardrail evaluation. */
+type GuardrailDecision = "allow" | "block" | "modify";
+/** The action configured on the policy that triggered this violation. */
+type PolicyAction = "block" | "alert" | "redact" | "log";
+/** A single policy violation detected during evaluation. */
+interface GuardrailViolation {
+    /** Internal policy identifier. */
+    policyId: string;
+    /** Human-readable policy name. */
+    policyName: string;
+    /** The action the policy is configured to take. */
+    action: PolicyAction;
+    /** Human-readable reason for the violation. */
+    reason: string;
+    /** The field that triggered the violation (e.g. "prompt", "model", "workflow"). */
+    field: string;
+}
+/** The result of a guardrail evaluation. */
+interface GuardrailResult {
+    /** The overall decision: allow, block, or modify. */
+    decision: GuardrailDecision;
+    /** All violations detected across all evaluated policies. */
+    violations: GuardrailViolation[];
+    /**
+     * The modified prompt to send to the LLM.
+     * Only present when `decision === "modify"` (e.g. PII redaction).
+     * Use this instead of the original prompt when decision is "modify".
+     */
+    modifiedInput?: string;
+    /** Evaluation latency in milliseconds. */
+    latencyMs: number;
+    /** Unique identifier for this evaluation (for audit correlation). */
+    evaluationId: string;
+}
+/** Parameters for evaluateGuardrail(). */
+interface EvaluateGuardrailParams {
+    /**
+     * The prompt text to evaluate. This is the only content sent to the
+     * Gateway — it is evaluated against policies and then discarded.
+     * It is never stored in the Songlines platform.
+     */
+    prompt: string;
+    /**
+     * The model identifier the prompt will be sent to.
+     * Used for model allowlist/denylist policy evaluation.
+     */
+    model: string;
+    /**
+     * The logical workflow or feature name.
+     * Used for workflow-scoped policy evaluation.
+     */
+    workflow?: string;
+    /**
+     * The provider name (e.g. "openai", "anthropic", "azure-openai").
+     * Used for provider-level policy enforcement.
+     */
+    provider?: string;
+    /**
+     * When true, throws a GuardrailBlockedError if the decision is "block".
+     * When false (default), returns the result and lets the caller decide.
+     * @default false
+     */
+    throwOnBlock?: boolean;
+}
+/**
+ * Thrown by evaluateGuardrail() when `throwOnBlock: true` and the
+ * guardrail returns `decision: "block"`.
+ *
+ * The full GuardrailResult is available on the `result` property.
+ */
+declare class GuardrailBlockedError extends Error {
+    readonly result: GuardrailResult;
+    constructor(result: GuardrailResult);
+}
+
+/**
+ * Songlines Control SDK client.
+ *
+ * Instruments AI workloads with a single `trackAIRequest()` call per LLM
+ * invocation. All telemetry is batched and sent asynchronously — the SDK
+ * never blocks or slows down your AI calls.
+ *
+ * @example
+ * ```typescript
+ * import { SonglinesClient } from "@songlines/sdk";
+ *
+ * const songlines = new SonglinesClient({
+ *   apiKey: process.env.SONGLINES_API_KEY!,
+ * });
+ *
+ * // After every LLM call:
+ * await songlines.trackAIRequest({
+ *   model: "gpt-4o",
+ *   provider: "openai",
+ *   workflow: "invoice-processor",
+ *   inputTokens: response.usage.prompt_tokens,
+ *   outputTokens: response.usage.completion_tokens,
+ *   latencyMs: Date.now() - startTime,
+ * });
+ * ```
+ */
+declare class SonglinesClient {
+    private readonly config;
+    private readonly queue;
+    constructor(config: SonglinesClientConfig);
+    /**
+     * Records an AI request event. The event is queued immediately and sent
+     * asynchronously — this method returns as soon as the event is enqueued.
+     *
+     * The returned Promise resolves when the event has been enqueued (not when
+     * it has been sent). Use `flush()` if you need confirmation of delivery.
+     */
+    trackAIRequest(params: TrackAIRequestParams): Promise<void>;
+    /**
+     * Forces an immediate flush of all queued events to the API.
+     * Resolves when the flush completes (successfully or not).
+     */
+    flush(): Promise<void>;
+    /**
+     * Flushes all remaining events and shuts down the background timer.
+     * Call this during graceful shutdown (e.g. in a `process.on("SIGTERM")` handler).
+     *
+     * @example
+     * ```typescript
+     * process.on("SIGTERM", async () => {
+     *   await songlines.shutdown();
+     *   process.exit(0);
+     * });
+     * ```
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Evaluates a prompt against all active Songlines policies in real time.
+     *
+     * This method uses the **Songlines Gateway / Enforce** path, which is
+     * distinct from `trackAIRequest()`. Call it *before* sending the prompt
+     * to an LLM to enforce policies inline.
+     *
+     * @returns A `GuardrailResult` with `decision`, `violations`, and optionally
+     *   a `modifiedInput` (when a redaction policy fires).
+     *
+     * @example
+     * ```typescript
+     * const result = await songlines.evaluateGuardrail({
+     *   prompt: userMessage,
+     *   model: "gpt-4o",
+     *   workflow: "customer-support",
+     * });
+     *
+     * if (result.decision === "block") {
+     *   return { error: "Request blocked by policy", violations: result.violations };
+     * }
+     *
+     * const promptToSend = result.modifiedInput ?? userMessage;
+     * const response = await openai.chat.completions.create({ ... });
+     * ```
+     */
+    evaluateGuardrail(params: EvaluateGuardrailParams): Promise<GuardrailResult>;
+    /**
+     * Converts TrackAIRequestParams into the wire format expected by /api/ingest.
+     */
+    private buildEvent;
+    /**
+     * Sends a batch of events to POST /api/ingest.
+     * Called by the BatchQueue — never called directly.
+     */
+    private sendBatch;
+    /**
+     * Performs a single HTTP POST with timeout and error classification.
+     */
+    private httpPost;
+}
+
+/**
+ * OpenAI SDK wrapper for Songlines Control.
+ *
+ * Wraps an OpenAI client instance so that every `chat.completions.create()`
+ * and `completions.create()` call is automatically instrumented with telemetry.
+ *
+ * Prompt and completion text are NEVER captured — only metadata
+ * (model, tokens, latency, cost) is sent to the Songlines ingest API.
+ *
+ * @example
+ * ```typescript
+ * import OpenAI from "openai";
+ * import { SonglinesClient } from "@songlines/sdk";
+ *
+ * const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+ * const songlines = new SonglinesClient({ apiKey: process.env.SONGLINES_API_KEY! });
+ *
+ * const instrumentedOpenAI = songlines.wrapOpenAI(openai, {
+ *   workflow: "invoice-processor",
+ * });
+ *
+ * // All calls through instrumentedOpenAI are automatically tracked
+ * const response = await instrumentedOpenAI.chat.completions.create({
+ *   model: "gpt-4o",
+ *   messages: [{ role: "user", content: "Hello" }],
+ * });
+ * ```
+ */
+
+/**
+ * Wraps an OpenAI client to automatically track all LLM calls.
+ * Returns a Proxy that is type-compatible with the original client.
+ */
+declare function wrapOpenAI<T extends object>(client: T, songlines: SonglinesClient, defaults?: WrapOptions): T;
+
+/**
+ * Anthropic SDK wrapper for Songlines Control.
+ *
+ * Wraps an Anthropic client instance so that every `messages.create()` call
+ * is automatically instrumented with telemetry.
+ *
+ * Prompt and completion text are NEVER captured — only metadata
+ * (model, tokens, latency, cost) is sent to the Songlines ingest API.
+ *
+ * @example
+ * ```typescript
+ * import Anthropic from "@anthropic-ai/sdk";
+ * import { SonglinesClient } from "@songlines/sdk";
+ *
+ * const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+ * const songlines = new SonglinesClient({ apiKey: process.env.SONGLINES_API_KEY! });
+ *
+ * const instrumentedAnthropic = songlines.wrapAnthropic(anthropic, {
+ *   workflow: "document-review",
+ * });
+ *
+ * const response = await instrumentedAnthropic.messages.create({
+ *   model: "claude-3-5-sonnet-20241022",
+ *   max_tokens: 1024,
+ *   messages: [{ role: "user", content: "Hello" }],
+ * });
+ * ```
+ */
+
+/**
+ * Wraps an Anthropic client to automatically track all `messages.create()` calls.
+ */
+declare function wrapAnthropic<T extends object>(client: T, songlines: SonglinesClient, defaults?: WrapOptions): T;
+
+/**
+ * Client-side cost estimation.
+ *
+ * Provides approximate USD costs based on publicly available per-million-token
+ * pricing. Actual costs may differ due to batch discounts, enterprise agreements,
+ * or provider pricing changes.
+ *
+ * Rates are per 1,000,000 tokens (input / output) in USD.
+ * Last updated: June 2026.
+ */
+interface ModelRates {
+    /** Cost per 1M input tokens in USD */
+    input: number;
+    /** Cost per 1M output tokens in USD */
+    output: number;
+}
+interface CostEstimateParams {
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+}
+/**
+ * Estimates the USD cost of an AI request based on public model pricing.
+ *
+ * @returns Estimated cost in USD, rounded to 8 decimal places.
+ *          Returns 0 if token counts are 0.
+ */
+declare function estimateCost({ model, inputTokens, outputTokens }: CostEstimateParams): number;
+/**
+ * Returns the known rate table. Useful for displaying pricing information.
+ */
+declare function getModelRates(): Readonly<Record<string, ModelRates>>;
+
+export { type Environment, type EvaluateGuardrailParams, GuardrailBlockedError, type GuardrailDecision, type GuardrailResult, type GuardrailViolation, type IngestError, type IngestEvent, type IngestResponse, type IngestResult, InvalidApiKeyError, InvalidConfigError, NetworkError, PartialFailureError, type PolicyAction, QueueOverflowError, RateLimitedError, type RequestStatus, ServerError, SonglinesClient, type SonglinesClientConfig, SonglinesError, type SonglinesErrorCode, TimeoutError, type TrackAIRequestParams, type WrapOptions, estimateCost, getModelRates, wrapAnthropic, wrapOpenAI };