@rheonic/sdk 0.1.0-beta.1 → 0.1.0-beta.11

package/CHANGELOG.md

@@ -1,12 +1,24 @@
 # Changelog
 
-All notable changes to `rheonic-node` will be documented in this file.
+All notable changes to `@rheonic/sdk` will be documented in this file.
 
 ## Unreleased
 
-- Publish-ready changelog entries will be added here for the next release.
+### Changed
+- Google provider instrumentation and examples now align with the current official Google Gen AI JavaScript SDK shape: `@google/genai` with `ai.models.generateContent({...})`.
+
+### Fixed
+- SDK debug logs now always emit non-empty `trace_id` and `span_id`, including warmup, token-estimation, and protect preflight paths.
+- Provider instrumentation now keeps the full protected call lifecycle under one trace so SDK debug logs correlate cleanly with backend requests.
+- Quickstart and README examples now use the published `@rheonic/sdk` package name consistently and show the current Anthropic and Google instrumentation patterns.
+
+## 0.1.0-beta.7
+
+### Changed
+- `RHEONICBlockedError` now exposes structured block feedback for apps and agents: `reason`, `retry_after_seconds`, `blocked_until`, `trace_id`, `request_id`, and `snapshot`.
+- Fail-closed protect fallback now reports `reason="fail_closed"` instead of the generic `decision_unavailable` on blocked requests.
 
-## 0.1.0
+## 0.1.0-beta.6
 
 ### Added
 - Initial public beta release of the Rheonic Node SDK.

package/README.md

@@ -1,150 +1,179 @@
 # 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-node@next
+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`.
+## Required environment variables
 
-## Configuration
+```bash
+RHEONIC_INGEST_KEY=<your_project_ingest_key>
+RHEONIC_BASE_URL=<value_shown_in_dashboard>
+```
 
-- Required: `ingestKey`
-- Optional for local development: `baseUrl` (defaults to `RHEONIC_BASE_URL`, else `http://localhost:8000`)
-- Optional: `environment` (default `dev`)
+## Instrument provider calls
 
-For hosted beta, staging, or production deployments, set `RHEONIC_BASE_URL` or pass `baseUrl` explicitly. The localhost default is intended only for local development.
+Wrap your provider SDK once.
 
-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.
+Telemetry is captured automatically after each provider call.
 
-## Integration Recommendation
+Enforcement follows Project mode in the dashboard (`Observe` / `Protect`).
 
-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.
+OpenAI:
 
-## Logging
+```ts
+import OpenAI from "openai";
+import { createClient, instrumentOpenAI, RHEONICBlockedError } from "@rheonic/sdk";
 
-The SDK emits structured JSON logs to stdout. You do not need to configure file logging.
+const rheonic = createClient({
+  baseUrl: process.env.RHEONIC_BASE_URL!,
+  ingestKey: process.env.RHEONIC_INGEST_KEY!,
+});
 
-Example log:
+const openai = instrumentOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY! }), {
+  client: rheonic,
+  endpoint: "/chat/completions",
+  feature: "assistant",
+});
 
-```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": {}
+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(
+      JSON.stringify(
+        {
+          reason: error.reason,
+          retry_after_seconds: error.retry_after_seconds,
+          blocked_until: error.blocked_until,
+          trace_id: error.trace_id,
+          request_id: error.request_id,
+        },
+        null,
+        2,
+      ),
+    );
+  }
 }
 ```
 
-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)
+Anthropic:
 
 ```ts
-import { buildEvent, createClient } from "@rheonic/sdk";
+import Anthropic from "@anthropic-ai/sdk";
+import { createClient, instrumentAnthropic, 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 anthropic = instrumentAnthropic(new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }), {
+  client: rheonic,
+  endpoint: "/v1/messages",
   feature: "assistant",
-  inputTokensEstimate: 32,
-  maxOutputTokens: 256,
 });
+
+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(JSON.stringify({
+      reason: error.reason,
+      retry_after_seconds: error.retry_after_seconds,
+      blocked_until: error.blocked_until,
+      trace_id: error.trace_id,
+      request_id: error.request_id,
+    }, null, 2));
+  }
+}
 ```
 
-## Integration Path 2: OpenAI instrumentation (convenience wrapper)
+Google:
 
 ```ts
-import OpenAI from "openai";
-import { createClient, instrumentOpenAI } from "rheonic-node";
+import { GoogleGenAI } from "@google/genai";
+import { createClient, instrumentGoogle, 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",
+
+const ai = instrumentGoogle(new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY! }), {
+  client: rheonic,
+  endpoint: "/v1beta/models/generateContent",
   feature: "assistant",
 });
