@trillboards/api-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,642 @@
+/**
+ * Core type definitions for the Trillboards API Client SDK.
+ *
+ * Mirrors the canonical error contract from trillboard-api/utils/apiErrors.ts
+ * and the OpenAPI schema at trillboard-api/docs/openapi/partner-api.yaml.
+ */
+type ApiErrorType = 'invalid_request_error' | 'authentication_error' | 'permission_error' | 'rate_limit_error' | 'idempotency_error' | 'api_error';
+interface ErrorDetail {
+    field: string;
+    message: string;
+    code: string;
+}
+interface ErrorResponseBody {
+    error: {
+        type: ApiErrorType;
+        code: string;
+        message: string;
+        param?: string | null;
+        request_id?: string;
+        doc_url?: string;
+        details?: ErrorDetail[];
+        help?: Record<string, unknown>;
+    };
+}
+interface ClientOptions {
+    /** Partner API key (e.g. trb_partner_xxxxx). */
+    apiKey: string;
+    /** Base URL for the API. Defaults to https://api.trillboards.com */
+    baseUrl?: string;
+    /** API version header value. When set, sent as Trillboards-Version. */
+    version?: string;
+}
+interface RequestOptions {
+    params?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+interface ListResponse<T> {
+    success: boolean;
+    data: T[];
+    pagination?: {
+        total: number;
+        limit: number;
+        offset: number;
+        has_more: boolean;
+    };
+}
+interface Screen {
+    screen_id: string;
+    name: string;
+    status: string;
+    device_id?: string;
+    venue_type?: string;
+    country?: string;
+    city?: string;
+    timezone?: string;
+    resolution?: string;
+    embed_url?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface Device {
+    device_id: string;
+    device_name: string;
+    device_type?: string;
+    platform?: string;
+    screen_id?: string;
+    status: string;
+    last_heartbeat?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface Impression {
+    impression_id: string;
+    screen_id: string;
+    device_id: string;
+    ad_type?: string;
+    advertiser_name?: string;
+    cpm?: number;
+    earnings?: number;
+    played_at: string;
+    duration_seconds?: number;
+}
+interface AnalyticsData {
+    period: string;
+    total_impressions: number;
+    total_earnings: number;
+    average_cpm: number;
+    fill_rate: number;
+    screens_active: number;
+    screens_total: number;
+    by_screen?: Array<{
+        screen_id: string;
+        name: string;
+        impressions: number;
+        earnings: number;
+    }>;
+}
+interface EarningsData {
+    period: string;
+    total_earnings: number;
+    total_impressions: number;
+    average_cpm: number;
+    daily?: Array<{
+        date: string;
+        earnings: number;
+        impressions: number;
+    }>;
+    pending_payout: number;
+    last_payout_date?: string;
+    last_payout_amount?: number;
+}
+interface WebhookEvent {
+    id: string;
+    type: string;
+    created_at: string;
+    data: Record<string, unknown>;
+    partner_id: string;
+}
+interface Webhook {
+    id: string;
+    url: string;
+    events: string[];
+    status: string;
+    secret: string;
+    created_at: string;
+    updated_at: string;
+}
+interface ErrorEntry {
+    id: string;
+    code: string;
+    type: ApiErrorType;
+    message: string;
+    param?: string;
+    doc_url: string;
+    timestamp: string;
+    request_id: string;
+    endpoint: string;
+    method: string;
+}
+interface FleetCommand {
+    command_id: string;
+    command: string;
+    status: string;
+    target_screens: string[];
+    created_at: string;
+    completed_at?: string;
+}
+interface AudienceData {
+    screen_id: string;
+    timestamp: string;
+    attention_count: number;
+    dwell_time_avg: number;
+    demographics?: Record<string, unknown>;
+}
+interface BillingInfo {
+    plan: string;
+    credits_remaining: number;
+    credits_used: number;
+    usage_this_month: Record<string, number>;
+    stripe_connected: boolean;
+}
+
+/**
+ * Internal HTTP client for the Trillboards API.
+ *
+ * Uses native fetch (Node 18+). Zero runtime dependencies.
+ * Sends standard headers: Authorization, Content-Type, User-Agent, X-Trillboards-Client.
+ */
+
+interface HttpClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    version?: string;
+}
+declare class HttpClient {
+    private readonly config;
+    constructor(config: HttpClientConfig);
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    get<T>(path: string, opts?: {
+        params?: Record<string, unknown>;
+    }): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+    private buildUrl;
+}
+
+/**
+ * ScreensClient — Partner API screen management.
+ *
+ * Base path: /v1/partner (screens are mapped from devices + screen pairs)
+ */
+
+declare class ScreensClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** List all screens owned by this partner. */
+    list(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<ListResponse<Screen>>;
+    /** Get a single screen by ID. */
+    get(screenId: string): Promise<{
+        success: boolean;
+        data: Screen;
+    }>;
+    /** Register a new device/screen. */
+    create(body: {
+        device_name: string;
+        device_type?: string;
+        venue_type?: string;
+        country?: string;
+        city?: string;
+        timezone?: string;
+        resolution?: string;
+    }): Promise<{
+        success: boolean;
+        data: Screen;
+    }>;
+    /** Delete a screen/device. */
+    delete(screenId: string): Promise<{
+        success: boolean;
+    }>;
+}
+
+/**
+ * DevicesClient — device registration and heartbeat.
+ *
+ * Base path: /v1/partner
+ */
+
+declare class DevicesClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** List all devices for this partner. */
+    list(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<ListResponse<Device>>;
+    /** Get a single device by ID. */
+    get(deviceId: string): Promise<{
+        success: boolean;
+        data: Device;
+    }>;
+    /** Register a new device. */
+    create(body: {
+        device_name: string;
+        device_type?: string;
+        platform?: string;
+    }): Promise<{
+        success: boolean;
+        data: Device;
+    }>;
+    /** Delete a device. */
+    delete(deviceId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Send heartbeat for a device. */
+    heartbeat(deviceId: string, body?: Record<string, unknown>): Promise<{
+        success: boolean;
+    }>;
+}
+
+/**
+ * ImpressionsClient — impression tracking.
+ *
+ * Base path: /v1/partner
+ */
+
+declare class ImpressionsClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Record a single impression. */
+    create(body: {
+        screen_id: string;
+        device_id: string;
+        ad_type?: string;
+        duration_seconds?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        success: boolean;
+        data: Impression;
+    }>;
+    /** Record a batch of impressions (offline sync). */
+    createBatch(body: {
+        impressions: Array<{
+            screen_id: string;
+            device_id: string;
+            ad_type?: string;
+            duration_seconds?: number;
+            played_at?: string;
+            metadata?: Record<string, unknown>;
+        }>;
+    }): Promise<{
+        success: boolean;
+        count: number;
+    }>;
+}
+
+/**
+ * AnalyticsClient — partner analytics and reporting.
+ *
+ * Base path: /v1/partner
+ */
+
+declare class AnalyticsClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Get partner analytics summary. */
+    get(params?: {
+        period?: 'day' | 'week' | 'month';
+        start_date?: string;
+        end_date?: string;
+        screen_id?: string;
+    }): Promise<{
+        success: boolean;
+        data: AnalyticsData;
+    }>;
+}
+
+/**
+ * EarningsClient — earnings, payouts, and transaction history.
+ *
+ * Base path: /v1/partner
+ */
+
+declare class EarningsClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Get earnings summary for the authenticated partner. */
+    get(params?: {
+        period?: 'day' | 'week' | 'month';
+        start_date?: string;
+        end_date?: string;
+    }): Promise<{
+        success: boolean;
+        data: EarningsData;
+    }>;
+}
+
+/**
+ * ErrorsClient — query the partner error log.
+ *
+ * Base path: /v1/partner
+ */
+
+declare class ErrorsClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** List recent errors for this partner. */
+    list(params?: {
+        limit?: number;
+        offset?: number;
+        code?: string;
+        type?: string;
+    }): Promise<ListResponse<ErrorEntry>>;
+    /** Get a single error by request_id. */
+    get(requestId: string): Promise<{
+        success: boolean;
+        data: ErrorEntry;
+    }>;
+}
+
+/**
+ * WebhooksClient — webhook subscription management.
+ *
+ * Base path: /v1/partner
+ */
+
+declare class WebhooksClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** List all webhook subscriptions. */
+    list(): Promise<ListResponse<Webhook>>;
+    /** Create a new webhook subscription. */
+    create(body: {
+        url: string;
+        events: string[];
+    }): Promise<{
+        success: boolean;
+        data: Webhook;
+    }>;
+    /** Update a webhook subscription. */
+    update(webhookId: string, body: {
+        url?: string;
+        events?: string[];
+        status?: string;
+    }): Promise<{
+        success: boolean;
+        data: Webhook;
+    }>;
+    /** Delete a webhook subscription. */
+    delete(webhookId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Send a test event to a webhook. */
+    test(webhookId: string): Promise<{
+        success: boolean;
+    }>;
+}
+
+/**
+ * FleetClient — fleet-wide device management.
+ *
+ * Base path: /v1/partner
+ */
+
+declare class FleetClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Push a command to a set of screens. */
+    pushCommand(body: {
+        command: string;
+        target_screens?: string[];
+        venue_type?: string;
+        country?: string;
+        params?: Record<string, unknown>;
+    }): Promise<{
+        success: boolean;
+        data: FleetCommand;
+    }>;
+    /** List recent fleet commands. */
+    listCommands(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<ListResponse<FleetCommand>>;
+}
+
+/**
+ * AudienceClient — audience intelligence API.
+ *
+ * Base path: /v1/partner/audience
+ */
+
+declare class AudienceClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Get live audience data for a screen. */
+    getLive(screenId: string): Promise<{
+        success: boolean;
+        data: AudienceData;
+    }>;
+    /** Get audience heatmap across screens. */
+    getHeatmap(params?: {
+        start_date?: string;
+        end_date?: string;
+        screen_ids?: string[];
+    }): Promise<{
+        success: boolean;
+        data: Record<string, unknown>;
+    }>;
+    /** Get aggregate audience statistics. */
+    getStats(params?: {
+        period?: 'day' | 'week' | 'month';
+    }): Promise<{
+        success: boolean;
+        data: Record<string, unknown>;
+    }>;
+}
+
+/**
+ * DataClient — data export and venue intelligence.
+ *
+ * Base path: /v1/partner
+ */
+
+declare class DataClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Get venue intelligence data for a screen. */
+    getVenueIntelligence(screenId: string): Promise<{
+        success: boolean;
+        data: Record<string, unknown>;
+    }>;
+    /** Get API usage summary. */
+    getUsage(params?: {
+        period?: 'day' | 'week' | 'month';
+    }): Promise<{
+        success: boolean;
+        data: Record<string, unknown>;
+    }>;
+}
+
+/**
+ * BillingClient — usage-based billing and credits.
+ *
+ * Base path: /v1/partner
+ */
+
+declare class BillingClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Get current billing info (plan, credits, usage). */
+    get(): Promise<{
+        success: boolean;
+        data: BillingInfo;
+    }>;
+    /** Get Stripe Connect account status. */
+    getStripeStatus(): Promise<{
+        success: boolean;
+        data: Record<string, unknown>;
+    }>;
+    /** Request a payout transfer. */
+    requestPayout(body?: {
+        amount?: number;
+    }): Promise<{
+        success: boolean;
+        data: Record<string, unknown>;
+    }>;
+}
+
+/**
+ * TrillboardsClient — main entry point for the Trillboards Partner API SDK.
+ *
+ * Usage:
+ *   import { TrillboardsClient } from '@trillboards/api-client';
+ *
+ *   const client = new TrillboardsClient({ apiKey: 'trb_partner_xxxxx' });
+ *   const screens = await client.screens.list();
+ */
+
+declare class TrillboardsClient {
+    readonly screens: ScreensClient;
+    readonly devices: DevicesClient;
+    readonly impressions: ImpressionsClient;
+    readonly analytics: AnalyticsClient;
+    readonly webhooks: WebhooksClient;
+    readonly earnings: EarningsClient;
+    readonly fleet: FleetClient;
+    readonly audience: AudienceClient;
+    readonly data: DataClient;
+    readonly errors: ErrorsClient;
+    readonly billing: BillingClient;
+    /** The underlying HTTP client (exposed for advanced use cases). */
+    readonly _http: HttpClient;
+    constructor(options: ClientOptions);
+}
+
+/**
+ * TrillboardsError — client-side error class that mirrors the server-side
+ * canonical error envelope from utils/apiErrors.ts.
+ *
+ * Error shape from the API:
+ *   { error: { type, code, message, param, doc_url, request_id, details?, help? } }
+ */
+
+interface TrillboardsErrorOptions {
+    type: ApiErrorType;
+    code: string;
+    message: string;
+    statusCode: number;
+    param?: string | null;
+    requestId?: string;
+    docsUrl?: string;
+    details?: ErrorDetail[];
+    help?: Record<string, unknown>;
+    retryAfterSeconds?: number | null;
+}
+declare class TrillboardsError extends Error {
+    readonly type: ApiErrorType;
+    readonly code: string;
+    readonly param: string | null;
+    readonly requestId: string;
+    readonly docsUrl: string;
+    readonly statusCode: number;
+    readonly details: ErrorDetail[];
+    readonly help: Record<string, unknown> | null;
+    private readonly _retryAfterSeconds;
+    constructor(opts: TrillboardsErrorOptions);
+    /**
+     * Construct a TrillboardsError from an API error response body and fetch Response.
+     *
+     * The API wraps errors in { error: { ... } }. We unwrap and map to class fields.
+     */
+    static fromResponse(body: ErrorResponseBody | Record<string, unknown>, response: {
+        status: number;
+        headers: {
+            get(name: string): string | null;
+        };
+    }): TrillboardsError;
+    /** True if this is a 429 rate limit response. */
+    get isRateLimited(): boolean;
+    /**
+     * Number of seconds to wait before retrying, from the Retry-After header.
+     * Returns null if no Retry-After header was present.
+     */
+    get retryAfter(): number | null;
+    /** True if this is an authentication error (401). */
+    get isAuthError(): boolean;
+    /** True if this is a permission/forbidden error (403). */
+    get isForbidden(): boolean;
+    /** True if this is a server-side error (5xx). */
+    get isServerError(): boolean;
+}
+
+/**
+ * Webhook signature verification for Trillboards Partner API webhooks.
+ *
+ * Uses HMAC-SHA256 with timing-safe comparison to prevent signature
+ * forgery and timing attacks.
+ */
+
+/**
+ * Verify a webhook payload signature and parse the event.
+ *
+ * @param payload  - Raw request body as string or Buffer.
+ * @param signature - The signature from the `X-Trillboards-Signature` header.
+ * @param secret   - The webhook secret from your webhook subscription.
+ * @returns The parsed WebhookEvent if signature is valid.
+ * @throws TrillboardsError if the signature does not match.
+ *
+ * @example
+ * ```typescript
+ * import { Webhooks } from '@trillboards/api-client';
+ *
+ * app.post('/webhooks', (req, res) => {
+ *   const event = Webhooks.constructEvent(
+ *     req.body,
+ *     req.headers['x-trillboards-signature'],
+ *     process.env.WEBHOOK_SECRET
+ *   );
+ *   console.log('Received event:', event.type);
+ *   res.sendStatus(200);
+ * });
+ * ```
+ */
+declare function constructEvent(payload: string | Buffer, signature: string, secret: string): WebhookEvent;
+declare const Webhooks: {
+    constructEvent: typeof constructEvent;
+};
+
+/**
+ * SDK version constant. Sent in User-Agent and X-Trillboards-Client headers.
+ * Keep in sync with package.json version.
+ */
+declare const VERSION = "0.1.0";
+
+declare const generatedTypes: {};
+
+export { AnalyticsClient, type AnalyticsData, type ApiErrorType, AudienceClient, type AudienceData, BillingClient, type BillingInfo, type ClientOptions, DataClient, type Device, DevicesClient, EarningsClient, type EarningsData, type ErrorDetail, type ErrorEntry, type ErrorResponseBody, ErrorsClient, FleetClient, type FleetCommand, type Impression, ImpressionsClient, type ListResponse, type RequestOptions, type Screen, ScreensClient, TrillboardsClient, TrillboardsError, type TrillboardsErrorOptions, VERSION, type Webhook, type WebhookEvent, Webhooks, WebhooksClient, constructEvent, generatedTypes };