@logbrew/sdk 0.1.13 → 0.1.15

package/README.md

@@ -125,6 +125,13 @@ try {
       service: "checkout-web",
       runtime: "browser",
       fingerprint: "checkout-runtime-error",
+      evidence: {
+        likelyRootCause: "The payment provider exhausted its retry budget.",
+        likelyFixArea: { file: "src/payments/gateway.js", function: "chargeOrder", line: 42 },
+        impact: { failedAction: "checkout.submit", userVisibleOutcome: "The order was not confirmed." },
+        capturedFields: ["provider.status", "retry.count"],
+        redactedFields: ["provider.message"]
+      },
       debugIdMap: {
         "https://cdn.example/assets/app.js": "11111111-2222-4333-8444-555555555555"
       },
@@ -136,6 +143,8 @@ try {
 
 The helper records the error name/message, a typed exception with capture mechanism and handled state, and up to 32 ordered generated `stackFrames`, with query strings, hashes, and local absolute prefixes removed. Each frame carries filename, positive line/column, a conservatively parsed function name when the runtime provides one, and an optional matched Debug ID. Applications that create frames directly may also provide bounded `function`, `module`, and `inApp` identity. Existing first-frame metadata remains available for compatible grouping and tooling. The helper also emits an `issueGroupingKey` based on source, error type, and the sanitized first frame, plus an optional app-owned `issueFingerprint` when you pass a stable, safe, low-cardinality `fingerprint`. Nested `Error.cause` chains and `AggregateError.errors` are summarized as bounded cause counts, types, and sources without copying nested messages or stacks. Raw stack text is included only with `includeErrorStack: true`.
 
+`evidence` is explicit application knowledge, not an SDK inference. LogBrew labels `likelyRootCause` as a reported hypothesis and keeps `likelyFixArea` separate from observed frames. Field-state arrays make missing, redacted, and truncated evidence visible to API, CLI, dashboard, and agent consumers. Keep identities low-cardinality, use repository-relative file paths, and never put credentials, request bodies, personal data, or raw user input in these fields.
+
 Use `addBreadcrumb()` for explicit navigation, state, action, or network steps that should appear on later issues. The client keeps only the most recent 64 entries and marks an issue with `breadcrumbsTruncated: true` after older entries are evicted. `clearBreadcrumbs()` removes the current history.
 
 ```js

package/core.cjs

@@ -75,6 +75,7 @@ const PINO_SENSITIVE_CONTEXT_FIELDS = new Set([
 const TRACEPARENT_PATTERN = /^([0-9a-fA-F]{2})-([0-9a-fA-F]{32})-([0-9a-fA-F]{16})-([0-9a-fA-F]{2})$/u;
 const ZERO_TRACE_ID = "00000000000000000000000000000000";
 const ZERO_SPAN_ID = "0000000000000000";
+const RFC3339_TIMESTAMP_PATTERN = /^(\d{4})-(\d{2})-(\d{2})T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/u;
 const DEFAULT_MAX_QUEUE_SIZE = 1000;
 const DEFAULT_MAX_QUEUE_BYTES = 4 * 1024 * 1024;
 const DEFAULT_MAX_BATCH_EVENTS = 100;
@@ -138,7 +139,8 @@ const {
   cloneIssueDiagnostics,
   createIssueException,
   validateIssueBreadcrumb,
-  validateIssueDiagnostics
+  validateIssueDiagnostics,
+  validateIssueEvidence
 } = buildIssueDiagnosticsHelpers({ SdkError, requireTimestamp, validateIssueStackFrames });
 const {
   cloneTelemetryContext,
@@ -1410,6 +1412,7 @@ function createIssueAttributesFromError(error, options = {}) {
     exception,
     exceptionChain,
     ...(stackFrames.length > 0 ? { stackFrames } : {}),
+    ...(options.evidence === undefined ? {} : { evidence: validateIssueEvidence(options.evidence) }),
     metadata: compactMetadata(metadata)
   };
 }
@@ -2197,17 +2200,25 @@ function requireTraceFlags(traceFlags) {
 
 function requireTimestamp(timestamp) {
   requireNonEmpty("timestamp", timestamp);
-  if (timestamp.endsWith("Z")) {
-    return;
-  }
   const timePortion = timestamp.split("T")[1];
-  if (timePortion && (timePortion.includes("+") || /.+-.+/.test(timePortion))) {
-    return;
+  if (!timestamp.endsWith("Z")
+    && !(timePortion && (timePortion.includes("+") || /.+-.+/.test(timePortion)))) {
+    throw new SdkError(
+      "validation_error",
+      `timestamp must include a timezone offset: ${timestamp}`
+    );
+  }
+  const match = timestamp.match(RFC3339_TIMESTAMP_PATTERN);
+  const calendar = new Date(0);
+  calendar.setUTCHours(0, 0, 0, 0);
+  calendar.setUTCFullYear(Number(match?.[1]), Number(match?.[2]) - 1, Number(match?.[3]));
+  if (!match
+    || Number(match[1]) === 0
+    || calendar.getUTCFullYear() !== Number(match[1])
+    || calendar.getUTCMonth() !== Number(match[2]) - 1
+    || calendar.getUTCDate() !== Number(match[3])) {
+    throw new SdkError("validation_error", `invalid timestamp: ${timestamp}`);
   }
-  throw new SdkError(
-    "validation_error",
-    `timestamp must include a timezone offset: ${timestamp}`
-  );
 }
 
 function cloneMetadata(metadata) {