@dispatchtickets/sdk 0.3.0 → 0.6.0

package/README.md

@@ -44,12 +44,44 @@ 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
@@ -303,30 +335,36 @@ 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:
@@ -427,6 +465,16 @@ See the `/examples` directory for complete working examples:
 - **[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)