risicare 0.4.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +30 -0
  2. package/dist/frameworks/instructor.cjs +26 -19
  3. package/dist/frameworks/instructor.cjs.map +1 -1
  4. package/dist/frameworks/instructor.js +26 -19
  5. package/dist/frameworks/instructor.js.map +1 -1
  6. package/dist/frameworks/langchain.cjs +32 -25
  7. package/dist/frameworks/langchain.cjs.map +1 -1
  8. package/dist/frameworks/langchain.js +32 -25
  9. package/dist/frameworks/langchain.js.map +1 -1
  10. package/dist/frameworks/langgraph.cjs +32 -25
  11. package/dist/frameworks/langgraph.cjs.map +1 -1
  12. package/dist/frameworks/langgraph.js +32 -25
  13. package/dist/frameworks/langgraph.js.map +1 -1
  14. package/dist/frameworks/llamaindex.cjs +21 -14
  15. package/dist/frameworks/llamaindex.cjs.map +1 -1
  16. package/dist/frameworks/llamaindex.js +21 -14
  17. package/dist/frameworks/llamaindex.js.map +1 -1
  18. package/dist/index.cjs +675 -239
  19. package/dist/index.cjs.map +1 -1
  20. package/dist/index.d.cts +200 -46
  21. package/dist/index.d.ts +200 -46
  22. package/dist/index.js +670 -235
  23. package/dist/index.js.map +1 -1
  24. package/dist/providers/anthropic/index.cjs +32 -25
  25. package/dist/providers/anthropic/index.cjs.map +1 -1
  26. package/dist/providers/anthropic/index.js +32 -25
  27. package/dist/providers/anthropic/index.js.map +1 -1
  28. package/dist/providers/bedrock/index.cjs +32 -25
  29. package/dist/providers/bedrock/index.cjs.map +1 -1
  30. package/dist/providers/bedrock/index.js +32 -25
  31. package/dist/providers/bedrock/index.js.map +1 -1
  32. package/dist/providers/cerebras/index.cjs +32 -25
  33. package/dist/providers/cerebras/index.cjs.map +1 -1
  34. package/dist/providers/cerebras/index.js +32 -25
  35. package/dist/providers/cerebras/index.js.map +1 -1
  36. package/dist/providers/cohere/index.cjs +32 -25
  37. package/dist/providers/cohere/index.cjs.map +1 -1
  38. package/dist/providers/cohere/index.js +32 -25
  39. package/dist/providers/cohere/index.js.map +1 -1
  40. package/dist/providers/google/index.cjs +32 -25
  41. package/dist/providers/google/index.cjs.map +1 -1
  42. package/dist/providers/google/index.js +32 -25
  43. package/dist/providers/google/index.js.map +1 -1
  44. package/dist/providers/groq/index.cjs +32 -25
  45. package/dist/providers/groq/index.cjs.map +1 -1
  46. package/dist/providers/groq/index.js +32 -25
  47. package/dist/providers/groq/index.js.map +1 -1
  48. package/dist/providers/huggingface/index.cjs +32 -25
  49. package/dist/providers/huggingface/index.cjs.map +1 -1
  50. package/dist/providers/huggingface/index.js +32 -25
  51. package/dist/providers/huggingface/index.js.map +1 -1
  52. package/dist/providers/mistral/index.cjs +32 -25
  53. package/dist/providers/mistral/index.cjs.map +1 -1
  54. package/dist/providers/mistral/index.js +32 -25
  55. package/dist/providers/mistral/index.js.map +1 -1
  56. package/dist/providers/ollama/index.cjs +32 -25
  57. package/dist/providers/ollama/index.cjs.map +1 -1
  58. package/dist/providers/ollama/index.js +32 -25
  59. package/dist/providers/ollama/index.js.map +1 -1
  60. package/dist/providers/openai/index.cjs +32 -25
  61. package/dist/providers/openai/index.cjs.map +1 -1
  62. package/dist/providers/openai/index.js +32 -25
  63. package/dist/providers/openai/index.js.map +1 -1
  64. package/dist/providers/together/index.cjs +32 -25
  65. package/dist/providers/together/index.cjs.map +1 -1
  66. package/dist/providers/together/index.js +32 -25
  67. package/dist/providers/together/index.js.map +1 -1
  68. package/dist/providers/vercel-ai/index.cjs +26 -19
  69. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  70. package/dist/providers/vercel-ai/index.js +26 -19
  71. package/dist/providers/vercel-ai/index.js.map +1 -1
  72. package/package.json +1 -1
