@rheonic/sdk 0.1.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `rheonic-node` will be documented in this file.
+
+## Unreleased
+
+- Publish-ready changelog entries will be added here for the next release.
+
+## 0.1.0
+
+### Added
+- Initial public beta release of the Rheonic Node SDK.
+- Manual event capture and protect preflight client APIs.
+- OpenAI, Anthropic, and Google provider instrumentation helpers.
+- Structured SDK logging with trace correlation.
+
+### Changed
+- Packaged contents are limited to the compiled SDK, README, and changelog for clean npm publishing.
+
+### Docs
+- Added install, configuration, and minimal integration guidance for beta users.

package/README.md

@@ -0,0 +1,150 @@
+# Rheonic Node SDK
+
+The Rheonic Node SDK runs inside your app process, captures provider telemetry, and can request protect preflight decisions before provider calls.
+
+## Install
+
+Beta prerelease install:
+
+```bash
+npm install rheonic-node@next
+```
+
+Compatibility:
+- Node.js 18+
+- One of the supported provider SDKs: `openai`, `@anthropic-ai/sdk`, or `@google/generative-ai`
+
+Beta note:
+- Public beta releases may add guardrail fields and provider wrappers before `1.0.0`.
+
+## Configuration
+
+- Required: `ingestKey`
+- Optional for local development: `baseUrl` (defaults to `RHEONIC_BASE_URL`, else `http://localhost:8000`)
+- Optional: `environment` (default `dev`)
+
+For hosted beta, staging, or production deployments, set `RHEONIC_BASE_URL` or pass `baseUrl` explicitly. The localhost default is intended only for local development.
+
+Provider/model validation: SDK wrappers fail fast with `RHEONICValidationError` when provider is missing/unsupported or model is missing/empty. Supported providers are `openai`, `anthropic`, and `google`. Model naming is not pattern-validated so future vendor naming changes remain compatible.
+
+## Integration Recommendation
+
+Create one long-lived SDK client at app startup and reuse it for all provider calls. The SDK prewarms tokenizer state and the backend connection on client initialization, so reusing a single client avoids paying protect cold-start cost on every request.
+
+## Logging
+
+The SDK emits structured JSON logs to stdout. You do not need to configure file logging.
+
+Example log:
+
+```json
+{
+  "timestamp": "2026-03-18T09:20:15.145102+00:00",
+  "level": "info",
+  "service": "sdk-node",
+  "env": "staging",
+  "trace_id": "f4ac8b6b-6f8d-4f4c-b54f-3c2c2f76a27b",
+  "span_id": "9f12db3a1d204f8f",
+  "event": "sdk_client_initialized",
+  "message": "SDK client initialized",
+  "metadata": {}
+}
+```
+
+Notes:
+- backend requests automatically include `X-Trace-ID`,
+- SDK logs share that `trace_id` so you can correlate SDK, backend, worker, and webhook activity,
+- sensitive fields such as API keys and tokens are redacted.
+
+## Integration Path 1: Manual Capture (generic)
+
+```ts
+import { buildEvent, createClient } from "@rheonic/sdk";
+
+const client = createClient({
+  baseUrl: process.env.RHEONIC_BASE_URL!,
+  ingestKey: process.env.RHEONIC_INGEST_KEY!,
+});
+
+await client.captureEvent(
+  buildEvent({
+    provider: "openai",
+    model: "gpt-4o-mini",
+    request: { endpoint: "/chat", input_tokens: 12 },
+    response: { total_tokens: 32, latency_ms: 140, http_status: 200 },
+  }),
+);
+```
+
+Initialize `client` once during app startup, then reuse that same instance for manual capture and provider instrumentation.
+
+Minimal protect preflight usage:
+
+```ts
+const decision = await client.protect({
+  provider: "openai",
+  model: "gpt-4o-mini",
+  feature: "assistant",
+  inputTokensEstimate: 32,
+  maxOutputTokens: 256,
+});
+```
+
+## Integration Path 2: OpenAI instrumentation (convenience wrapper)
+
+```ts
+import OpenAI from "openai";
+import { createClient, instrumentOpenAI } from "rheonic-node";
+
+const rheonicClient = createClient({
+  baseUrl: process.env.RHEONIC_BASE_URL!,
+  ingestKey: process.env.RHEONIC_INGEST_KEY!,
+});
+const openai = instrumentOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), {
+  client: rheonicClient,
+  endpoint: "/chat/completions",
+  feature: "assistant",
+});
+```
+
+## Integration Path 3: Anthropic and Google wrappers
+
+```ts
+import Anthropic from "@anthropic-ai/sdk";
+import { GoogleGenerativeAI } from "@google/generative-ai";
+import { createClient } from "rheonic-node";
+
+const client = createClient({
+  baseUrl: process.env.RHEONIC_BASE_URL!,
+  ingestKey: process.env.RHEONIC_INGEST_KEY!,
+});
+
+const anthropic = client.instrumentAnthropic(new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }));
+await anthropic.messages.create({
+  model: "claude-3-5-sonnet-latest",
+  max_tokens: 256,
+  messages: [{ role: "user", content: "Hello Claude" }],
+});
+
+const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY!);
+const googleModel = client.instrumentGoogle(genAI.getGenerativeModel({ model: "gemini-1.5-pro" }));
+await googleModel.generateContent("Hello Google model");
+```
+
+Runtime call path:
+- SDK instrumentation calls `POST /api/v1/protect/decision` then `POST /api/v1/events`.
+- Project mode in dashboard controls decision behavior:
+  - Observe: allow only.
+  - Protect: allow/warn/block with cooldown.
+
+## Provider SDKs
+
+Install only the provider SDKs you actually use alongside `rheonic-node`:
+
+```bash
+npm install openai
+npm install @anthropic-ai/sdk
+npm install @google/generative-ai
+```
+
+Beta prereleases use semver prerelease format such as `0.2.0-beta.1` and are published under the `next` tag.

