@trillboards/ads-sdk 2.0.0 → 2.1.1

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to `@trillboards/ads-sdk` will be documented in this file.
 
+## [2.1.1] - 2026-02-15
+
+### Fixes
+- **Exports map**: Fixed `package.json` exports — `import` now correctly resolves to `.mjs`/`.d.mts` and `require` to `.js`/`.d.ts` (matches actual tsup output)
+- **204 handling**: `fetchWithAuth` no longer throws `SyntaxError` on HTTP 204 No Content responses (affects `CreativeClient.block()` and `unblock()`)
+- **Browser debug mode**: `debug: true` in `TrillboardsConfig` now correctly activates the logger (was a no-op in v2.1.0)
+- **Error `instanceof`**: Added `Object.setPrototypeOf` to `TrillboardsError` base class for correct `instanceof` checks in transpiled environments
+
+## [2.1.0] - 2026-02-15
+
+### Features
+- **CLI setup wizard**: `npx @trillboards/ads-sdk init` — registers account, creates first device, saves API key to `.env` in 30 seconds
+- **Structured errors**: `TrillboardsError`, `TrillboardsAuthenticationError`, `TrillboardsRateLimitError`, `TrillboardsNotFoundError`, `TrillboardsValidationError` — all errors include `code`, `statusCode`, `type`, and `help` fields
+- **Debug mode**: Set `debug: true` in config or `TRILLBOARDS_DEBUG=true` env var to log all API requests with timing
+- **Environment variable auto-detection**: `PartnerClient` reads `TRILLBOARDS_API_KEY` from env — no need to pass in code
+- **`PartnerClient.quickStart()`**: Static method for one-call registration + device creation + pre-authenticated client
+- **Test mode detection**: `client.isTestMode` returns `true` when using a test API key (`trb_test_*`)
+
+### Improvements
+- Error messages now include actionable help text and links to docs
+- All API errors parsed from JSON response body with `type`, `code`, `message`, `param` fields
+- Debug logger prefixed with `[Trillboards]` for easy filtering
+
 ## [2.0.0] - 2026-02-14
 
 ### Breaking Changes

package/README.md

@@ -14,6 +14,24 @@ npm install @trillboards/ads-sdk
 
 ## Quick Start
 
+### Fastest: One-command setup
+
+```bash
+npx @trillboards/ads-sdk init
+```
+
+This registers your account, creates your first device, and saves your API key to `.env`. Zero configuration.
+
+### Server (Node.js with env var)
+
+```typescript
+import { PartnerClient } from '@trillboards/ads-sdk/server';
+
+// Reads TRILLBOARDS_API_KEY from environment automatically
+const client = new PartnerClient();
+const audience = await client.audience.getLive('screen-id');
+```
+
 ### Browser (core)
 
 ```typescript
@@ -75,6 +93,53 @@ The `TrillboardsConfig` interface accepts the following options:
 | `refreshInterval` | `number` | `120000` | Ad refresh interval (ms) |
 | `cacheSize` | `number` | `10` | Max cached ads |
 
+## Debug Mode
+
+Enable debug logging to see all API requests, state transitions, and cache operations:
+
+```typescript
+// Browser
+const sdk = await TrillboardsAds.create({ deviceId: 'xxx', debug: true });
+
+// Server
+const client = new PartnerClient({ debug: true });
+```
+
+Or set the environment variable:
+
+```bash
+TRILLBOARDS_DEBUG=true
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `TRILLBOARDS_API_KEY` | API key for `PartnerClient` (avoids passing in code) |
+| `TRILLBOARDS_DEBUG` | Set to `true` to enable debug logging |
+
+## Error Handling
+
+The SDK throws typed errors that match the API error format:
+
+```typescript
+import {
+  TrillboardsAuthenticationError,
+  TrillboardsRateLimitError,
+} from '@trillboards/ads-sdk/server';
+
+try {
+  const audience = await client.audience.getLive('screen-id');
+} catch (error) {
+  if (error instanceof TrillboardsAuthenticationError) {
+    console.log('Bad API key:', error.message);
+    console.log('Help:', error.help);
+  } else if (error instanceof TrillboardsRateLimitError) {
+    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
+  }
+}
+```
+
 ## Events
 
 The SDK emits typed events via the `EventMap` interface. Subscribe with `sdk.on(event, listener)` or `sdk.once(event, listener)`.

