@trillboards/api-client 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# @trillboards/api-client
+
+Official TypeScript SDK for the Trillboards DOOH Partner API.
+
+## Installation
+
+```bash
+npm install @trillboards/api-client
+```
+
+Requires Node.js 18+ (uses native `fetch` and `crypto`). Zero runtime dependencies.
+
+## Quick Start
+
+```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' });
+```
+
+## Resources
+
+| Resource | Methods |
+|----------|---------|
+| `client.screens` | `list`, `get`, `create`, `delete` |
+| `client.devices` | `list`, `get`, `create`, `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` |
+| `client.errors` | `list`, `get` |
+| `client.billing` | `get`, `getStripeStatus`, `requestPayout` |
+
+## Error Handling
+
+```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 Verification
+
+```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);
+});
+```
+
+## Configuration
+
+```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
+});
+```
+
+## License
+
+MIT