feat(audience): add AudienceError class and onError callback

Adds AudienceError as the public error type on the Audience SDK, along
with an onError callback in AudienceConfig that receives every error
the SDK produces — transport failures, consent sync failures, and any
other async errors from the queue or consent manager.

AudienceError fields:
  - source: 'transport' | 'consent' | 'queue'
  - message: human-readable summary
  - cause: the underlying TransportError or thrown Error
  - status: HTTP status (0 on network failure)
  - endpoint: URL that failed (when applicable)

DebugLogger.logError() routes AudienceError into the same console
output as other debug events, so calling Audience.init with debug: true
surfaces errors without the studio needing to wire onError themselves.

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

Author: ImmutableJeffrey

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

@@ -1,19 +1,23 @@
 import type { Message } from '@imtbl/audience-core';
 import { DebugLogger } from './debug';
 import { LOG_PREFIX } from './config';
+import { AudienceError } from './types';
 
 describe('DebugLogger', () => {
   let logSpy: jest.SpyInstance;
   let warnSpy: jest.SpyInstance;
+  let errorSpy: jest.SpyInstance;
 
   beforeEach(() => {
     logSpy = jest.spyOn(console, 'log').mockImplementation();
     warnSpy = jest.spyOn(console, 'warn').mockImplementation();
+    errorSpy = jest.spyOn(console, 'error').mockImplementation();
   });
 
   afterEach(() => {
     logSpy.mockRestore();
     warnSpy.mockRestore();
+    errorSpy.mockRestore();
   });
 
   const stubMessage: Message = {
@@ -27,15 +31,26 @@ describe('DebugLogger', () => {
     properties: {},
   };
 
+  const stubAudienceError = new AudienceError({
+    code: 'FLUSH_FAILED',
+    message: 'Flush failed with status 500',
+    status: 500,
+    endpoint: 'https://api.sandbox.immutable.com/v1/audience/messages',
+    responseBody: { code: 'INTERNAL_ERROR', detail: 'bad state' },
+    cause: undefined,
+  });
+
   it('should not log when disabled', () => {
     const logger = new DebugLogger(false);
     logger.logEvent('track', stubMessage);
     logger.logFlush(true, 1);
     logger.logConsent('none', 'full');
     logger.logWarning('test');
+    logger.logError(stubAudienceError);
 
     expect(logSpy).not.toHaveBeenCalled();
     expect(warnSpy).not.toHaveBeenCalled();
+    expect(errorSpy).not.toHaveBeenCalled();
   });
 
   it('should log events when enabled', () => {
@@ -90,4 +105,41 @@ describe('DebugLogger', () => {
       `${LOG_PREFIX} something went wrong`,
     );
   });
+
+  it('should log AudienceError with structured context', () => {
+    const logger = new DebugLogger(true);
+    logger.logError(stubAudienceError);
+
+    expect(errorSpy).toHaveBeenCalledWith(
+      `${LOG_PREFIX} AudienceError FLUSH_FAILED: Flush failed with status 500`,
+      {
+        status: 500,
+        endpoint: 'https://api.sandbox.immutable.com/v1/audience/messages',
+        responseBody: { code: 'INTERNAL_ERROR', detail: 'bad state' },
+        cause: undefined,
+      },
+    );
+  });
+
+  it('should log AudienceError with CONSENT_SYNC_FAILED code', () => {
+    const logger = new DebugLogger(true);
+    const consentErr = new AudienceError({
+      code: 'CONSENT_SYNC_FAILED',
+      message: 'Consent sync failed with status 500',
+      status: 500,
+      endpoint: 'https://api.sandbox.immutable.com/v1/audience/tracking-consent',
+      responseBody: { code: 'INTERNAL_ERROR' },
+    });
+
+    logger.logError(consentErr);
+
+    expect(errorSpy).toHaveBeenCalledWith(
+      `${LOG_PREFIX} AudienceError CONSENT_SYNC_FAILED: Consent sync failed with status 500`,
+      expect.objectContaining({
+        status: 500,
+        endpoint: 'https://api.sandbox.immutable.com/v1/audience/tracking-consent',
+        responseBody: { code: 'INTERNAL_ERROR' },
+      }),
+    );
+  });
 });

packages/audience/sdk/src/debug.ts

@@ -1,5 +1,6 @@
 import type { ConsentLevel, Message, TransportError } from '@imtbl/audience-core';
 import { LOG_PREFIX } from './config';
+import type { AudienceError } from './types';
 
 export class DebugLogger {
   private enabled: boolean;
@@ -44,4 +45,18 @@ export class DebugLogger {
     // eslint-disable-next-line no-console
     console.warn(`${LOG_PREFIX} ${msg}`);
   }
+
+  logError(err: AudienceError): void {
+    if (!this.enabled) return;
+    // eslint-disable-next-line no-console
+    console.error(
+      `${LOG_PREFIX} AudienceError ${err.code}: ${err.message}`,
+      {
+        status: err.status,
+        endpoint: err.endpoint,
+        responseBody: err.responseBody,
+        cause: err.cause,
+      },
+    );
+  }
 }

packages/audience/sdk/src/index.ts

@@ -1,4 +1,5 @@
 export { Audience } from './sdk';
 export { IdentityType } from '@imtbl/audience-core';
-export type { AudienceConfig } from './types';
+export { AudienceError } from './types';
+export type { AudienceConfig, AudienceErrorCode } from './types';
 export type { Environment, ConsentLevel, UserTraits } from '@imtbl/audience-core';

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

@@ -23,7 +23,13 @@ const fetchCalls: { url: string; init: RequestInit }[] = [];
 const mockFetch = jest.fn().mockImplementation(
   async (url: string, init?: RequestInit) => {
     fetchCalls.push({ url: url as string, init: init ?? {} });
-    return { ok: true, json: async () => ({}) };
+    return {
+      ok: true,
+      status: 200,
+      headers: { get: () => 'application/json' },
+      json: async () => ({ success: true, accepted: 1, rejected: 0 }),
+      text: async () => '',
+    };
   },
 );
 global.fetch = mockFetch;
@@ -718,6 +724,213 @@ describe('Audience', () => {
     });
   });
 
+  describe('onError callback', () => {
+    // Each test in this block overrides global.fetch with a specific failing mock.
+    // Restore the original mock after each test so later tests (reset, etc.) are
+    // unaffected. Also use real timers so Promise microtasks settle predictably.
+    const savedFetch = global.fetch;
+    beforeEach(() => {
+      jest.useRealTimers();
+    });
+    afterEach(() => {
+      global.fetch = savedFetch;
+      jest.useFakeTimers();
+    });
+
+    function mockFailingFetch(status: number, body: unknown) {
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: false,
+        status,
+        headers: {
+          get: (name: string) => (name.toLowerCase() === 'content-type' ? 'application/json' : null),
+        },
+        json: async () => body,
+        text: async () => JSON.stringify(body),
+      } as unknown as Response);
+    }
+
+    function mockNetworkError(err: Error) {
+      global.fetch = jest.fn().mockRejectedValue(err);
+    }
+
+    it('calls onError with FLUSH_FAILED on 400', async () => {
+      mockFailingFetch(400, { code: 'VALIDATION_ERROR', message: 'invalid identityType' });
+      const onError = jest.fn();
+      const sdk = createSDK({ consent: 'anonymous', onError });
+
+      sdk.track('invalid_event');
+      await sdk.flush();
+
+      expect(onError).toHaveBeenCalledTimes(1);
+      const err = onError.mock.calls[0][0];
+      expect(err.code).toBe('FLUSH_FAILED');
+      expect(err.status).toBe(400);
+      expect(err.responseBody).toEqual({ code: 'VALIDATION_ERROR', message: 'invalid identityType' });
+      expect(err).toBeInstanceOf(Error);
+
+      sdk.shutdown();
+    });
+
+    it('calls onError with NETWORK_ERROR on fetch rejection', async () => {
+      mockNetworkError(new TypeError('Failed to fetch'));
+      const onError = jest.fn();
+      const sdk = createSDK({ consent: 'anonymous', onError });
+
+      sdk.track('offline_event');
+      await sdk.flush();
+
+      expect(onError).toHaveBeenCalledTimes(1);
+      const err = onError.mock.calls[0][0];
+      expect(err.code).toBe('NETWORK_ERROR');
+      expect(err.status).toBe(0);
+      expect(err.cause).toBeInstanceOf(TypeError);
+
+      sdk.shutdown();
+    });
+
+    it('calls onError with CONSENT_SYNC_FAILED on consent PUT 500', async () => {
+      mockFailingFetch(500, { code: 'INTERNAL_ERROR' });
+      const onError = jest.fn();
+      const sdk = createSDK({ consent: 'none', onError });
+
+      sdk.setConsent('anonymous');
+
+      // consent PUT is fire-and-forget; wait for microtasks to settle.
+      // The chain is: fetch → parseBody → httpSend returns → .then → onConsentError
+      // Each await in an async function is at least one microtask tick.
+      for (let i = 0; i < 10; i += 1) {
+        // eslint-disable-next-line no-await-in-loop
+        await Promise.resolve();
+      }
+
+      expect(onError).toHaveBeenCalled();
+      const err = onError.mock.calls.find(
+        (call: any[]) => call[0].code === 'CONSENT_SYNC_FAILED',
+      );
+      expect(err).toBeDefined();
+      expect(err![0].status).toBe(500);
+
+      sdk.shutdown();
+    });
+
+    it('swallows errors thrown by the onError callback', async () => {
+      mockFailingFetch(400, null);
+      const throwingCallback = jest.fn().mockImplementation(() => {
+        throw new Error('handler boom');
+      });
+      const sdk = createSDK({ consent: 'anonymous', onError: throwingCallback });
+
+      sdk.track('will_fail');
+      // Must not throw — SDK error handling must be resilient.
+      await expect(sdk.flush()).resolves.toBeUndefined();
+
+      expect(throwingCallback).toHaveBeenCalled();
+
+      sdk.shutdown();
+    });
+
+    it('does not call onError on success', async () => {
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        headers: {
+          get: () => 'application/json',
+        },
+        json: async () => ({ success: true, accepted: 1, rejected: 0 }),
+        text: async () => '',
+      } as unknown as Response);
+
+      const onError = jest.fn();
+      const sdk = createSDK({ consent: 'anonymous', onError });
+
+      sdk.track('ok_event');
+      await sdk.flush();
+
+      expect(onError).not.toHaveBeenCalled();
+
+      sdk.shutdown();
+    });
+
+    it('logs FLUSH_FAILED errors to console when debug is enabled', async () => {
+      mockFailingFetch(500, { code: 'INTERNAL_ERROR' });
+      const errorSpy = jest.spyOn(console, 'error').mockImplementation();
+      const logSpy = jest.spyOn(console, 'log').mockImplementation();
+      try {
+        const sdk = createSDK({ consent: 'anonymous', debug: true });
+
+        sdk.track('will_fail');
+        await sdk.flush();
+
+        const errorCall = errorSpy.mock.calls.find(
+          (call) => typeof call[0] === 'string'
+            && call[0].includes('AudienceError FLUSH_FAILED'),
+        );
+        expect(errorCall).toBeDefined();
+        expect(errorCall![1]).toMatchObject({
+          status: 500,
+          responseBody: { code: 'INTERNAL_ERROR' },
+        });
+
+        sdk.shutdown();
+      } finally {
+        errorSpy.mockRestore();
+        logSpy.mockRestore();
+      }
+    });
+
+    it('logs CONSENT_SYNC_FAILED errors to console when debug is enabled', async () => {
+      mockFailingFetch(500, { code: 'INTERNAL_ERROR' });
+      const errorSpy = jest.spyOn(console, 'error').mockImplementation();
+      const logSpy = jest.spyOn(console, 'log').mockImplementation();
+      try {
+        const sdk = createSDK({ consent: 'none', debug: true });
+
+        sdk.setConsent('anonymous');
+
+        // consent PUT is fire-and-forget; drain microtasks so .then() runs.
+        for (let i = 0; i < 10; i += 1) {
+          // eslint-disable-next-line no-await-in-loop
+          await Promise.resolve();
+        }
+
+        const errorCall = errorSpy.mock.calls.find(
+          (call) => typeof call[0] === 'string'
+            && call[0].includes('AudienceError CONSENT_SYNC_FAILED'),
+        );
+        expect(errorCall).toBeDefined();
+        expect(errorCall![1]).toMatchObject({
+          status: 500,
+        });
+
+        sdk.shutdown();
+      } finally {
+        errorSpy.mockRestore();
+        logSpy.mockRestore();
+      }
+    });
+
+    it('does not log AudienceError to console when debug is disabled', async () => {
+      mockFailingFetch(500, { code: 'INTERNAL_ERROR' });
+      const errorSpy = jest.spyOn(console, 'error').mockImplementation();
+      try {
+        const sdk = createSDK({ consent: 'anonymous', debug: false });
+
+        sdk.track('will_fail');
+        await sdk.flush();
+
+        const errorCall = errorSpy.mock.calls.find(
+          (call) => typeof call[0] === 'string'
+            && call[0].includes('AudienceError'),
+        );
+        expect(errorCall).toBeUndefined();
+
+        sdk.shutdown();
+      } finally {
+        errorSpy.mockRestore();
+      }
+    });
+  });
+
   describe('reset', () => {
     it('clears pending messages from the queue', async () => {
       const sdk = createSDK({ consent: 'full' });