package/dist/cli.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+'use strict';
+
+var readline = require('readline');
+var fs = require('fs');
+var path = require('path');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var readline__namespace = /*#__PURE__*/_interopNamespace(readline);
+var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
+var path__namespace = /*#__PURE__*/_interopNamespace(path);
+
+// src/core/config.ts
+var SDK_VERSION = "2.1.1";
+
+// src/cli.ts
+var BANNER = `
+  _____ ___ ___ _    _    ___  ___   _   ___ ___  ___
+ |_   _| _ \\_ _| |  | |  | _ )/ _ \\ /_\\ | _ \\   \\/ __|
+   | | |   /| || |__| |__| _ \\ (_) / _ \\|   / |) \\__ \\
+   |_| |_|_\\___|____|____|___/\\___/_/ \\_\\_|_\\___/|___/
+
+   Turn any screen into ad revenue in 30 seconds
+`;
+var API_BASE = "https://api.trillboards.com/v1";
+function prompt(rl, question) {
+  return new Promise((resolve2) => {
+    rl.question(question, (answer) => resolve2(answer.trim()));
+  });
+}
+async function callQuickStart(companyName, email) {
+  const response = await fetch(`${API_BASE}/partner/quick-start`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      company_name: companyName,
+      email
+    }),
+    signal: AbortSignal.timeout(3e4)
+  });
+  const json = await response.json();
+  if (!response.ok) {
+    const msg = json?.error?.message ?? json?.message ?? `HTTP ${response.status}`;
+    throw new Error(msg);
+  }
+  return json.data;
+}
+function appendToEnvFile(apiKey) {
+  const envPath = path__namespace.resolve(process.cwd(), ".env");
+  const line = `TRILLBOARDS_API_KEY=${apiKey}
+`;
+  if (fs__namespace.existsSync(envPath)) {
+    const content = fs__namespace.readFileSync(envPath, "utf-8");
+    if (content.includes("TRILLBOARDS_API_KEY=")) {
+      const updated = content.replace(/^TRILLBOARDS_API_KEY=.*$/m, `TRILLBOARDS_API_KEY=${apiKey}`);
+      fs__namespace.writeFileSync(envPath, updated);
+    } else {
+      const separator = content.endsWith("\n") ? "" : "\n";
+      fs__namespace.appendFileSync(envPath, `${separator}${line}`);
+    }
+  } else {
+    fs__namespace.writeFileSync(envPath, line);
+  }
+}
+async function runInit() {
+  console.log(BANNER);
+  let completed = false;
+  const rl = readline__namespace.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  rl.on("close", () => {
+    if (!completed) {
+      console.log("\nAborted.");
+      process.exit(0);
+    }
+  });
+  try {
+    const companyName = await prompt(rl, "  Company name: ");
+    if (!companyName) {
+      console.error("\n  Error: Company name is required.");
+      process.exit(1);
+    }
+    const email = await prompt(rl, "  Email: ");
+    if (!email || !email.includes("@")) {
+      console.error("\n  Error: A valid email is required.");
+      process.exit(1);
+    }
+    console.log("\n  Registering...\n");
+    const data = await callQuickStart(companyName, email);
+    appendToEnvFile(data.credentials.api_key);
+    const keyPreview = data.credentials.api_key_prefix;
+    const fingerprint = data.device.fingerprint;
+    const embedUrl = data.device.embed_url;
+    console.log(`  Your API Key:    ${keyPreview}`);
+    console.log(`  Device ID:       ${fingerprint}`);
+    console.log(`  Embed URL:       ${embedUrl}`);
+    console.log("");
+    console.log("  API key saved to .env");
+    console.log("");
+    console.log("  Quick integration:");
+    console.log("");
+    console.log("    // Node.js / server");
+    console.log("    import { PartnerClient } from '@trillboards/ads-sdk/server';");
+    console.log("    const client = new PartnerClient(); // reads from TRILLBOARDS_API_KEY");
+    console.log("");
+    console.log("    // Browser \u2014 paste in your HTML");
+    console.log(`    <iframe src="${embedUrl}" style="width:100%;height:100%;border:none;" allow="autoplay; fullscreen" allowfullscreen></iframe>`);
+    console.log("");
+    console.log("  Next steps:");
+    console.log("    1. Register more devices: POST /v1/partner/device");
+    console.log("    2. Connect Stripe for payouts: POST /v1/partner/stripe/connect");
+    console.log("    3. Read the docs: https://trillboards.com/developers");
+    console.log("");
+    completed = true;
+  } catch (err) {
+    console.error(`
+  Error: ${err.message}
+`);
+    process.exit(1);
+  } finally {
+    rl.close();
+  }
+}
+var args = process.argv.slice(2);
+if (args.includes("--version") || args.includes("-v")) {
+  console.log(SDK_VERSION);
+  process.exit(0);
+}
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`
+  @trillboards/ads-sdk v${SDK_VERSION}
+
+  Usage:
+    npx @trillboards/ads-sdk init    Register and set up your first device
+    npx @trillboards/ads-sdk --version
+    npx @trillboards/ads-sdk --help
+`);
+  process.exit(0);
+}
+runInit();