+
+try {
+  await ai.models.generateContent({
+    model: "gemini-1.5-pro",
+    contents: "hello",
+    config: {
+      maxOutputTokens: 256,
+    },
+  });
+} catch (error) {
+  if (error instanceof RHEONICBlockedError) {
+    console.log(JSON.stringify({
+      reason: error.reason,
+      retry_after_seconds: error.retry_after_seconds,
+      blocked_until: error.blocked_until,
+      trace_id: error.trace_id,
+      request_id: error.request_id,
+    }, null, 2));
+  }
+}
 ```
 
-## Integration Path 3: Anthropic and Google wrappers
+`RHEONICBlockedError.reason` is meant to be operator-relevant. The main values are:
+- `tok_cap_breach`
+- `req_cap_breach`
+- `cooldown_active`
+- `fail_closed`
+
+If Protect is `fail_open`, timeout or availability problems stay internal and the provider call continues. If Protect is `fail_closed`, the SDK raises `RHEONICBlockedError` with the feedback fields shown above.
+
+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.
+
+## Optional: custom event capture
+
+Use this only if you can't instrument a provider SDK or need custom events.
 
 ```ts
-import Anthropic from "@anthropic-ai/sdk";
-import { GoogleGenerativeAI } from "@google/generative-ai";
-import { createClient } from "rheonic-node";
+import { createClient, buildEvent } from "@rheonic/sdk";
 
 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");
+await client.captureEvent(
+  buildEvent({
+    provider: "openai",
+    model: "gpt-4o-mini",
+    request: { endpoint: "/chat/completions", feature: "assistant", token_explosion_tokens: 64 },
+    response: { total_tokens: 64, latency_ms: 120, http_status: 200 },
+  }),
+);
 ```
 
-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
+`token_explosion_tokens` is optional. Set it only for custom/manual events when you want token-explosion detection to use the same request-context signal that the SDK instrumentation sends to both protect and ingest.
 
-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
-```
+## Reference
 
-Beta prereleases use semver prerelease format such as `0.2.0-beta.1` and are published under the `next` tag.
+Full quickstart:
+- `https://beta.rheonic.dev/quickstart`

package/dist/client.d.ts

@@ -42,6 +42,7 @@ export declare class Client {
     private warmupCompleted;
     constructor(config: ClientConfig);
     captureEvent(event: EventPayload): Promise<void>;
+    captureEventAndFlush(event: EventPayload): Promise<void>;
     getStats(): ClientStats;
     flush(): Promise<void>;
     evaluateProtectDecision(context: ProtectContext): Promise<ProtectEvaluation>;

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";
@@ -92,6 +98,10 @@ export class Client {
             return;
         }
     }
