@trillboards/api-client 0.1.3 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Trillboards, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -67,20 +67,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