risicare 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -371,7 +371,7 @@ declare function getMetrics(): {
     queueUtilization: number;
 };
 /**
- * Report a caught exception to the self-healing pipeline.
+ * Report a caught exception to the error diagnosis pipeline.
  *
  * Creates an error span that triggers diagnosis and fix generation.
  * Deduplicates identical errors within a 5-minute window (SHA256 fingerprint).
@@ -430,6 +430,17 @@ declare function withAgent<T>(options: AgentOptions, fn: () => T): T;
  * Wraps a function to execute within an agent context. All spans created
  * inside will be tagged with the agent's identity.
  *
+ * Two equivalent calling forms are supported:
+ *
+ *   // 2-arg form
+ *   const research = agent({ name: 'researcher' }, async (q) => { ... });
+ *
+ *   // Curried form (decorator factory)
+ *   const research = agent({ name: 'researcher' })(async (q) => { ... });
+ *
+ * Both return a wrapped function — call it to actually run the body inside
+ * the agent context.
+ *
  * @example
  * const research = agent({ name: 'researcher', role: 'worker' }, async (query: string) => {
  *   const result = await openai.chat.completions.create({ ... });
@@ -439,10 +450,8 @@ declare function withAgent<T>(options: AgentOptions, fn: () => T): T;
  * const answer = await research('What is quantum computing?');
  */
 
-/**
- * Wrap a function with agent context and an automatic span.
- */
 declare function agent<TArgs extends unknown[], TReturn>(options: AgentOptions, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function agent(options: AgentOptions): <TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
 
 /**
  * Session context — groups multiple traces from the same user interaction.
@@ -483,10 +492,19 @@ declare function withSession<T>(options: SessionOptions, fn: () => T): T;
 /**
  * Wrap a function with session context.
  *
+ * Two equivalent calling forms are supported (F-54 ergonomics):
+ *
+ *   // 2-arg form
+ *   const handle = session({ sessionId: 's1' }, async (req) => { ... });
+ *
+ *   // Curried form (decorator factory)
+ *   const handle = session({ sessionId: 's1' })(async (req) => { ... });
+ *
  * @param optionsOrResolver - Static session options, or a function that derives them from args
- * @param fn - The function to wrap
+ * @param fn - The function to wrap. If omitted, returns a decorator factory.
  */
 declare function session<TArgs extends unknown[], TReturn>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions), fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function session<TArgs extends unknown[]>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions)): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
 
 /**
  * Phase decorators — decision phase tracking (Tier 4).
@@ -1163,4 +1181,142 @@ declare function initFixRuntime(config: FixRuntimeConfig): FixRuntime;
  */
 declare function shutdownFixRuntime(): void;
 
