@rheonic/sdk 0.1.0-beta.2 → 0.1.0-beta.4

package/README.md

@@ -1,150 +1,132 @@
 # Rheonic Node SDK
 
-The Rheonic Node SDK runs inside your app process, captures provider telemetry, and can request protect preflight decisions before provider calls.
+Rheonic captures provider telemetry and applies protect preflight decisions before provider calls.
 
 ## Install
 
-Beta prerelease install:
-
 ```bash
 npm install @rheonic/sdk
 ```
 
-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
+## Required environment variables
 
-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.
+```bash
+RHEONIC_INGEST_KEY=<your_project_ingest_key>
+RHEONIC_BASE_URL=<value_shown_in_dashboard>
+```
 
-## Logging
+## Instrument provider calls
 
-The SDK emits structured JSON logs to stdout. You do not need to configure file logging.
+Wrap your provider SDK once.
 
-Example log:
+Telemetry is captured automatically after each provider call.
 
-```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": {}
-}
-```
+Enforcement follows Project mode in the dashboard (`Observe` / `Protect`).
 
-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)
+OpenAI:
 
 ```ts
-import { buildEvent, createClient } from "@rheonic/sdk";
+import OpenAI from "openai";
+import { createClient, instrumentOpenAI, RHEONICBlockedError } from "@rheonic/sdk";
 
-const client = createClient({
+const rheonic = 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",
+const openai = instrumentOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY! }), {
+  client: rheonic,
+  endpoint: "/chat/completions",
   feature: "assistant",
-  inputTokensEstimate: 32,
-  maxOutputTokens: 256,
 });
+
+try {
+  await openai.chat.completions.create({
+    model: "gpt-4o-mini",
+    messages: [{ role: "user", content: "hello" }],
+    max_tokens: 256,
+  });
+} catch (error) {
+  if (error instanceof RHEONICBlockedError) {
+    console.log("Blocked by protect preflight");
+  }
+}
 ```
 
-## Integration Path 2: OpenAI instrumentation (convenience wrapper)
+Anthropic:
 
 ```ts
-import OpenAI from "openai";
-import { createClient, instrumentOpenAI } from "rheonic-node";
+import Anthropic from "@anthropic-ai/sdk";
+import { createClient, RHEONICBlockedError } from "@rheonic/sdk";
 
-const rheonicClient = createClient({
+const rheonic = 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",
-});
+
+const anthropic = rheonic.instrumentAnthropic(new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }));
+
+try {
+  await anthropic.messages.create({
+    model: "claude-3-5-sonnet-latest",
+    max_tokens: 256,
+    messages: [{ role: "user", content: "hello" }],
+  });
+} catch (error) {
+  if (error instanceof RHEONICBlockedError) {
+    console.log("Blocked by protect preflight");
+  }
+}
 ```
 
-## Integration Path 3: Anthropic and Google wrappers
+Google:
 
 ```ts
-import Anthropic from "@anthropic-ai/sdk";
 import { GoogleGenerativeAI } from "@google/generative-ai";
-import { createClient } from "rheonic-node";
+import { createClient, RHEONICBlockedError } from "@rheonic/sdk";
 
-const client = createClient({
+const rheonic = 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");
+const model = rheonic.instrumentGoogle(genAI.getGenerativeModel({ model: "gemini-1.5-pro" }));
+
+try {
+  await model.generateContent("hello");
+} catch (error) {
+  if (error instanceof RHEONICBlockedError) {
+    console.log("Blocked by protect preflight");
+  }
+}
 ```
 
-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.
+Keep one long-lived SDK client per app process. Initialize it during app startup and reuse it for all capture and instrumentation calls so Rheonic can avoid repeated protect cold-start latency.
 
-## Provider SDKs
+## Optional: custom event capture
 
-Install only the provider SDKs you actually use alongside `rheonic-node`:
+Use this only if you can't instrument a provider SDK or need custom events.
 
