@djust-b2b/djust-front-sdk 3.0.0 → 3.1.0

package/dist/index.cjs

@@ -24,7 +24,7 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getHttpStatus = exports.isApiError = exports.withStructuredErrors = exports.withLegacyErrors = exports.parseLegacyError = exports.isLegacyError = exports.fromLegacyError = exports.toLegacyError = exports.getUserFriendlyMessage = exports.extractErrorCode = exports.extractStatusCode = exports.isTransientError = exports.isClientError = exports.shouldReauthenticate = exports.getRetryDelay = exports.isRetryable = exports.isUnexpectedError = exports.isRateLimitError = exports.isNotFoundError = exports.isValidationError = exports.isServerError = exports.isTimeoutError = exports.isNetworkError = exports.isForbiddenError = exports.isAuthError = exports.isSDKError = exports.createErrorFromException = exports.createErrorFromResponse = exports.UnexpectedError = exports.ServerError = exports.TimeoutError = exports.NetworkError = exports.RateLimitError = exports.NotFoundError = exports.ForbiddenError = exports.AuthError = exports.ValidationError = exports.RETRIABLE_HTTP_STATUS_CODES = exports.RETRIABLE_ERROR_CODES = exports.SDKErrorCode = exports.SDKError = exports.createDjustClient = exports.DjustSDK = void 0;
+exports.getW3CTraceFromHeaders = exports.mergeTransportHooks = exports.createDjustErrorHooks = exports.buildDjustErrorEvent = exports.createDjustSentryHooks = exports.captureDjustError = exports.buildDjustSentryTags = exports.getHttpStatus = exports.isApiError = exports.withStructuredErrors = exports.withLegacyErrors = exports.parseLegacyError = exports.isLegacyError = exports.fromLegacyError = exports.toLegacyError = exports.getUserFriendlyMessage = exports.extractErrorCode = exports.extractStatusCode = exports.isTransientError = exports.isClientError = exports.shouldReauthenticate = exports.getRetryDelay = exports.isRetryable = exports.isUnexpectedError = exports.isRateLimitError = exports.isNotFoundError = exports.isValidationError = exports.isServerError = exports.isTimeoutError = exports.isNetworkError = exports.isForbiddenError = exports.isAuthError = exports.isSDKError = exports.createErrorFromException = exports.createErrorFromResponse = exports.UnexpectedError = exports.ServerError = exports.TimeoutError = exports.NetworkError = exports.RateLimitError = exports.NotFoundError = exports.ForbiddenError = exports.AuthError = exports.ValidationError = exports.RETRIABLE_HTTP_STATUS_CODES = exports.RETRIABLE_ERROR_CODES = exports.SDKErrorCode = exports.SDKError = exports.createDjustClient = exports.DjustSDK = void 0;
 const tslib_1 = require("tslib");
 const AuthServices = tslib_1.__importStar(require("./services/auth"));
 const CartServices = tslib_1.__importStar(require("./services/cart"));