package/dist/client.d.ts

@@ -0,0 +1,59 @@
+import { type ProtectContext, type ProtectEvaluation, type ProtectFailMode } from "./protectEngine.js";
+import { type AnthropicInstrumentationOptions } from "./providers/anthropicAdapter.js";
+import { type GoogleInstrumentationOptions } from "./providers/googleAdapter.js";
+import { type OpenAIInstrumentationOptions } from "./providers/openaiAdapter.js";
+import type { EventPayload } from "./eventBuilder.js";
+export type OverflowPolicy = "drop_oldest" | "drop_newest";
+export interface ClientStats {
+    queued: number;
+    dropped: number;
+    sent: number;
+    failed: number;
+}
+export interface ClientConfig {
+    baseUrl?: string;
+    ingestKey: string;
+    environment?: string;
+    flushIntervalMs?: number;
+    maxQueueSize?: number;
+    overflowPolicy?: OverflowPolicy;
+    requestTimeoutMs?: number;
+    protectFailMode?: ProtectFailMode;
+    debug?: boolean;
+}
+export declare class Client {
+    readonly baseUrl: string;
+    readonly ingestKey: string;
+    readonly environment: string;
+    private readonly flushIntervalMs;
+    private readonly maxQueueSize;
+    private readonly overflowPolicy;
+    private readonly requestTimeoutMs;
+    private readonly protectEngine;
+    private readonly debug;
+    private queue;
+    private isFlushing;
+    private timer;
+    private dropped;
+    private sent;
+    private failed;
+    private isClosed;
+    private warmupPromise;
+    private warmupCompleted;
+    constructor(config: ClientConfig);
+    captureEvent(event: EventPayload): Promise<void>;
+    getStats(): ClientStats;
+    flush(): Promise<void>;
+    evaluateProtectDecision(context: ProtectContext): Promise<ProtectEvaluation>;
+    warmConnections(): Promise<void>;
+    private ensureWarmup;
+    private runWarmup;
+    instrumentOpenAI<T extends Record<string, any>>(openaiClient: T, options?: Omit<OpenAIInstrumentationOptions, "client">): T;
+    instrumentAnthropic<T extends Record<string, any>>(anthropicClient: T, options?: Omit<AnthropicInstrumentationOptions, "client">): T;
+    instrumentGoogle<T extends Record<string, any>>(googleModel: T, options?: Omit<GoogleInstrumentationOptions, "client">): T;
+    flushWithTimeout(timeoutMs?: 500): Promise<void>;
+    close(): void;
+    private sendEvent;
+    private sendEventOnce;
+    debugLog(message: string, meta?: Record<string, unknown>): void;
+}

package/dist/client.js