package/dist/index.d.cts CHANGED
@@ -3,49 +3,6 @@ export { instrumentLangGraph } from './frameworks/langgraph.cjs';
3
3
  export { patchInstructor } from './frameworks/instructor.cjs';
4
4
  export { RisicareLlamaIndexHandler } from './frameworks/llamaindex.cjs';
5
5
 
6
- /**
7
- * SDK configuration with environment variable loading.
8
- *
9
- * Environment variables match the Python SDK exactly:
10
- * RISICARE_API_KEY, RISICARE_ENDPOINT, RISICARE_PROJECT_ID, etc.
11
- */
12
- interface RisicareConfig {
13
- /** API key for authentication (format: "rsk-{random}"). Each key is scoped to one project. */
14
- apiKey?: string;
15
- /** Gateway endpoint URL */
16
- endpoint?: string;
17
- /**
18
- * @deprecated Project is determined by your API key. This field is ignored
19
- * by the gateway and will be removed in v1.0. Use `serviceName` and
20
- * `environment` for within-project organization.
21
- */
22
- projectId?: string;
23
- /** Environment name (production, staging, development). Used for within-project organization. */
24
- environment?: string;
25
- /** Service name for within-project organization. */
26
- serviceName?: string;
27
- /** Service version */
28
- serviceVersion?: string;
29
- /** Whether tracing is enabled (default: true if apiKey provided) */
30
- enabled?: boolean;
31
- /** Whether to capture prompt/completion content (default: true) */
32
- traceContent?: boolean;
33
- /** Sample rate 0.0–1.0 (default: 1.0 = trace all) */
34
- sampleRate?: number;
35
- /** Batch size threshold before flush (default: 100) */
36
- batchSize?: number;
37
- /** Batch timeout in ms before flush (default: 1000) */
38
- batchTimeoutMs?: number;
39
- /** Maximum queue size (default: 10000) */
40
- maxQueueSize?: number;
41
- /** Enable debug logging (default: false) */
42
- debug?: boolean;
43
- /** Enable gzip compression for HTTP exports (default: false) */
44
- compress?: boolean;
45
- /** Custom metadata attached to all spans */
46
- metadata?: Record<string, unknown>;
47
- }
48
-
49
6
  /**
50
7
  * Core type definitions for the Risicare SDK.
51
8
  *
@@ -241,6 +198,137 @@ declare class Span {
241
198
  toPayload(): SpanPayload;
242
199
  }
243
200
 
201
+ /**
202
+ * Customer-supplied masking of span content, applied before anything leaves the process.
203
+ *
204
+ * The full rationale — why this is the ONLY layer rather than defence in depth,
205
+ * why the hook carries the key, what is deliberately not masked, and the
206
+ * fail-closed-per-field ruling — is written once, in the Python twin:
207
+ * `packages/risicare-sdk/src/risicare/masking.py`. This file mirrors it. Where
208
+ * the two languages diverge, the divergence is called out inline below; do not
209
+ * "align" them without reading both.
210
+ *
211
+ * ── Mirrored from Python ─────────────────────────────────────────────────────
212
+ * • signature `mask(key, value) => value` — the key is REQUIRED, because our
213
+ * span model has no input/output fields: the prompt and the model name are
214
+ * both plain entries of `span.attributes`, so a keyless hook cannot tell
215
+ * them apart and `() => '***'` would erase every dashboard label.
216
+ * • masked: every attribute value, `statusMessage`, every event-attribute
217
+ * value, every link-attribute value — plus `score.comment`, the one key
218
+ * that is NOT a span field (see {@link SCORE_COMMENT_KEY}).
219
+ * • NOT masked: traceId / spanId / parentSpanId, `span.name`, `event.name`,
220
+ * and the typed identity + llm columns (agentId, agentName, agentType,
221
+ * sessionId, toolName, llmModel, …). Masking an identifier breaks the
222
+ * customer's own joins — the F-39C lesson. The OTel-style attribute forms
223
+ * (`agent.name`, `session.user_id`) live in `attributes` and ARE masked.
224
+ * • no type narrowing: the hook sees numbers and booleans too. A card number
225
+ * is representable as a number, and deciding otherwise on the customer's
226
+ * behalf is the quiet narrowing this codebase keeps paying for.
227
+ * • fail closed per FIELD: a throwing hook yields `MASK_ERROR_MARKER` for
228
+ * that field and the span is exported intact. Never drop the span — the
229
+ * SDK is the last place the data exists, so a drop here is permanent loss,
230
+ * and it additionally orphans the span's children for zero extra safety.
231
+ * • idempotent: `_exportBatch` can re-queue a refused batch, and a user
232
+ * callback cannot be assumed idempotent, so a masked span is flagged.
233
+ *
234
+ * ── Where JS DIFFERS from Python, and it matters ─────────────────────────────
235
+ * 1. There is no `exceptions[]` on the JS Span — `toPayload()` emits none — so
236
+ * there are no `exceptions.{i}.*` keys here. A port that adds exceptions to
237
+ * the JS span must add them here in the same change.
238
+ * 2. ⚠ THE HOT-PATH COST IS STRICTLY WORSE THAN PYTHON'S. Python runs the mask
239
+ * on a background worker THREAD, so a slow mask costs only drain rate. Node
240
+ * has one thread: `_exportBatch` is `async`, but the mask itself is sync, so
241
+ * while it runs NOTHING else in the customer's process runs — not their
242
+ * request handlers, not their timers. In Python a slow mask degrades
243
+ * throughput; in JS it degrades the whole application. The budget warning
244
+ * below is not advisory decoration here.
245
+ * 3. `_masked` is a real private field on `Span` (we own that class), rather
246
+ * than Python's `setattr` — which Python needs only because its `Span`
247
+ * lives in the separate `risicare-core` package.
248
+ */
249
+
250
+ /**
251
+ * A customer mask callback.
252
+ *
253
+ * @param key Fully-qualified path of the value: an attribute key as-is
254
+ * (`"gen_ai.prompt.0.content"`), or a dotted path
255
+ * (`"statusMessage"`, `"events.0.attributes.foo"`,
256
+ * `"links.0.attributes.bar"`).
257
+ * @param value The current value — any type, not just string.
258
+ * @returns The replacement, or `value` unchanged.
259
+ */
260
+ type MaskFn = (key: string, value: unknown) => unknown;
261
+ /**
262
+ * Substituted for a value whose mask threw. Fixed, deliberately not
263
+ * valid-looking, and greppable in a dashboard.
264
+ */
265
+ declare const MASK_ERROR_MARKER = "<risicare:mask-error>";
266
+
267
+ /**
268
+ * SDK configuration with environment variable loading.
269
+ *
270
+ * Environment variables match the Python SDK exactly:
271
+ * RISICARE_API_KEY, RISICARE_ENDPOINT, RISICARE_PROJECT_ID, etc.
272
+ */
273
+
274
+ interface RisicareConfig {
275
+ /** API key for authentication (format: "rsk-{random}"). Each key is scoped to one project. */
276
+ apiKey?: string;
277
+ /** Gateway endpoint URL */
278
+ endpoint?: string;
279
+ /**
280
+ * @deprecated Project is determined by your API key. This field is ignored
281
+ * by the gateway and will be removed in v1.0. Use `serviceName` and
282
+ * `environment` for within-project organization.
283
+ */
284
+ projectId?: string;
285
+ /** Environment name (production, staging, development). Used for within-project organization. */
286
+ environment?: string;
287
+ /** Service name for within-project organization. */
288
+ serviceName?: string;
289
+ /** Service version */
290
+ serviceVersion?: string;
291
+ /** Whether tracing is enabled (default: true if apiKey provided) */
292
+ enabled?: boolean;
293
+ /** Whether to capture prompt/completion content (default: true) */
294
+ traceContent?: boolean;
295
+ /** Sample rate 0.0–1.0 (default: 1.0 = trace all) */
296
+ sampleRate?: number;
297
+ /** Batch size threshold before flush (default: 100) */
298
+ batchSize?: number;
299
+ /** Batch timeout in ms before flush (default: 1000) */
300
+ batchTimeoutMs?: number;
301
+ /** Maximum queue size (default: 10000) */
302
+ maxQueueSize?: number;
303
+ /** Enable debug logging (default: false) */
304
+ debug?: boolean;
305
+ /** Enable gzip compression for HTTP exports (default: false) */
306
+ compress?: boolean;
307
+ /** Custom metadata attached to all spans */
308
+ metadata?: Record<string, unknown>;
309
+ /**
310
+ * Masking callback applied to every content-bearing field of every span
311
+ * BEFORE the batch leaves the process — `mask(key, value) => value`.
312
+ *
313
+ * This is the only layer at which you can keep data off Risicare's wire, so
314
+ * it applies to every exporter, including custom ones. `key` is the attribute
315
+ * key (`"gen_ai.prompt.0.content"`) or a dotted path (`"statusMessage"`,
316
+ * `"events.0.attributes.x"`). Identifiers and span/event names are NOT passed
317
+ * to it — masking those breaks trace structure and your own joins.
318
+ *
319
+ * ⚠ Must be CPU-only and fast: Node is single-threaded, so this runs on your
320
+ * event loop. No I/O, no network, no unbounded retries, no per-request state.
321
+ * If it throws, that one field becomes `"<risicare:mask-error>"` and the span
322
+ * is still exported. See `masking.ts`.
323
+ *
324
+ * ⚠ Has NO environment-variable form, deliberately: the shapes that would
325
+ * make a callable env-resolvable are arbitrary code execution driven by the
326
+ * process environment. Masking is configured in code, by the application that
327
+ * owns the data.
328
+ */
329
+ mask?: MaskFn;
330
+ }
331
+
244
332
  /**
245
333
  * Tracer — creates spans with automatic context nesting.
246
334
  *
@@ -336,8 +424,16 @@ declare function init(config?: Partial<RisicareConfig>): void;
336
424
  declare function shutdown(): Promise<void>;
337
425
  /**
338
426
  * Flush all pending spans without shutting down.
427
+ *
428
+ * @returns `true` only if everything queued at entry was DELIVERED — `false`
429
+ * if the deadline expired with spans still queued, or if any span was
430
+ * discarded during the window (F-SDKCB-001 §6). An uninitialised SDK returns
431
+ * `true`: it was handed nothing, and it lost nothing.
432
+ *
433
+ * ⚠ Signature change in 0.5.0 — was `Promise<void>`. Existing callers that
434
+ * ignore the result keep working unchanged.
339
435
  */