package/dist/index.d.mts

@@ -13,6 +13,7 @@ interface TrillboardsConfig {
     programmaticRetry?: number;
     programmaticBackoffMax?: number;
     cacheSize?: number;
+    debug?: boolean;
 }
 type WaterfallMode = 'programmatic_only' | 'programmatic_then_direct' | 'direct_only';
 interface AdItem {
@@ -316,7 +317,7 @@ declare class EventEmitter {
 }
 
 /** Single source of truth for the SDK version string. */
-declare const SDK_VERSION = "2.0.0";
+declare const SDK_VERSION = "2.1.1";
 /**
  * Compile-time constants that mirror the original IIFE CONFIG
  * object. Every value here acts as a sensible production default
@@ -335,7 +336,7 @@ declare const DEFAULT_CONFIG: {
     readonly PROGRAMMATIC_MIN_INTERVAL_MS: 5000;
     readonly PROGRAMMATIC_RETRY_MS: 5000;
     readonly PROGRAMMATIC_BACKOFF_MAX_MS: number;
-    readonly VERSION: "2.0.0";
+    readonly VERSION: "2.1.1";
 };
 /**
  * Merge a caller-supplied TrillboardsConfig with the defaults,
@@ -360,6 +361,7 @@ declare function resolveConfig(userConfig: TrillboardsConfig): {
     readonly programmaticRetry: number;
     readonly programmaticBackoffMax: number;
     readonly cacheSize: number;
+    readonly debug: boolean;
 };
 
 /**
@@ -599,4 +601,55 @@ declare class ApiClient {
     }): Promise<boolean>;
 }
 
-export { type AdItem, ApiClient, type AuctionWinner, type BridgeConfig, type BridgePayload, type BridgeType, CircuitBreaker, type CircuitBreakerState, DEFAULT_CONFIG, DEFAULT_PUBLIC_STATE, EventEmitter, type EventMap, type FetchAdsResult, type ImpressionData, type PlayerTruth, type ProgrammaticSettings, SDK_VERSION, type ScreenDimensions, Telemetry, type TelemetrySnapshot, TrillboardsAds, type TrillboardsConfig, type TrillboardsState, type VastSource, WaterfallEngine, type WaterfallMode, createInitialState, getPublicState, resolveConfig };
+/**
+ * Base error class for all Trillboards SDK errors.
+ * Mirrors the API error response shape: `{ type, code, message, param, help }`.
+ */
+declare class TrillboardsError extends Error {
+    readonly type: string;
+    readonly code: string;
+    readonly statusCode: number;
+    readonly help?: string;
+    readonly param?: string;
+    constructor(message: string, options?: {
+        type?: string;
+        code?: string;
+        statusCode?: number;
+        help?: string;
+        param?: string;
+    });
+}
+/** Thrown on HTTP 401 — invalid or missing API key. */
+declare class TrillboardsAuthenticationError extends TrillboardsError {
+    constructor(message?: string);
+}
+/** Thrown on HTTP 429 — rate limit exceeded. */
+declare class TrillboardsRateLimitError extends TrillboardsError {
+    readonly retryAfter: number;
+    constructor(retryAfter: number, message?: string);
+}
+/** Thrown on HTTP 404 — resource not found. */
+declare class TrillboardsNotFoundError extends TrillboardsError {
+    constructor(message?: string);
+}
+/** Thrown on HTTP 400 — validation / bad request. */
+declare class TrillboardsValidationError extends TrillboardsError {
+    constructor(message?: string, param?: string);
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+declare class Logger {
+    private level;
+    setLevel(level: LogLevel): void;
+    getLevel(): LogLevel;
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+/** Singleton logger instance shared across the SDK. */
+declare const logger: Logger;
+/** Set the global log level for the SDK. */
+declare function setLogLevel(level: LogLevel): void;
+
+export { type AdItem, ApiClient, type AuctionWinner, type BridgeConfig, type BridgePayload, type BridgeType, CircuitBreaker, type CircuitBreakerState, DEFAULT_CONFIG, DEFAULT_PUBLIC_STATE, EventEmitter, type EventMap, type FetchAdsResult, type ImpressionData, type LogLevel, type PlayerTruth, type ProgrammaticSettings, SDK_VERSION, type ScreenDimensions, Telemetry, type TelemetrySnapshot, TrillboardsAds, TrillboardsAuthenticationError, type TrillboardsConfig, TrillboardsError, TrillboardsNotFoundError, TrillboardsRateLimitError, type TrillboardsState, TrillboardsValidationError, type VastSource, WaterfallEngine, type WaterfallMode, createInitialState, getPublicState, logger, resolveConfig, setLogLevel };

package/dist/index.d.ts

@@ -13,6 +13,7 @@ interface TrillboardsConfig {
     programmaticRetry?: number;
     programmaticBackoffMax?: number;
     cacheSize?: number;
+    debug?: boolean;
 }
 type WaterfallMode = 'programmatic_only' | 'programmatic_then_direct' | 'direct_only';
 interface AdItem {
@@ -316,7 +317,7 @@ declare class EventEmitter {
 }
 
 /** Single source of truth for the SDK version string. */
-declare const SDK_VERSION = "2.0.0";
+declare const SDK_VERSION = "2.1.1";
 /**
  * Compile-time constants that mirror the original IIFE CONFIG
  * object. Every value here acts as a sensible production default
@@ -335,7 +336,7 @@ declare const DEFAULT_CONFIG: {
     readonly PROGRAMMATIC_MIN_INTERVAL_MS: 5000;
     readonly PROGRAMMATIC_RETRY_MS: 5000;
     readonly PROGRAMMATIC_BACKOFF_MAX_MS: number;
-    readonly VERSION: "2.0.0";
+    readonly VERSION: "2.1.1";
 };
 /**
  * Merge a caller-supplied TrillboardsConfig with the defaults,
@@ -360,6 +361,7 @@ declare function resolveConfig(userConfig: TrillboardsConfig): {
     readonly programmaticRetry: number;
     readonly programmaticBackoffMax: number;
     readonly cacheSize: number;
+    readonly debug: boolean;
 };
 
 /**
@@ -599,4 +601,55 @@ declare class ApiClient {
     }): Promise<boolean>;
 }
 
-export { type AdItem, ApiClient, type AuctionWinner, type BridgeConfig, type BridgePayload, type BridgeType, CircuitBreaker, type CircuitBreakerState, DEFAULT_CONFIG, DEFAULT_PUBLIC_STATE, EventEmitter, type EventMap, type FetchAdsResult, type ImpressionData, type PlayerTruth, type ProgrammaticSettings, SDK_VERSION, type ScreenDimensions, Telemetry, type TelemetrySnapshot, TrillboardsAds, type TrillboardsConfig, type TrillboardsState, type VastSource, WaterfallEngine, type WaterfallMode, createInitialState, getPublicState, resolveConfig };
+/**
+ * Base error class for all Trillboards SDK errors.
+ * Mirrors the API error response shape: `{ type, code, message, param, help }`.
+ */
+declare class TrillboardsError extends Error {
+    readonly type: string;
+    readonly code: string;
+    readonly statusCode: number;
+    readonly help?: string;
+    readonly param?: string;
+    constructor(message: string, options?: {
+        type?: string;
+        code?: string;
+        statusCode?: number;
+        help?: string;
+        param?: string;
+    });
+}
+/** Thrown on HTTP 401 — invalid or missing API key. */
+declare class TrillboardsAuthenticationError extends TrillboardsError {
+    constructor(message?: string);
+}
+/** Thrown on HTTP 429 — rate limit exceeded. */
+declare class TrillboardsRateLimitError extends TrillboardsError {
+    readonly retryAfter: number;
+    constructor(retryAfter: number, message?: string);
+}
+/** Thrown on HTTP 404 — resource not found. */
+declare class TrillboardsNotFoundError extends TrillboardsError {
+    constructor(message?: string);
+}
+/** Thrown on HTTP 400 — validation / bad request. */
+declare class TrillboardsValidationError extends TrillboardsError {
+    constructor(message?: string, param?: string);
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+declare class Logger {
+    private level;
+    setLevel(level: LogLevel): void;
+    getLevel(): LogLevel;
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+/** Singleton logger instance shared across the SDK. */
+declare const logger: Logger;
+/** Set the global log level for the SDK. */
+declare function setLogLevel(level: LogLevel): void;
+
+export { type AdItem, ApiClient, type AuctionWinner, type BridgeConfig, type BridgePayload, type BridgeType, CircuitBreaker, type CircuitBreakerState, DEFAULT_CONFIG, DEFAULT_PUBLIC_STATE, EventEmitter, type EventMap, type FetchAdsResult, type ImpressionData, type LogLevel, type PlayerTruth, type ProgrammaticSettings, SDK_VERSION, type ScreenDimensions, Telemetry, type TelemetrySnapshot, TrillboardsAds, TrillboardsAuthenticationError, type TrillboardsConfig, TrillboardsError, TrillboardsNotFoundError, TrillboardsRateLimitError, type TrillboardsState, TrillboardsValidationError, type VastSource, WaterfallEngine, type WaterfallMode, createInitialState, getPublicState, logger, resolveConfig, setLogLevel };

package/dist/index.js

@@ -1,7 +1,7 @@
 'use strict';
 
 // src/core/config.ts
-var SDK_VERSION = "2.0.0";
+var SDK_VERSION = "2.1.1";
 var DEFAULT_CONFIG = {
   API_BASE: "https://api.trillboards.com/v1/partner",
   CDN_BASE: "https://cdn.trillboards.com",
@@ -44,7 +44,8 @@ function resolveConfig(userConfig) {
     programmaticMinInterval: Math.max(userConfig.programmaticMinInterval ?? DEFAULT_CONFIG.PROGRAMMATIC_MIN_INTERVAL_MS, 1e3),
     programmaticRetry: Math.max(userConfig.programmaticRetry ?? DEFAULT_CONFIG.PROGRAMMATIC_RETRY_MS, 1e3),
     programmaticBackoffMax: Math.max(userConfig.programmaticBackoffMax ?? DEFAULT_CONFIG.PROGRAMMATIC_BACKOFF_MAX_MS, 5e3),
-    cacheSize: Math.max(userConfig.cacheSize ?? DEFAULT_CONFIG.CACHE_SIZE, 1)
+    cacheSize: Math.max(userConfig.cacheSize ?? DEFAULT_CONFIG.CACHE_SIZE, 1),
+    debug: userConfig.debug ?? false
   };
 }
 
@@ -171,6 +172,67 @@ var EventEmitter = class {
   }
 };
 
+// src/logger.ts
+var LEVEL_PRIORITY = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  none: 4
+};
+var PREFIX = "[Trillboards]";
+var Logger = class {
+  constructor() {
+    this.level = "none";
+  }
+  setLevel(level) {
+    this.level = level;
+  }
+  getLevel() {
+    return this.level;
+  }
+  debug(message, data) {
+    if (LEVEL_PRIORITY[this.level] <= LEVEL_PRIORITY.debug) {
+      if (data !== void 0) {
+        console.debug(PREFIX, message, data);
+      } else {
+        console.debug(PREFIX, message);
+      }
+    }
+  }
+  info(message, data) {
+    if (LEVEL_PRIORITY[this.level] <= LEVEL_PRIORITY.info) {
+      if (data !== void 0) {
+        console.info(PREFIX, message, data);
+      } else {
+        console.info(PREFIX, message);
+      }
+    }
+  }
+  warn(message, data) {
+    if (LEVEL_PRIORITY[this.level] <= LEVEL_PRIORITY.warn) {
+      if (data !== void 0) {
+        console.warn(PREFIX, message, data);
+      } else {
+        console.warn(PREFIX, message);
+      }
+    }
+  }
+  error(message, data) {
+    if (LEVEL_PRIORITY[this.level] <= LEVEL_PRIORITY.error) {
+      if (data !== void 0) {
+        console.error(PREFIX, message, data);
+      } else {
+        console.error(PREFIX, message);
+      }
+    }
+  }
+};
+var logger = new Logger();
+function setLogLevel(level) {
+  logger.setLevel(level);
+}
+
 // src/api/client.ts
 function getPlayerTruth(container) {
   if (typeof window === "undefined") {
@@ -220,6 +282,7 @@ var ApiClient = class {
    * The request is aborted after 10 seconds.
    */
   async fetchAds(deviceId, etag = null) {
+    logger.debug("Fetching ads", { deviceId });
     const headers = { Accept: "application/json" };
     if (etag) headers["If-None-Match"] = etag;
     const controller = new AbortController();
@@ -254,7 +317,7 @@ var ApiClient = class {
       }
       const data = await response.json();
       const newEtag = response.headers.get("ETag");
-      return {
+      const result = {
         ads: data.data?.ads ?? [],
         settings: data.data?.settings ?? {},
         programmatic: data.data?.header_bidding_settings ?? null,
@@ -264,6 +327,8 @@ var ApiClient = class {
         etag: newEtag,
         notModified: false
       };
+      logger.debug("Ads fetched", { deviceId, count: result.ads.length, notModified: false });
+      return result;
     } catch (error) {
       clearTimeout(timeoutId);
       throw error;
@@ -279,6 +344,7 @@ var ApiClient = class {
    * Returns `true` if the server acknowledged the impression.
    */
   async reportImpression(impression) {
+    logger.debug("Reporting impression", { adId: impression.adid, impressionId: impression.impid });
     try {
       const params = new URLSearchParams({
         adid: impression.adid,
@@ -302,6 +368,7 @@ var ApiClient = class {
    * Returns `true` on 2xx, `false` on any error.
    */
   async sendHeartbeat(deviceId, screenId) {
+    logger.debug("Sending heartbeat", { deviceId });
     try {
       const response = await fetch(`${this.apiBase}/device/${deviceId}/heartbeat`, {
         method: "POST",
@@ -324,6 +391,7 @@ var ApiClient = class {
    * error, etc.) to the analytics backend.
    */
   async reportProgrammaticEvent(event) {
+    logger.debug("Reporting programmatic event", { eventType: event.eventType });
     try {
       const response = await fetch(`${this.apiBase}/programmatic-event`, {
         method: "POST",
@@ -1332,6 +1400,9 @@ var _TrillboardsAds = class _TrillboardsAds {
     this.offlineHandler = null;
     this.visibilityHandler = null;
     this.config = resolveConfig(config);
+    if (this.config.debug) {
+      setLogLevel("debug");
+    }
     this.state = createInitialState();
     this.events = new EventEmitter();
     this.api = new ApiClient(this.config.apiBase);
@@ -1736,6 +1807,76 @@ var _TrillboardsAds = class _TrillboardsAds {
 _TrillboardsAds._instance = null;
 var TrillboardsAds = _TrillboardsAds;
 
+// src/errors.ts
+var TrillboardsError = class extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "TrillboardsError";
+    this.type = options.type ?? "api_error";
+    this.code = options.code ?? "unknown_error";
+    this.statusCode = options.statusCode ?? 500;
+    this.help = options.help;
+    this.param = options.param;
+  }
+};
+var TrillboardsAuthenticationError = class extends TrillboardsError {
+  constructor(message) {
+    super(
+      message ?? "Invalid API key. Check your key at https://trillboards.com/developers",
+      {
+        type: "authentication_error",
+        code: "invalid_api_key",
+        statusCode: 401,
+        help: "https://trillboards.com/developers"
+      }
+    );
+    this.name = "TrillboardsAuthenticationError";
+  }
+};
+var TrillboardsRateLimitError = class extends TrillboardsError {
+  constructor(retryAfter, message) {
+    super(
+      message ?? `Rate limit exceeded. Retry after ${retryAfter} seconds.`,
+      {
+        type: "rate_limit_error",
+        code: "rate_limited",
+        statusCode: 429
+      }
+    );
+    this.name = "TrillboardsRateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var TrillboardsNotFoundError = class extends TrillboardsError {
+  constructor(message) {
+    super(
+      message ?? "The requested resource was not found.",
+      {
+        type: "not_found_error",
+        code: "resource_not_found",
+        statusCode: 404,
+        help: "Verify the ID is correct and belongs to your account."
+      }
+    );
+    this.name = "TrillboardsNotFoundError";
+  }
+};
+var TrillboardsValidationError = class extends TrillboardsError {
+  constructor(message, param) {
+    super(
+      message ?? "The request was invalid.",
+      {
+        type: "validation_error",
+        code: "invalid_request",
+        statusCode: 400,
+        param
+      }
+    );
+    this.name = "TrillboardsValidationError";
+  }
+};
+
 exports.ApiClient = ApiClient;
 exports.CircuitBreaker = CircuitBreaker;
 exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
@@ -1744,9 +1885,16 @@ exports.EventEmitter = EventEmitter;
 exports.SDK_VERSION = SDK_VERSION;
 exports.Telemetry = Telemetry;
 exports.TrillboardsAds = TrillboardsAds;
+exports.TrillboardsAuthenticationError = TrillboardsAuthenticationError;
+exports.TrillboardsError = TrillboardsError;
+exports.TrillboardsNotFoundError = TrillboardsNotFoundError;
+exports.TrillboardsRateLimitError = TrillboardsRateLimitError;
+exports.TrillboardsValidationError = TrillboardsValidationError;
 exports.WaterfallEngine = WaterfallEngine;
 exports.createInitialState = createInitialState;
 exports.getPublicState = getPublicState;
+exports.logger = logger;
 exports.resolveConfig = resolveConfig;
+exports.setLogLevel = setLogLevel;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map