@@ -0,0 +1,305 @@
+import { sdkNodeConfig } from "./config.js";
+import { requestJson } from "./httpTransport.js";
+import { bindTraceContext, emitLog, generateSpanId, generateTraceId, getSpanId, getTraceId } from "./logger.js";
+import { ProtectEngine } from "./protectEngine.js";
+import { instrumentAnthropic as instrumentAnthropicProvider } from "./providers/anthropicAdapter.js";
+import { instrumentGoogle as instrumentGoogleProvider } from "./providers/googleAdapter.js";
+import { instrumentOpenAI as instrumentOpenAIProvider } from "./providers/openaiAdapter.js";
+import { prewarmTokenEstimator } from "./tokenEstimator.js";
+const CLIENT_REGISTRY = new Set();
+let EXIT_HOOKS_REGISTERED = false;
+export class Client {
+    baseUrl;
+    ingestKey;
+    environment;
+    flushIntervalMs;
+    maxQueueSize;
+    overflowPolicy;
+    requestTimeoutMs;
+    protectEngine;
+    debug;
+    queue = [];
+    isFlushing = false;
+    timer = null;
+    dropped = 0;
+    sent = 0;
+    failed = 0;
+    isClosed = false;
+    warmupPromise = null;
+    warmupCompleted = false;
+    constructor(config) {
+        this.baseUrl = config.baseUrl ?? process.env.RHEONIC_BASE_URL ?? sdkNodeConfig.defaultBaseUrl;
+        this.ingestKey = config.ingestKey;
+        this.environment = config.environment ?? sdkNodeConfig.defaultEnvironment;
+        this.flushIntervalMs = config.flushIntervalMs ?? sdkNodeConfig.defaultFlushIntervalMs;
+        this.maxQueueSize = config.maxQueueSize ?? sdkNodeConfig.defaultMaxQueueSize;
+        this.overflowPolicy = config.overflowPolicy ?? "drop_oldest";
+        this.requestTimeoutMs = config.requestTimeoutMs ?? sdkNodeConfig.defaultRequestTimeoutMs;
+        const initialFailMode = config.protectFailMode ?? sdkNodeConfig.defaultProtectFailMode;
+        const envDebug = process.env.RHEONIC_DEBUG === "1" || process.env.RHEONIC_DEBUG === "true";
+        this.debug = config.debug ?? envDebug;
+        // Warm default/model-specific tokenizer state before the first protected call.
+        prewarmTokenEstimator(null);
+        const prewarmModel = process.env.RHEONIC_MODEL?.trim();
+        if (prewarmModel) {
+            prewarmTokenEstimator(prewarmModel);
+        }
+        this.protectEngine = new ProtectEngine({
+            baseUrl: this.baseUrl,
+            ingestKey: this.ingestKey,
+            environment: this.environment,
+            fallbackRequestTimeoutMs: this.requestTimeoutMs,
+            initialFailMode,
+            debugLog: this.debugLog.bind(this),
+        });
+        this.warmupPromise = this.runWarmup();
+        this.timer = setInterval(() => {
+            void this.flush();
+        }, this.flushIntervalMs);
+        this.timer.unref?.();
+        CLIENT_REGISTRY.add(this);
+        registerExitHooks();
+        emitLog({
+            level: "info",
+            event: "sdk_client_initialized",
+            message: "SDK client initialized",
+            environment: this.environment,
+            traceId: generateTraceId(),
+            spanId: generateSpanId(),
+        });
+    }
+    async captureEvent(event) {
+        try {
+            if (this.queue.length >= this.maxQueueSize) {
+                if (this.overflowPolicy === "drop_oldest") {
+                    this.queue.shift();
+                    this.dropped += 1;
+                }
+                else {
+                    this.dropped += 1;
+                    return;
+                }
+            }
+            if (this.isClosed) {
+                return;
+            }
+            this.queue.push({
+                ...event,
+                environment: event.environment || this.environment,
+            });
+        }
+        catch {
+            return;
+        }
+    }
+    getStats() {
+        return {
+            queued: this.queue.length,
+            dropped: this.dropped,
+            sent: this.sent,
+            failed: this.failed,
+        };
+    }
+    async flush() {
+        if (this.isFlushing || this.isClosed) {
+            return;
+        }
+        this.isFlushing = true;
+        try {
+            while (this.queue.length > 0) {
+                const event = this.queue.shift();
+                if (!event) {
+                    continue;
+                }
+                await this.sendEvent(event);
+            }
+        }
+        finally {
+            this.isFlushing = false;
+        }
+    }
+    async evaluateProtectDecision(context) {
+        await this.ensureWarmup();
+        return this.protectEngine.evaluate(context);
+    }
+    async warmConnections() {
+        if (this.warmupCompleted) {
+            return;
+        }
+        if (this.warmupPromise) {
+            await this.warmupPromise;
+            this.warmupPromise = null;
+            return;
+        }
+        this.warmupPromise = this.runWarmup();
+        await this.warmupPromise;
+        this.warmupPromise = null;
+    }
+    async ensureWarmup() {
+        if (this.warmupCompleted) {
+            return;
+        }
+        if (this.warmupPromise) {
+            await this.warmupPromise;
+            this.warmupPromise = null;
+        }
+    }
+    async runWarmup() {
+        try {
+            const response = await bindTraceContext(generateTraceId(), generateSpanId(), async () => await requestJson(`${this.baseUrl}/health`, {
+                method: "GET",
+                headers: {
+                    "X-Trace-ID": getTraceId(),
+                    "X-Span-ID": getSpanId(),
+                },
+            }));
+            this.debugLog("SDK connection warmup completed", { status_code: response.status });
+        }
+        catch {
+            this.debugLog("SDK connection warmup failed");
+        }
+        try {
+            await this.protectEngine.bootstrap();
+            this.debugLog("SDK protect config bootstrap completed");
+        }
+        catch {
+            this.debugLog("SDK protect config bootstrap failed");
+        }
+        this.warmupCompleted = true;
+    }
+    instrumentOpenAI(openaiClient, options) {
+        return instrumentOpenAIProvider(openaiClient, {
+            client: this,
+            environment: options?.environment,
+            endpoint: options?.endpoint,
+            feature: options?.feature,
+        });
+    }
+    instrumentAnthropic(anthropicClient, options) {
+        return instrumentAnthropicProvider(anthropicClient, {
+            client: this,
+            environment: options?.environment,
+            endpoint: options?.endpoint,
+            feature: options?.feature,
+        });
+    }
+    instrumentGoogle(googleModel, options) {
+        return instrumentGoogleProvider(googleModel, {
+            client: this,
+            environment: options?.environment,
+            endpoint: options?.endpoint,
+            feature: options?.feature,
+        });
+    }
+    async flushWithTimeout(timeoutMs = sdkNodeConfig.defaultFlushTimeoutMs) {
+        await Promise.race([
+            this.flush(),
+            new Promise((resolve) => {
+                setTimeout(resolve, timeoutMs);
+            }),
+        ]);
+    }
+    close() {
+        if (this.isClosed) {
+            return;
+        }
+        this.isClosed = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        CLIENT_REGISTRY.delete(this);
+    }
+    async sendEvent(event) {
+        const firstAttempt = await this.sendEventOnce(event);
+        if (firstAttempt.ok) {
+            this.sent += 1;
+            return;
+        }
+        if (!firstAttempt.shouldRetry) {
+            this.failed += 1;
+            return;
+        }
+        await waitMs(jitterMs(sdkNodeConfig.retryDelayMinMs, sdkNodeConfig.retryDelayMaxMs));
+        const secondAttempt = await this.sendEventOnce(event);
+        if (secondAttempt.ok) {
+            this.sent += 1;
+            return;
+        }
+        this.failed += 1;
+    }
+    async sendEventOnce(event) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+        const traceId = generateTraceId();
+        const spanId = generateSpanId();
+        try {
+            const response = await bindTraceContext(traceId, spanId, async () => await requestJson(`${this.baseUrl}/api/v1/events`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Project-Ingest-Key": this.ingestKey,
+                    "X-Trace-ID": getTraceId(),
+                    "X-Span-ID": spanId,
+                },
+                body: JSON.stringify(event),
+                signal: controller.signal,
+            }));
+            clearTimeout(timeout);
+            if (response.ok) {
+                return { ok: true, shouldRetry: false };
+            }
+            if (response.status >= 500) {
+                this.debugLog(`Server error ${response.status}; scheduling retry`);
+                return { ok: false, shouldRetry: true };
+            }
+            return { ok: false, shouldRetry: false };
+        }
+        catch {
+            clearTimeout(timeout);
+            return { ok: false, shouldRetry: true };
+        }
+    }
+    debugLog(message, meta) {
+        if (!this.debug) {
+            return;
+        }
+        emitLog({
+            level: "debug",
+            event: "sdk_debug",
+            message,
+            metadata: meta,
+            environment: this.environment,
+        });
+    }
+}
+function registerExitHooks() {
+    if (EXIT_HOOKS_REGISTERED || typeof process === "undefined") {
+        return;
+    }
+    EXIT_HOOKS_REGISTERED = true;
+    process.on("beforeExit", () => {
+        void flushAllClients();
+    });
+    process.on("SIGINT", () => {
+        void flushAllClients().finally(() => {
+            process.exit(0);
+        });
+    });
+    process.on("SIGTERM", () => {
+        void flushAllClients().finally(() => {
+            process.exit(0);
+        });
+    });
+}
+async function flushAllClients() {
+    await Promise.all(Array.from(CLIENT_REGISTRY, (client) => client.flushWithTimeout()));
+}
+function jitterMs(minMs, maxMs) {
+    return Math.floor(Math.random() * (maxMs - minMs + 1)) + minMs;
+}
+function waitMs(delayMs) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, delayMs);
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,15 @@
+export declare const sdkNodeConfig: {
+    readonly defaultBaseUrl: "http://localhost:8000";
+    readonly defaultEnvironment: "dev";
+    readonly defaultFlushIntervalMs: 1000;
+    readonly defaultMaxQueueSize: 1000;
+    readonly defaultFlushTimeoutMs: 500;
+    readonly defaultRequestTimeoutMs: 1000;
+    readonly defaultProtectFailMode: "open";
+    readonly internalProtectDecisionTimeoutMs: 150;
+    readonly retryDelayMinMs: 200;
+    readonly retryDelayMaxMs: 400;
+    readonly defaultTokenizerEncoding: "cl100k_base";
+    readonly maxInputTokenEstimate: 50000;
+    readonly supportedProviders: readonly ["openai", "anthropic", "google"];
+};

