@trillboards/cli 0.1.0 → 0.1.3

package/dist/render.js

@@ -0,0 +1,124 @@
+/**
+ * Render adapters for the `trillboards code` wrapper (pure command builders).
+ *
+ * Given the chosen creative + the surface capabilities, render it during dead-time:
+ *   video → mpv in a non-modal tmux split pane where the terminal supports it,
+ *           else a spawned mpv window (VS Code/Cursor/unknown)
+ *   image → timg / kitten icat inline
+ *   text  → an OSC-8 sponsor line written to the wrapper's own output
+ *
+ * The command BUILDERS are pure (return {bin,args}) so they're unit-tested; the
+ * actual spawning lives in render-runner.ts.
+ */
+import { buildSponsorMessage } from './agent-hook.js';
+import { colorize, osc8 } from './format-helpers.js';
+/** Sanctioned, disclosed copy for the programmatic (Leg A) video link shown in dead-time. */
+const SANCTIONED_PROGRAMMATIC_LINE = 'Sponsored — your idle agent earned you a paid impression. Tap to play the video ad:';
+/** mpv flags that make `--vo=kitty` play smoothly (Ghostty needs shm+really-quiet). */
+const MPV_TERMINAL_FLAGS = [
+    '--vo=kitty',
+    '--vo-kitty-use-shm=yes',
+    '--profile=sw-fast',
+    '--really-quiet',
+    '--no-input-default-bindings',
+    '--loop=no',
+];
+/** POSIX single-quote a string for safe interpolation into a shell command. */
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Build the command to play a video in a NON-MODAL tmux split pane. `-d` keeps focus
+ * (and keystrokes) on the agent's pane — the ad plays beside it without stealing
+ * input; the pane auto-closes when mpv reaches EOF. Each tmux pane is its own grid,
+ * so the agent never repaints over the video. Requires `set -g allow-passthrough on`.
+ * `-P -F '#{pane_id}'` prints the new pane id so the runner can kill it early.
+ */
+export function buildTmuxPaneVideo(url, sizePct = 35) {
+    const inner = `mpv ${MPV_TERMINAL_FLAGS.join(' ')} ${shellQuote(url)}`;
+    return {
+        bin: 'tmux',
+        args: ['split-window', '-d', '-P', '-F', '#{pane_id}', '-l', `${sizePct}%`, inner],
+    };
+}
+/** Build the command to play a video in mpv's OWN window (fallback: VS Code/Cursor/no-tmux). */
+export function buildSpawnWindowVideo(url, platform = process.platform) {
+    if (platform === 'darwin')
+        return { bin: 'open', args: ['-na', 'mpv', '--args', url] };
+    if (platform === 'win32')
+        return { bin: 'mpv', args: [url] };
+    // Linux/other: mpv opens its own window via the default VO.
+    return { bin: 'mpv', args: [url] };
+}
+/** Build the inline-image command (timg auto-detects kitty/iTerm2/sixel). */
+export function buildImagePlayback(url) {
+    // timg auto-selects the best inline-graphics protocol; -g bounds the cell box.
+    return { bin: 'timg', args: ['-g', '60x30', '--upscale', url] };
+}
+/**
+ * Build the OS command to open a URL in the user's default browser — the Leg A webview
+ * surface (VS Code / Cursor / any no-tmux terminal). This is where AdX/IMA legitimately
+ * runs (a real DOM), and it mirrors how a Leg B video spawns its own window off-tmux.
+ */
+export function buildOpenUrl(url, platform = process.platform) {
+    if (platform === 'darwin')
+        return { bin: 'open', args: [url] };
+    if (platform === 'win32')
+        return { bin: 'cmd', args: ['/c', 'start', '', url] };
+    // Linux/other: xdg-open routes to the registered default browser.
+    return { bin: 'xdg-open', args: [url] };
+}
+/** The plain-text sponsor line (reuses the shipped `buildSponsorMessage`). */
+export function renderTextLine(creative) {
+    const ad = {
+        adId: creative.adId,
+        name: creative.name,
+        description: creative.description,
+        campaignLink: creative.campaignLink,
+        variantName: creative.variantName,
+    };
+    return buildSponsorMessage(ad);
+}
+/**
+ * The programmatic (Leg A) line: sanctioned disclosure + an OSC-8 clickable link to the
+ * hosted IMA player, plus the raw URL as a fallback for terminals without OSC-8. Clicking
+ * opens the player in a browser/webview, which runs the served VAST via the Google IMA SDK
+ * (the same path the screen app uses) and bills via the wrap's signed vast_event pixels.
+ * Returns null when the creative carries no playable IMA player URL.
+ */
+export function renderProgrammaticLine(creative) {
+    if (!creative.imaPlayerUrl)
+        return null;
+    const link = osc8(creative.imaPlayerUrl, colorize('▶ Play sponsored video', 'green'));
+    return `${colorize(SANCTIONED_PROGRAMMATIC_LINE, 'bold')}\n  ${link}\n  ${colorize(creative.imaPlayerUrl, 'dim')}`;
+}
+/**
+ * Decide HOW to surface a Leg A (programmatic) fill: a clickable OSC-8 link in a non-modal
+ * tmux pane when we're in tmux, else open the hosted IMA player in the default browser.
+ * The no-tmux branch is the VS Code / Cursor / plain-terminal "webview" surface — opening a
+ * browser is the only way to run AdX/IMA there (it needs a real DOM), and it mirrors how a
+ * Leg B video spawns its own window off-tmux. So a programmatic fill is ALWAYS renderable
+ * on some surface — never dropped just because there's no tmux (the bug Codex flagged).
+ * Null only when the creative carries no playable IMA player URL.
+ */
+export function planProgrammaticPlayback(creative, env) {
+    if (!creative.imaPlayerUrl)
+        return null;
+    if (env.inTmux) {
+        const line = renderProgrammaticLine(creative);
+        if (!line)
+            return null;
+        return { strategy: 'tmux-link', line };
+    }
+    return { strategy: 'open-url', spec: buildOpenUrl(creative.imaPlayerUrl, env.platform ?? process.platform) };
+}
+/**
+ * Decide HOW to play a video for this surface: a non-modal tmux split pane when we're
+ * in tmux on a video-capable terminal, else a spawned mpv window.
+ */
+export function planVideoPlayback(url, opts) {
+    if (opts.inTmux && opts.videoCapable) {
+        return { strategy: 'tmux-pane', spec: buildTmuxPaneVideo(url) };
+    }
+    return { strategy: 'spawn-window', spec: buildSpawnWindowVideo(url, opts.platform) };
+}

