@dispatchtickets/sdk 0.1.0 → 0.5.0

package/README.md

@@ -44,16 +44,83 @@ const client = new DispatchTickets({
   apiKey: 'sk_live_...',        // Required
   baseUrl: 'https://...',        // Optional, default: production API
   timeout: 30000,                // Optional, request timeout in ms
-  maxRetries: 3,                 // Optional, retry count for failed requests
   debug: false,                  // Optional, enable debug logging
+  fetch: customFetch,            // Optional, custom fetch for testing
+  retry: {                       // Optional, fine-grained retry config
+    maxRetries: 3,
+    retryableStatuses: [429, 500, 502, 503, 504],
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
+  },
+  hooks: {                       // Optional, observability hooks
+    onRequest: (ctx) => console.log(`${ctx.method} ${ctx.url}`),
+    onResponse: (ctx) => console.log(`${ctx.status} in ${ctx.durationMs}ms`),
+    onError: (error) => Sentry.captureException(error),
+    onRetry: (ctx, error, delay) => console.log(`Retrying in ${delay}ms`),
+  },
 });
 ```
 
+### Request Cancellation
+
+Cancel long-running requests with an AbortController:
+
+```typescript
+const controller = new AbortController();
+
+// Cancel after 5 seconds
+setTimeout(() => controller.abort(), 5000);
+
+try {
+  const page = await client.tickets.listPage('ws_abc', {}, {
+    signal: controller.signal,
+  });
+} catch (error) {
+  if (error.message.includes('aborted')) {
+    console.log('Request was cancelled');
+  }
+}
+```
+
 ## Resources
 
+### Accounts
+
+```typescript
+// Get current account
+const account = await client.accounts.me();
+
+// Get usage statistics
+const usage = await client.accounts.getUsage();
+console.log(`${usage.ticketsThisMonth}/${usage.plan?.ticketLimit} tickets used`);
+
+// List API keys
+const apiKeys = await client.accounts.listApiKeys();
+
+// Create a new API key
+const newKey = await client.accounts.createApiKey({
+  name: 'Production',
+  allBrands: true,  // or brandIds: ['br_123']
+});
+console.log('Save this key:', newKey.key); // Only shown once!
+
+// Update API key scope
+await client.accounts.updateApiKeyScope('key_abc', {
+  allBrands: false,
+  brandIds: ['br_123', 'br_456'],
+});
+
+// Revoke an API key
+await client.accounts.revokeApiKey('key_abc');
+```
+
 ### Brands
 
 ```typescript
+// Get inbound email address for a brand
+const inboundEmail = client.brands.getInboundEmail('br_abc123');
+// Returns: br_abc123@inbound.dispatchtickets.com
+
 // Create a brand
 const brand = await client.brands.create({
   name: 'Acme Support',
@@ -268,30 +335,73 @@ await client.fields.delete('ws_abc123', 'ticket', 'order_id');
 
 ## Error Handling
 
+Use type guards for clean error handling:
+
 ```typescript
 import {
   DispatchTickets,
-  AuthenticationError,
-  RateLimitError,
-  ValidationError,
-  NotFoundError,
+  isNotFoundError,
+  isAuthenticationError,
+  isRateLimitError,
+  isValidationError,
 } from '@dispatchtickets/sdk';
 
 try {
   await client.tickets.get('ws_abc123', 'tkt_invalid');
 } catch (error) {
-  if (error instanceof NotFoundError) {
+  if (isNotFoundError(error)) {
     console.log('Ticket not found');
-  } else if (error instanceof AuthenticationError) {
+    console.log('Request ID:', error.requestId); // For debugging with support
+  } else if (isAuthenticationError(error)) {
     console.log('Invalid API key');
-  } else if (error instanceof RateLimitError) {
+  } else if (isRateLimitError(error)) {
     console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
-  } else if (error instanceof ValidationError) {
+    console.log(`Limit: ${error.limit}, Remaining: ${error.remaining}`);
+  } else if (isValidationError(error)) {
     console.log('Validation errors:', error.errors);
   }
 }
 ```
 
+All errors include a `requestId` for debugging with support.
+
+## Webhook Events
+
+Handle webhook events with full type safety:
+
+```typescript
+import {
+  DispatchTickets,
+  parseWebhookEvent,
+  isTicketCreatedEvent,
+  isTicketUpdatedEvent,
+  isCommentCreatedEvent,
+} from '@dispatchtickets/sdk';
+
+// Parse and validate webhook payload
+const event = parseWebhookEvent(req.body);
+
+// Use type guards for type-safe event handling
+if (isTicketCreatedEvent(event)) {
+  // event.data is typed as TicketCreatedData
+  console.log('New ticket:', event.data.title);
+  console.log('Priority:', event.data.priority);
+  console.log('Customer:', event.data.customerEmail);
+}
+
+if (isTicketUpdatedEvent(event)) {
+  // event.data is typed as TicketUpdatedData
+  console.log('Ticket updated:', event.data.id);
+  console.log('Changed fields:', event.data.changes);
+}
+
+if (isCommentCreatedEvent(event)) {
+  // event.data is typed as CommentCreatedData
+  console.log('New comment on', event.data.ticketNumber);
+  console.log('Author:', event.data.comment.authorType);
+}
+```
+
 ## Webhook Verification
 
 ```typescript
@@ -322,6 +432,55 @@ app.post('/webhooks', (req, res) => {
 });
 ```
 
+## Testing
+
+Use the custom `fetch` option to mock API responses in tests:
+
+```typescript
+import { DispatchTickets } from '@dispatchtickets/sdk';
+import { vi } from 'vitest';
+
+const mockFetch = vi.fn().mockResolvedValue({
+  ok: true,
+  status: 200,
+  headers: { get: () => 'application/json' },
+  json: () => Promise.resolve([{ id: 'br_123', name: 'Test' }]),
+});
+
+const client = new DispatchTickets({
+  apiKey: 'sk_test_123',
+  fetch: mockFetch,
+});
+
+const brands = await client.brands.list();
+expect(brands).toHaveLength(1);
+expect(mockFetch).toHaveBeenCalled();
+```
+
+## Examples
+
+See the `/examples` directory for complete working examples:
+
+- **[express-webhook.ts](./examples/express-webhook.ts)** - Express.js webhook handler with signature verification
+- **[nextjs-api-route.ts](./examples/nextjs-api-route.ts)** - Next.js App Router webhook handler
+- **[basic-usage.ts](./examples/basic-usage.ts)** - Common SDK operations (tickets, comments, pagination)
+
+## API Documentation
+
+Generate TypeDoc API documentation locally:
+
+```bash
+npm run docs
+```
+
+This creates a `docs/` folder with HTML documentation for all exported types and methods.
+
+## Links
+
+- [API Reference (Swagger)](https://dispatch-tickets-api.onrender.com/docs)
+- [GitHub](https://github.com/Epic-Design-Labs/app-dispatchtickets-sdk)
+- [Changelog](./CHANGELOG.md)
+
 ## License
 
 MIT