@trillboards/api-client 0.2.0 → 0.4.1

package/README.md

@@ -33,8 +33,8 @@ const { data: earnings } = await client.earnings.get({ period: 'month' });
 
 | Resource | Methods |
 |----------|---------|
-| `client.screens` | `list`, `get`, `create`, `delete` |
-| `client.devices` | `list`, `get`, `create`, `delete`, `heartbeat` |
+| `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` |
@@ -45,6 +45,36 @@ const { data: earnings } = await client.earnings.get({ period: 'month' });
 | `client.errors` | `list`, `get` |
 | `client.billing` | `get`, `getStripeStatus`, `requestPayout` |
 
+### Content fit
+
+```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` preserves the full creative and may letterbox; `fill` covers the screen
+and may crop its edges. Omit `content_fit` to leave existing behavior unchanged.
+
 ## Error Handling
 
 ```typescript
@@ -67,20 +97,52 @@ try {
 
 ## Webhook Verification
 
+Trillboards webhooks carry a Stripe-style compound signature header
+`X-Trillboards-Signature: t=<timestamp>,v0=<hex>,v1=<hex>` and a separate
+`X-Trillboards-Timestamp: <unix_seconds>` for redundancy.
+
+The verifier accepts either format and rejects payloads outside a 300-second
+replay window by default.
+
 ```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('Event:', event.type, event.data);
-  res.sendStatus(200);
+// 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.type, event.data);
+    res.sendStatus(200);
+  } catch (err) {
+    // TrillboardsError with code "webhook_signature_invalid"
+    res.sendStatus(401);
+  }
 });
 ```
 
+Override the replay-window tolerance (default 300s):
+
+```typescript
+const event = Webhooks.constructEvent(req.body, req.headers, secret, {
+  tolerance: 600, // 10 minutes
+});
+```
+
+> **Upgrading from 0.2.0**: the 0.2.0 call shape
+> `Webhooks.constructEvent(payload, signatureString, secret)` produced
+> verification failures against the production server because the server
+> signs `${timestamp}.${payload}` while the 0.2.0 verifier signed `payload`
+> only. The 0.3.0 verifier handles both formats AND adds replay protection.
+> Migrate to the new `Webhooks.constructEvent(payload, req.headers, secret)`
+> call shape. The 0.2.0 shape is preserved as `Webhooks.constructEventLegacy`
+> for one minor version (logs a deprecation warning).
+
+Full webhook contract: https://api.trillboards.com/docs/integrations/webhook-signature-verification.md
+
 ## Configuration
 
 ```typescript