340
- declare function flush(): Promise<void>;
436
+ declare function flush(): Promise<boolean>;
341
437
  /**
342
438
  * Enable tracing at runtime.
343
439
  */
@@ -360,15 +456,69 @@ declare function getTracer(): Tracer | undefined;
360
456
  declare function getTraceContent(): boolean;
361
457
  /**
362
458
  * Get SDK metrics: exported spans, dropped spans, failed exports, queue stats.
363
- * Returns zero-valued metrics if SDK is not initialized.
459
+ *
460
+ * `sdkState` — SDK-RELEASE-RULING.md §5 — says WHICH of three different facts
461
+ * the numbers are, because before it all three rendered as the same zeros:
462
+ *
463
+ * - `"uninitialised"` nothing was ever queued; the zeros are the truth
464
+ * - `"running"` live readings from a live processor
465
+ * - `"shutdown"` the RETAINED FINAL TALLY. Not live, and says so.
466
+ *
467
+ * The `"shutdown"` case is why this field exists. `shutdown()` clears the global
468
+ * client, so this used to answer `droppedSpans: 0` from a hardcoded literal in
469
+ * the very process that had just discarded spans — a guess presented
470
+ * byte-identical to an authoritative answer, which is the W1/W3 class this
471
+ * codebase already ruled against (`cost_source`, `settled`). The remedy there
472
+ * and here is the same: do not hide the value and do not null it, LABEL it.
473
+ * Every field of a retained tally is still true — the queue really is empty,
474
+ * the capacity really is the configured one, and the drop counts describe the
475
+ * whole life of the process, `shutdown_residue` included.
476
+ *
477
+ * ⚠ What it still CANNOT do: report loss to anything OUTSIDE the dying process.
478
+ * A counter in memory about to be freed has no reader, and a SIGKILL takes this
479
+ * and the WARNING together. The WARNING remains the primary signal.
364
480
  */
