@rheonic/sdk 0.1.0-beta.1

package/dist/httpTransport.js

@@ -0,0 +1,100 @@
+import http from "node:http";
+import https from "node:https";
+const HTTP_AGENT = new http.Agent({
+    keepAlive: true,
+    maxSockets: 32,
+});
+const HTTPS_AGENT = new https.Agent({
+    keepAlive: true,
+    maxSockets: 32,
+});
+class BufferedJsonResponse {
+    status;
+    payload;
+    ok;
+    constructor(status, payload) {
+        this.status = status;
+        this.payload = payload;
+        this.ok = status >= 200 && status < 300;
+    }
+    async json() {
+        if (!this.payload) {
+            return {};
+        }
+        return JSON.parse(this.payload);
+    }
+}
+export async function requestJson(url, options) {
+    const mockedFetch = getMockedFetchOverride();
+    if (mockedFetch) {
+        const response = await mockedFetch(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 target = new URL(url);
+    const useHttps = target.protocol === "https:";
+    const transport = useHttps ? https : http;
+    const agent = useHttps ? HTTPS_AGENT : HTTP_AGENT;
+    return await new Promise((resolve, reject) => {
+        const req = transport.request({
+            protocol: target.protocol,
+            hostname: target.hostname,
+            port: target.port || (useHttps ? 443 : 80),
+            path: `${target.pathname}${target.search}`,
+            method: options.method,
+            headers: options.headers,
+            agent,
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            });
+            res.on("end", () => {
+                resolve(new BufferedJsonResponse(res.statusCode ?? 0, Buffer.concat(chunks).toString("utf-8")));
+            });
+        });
+        req.on("error", reject);
+        let abortHandler;
+        if (options.signal) {
+            if (options.signal.aborted) {
+                req.destroy(createAbortError());
+            }
+            else {
+                abortHandler = () => req.destroy(createAbortError());
+                options.signal.addEventListener("abort", abortHandler, { once: true });
+            }
+        }
+        req.on("close", () => {
+            if (abortHandler && options.signal) {
+                options.signal.removeEventListener("abort", abortHandler);
+            }
+        });
+        if (options.body) {
+            req.write(options.body);
+        }
+        req.end();
+    });
+}
+function createAbortError() {
+    const error = new Error("Request aborted");
+    error.name = "AbortError";
+    return error;
+}
+function getMockedFetchOverride() {
+    if (typeof globalThis.fetch !== "function") {
+        return null;
+    }
+    const source = Function.prototype.toString.call(globalThis.fetch);
+    if (source.includes("[native code]")) {
+        return null;
+    }
+    return globalThis.fetch.bind(globalThis);
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { Client, type ClientConfig, type ClientStats, type OverflowPolicy } from "./client.js";
+import { buildEvent, type BuildEventInput, type EventPayload } from "./eventBuilder.js";
+import { RHEONICBlockedError } from "./protectEngine.js";
+import { RHEONICValidationError } from "./providerModelValidation.js";
+import { type AnthropicInstrumentationOptions } from "./providers/anthropicAdapter.js";
+import { type GoogleInstrumentationOptions } from "./providers/googleAdapter.js";
+import { type OpenAIInstrumentationOptions } from "./providers/openaiAdapter.js";
+export { Client, RHEONICBlockedError, RHEONICValidationError, type ClientConfig, type ClientStats, type OverflowPolicy, buildEvent, type BuildEventInput, type EventPayload, };
+export declare function createClient(config: ClientConfig): Client;
+export declare function captureEvent(event: EventPayload | BuildEventInput): Promise<void>;
+export declare function instrumentOpenAI<T extends Record<string, any>>(openaiClient: T, options?: Omit<OpenAIInstrumentationOptions, "client"> & {
+    client?: Client;
+}): T;
+export declare function instrumentAnthropic<T extends Record<string, any>>(anthropicClient: T, options?: Omit<AnthropicInstrumentationOptions, "client"> & {
+    client?: Client;
+}): T;
+export declare function instrumentGoogle<T extends Record<string, any>>(googleModel: T, options?: Omit<GoogleInstrumentationOptions, "client"> & {
+    client?: Client;
+}): T;

package/dist/index.js

@@ -0,0 +1,60 @@
+import { Client } from "./client.js";
+import { buildEvent } from "./eventBuilder.js";
+import { RHEONICBlockedError } from "./protectEngine.js";
+import { RHEONICValidationError } from "./providerModelValidation.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";
+let defaultClient = null;
+export { Client, RHEONICBlockedError, RHEONICValidationError, buildEvent, };
+export function createClient(config) {
+    if (defaultClient) {
+        defaultClient.close();
+    }
+    const client = new Client(config);
+    defaultClient = client;
+    return client;
+}
+export async function captureEvent(event) {
+    if (!defaultClient) {
+        return;
+    }
+    const payload = "provider" in event && "ts" in event ? event : buildEvent(event);
+    await defaultClient.captureEvent(payload);
+}
+export function instrumentOpenAI(openaiClient, options) {
+    const resolvedClient = options?.client ?? defaultClient;
+    if (!resolvedClient) {
+        return openaiClient;
+    }
+    return instrumentOpenAIProvider(openaiClient, {
+        client: resolvedClient,
+        environment: options?.environment,
+        endpoint: options?.endpoint,
+        feature: options?.feature,
+    });
+}
+export function instrumentAnthropic(anthropicClient, options) {
+    const resolvedClient = options?.client ?? defaultClient;
+    if (!resolvedClient) {
+        return anthropicClient;
+    }
+    return instrumentAnthropicProvider(anthropicClient, {
+        client: resolvedClient,
+        environment: options?.environment,
+        endpoint: options?.endpoint,
+        feature: options?.feature,
+    });
+}
+export function instrumentGoogle(googleModel, options) {
+    const resolvedClient = options?.client ?? defaultClient;
+    if (!resolvedClient) {
+        return googleModel;
+    }
+    return instrumentGoogleProvider(googleModel, {
+        client: resolvedClient,
+        environment: options?.environment,
+        endpoint: options?.endpoint,
+        feature: options?.feature,
+    });
+}

package/dist/logger.d.ts

@@ -0,0 +1,16 @@
+type LogLevel = "debug" | "info" | "warn" | "error";
+export declare function generateTraceId(): string;
+export declare function generateSpanId(): string;
+export declare function bindTraceContext<T>(traceId: string, spanId: string, fn: () => T): T;
+export declare function getTraceId(): string;
+export declare function getSpanId(): string;
+export declare function emitLog(params: {
+    level: LogLevel;
+    event: string;
+    message: string;
+    metadata?: Record<string, unknown>;
+    traceId?: string;
+    spanId?: string;
+    environment?: string;
+}): void;
+export {};

package/dist/logger.js

@@ -0,0 +1,56 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+const contextStorage = new AsyncLocalStorage();
+const SENSITIVE_MARKERS = ["api_key", "apikey", "authorization", "cookie", "password", "secret", "token"];
+const SERVICE_NAME = "sdk-node";
+export function generateTraceId() {
+    return randomUUID();
+}
+export function generateSpanId() {
+    return randomUUID().replace(/-/g, "").slice(0, 16);
+}
+export function bindTraceContext(traceId, spanId, fn) {
+    return contextStorage.run({ traceId, spanId }, fn);
+}
+export function getTraceId() {
+    return contextStorage.getStore()?.traceId ?? "";
+}
+export function getSpanId() {
+    return contextStorage.getStore()?.spanId ?? "";
+}
+export function emitLog(params) {
+    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(),
+        event: sanitizeEvent(params.event),
+        message: params.message,
+        metadata: sanitizeMetadata(params.metadata ?? {}),
+    };
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+function sanitizeEvent(value) {
+    const normalized = value.trim().toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "");
+    return normalized || "log";
+}
+function sanitizeMetadata(value) {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, sanitizeValue(entry, key)]));
+}
+function sanitizeValue(value, key) {
+    if (key && SENSITIVE_MARKERS.some((marker) => key.toLowerCase().includes(marker))) {
+        return "[REDACTED]";
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeValue(item));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([childKey, childValue]) => [
+            childKey,
+            sanitizeValue(childValue, childKey),
+        ]));
+    }
+    return value ?? null;
+}