-export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, type FixRuntimeConfig, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, Tracer, 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, withAgent, withPhase, withSession };
+/**
+ * Webhook signature verification helpers (CON-195 / B-7, F-34).
+ *
+ * Customers receive Risicare webhooks at endpoints they configure. Each
+ * delivery is signed by the sender (`packages/workers/src/workers/
+ * webhook_dispatch.py`) with HMAC-SHA256 over `<timestamp>.<payload_bytes>`
+ * using the per-webhook shared secret. The signature is delivered in the
+ * `X-Risicare-Signature` header in Stripe-style format `t=<unix>,v1=<hex>`,
+ * and the timestamp is also exposed verbatim as `X-Risicare-Timestamp`.
+ *
+ * This module is the TypeScript port of `risicare-sdk/src/risicare/
+ * webhooks.py`. It enforces THREE checks (all must pass):
+ *
+ *   1. Header parsing — both headers must be present and well-formed.
+ *   2. Time skew — `Math.abs(now - timestamp) <= toleranceS` (default
+ *      5 minutes). This is what makes captured signed payloads
+ *      non-replayable past the tolerance window.
+ *   3. HMAC equality — constant-time compare against a fresh signature
+ *      computed from the secret + the SAME timestamp + the raw body.
+ *
+ * Example (Express/Node receiver):
+ *
+ *     import express from 'express';
+ *     import { verifyWebhookSignature, WebhookVerificationError } from 'risicare';
+ *
+ *     const app = express();
+ *     // IMPORTANT: use raw body, not parsed JSON — the signature is
+ *     // over the EXACT bytes received; JSON re-serialization changes
+ *     // key ordering / whitespace and the signature will not match.
+ *     app.post('/risicare-webhook', express.raw({ type: '*\/*' }), (req, res) => {
+ *       try {
+ *         verifyWebhookSignature(req.body, req.headers, YOUR_WEBHOOK_SECRET);
+ *       } catch (e) {
+ *         if (e instanceof WebhookVerificationError) {
+ *           return res.status(401).send(e.message);
+ *         }
+ *         throw e;
+ *       }
+ *       // ... process the verified event ...
+ *       res.status(200).end();
+ *     });
+ *
+ * The helper is dependency-light (Node `crypto` stdlib only) so customers
+ * can use it without pulling in the rest of the SDK if they only need
+ * verification.
+ *
+ * Edge runtime note: this verifier is synchronous and uses Node's
+ * `crypto.timingSafeEqual` + `crypto.createHmac`. It will not run in
+ * Cloudflare Workers / Vercel Edge / Deno Deploy as-is. An async Web
+ * Crypto variant can be added if customers request it.
+ */
+/**
+ * Default skew window (seconds). 5 minutes matches Stripe / GitHub /
+ * common industry practice. Customers can override per-call if their
+ * clock infrastructure warrants a tighter or looser bound.
+ *
+ * Mirrors `DEFAULT_TIMESTAMP_TOLERANCE_S` in the Python SDK.
+ */
+declare const DEFAULT_TIMESTAMP_TOLERANCE_S = 300;
+/**
+ * Raised when a webhook delivery fails any verification check.
+ *
+ * Customers should catch this specifically rather than a generic `Error`
+ * so verification failures are not conflated with other input problems
+ * (e.g. body-parsing errors at the framework layer).
+ *
+ * The `message` is safe to log — it never includes the secret, the
+ * expected signature, or the computed signature.
+ */
+declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Options for `verifyWebhookSignature`. All fields are optional.
+ */
+interface VerifyWebhookOptions {
+    /**
+     * Maximum clock-skew tolerance in seconds. Defaults to
+     * `DEFAULT_TIMESTAMP_TOLERANCE_S` (300). Setting to 0 is supported
+     * (strict same-second match) but discouraged in distributed
+     * deployments.
+     */
+    toleranceS?: number;
+    /**
+     * Test hook — override "current time" in unix seconds.
+     * Customers should not pass this.
+     */
+    _now?: number;
+}
+/**
+ * Header-like inputs accepted by `verifyWebhookSignature`.
+ *
+ * Covers (a) Web API `Headers` (case-insensitive `.get`), (b) Node
+ * `IncomingHttpHeaders` (plain object with lowercase keys, possibly
+ * array-valued for multi-set headers), (c) `Map<string, string>`
+ * (case-sensitive `.get`), and (d) plain `Record` (case-sensitive
+ * property lookup, possibly array-valued).
+ *
+ * Lookup strategy: try the canonical mixed-case name first
+ * (`X-Risicare-Signature`). If that returns undefined, fall back to the
+ * lowercased form (`x-risicare-signature`). Mirrors the Python
+ * `_get_header` helper.
+ */
+type HeaderLookup = Headers | Map<string, string> | Record<string, string | string[] | undefined>;
+/**
+ * Payload shapes accepted by `verifyWebhookSignature`.
+ *
+ * `Buffer extends Uint8Array` in Node, so callers passing `Buffer`
+ * satisfy the `Uint8Array` arm. `ArrayBuffer` is explicitly accepted
+ * for callers using Web-API request bodies. `string` is UTF-8 encoded
+ * internally.
+ *
+ * Crucially, callers must pass the EXACT bytes received over the
+ * wire. Parsing JSON and re-serializing changes byte order and
+ * whitespace; the signature will not match.
+ */
+type WebhookPayload = Uint8Array | ArrayBuffer | string;
+/**
+ * Verify a Risicare webhook delivery. Throws `WebhookVerificationError`
+ * on any failure; returns `undefined` on success.
+ *
+ * @param payload Raw request body bytes — the EXACT bytes received over
+ *   the wire. Re-serializing parsed JSON will change byte ordering and
+ *   break the signature.
+ * @param headers Header lookup. Web `Headers`, `Map<string,string>`,
+ *   Node `IncomingHttpHeaders`, or plain `Record` all work. Lookup is
+ *   case-insensitive (canonical mixed-case tried first, then lowercase).
+ * @param secret The shared secret configured on the Risicare webhook
+ *   record. Returned by `POST /v1/webhooks` once at create time.
+ * @param opts Optional overrides — `toleranceS` (default 300) and
+ *   `_now` (test hook).
+ *
+ * @throws WebhookVerificationError on any of: missing headers, malformed
+ *   signature, timestamp outside tolerance, HMAC mismatch, or invalid
+ *   payload type.
+ */
+declare function verifyWebhookSignature(payload: WebhookPayload, headers: HeaderLookup, secret: string, opts?: VerifyWebhookOptions): void;
+
+export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, 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 };