365
481
  declare function getMetrics(): {
482
+ sdkState: "running";
366
483
  exportedSpans: number;
367
484
  droppedSpans: number;
485
+ droppedSpansByReason: {
486
+ queue_full: number;
487
+ transport_refused: number;
488
+ shutdown_residue: number;
489
+ };
368
490
  failedExports: number;
491
+ maskErrors: number;
369
492
  queueSize: number;
370
493
  queueCapacity: number;
371
494
  queueUtilization: number;
495
+ } | {
496
+ droppedSpansByReason: {
497
+ queue_full: number;
498
+ transport_refused: number;
499
+ shutdown_residue: number;
500
+ };
501
+ sdkState: "shutdown";
502
+ exportedSpans: number;
503
+ droppedSpans: number;
504
+ failedExports: number;
505
+ maskErrors: number;
506
+ queueSize: number;
507
+ queueCapacity: number;
508
+ queueUtilization: number;
509
+ } | {
510
+ exportedSpans: number;
511
+ droppedSpans: number;
512
+ droppedSpansByReason: {
513
+ queue_full: number;
514
+ transport_refused: number;
515
+ shutdown_residue: number;
516
+ };
517
+ failedExports: number;
518
+ queueSize: number;
519
+ queueCapacity: number;
520
+ queueUtilization: number;
521
+ sdkState: "uninitialised";
372
522
  };