package/dist/protectEngine.d.ts

@@ -0,0 +1,48 @@
+export type ProtectDecision = "allow" | "warn" | "block";
+export type ProtectFailMode = "open" | "closed";
+export interface ProtectContext {
+    provider: string;
+    model?: string | null;
+    feature?: string;
+    max_output_tokens?: number;
+    input_tokens_estimate?: number;
+}
+export interface ProtectEvaluation {
+    decision: ProtectDecision;
+    reason: string;
+    snapshot?: Record<string, unknown>;
+    applyClampEnabled?: boolean;
+    clamp?: {
+        recommended_max_output_tokens: number;
+        applied: boolean;
+    };
+}
+export declare class RHEONICBlockedError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export declare class ProtectEngine {
+    private readonly baseUrl;
+    private readonly ingestKey;
+    private readonly environment;
+    private readonly fallbackRequestTimeoutMs;
+    private readonly debugLog?;
+    private failMode;
+    private decisionTimeoutMs;
+    private cooldownUntilMs;
+    private cooldownReason;
+    constructor(params: {
+        baseUrl: string;
+        ingestKey: string;
+        environment: string;
+        fallbackRequestTimeoutMs: number;
+        initialFailMode: ProtectFailMode;
+        initialDecisionTimeoutMs?: number;
+        debugLog?: (message: string, meta?: Record<string, unknown>) => void;
+    });
+    evaluate(context: ProtectContext): Promise<ProtectEvaluation>;
+    bootstrap(): Promise<void>;
+    private reportDecisionTimeout;
+    private reportDecisionUnavailable;
+}
+export declare const defaultProtectTimeoutMs: 150;