package/dist/index.d.ts

@@ -371,7 +371,7 @@ declare function getMetrics(): {
     queueUtilization: number;
 };
 /**
- * Report a caught exception to the self-healing pipeline.
+ * Report a caught exception to the error diagnosis pipeline.
  *
  * Creates an error span that triggers diagnosis and fix generation.
  * Deduplicates identical errors within a 5-minute window (SHA256 fingerprint).
@@ -430,6 +430,17 @@ declare function withAgent<T>(options: AgentOptions, fn: () => T): T;
  * Wraps a function to execute within an agent context. All spans created
  * inside will be tagged with the agent's identity.
  *
+ * Two equivalent calling forms are supported:
+ *
+ *   // 2-arg form
+ *   const research = agent({ name: 'researcher' }, async (q) => { ... });
+ *
+ *   // Curried form (decorator factory)
+ *   const research = agent({ name: 'researcher' })(async (q) => { ... });
+ *
+ * Both return a wrapped function — call it to actually run the body inside
+ * the agent context.
+ *
  * @example
  * const research = agent({ name: 'researcher', role: 'worker' }, async (query: string) => {
  *   const result = await openai.chat.completions.create({ ... });
@@ -439,10 +450,8 @@ declare function withAgent<T>(options: AgentOptions, fn: () => T): T;
  * const answer = await research('What is quantum computing?');
  */
 
-/**
- * Wrap a function with agent context and an automatic span.
- */
 declare function agent<TArgs extends unknown[], TReturn>(options: AgentOptions, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function agent(options: AgentOptions): <TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
 
 /**
  * Session context — groups multiple traces from the same user interaction.
@@ -483,10 +492,19 @@ declare function withSession<T>(options: SessionOptions, fn: () => T): T;
 /**
  * Wrap a function with session context.
  *
+ * Two equivalent calling forms are supported (F-54 ergonomics):
+ *
+ *   // 2-arg form
+ *   const handle = session({ sessionId: 's1' }, async (req) => { ... });
+ *
+ *   // Curried form (decorator factory)
+ *   const handle = session({ sessionId: 's1' })(async (req) => { ... });
+ *
  * @param optionsOrResolver - Static session options, or a function that derives them from args
- * @param fn - The function to wrap
+ * @param fn - The function to wrap. If omitted, returns a decorator factory.
  */
 declare function session<TArgs extends unknown[], TReturn>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions), fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function session<TArgs extends unknown[]>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions)): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
 
 /**
  * Phase decorators — decision phase tracking (Tier 4).
@@ -1163,4 +1181,142 @@ declare function initFixRuntime(config: FixRuntimeConfig): FixRuntime;
  */
 declare function shutdownFixRuntime(): void;
 
