retrace-sdk 0.13.2 → 0.14.0

package/README.md

@@ -15,7 +15,7 @@ Requires Node.js 20+. ESM-only package.
 ```typescript
 import { configure, trace } from "retrace-sdk";
 
-configure({ apiKey: "rt_live_..." }); // Get your key at retraceai.tech/settings
+configure({ apiKey: "rt_..." }); // Get your key at retraceai.tech/settings
 
 const myAgent = trace(async (prompt: string) => {
   const response = await openai.chat.completions.create({
@@ -44,7 +44,7 @@ No extra setup needed. Install the provider SDK alongside `retrace-sdk`.
 import { configure } from "retrace-sdk";
 
 configure({
-  apiKey: "rt_live_...",           // or RETRACE_API_KEY env var
+  apiKey: "rt_...",           // or RETRACE_API_KEY env var
   baseUrl: "https://api.retraceai.tech",
   projectId: "...",                 // or RETRACE_PROJECT_ID env var
 });
@@ -74,7 +74,7 @@ Mark a function as resumable to enable full cascade replay from the dashboard:
 ```typescript
 import { configure, trace } from "retrace-sdk";
 
-configure({ apiKey: "rt_live_..." });
+configure({ apiKey: "rt_..." });
 
 const myAgent = trace(async (prompt: string) => {
   const plan = await planner(prompt);
@@ -101,7 +101,7 @@ Hard ceilings that stop a runaway agent before the next call. Local limits are e
 import { configure, RetraceEnforcementError } from "retrace-sdk";
 
 configure({
-  apiKey: "rt_live_...",
+  apiKey: "rt_...",
   maxStepsPerRun: 50,
   maxUsdPerRun: 2.0,
   serverEnforcement: true, // optional: also consult server policies
@@ -141,7 +141,7 @@ writeGoldenCassette("golden.json", { recorder });
 ## Sampling
 
 ```typescript
-configure({ apiKey: "rt_live_...", sampleRate: 0.1 }); // Record 10% of traces
+configure({ apiKey: "rt_...", sampleRate: 0.1 }); // Record 10% of traces
 ```
 
 ## Changelog

package/dist/config.d.ts

@@ -32,6 +32,10 @@ export interface Config {
      *  the fail-closed timeout verdict. 0 = trip immediately. (The auto path is synchronous, so the
      *  poll runs in the background and a denial/timeout trips the NEXT span.) */
     enforcementHoldWaitSeconds: number;
+    /** Environment indicator sent with every trace as `metadata.environment`. Set to "sandbox" to
+     *  record into the auto-expiring sandbox data-namespace instead of production (the server also
+     *  accepts an `X-Retrace-Environment` header). Env: RETRACE_ENVIRONMENT. */
+    environment: string | undefined;
 }
 export declare function configure(opts: Partial<Config>): Config;
 export declare function requireApiKey(): string;

package/dist/config.js

@@ -13,11 +13,12 @@ const config = {
     maxUsdPerRun: process.env.RETRACE_MAX_USD_PER_RUN ? parseFloat(process.env.RETRACE_MAX_USD_PER_RUN) : undefined,
     serverEnforcement: ["true", "1", "yes"].includes((process.env.RETRACE_SERVER_ENFORCEMENT || "").toLowerCase()),
     enforcementHoldWaitSeconds: process.env.RETRACE_ENFORCEMENT_HOLD_WAIT_SECONDS ? parseInt(process.env.RETRACE_ENFORCEMENT_HOLD_WAIT_SECONDS, 10) : 0,
+    environment: process.env.RETRACE_ENVIRONMENT || undefined,
 };
 config.wsUrl = config.baseUrl.replace("https://", "wss://").replace("http://", "ws://");
 export function configure(opts) {
-    if (opts.apiKey && !opts.apiKey.startsWith("rt_live_")) {
-        throw new Error("Invalid Retrace API key. Keys must start with 'rt_live_'. Get yours at https://retraceai.tech/settings");
+    if (opts.apiKey && (!opts.apiKey.startsWith("rt_") || opts.apiKey.startsWith("rt_live_") || opts.apiKey.startsWith("rt_test_"))) {
+        throw new Error("Invalid Retrace API key. Keys must start with 'rt_'. Get yours at https://retraceai.tech/settings");
     }
     Object.assign(config, opts);
     if (opts.baseUrl && !opts.wsUrl) {
@@ -30,11 +31,12 @@ export function configure(opts) {
     if (config.enabled) {
         void import("./interceptors/install.js").then((m) => m.ensureInterceptorsInstalled()).catch(() => { });
     }
+    void import("./telemetry.js").then((m) => m.track("configure")).catch(() => { });
     return config;
 }
 export function requireApiKey() {
     if (!config.apiKey) {
-        throw new Error("Retrace API key required. Call configure({ apiKey: 'rt_live_...' }) or set RETRACE_API_KEY. Get yours at https://retraceai.tech/settings");
+        throw new Error("Retrace API key required. Call configure({ apiKey: 'rt_...' }) or set RETRACE_API_KEY. Get yours at https://retraceai.tech/settings");
     }
     return config.apiKey;
 }

package/dist/telemetry.d.ts

@@ -0,0 +1 @@
+export declare function track(event: string, fields?: Record<string, string | number | boolean>): void;

package/dist/telemetry.js

@@ -0,0 +1,51 @@
+/**
+ * Anonymous, opt-out diagnostic telemetry.
+ *
+ * Sends NO user code, API keys, prompts, responses, or personal information — only the SDK version,
+ * the runtime/OS family, an anonymous per-process id, and event/error *categories* — to the Retrace
+ * API's internal log ingest (forwarded to the centralized logging platform under
+ * service="sdk-typescript"). Fire-and-forget; never blocks, never throws.
+ *
+ * Disable entirely with RETRACE_TELEMETRY=0 (also accepts false/no/off).
+ */
+import os from "node:os";
+import { getConfig } from "./config.js";
+// Per-process random id — anonymous, not linked to any account, user, or machine identity.
+const ANON_ID = Math.random().toString(16).slice(2, 18);
+const DISABLED = new Set(["0", "false", "no", "off"]);
+// Keep in sync with package.json version.
+const SDK_VERSION = "0.14.0";
+function enabled() {
+    return !DISABLED.has((process.env.RETRACE_TELEMETRY ?? "1").trim().toLowerCase());
+}
+export function track(event, fields = {}) {
+    if (!enabled())
+        return;
+    try {
+        const base = (getConfig().baseUrl || "https://api.retraceai.tech").replace(/\/$/, "");
+        const body = JSON.stringify({
+            service: "sdk-typescript",
+            events: [
+                {
+                    level: "info",
+                    message: `sdk-typescript ${event}`,
+                    event,
+                    sdk_version: SDK_VERSION,
+                    node: process.version,
+                    os: os.platform(),
+                    anon_id: ANON_ID,
+                    ...fields,
+                },
+            ],
+        });
+        // Fire-and-forget; never block or throw.
+        void fetch(`${base}/api/v1/internal/logs`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+        }).catch(() => { });
+    }
+    catch {
+        /* telemetry must never affect the user's program */
+    }
+}

package/dist/trace.js

@@ -1,4 +1,5 @@
 import { genId, nowIso, utcNow } from "./utils.js";
+import { getConfig } from "./config.js";
 export var SpanType;
 (function (SpanType) {
     SpanType["LLM_CALL"] = "llm_call";
@@ -106,5 +107,13 @@ export class TraceBuilder {
     setProjectId(id) { this.data.project_id = id; }
     setSessionId(id) { this.data.session_id = id; }
     setMetadata(m) { this.data.metadata = m; }
-    toDict() { return this.data; }
+    toDict() {
+        // Tag the run's environment (e.g. "sandbox") from config as metadata.environment so the server
+        // routes it to the matching data-namespace. Explicit per-trace metadata.environment always wins.
+        const env = getConfig().environment;
+        if (env && !(this.data.metadata && "environment" in this.data.metadata)) {
+            this.data.metadata = { ...(this.data.metadata || {}), environment: env };
+        }
+        return this.data;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retrace-sdk",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "The execution replay engine for AI agents. Record, replay, fork, and share agent executions.",
   "type": "module",
   "main": "dist/index.js",