@rheonic/sdk 0.1.0-beta.6 → 0.1.0-beta.8

package/CHANGELOG.md

@@ -1,12 +1,18 @@
 # 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.
 
-## 0.1.0
+## 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-beta.6
 
 ### Added
 - Initial public beta release of the Rheonic Node SDK.

package/README.md

@@ -48,7 +48,19 @@ try {
   });
 } catch (error) {
   if (error instanceof RHEONICBlockedError) {
-    console.log("Blocked by protect preflight");
+    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,
+      ),
+    );
   }
 }
 ```
@@ -74,7 +86,13 @@ try {
   });
 } catch (error) {
   if (error instanceof RHEONICBlockedError) {
-    console.log("Blocked by protect preflight");
+    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));
   }
 }
 ```
@@ -97,11 +115,25 @@ try {
   await model.generateContent("hello");
 } catch (error) {
   if (error instanceof RHEONICBlockedError) {
-    console.log("Blocked by protect preflight");
+    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));
   }
 }
 ```
 
+`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

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

@@ -98,6 +98,10 @@ export class Client {
             return;
         }
     }
+    async captureEventAndFlush(event) {
+        await this.captureEvent(event);
+        await this.flushWithTimeout();
+    }
     getStats() {
         return {
             queued: this.queue.length,

package/dist/protectEngine.d.ts

@@ -10,6 +10,10 @@ export interface ProtectContext {
 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 +23,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,6 +57,7 @@ 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;

package/dist/protectEngine.js

@@ -4,10 +4,20 @@ import { requestJson } from "./httpTransport.js";
 import { bindTraceContext, generateSpanId, generateTraceId, getTraceId } from "./logger.js";
 export class RHEONICBlockedError extends Error {
     reason;
-    constructor(reason) {
-        super(`Request blocked by Rheonic: ${reason}`);
+    trace_id;
+    request_id;
+    blocked_until;
+    retry_after_seconds;
+    snapshot;
+    constructor(params) {
+        super(`Request blocked by Rheonic: ${params.reason}`);
         this.name = "RHEONICBlockedError";
-        this.reason = reason;
+        this.reason = params.reason;
+        this.trace_id = params.trace_id;
+        this.request_id = params.request_id;
+        this.blocked_until = params.blocked_until;
+        this.retry_after_seconds = params.retry_after_seconds;
+        this.snapshot = params.snapshot;
     }
 }
 export class ProtectEngine {
@@ -35,6 +45,8 @@ export class ProtectEngine {
         this.cooldownReason = null;
     }
     async evaluate(context) {
+        const requestId = randomUUID();
+        const traceId = generateTraceId();
         const nowMs = Date.now();
         if (this.cooldownUntilMs !== null && nowMs < this.cooldownUntilMs) {
             this.debugLog?.("Protect preflight blocked locally from cached cooldown", {
@@ -42,15 +54,20 @@ export class ProtectEngine {
                 decision: "block",
                 reason: this.cooldownReason ?? "cooldown_active",
             });
-            return { decision: "block", reason: this.cooldownReason ?? "cooldown_active" };
+            return {
+                decision: "block",
+                reason: this.cooldownReason ?? "cooldown_active",
+                trace_id: traceId,
+                request_id: requestId,
+                blocked_until: formatBlockedUntilMs(this.cooldownUntilMs),
+                retry_after_seconds: toRetryAfterSeconds(this.cooldownUntilMs, nowMs),
+            };
         }
         const controller = new AbortController();
         const timeoutMs = this.decisionTimeoutMs > 0 ? this.decisionTimeoutMs : this.fallbackRequestTimeoutMs;
         const timeout = setTimeout(() => controller.abort(), timeoutMs);
         timeout.unref?.();
         const startedAt = Date.now();
-        const requestId = randomUUID();
-        const traceId = generateTraceId();
         const spanId = generateSpanId();
         try {
             const response = await bindTraceContext(traceId, spanId, async () => await requestJson(`${this.baseUrl}/api/v1/protect/decision`, {
@@ -72,10 +89,8 @@ export class ProtectEngine {
                     status_code: response.status,
                     latency_ms: Date.now() - startedAt,
                 });
-                void this.reportDecisionUnavailable(context.provider, typeof context.model === "string" ? context.model : undefined, requestId);
-                return this.failMode === "closed"
-                    ? { decision: "block", reason: "decision_unavailable" }
-                    : { decision: "allow", reason: "decision_unavailable" };
+                void this.reportDecisionUnavailable(context.provider, typeof context.model === "string" ? context.model : undefined, requestId, traceId);
+                return this.fallbackEvaluation(traceId, requestId);
             }
             const parsed = (await response.json());
             const decision = parseDecision(parsed.decision);
@@ -107,6 +122,10 @@ export class ProtectEngine {
             return {
                 decision,
                 reason,
+                trace_id: traceId,
+                request_id: requestId,
+                blocked_until: typeof parsed.blocked_until === "string" ? parsed.blocked_until : undefined,
+                retry_after_seconds: parseRetryAfterSeconds(parsed.retry_after_seconds),
                 snapshot: parseSnapshot(parsed.snapshot),
                 applyClampEnabled: typeof parsed.apply_clamp_enabled === "boolean" ? parsed.apply_clamp_enabled : undefined,
                 clamp: parseClamp(parsed.clamp),
@@ -120,7 +139,7 @@ export class ProtectEngine {
                     latency_ms: Date.now() - startedAt,
                     timeout_ms: timeoutMs,
                 });
-                void this.reportDecisionTimeout(context.provider, typeof context.model === "string" ? context.model : undefined, requestId);
+                void this.reportDecisionTimeout(context.provider, typeof context.model === "string" ? context.model : undefined, requestId, traceId);
             }
             else {
                 this.debugLog?.("Protect preflight failed", {
@@ -128,13 +147,19 @@ export class ProtectEngine {
                     latency_ms: Date.now() - startedAt,
                     error_type: extractErrorType(error),
                 });
-                void this.reportDecisionUnavailable(context.provider, typeof context.model === "string" ? context.model : undefined, requestId);
+                void this.reportDecisionUnavailable(context.provider, typeof context.model === "string" ? context.model : undefined, requestId, traceId);
             }
-            return this.failMode === "closed"
-                ? { decision: "block", reason: "decision_unavailable" }
-                : { decision: "allow", reason: "decision_unavailable" };
+            return this.fallbackEvaluation(traceId, requestId);
         }
     }
+    fallbackEvaluation(traceId, requestId) {
+        return {
+            decision: this.failMode === "closed" ? "block" : "allow",
+            reason: this.failMode === "closed" ? "fail_closed" : "decision_unavailable",
+            trace_id: traceId,
+            request_id: requestId,
+        };
+    }
     async bootstrap() {
         try {
             const response = await requestJson(`${this.baseUrl}/api/v1/protect/config`, {
@@ -162,14 +187,14 @@ export class ProtectEngine {
             // Best effort only; keep local defaults if bootstrap fails.
         }
     }
-    async reportDecisionTimeout(provider, model, requestId) {
+    async reportDecisionTimeout(provider, model, requestId, traceId) {
         try {
             await requestJson(`${this.baseUrl}/api/v1/protect/decision-timeout`, {
                 method: "POST",
                 headers: {
                     "Content-Type": "application/json",
                     "X-Project-Ingest-Key": this.ingestKey,
-                    "X-Trace-ID": generateTraceId(),
+                    "X-Trace-ID": traceId,
                     "X-Span-ID": generateSpanId(),
                     "X-Rheonic-Protect-Request-Id": requestId,
                 },
@@ -180,14 +205,14 @@ export class ProtectEngine {
             // Swallow timeout reporting errors; protect evaluation must never throw here.
         }
     }
-    async reportDecisionUnavailable(provider, model, requestId) {
+    async reportDecisionUnavailable(provider, model, requestId, traceId) {
         try {
             await requestJson(`${this.baseUrl}/api/v1/protect/decision-unavailable`, {
                 method: "POST",
                 headers: {
                     "Content-Type": "application/json",
                     "X-Project-Ingest-Key": this.ingestKey,
-                    "X-Trace-ID": generateTraceId(),
+                    "X-Trace-ID": traceId,
                     "X-Span-ID": generateSpanId(),
                     "X-Rheonic-Protect-Request-Id": requestId,
                 },
@@ -234,6 +259,24 @@ function parseDecision(value) {
     }
     return "allow";
 }
+function parseRetryAfterSeconds(value) {
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+        return Math.floor(value);
+    }
+    return undefined;
+}
+function formatBlockedUntilMs(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        return undefined;
+    }
+    return new Date(value).toISOString();
+}
+function toRetryAfterSeconds(blockedUntilMs, nowMs) {
+    if (typeof blockedUntilMs !== "number" || !Number.isFinite(blockedUntilMs) || blockedUntilMs <= nowMs) {
+        return undefined;
+    }
+    return Math.max(0, Math.ceil((blockedUntilMs - nowMs) / 1000));
+}
 function parseFailMode(value) {
     if (value === "open" || value === "closed") {
         return value;

package/dist/providers/anthropicAdapter.js

@@ -42,13 +42,13 @@ export function instrumentAnthropic(anthropicClient, options) {
         }
         const protectDecision = await options.client.evaluateProtectDecision(protectPayload);
         if (protectDecision.decision === "block") {
-            throw new RHEONICBlockedError(protectDecision.reason);
+            throw new RHEONICBlockedError(protectDecision);
         }
         const callArgs = maybeApplyAnthropicClamp(args, protectDecision);
         markClampAppliedIfChanged(protectDecision, extractMaxOutputTokens(args), extractMaxOutputTokens(callArgs));
         try {
             const response = await originalCreate(...callArgs);
-            void options.client.captureEvent(buildEvent({
+            await options.client.captureEventAndFlush(buildEvent({
                 provider: "anthropic",
                 model: extractResponseModel(response) ?? requestedModel,
                 environment: options.environment ?? options.client.environment,
@@ -69,7 +69,7 @@ export function instrumentAnthropic(anthropicClient, options) {
             return response;
         }
         catch (error) {
-            void options.client.captureEvent(buildEvent({
+            await options.client.captureEventAndFlush(buildEvent({
                 provider: "anthropic",
                 model: requestedModel,
                 environment: options.environment ?? options.client.environment,

package/dist/providers/googleAdapter.js

@@ -42,13 +42,13 @@ export function instrumentGoogle(googleModel, options) {
         }
         const protectDecision = await options.client.evaluateProtectDecision(protectPayload);
         if (protectDecision.decision === "block") {
-            throw new RHEONICBlockedError(protectDecision.reason);
+            throw new RHEONICBlockedError(protectDecision);
         }
         const callArgs = maybeApplyGoogleClamp(args, protectDecision);
         markClampAppliedIfChanged(protectDecision, extractMaxOutputTokens(args), extractMaxOutputTokens(callArgs));
         try {
             const response = await originalGenerate(...callArgs);
-            void options.client.captureEvent(buildEvent({
+            await options.client.captureEventAndFlush(buildEvent({
                 provider: "google",
                 model: requestedModel,
                 environment: options.environment ?? options.client.environment,
@@ -69,7 +69,7 @@ export function instrumentGoogle(googleModel, options) {
             return response;
         }
         catch (error) {
-            void options.client.captureEvent(buildEvent({
+            await options.client.captureEventAndFlush(buildEvent({
                 provider: "google",
                 model: requestedModel,
                 environment: options.environment ?? options.client.environment,

package/dist/providers/openaiAdapter.js

@@ -43,13 +43,13 @@ export function instrumentOpenAI(openaiClient, options) {
             ...protectPayload,
         });
         if (protectDecision.decision === "block") {
-            throw new RHEONICBlockedError(protectDecision.reason);
+            throw new RHEONICBlockedError(protectDecision);
         }
         const callArgs = maybeApplyOpenAIClamp(args, protectDecision);
         markClampAppliedIfChanged(protectDecision, extractMaxOutputTokens(args), extractMaxOutputTokens(callArgs));
         try {
             const response = await originalCreate(...callArgs);
-            void options.client.captureEvent(buildEvent({
+            await options.client.captureEventAndFlush(buildEvent({
                 provider: "openai",
                 model: extractResponseModel(response) ?? model,
                 environment: options.environment ?? options.client.environment,
@@ -69,7 +69,7 @@ export function instrumentOpenAI(openaiClient, options) {
             return response;
         }
         catch (error) {
-            void options.client.captureEvent(buildEvent({
+            await options.client.captureEventAndFlush(buildEvent({
                 provider: "openai",
                 model,
                 environment: options.environment ?? options.client.environment,

package/package.json

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