@@ -176,6 +176,17 @@ Object.defineProperty(exports, "withStructuredErrors", { enumerable: true, get:
 Object.defineProperty(exports, "isApiError", { enumerable: true, get: function () { return errors_1.isApiError; } });
 Object.defineProperty(exports, "getHttpStatus", { enumerable: true, get: function () { return errors_1.getHttpStatus; } });
 // ============================================================================
+// MONITORING (Sentry helpers — @sentry/node is a host-app peer)
+// ============================================================================
+var monitoring_1 = require("./monitoring");
+Object.defineProperty(exports, "buildDjustSentryTags", { enumerable: true, get: function () { return monitoring_1.buildDjustSentryTags; } });
+Object.defineProperty(exports, "captureDjustError", { enumerable: true, get: function () { return monitoring_1.captureDjustError; } });
+Object.defineProperty(exports, "createDjustSentryHooks", { enumerable: true, get: function () { return monitoring_1.createDjustSentryHooks; } });
+Object.defineProperty(exports, "buildDjustErrorEvent", { enumerable: true, get: function () { return monitoring_1.buildDjustErrorEvent; } });
+Object.defineProperty(exports, "createDjustErrorHooks", { enumerable: true, get: function () { return monitoring_1.createDjustErrorHooks; } });
+Object.defineProperty(exports, "mergeTransportHooks", { enumerable: true, get: function () { return monitoring_1.mergeTransportHooks; } });
+Object.defineProperty(exports, "getW3CTraceFromHeaders", { enumerable: true, get: function () { return monitoring_1.getW3CTraceFromHeaders; } });
+// ============================================================================
 // INTERFACES (unchanged)
 // ============================================================================
 tslib_1.__exportStar(require("./interfaces"), exports);

package/dist/index.d.ts

@@ -263,5 +263,7 @@ export { createDjustClient } from "./client";
 export type { DjustClientConfig, DjustClient, DjustScopedClient, RequestContext, RetryConfig, TransportHooks, } from "./client";
 export { SDKError, SDKErrorCode, RETRIABLE_ERROR_CODES, RETRIABLE_HTTP_STATUS_CODES, ValidationError, AuthError, ForbiddenError, NotFoundError, RateLimitError, NetworkError, TimeoutError, ServerError, UnexpectedError, createErrorFromResponse, createErrorFromException, isSDKError, isAuthError, isForbiddenError, isNetworkError, isTimeoutError, isServerError, isValidationError, isNotFoundError, isRateLimitError, isUnexpectedError, isRetryable, getRetryDelay, shouldReauthenticate, isClientError, isTransientError, extractStatusCode, extractErrorCode, getUserFriendlyMessage, toLegacyError, fromLegacyError, isLegacyError, parseLegacyError, withLegacyErrors, withStructuredErrors, isApiError, getHttpStatus, } from "./errors";
 export type { SDKErrorCodeType, SDKErrorOptions, RequestMetadata, ErrorFactoryOptions, SerializedError, ClientSafeError, } from "./errors";
+export { buildDjustSentryTags, captureDjustError, createDjustSentryHooks, buildDjustErrorEvent, createDjustErrorHooks, mergeTransportHooks, getW3CTraceFromHeaders, } from "./monitoring";
+export type { DjustErrorCaptureContext, DjustSentryMonitoringOptions, SentryLike, SentryScope, DjustErrorEvent, DjustErrorHooksOptions, DjustErrorListener, DjustMonitoringTier, W3CTraceFields, } from "./monitoring";
 export * from "./interfaces";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAwBH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ;IAiBnB;;OAEG;;IAEH;;OAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gBA2H+usB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;CAzHpvsB,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EACV,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,cAAc,GACf,MAAM,UAAU,CAAC;AAMlB,OAAO,EAEL,QAAQ,EACR,YAAY,EACZ,qBAAqB,EACrB,2BAA2B,EAG3B,eAAe,EACf,SAAS,EACT,cAAc,EACd,aAAa,EACb,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,eAAe,EAGf,uBAAuB,EACvB,wBAAwB,EAGxB,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EAGjB,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EAGtB,aAAa,EACb,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,UAAU,EACV,aAAa,GACd,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,eAAe,GAChB,MAAM,UAAU,CAAC;AAMlB,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAwBH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ;IAiBnB;;OAEG;;IAEH;;OAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gBAqJwlrB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;CAnJ7lrB,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EACV,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,cAAc,GACf,MAAM,UAAU,CAAC;AAMlB,OAAO,EAEL,QAAQ,EACR,YAAY,EACZ,qBAAqB,EACrB,2BAA2B,EAG3B,eAAe,EACf,SAAS,EACT,cAAc,EACd,aAAa,EACb,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,eAAe,EAGf,uBAAuB,EACvB,wBAAwB,EAGxB,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EAGjB,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EAGtB,aAAa,EACb,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,UAAU,EACV,aAAa,GACd,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,eAAe,GAChB,MAAM,UAAU,CAAC;AAMlB,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,wBAAwB,EACxB,4BAA4B,EAC5B,UAAU,EACV,WAAW,EACX,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,GACf,MAAM,cAAc,CAAC;AAMtB,cAAc,cAAc,CAAC"}

package/dist/index.mjs

@@ -1326,7 +1326,7 @@ import * as Sentry from "@sentry/browser";
 import "isomorphic-fetch";
 
 // src/settings/sdk-version.ts
-var SDK_VERSION = "3.0.0";
+var SDK_VERSION = "3.1.0";
 
 // src/settings/fetch-instance.ts
 var clientConfig = {
@@ -11628,6 +11628,246 @@ init_unexpected_error();
 // src/errors/index.ts
 init_factory();
 
+// src/monitoring/w3c-trace.ts
+function getW3CTraceFromHeaders(headers) {
+  const traceparent = headers.traceparent ?? headers.Traceparent;
+  if (!traceparent) {
+    return {};
+  }
+  const parts = traceparent.trim().split("-");
+  if (parts.length !== 4 || parts[0] !== "00") {
+    return { traceparent };
+  }
+  const [, traceId, spanId] = parts;
+  const isHex = (value, length) => value.length === length && /^[0-9a-f]+$/i.test(value);
+  if (!isHex(traceId, 32) || !isHex(spanId, 16)) {
+    return { traceparent };
+  }
+  return { traceparent, traceId, spanId };
+}
+
+// src/monitoring/utils.ts
+function getEndpoint(url) {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url;
+  }
+}
+
+// src/monitoring/sentry.ts
+function resolveErrorCode(error) {
+  if (isSDKError(error)) {
+    return String(error.code);
+  }
+  const legacy = fromLegacyError(error);
+  return legacy ? String(legacy.code) : SDKErrorCode.UNEXPECTED_ERROR;
+}
+function resolveHttpStatus(error) {
+  if (isSDKError(error)) {
+    return error.httpStatus;
+  }
+  const legacy = fromLegacyError(error);
+  return legacy?.httpStatus ?? 500;
+}
+function buildDjustSentryTags(error, context) {
+  const tags = {
+    "djust.source": context.source,
+    "djust.error_code": resolveErrorCode(error),
+    "djust.http_status": String(resolveHttpStatus(error)),
+    "djust.retriable": String(isSDKError(error) ? error.retriable : false)
+  };
+  if (context.clientId)
+    tags["djust.client_id"] = context.clientId;
+  if (context.clientName)
+    tags["djust.client_name"] = context.clientName;
+  if (context.environment)
+    tags["djust.env"] = context.environment;
+  if (context.requestId)
+    tags["djust.request_id"] = context.requestId;
+  if (context.traceId)
+    tags["djust.trace_id"] = context.traceId;
+  if (context.traceparent)
+    tags["djust.traceparent"] = context.traceparent;
+  if (context.spanId)
+    tags["djust.span_id"] = context.spanId;
+  if (context.method)
+    tags["djust.method"] = context.method;
+  if (context.endpoint)
+    tags["djust.endpoint"] = context.endpoint;
+  if (context.bffRoute)
+    tags["djust.bff_route"] = context.bffRoute;
+  if (context.monitoringTier) {
+    tags["djust.monitoring_tier"] = context.monitoringTier;
+  }
+  if (context.willRetry !== void 0) {
+    tags["djust.will_retry"] = String(context.willRetry);
+  }
+  return tags;
+}
+function captureDjustError(sentry, error, context, options) {
+  if (options?.skipIfRetrying && context.willRetry) {
+    return;
+  }
+  const httpStatus = resolveHttpStatus(error);
+  const ignored = options?.ignoredHttpStatuses ?? [];
+  if (ignored.includes(httpStatus)) {
+    return;
+  }
+  const endpoint = context.endpoint ?? (isSDKError(error) ? error.metadata.endpoint : void 0);
+  const tags = buildDjustSentryTags(error, { ...context, endpoint });
+  sentry.withScope((scope) => {
+    for (const [key, value] of Object.entries(tags)) {
+      scope.setTag(key, value);
+    }
+    if (isSDKError(error)) {
+      scope.setContext(
+        "djust_error",
+        error.toJSON()
+      );
+    }
+    if (context.traceparent || context.traceId || context.spanId) {
+      scope.setContext("w3c_trace", {
+        traceId: context.traceId ?? context.requestId,
+        spanId: context.spanId,
+        traceparent: context.traceparent
+      });
+    }
+    scope.captureException(error);
+  });
+}
+function createDjustSentryHooks(sentry, options = {}) {
+  const skipRetrying = options.skipRetryingErrors ?? true;
+  const ignoredHttpStatuses = options.ignoredHttpStatuses ?? [];
+  return {
+    onError(ctx) {
+      const w3c = getW3CTraceFromHeaders(ctx.headers);
+      captureDjustError(
+        sentry,
+        ctx.error,
+        {
+          source: "sdk",
+          monitoringTier: options.monitoringTier ?? "djust",
+          clientId: options.clientId,
+          clientName: options.clientName,
+          environment: options.environment,
+          requestId: ctx.requestId,
+          traceId: w3c.traceId ?? ctx.requestId,
+          traceparent: w3c.traceparent,
+          spanId: w3c.spanId,
+          method: ctx.method,
+          endpoint: getEndpoint(ctx.url),
+          willRetry: ctx.willRetry
+        },
+        { skipIfRetrying: skipRetrying, ignoredHttpStatuses }
+      );
+    },
+    onRetry(ctx) {
+      sentry.addBreadcrumb({
+        category: "djust.retry",
+        message: `Retry ${ctx.attempt}/${ctx.maxAttempts} for ${ctx.requestId}`,
+        level: "warning",
+        data: {
+          requestId: ctx.requestId,
+          attempt: ctx.attempt,
+          delayMs: ctx.delayMs,
+          reason: ctx.reason,
+          errorCode: resolveErrorCode(ctx.error)
+        }
+      });
+    }
+  };
+}
+
+// src/monitoring/observability.ts
+function resolveMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function buildDjustErrorEvent(error, context) {
+  const sdkError = isSDKError(error) ? error : fromLegacyError(error);
+  const endpoint = context.endpoint ?? (isSDKError(error) ? error.metadata.endpoint : void 0);
+  return {
+    code: sdkError ? String(sdkError.code) : SDKErrorCode.UNEXPECTED_ERROR,
+    httpStatus: sdkError?.httpStatus ?? 500,
+    retriable: sdkError?.retriable ?? false,
+    message: resolveMessage(error),
+    source: context.source,
+    monitoringTier: context.monitoringTier,
+    clientId: context.clientId,
+    clientName: context.clientName,
+    environment: context.environment,
+    traceId: context.traceId ?? context.requestId,
+    traceparent: context.traceparent,
+    spanId: context.spanId,
+    requestId: context.requestId,
+    method: context.method,
+    endpoint,
+    bffRoute: context.bffRoute,
+    willRetry: context.willRetry,
+    serialized: isSDKError(error) ? error.toJSON() : void 0,
+    error
+  };
+}
+function createDjustErrorHooks(onError, options = {}) {
+  const skipRetrying = options.skipRetryingErrors ?? true;
+  const ignoredHttpStatuses = options.ignoredHttpStatuses ?? [];
+  return {
+    onError(ctx) {
+      if (skipRetrying && ctx.willRetry) {
+        return;
+      }
+      const httpStatus = isSDKError(ctx.error) ? ctx.error.httpStatus : fromLegacyError(ctx.error)?.httpStatus ?? 500;
+      if (ignoredHttpStatuses.includes(httpStatus)) {
+        return;
+      }
+      const w3c = getW3CTraceFromHeaders(ctx.headers);
+      const event = buildDjustErrorEvent(ctx.error, {
+        source: "sdk",
+        monitoringTier: options.monitoringTier,
+        clientId: options.clientId,
+        clientName: options.clientName,
+        environment: options.environment,
+        requestId: ctx.requestId,
+        traceId: w3c.traceId ?? ctx.requestId,
+        traceparent: w3c.traceparent,
+        spanId: w3c.spanId,
+        method: ctx.method,
+        endpoint: getEndpoint(ctx.url),
+        willRetry: ctx.willRetry
+      });
+      return onError(event);
+    }
+  };
+}
+var TRANSPORT_HOOK_NAMES = [
+  "onRequestStart",
+  "onRequestEnd",
+  "onError",
+  "onRetry",
+  "onCacheHit"
+];
+function mergeTransportHooks(...hookSets) {
+  const merged = {};
+  for (const hookName of TRANSPORT_HOOK_NAMES) {
+    const handlers = hookSets.map((set) => set[hookName]).filter(
+      (handler) => Boolean(handler)
+    );
+    if (handlers.length === 0) {
+      continue;
+    }
+    const runHandlers = async (ctx) => {
+      await Promise.allSettled(
+        handlers.map(async (handler) => handler(ctx))
+      );
+    };
+    Object.assign(merged, { [hookName]: runHandlers });
+  }
+  return merged;
+}
+
 // src/services/operation/definitions.ts
 var OperationType = /* @__PURE__ */ ((OperationType2) => {
   OperationType2["PUBLIC"] = "PUBLIC";
@@ -11693,7 +11933,12 @@ export {
   TimeoutError,
   UnexpectedError,
   ValidationError,
+  buildDjustErrorEvent,
+  buildDjustSentryTags,
+  captureDjustError,
   createDjustClient,
+  createDjustErrorHooks,
+  createDjustSentryHooks,
   createErrorFromException,
   createErrorFromResponse,
   extractErrorCode,
@@ -11702,6 +11947,7 @@ export {
   getHttpStatus,
   getRetryDelay,
   getUserFriendlyMessage,
+  getW3CTraceFromHeaders,
   isApiError,
   isAuthError,
   isClientError,
@@ -11717,6 +11963,7 @@ export {
   isTransientError,
   isUnexpectedError,
   isValidationError,
+  mergeTransportHooks,
   parseLegacyError,
   shouldReauthenticate,
   toLegacyError,

package/dist/monitoring/index.d.ts

@@ -0,0 +1,7 @@
+export { buildDjustSentryTags, captureDjustError, createDjustSentryHooks, } from "./sentry";
+export { buildDjustErrorEvent, createDjustErrorHooks, mergeTransportHooks, } from "./observability";
+export { getW3CTraceFromHeaders } from "./w3c-trace";
+export type { W3CTraceFields } from "./w3c-trace";
+export type { DjustErrorCaptureContext, DjustSentryMonitoringOptions, SentryLike, SentryScope, } from "./sentry";
+export type { DjustErrorEvent, DjustErrorHooksOptions, DjustErrorListener, DjustMonitoringTier, } from "./observability";
+//# sourceMappingURL=index.d.ts.map

package/dist/monitoring/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/monitoring/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,YAAY,EACV,wBAAwB,EACxB,4BAA4B,EAC5B,UAAU,EACV,WAAW,GACZ,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC"}

package/dist/monitoring/observability.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Vendor-neutral observability primitives.
+ * DJUST Sentry and client monitoring (Sentry, DataDog, …) run in parallel.
+ *
+ * @module monitoring/observability
+ * @since 3.0.1
+ */
+import type { TransportHooks } from "../client/transport";
+import type { SerializedError } from "../errors/types";
+import type { DjustErrorCaptureContext } from "./sentry";
+export type DjustMonitoringTier = "djust" | "client";
+export interface DjustErrorEvent {
+    /** Normalized error payload — safe for logs and third-party tools */
+    code: string;
+    httpStatus: number;
+    retriable: boolean;
+    message: string;
+    source: DjustErrorCaptureContext["source"];
+    monitoringTier?: DjustMonitoringTier;
+    clientId?: string;
+    clientName?: string;
+    environment?: string;
+    /** W3C trace id — aligns with `getSDKTraceFields(event).requestId` */
+    traceId?: string;
+    traceparent?: string;
+    spanId?: string;
+    requestId?: string;
+    method?: string;
+    endpoint?: string;
+    bffRoute?: string;
+    willRetry?: boolean;
+    /** Present when the original error is an SDKError */
+    serialized?: SerializedError;
+    /** Original error reference (do not send to external tools verbatim) */
+    error: unknown;
+}
+export type DjustErrorListener = (event: DjustErrorEvent) => void | Promise<void>;
+export interface DjustErrorHooksOptions {
+    clientId?: string;
+    clientName?: string;
+    environment?: string;
+    monitoringTier?: DjustMonitoringTier;
+    skipRetryingErrors?: boolean;
+    ignoredHttpStatuses?: number[];
+}
+/**
+ * Builds a vendor-neutral error event from an SDKError (or legacy error).
+ * Use for DataDog, custom loggers, or a client-owned Sentry project.
+ */
+export declare function buildDjustErrorEvent(error: unknown, context: DjustErrorCaptureContext): DjustErrorEvent;
+/**
+ * Generic transport hooks for any monitoring backend.
+ * Compose in parallel with `createDjustSentryHooks` via `mergeTransportHooks`.
+ */
+export declare function createDjustErrorHooks(onError: DjustErrorListener, options?: DjustErrorHooksOptions): Pick<TransportHooks, "onError">;
+/**
+ * Runs multiple hook sets in parallel — DJUST Sentry + client Sentry + DataDog, etc.
+ */
+export declare function mergeTransportHooks(...hookSets: TransportHooks[]): TransportHooks;
+//# sourceMappingURL=observability.d.ts.map

package/dist/monitoring/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../src/monitoring/observability.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAGV,cAAc,EACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC;AAIzD,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAC3C,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,qDAAqD;IACrD,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,wEAAwE;IACxE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,kBAAkB,GAAG,CAC/B,KAAK,EAAE,eAAe,KACnB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAUD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,wBAAwB,GAChC,eAAe,CA4BjB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,sBAA2B,GACnC,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,CAsCjC;AAYD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,QAAQ,EAAE,cAAc,EAAE,GAC5B,cAAc,CAuBhB"}

package/dist/monitoring/sentry.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Sentry helpers for DJUST SDK and Auth BFF monitoring.
+ * Uses a minimal interface so @sentry/node stays a host-app peer dependency.
+ *
+ * @module monitoring/sentry
+ * @since 3.0.1
+ */
+import type { TransportHooks } from "../client/transport";
+export interface SentryScope {
+    setTag(key: string, value: string): void;
+    setContext(name: string, context: Record<string, unknown> | null): void;
+    captureException(exception: unknown): string;
+}
+export interface SentryLike {
+    withScope(callback: (scope: SentryScope) => void): void;
+    addBreadcrumb(breadcrumb: {
+        category?: string;
+        message?: string;
+        level?: "debug" | "info" | "warning" | "error" | "fatal";
+        data?: Record<string, unknown>;
+    }): void;
+}
+export interface DjustErrorCaptureContext {
+    /** `sdk` for commerce API calls, `auth` for Auth BFF routes */
+    source: "sdk" | "auth";
+    /** `djust` = DJUST org Sentry; `client` = portal-owned monitoring */
+    monitoringTier?: "djust" | "client";
+    clientId?: string;
+    clientName?: string;
+    environment?: string;
+    /** W3C trace id (same as `requestId` when `getSDKTraceFields` is wired) */
+    traceId?: string;
+    /** W3C `traceparent` header propagated to the Ecom API */
+    traceparent?: string;
+    /** W3C parent span id for the current SSR request */
+    spanId?: string;
+    requestId?: string;
+    method?: string;
+    /** Backend API path (from SDKError.metadata.endpoint) */
+    endpoint?: string;
+    /** BFF route, e.g. `POST /api/auth/login` */
+    bffRoute?: string;
+    willRetry?: boolean;
+}
+export interface DjustSentryMonitoringOptions {
+    clientId?: string;
+    clientName?: string;
+    environment?: string;
+    /** Defaults to `djust` — set `client` for a portal-owned Sentry project */
+    monitoringTier?: "djust" | "client";
+    /** Skip capture while the transport will retry (default: true) */
+    skipRetryingErrors?: boolean;
+    /** HTTP statuses excluded from capture (e.g. 404, 422) */
+    ignoredHttpStatuses?: number[];
+}
+/**
+ * Builds stable Sentry tags from an SDKError (or legacy error) and request context.
+ * Use the same tags across SDK commerce calls and Auth BFF routes for cross-client dashboards.
+ */
+export declare function buildDjustSentryTags(error: unknown, context: DjustErrorCaptureContext): Record<string, string>;
+/**
+ * Captures a DJUST error in Sentry with SDKError-aligned tags and context.
+ */
+export declare function captureDjustError(sentry: SentryLike, error: unknown, context: DjustErrorCaptureContext, options?: Pick<DjustSentryMonitoringOptions, "ignoredHttpStatuses"> & {
+    skipIfRetrying?: boolean;
+}): void;
+/**
+ * Creates Transport hooks that report SDK commerce errors to Sentry.
+ * Wire in the host `createDjustClient({ hooks: createDjustSentryHooks(Sentry, opts) })`.
+ */
+export declare function createDjustSentryHooks(sentry: SentryLike, options?: DjustSentryMonitoringOptions): TransportHooks;
+//# sourceMappingURL=sentry.d.ts.map

package/dist/monitoring/sentry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentry.d.ts","sourceRoot":"","sources":["../../src/monitoring/sentry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAGV,cAAc,EACf,MAAM,qBAAqB,CAAC;AAK7B,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IACxE,gBAAgB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAAC;CAC9C;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI,CAAC;IACxD,aAAa,CAAC,UAAU,EAAE;QACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;QACzD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAChC,GAAG,IAAI,CAAC;CACV;AAED,MAAM,WAAW,wBAAwB;IACvC,+DAA+D;IAC/D,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,qEAAqE;IACrE,cAAc,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACpC,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,0DAA0D;IAC1D,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAoBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,wBAAwB,GAChC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0BxB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,wBAAwB,EACjC,OAAO,CAAC,EAAE,IAAI,CAAC,4BAA4B,EAAE,qBAAqB,CAAC,GAAG;IACpE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GACA,IAAI,CAuCN;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,4BAAiC,GACzC,cAAc,CA4ChB"}

package/dist/monitoring/utils.d.ts

@@ -0,0 +1,3 @@
+/** Extracts the pathname from a request URL for monitoring tags. */
+export declare function getEndpoint(url: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/monitoring/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/monitoring/utils.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM/C"}

package/dist/monitoring/w3c-trace.d.ts

@@ -0,0 +1,13 @@
+/**
+ * W3C Trace Context fields ([trace-context](https://www.w3.org/TR/trace-context/)).
+ */
+export interface W3CTraceFields {
+    traceparent?: string;
+    traceId?: string;
+    spanId?: string;
+}
+/**
+ * Parses W3C `traceparent` from outbound SDK request headers.
+ */
+export declare function getW3CTraceFromHeaders(headers: Record<string, string>): W3CTraceFields;
+//# sourceMappingURL=w3c-trace.d.ts.map

package/dist/monitoring/w3c-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"w3c-trace.d.ts","sourceRoot":"","sources":["../../src/monitoring/w3c-trace.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,cAAc,CAoBhB"}

package/dist/settings/sdk-version.d.ts

@@ -1,3 +1,3 @@
 /** Auto-generated by scripts/sync-sdk-version.js — do not edit */
-export declare const SDK_VERSION = "3.0.0";
+export declare const SDK_VERSION = "3.1.0";
 //# sourceMappingURL=sdk-version.d.ts.map