373
523
  /**
374
524
  * Report a caught exception to the error diagnosis pipeline.
@@ -390,6 +540,10 @@ declare function reportError(error: unknown, options?: {
390
540
  * Sends the score to the server in a fire-and-forget fashion.
391
541
  * This function never throws and is non-blocking.
392
542
  *
543
+ * If a `mask` is configured on `init()`, `options.comment` is passed to it under
544
+ * the key `score.comment` before the request is built. `traceId`, `spanId` and
545
+ * `name` are NOT masked — they are identifiers the platform joins and groups on.
546
+ *
393
547
  * @param traceId - The trace to score
394
548
  * @param name - Score name (e.g., "accuracy", "user_satisfaction")
395
549
  * @param value - Score value between 0.0 and 1.0 inclusive
@@ -1353,4 +1507,4 @@ type WebhookPayload = Uint8Array | ArrayBuffer | string;
1353
1507
  */
1354
1508
  declare function verifyWebhookSignature(payload: WebhookPayload, headers: HeaderLookup, secret: string, opts?: VerifyWebhookOptions): void;
1355
1509
 
1356
- export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, GuardRejectedError, type HeaderLookup, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, Tracer, type VerifyWebhookOptions, type WebhookPayload, WebhookVerificationError, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getFixRuntime, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, initFixRuntime, injectTraceContext, isEnabled, isProviderInstrumentationSuppressed, registerSpan, reportError, score, session, shutdown, shutdownFixRuntime, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, verifyWebhookSignature, withAgent, withPhase, withSession };
1510
+ export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, GuardRejectedError, type HeaderLookup, MASK_ERROR_MARKER, type MaskFn, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, Tracer, type VerifyWebhookOptions, type WebhookPayload, WebhookVerificationError, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getFixRuntime, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, initFixRuntime, injectTraceContext, isEnabled, isProviderInstrumentationSuppressed, registerSpan, reportError, score, session, shutdown, shutdownFixRuntime, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, verifyWebhookSignature, withAgent, withPhase, withSession };
package/dist/index.d.ts CHANGED
@@ -3,49 +3,6 @@ export { instrumentLangGraph } from './frameworks/langgraph.js';
3
3
  export { patchInstructor } from './frameworks/instructor.js';
4
4
  export { RisicareLlamaIndexHandler } from './frameworks/llamaindex.js';
5
5
 