-```bash
-npm install openai
-npm install @anthropic-ai/sdk
-npm install @google/generative-ai
+```ts
+import { createClient, buildEvent } 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/completions", feature: "assistant" },
+    response: { total_tokens: 64, latency_ms: 120, http_status: 200 },
+  }),
+);
 ```
 
-Beta prereleases use semver prerelease format such as `0.2.0-beta.1` and are published under the `next` tag.
+## Reference
+
+Full quickstart:
+- `https://beta.rheonic.dev/quickstart`

package/dist/client.js

@@ -30,7 +30,13 @@ export class Client {
     constructor(config) {
         this.baseUrl = config.baseUrl ?? process.env.RHEONIC_BASE_URL ?? sdkNodeConfig.defaultBaseUrl;
         this.ingestKey = config.ingestKey;
-        this.environment = config.environment ?? sdkNodeConfig.defaultEnvironment;
+        this.environment =
+            config.environment ??
+                process.env.NODE_ENV ??
+                process.env.APP_ENV ??
+                process.env.ENVIRONMENT ??
+                process.env.ENV ??
+                sdkNodeConfig.defaultEnvironment;
         this.flushIntervalMs = config.flushIntervalMs ?? sdkNodeConfig.defaultFlushIntervalMs;
         this.maxQueueSize = config.maxQueueSize ?? sdkNodeConfig.defaultMaxQueueSize;
         this.overflowPolicy = config.overflowPolicy ?? "drop_oldest";

package/dist/config.d.ts

@@ -1,12 +1,12 @@
 export declare const sdkNodeConfig: {
     readonly defaultBaseUrl: "http://localhost:8000";
-    readonly defaultEnvironment: "dev";
+    readonly defaultEnvironment: "unknown";
     readonly defaultFlushIntervalMs: 1000;
     readonly defaultMaxQueueSize: 1000;
     readonly defaultFlushTimeoutMs: 500;
     readonly defaultRequestTimeoutMs: 1000;
     readonly defaultProtectFailMode: "open";
-    readonly internalProtectDecisionTimeoutMs: 150;
+    readonly internalProtectDecisionTimeoutMs: 160;
     readonly retryDelayMinMs: 200;
     readonly retryDelayMaxMs: 400;
     readonly defaultTokenizerEncoding: "cl100k_base";

package/dist/config.js

@@ -1,12 +1,12 @@
 export const sdkNodeConfig = {
     defaultBaseUrl: "http://localhost:8000",
-    defaultEnvironment: "dev",
+    defaultEnvironment: "unknown",
     defaultFlushIntervalMs: 1000,
     defaultMaxQueueSize: 1000,
     defaultFlushTimeoutMs: 500,
     defaultRequestTimeoutMs: 1000,
     defaultProtectFailMode: "open",
-    internalProtectDecisionTimeoutMs: 150,
+    internalProtectDecisionTimeoutMs: 160,
     retryDelayMinMs: 200,
     retryDelayMaxMs: 400,
     defaultTokenizerEncoding: "cl100k_base",

package/dist/logger.js

@@ -23,7 +23,12 @@ export function emitLog(params) {
         timestamp: new Date().toISOString(),
         level: params.level,
         service: SERVICE_NAME,
-        env: (params.environment ?? process.env.RHEONIC_ENV ?? process.env.NODE_ENV ?? "dev").toLowerCase(),
+        env: (params.environment ??
+            process.env.NODE_ENV ??
+            process.env.APP_ENV ??
+            process.env.ENVIRONMENT ??
+            process.env.ENV ??
+            "unknown").toLowerCase(),
         trace_id: params.traceId ?? getTraceId(),
         span_id: params.spanId ?? getSpanId(),
         event: sanitizeEvent(params.event),

package/dist/protectEngine.d.ts

@@ -45,4 +45,4 @@ export declare class ProtectEngine {
     private reportDecisionTimeout;
     private reportDecisionUnavailable;
 }
-export declare const defaultProtectTimeoutMs: 150;
+export declare const defaultProtectTimeoutMs: 160;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rheonic/sdk",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "description": "Node.js SDK for Rheonic observability and protect preflight enforcement.",
   "author": "Rheonic <founder@rheonic.dev>",
   "license": "MIT",