# @trillboards/api-client 中文文档

规范地址：https://npmcn.com/package/%40trillboards/api-client/

版本：3\.2\.23
npm 元数据更新时间：2026-11-02T17:17:13.607Z
中文译文更新时间：2026-11-02T17:39:56.219Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40trillboards/api-client
原文对照：https://npmcn.com/package/%40trillboards/api-client/?lang=original
项目主页：https://trillboards.com/support/developers/typescript-sdk/

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.7 MB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：2 个
- 首次发布：2026-04-16T12:31:25.313Z
- 最新版本发布：2026-11-02T17:17:13.385Z
- 已发布版本数：40（近 12 个月 40 个）

## 中文简介

Trillboards DOOH合作伙伴API的官方TypeScript SDK

## 安装

```sh
npm install @trillboards/api-client
```

也可以使用：`pnpm add @trillboards/api-client`、`yarn add @trillboards/api-client`、`bun add @trillboards/api-client`

## README

# @trillboards / api-client

Trillboards DOOH合作伙伴API的官方TypeScript SDK。

## 安装

```bash
npm install @trillboards/api-client
```

要求Node.js 18+。REST使用本机 `fetch`； 媒体购买使用官方MCP客户端，流媒体使用其共享的SSE解析器。继续在服务器应用程序中购买凭据。

## 快速入门

```typescript
import { TrillboardsClient } from '@trillboards/api-client';

const client = new TrillboardsClient({
  apiKey: 'trb_partner_xxxxx',
});

// List screens
const { data: screens } = await client.screens.list({ limit: 10 });

// Get analytics
const { data: analytics } = await client.analytics.get({ period: 'week' });

// Get earnings
const { data: earnings } = await client.earnings.get({ period: 'month' });
```

## 资源

| 资源 | 方法 |
| --- | --- |
| `client.screens` | `list`， `get`， `create`， `delete`， `getDisplaySettings`， `patchDisplaySettings`， `updateDisplaySettings`， `batchUpdateDisplaySettings` |
| `client.devices` | `list`， `get`， `create`， `createBatch`， `delete`， `heartbeat` |
| `client.impressions` | `create`， `createBatch` |
| `client.analytics` | `get` |
| `client.earnings` | `get` |
| `client.webhooks` | `list`， `create`， `update`， `delete`， `test` |
| `client.fleet` | `pushCommand`， `listCommands` |
| `client.audience` | `getLive`， `getHeatmap`， `getStats` |
| `client.data` | `getVenueIntelligence`， `getUsage`， `listScreens`， `getHistory`， `getAudience`， `query`， `stream` |
| `client.errors` | `list`， `get` |
| `client.billing` | `setup`， `createCreditCheckout`， `purchaseCredits`， `getUsageSummary`， `get`， `getStripeStatus`， `requestPayout` |
| `client.mediaBuys` | `getProducts`， `discoverInventory`， `listAccounts`， `syncAccounts`， `create`， `list`， `update`， `syncCreatives`， `getDelivery`， `close` |
| `client.creativeExperiments` | `create`， `get`， `configureBrand`， `generate`， `importCreative`， `review`， `registerVariants`， `updatePolicy`， `getRewards`， `stop` |

## 建立并运行一个创造性的反馈循环