6
- /**
7
- * SDK configuration with environment variable loading.
8
- *
9
- * Environment variables match the Python SDK exactly:
10
- * RISICARE_API_KEY, RISICARE_ENDPOINT, RISICARE_PROJECT_ID, etc.
11
- */
12
- interface RisicareConfig {
13
- /** API key for authentication (format: "rsk-{random}"). Each key is scoped to one project. */
14
- apiKey?: string;
15
- /** Gateway endpoint URL */
16
- endpoint?: string;
17
- /**
18
- * @deprecated Project is determined by your API key. This field is ignored
19
- * by the gateway and will be removed in v1.0. Use `serviceName` and
20
- * `environment` for within-project organization.
21
- */
22
- projectId?: string;
23
- /** Environment name (production, staging, development). Used for within-project organization. */
24
- environment?: string;
25
- /** Service name for within-project organization. */
26
- serviceName?: string;
27
- /** Service version */
28
- serviceVersion?: string;
29
- /** Whether tracing is enabled (default: true if apiKey provided) */
30
- enabled?: boolean;
31
- /** Whether to capture prompt/completion content (default: true) */
32
- traceContent?: boolean;
33
- /** Sample rate 0.0–1.0 (default: 1.0 = trace all) */
34
- sampleRate?: number;
35
- /** Batch size threshold before flush (default: 100) */
36
- batchSize?: number;
37
- /** Batch timeout in ms before flush (default: 1000) */
38
- batchTimeoutMs?: number;
39
- /** Maximum queue size (default: 10000) */
40
- maxQueueSize?: number;
41
- /** Enable debug logging (default: false) */
42
- debug?: boolean;
43
- /** Enable gzip compression for HTTP exports (default: false) */
44
- compress?: boolean;
45
- /** Custom metadata attached to all spans */
46
- metadata?: Record<string, unknown>;
47
- }
48
-
49
6
  /**
50
7
  * Core type definitions for the Risicare SDK.
51
8
  *
@@ -241,6 +198,137 @@ declare class Span {
241
198
  toPayload(): SpanPayload;
242
199
  }
243
200
 
201
+ /**
202
+ * Customer-supplied masking of span content, applied before anything leaves the process.
203
+ *
204
+ * The full rationale — why this is the ONLY layer rather than defence in depth,
205
+ * why the hook carries the key, what is deliberately not masked, and the
206
+ * fail-closed-per-field ruling — is written once, in the Python twin:
207
+ * `packages/risicare-sdk/src/risicare/masking.py`. This file mirrors it. Where
208
+ * the two languages diverge, the divergence is called out inline below; do not
209
+ * "align" them without reading both.
210
+ *
211
+ * ── Mirrored from Python ─────────────────────────────────────────────────────
212
+ * • signature `mask(key, value) => value` — the key is REQUIRED, because our
213
+ * span model has no input/output fields: the prompt and the model name are
214
+ * both plain entries of `span.attributes`, so a keyless hook cannot tell
215
+ * them apart and `() => '***'` would erase every dashboard label.
216
+ * • masked: every attribute value, `statusMessage`, every event-attribute
217
+ * value, every link-attribute value — plus `score.comment`, the one key
218
+ * that is NOT a span field (see {@link SCORE_COMMENT_KEY}).
219
+ * • NOT masked: traceId / spanId / parentSpanId, `span.name`, `event.name`,
220
+ * and the typed identity + llm columns (agentId, agentName, agentType,
221
+ * sessionId, toolName, llmModel, …). Masking an identifier breaks the
222
+ * customer's own joins — the F-39C lesson. The OTel-style attribute forms
223
+ * (`agent.name`, `session.user_id`) live in `attributes` and ARE masked.
224
+ * • no type narrowing: the hook sees numbers and booleans too. A card number
225
+ * is representable as a number, and deciding otherwise on the customer's
226
+ * behalf is the quiet narrowing this codebase keeps paying for.
227
+ * • fail closed per FIELD: a throwing hook yields `MASK_ERROR_MARKER` for
228
+ * that field and the span is exported intact. Never drop the span — the
229
+ * SDK is the last place the data exists, so a drop here is permanent loss,
230
+ * and it additionally orphans the span's children for zero extra safety.
231
+ * • idempotent: `_exportBatch` can re-queue a refused batch, and a user
232
+ * callback cannot be assumed idempotent, so a masked span is flagged.
233
+ *
234
+ * ── Where JS DIFFERS from Python, and it matters ─────────────────────────────
235
+ * 1. There is no `exceptions[]` on the JS Span — `toPayload()` emits none — so
236
+ * there are no `exceptions.{i}.*` keys here. A port that adds exceptions to
237
+ * the JS span must add them here in the same change.
238
+ * 2. ⚠ THE HOT-PATH COST IS STRICTLY WORSE THAN PYTHON'S. Python runs the mask
239
+ * on a background worker THREAD, so a slow mask costs only drain rate. Node
240
+ * has one thread: `_exportBatch` is `async`, but the mask itself is sync, so
241
+ * while it runs NOTHING else in the customer's process runs — not their
242
+ * request handlers, not their timers. In Python a slow mask degrades
243
+ * throughput; in JS it degrades the whole application. The budget warning
244
+ * below is not advisory decoration here.
245
+ * 3. `_masked` is a real private field on `Span` (we own that class), rather
246
+ * than Python's `setattr` — which Python needs only because its `Span`
247
+ * lives in the separate `risicare-core` package.
248
+ */
249
+
250
+ /**
251
+ * A customer mask callback.
252
+ *
253
+ * @param key Fully-qualified path of the value: an attribute key as-is
254
+ * (`"gen_ai.prompt.0.content"`), or a dotted path
255
+ * (`"statusMessage"`, `"events.0.attributes.foo"`,
256
+ * `"links.0.attributes.bar"`).
257
+ * @param value The current value — any type, not just string.
258
+ * @returns The replacement, or `value` unchanged.
259
+ */
260
+ type MaskFn = (key: string, value: unknown) => unknown;
261
+ /**
262
+ * Substituted for a value whose mask threw. Fixed, deliberately not
263
+ * valid-looking, and greppable in a dashboard.
264
+ */
265
+ declare const MASK_ERROR_MARKER = "<risicare:mask-error>";
266
+
267
+ /**
268
+ * SDK configuration with environment variable loading.
269
+ *
270
+ * Environment variables match the Python SDK exactly:
271
+ * RISICARE_API_KEY, RISICARE_ENDPOINT, RISICARE_PROJECT_ID, etc.
272
+ */
273
+
274
+ interface RisicareConfig {
275
+ /** API key for authentication (format: "rsk-{random}"). Each key is scoped to one project. */
276
+ apiKey?: string;
277
+ /** Gateway endpoint URL */
278
+ endpoint?: string;
279
+ /**
280
+ * @deprecated Project is determined by your API key. This field is ignored
281
+ * by the gateway and will be removed in v1.0. Use `serviceName` and
282
+ * `environment` for within-project organization.
283
+ */
284
+ projectId?: string;
285
+ /** Environment name (production, staging, development). Used for within-project organization. */
286
+ environment?: string;
287
+ /** Service name for within-project organization. */
288
+ serviceName?: string;
289
+ /** Service version */
290
+ serviceVersion?: string;
291
+ /** Whether tracing is enabled (default: true if apiKey provided) */
292
+ enabled?: boolean;
293
+ /** Whether to capture prompt/completion content (default: true) */
294
+ traceContent?: boolean;
295
+ /** Sample rate 0.0–1.0 (default: 1.0 = trace all) */
296
+ sampleRate?: number;
297
+ /** Batch size threshold before flush (default: 100) */
298
+ batchSize?: number;
299
+ /** Batch timeout in ms before flush (default: 1000) */
300
+ batchTimeoutMs?: number;
301
+ /** Maximum queue size (default: 10000) */
302
+ maxQueueSize?: number;
303
+ /** Enable debug logging (default: false) */
304
+ debug?: boolean;
305
+ /** Enable gzip compression for HTTP exports (default: false) */
306
+ compress?: boolean;
307
+ /** Custom metadata attached to all spans */
308
+ metadata?: Record<string, unknown>;
309
+ /**
310
+ * Masking callback applied to every content-bearing field of every span
311
+ * BEFORE the batch leaves the process — `mask(key, value) => value`.
312
+ *
313
+ * This is the only layer at which you can keep data off Risicare's wire, so
314
+ * it applies to every exporter, including custom ones. `key` is the attribute
315
+ * key (`"gen_ai.prompt.0.content"`) or a dotted path (`"statusMessage"`,
316
+ * `"events.0.attributes.x"`). Identifiers and span/event names are NOT passed
317
+ * to it — masking those breaks trace structure and your own joins.
318
+ *
319
+ * ⚠ Must be CPU-only and fast: Node is single-threaded, so this runs on your
320
+ * event loop. No I/O, no network, no unbounded retries, no per-request state.
321
+ * If it throws, that one field becomes `"<risicare:mask-error>"` and the span
322
+ * is still exported. See `masking.ts`.
323
+ *
324
+ * ⚠ Has NO environment-variable form, deliberately: the shapes that would
325
+ * make a callable env-resolvable are arbitrary code execution driven by the
326
+ * process environment. Masking is configured in code, by the application that
327
+ * owns the data.
328
+ */
329
+ mask?: MaskFn;
330
+ }
331
+
244
332
  /**
245
333
  * Tracer — creates spans with automatic context nesting.
246
334
  *
@@ -336,8 +424,16 @@ declare function init(config?: Partial<RisicareConfig>): void;
336
424
  declare function shutdown(): Promise<void>;
337
425
  /**
338
426
  * Flush all pending spans without shutting down.
427
+ *
428
+ * @returns `true` only if everything queued at entry was DELIVERED — `false`
429
+ * if the deadline expired with spans still queued, or if any span was
430
+ * discarded during the window (F-SDKCB-001 §6). An uninitialised SDK returns
431
+ * `true`: it was handed nothing, and it lost nothing.
432
+ *
433
+ * ⚠ Signature change in 0.5.0 — was `Promise<void>`. Existing callers that
434
+ * ignore the result keep working unchanged.
339
435
  */