package/dist/protectEngine.js

@@ -0,0 +1,255 @@
+import { randomUUID } from "node:crypto";
+import { sdkNodeConfig } from "./config.js";
+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}`);
+        this.name = "RHEONICBlockedError";
+        this.reason = reason;
+    }
+}
+export class ProtectEngine {
+    baseUrl;
+    ingestKey;
+    environment;
+    fallbackRequestTimeoutMs;
+    debugLog;
+    failMode;
+    decisionTimeoutMs;
+    cooldownUntilMs;
+    cooldownReason;
+    constructor(params) {
+        this.baseUrl = params.baseUrl;
+        this.ingestKey = params.ingestKey;
+        this.environment = params.environment;
+        this.fallbackRequestTimeoutMs = params.fallbackRequestTimeoutMs;
+        this.debugLog = params.debugLog;
+        this.failMode = params.initialFailMode;
+        this.decisionTimeoutMs =
+            typeof params.initialDecisionTimeoutMs === "number" && Number.isFinite(params.initialDecisionTimeoutMs) && params.initialDecisionTimeoutMs > 0
+                ? Math.floor(params.initialDecisionTimeoutMs)
+                : sdkNodeConfig.internalProtectDecisionTimeoutMs;
+        this.cooldownUntilMs = null;
+        this.cooldownReason = null;
+    }
+    async evaluate(context) {
+        const nowMs = Date.now();
+        if (this.cooldownUntilMs !== null && nowMs < this.cooldownUntilMs) {
+            this.debugLog?.("Protect preflight blocked locally from cached cooldown", {
+                provider: context.provider,
+                decision: "block",
+                reason: this.cooldownReason ?? "cooldown_active",
+            });
+            return { decision: "block", reason: this.cooldownReason ?? "cooldown_active" };
+        }
+        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`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Project-Ingest-Key": this.ingestKey,
+                    "X-Trace-ID": getTraceId(),
+                    "X-Span-ID": spanId,
+                    "X-Rheonic-Protect-Request-Id": requestId,
+                },
+                body: JSON.stringify(context),
+                signal: controller.signal,
+            }));
+            clearTimeout(timeout);
+            if (!response.ok) {
+                this.debugLog?.("Protect preflight returned non-success status", {
+                    provider: context.provider,
+                    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" };
+            }
+            const parsed = (await response.json());
+            const decision = parseDecision(parsed.decision);
+            const reason = typeof parsed.reason === "string" ? parsed.reason : "ok";
+            const failMode = parseFailMode(parsed.fail_mode);
+            if (failMode) {
+                this.failMode = failMode;
+            }
+            const decisionTimeout = Number(parsed.protect_decision_timeout_ms);
+            if (Number.isFinite(decisionTimeout) && decisionTimeout > 0) {
+                this.decisionTimeoutMs = decisionTimeout;
+            }
+            const blockedUntilMs = parseBlockedUntilMs(parsed.blocked_until);
+            if (blockedUntilMs !== null && blockedUntilMs > Date.now()) {
+                this.cooldownUntilMs = blockedUntilMs;
+                this.cooldownReason = "cooldown_active";
+            }
+            else if (this.cooldownUntilMs !== null && Date.now() >= this.cooldownUntilMs) {
+                this.cooldownUntilMs = null;
+                this.cooldownReason = null;
+            }
+            this.debugLog?.("Protect preflight completed", {
+                provider: context.provider,
+                decision,
+                reason,
+                latency_ms: Date.now() - startedAt,
+                timeout_ms: this.decisionTimeoutMs,
+            });
+            return {
+                decision,
+                reason,
+                snapshot: parseSnapshot(parsed.snapshot),
+                applyClampEnabled: typeof parsed.apply_clamp_enabled === "boolean" ? parsed.apply_clamp_enabled : undefined,
+                clamp: parseClamp(parsed.clamp),
+            };
+        }
+        catch (error) {
+            clearTimeout(timeout);
+            if (isAbortError(error)) {
+                this.debugLog?.("Protect preflight timed out", {
+                    provider: context.provider,
+                    latency_ms: Date.now() - startedAt,
+                    timeout_ms: timeoutMs,
+                });
+                void this.reportDecisionTimeout(context.provider, typeof context.model === "string" ? context.model : undefined, requestId);
+            }
+            else {
+                this.debugLog?.("Protect preflight failed", {
+                    provider: context.provider,
+                    latency_ms: Date.now() - startedAt,
+                    error_type: extractErrorType(error),
+                });
+                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" };
+        }
+    }
+    async bootstrap() {
+        try {
+            const response = await requestJson(`${this.baseUrl}/api/v1/protect/config`, {
+                method: "GET",
+                headers: {
+                    "X-Project-Ingest-Key": this.ingestKey,
+                    "X-Trace-ID": generateTraceId(),
+                    "X-Span-ID": generateSpanId(),
+                },
+            });
+            if (!response.ok) {
+                return;
+            }
+            const parsed = (await response.json());
+            const failMode = parseFailMode(parsed.protect_fail_mode);
+            if (failMode) {
+                this.failMode = failMode;
+            }
+            const decisionTimeout = Number(parsed.protect_decision_timeout_ms);
+            if (Number.isFinite(decisionTimeout) && decisionTimeout > 0) {
+                this.decisionTimeoutMs = Math.floor(decisionTimeout);
+            }
+        }
+        catch {
+            // Best effort only; keep local defaults if bootstrap fails.
+        }
+    }
+    async reportDecisionTimeout(provider, model, requestId) {
+        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-Span-ID": generateSpanId(),
+                    "X-Rheonic-Protect-Request-Id": requestId,
+                },
+                body: JSON.stringify({ environment: this.environment, provider, model, request_id: requestId }),
+            });
+        }
+        catch {
+            // Swallow timeout reporting errors; protect evaluation must never throw here.
+        }
+    }
+    async reportDecisionUnavailable(provider, model, requestId) {
+        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-Span-ID": generateSpanId(),
+                    "X-Rheonic-Protect-Request-Id": requestId,
+                },
+                body: JSON.stringify({ environment: this.environment, provider, model, request_id: requestId }),
+            });
+        }
+        catch {
+            // Swallow unavailable reporting errors; protect evaluation must never throw here.
+        }
+    }
+}
+function parseClamp(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const candidate = value;
+    if (typeof candidate.recommended_max_output_tokens !== "number" || candidate.recommended_max_output_tokens < 1) {
+        return undefined;
+    }
+    return {
+        recommended_max_output_tokens: Math.floor(candidate.recommended_max_output_tokens),
+        applied: typeof candidate.applied === "boolean" ? candidate.applied : false,
+    };
+}
+function parseSnapshot(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}
+function parseBlockedUntilMs(value) {
+    if (typeof value !== "string" || !value) {
+        return null;
+    }
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return null;
+    }
+    return parsed;
+}
+function parseDecision(value) {
+    if (value === "warn" || value === "block" || value === "allow") {
+        return value;
+    }
+    return "allow";
+}
+function parseFailMode(value) {
+    if (value === "open" || value === "closed") {
+        return value;
+    }
+    return null;
+}
+function isAbortError(value) {
+    return typeof value === "object" && value !== null && "name" in value && value.name === "AbortError";
+}
+function extractErrorType(value) {
+    if (value && typeof value === "object" && "name" in value) {
+        const maybeName = value.name;
+        if (typeof maybeName === "string" && maybeName.length > 0) {
+            return maybeName;
+        }
+    }
+    return "unknown";
+}
+export const defaultProtectTimeoutMs = sdkNodeConfig.internalProtectDecisionTimeoutMs;

