feat(audience-core): add AudienceError + unified onError callback

Move the public error surface into core so every audience surface
(web, pixel, unity, unreal) reports failures through the same shape
without per-package error classes or duplicated mapping logic.

- New AudienceError class in errors.ts: extends Error, carries
  a closed AudienceErrorCode union ('FLUSH_FAILED', 'CONSENT_SYNC_FAILED',
  'NETWORK_ERROR'), plus status / endpoint / responseBody / cause for
  triage. Routable to Sentry / Datadog without an adapter.
- New toAudienceError(err, source, count?) helper that maps a low-level
  TransportError into an AudienceError. Centralised so MessageQueue and
  ConsentManager don't carry duplicate copies of the
  status === 0 → NETWORK_ERROR mapping.
- MessageQueue accepts onError?: (err: AudienceError) => void in its
  options. Fires after onFlush on a failed flush, with errors mapped
  via toAudienceError(_, 'flush', batch.length). onFlush is unchanged
  and stays focused on debug/metrics observability.
- createConsentManager accepts onError?: (err: AudienceError) => void
  as a new optional last parameter. Wires a .then() onto the consent
  PUT so synchronous fire-and-forget behaviour is preserved while
  failures are still observable. Mapped via toAudienceError(_, 'consent').
- Both call sites swallow exceptions thrown from the onError callback —
  the queue and consent state machine must not wedge on a bad handler.

Tests: errors.test.ts covers AudienceError construction and
toAudienceError mapping for all source/error combinations. queue.test.ts
adds four onError tests (mapped FLUSH_FAILED, mapped NETWORK_ERROR with
batch count, no-fire on success, swallows callback exceptions).
consent.test.ts adds the same four tests plus the synchronous-throw
guarantee. 104 core tests pass.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ImmutableJeffrey

packages/audience/core/src/consent.test.ts

@@ -1,7 +1,7 @@
 import { createConsentManager } from './consent';
 import type { HttpSend } from './transport';
 
-function createMockSend(): jest.MockedFunction<HttpSend> {
+function createMockSend() {
   return jest.fn<ReturnType<HttpSend>, Parameters<HttpSend>>().mockResolvedValue({ ok: true });
 }
 
@@ -117,4 +117,85 @@ describe('createConsentManager', () => {
 
     Object.defineProperty(navigator, 'doNotTrack', { value: '0', configurable: true });
   });
+
+  describe('onError callback', () => {
+    it('fires onError with mapped CONSENT_SYNC_FAILED on consent PUT failure', async () => {
+      const queue = createMockQueue();
+      const send = jest.fn<ReturnType<HttpSend>, Parameters<HttpSend>>().mockResolvedValue({
+        ok: false,
+        error: {
+          status: 503,
+          endpoint: 'https://api.dev.immutable.com/v1/audience/tracking-consent',
+          body: { code: 'SERVICE_UNAVAILABLE' },
+        },
+      });
+      const onError = jest.fn();
+      const manager = createConsentManager(queue, send, 'pk_test', 'anon-1', 'dev', 'pixel', 'none', onError);
+
+      manager.setLevel('anonymous');
+
+      // notifyBackend's .then() runs on the microtask queue.
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(onError).toHaveBeenCalledTimes(1);
+      const err = onError.mock.calls[0][0];
+      expect(err.code).toBe('CONSENT_SYNC_FAILED');
+      expect(err.status).toBe(503);
+      expect(err.message).toBe('Consent sync failed with status 503');
+    });
+
+    it('fires onError with NETWORK_ERROR on network failure', async () => {
+      const queue = createMockQueue();
+      const send = jest.fn<ReturnType<HttpSend>, Parameters<HttpSend>>().mockResolvedValue({
+        ok: false,
+        error: {
+          status: 0,
+          endpoint: 'https://api.dev.immutable.com/v1/audience/tracking-consent',
+          cause: new TypeError('Failed to fetch'),
+        },
+      });
+      const onError = jest.fn();
+      const manager = createConsentManager(queue, send, 'pk_test', 'anon-1', 'dev', 'pixel', 'none', onError);
+
+      manager.setLevel('anonymous');
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(onError).toHaveBeenCalledTimes(1);
+      const err = onError.mock.calls[0][0];
+      expect(err.code).toBe('NETWORK_ERROR');
+      expect(err.message).toBe('Network error syncing consent');
+    });
+
+    it('does not fire onError on successful consent sync', async () => {
+      const queue = createMockQueue();
+      const send = createMockSend();
+      const onError = jest.fn();
+      const manager = createConsentManager(queue, send, 'pk_test', 'anon-1', 'dev', 'pixel', 'none', onError);
+
+      manager.setLevel('anonymous');
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(onError).not.toHaveBeenCalled();
+    });
+
+    it('swallows exceptions thrown from the onError callback', async () => {
+      const queue = createMockQueue();
+      const send = jest.fn<ReturnType<HttpSend>, Parameters<HttpSend>>().mockResolvedValue({
+        ok: false,
+        error: { status: 500, endpoint: 'x', body: null },
+      });
+      const onError = jest.fn().mockImplementation(() => { throw new Error('callback boom'); });
+      const manager = createConsentManager(queue, send, 'pk_test', 'anon-1', 'dev', 'pixel', 'none', onError);
+
+      // Synchronous call must not throw even though the .then() handler will.
+      expect(() => manager.setLevel('anonymous')).not.toThrow();
+
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(onError).toHaveBeenCalled();
+    });
+  });
 });