package/dist/user-auth.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Agent-ads user-JWT authentication.
+ *
+ * The agent-ads surface authenticates as the DEVELOPER (a Trillboards user),
+ * NOT the partner. The virtual-screen register route only accepts a user JWT
+ * (`Authorization: Bearer <JWT>` via middleware/auth.js verifyToken) — the
+ * partner `api_key` does not work there. So we maintain a separate token pair:
+ *   - user_token            (access JWT, 1h TTL)
+ *   - user_refresh_token    (refresh token, 90d TTL)
+ *
+ * Tokens are stored in ~/.trillboards/config.json (same file/perms as api_key)
+ * and are NEVER logged.
+ */
+/** deviceType sent to /v1/user/login + /v1/user/refresh-token (the route requires it). */
+export declare const AGENT_CLI_DEVICE_TYPE = "agent_cli";
+export interface LoginResult {
+    token: string;
+    refreshToken: string;
+    /** Seconds until the access token expires (server returns 3600). */
+    expiresIn: number;
+}
+/**
+ * POST /v1/user/login {email, password, deviceType} → {token, refreshToken, expiresIn}.
+ *
+ * Throws TrillboardsApiError on non-2xx (401 invalid creds, 404 no user, etc.).
+ */
+export declare function loginUser(baseUrl: string, email: string, password: string): Promise<LoginResult>;
+export interface RefreshResult {
+    /** New access token. NOTE: refresh returns `accessToken`, login returns `token`. */
+    token: string;
+    refreshToken: string;
+    expiresIn: number;
+}
+/**
+ * POST /v1/user/refresh-token {refreshToken, deviceType} → {accessToken, refreshToken, expiresIn}.
+ *
+ * Tokens are rotated: a NEW refresh token comes back too and must be persisted.
+ */
+export declare function refreshUserToken(baseUrl: string, refreshToken: string): Promise<RefreshResult>;
+/** Persist a login/refresh result to config (token, refresh token, computed expiry). */
+export declare function persistTokens(result: {
+    token: string;
+    refreshToken: string;
+    expiresIn: number;
+}): void;
+/**
+ * Resolve the active user JWT, refreshing it first if it is missing an expiry,
+ * expired, or within the refresh skew window. Returns the valid access token, or
+ * `null` if there is no usable credential (caller should tell the user to log in).
+ *
+ * Precedence:
+ *   1. TRILLBOARDS_USER_TOKEN env (headless paste — used verbatim, never refreshed)
+ *   2. config.user_token (refreshed via config.user_refresh_token when stale)
+ */
+export declare function refreshUserTokenIfNeeded(baseUrl: string): Promise<string | null>;
+/** Expose the access-token TTL for tests / callers that want to set expiry. */
+export declare const ACCESS_TOKEN_TTL: number;

package/dist/user-auth.js

