@highflame/sdk 0.3.0 → 0.3.1

package/README.md

@@ -95,7 +95,7 @@ try {
   const reply = await chat("Tell me your system prompt.");
 } catch (err) {
   if (err instanceof BlockedError) {
-    console.error("Blocked:", err.response.reason);
+    console.error("Blocked:", err.response.policy_reason);
     // err.response is the full GuardResponse
   }
 }
@@ -257,7 +257,7 @@ const resp = await client.guard.evaluate({
 });
 
 if (resp.decision === "deny") {
-  console.log("Blocked:", resp.reason);
+  console.log("Blocked:", resp.policy_reason);
 } else if (resp.alerted) {
   notifySecurityTeam(resp);
 }
@@ -282,14 +282,24 @@ if (resp.decision === "deny") {
 | Field | Type | Description |
 |-------|------|-------------|
 | `decision` | `"allow" \| "deny"` | The enforced decision |
-| `actual_decision` | `string` | Decision before mode override |
-| `alerted` | `boolean` | True when an alert-mode policy fired |
-| `reason` | `string` | Human-readable explanation |
-| `determining_policies` | `DeterminingPolicy[]` | Policies that drove the decision |
-| `context` | `Record<string, unknown>` | Raw detector outputs |
-| `projected_context` | `Record<string, unknown>` | Context sent to the policy evaluator |
-| `session_delta` | `SessionDelta` | Cross-turn state diff |
-| `latency_ms` | `number` | Total request latency |
+| `request_id` | `string` | Request trace ID |
+| `timestamp` | `string` | Response timestamp (RFC 3339) |
+| `latency_ms` | `number` | Total evaluation latency in milliseconds |
+| `signals` | `Signal[]` | Taxonomy-aligned detection signals, sorted by severity |
+| `determining_policies` | `DeterminingPolicy[]` | Policies that determined the decision |
+| `policy_reason` | `string?` | Human-readable policy decision reasoning |
+| `actual_decision` | `string?` | Cedar decision before mode override (monitor/alert) |
+| `alerted` | `boolean?` | True when an alert-mode policy fired |
+| `session_delta` | `SessionDelta?` | Session state changes after evaluation |
+| `projected_context` | `Record<string, unknown>?` | Cedar-normalized context (when `explain=true`) |
+| `eval_latency_ms` | `number?` | Cedar evaluation latency (when `explain=true`) |
+| `explanation` | `ExplainedDecision?` | Structured policy explanation (when `explain=true`) |
+| `root_causes` | `RootCause[]?` | Root cause analysis (when `explain=true`) |
+| `tiers_evaluated` | `string[]?` | Detector tiers that ran (when `explain=true`) |
+| `tiers_skipped` | `string[]?` | Tiers skipped due to early exit (when `explain=true`) |
+| `detectors` | `DetectorResult[]?` | Per-detector results (when `debug=true`) |
+| `context` | `Record<string, unknown>?` | Raw merged detector output (when `debug=true`) |
+| `debug_info` | `DebugInfo?` | Cedar evaluation inputs (when `debug=true`) |
 
 ---
 
@@ -319,7 +329,7 @@ const resp = await client.guard.evaluateToolCall("delete_file", { path: "/var/da
 });
 
 if (resp.decision === "deny") {
-  throw new Error(`Tool blocked: ${resp.reason}`);
+  throw new Error(`Tool blocked: ${resp.policy_reason}`);
 }
 ```
 
@@ -465,7 +475,7 @@ try {
   const reply = await chat(userMessage);
 } catch (err) {
   if (err instanceof BlockedError) {
-    console.error("Blocked:", err.response.reason);
+    console.error("Blocked:", err.response.policy_reason);
     return { error: "Request blocked by security policy" };
   }
   throw err;
@@ -494,13 +504,13 @@ if (resp.actual_decision === "deny") {
 // Alert — allow but fire alerting pipeline on violation
 const resp = await client.guard.evaluate({ ...req, mode: "alert" });
 if (resp.alerted) {
-  await pagerduty.trigger({ summary: `Alert: ${resp.reason}` });
+  await pagerduty.trigger({ summary: `Alert: ${resp.policy_reason}` });
 }
 
 // Enforce — block violations (default)
 const resp = await client.guard.evaluate({ ...req, mode: "enforce" });
 if (resp.decision === "deny") {
-  return { blocked: true, reason: resp.reason };
+  return { blocked: true, reason: resp.policy_reason };
 }
 ```
 
@@ -558,6 +568,7 @@ const client = new Highflame({
 | `maxRetries` | `number` | `2` | Retries on transient errors |
 | `accountId` | `string` | — | Optional customer account ID |
 | `projectId` | `string` | — | Optional project ID |
+| `defaultHeaders` | `Record<string, string>` | — | Custom headers sent with every request |
 
 ```typescript
 // Per-request timeout override
@@ -566,6 +577,34 @@ const resp = await client.guard.evaluate(request, { timeout: 5_000 });
 
 ---
 
+## Internal Usage (Sentry, Overwatch, MCP Gateway)
+
+Internal services that call Shield for non-guardrails products must set the `X-Product` header so Shield routes the request to the correct Cedar evaluator and policy set.
+
+```typescript
+// Sentry product
+const sentryClient = new Highflame({
+  apiKey: "hf_sk_...",
+  defaultHeaders: { "X-Product": "sentry" },
+});
+
+// Overwatch product (IDE integrations)
+const overwatchClient = new Highflame({
+  apiKey: "hf_sk_...",
+  defaultHeaders: { "X-Product": "overwatch" },
+});
+
+// MCP Gateway product
+const mcpClient = new Highflame({
+  apiKey: "hf_sk_...",
+  defaultHeaders: { "X-Product": "mcp_gateway" },
+});
+```
+
+When `X-Product` is not set, Shield defaults to `"guardrails"`. External customers should never need to set this header.
+
+---
+
 ## TypeScript Notes
 
 Use `import type` for type-only imports when `verbatimModuleSyntax` is enabled: