@trillboards/ads-sdk 2.0.0 → 2.1.0

package/dist/server.d.mts

@@ -205,8 +205,43 @@ declare class CreativeClient {
 }
 
 interface PartnerClientConfig {
-    apiKey: string;
+    apiKey?: string;
     apiBase?: string;
+    debug?: boolean;
+}
+interface QuickStartResult {
+    partner: {
+        partner_id: string;
+        name: string;
+        slug: string;
+        status: string;
+        revenue_share_percent: number;
+    };
+    credentials: {
+        api_key: string;
+        api_key_prefix: string;
+        warning: string;
+    };
+    device: {
+        device_id: string;
+        external_device_id: string;
+        fingerprint: string;
+        screen_id: string;
+        name: string;
+        status: string;
+        embed_url: string;
+    };
+    integration: {
+        sdk_snippet: string;
+        iframe_snippet: string;
+        embed_url: string;
+        api_base: string;
+        sdk_url: string;
+        docs_url: string;
+    };
+    sdk_config: Record<string, unknown>;
+    next_steps: string[];
+    client: PartnerClient;
 }
 declare class PartnerClient {
     private apiKey;
@@ -216,7 +251,22 @@ declare class PartnerClient {
     readonly analytics: AnalyticsClient;
     readonly auctions: AuctionClient;
     readonly creatives: CreativeClient;
-    constructor(config: PartnerClientConfig);
+    constructor(config?: PartnerClientConfig);
+    /** Returns `true` if the API key is a test key (`trb_test_*`). */
+    get isTestMode(): boolean;
+    /**
+     * One-call onboarding: register a partner, create the first device,
+     * and return a pre-authenticated `PartnerClient` instance ready to use.
+     *
+     * This calls `POST /v1/partner/quick-start` (public, no auth required).
+     */
+    static quickStart(options: {
+        companyName: string;
+        email: string;
+        deviceName?: string;
+        apiBase?: string;
+        debug?: boolean;
+    }): Promise<QuickStartResult>;
     createVastTagBuilder(): VastTagBuilder;
     createTrackingBatch(): TrackingBatch;
     protected fetch(path: string, options?: RequestInit): Promise<any>;
@@ -231,8 +281,60 @@ declare class PartnerClient {
  *   the caller provides their own `signal`.
  * - Always sends `Authorization: Bearer <key>` and
  *   `Content-Type: application/json`.
- * - Throws on non-2xx responses.
+ * - Throws structured `TrillboardsError` subclasses on non-2xx responses.
+ * - Logs requests and responses when debug logging is active.
  */
 declare function createAuthenticatedFetch(apiKey: string, apiBase: string): (path: string, options?: RequestInit) => Promise<any>;
 
-export { AnalyticsClient, AuctionClient, type AuctionResult, AudienceClient, type AudiencePrediction, type BuildTagOptions, CreativeClient, type CreativeReview, type CreativeStats, type EarningsData, type ImpressionReport, type LiveAudience, type LookalikeScreen, PartnerClient, type PartnerClientConfig, type ScreenDailyAnalytics, TrackingBatch, type TrackingBatchConfig, type TrackingResult, VastTagBuilder, type VastTagBuilderConfig, type VastTagResult, createAuthenticatedFetch };
+/**
+ * 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 { AnalyticsClient, AuctionClient, type AuctionResult, AudienceClient, type AudiencePrediction, type BuildTagOptions, CreativeClient, type CreativeReview, type CreativeStats, type EarningsData, type ImpressionReport, type LiveAudience, type LogLevel, type LookalikeScreen, PartnerClient, type PartnerClientConfig, type QuickStartResult, type ScreenDailyAnalytics, TrackingBatch, type TrackingBatchConfig, type TrackingResult, TrillboardsAuthenticationError, TrillboardsError, TrillboardsNotFoundError, TrillboardsRateLimitError, TrillboardsValidationError, VastTagBuilder, type VastTagBuilderConfig, type VastTagResult, createAuthenticatedFetch, logger, setLogLevel };

package/dist/server.d.ts

@@ -205,8 +205,43 @@ declare class CreativeClient {
 }
 
 interface PartnerClientConfig {
-    apiKey: string;
+    apiKey?: string;
     apiBase?: string;
+    debug?: boolean;
+}
+interface QuickStartResult {
+    partner: {
+        partner_id: string;
+        name: string;
+        slug: string;
+        status: string;
+        revenue_share_percent: number;
+    };
+    credentials: {
+        api_key: string;
+        api_key_prefix: string;
+        warning: string;
+    };
+    device: {
+        device_id: string;
+        external_device_id: string;
+        fingerprint: string;
+        screen_id: string;
+        name: string;
+        status: string;
+        embed_url: string;
+    };
+    integration: {
+        sdk_snippet: string;
+        iframe_snippet: string;
+        embed_url: string;
+        api_base: string;
+        sdk_url: string;
+        docs_url: string;
+    };
+    sdk_config: Record<string, unknown>;
+    next_steps: string[];
+    client: PartnerClient;
 }
 declare class PartnerClient {
     private apiKey;
@@ -216,7 +251,22 @@ declare class PartnerClient {
     readonly analytics: AnalyticsClient;
     readonly auctions: AuctionClient;
     readonly creatives: CreativeClient;
-    constructor(config: PartnerClientConfig);
+    constructor(config?: PartnerClientConfig);
+    /** Returns `true` if the API key is a test key (`trb_test_*`). */
+    get isTestMode(): boolean;
+    /**
+     * One-call onboarding: register a partner, create the first device,
+     * and return a pre-authenticated `PartnerClient` instance ready to use.
+     *
+     * This calls `POST /v1/partner/quick-start` (public, no auth required).
+     */
+    static quickStart(options: {
+        companyName: string;
+        email: string;
+        deviceName?: string;
+        apiBase?: string;
+        debug?: boolean;
+    }): Promise<QuickStartResult>;
     createVastTagBuilder(): VastTagBuilder;
     createTrackingBatch(): TrackingBatch;
     protected fetch(path: string, options?: RequestInit): Promise<any>;
@@ -231,8 +281,60 @@ declare class PartnerClient {
  *   the caller provides their own `signal`.
  * - Always sends `Authorization: Bearer <key>` and
  *   `Content-Type: application/json`.
- * - Throws on non-2xx responses.
+ * - Throws structured `TrillboardsError` subclasses on non-2xx responses.
+ * - Logs requests and responses when debug logging is active.
  */
 declare function createAuthenticatedFetch(apiKey: string, apiBase: string): (path: string, options?: RequestInit) => Promise<any>;
 
-export { AnalyticsClient, AuctionClient, type AuctionResult, AudienceClient, type AudiencePrediction, type BuildTagOptions, CreativeClient, type CreativeReview, type CreativeStats, type EarningsData, type ImpressionReport, type LiveAudience, type LookalikeScreen, PartnerClient, type PartnerClientConfig, type ScreenDailyAnalytics, TrackingBatch, type TrackingBatchConfig, type TrackingResult, VastTagBuilder, type VastTagBuilderConfig, type VastTagResult, createAuthenticatedFetch };
+/**
+ * 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 { AnalyticsClient, AuctionClient, type AuctionResult, AudienceClient, type AudiencePrediction, type BuildTagOptions, CreativeClient, type CreativeReview, type CreativeStats, type EarningsData, type ImpressionReport, type LiveAudience, type LogLevel, type LookalikeScreen, PartnerClient, type PartnerClientConfig, type QuickStartResult, type ScreenDailyAnalytics, TrackingBatch, type TrackingBatchConfig, type TrackingResult, TrillboardsAuthenticationError, TrillboardsError, TrillboardsNotFoundError, TrillboardsRateLimitError, TrillboardsValidationError, VastTagBuilder, type VastTagBuilderConfig, type VastTagResult, createAuthenticatedFetch, logger, setLogLevel };

package/dist/server.js

@@ -1,9 +1,172 @@
 'use strict';
 
+// src/errors.ts
+var TrillboardsError = class extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    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";
+  }
+};
+
+// 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/server/fetchWithAuth.ts
+async function errorFromResponse(response, path) {
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+  }
+  const apiError = body?.error ?? body;
+  const msg = apiError?.message ?? `API error: HTTP ${response.status}`;
+  switch (response.status) {
+    case 401:
+      return new TrillboardsAuthenticationError(msg);
+    case 429: {
+      const retryHeader = response.headers.get("retry-after");
+      const retryAfter = retryHeader ? parseInt(retryHeader, 10) : 60;
+      return new TrillboardsRateLimitError(isNaN(retryAfter) ? 60 : retryAfter, msg);
+    }
+    case 404:
+      return new TrillboardsNotFoundError(msg);
+    case 400:
+      return new TrillboardsValidationError(msg, apiError?.param);
+    default:
+      return new TrillboardsError(msg, {
+        type: apiError?.type,
+        code: apiError?.code,
+        statusCode: response.status,
+        help: apiError?.help,
+        param: apiError?.param
+      });
+  }
+}
 function createAuthenticatedFetch(apiKey, apiBase) {
   const base = apiBase.replace(/\/+$/, "");
   return async (path, options) => {
+    const method = options?.method ?? "GET";
+    const start = Date.now();
+    logger.debug(`${method} ${path}`, { base });
     const response = await globalThis.fetch(`${base}${path}`, {
       ...options,
       signal: options?.signal ?? AbortSignal.timeout(1e4),
@@ -13,9 +176,13 @@ function createAuthenticatedFetch(apiKey, apiBase) {
         ...options?.headers ?? {}
       }
     });
+    const ms = Date.now() - start;
     if (!response.ok) {
-      throw new Error(`API error: HTTP ${response.status}`);
+      const error = await errorFromResponse(response);
+      logger.debug(`${method} ${path} -> ${response.status} (${ms}ms) ERROR`);
+      throw error;
     }
+    logger.debug(`${method} ${path} -> ${response.status} (${ms}ms)`);
     return response.json();
   };
 }
@@ -176,15 +343,87 @@ var CreativeClient = class {
 };
 
 // src/server/PartnerClient.ts
-var PartnerClient = class {
-  constructor(config) {
-    this.apiKey = config.apiKey;
+var PartnerClient = class _PartnerClient {
+  constructor(config = {}) {
+    const debug = config.debug ?? (typeof process !== "undefined" && process.env?.TRILLBOARDS_DEBUG === "true");
+    if (debug) {
+      setLogLevel("debug");
+    }
+    const resolvedKey = config.apiKey ?? (typeof process !== "undefined" ? process.env?.TRILLBOARDS_API_KEY : void 0);
+    if (!resolvedKey) {
+      throw new TrillboardsAuthenticationError(
+        "No API key provided. Pass apiKey in config or set TRILLBOARDS_API_KEY environment variable."
+      );
+    }
+    this.apiKey = resolvedKey;
     this.apiBase = config.apiBase ?? "https://api.trillboards.com/v1";
     this.authFetch = createAuthenticatedFetch(this.apiKey, this.apiBase);
     this.audience = new AudienceClient(this.apiKey, this.apiBase);
     this.analytics = new AnalyticsClient(this.apiKey, this.apiBase);
     this.auctions = new AuctionClient(this.apiKey, this.apiBase);
     this.creatives = new CreativeClient(this.apiKey, this.apiBase);
+    if (this.isTestMode) {
+      logger.info("Test mode active");
+    }
+    logger.debug("PartnerClient initialized", {
+      apiBase: this.apiBase,
+      testMode: this.isTestMode
+    });
+  }
+  /** Returns `true` if the API key is a test key (`trb_test_*`). */
+  get isTestMode() {
+    return this.apiKey.startsWith("trb_test_");
+  }
+  /**
+   * One-call onboarding: register a partner, create the first device,
+   * and return a pre-authenticated `PartnerClient` instance ready to use.
+   *
+   * This calls `POST /v1/partner/quick-start` (public, no auth required).
+   */
+  static async quickStart(options) {
+    const base = (options.apiBase ?? "https://api.trillboards.com/v1").replace(/\/+$/, "");
+    if (options.debug) {
+      setLogLevel("debug");
+    }
+    logger.debug("QuickStart: registering partner", {
+      company: options.companyName,
+      email: options.email
+    });
+    const response = await globalThis.fetch(`${base}/partner/quick-start`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        company_name: options.companyName,
+        email: options.email,
+        device_name: options.deviceName
+      }),
+      signal: AbortSignal.timeout(3e4)
+    });
+    if (!response.ok) {
+      let errorMsg = `Quick start failed: HTTP ${response.status}`;
+      let errorCode = "quick_start_failed";
+      try {
+        const body = await response.json();
+        errorMsg = body?.error?.message ?? body?.message ?? errorMsg;
+        errorCode = body?.error?.code ?? errorCode;
+      } catch {
+      }
+      if (response.status === 400) {
+        throw new TrillboardsValidationError(errorMsg);
+      }
+      throw new TrillboardsError(errorMsg, {
+        code: errorCode,
+        statusCode: response.status
+      });
+    }
+    const json = await response.json();
+    const data = json.data;
+    const client = new _PartnerClient({
+      apiKey: data.credentials.api_key,
+      apiBase: options.apiBase,
+      debug: options.debug
+    });
+    return { ...data, client };
   }
   createVastTagBuilder() {
     return new VastTagBuilder({ apiKey: this.apiKey, apiBase: this.apiBase });
@@ -203,7 +442,14 @@ exports.AudienceClient = AudienceClient;
 exports.CreativeClient = CreativeClient;
 exports.PartnerClient = PartnerClient;
 exports.TrackingBatch = TrackingBatch;
+exports.TrillboardsAuthenticationError = TrillboardsAuthenticationError;
+exports.TrillboardsError = TrillboardsError;
+exports.TrillboardsNotFoundError = TrillboardsNotFoundError;
+exports.TrillboardsRateLimitError = TrillboardsRateLimitError;
+exports.TrillboardsValidationError = TrillboardsValidationError;
 exports.VastTagBuilder = VastTagBuilder;
 exports.createAuthenticatedFetch = createAuthenticatedFetch;
+exports.logger = logger;
+exports.setLogLevel = setLogLevel;
 //# sourceMappingURL=server.js.map
 //# sourceMappingURL=server.js.map