340
- declare function flush(): Promise<void>;
436
+ declare function flush(): Promise<boolean>;
341
437
  /**
342
438
  * Enable tracing at runtime.
343
439
  */
@@ -360,15 +456,69 @@ declare function getTracer(): Tracer | undefined;
360
456
  declare function getTraceContent(): boolean;
361
457
  /**
362
458
  * Get SDK metrics: exported spans, dropped spans, failed exports, queue stats.
363
- * Returns zero-valued metrics if SDK is not initialized.
459
+ *
460
+ * `sdkState` — SDK-RELEASE-RULING.md §5 — says WHICH of three different facts
461
+ * the numbers are, because before it all three rendered as the same zeros:
462
+ *
463
+ * - `"uninitialised"` nothing was ever queued; the zeros are the truth
464
+ * - `"running"` live readings from a live processor
465
+ * - `"shutdown"` the RETAINED FINAL TALLY. Not live, and says so.
466
+ *
467
+ * The `"shutdown"` case is why this field exists. `shutdown()` clears the global
468
+ * client, so this used to answer `droppedSpans: 0` from a hardcoded literal in
469
+ * the very process that had just discarded spans — a guess presented
470
+ * byte-identical to an authoritative answer, which is the W1/W3 class this
471
+ * codebase already ruled against (`cost_source`, `settled`). The remedy there
472
+ * and here is the same: do not hide the value and do not null it, LABEL it.
473
+ * Every field of a retained tally is still true — the queue really is empty,
474
+ * the capacity really is the configured one, and the drop counts describe the
475
+ * whole life of the process, `shutdown_residue` included.
476
+ *
477
+ * ⚠ What it still CANNOT do: report loss to anything OUTSIDE the dying process.
478
+ * A counter in memory about to be freed has no reader, and a SIGKILL takes this
479
+ * and the WARNING together. The WARNING remains the primary signal.
364
480
  */