package/dist/providerModelValidation.d.ts

@@ -0,0 +1,7 @@
+export declare class RHEONICValidationError extends Error {
+    readonly provider: string;
+    readonly model: string;
+    readonly expectedProviders: readonly string[];
+    constructor(message: string, provider: string, model: string, expectedProviders: readonly string[]);
+}
+export declare function validateProviderModel(provider: string, model: string | null | undefined): void;

package/dist/providerModelValidation.js

@@ -0,0 +1,26 @@
+import { sdkNodeConfig } from "./config.js";
+export class RHEONICValidationError extends Error {
+    provider;
+    model;
+    expectedProviders;
+    constructor(message, provider, model, expectedProviders) {
+        super(message);
+        this.name = "RHEONICValidationError";
+        this.provider = provider;
+        this.model = model;
+        this.expectedProviders = expectedProviders;
+    }
+}
+export function validateProviderModel(provider, model) {
+    const normalizedProvider = provider.trim().toLowerCase();
+    if (!normalizedProvider) {
+        throw new RHEONICValidationError("RHEONIC: provider must be explicitly provided.", provider, String(model ?? ""), sdkNodeConfig.supportedProviders);
+    }
+    if (!sdkNodeConfig.supportedProviders.includes(normalizedProvider)) {
+        throw new RHEONICValidationError(`RHEONIC: unsupported provider: ${provider}`, provider, String(model ?? ""), sdkNodeConfig.supportedProviders);
+    }
+    const normalizedModel = typeof model === "string" ? model.trim() : "";
+    if (!normalizedModel) {
+        throw new RHEONICValidationError(`RHEONIC: model must be explicitly provided for provider ${normalizedProvider}.`, normalizedProvider, String(model ?? ""), sdkNodeConfig.supportedProviders);
+    }
+}

package/dist/providers/anthropicAdapter.d.ts

@@ -0,0 +1,9 @@
+import type { Client } from "../client.js";
+export interface AnthropicInstrumentationOptions {
+    client: Client;
+    environment?: string;
+    endpoint?: string;
+    feature?: string;
+}
+export declare function __setInputTokenEstimatorForTests(estimator: ((payload: unknown) => number | null) | null): void;
+export declare function instrumentAnthropic<T extends Record<string, any>>(anthropicClient: T, options: AnthropicInstrumentationOptions): T;