package/dist/config.js

@@ -0,0 +1,15 @@
+export const sdkNodeConfig = {
+    defaultBaseUrl: "http://localhost:8000",
+    defaultEnvironment: "dev",
+    defaultFlushIntervalMs: 1000,
+    defaultMaxQueueSize: 1000,
+    defaultFlushTimeoutMs: 500,
+    defaultRequestTimeoutMs: 1000,
+    defaultProtectFailMode: "open",
+    internalProtectDecisionTimeoutMs: 150,
+    retryDelayMinMs: 200,
+    retryDelayMaxMs: 400,
+    defaultTokenizerEncoding: "cl100k_base",
+    maxInputTokenEstimate: 50_000,
+    supportedProviders: ["openai", "anthropic", "google"],
+};

package/dist/costCalculator.d.ts

@@ -0,0 +1,3 @@
+export declare class CostCalculator {
+    calculate(_usage: Record<string, unknown>): number;
+}

package/dist/costCalculator.js

@@ -0,0 +1,6 @@
+export class CostCalculator {
+    calculate(_usage) {
+        // TODO: Implement provider-aware deterministic cost calculation.
+        return 0;
+    }
+}

package/dist/eventBuilder.d.ts

@@ -0,0 +1,35 @@
+export interface EventRequest {
+    endpoint?: string;
+    feature?: string;
+    input_tokens?: number;
+    input_tokens_estimate?: number;
+    max_output_tokens?: number;
+    protect_decision?: string;
+    protect_reason?: string;
+}
+export interface EventResponse {
+    http_status?: number;
+    latency_ms?: number;
+    total_tokens?: number;
+    error_type?: string;
+}
+export interface EventPayload {
+    ts: string;
+    provider: string;
+    model: string | null;
+    environment: string;
+    request: EventRequest;
+    response: EventResponse;
+}
+export interface BuildEventInput {
+    provider: string;
+    model?: string | null;
+    environment?: string;
+    ts?: string;
+    request?: EventRequest;
+    response?: EventResponse;
+}
+export declare function buildEvent(input: BuildEventInput): EventPayload;
+export declare class EventBuilder {
+    build(payload: BuildEventInput): EventPayload;
+}

package/dist/eventBuilder.js

@@ -0,0 +1,15 @@
+export function buildEvent(input) {
+    return {
+        ts: input.ts ?? new Date().toISOString(),
+        provider: input.provider,
+        model: input.model ?? null,
+        environment: input.environment ?? "dev",
+        request: input.request ?? {},
+        response: input.response ?? {},
+    };
+}
+export class EventBuilder {
+    build(payload) {
+        return buildEvent(payload);
+    }
+}

package/dist/httpTransport.d.ts

@@ -0,0 +1,12 @@
+export interface JsonRequestOptions {
+    method: "GET" | "POST";
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}
+export interface JsonHttpResponse {
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}
+export declare function requestJson(url: string, options: JsonRequestOptions): Promise<JsonHttpResponse>;