使用 [创造性的AI反馈循环](https://api.trillboards.com/docs/guides/integrations/creative-feedback) 对于完整的购买，创造性的评论，服务和纠正意识奖励的例子。相同的合作伙伴密钥适用于REST和本地MCP购买工具。

创建一个信用结帐与稳定的关键为这个确切的购买，然后打开返回的条纹URL：

```typescript
const checkout = await client.billing.createCreditCheckout(
  { tier: 'tier_500' },
  { idempotencyKey: 'my-first-credit-checkout-v1' },
);
console.log(checkout.checkout_url);
```

付款完成后，读取承诺余额：

```typescript
const balance = await client.billing.getUsageSummary();
console.log(balance.credit_balance_cents, balance.credit_reserved_cents);
```

余额和计量金额保留其精确的十进制字符串。节省的付款方式本身并不能为交付提供资金。媒体使用其认可的引用；API使用使用已发布的API收费标准。

直接 `purchaseCredits` 可以返回 `requires_action: true` 与一个 `client_secret`。完成支付的Stripe认证，然后读取已提交的余额；保持其 `operation_id` 和稳定键。SDK不加更改地返回这些字段。Stripe Checkout在返回的浏览器流中处理身份验证。

在创建购买之前，发现您的帐户和实时产品目录：

```typescript
try {
  const accounts = await client.mediaBuys.listAccounts();
  const products = await client.mediaBuys.getProducts({
    brief: 'Transit screens for a creative attention test',
    pagination: { max_results: 10 },
  });
  console.log(accounts.accounts, products.products, products.pagination);
} finally {
  await client.mediaBuys.close();
}
```

`client.mediaBuys.create` 接受原生AdCP请求，包括帐户、航班、产品/定价选项标识符、预算和稳定性 `idempotency_key`. `list` 接受 `media_buy_ids` 和分页; `update` 接受本机修订。保存 `media_buy_id` 和 `packages[].package_id` 用于 `creativeExperiments.create`。MCP任务 `status` 描述任务执行情况；返回的媒体购买生命周期、资金和节制描述了交付准备情况。始终释放MCP连接 `mediaBuys.close()` 当完成。

## 历史数据和实时数据

Data API资源需要其端点声明的作用域： `read:live`， `read:historical` 或者 `stream:live`。屏幕列表分页将不变地返回为 `has_more` 和 `next_offset`。有限的历史读取保存了未测量的值 `null`.

```typescript
const history = await client.data.getHistory('YOUR_SCREEN_ID', {
  since: '2026-10-01T00:00:00Z',
  until: '2026-10-02T00:00:00Z',
  limit: 100,
});
console.log(history.metrics);

const controller = new AbortController();
try {
  for await (const event of client.data.stream({}, { signal: controller.signal })) {
    console.log(event.event, event.data);
    if (event.event === 'audience') break;
  }
} finally {
  controller.abort();
}
```

向前流 `connected`， `audience` 和带内 `error` 事件。中断迭代或中止将关闭连接。它是一个活动尾巴：显式地重新连接并使用有界的历史读取来恢复历史数据。创造性的奖励更正使用指南的标准密钥/修订扫描协议。

MCP工具故障抛出 `McpToolError` 用精确的 `tool` 和原始 `result`，包括结构化错误代码和收据。来自官方MCP传输的协议/HTTP错误保持不变。REST故障使用 `TrillboardsError`.

### 内容符合

```typescript
await client.screens.patchDisplaySettings('SCREEN_ID', {
  content_fit: {
    advertisements: 'fill',
    default_streams: 'fill',
    self_promo: 'fit',
  },
});

await client.devices.createBatch({
  defaults: {
    display_settings: {
      content_fit: { advertisements: 'fill', self_promo: 'fill' },
    },
  },
  devices: [
    { device_id: 'screen-001' },
    {
      device_id: 'screen-002',
      display_settings: { content_fit: { self_promo: 'fit' } },
    },
  ],
});
```

`fit` 保留了充分的创意和可能的信箱； `fill` 覆盖屏幕 并可能剪掉它的边缘。省略 `content_fit` 保持现有的行为不变。

## 错误处理

```typescript
import { TrillboardsClient, TrillboardsError } from '@trillboards/api-client';

try {
  await client.screens.get('nonexistent');
} catch (err) {
  if (err instanceof TrillboardsError) {
    console.log(err.code);       // 'screen_not_found'
    console.log(err.statusCode); // 404
    console.log(err.docsUrl);    // 'https://api.trillboards.com/docs/errors#screen_not_found'

    if (err.isRateLimited) {
      const retryAfter = err.retryAfter; // seconds from Retry-After header
    }
  }
}
```

## Webhook验证

Trillboards网钩带有条纹样式的复合签名头 `X-Trillboards-Signature: t=<timestamp>,v0=<hex>,v1=<hex>` 还有一个单独的 `X-Trillboards-Timestamp: <unix_seconds>` 为冗余。

验证器接受任意一种格式，并在300秒之外拒绝有效载荷 默认为重播窗口。

```typescript
import { Webhooks } from '@trillboards/api-client';

// Use express.raw for the webhook route so req.body is the exact signed bytes
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = Webhooks.constructEvent(
      req.body,                              // raw Buffer or string (NOT JSON.parsed)
      req.headers,                           // IncomingHttpHeaders — case-insensitive lookup
      process.env.WEBHOOK_SECRET!,
    );
    console.log('Event:', event.event, event.data);
    res.sendStatus(200);
  } catch (err) {
    // TrillboardsError with code "webhook_signature_invalid"
    res.sendStatus(401);
  }
});
```

覆盖重放窗口公差（默认300秒）：

```typescript
const event = Webhooks.constructEvent(req.body, req.headers, secret, {
  tolerance: 600, // 10 minutes
});
```

> **从0.2.0升级**： 0.2.0调用形状 `Webhooks.constructEvent(payload, signatureString, secret)` 生产 针对生产服务器的验证失败，因为服务器 迹象 `${timestamp}.${payload}` 而0.2.0验证者签名 `payload` 只有。0.3.0的验证器处理两种格式，并增加了重放保护。 迁移到新环境 `Webhooks.constructEvent(payload, req.headers, secret)` 电话的形状。0.2.0形状保留为 `Webhooks.constructEventLegacy` 对于一个次要版本（记录弃用警告）。

完整的webhook合同： [https://api.trillboards.com/docs/integrations/webhook-signature-verification.md](https://api.trillboards.com/docs/integrations/webhook-signature-verification.md)

## 配置

```typescript
const client = new TrillboardsClient({
  apiKey: 'trb_partner_xxxxx',       // Required
  baseUrl: 'https://api.trillboards.com', // Optional, defaults to production
  version: '2024-01-15',            // Optional, sent as Trillboards-Version header
});
```

## 许可证

麻省理工学院

## 常见问题

### @trillboards/api-client 是什么？

Trillboards DOOH合作伙伴API的官方TypeScript SDK

### 如何安装 @trillboards/api-client？

在项目目录运行 npm install @trillboards/api-client，或使用 pnpm add / yarn add / bun add。

### @trillboards/api-client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @trillboards/api-client 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @trillboards/api-client 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @trillboards/api-client 可以商用吗？

@trillboards/api-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @trillboards/api-client 还在维护吗？

最新版本 3\.2\.23 发布于 2026/11/03（今天）；至今共发布 40 个版本，其中过去 12 个月发布了 40 个；首次发布于 2026/04/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。