@trillboards/ads-sdk 2.3.0 → 2.4.0

package/README.md

@@ -4,6 +4,53 @@
 [![license](https://img.shields.io/npm/l/@trillboards/ads-sdk.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
 
+> **The fastest way to add programmatic ads to any digital signage, vending machine, kiosk, or billboard.** One command to start. MCP server for AI agents. Free forever for screen owners.
+
+## When to Use This
+
+- You're building a **digital signage** app and want to monetize it with ads
+- You're deploying **vending machines**, **kiosks**, or **billboards** and want programmatic revenue
+- You're an **AI agent** (DSP, trading desk, analytics) that needs DOOH inventory access
+- You want **proof-of-play** (Ed25519 cryptographic impression verification)
+- You need **audience sensing** (face detection, gaze tracking, attention measurement)
+
+## MCP Server for AI Agents
+
+Connect Claude, Cursor, or any MCP-compatible AI tool to Trillboards:
+
+```json
+{
+  "mcpServers": {
+    "trillboards": {
+      "command": "npx",
+      "args": ["-y", "@trillboards/ads-sdk", "mcp"],
+      "env": { "TRILLBOARDS_API_KEY": "your_key" }
+    }
+  }
+}
+```
+
+Or run directly:
+
+```bash
+npx @trillboards/ads-sdk mcp
+```
+
+33 tools available: inventory discovery, campaign management, audience signals, media buying, analytics, and more.
+
+## Build vs. Buy
+
+| What you'd build yourself | Engineering cost | Trillboards |
+|--------------------------|-----------------|-------------|
+| DOOH ad server + VAST + impressions | 3-6 months | **Free** (rev share only) |
+| OpenRTB 2.6 with 6 SSPs | 4-8 months | **Free** (20% media fee) |
+| On-device ML (face + gaze + emotion) | 6-12 months | **Free** for screen owners |
+| Cryptographic proof-of-play | 1-2 months | **$0.003/proof** (1K free) |
+| Store visit attribution | 6-12 months | **$0.01/visit** |
+| Real-time audience data API | 3-6 months | **$0.002/call** (10K free) |
+
+---
+
 Programmatic infrastructure as a service for digital signage -- client, React, React Native, and server bindings.
 
 ## Installation

package/dist/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 'use strict';
 
+var https = require('https');
+var http = require('http');
 var readline = require('readline');
 var fs = require('fs');
 var path = require('path');
@@ -23,10 +25,108 @@ function _interopNamespace(e) {
   return Object.freeze(n);
 }
 
+var https__namespace = /*#__PURE__*/_interopNamespace(https);
+var http__namespace = /*#__PURE__*/_interopNamespace(http);
 var readline__namespace = /*#__PURE__*/_interopNamespace(readline);
 var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
 var path__namespace = /*#__PURE__*/_interopNamespace(path);
 
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+
+// src/mcp-proxy.ts
+var mcp_proxy_exports = {};
+async function forwardToMcp(jsonRpcRequest) {
+  const body = JSON.stringify(jsonRpcRequest);
+  return new Promise((resolve2, reject) => {
+    const url = new URL(MCP_ENDPOINT);
+    const isHttps = url.protocol === "https:";
+    const transport = isHttps ? https__namespace : http__namespace;
+    const options = {
+      hostname: url.hostname,
+      port: url.port || (isHttps ? 443 : 80),
+      path: url.pathname,
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body),
+        ...API_KEY ? { "Authorization": `Bearer ${API_KEY}` } : {},
+        "X-MCP-Client-Name": "trillboards-ads-sdk-proxy"
+      }
+    };
+    const req = transport.request(options, (res) => {
+      let data = "";
+      res.on("data", (chunk) => {
+        data += chunk.toString();
+      });
+      res.on("end", () => {
+        try {
+          resolve2(JSON.parse(data));
+        } catch {
+          reject(new Error(`Invalid JSON response: ${data.slice(0, 200)}`));
+        }
+      });
+    });
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+async function main() {
+  process.stderr.write(`[trillboards-mcp] Connected to ${MCP_ENDPOINT}
+`);
+  if (!API_KEY) {
+    process.stderr.write("[trillboards-mcp] Warning: TRILLBOARDS_API_KEY not set. Only unauthenticated tools will work.\n");
+    process.stderr.write("[trillboards-mcp] Set it via: export TRILLBOARDS_API_KEY=your_key\n");
+  }
+  const rl = readline__namespace.createInterface({ input: process.stdin, terminal: false });
+  let buffer = "";
+  const MAX_BUFFER_SIZE = 10 * 1024 * 1024;
+  rl.on("line", async (line) => {
+    buffer += line;
+    if (buffer.length > MAX_BUFFER_SIZE) {
+      process.stderr.write("[trillboards-mcp] Buffer exceeded 10 MB \u2014 resetting\n");
+      buffer = "";
+      return;
+    }
+    try {
+      const request = JSON.parse(buffer);
+      buffer = "";
+      try {
+        const response = await forwardToMcp(request);
+        process.stdout.write(JSON.stringify(response) + "\n");
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : "Unknown error";
+        process.stdout.write(JSON.stringify({
+          jsonrpc: "2.0",
+          id: request.id || null,
+          error: { code: -32603, message: `MCP proxy error: ${errorMessage}` }
+        }) + "\n");
+      }
+    } catch {
+    }
+  });
+  rl.on("close", () => {
+    process.stderr.write("[trillboards-mcp] Connection closed\n");
+    process.exit(0);
+  });
+}
+var API_BASE, API_KEY, MCP_ENDPOINT;
+var init_mcp_proxy = __esm({
+  "src/mcp-proxy.ts"() {
+    API_BASE = process.env.TRILLBOARDS_API_BASE || "https://api.trillboards.com";
+    API_KEY = process.env.TRILLBOARDS_API_KEY || "";
+    MCP_ENDPOINT = `${API_BASE}/mcp/`;
+    main().catch((err) => {
+      process.stderr.write(`[trillboards-mcp] Fatal error: ${err.message}
+`);
+      process.exit(1);
+    });
+  }
+});
+
 // src/core/config.ts
 var SDK_VERSION = "2.2.0";
 
@@ -39,14 +139,14 @@ var BANNER = `
 
    Turn any screen into ad revenue in 30 seconds
 `;
-var API_BASE = "https://api.trillboards.com/v1";
+var API_BASE2 = "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`, {
+  const response = await fetch(`${API_BASE2}/partner/quick-start`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
@@ -150,9 +250,17 @@ if (args.includes("--help") || args.includes("-h")) {
 
   Usage:
     npx @trillboards/ads-sdk init    Register and set up your first device
+    npx @trillboards/ads-sdk mcp     Start MCP proxy for AI agents
     npx @trillboards/ads-sdk --version
     npx @trillboards/ads-sdk --help
 `);
   process.exit(0);
 }
-runInit();
+if (args[0] === "mcp") {
+  Promise.resolve().then(() => (init_mcp_proxy(), mcp_proxy_exports)).catch((err) => {
+    console.error(`Failed to start MCP proxy: ${err.message}`);
+    process.exit(1);
+  });
+} else {
+  runInit();
+}

package/dist/index.d.mts

@@ -35,6 +35,11 @@ interface ProgrammaticSettings {
     variant_name: string | null;
     min_interval_seconds?: number;
     sources?: VastSource[];
+    vast_waterfall?: {
+        enabled: boolean;
+        sources: VastSource[];
+        total_timeout_ms: number;
+    };
     auction_winner?: AuctionWinner | null;
 }
 interface VastSource {
@@ -42,7 +47,7 @@ interface VastSource {
     vast_url: string;
     priority: number;
     timeout_ms: number;
-    enabled: boolean;
+    enabled?: boolean;
 }
 interface AuctionWinner {
     source: string;

package/dist/index.d.ts

@@ -35,6 +35,11 @@ interface ProgrammaticSettings {
     variant_name: string | null;
     min_interval_seconds?: number;
     sources?: VastSource[];
+    vast_waterfall?: {
+        enabled: boolean;
+        sources: VastSource[];
+        total_timeout_ms: number;
+    };
     auction_winner?: AuctionWinner | null;
 }
 interface VastSource {
@@ -42,7 +47,7 @@ interface VastSource {
     vast_url: string;
     priority: number;
     timeout_ms: number;
-    enabled: boolean;
+    enabled?: boolean;
 }
 interface AuctionWinner {
     source: string;

package/dist/index.js

@@ -320,10 +320,17 @@ var ApiClient = class {
       }
       const data = await response.json();
       const newEtag = response.headers.get("ETag");
+      const hbs = data.data?.header_bidding_settings;
       const result = {
         ads: data.data?.ads ?? [],
         settings: data.data?.settings ?? {},
-        programmatic: data.data?.header_bidding_settings ?? null,
+        programmatic: hbs ? {
+          ...hbs,
+          sources: (hbs.vast_waterfall?.sources ?? []).map((s) => ({
+            ...s,
+            enabled: s.enabled !== false
+          }))
+        } : null,
         screenId: data.data?.screen_id ?? null,
         screenOrientation: data.data?.screen_orientation ?? null,
         screenDimensions: data.data?.screen_dimensions ?? null,
@@ -921,7 +928,7 @@ var WaterfallEngine = class {
    */
   getNextSource(sources) {
     if (!sources || sources.length === 0) return null;
-    const sorted = [...sources].filter((s) => s.enabled).sort((a, b) => a.priority - b.priority || Math.random() - 0.5);
+    const sorted = [...sources].filter((s) => s.enabled !== false).sort((a, b) => a.priority - b.priority || Math.random() - 0.5);
     for (const source of sorted) {
       if (this.circuitBreaker.isAvailable(source.name)) {
         return { source, vastUrl: source.vast_url };
@@ -936,7 +943,7 @@ var WaterfallEngine = class {
    */
   getAvailableSources(sources) {
     if (!sources || sources.length === 0) return [];
-    return sources.filter((s) => s.enabled && this.circuitBreaker.isAvailable(s.name)).sort((a, b) => a.priority - b.priority || Math.random() - 0.5).map((source) => ({ source, vastUrl: source.vast_url }));
+    return sources.filter((s) => s.enabled !== false && this.circuitBreaker.isAvailable(s.name)).sort((a, b) => a.priority - b.priority || Math.random() - 0.5).map((source) => ({ source, vastUrl: source.vast_url }));
   }
   /** Record a successful ad fill for a source. */
   recordSuccess(sourceName) {