@trillboards/cli 0.1.0

package/dist/commands/screens/watch.js

@@ -0,0 +1,158 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base-command.js';
+import { clearScreen, colorFillRate, colorStatus, colorize, formatCurrency, relativeTime, } from '../../format-helpers.js';
+import { apiRequest } from '../../http.js';
+export default class ScreensWatch extends BaseCommand {
+    static description = 'Live fleet dashboard — watch all screens in real-time';
+    static examples = [
+        '<%= config.bin %> screens watch',
+        '<%= config.bin %> screens watch --filter online',
+        '<%= config.bin %> screens watch --sort earnings',
+        '<%= config.bin %> screens watch --format json',
+    ];
+    static flags = {
+        filter: Flags.string({
+            description: 'Filter screens by status',
+            options: ['online', 'offline'],
+        }),
+        interval: Flags.integer({
+            default: 10,
+            description: 'Refresh interval in seconds',
+        }),
+        sort: Flags.string({
+            default: 'name',
+            description: 'Sort column',
+            options: ['name', 'earnings', 'fill-rate'],
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(ScreensWatch);
+        this.setParsedFlags(flags);
+        const apiKey = this.getApiKey();
+        if (!apiKey) {
+            this.error('Not logged in. Run: trillboards login', { exit: 1 });
+        }
+        const baseUrl = this.getBaseUrl();
+        const format = this.getFormat();
+        // Single fetch for --format json (no live loop)
+        if (format === 'json') {
+            const data = await this.fetchData(apiKey, baseUrl);
+            const filtered = this.filterAndSort(data.screens, flags.filter, flags.sort ?? 'name');
+            this.output(filtered);
+            return;
+        }
+        // Live mode with setInterval
+        const render = async () => {
+            try {
+                const data = await this.fetchData(apiKey, baseUrl);
+                const screens = this.filterAndSort(data.screens, flags.filter, flags.sort ?? 'name');
+                clearScreen();
+                this.renderTable(screens, data.analytics);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                clearScreen();
+                this.log(colorize(`Error fetching fleet data: ${msg}`, 'red'));
+                this.log('Retrying...');
+            }
+        };
+        // Initial render
+        await render();
+        // Schedule refresh
+        const intervalMs = (flags.interval ?? 10) * 1000;
+        const timer = setInterval(() => {
+            render().catch(() => {
+                // Errors handled inside render
+            });
+        }, intervalMs);
+        // Clean exit on Ctrl+C
+        const cleanup = () => {
+            clearInterval(timer);
+            this.log('\nStopped watching.');
+            process.exit(0);
+        };
+        process.on('SIGINT', cleanup);
+        process.on('SIGTERM', cleanup);
+        // Keep process alive
+        await new Promise(() => {
+            // Never resolves — exits via signal handler
+        });
+    }
+    async fetchData(apiKey, baseUrl) {
+        const [healthResult, analyticsResult] = await Promise.allSettled([
+            apiRequest('GET', '/v1/partner/connect/health', { apiKey, baseUrl }),
+            apiRequest('GET', '/v1/partner/fleet/analytics', { apiKey, baseUrl }),
+        ]);
+        const health = healthResult.status === 'fulfilled' ? healthResult.value : { screens: [] };
+        const analytics = analyticsResult.status === 'fulfilled' ? analyticsResult.value : {};
+        return { analytics, screens: health.screens ?? [] };
+    }
+    filterAndSort(screens, filter, sort) {
+        let result = [...screens];
+        if (filter === 'online') {
+            result = result.filter((s) => s.status?.toLowerCase() === 'online');
+        }
+        else if (filter === 'offline') {
+            result = result.filter((s) => s.status?.toLowerCase() !== 'online');
+        }
+        switch (sort) {
+            case 'earnings': {
+                result.sort((a, b) => (b.earnings_today ?? 0) - (a.earnings_today ?? 0));
+                break;
+            }
+            case 'fill-rate': {
+                result.sort((a, b) => (b.fill_rate ?? 0) - (a.fill_rate ?? 0));
+                break;
+            }
+            default: {
+                result.sort((a, b) => (a.name ?? '').localeCompare(b.name ?? ''));
+            }
+        }
+        return result;
+    }
+    renderTable(screens, analytics) {
+        const header = colorize('Trillboards Fleet Dashboard', 'bold');
+        const timestamp = new Date().toLocaleTimeString();
+        this.log(header);
+        this.log(`Updated: ${timestamp}  |  Online: ${analytics.screens_online ?? '?'}/${analytics.screens_total ?? '?'}  |  Network Fill: ${analytics.fill_rate != null ? colorFillRate(analytics.fill_rate) : 'N/A'}`);
+        this.log('');
+        // Column headers
+        const nameW = 30;
+        const statusW = 10;
+        const fillW = 12;
+        const earnW = 16;
+        const hbW = 18;
+        const headerRow = [
+            'Name'.padEnd(nameW),
+            'Status'.padEnd(statusW),
+            'Fill Rate'.padEnd(fillW),
+            'Earnings Today'.padEnd(earnW),
+            'Last Heartbeat'.padEnd(hbW),
+        ].join('  ');
+        this.log(colorize(headerRow, 'dim'));
+        this.log('-'.repeat(nameW + statusW + fillW + earnW + hbW + 8));
+        if (screens.length === 0) {
+            this.log('  No screens found.');
+            return;
+        }
+        for (const screen of screens) {
+            const name = (screen.name ?? screen.screen_id ?? 'Unknown').slice(0, nameW).padEnd(nameW);
+            const statusRaw = screen.status ?? 'unknown';
+            let statusDisplay = statusRaw;
+            // Check for stale heartbeat (>60s)
+            if (statusRaw.toLowerCase() === 'online' && screen.last_heartbeat) {
+                const diffMs = Date.now() - new Date(screen.last_heartbeat).getTime();
+                if (diffMs > 60_000) {
+                    statusDisplay = 'stale';
+                }
+            }
+            const status = colorStatus(statusDisplay).padEnd(statusW + 9); // +9 for ANSI codes
+            const fill = screen.fill_rate != null ? colorFillRate(screen.fill_rate).padEnd(fillW + 9) : 'N/A'.padEnd(fillW);
+            const earn = screen.earnings_today != null ? formatCurrency(screen.earnings_today).padEnd(earnW) : 'N/A'.padEnd(earnW);
+            const hb = screen.last_heartbeat ? relativeTime(screen.last_heartbeat).padEnd(hbW) : 'N/A'.padEnd(hbW);
+            this.log(`${name}  ${status}  ${fill}  ${earn}  ${hb}`);
+        }
+        this.log('');
+        this.log(colorize('Press Ctrl+C to stop', 'dim'));
+    }
+}

package/dist/commands/trigger.d.ts

@@ -0,0 +1,9 @@
+import { BaseCommand } from '../base-command.js';
+export default class Trigger extends BaseCommand {
+    static args: {
+        event_type: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/trigger.js

@@ -0,0 +1,53 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../base-command.js';
+import { apiRequest } from '../http.js';
+const KNOWN_EVENT_TYPES = [
+    'impression_start',
+    'impression_complete',
+    'impression_error',
+    'screen_heartbeat',
+    'screen_online',
+    'screen_offline',
+    'content_loaded',
+    'content_error',
+];
+export default class Trigger extends BaseCommand {
+    static args = {
+        event_type: Args.string({
+            description: 'Event type to fire (e.g. impression_start)',
+            required: false,
+        }),
+    };
+    static description = 'Fire test events in the sandbox';
+    static examples = [
+        '<%= config.bin %> trigger',
+        '<%= config.bin %> trigger impression_start',
+        '<%= config.bin %> trigger impression_complete --format json',
+    ];
+    async run() {
+        const { args, flags } = await this.parse(Trigger);
+        this.setParsedFlags(flags);
+        const apiKey = this.getApiKey();
+        if (!apiKey) {
+            this.error('Not logged in. Run: trillboards login', { exit: 1 });
+        }
+        const baseUrl = this.getBaseUrl();
+        if (!args.event_type) {
+            // List available event types
+            this.log('Available event types:');
+            this.output(KNOWN_EVENT_TYPES.map((type) => ({ event_type: type })));
+            return;
+        }
+        const eventType = args.event_type;
+        const result = await apiRequest('POST', '/v1/partner/sandbox/event', {
+            apiKey,
+            baseUrl,
+            body: {
+                event_type: eventType,
+                timestamp: new Date().toISOString(),
+            },
+        });
+        this.log(`Event fired: ${eventType}`);
+        this.output(result);
+    }
+}

package/dist/commands/validate.d.ts

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../base-command.js';
+export default class Validate extends BaseCommand {
+    static args: {
+        file: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        operation: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/validate.js

@@ -0,0 +1,93 @@
+import { readFileSync } from 'node:fs';
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../base-command.js';
+import { apiRequest } from '../http.js';
+export default class Validate extends BaseCommand {
+    static args = {
+        file: Args.string({ description: 'Path to JSON file to validate', required: true }),
+    };
+    static description = 'Validate a JSON payload against the API (dry-run)';
+    static examples = [
+        '<%= config.bin %> validate payload.json',
+        '<%= config.bin %> validate payload.json --operation create_screen',
+    ];
+    static flags = {
+        operation: Flags.string({
+            char: 'o',
+            description: 'Operation ID for the playground endpoint (e.g. create_screen)',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Validate);
+        this.setParsedFlags(flags);
+        // Read and parse the file
+        let content;
+        try {
+            content = readFileSync(args.file, 'utf-8');
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.error(`Could not read file: ${msg}`, { exit: 1 });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.error(`Invalid JSON in ${args.file}: ${msg}`, { exit: 1 });
+        }
+        // If operation is specified and we have an API key, try the playground endpoint
+        const apiKey = this.getApiKey();
+        const baseUrl = this.getBaseUrl();
+        if (flags.operation && apiKey) {
+            try {
+                const result = await apiRequest('POST', `/v1/playground/${flags.operation}`, {
+                    apiKey,
+                    baseUrl,
+                    body: parsed,
+                });
+                this.log('Validation passed (server-side):');
+                this.output(result);
+                return;
+            }
+            catch (error) {
+                // If the playground endpoint doesn't exist, fall through to local validation
+                if (error instanceof Error && 'statusCode' in error && error.statusCode === 404) {
+                    this.warn('Playground endpoint not available. Showing local validation only.');
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        // Local validation: show the parsed structure
+        this.log('JSON is valid. Structure:');
+        const summary = summarizeJson(parsed);
+        this.output(summary);
+    }
+}
+function summarizeJson(data, depth = 0) {
+    if (depth > 3)
+        return { type: typeof data };
+    if (Array.isArray(data)) {
+        return {
+            items: data.length > 0 ? summarizeJson(data[0], depth + 1) : {},
+            length: data.length,
+            type: 'array',
+        };
+    }
+    if (typeof data === 'object' && data !== null) {
+        const fields = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (typeof value === 'object' && value !== null) {
+                fields[key] = summarizeJson(value, depth + 1);
+            }
+            else {
+                fields[key] = typeof value;
+            }
+        }
+        return { fields, type: 'object' };
+    }
+    return { type: typeof data, value: data };
+}

package/dist/commands/whoami.d.ts

@@ -0,0 +1,6 @@
+import { BaseCommand } from '../base-command.js';
+export default class Whoami extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/whoami.js

@@ -0,0 +1,39 @@
+import { BaseCommand } from '../base-command.js';
+import { apiRequest } from '../http.js';
+export default class Whoami extends BaseCommand {
+    static description = 'Show current partner info and API key status';
+    static examples = [
+        '<%= config.bin %> whoami',
+        '<%= config.bin %> whoami --format json',
+    ];
+    async run() {
+        const { flags } = await this.parse(Whoami);
+        this.setParsedFlags(flags);
+        const apiKey = this.getApiKey();
+        if (!apiKey) {
+            this.error('Not logged in. Run: trillboards login', { exit: 1 });
+        }
+        const baseUrl = this.getBaseUrl();
+        const info = (await apiRequest('GET', '/v1/partner/info', { apiKey, baseUrl }));
+        const maskedKey = maskApiKey(apiKey);
+        const format = this.getFormat();
+        if (format === 'json') {
+            this.output({ ...info, api_key: maskedKey });
+            return;
+        }
+        // Table/yaml — show a summary
+        const display = {
+            'Partner Name': info.partner_name || info.name || 'Unknown',
+            Tier: info.tier || 'standard',
+            'Screens Online': info.screens_online ?? 'N/A',
+            'Screens Total': info.screens_total ?? 'N/A',
+            'API Key': maskedKey,
+        };
+        this.output(display);
+    }
+}
+function maskApiKey(key) {
+    if (key.length <= 8)
+        return '****';
+    return key.slice(0, 4) + '...' + key.slice(-4);
+}

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export interface TrillboardsConfig {
+    api_key?: string;
+    base_url?: string;
+    default_format?: 'json' | 'table' | 'yaml';
+    partner_name?: string;
+}
+export declare function readConfig(): TrillboardsConfig;
+export declare function writeConfig(config: TrillboardsConfig): void;
+export declare function updateConfig(updates: Partial<TrillboardsConfig>): void;
+export declare function getConfigPath(): string;

package/dist/config.js

@@ -0,0 +1,32 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const CONFIG_DIR = join(homedir(), '.trillboards');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+function ensureConfigDir() {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+}
+export function readConfig() {
+    try {
+        if (!existsSync(CONFIG_FILE))
+            return {};
+        const raw = readFileSync(CONFIG_FILE, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export function writeConfig(config) {
+    ensureConfigDir();
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+export function updateConfig(updates) {
+    const existing = readConfig();
+    writeConfig({ ...existing, ...updates });
+}
+export function getConfigPath() {
+    return CONFIG_FILE;
+}

package/dist/format-helpers.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared formatting helpers for DOOH CLI commands.
+ * Currency, percentages, counts, ANSI colors, ASCII bar charts.
+ */
+export declare const ansi: {
+    readonly bold: "\u001B[1m";
+    readonly dim: "\u001B[2m";
+    readonly green: "\u001B[32m";
+    readonly red: "\u001B[31m";
+    readonly reset: "\u001B[0m";
+    readonly yellow: "\u001B[33m";
+};
+export declare function colorize(text: string, color: keyof typeof ansi): string;
+/**
+ * Format a number as USD currency: $1,234.56
+ */
+export declare function formatCurrency(value: number): string;
+/**
+ * Format a number with comma separators: 1,234
+ */
+export declare function formatCount(value: number): string;
+/**
+ * Format a number as percentage: 78%
+ */
+export declare function formatPercent(value: number): string;
+/**
+ * Color a fill rate value: green >70%, yellow 50-70%, red <50%
+ */
+export declare function colorFillRate(value: number): string;
+/**
+ * Color a status string: green=online, red=offline, yellow=stale
+ */
+export declare function colorStatus(status: string): string;
+/**
+ * Render an ASCII bar chart row.
+ * maxWidth is the number of block characters at 100%.
+ */
+export declare function barChartRow(label: string, value: number, maxValue: number, maxWidth?: number): string;
+/**
+ * Format a relative time string from a timestamp.
+ */
+export declare function relativeTime(timestamp: string | number | Date): string;
+/**
+ * Clear the terminal screen and move cursor to top.
+ */
+export declare function clearScreen(): void;

package/dist/format-helpers.js

@@ -0,0 +1,96 @@
+/**
+ * Shared formatting helpers for DOOH CLI commands.
+ * Currency, percentages, counts, ANSI colors, ASCII bar charts.
+ */
+// ANSI color codes
+export const ansi = {
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    reset: '\x1b[0m',
+    yellow: '\x1b[33m',
+};
+export function colorize(text, color) {
+    if (!process.stdout.isTTY)
+        return text;
+    return `${ansi[color]}${text}${ansi.reset}`;
+}
+/**
+ * Format a number as USD currency: $1,234.56
+ */
+export function formatCurrency(value) {
+    return '$' + value.toLocaleString('en-US', { maximumFractionDigits: 2, minimumFractionDigits: 2 });
+}
+/**
+ * Format a number with comma separators: 1,234
+ */
+export function formatCount(value) {
+    return value.toLocaleString('en-US');
+}
+/**
+ * Format a number as percentage: 78%
+ */
+export function formatPercent(value) {
+    return Math.round(value) + '%';
+}
+/**
+ * Color a fill rate value: green >70%, yellow 50-70%, red <50%
+ */
+export function colorFillRate(value) {
+    const text = formatPercent(value);
+    if (value >= 70)
+        return colorize(text, 'green');
+    if (value >= 50)
+        return colorize(text, 'yellow');
+    return colorize(text, 'red');
+}
+/**
+ * Color a status string: green=online, red=offline, yellow=stale
+ */
+export function colorStatus(status) {
+    const lower = status.toLowerCase();
+    if (lower === 'online')
+        return colorize(status, 'green');
+    if (lower === 'offline')
+        return colorize(status, 'red');
+    return colorize(status, 'yellow');
+}
+/**
+ * Render an ASCII bar chart row.
+ * maxWidth is the number of block characters at 100%.
+ */
+export function barChartRow(label, value, maxValue, maxWidth = 20) {
+    const ratio = maxValue > 0 ? value / maxValue : 0;
+    const filled = Math.round(ratio * maxWidth);
+    const empty = maxWidth - filled;
+    const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(empty);
+    return `${label} ${bar}  ${formatCurrency(value)}`;
+}
+/**
+ * Format a relative time string from a timestamp.
+ */
+export function relativeTime(timestamp) {
+    const now = Date.now();
+    const then = new Date(timestamp).getTime();
+    const diffMs = now - then;
+    const diffSec = Math.floor(diffMs / 1000);
+    if (diffSec < 0)
+        return 'just now';
+    if (diffSec < 60)
+        return `${diffSec}s ago`;
+    const diffMin = Math.floor(diffSec / 60);
+    if (diffMin < 60)
+        return `${diffMin}m ago`;
+    const diffHr = Math.floor(diffMin / 60);
+    if (diffHr < 24)
+        return `${diffHr}h ago`;
+    const diffDay = Math.floor(diffHr / 24);
+    return `${diffDay}d ago`;
+}
+/**
+ * Clear the terminal screen and move cursor to top.
+ */
+export function clearScreen() {
+    process.stdout.write('\x1b[2J\x1b[H');
+}

package/dist/http.d.ts

@@ -0,0 +1,13 @@
+export declare class TrillboardsApiError extends Error {
+    code: string;
+    statusCode: number;
+    constructor(message: string, code: string, statusCode: number);
+    static fromResponse(body: Record<string, unknown>, statusCode: number): TrillboardsApiError;
+}
+export interface ApiRequestOptions {
+    apiKey: string;
+    baseUrl: string;
+    body?: unknown;
+    params?: Record<string, string>;
+}
+export declare function apiRequest(method: string, path: string, options: ApiRequestOptions): Promise<unknown>;

package/dist/http.js

@@ -0,0 +1,51 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { version: VERSION } = require('../package.json');
+export class TrillboardsApiError extends Error {
+    code;
+    statusCode;
+    constructor(message, code, statusCode) {
+        super(message);
+        this.name = 'TrillboardsApiError';
+        this.code = code;
+        this.statusCode = statusCode;
+    }
+    static fromResponse(body, statusCode) {
+        const message = body.message || body.error || `API returned ${statusCode}`;
+        const code = body.code || `HTTP_${statusCode}`;
+        return new TrillboardsApiError(message, code, statusCode);
+    }
+}
+export async function apiRequest(method, path, options) {
+    const url = new URL(path, options.baseUrl);
+    if (options.params) {
+        for (const [k, v] of Object.entries(options.params)) {
+            url.searchParams.set(k, v);
+        }
+    }
+    const headers = {
+        'Authorization': `Bearer ${options.apiKey}`,
+        'Content-Type': 'application/json',
+        'User-Agent': `trillboards-cli/${VERSION}`,
+        'X-Trillboards-Client-Type': 'agent',
+    };
+    const response = await fetch(url.toString(), {
+        body: options.body ? JSON.stringify(options.body) : undefined,
+        headers,
+        method,
+    });
+    let json;
+    try {
+        json = (await response.json());
+    }
+    catch {
+        if (!response.ok) {
+            throw new TrillboardsApiError(`API returned ${response.status} with non-JSON body`, `HTTP_${response.status}`, response.status);
+        }
+        return { ok: true, status: response.status };
+    }
+    if (!response.ok) {
+        throw TrillboardsApiError.fromResponse(json, response.status);
+    }
+    return json;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/index.js

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/output.d.ts

@@ -0,0 +1,2 @@
+export type OutputFormat = 'json' | 'table' | 'yaml';
+export declare function formatOutput(data: unknown, format: OutputFormat): string;