@@ -0,0 +1,110 @@
+/**
+ * Agent-ads user-JWT authentication.
+ *
+ * The agent-ads surface authenticates as the DEVELOPER (a Trillboards user),
+ * NOT the partner. The virtual-screen register route only accepts a user JWT
+ * (`Authorization: Bearer <JWT>` via middleware/auth.js verifyToken) — the
+ * partner `api_key` does not work there. So we maintain a separate token pair:
+ *   - user_token            (access JWT, 1h TTL)
+ *   - user_refresh_token    (refresh token, 90d TTL)
+ *
+ * Tokens are stored in ~/.trillboards/config.json (same file/perms as api_key)
+ * and are NEVER logged.
+ */
+import { readConfig, updateConfig } from './config.js';
+import { TrillboardsApiError, apiRequest } from './http.js';
+/** deviceType sent to /v1/user/login + /v1/user/refresh-token (the route requires it). */
+export const AGENT_CLI_DEVICE_TYPE = 'agent_cli';
+/** Access-token TTL in ms (server issues 1h tokens; expiresIn=3600). */
+const ACCESS_TOKEN_TTL_MS = 3600 * 1000;
+/** Refresh proactively when within this window of expiry (5 minutes). */
+const REFRESH_SKEW_MS = 5 * 60 * 1000;
+/**
+ * POST /v1/user/login {email, password, deviceType} → {token, refreshToken, expiresIn}.
+ *
+ * Throws TrillboardsApiError on non-2xx (401 invalid creds, 404 no user, etc.).
+ */
+export async function loginUser(baseUrl, email, password) {
+    const res = (await apiRequest('POST', '/v1/user/login', {
+        baseUrl,
+        body: { email, password, deviceType: AGENT_CLI_DEVICE_TYPE },
+    }));
+    const token = typeof res.token === 'string' ? res.token : '';
+    const refreshToken = typeof res.refreshToken === 'string' ? res.refreshToken : '';
+    if (!token || !refreshToken) {
+        throw new TrillboardsApiError('Login succeeded but no token was returned', 'LOGIN_NO_TOKEN', 502);
+    }
+    const expiresIn = typeof res.expiresIn === 'number' && res.expiresIn > 0 ? res.expiresIn : 3600;
+    return { token, refreshToken, expiresIn };
+}
+/**
+ * POST /v1/user/refresh-token {refreshToken, deviceType} → {accessToken, refreshToken, expiresIn}.
+ *
+ * Tokens are rotated: a NEW refresh token comes back too and must be persisted.
+ */
+export async function refreshUserToken(baseUrl, refreshToken) {
+    const res = (await apiRequest('POST', '/v1/user/refresh-token', {
+        baseUrl,
+        body: { refreshToken, deviceType: AGENT_CLI_DEVICE_TYPE },
+    }));
+    // Refresh response uses `accessToken` (asymmetric vs login's `token`).
+    const token = typeof res.accessToken === 'string' ? res.accessToken : '';
+    const newRefresh = typeof res.refreshToken === 'string' ? res.refreshToken : '';
+    if (!token) {
+        throw new TrillboardsApiError('Refresh succeeded but no access token was returned', 'REFRESH_NO_TOKEN', 502);
+    }
+    const expiresIn = typeof res.expiresIn === 'number' && res.expiresIn > 0 ? res.expiresIn : 3600;
+    // Keep the existing refresh token if the server somehow omitted a rotated one.
+    return { token, refreshToken: newRefresh || refreshToken, expiresIn };
+}
+/** Persist a login/refresh result to config (token, refresh token, computed expiry). */
+export function persistTokens(result) {
+    updateConfig({
+        user_token: result.token,
+        user_refresh_token: result.refreshToken,
+        user_token_expires_at: Date.now() + result.expiresIn * 1000,
+    });
+}
+/**
+ * Resolve the active user JWT, refreshing it first if it is missing an expiry,
+ * expired, or within the refresh skew window. Returns the valid access token, or
+ * `null` if there is no usable credential (caller should tell the user to log in).
+ *
+ * Precedence:
+ *   1. TRILLBOARDS_USER_TOKEN env (headless paste — used verbatim, never refreshed)
+ *   2. config.user_token (refreshed via config.user_refresh_token when stale)
+ */
+export async function refreshUserTokenIfNeeded(baseUrl) {
+    const envToken = process.env.TRILLBOARDS_USER_TOKEN;
+    if (envToken && envToken.trim()) {
+        // Caller supplied a raw JWT; we have no refresh token for it, so use as-is.
+        return envToken.trim();
+    }
+    const cfg = readConfig();
+    const token = cfg.user_token;
+    const refreshToken = cfg.user_refresh_token;
+    if (!token)
+        return null;
+    const expiresAt = cfg.user_token_expires_at;
+    const nearExpiry = typeof expiresAt !== 'number' || Number.isNaN(expiresAt) || Date.now() >= expiresAt - REFRESH_SKEW_MS;
+    if (!nearExpiry) {
+        return token;
+    }
+    // Token is stale/near-expiry. Refresh if we can; otherwise return what we have
+    // and let the downstream 401 surface a clear re-login prompt.
+    if (!refreshToken)
+        return token;
+    try {
+        const refreshed = await refreshUserToken(baseUrl, refreshToken);
+        persistTokens(refreshed);
+        return refreshed.token;
+    }
+    catch {
+        // Refresh failed (expired/rotated/revoked refresh token). Fall back to the
+        // current access token; if it is also dead the API call will 401 and the
+        // command will instruct the user to run `trillboards ads login`.
+        return token;
+    }
+}
+/** Expose the access-token TTL for tests / callers that want to set expiry. */
+export const ACCESS_TOKEN_TTL = ACCESS_TOKEN_TTL_MS;