+    async captureEventAndFlush(event) {
+        await this.captureEvent(event);
+        await this.flushWithTimeout();
+    }
     getStats() {
         return {
             queued: this.queue.length,
@@ -120,7 +130,11 @@ export class Client {
     }
     async evaluateProtectDecision(context) {
         await this.ensureWarmup();
-        return this.protectEngine.evaluate(context);
+        return this.protectEngine.evaluate({
+            ...context,
+            trace_id: context.trace_id ?? getTraceId() ?? undefined,
+            span_id: context.span_id ?? getSpanId() ?? undefined,
+        });
     }
     async warmConnections() {
         if (this.warmupCompleted) {
@@ -146,21 +160,29 @@ export class Client {
     }
     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 });
+            const traceId = generateTraceId();
+            const spanId = generateSpanId();
+            await bindTraceContext(traceId, spanId, async () => {
+                const response = 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");
+            const traceId = generateTraceId();
+            const spanId = generateSpanId();
+            await bindTraceContext(traceId, spanId, async () => {
+                await this.protectEngine.bootstrap();
+                this.debugLog("SDK protect config bootstrap completed");
+            });
         }
         catch {
             this.debugLog("SDK protect config bootstrap failed");

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: 300;
     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: 300,
     retryDelayMinMs: 200,
     retryDelayMaxMs: 400,
     defaultTokenizerEncoding: "cl100k_base",

package/dist/eventBuilder.d.ts

@@ -1,8 +1,10 @@
 export interface EventRequest {
     endpoint?: string;
     feature?: string;
+    request_fingerprint?: string;
     input_tokens?: number;
     input_tokens_estimate?: number;
+    token_explosion_tokens?: number;
     max_output_tokens?: number;
     protect_decision?: string;
     protect_reason?: string;

package/dist/httpTransport.js

@@ -25,19 +25,18 @@ class BufferedJsonResponse {
     }
 }
 export async function requestJson(url, options) {
-    const mockedFetch = getMockedFetchOverride();
-    if (mockedFetch) {
-        const response = await mockedFetch(url, {
+    if (typeof globalThis.fetch === "function") {
+        const response = await globalThis.fetch(url, {
             method: options.method,
             headers: options.headers,
             body: options.body,
             signal: options.signal,
         });
-        return {
-            ok: response.ok,
-            status: response.status,
-            json: async () => await response.json(),
-        };
+        const textReader = response.text;
+        const payload = typeof textReader === "function"
+            ? await textReader.call(response)
+            : await serializeFetchJson(response);
+        return new BufferedJsonResponse(response.status, payload);
     }
     const target = new URL(url);
     const useHttps = target.protocol === "https:";
@@ -88,13 +87,10 @@ function createAbortError() {
     error.name = "AbortError";
     return error;
 }
-function getMockedFetchOverride() {
-    if (typeof globalThis.fetch !== "function") {
-        return null;
+async function serializeFetchJson(response) {
+    if (typeof response.json !== "function") {
+        return "";
     }
-    const source = Function.prototype.toString.call(globalThis.fetch);
-    if (source.includes("[native code]")) {
-        return null;
-    }
-    return globalThis.fetch.bind(globalThis);
+    const payload = await response.json();
+    return payload == null ? "" : JSON.stringify(payload);
 }

package/dist/logger.js

@@ -19,13 +19,20 @@ export function getSpanId() {
     return contextStorage.getStore()?.spanId ?? "";
 }
 export function emitLog(params) {
+    const traceId = params.traceId ?? getTraceId();
+    const spanId = params.spanId ?? getSpanId();
     const payload = {
         timestamp: new Date().toISOString(),
         level: params.level,
         service: SERVICE_NAME,
-        env: (params.environment ?? process.env.RHEONIC_ENV ?? process.env.NODE_ENV ?? "dev").toLowerCase(),
-        trace_id: params.traceId ?? getTraceId(),
-        span_id: params.spanId ?? getSpanId(),
+        env: (params.environment ??
+            process.env.NODE_ENV ??
+            process.env.APP_ENV ??
+            process.env.ENVIRONMENT ??
+            process.env.ENV ??
+            "unknown").toLowerCase(),
+        trace_id: traceId || generateTraceId(),
+        span_id: spanId || generateSpanId(),
         event: sanitizeEvent(params.event),
         message: params.message,
         metadata: sanitizeMetadata(params.metadata ?? {}),

package/dist/protectEngine.d.ts

@@ -1,4 +1,4 @@
-export type ProtectDecision = "allow" | "warn" | "block";
+export type ProtectDecision = "allow" | "clamp" | "block";
 export type ProtectFailMode = "open" | "closed";
 export interface ProtectContext {
     provider: string;
@@ -6,10 +6,16 @@ export interface ProtectContext {
     feature?: string;
     max_output_tokens?: number;
     input_tokens_estimate?: number;
+    trace_id?: string;
+    span_id?: string;
 }
 export interface ProtectEvaluation {
     decision: ProtectDecision;
     reason: string;
+    trace_id: string;
+    request_id: string;
+    blocked_until?: string;
+    retry_after_seconds?: number;
     snapshot?: Record<string, unknown>;
     applyClampEnabled?: boolean;
     clamp?: {
@@ -19,7 +25,19 @@ export interface ProtectEvaluation {
 }
 export declare class RHEONICBlockedError extends Error {
     readonly reason: string;
-    constructor(reason: string);
+    readonly trace_id: string;
+    readonly request_id: string;
+    readonly blocked_until?: string;
+    readonly retry_after_seconds?: number;
+    readonly snapshot?: Record<string, unknown>;
+    constructor(params: {
+        reason: string;
+        trace_id: string;
+        request_id: string;
+        blocked_until?: string;
+        retry_after_seconds?: number;
+        snapshot?: Record<string, unknown>;
+    });
 }
 export declare class ProtectEngine {
     private readonly baseUrl;
@@ -41,8 +59,9 @@ export declare class ProtectEngine {
         debugLog?: (message: string, meta?: Record<string, unknown>) => void;
     });
     evaluate(context: ProtectContext): Promise<ProtectEvaluation>;
+    private fallbackEvaluation;
     bootstrap(): Promise<void>;
     private reportDecisionTimeout;
     private reportDecisionUnavailable;
 }
-export declare const defaultProtectTimeoutMs: 150;
+export declare const defaultProtectTimeoutMs: 300;