@dispatchtickets/sdk 0.1.0 → 0.3.0

package/README.md

@@ -46,14 +46,49 @@ const client = new DispatchTickets({
   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
 });
 ```
 
 ## 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',
@@ -292,6 +327,43 @@ try {
 }
 ```
 
+## 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 +394,45 @@ 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)
+
+## 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

package/dist/index.cjs

@@ -76,8 +76,10 @@ var NetworkError = class extends DispatchTicketsError {
 // src/utils/http.ts
 var HttpClient = class {
   config;
+  fetchFn;
   constructor(config) {
     this.config = config;
+    this.fetchFn = config.fetch ?? fetch;
   }
   /**
    * Execute an HTTP request with retry logic
@@ -157,7 +159,7 @@ var HttpClient = class {
           console.log("[DispatchTickets] Body:", JSON.stringify(body, null, 2));
         }
       }
-      const response = await fetch(url, {
+      const response = await this.fetchFn(url, {
         method,
         headers,
         body: body ? JSON.stringify(body) : void 0,
@@ -270,6 +272,52 @@ var BaseResource = class {
   }
 };
 
+// src/resources/accounts.ts
+var AccountsResource = class extends BaseResource {
+  /**
+   * Get the current account
+   */
+  async me() {
+    return this._get("/accounts/me");
+  }
+  /**
+   * Get usage statistics for the current account
+   */
+  async getUsage() {
+    return this._get("/accounts/me/usage");
+  }
+  /**
+   * List all API keys for the current account
+   */
+  async listApiKeys() {
+    return this._get("/accounts/me/api-keys");
+  }
+  /**
+   * Create a new API key
+   *
+   * Note: The full key value is only returned once on creation.
+   * Store it securely as it cannot be retrieved again.
+   */
+  async createApiKey(data) {
+    return this._post("/accounts/me/api-keys", data);
+  }
+  /**
+   * Update the brand scope for an API key
+   */
+  async updateApiKeyScope(keyId, data) {
+    return this._patch(
+      `/accounts/me/api-keys/${keyId}/scope`,
+      data
+    );
+  }
+  /**
+   * Revoke an API key
+   */
+  async revokeApiKey(keyId) {
+    await this._delete(`/accounts/me/api-keys/${keyId}`);
+  }
+};
+
 // src/resources/brands.ts
 var BrandsResource = class extends BaseResource {
   /**
@@ -320,6 +368,28 @@ var BrandsResource = class extends BaseResource {
   async updateSchema(brandId, schema) {
     return this._put(`/brands/${brandId}/schema`, schema);
   }
+  /**
+   * Get the inbound email address for a brand
+   *
+   * Emails sent to this address will automatically create tickets.
+   *
+   * @param brandId - The brand ID
+   * @param domain - Optional custom inbound domain (default: inbound.dispatchtickets.com)
+   * @returns The inbound email address
+   *
+   * @example
+   * ```typescript
+   * const email = client.brands.getInboundEmail('br_abc123');
+   * // Returns: br_abc123@inbound.dispatchtickets.com
+   *
+   * // With custom domain:
+   * const customEmail = client.brands.getInboundEmail('br_abc123', 'support.mycompany.com');
+   * // Returns: br_abc123@support.mycompany.com
+   * ```
+   */
+  getInboundEmail(brandId, domain = "inbound.dispatchtickets.com") {
+    return `${brandId}@${domain}`;
+  }
 };
 
 // src/resources/tickets.ts
@@ -834,6 +904,10 @@ var webhookUtils = {
 // src/client.ts
 var DispatchTickets = class {
   http;
+  /**
+   * Accounts resource for managing the current account and API keys
+   */
+  accounts;
   /**
    * Brands (workspaces) resource
    */
@@ -883,9 +957,11 @@ var DispatchTickets = class {
       apiKey: config.apiKey,
       timeout: config.timeout ?? 3e4,
       maxRetries: config.maxRetries ?? 3,
-      debug: config.debug ?? false
+      debug: config.debug ?? false,
+      fetch: config.fetch
     };
     this.http = new HttpClient(httpConfig);
+    this.accounts = new AccountsResource(this.http);
     this.brands = new BrandsResource(this.http);
     this.tickets = new TicketsResource(this.http);
     this.comments = new CommentsResource(this.http);
@@ -898,6 +974,37 @@ var DispatchTickets = class {
   }
 };
 
+// src/types/events.ts
+function isTicketCreatedEvent(event) {
+  return event.event === "ticket.created";
+}
+function isTicketUpdatedEvent(event) {
+  return event.event === "ticket.updated";
+}
+function isCommentCreatedEvent(event) {
+  return event.event === "ticket.comment.created";
+}
+function parseWebhookEvent(payload) {
+  const event = typeof payload === "string" ? JSON.parse(payload) : payload;
+  if (!event || typeof event !== "object") {
+    throw new Error("Invalid webhook payload: expected object");
+  }
+  if (!event.event || typeof event.event !== "string") {
+    throw new Error("Invalid webhook payload: missing event type");
+  }
+  if (!event.id || typeof event.id !== "string") {
+    throw new Error("Invalid webhook payload: missing event id");
+  }
+  if (!event.data || typeof event.data !== "object") {
+    throw new Error("Invalid webhook payload: missing data");
+  }
+  const validEvents = ["ticket.created", "ticket.updated", "ticket.comment.created"];
+  if (!validEvents.includes(event.event)) {
+    throw new Error(`Invalid webhook payload: unknown event type "${event.event}"`);
+  }
+  return event;
+}
+
 // src/utils/pagination.ts
 async function collectAll(iterable) {
   const items = [];
@@ -918,6 +1025,10 @@ exports.ServerError = ServerError;
 exports.TimeoutError = TimeoutError;
 exports.ValidationError = ValidationError;
 exports.collectAll = collectAll;
+exports.isCommentCreatedEvent = isCommentCreatedEvent;
+exports.isTicketCreatedEvent = isTicketCreatedEvent;
+exports.isTicketUpdatedEvent = isTicketUpdatedEvent;
+exports.parseWebhookEvent = parseWebhookEvent;
 exports.webhookUtils = webhookUtils;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map