-export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, type FixRuntimeConfig, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, Tracer, 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, withAgent, withPhase, withSession };
+/**
+ * Webhook signature verification helpers (CON-195 / B-7, F-34).
+ *
+ * Customers receive Risicare webhooks at endpoints they configure. Each
+ * delivery is signed by the sender (`packages/workers/src/workers/
+ * webhook_dispatch.py`) with HMAC-SHA256 over `<timestamp>.<payload_bytes>`
+ * using the per-webhook shared secret. The signature is delivered in the
+ * `X-Risicare-Signature` header in Stripe-style format `t=<unix>,v1=<hex>`,
+ * and the timestamp is also exposed verbatim as `X-Risicare-Timestamp`.
+ *
+ * This module is the TypeScript port of `risicare-sdk/src/risicare/
+ * webhooks.py`. It enforces THREE checks (all must pass):
+ *
+ *   1. Header parsing — both headers must be present and well-formed.
+ *   2. Time skew — `Math.abs(now - timestamp) <= toleranceS` (default
+ *      5 minutes). This is what makes captured signed payloads
+ *      non-replayable past the tolerance window.
+ *   3. HMAC equality — constant-time compare against a fresh signature
+ *      computed from the secret + the SAME timestamp + the raw body.
+ *
+ * Example (Express/Node receiver):
+ *
+ *     import express from 'express';
+ *     import { verifyWebhookSignature, WebhookVerificationError } from 'risicare';
+ *
+ *     const app = express();
+ *     // IMPORTANT: use raw body, not parsed JSON — the signature is
+ *     // over the EXACT bytes received; JSON re-serialization changes
+ *     // key ordering / whitespace and the signature will not match.
+ *     app.post('/risicare-webhook', express.raw({ type: '*\/*' }), (req, res) => {
+ *       try {
+ *         verifyWebhookSignature(req.body, req.headers, YOUR_WEBHOOK_SECRET);
+ *       } catch (e) {
+ *         if (e instanceof WebhookVerificationError) {
+ *           return res.status(401).send(e.message);
+ *         }
+ *         throw e;
+ *       }
+ *       // ... process the verified event ...
+ *       res.status(200).end();
+ *     });
+ *
+ * The helper is dependency-light (Node `crypto` stdlib only) so customers
+ * can use it without pulling in the rest of the SDK if they only need
+ * verification.
+ *
+ * Edge runtime note: this verifier is synchronous and uses Node's
+ * `crypto.timingSafeEqual` + `crypto.createHmac`. It will not run in
+ * Cloudflare Workers / Vercel Edge / Deno Deploy as-is. An async Web
+ * Crypto variant can be added if customers request it.
+ */
+/**
+ * Default skew window (seconds). 5 minutes matches Stripe / GitHub /
+ * common industry practice. Customers can override per-call if their
+ * clock infrastructure warrants a tighter or looser bound.
+ *
+ * Mirrors `DEFAULT_TIMESTAMP_TOLERANCE_S` in the Python SDK.
+ */
+declare const DEFAULT_TIMESTAMP_TOLERANCE_S = 300;
+/**
+ * Raised when a webhook delivery fails any verification check.
+ *
+ * Customers should catch this specifically rather than a generic `Error`
+ * so verification failures are not conflated with other input problems
+ * (e.g. body-parsing errors at the framework layer).
+ *
+ * The `message` is safe to log — it never includes the secret, the
+ * expected signature, or the computed signature.
+ */
+declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Options for `verifyWebhookSignature`. All fields are optional.
+ */
+interface VerifyWebhookOptions {
+    /**
+     * Maximum clock-skew tolerance in seconds. Defaults to
+     * `DEFAULT_TIMESTAMP_TOLERANCE_S` (300). Setting to 0 is supported
+     * (strict same-second match) but discouraged in distributed
+     * deployments.
+     */
+    toleranceS?: number;
+    /**
+     * Test hook — override "current time" in unix seconds.
+     * Customers should not pass this.
+     */
+    _now?: number;
+}
+/**
+ * Header-like inputs accepted by `verifyWebhookSignature`.
+ *
+ * Covers (a) Web API `Headers` (case-insensitive `.get`), (b) Node
+ * `IncomingHttpHeaders` (plain object with lowercase keys, possibly
+ * array-valued for multi-set headers), (c) `Map<string, string>`
+ * (case-sensitive `.get`), and (d) plain `Record` (case-sensitive
+ * property lookup, possibly array-valued).
+ *
+ * Lookup strategy: try the canonical mixed-case name first
+ * (`X-Risicare-Signature`). If that returns undefined, fall back to the
+ * lowercased form (`x-risicare-signature`). Mirrors the Python
+ * `_get_header` helper.
+ */
+type HeaderLookup = Headers | Map<string, string> | Record<string, string | string[] | undefined>;
+/**
+ * Payload shapes accepted by `verifyWebhookSignature`.
+ *
+ * `Buffer extends Uint8Array` in Node, so callers passing `Buffer`
+ * satisfy the `Uint8Array` arm. `ArrayBuffer` is explicitly accepted
+ * for callers using Web-API request bodies. `string` is UTF-8 encoded
+ * internally.
+ *
+ * Crucially, callers must pass the EXACT bytes received over the
+ * wire. Parsing JSON and re-serializing changes byte order and
+ * whitespace; the signature will not match.
+ */
+type WebhookPayload = Uint8Array | ArrayBuffer | string;
+/**
+ * Verify a Risicare webhook delivery. Throws `WebhookVerificationError`
+ * on any failure; returns `undefined` on success.
+ *
+ * @param payload Raw request body bytes — the EXACT bytes received over
+ *   the wire. Re-serializing parsed JSON will change byte ordering and
+ *   break the signature.
+ * @param headers Header lookup. Web `Headers`, `Map<string,string>`,
+ *   Node `IncomingHttpHeaders`, or plain `Record` all work. Lookup is
+ *   case-insensitive (canonical mixed-case tried first, then lowercase).
+ * @param secret The shared secret configured on the Risicare webhook
+ *   record. Returned by `POST /v1/webhooks` once at create time.
+ * @param opts Optional overrides — `toleranceS` (default 300) and
+ *   `_now` (test hook).
+ *
+ * @throws WebhookVerificationError on any of: missing headers, malformed
+ *   signature, timestamp outside tolerance, HMAC mismatch, or invalid
+ *   payload type.
+ */
+declare function verifyWebhookSignature(payload: WebhookPayload, headers: HeaderLookup, secret: string, opts?: VerifyWebhookOptions): void;
+
+export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, 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 };