feat(audience): wire onError callback from AudienceConfig through to core

Exposes AudienceError to web SDK consumers. The core queue and consent
manager already accept an onError callback and map TransportError to a
public AudienceError via toAudienceError; this commit just forwards
AudienceConfig.onError into both positional slots in the Audience
constructor, which were previously hard-coded to undefined.

Also re-exports AudienceError (runtime) and AudienceErrorCode (type)
from the @imtbl/audience package index so ESM consumers can import
the error type they need for their onError handler. CDN consumers
already have it via window.ImmutableAudience.AudienceError from the
CDN bundle work in #2853.

Two new sdk.test.ts tests cover the wire-through end-to-end: a flush
failure against a mocked backend, and a consent sync failure against
a mocked backend. Both verify the AudienceError shape (name, code,
status, endpoint) rather than just that the callback fires.

Refs SDK-49

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

Author: ImmutableJeffrey

packages/audience/sdk/src/index.ts

@@ -1,8 +1,14 @@
 export { Audience } from './sdk';
 export { AudienceEvents } from './events';
-export { IdentityType, canTrack, canIdentify } from '@imtbl/audience-core';
+export {
+  IdentityType,
+  canTrack,
+  canIdentify,
+  AudienceError,
+} from '@imtbl/audience-core';
 export type { ImmutableAudienceGlobal } from './cdn';
 export type { AudienceConfig } from './types';
+export type { AudienceErrorCode } from '@imtbl/audience-core';
 export type {
   AudienceEventName,
   EmailAcquiredProperties,

packages/audience/sdk/src/sdk.test.ts

@@ -905,4 +905,65 @@ describe('Audience', () => {
       sdk.shutdown();
     });
   });
+
+  describe('onError wire-through', () => {
+    it('invokes config.onError with an AudienceError when a flush fails', async () => {
+      mockFetch.mockImplementationOnce(
+        async (url: string, init?: RequestInit) => {
+          fetchCalls.push({ url, init: init ?? {} });
+          return { ok: false, status: 500, json: async () => ({}) };
+        },
+      );
+
+      const errors: any[] = [];
+      const sdk = createSDK({
+        consent: 'anonymous',
+        onError: (err: any) => errors.push(err),
+      });
+
+      sdk.page();
+      await sdk.flush();
+
+      expect(errors).toHaveLength(1);
+      expect(errors[0].name).toBe('AudienceError');
+      expect(errors[0].code).toBe('FLUSH_FAILED');
+      expect(errors[0].status).toBe(500);
+      expect(errors[0].endpoint).toContain(INGEST_PATH);
+
+      sdk.shutdown();
+    });
+
+    it('invokes config.onError with an AudienceError when consent sync fails', async () => {
+      mockFetch.mockImplementation(
+        async (url: string, init?: RequestInit) => {
+          fetchCalls.push({ url, init: init ?? {} });
+          if (url.includes(CONSENT_PATH)) {
+            return { ok: false, status: 503, json: async () => ({}) };
+          }
+          return { ok: true, json: async () => ({}) };
+        },
+      );
+
+      const errors: any[] = [];
+      const sdk = createSDK({
+        consent: 'none',
+        onError: (err: any) => errors.push(err),
+      });
+
+      sdk.setConsent('anonymous');
+
+      // Yield for the fire-and-forget consent PUT to resolve
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(errors).toHaveLength(1);
+      expect(errors[0].name).toBe('AudienceError');
+      expect(errors[0].code).toBe('CONSENT_SYNC_FAILED');
+      expect(errors[0].status).toBe(503);
+      expect(errors[0].endpoint).toContain(CONSENT_PATH);
+
+      sdk.shutdown();
+    });
+  });
 });

packages/audience/sdk/src/sdk.ts

@@ -93,6 +93,7 @@ export class Audience {
         flushIntervalMs: config.flushInterval,
         flushSize: config.flushSize,
         onFlush: (ok, count) => this.debug.logFlush(ok, count),
+        onError: config.onError,
         staleFilter: (m) => isTimestampValid(m.eventTimestamp),
         storagePrefix: '__imtbl_web_',
       },
@@ -105,7 +106,7 @@ export class Audience {
       this.anonymousId,
       consentSource,
       consentLevel,
-      undefined,
+      config.onError,
       config.baseUrl,
     );
 

packages/audience/sdk/src/types.ts

@@ -1,4 +1,4 @@
-import type { ConsentLevel } from '@imtbl/audience-core';
+import type { AudienceError, ConsentLevel } from '@imtbl/audience-core';
 
 /** Configuration for the Immutable Web SDK. */
 export interface AudienceConfig {
@@ -16,4 +16,12 @@ export interface AudienceConfig {
   flushSize?: number;
   /** Override the default API base URL. */
   baseUrl?: string;
+  /**
+   * Called when the SDK fails to reach the backend. Receives a structured
+   * {@link AudienceError} with a machine-readable `code` so studios can
+   * branch on the failure mode (FLUSH_FAILED, CONSENT_SYNC_FAILED,
+   * NETWORK_ERROR, VALIDATION_REJECTED). Exceptions thrown from this
+   * callback are swallowed so a bad handler can't wedge the SDK.
+   */
+  onError?: (err: AudienceError) => void;
 }