365
481
  declare function getMetrics(): {
482
+ sdkState: "running";
366
483
  exportedSpans: number;
367
484
  droppedSpans: number;
485
+ droppedSpansByReason: {
486
+ queue_full: number;
487
+ transport_refused: number;
488
+ shutdown_residue: number;
489
+ };
368
490
  failedExports: number;
491
+ maskErrors: number;
369
492
  queueSize: number;
370
493
  queueCapacity: number;
371
494
  queueUtilization: number;
495
+ } | {
496
+ droppedSpansByReason: {
497
+ queue_full: number;
498
+ transport_refused: number;
499
+ shutdown_residue: number;
500
+ };
501
+ sdkState: "shutdown";
502
+ exportedSpans: number;
503
+ droppedSpans: number;
504
+ failedExports: number;
505
+ maskErrors: number;
506
+ queueSize: number;
507
+ queueCapacity: number;
508
+ queueUtilization: number;
509
+ } | {
510
+ exportedSpans: number;
511
+ droppedSpans: number;
512
+ droppedSpansByReason: {
513
+ queue_full: number;
514
+ transport_refused: number;
515
+ shutdown_residue: number;
516
+ };
517
+ failedExports: number;
518
+ queueSize: number;
519
+ queueCapacity: number;
520
+ queueUtilization: number;
521
+ sdkState: "uninitialised";
372
522
  };
373
523
  /**
374
524
  * Report a caught exception to the error diagnosis pipeline.
@@ -390,6 +540,10 @@ declare function reportError(error: unknown, options?: {
390
540
  * Sends the score to the server in a fire-and-forget fashion.
391
541
  * This function never throws and is non-blocking.
392
542
  *
543
+ * If a `mask` is configured on `init()`, `options.comment` is passed to it under
544
+ * the key `score.comment` before the request is built. `traceId`, `spanId` and
545
+ * `name` are NOT masked — they are identifiers the platform joins and groups on.
546
+ *
393
547
  * @param traceId - The trace to score
394
548
  * @param name - Score name (e.g., "accuracy", "user_satisfaction")
395
549
  * @param value - Score value between 0.0 and 1.0 inclusive
@@ -1353,4 +1507,4 @@ type WebhookPayload = Uint8Array | ArrayBuffer | string;
1353
1507
  */
1354
1508
  declare function verifyWebhookSignature(payload: WebhookPayload, headers: HeaderLookup, secret: string, opts?: VerifyWebhookOptions): void;
1355
1509
 
1356
- export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, GuardRejectedError, type HeaderLookup, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, Tracer, type VerifyWebhookOptions, type WebhookPayload, WebhookVerificationError, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getFixRuntime, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, initFixRuntime, injectTraceContext, isEnabled, isProviderInstrumentationSuppressed, registerSpan, reportError, score, session, shutdown, shutdownFixRuntime, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, verifyWebhookSignature, withAgent, withPhase, withSession };
1510
+ export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, GuardRejectedError, type HeaderLookup, MASK_ERROR_MARKER, type MaskFn, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, Tracer, type VerifyWebhookOptions, type WebhookPayload, WebhookVerificationError, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getFixRuntime, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, initFixRuntime, injectTraceContext, isEnabled, isProviderInstrumentationSuppressed, registerSpan, reportError, score, session, shutdown, shutdownFixRuntime, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, verifyWebhookSignature, withAgent, withPhase, withSession };