packages/audience/core/src/consent.ts

@@ -3,6 +3,7 @@ import type {
 } from './types';
 import type { MessageQueue } from './queue';
 import type { HttpSend } from './transport';
+import { type AudienceError, toAudienceError } from './errors';
 import { CONSENT_PATH, getBaseUrl } from './config';
 
 export interface ConsentManager {
@@ -29,6 +30,10 @@ export function detectDoNotTrack(): boolean {
  * - Fires PUT to `/v1/audience/tracking-consent` on every state change via
  *   the injected `send`. Sharing the same `HttpSend` instance with the queue
  *   keeps the transport layer uniform — no module-level mocking required.
+ * - On consent sync failure, fires `onError` with a public {@link AudienceError}
+ *   mapped via {@link toAudienceError}, so callers don't have to repeat the
+ *   `status === 0 → NETWORK_ERROR` mapping themselves. Exceptions thrown
+ *   from the callback are swallowed.
  */
 export function createConsentManager(
   queue: MessageQueue,
@@ -38,6 +43,7 @@ export function createConsentManager(
   environment: Environment,
   source: string,
   initialLevel?: ConsentLevel,
+  onError?: (err: AudienceError) => void,
 ): ConsentManager {
   const dntDetected = detectDoNotTrack();
   let current: ConsentLevel = initialLevel ?? (dntDetected ? 'none' : 'none');
@@ -47,8 +53,18 @@ export function createConsentManager(
   function notifyBackend(level: ConsentLevel): void {
     const url = `${getBaseUrl(environment)}${CONSENT_PATH}`;
     const payload: ConsentUpdatePayload = { anonymousId, status: level, source };
-    // Fire-and-forget. HttpSend never rejects, so a floating promise is safe.
-    send(url, publishableKey, payload, { method: 'PUT', keepalive: true });
+    // Fire-and-forget. HttpSend never rejects, so the floating chain is safe.
+    send(url, publishableKey, payload, { method: 'PUT', keepalive: true })
+      .then((result) => {
+        if (!result.ok && result.error && onError) {
+          try {
+            onError(toAudienceError(result.error, 'consent'));
+          } catch {
+            // Swallow callback errors — the consent state machine must not
+            // wedge on a throwing handler.
+          }
+        }
+      });
   }
 
   const manager: ConsentManager = {

packages/audience/core/src/errors.test.ts

@@ -0,0 +1,98 @@
+import {
+  AudienceError, toAudienceError, type TransportError,
+} from './errors';
+
+describe('AudienceError', () => {
+  it('is an instance of Error', () => {
+    const err = new AudienceError({
+      code: 'FLUSH_FAILED',
+      message: 'flush failed',
+      status: 500,
+      endpoint: 'https://example.com',
+    });
+
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(AudienceError);
+    expect(err.name).toBe('AudienceError');
+  });
+
+  it('exposes structured fields from init', () => {
+    const cause = new TypeError('boom');
+    const err = new AudienceError({
+      code: 'NETWORK_ERROR',
+      message: 'network down',
+      status: 0,
+      endpoint: 'https://example.com',
+      responseBody: { detail: 'x' },
+      cause,
+    });
+
+    expect(err.code).toBe('NETWORK_ERROR');
+    expect(err.message).toBe('network down');
+    expect(err.status).toBe(0);
+    expect(err.endpoint).toBe('https://example.com');
+    expect(err.responseBody).toEqual({ detail: 'x' });
+    expect(err.cause).toBe(cause);
+  });
+});
+
+describe('toAudienceError', () => {
+  const httpError: TransportError = {
+    status: 500,
+    endpoint: 'https://api.dev.immutable.com/v1/audience/messages',
+    body: { code: 'INTERNAL_ERROR' },
+  };
+
+  const networkError: TransportError = {
+    status: 0,
+    endpoint: 'https://api.dev.immutable.com/v1/audience/messages',
+    cause: new TypeError('Failed to fetch'),
+  };
+
+  describe('flush source', () => {
+    it('maps HTTP error to FLUSH_FAILED with status in message', () => {
+      const err = toAudienceError(httpError, 'flush', 5);
+
+      expect(err.code).toBe('FLUSH_FAILED');
+      expect(err.message).toBe('Flush failed with status 500');
+      expect(err.status).toBe(500);
+      expect(err.endpoint).toBe(httpError.endpoint);
+      expect(err.responseBody).toEqual({ code: 'INTERNAL_ERROR' });
+    });
+
+    it('maps network error to NETWORK_ERROR with batch count in message', () => {
+      const err = toAudienceError(networkError, 'flush', 5);
+
+      expect(err.code).toBe('NETWORK_ERROR');
+      expect(err.message).toBe('Network error sending 5 messages');
+      expect(err.status).toBe(0);
+      expect(err.cause).toBe(networkError.cause);
+    });
+
+    it('falls back to count 0 in network message when count is undefined', () => {
+      const err = toAudienceError(networkError, 'flush');
+      expect(err.message).toBe('Network error sending 0 messages');
+    });
+  });
+
+  describe('consent source', () => {
+    it('maps HTTP error to CONSENT_SYNC_FAILED with status in message', () => {
+      const err = toAudienceError(
+        { ...httpError, endpoint: 'https://api.dev.immutable.com/v1/audience/tracking-consent' },
+        'consent',
+      );
+
+      expect(err.code).toBe('CONSENT_SYNC_FAILED');
+      expect(err.message).toBe('Consent sync failed with status 500');
+    });
+
+    it('maps network error to NETWORK_ERROR with consent-specific message', () => {
+      const err = toAudienceError(networkError, 'consent');
+
+      expect(err.code).toBe('NETWORK_ERROR');
+      expect(err.message).toBe('Network error syncing consent');
+      expect(err.status).toBe(0);
+      expect(err.cause).toBe(networkError.cause);
+    });
+  });
+});

packages/audience/core/src/errors.ts

@@ -54,3 +54,103 @@ export interface TransportResult {
   ok: boolean;
   error?: TransportError;
 }
+
+/**
+ * Stable, machine-readable code identifying the kind of audience SDK
+ * failure. Studios can branch on this in their `onError` handler.
+ *
+ * - `'FLUSH_FAILED'` — POST to `/v1/audience/messages` returned non-2xx.
+ * - `'CONSENT_SYNC_FAILED'` — PUT to `/v1/audience/tracking-consent` returned non-2xx.
+ * - `'NETWORK_ERROR'` — fetch rejected before a response was received
+ *                       (network failure, CORS, DNS, etc.).
+ */
+export type AudienceErrorCode =
+  | 'FLUSH_FAILED'
+  | 'CONSENT_SYNC_FAILED'
+  | 'NETWORK_ERROR';
+
+/**
+ * Public error type passed to the SDK's `onError` callback. Wraps the
+ * low-level {@link TransportError} and adds a closed `code` union plus a
+ * human-readable `message`.
+ *
+ * Lives in `@imtbl/audience-core` so every surface (web, pixel, unity,
+ * unreal) reports failures through the same shape — no per-package
+ * error class, no duplicated mapping logic.
+ *
+ * Is an instance of `Error` so it can be thrown, logged, or passed to
+ * Sentry / Datadog without an adapter.
+ */
+export class AudienceError extends Error {
+  readonly code: AudienceErrorCode;
+
+  readonly status: number;
+
+  readonly endpoint: string;
+
+  readonly responseBody?: unknown;
+
+  // `cause` is a standard Error prop in ES2022, declared here for older
+  // TS targets that don't have it in their lib.d.ts.
+  readonly cause?: unknown;
+
+  constructor(init: {
+    code: AudienceErrorCode;
+    message: string;
+    status: number;
+    endpoint: string;
+    responseBody?: unknown;
+    cause?: unknown;
+  }) {
+    super(init.message);
+    this.name = 'AudienceError';
+    this.code = init.code;
+    this.status = init.status;
+    this.endpoint = init.endpoint;
+    this.responseBody = init.responseBody;
+    this.cause = init.cause;
+  }
+}
+
+/**
+ * Convert a low-level {@link TransportError} into a public
+ * {@link AudienceError} for delivery to studio code.
+ *
+ * Centralised so MessageQueue and ConsentManager don't each carry their
+ * own copy of `status === 0 → NETWORK_ERROR` mapping logic.
+ *
+ * @param err     The transport-level failure.
+ * @param source  Which subsystem hit the error — selects the error code
+ *                and shapes the human message.
+ * @param count   For `'flush'` failures, the number of messages in the
+ *                batch. Used in the human-readable message; ignored for
+ *                consent failures.
+ */
+export function toAudienceError(
+  err: TransportError,
+  source: 'flush' | 'consent',
+  count?: number,
+): AudienceError {
+  if (err.status === 0) {
+    return new AudienceError({
+      code: 'NETWORK_ERROR',
+      message: source === 'flush'
+        ? `Network error sending ${count ?? 0} messages`
+        : 'Network error syncing consent',
+      status: 0,
+      endpoint: err.endpoint,
+      cause: err.cause,
+    });
+  }
+
+  return new AudienceError({
+    code: source === 'flush' ? 'FLUSH_FAILED' : 'CONSENT_SYNC_FAILED',
+    message: source === 'flush'
+      ? `Flush failed with status ${err.status}`
+      : `Consent sync failed with status ${err.status}`,
+    status: err.status,
+    endpoint: err.endpoint,
+    responseBody: err.body,
+    cause: err.cause,
+  });
+}

packages/audience/core/src/index.ts

@@ -43,7 +43,12 @@ export { generateId, getTimestamp, isBrowser } from './utils';
 
 export type { HttpSend, TransportOptions } from './transport';
 export { httpSend } from './transport';
-export type { TransportError, TransportResult } from './errors';
+export type {
+  TransportError,
+  TransportResult,
+  AudienceErrorCode,
+} from './errors';
+export { AudienceError, toAudienceError } from './errors';
 export { MessageQueue } from './queue';
 export { collectContext } from './context';
 export {