@dispatchtickets/sdk 0.3.0 → 0.5.0

package/dist/index.cjs

@@ -7,33 +7,45 @@ var DispatchTicketsError = class extends Error {
   code;
   statusCode;
   details;
-  constructor(message, code, statusCode, details) {
+  /** Request ID for debugging with support */
+  requestId;
+  constructor(message, code, statusCode, details, requestId) {
     super(message);
     this.name = "DispatchTicketsError";
     this.code = code;
     this.statusCode = statusCode;
     this.details = details;
+    this.requestId = requestId;
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
 var AuthenticationError = class extends DispatchTicketsError {
-  constructor(message = "Invalid or missing API key") {
-    super(message, "authentication_error", 401);
+  constructor(message = "Invalid or missing API key", requestId) {
+    super(message, "authentication_error", 401, void 0, requestId);
     this.name = "AuthenticationError";
   }
 };
 var RateLimitError = class extends DispatchTicketsError {
   retryAfter;
-  constructor(message = "Rate limit exceeded", retryAfter) {
-    super(message, "rate_limit_error", 429);
+  /** Rate limit ceiling */
+  limit;
+  /** Remaining requests in current window */
+  remaining;
+  /** Unix timestamp when rate limit resets */
+  reset;
+  constructor(message = "Rate limit exceeded", retryAfter, requestId, rateLimitInfo) {
+    super(message, "rate_limit_error", 429, void 0, requestId);
     this.name = "RateLimitError";
     this.retryAfter = retryAfter;
+    this.limit = rateLimitInfo?.limit;
+    this.remaining = rateLimitInfo?.remaining;
+    this.reset = rateLimitInfo?.reset;
   }
 };
 var ValidationError = class extends DispatchTicketsError {
   errors;
-  constructor(message = "Validation failed", errors) {
-    super(message, "validation_error", 400, { errors });
+  constructor(message = "Validation failed", errors, requestId) {
+    super(message, "validation_error", 400, { errors }, requestId);
     this.name = "ValidationError";
     this.errors = errors;
   }
@@ -41,22 +53,22 @@ var ValidationError = class extends DispatchTicketsError {
 var NotFoundError = class extends DispatchTicketsError {
   resourceType;
   resourceId;
-  constructor(message = "Resource not found", resourceType, resourceId) {
-    super(message, "not_found", 404, { resourceType, resourceId });
+  constructor(message = "Resource not found", resourceType, resourceId, requestId) {
+    super(message, "not_found", 404, { resourceType, resourceId }, requestId);
     this.name = "NotFoundError";
     this.resourceType = resourceType;
     this.resourceId = resourceId;
   }
 };
 var ConflictError = class extends DispatchTicketsError {
-  constructor(message = "Resource conflict") {
-    super(message, "conflict", 409);
+  constructor(message = "Resource conflict", requestId) {
+    super(message, "conflict", 409, void 0, requestId);
     this.name = "ConflictError";
   }
 };
 var ServerError = class extends DispatchTicketsError {
-  constructor(message = "Internal server error", statusCode = 500) {
-    super(message, "server_error", statusCode);
+  constructor(message = "Internal server error", statusCode = 500, requestId) {
+    super(message, "server_error", statusCode, void 0, requestId);
     this.name = "ServerError";
   }
 };
@@ -72,14 +84,68 @@ var NetworkError = class extends DispatchTicketsError {
     this.name = "NetworkError";
   }
 };
+function isDispatchTicketsError(error) {
+  return error instanceof DispatchTicketsError;
+}
+function isAuthenticationError(error) {
+  return error instanceof AuthenticationError;
+}
+function isRateLimitError(error) {
+  return error instanceof RateLimitError;
+}
+function isValidationError(error) {
+  return error instanceof ValidationError;
+}
+function isNotFoundError(error) {
+  return error instanceof NotFoundError;
+}
+function isConflictError(error) {
+  return error instanceof ConflictError;
+}
+function isServerError(error) {
+  return error instanceof ServerError;
+}
+function isTimeoutError(error) {
+  return error instanceof TimeoutError;
+}
+function isNetworkError(error) {
+  return error instanceof NetworkError;
+}
 
 // src/utils/http.ts
 var HttpClient = class {
   config;
   fetchFn;
+  retryConfig;
+  /** Rate limit info from the last response */
+  _lastRateLimit;
+  /** Request ID from the last response */
+  _lastRequestId;
   constructor(config) {
     this.config = config;
     this.fetchFn = config.fetch ?? fetch;
+    this.retryConfig = {
+      maxRetries: config.retry?.maxRetries ?? config.maxRetries,
+      retryableStatuses: config.retry?.retryableStatuses ?? [429, 500, 502, 503, 504],
+      retryOnNetworkError: config.retry?.retryOnNetworkError ?? true,
+      retryOnTimeout: config.retry?.retryOnTimeout ?? true,
+      initialDelayMs: config.retry?.initialDelayMs ?? 1e3,
+      maxDelayMs: config.retry?.maxDelayMs ?? 3e4,
+      backoffMultiplier: config.retry?.backoffMultiplier ?? 2,
+      jitter: config.retry?.jitter ?? 0.25
+    };
+  }
+  /**
+   * Get rate limit info from the last response
+   */
+  get lastRateLimit() {
+    return this._lastRateLimit;
+  }
+  /**
+   * Get request ID from the last response
+   */
+  get lastRequestId() {
+    return this._lastRequestId;
   }
   /**
    * Execute an HTTP request with retry logic
@@ -89,43 +155,89 @@ var HttpClient = class {
     const headers = this.buildHeaders(options.headers, options.idempotencyKey);
     let lastError;
     let attempt = 0;
-    while (attempt <= this.config.maxRetries) {
+    while (attempt <= this.retryConfig.maxRetries) {
+      const requestContext = {
+        method: options.method,
+        url,
+        headers,
+        body: options.body,
+        attempt
+      };
       try {
-        const response = await this.executeRequest(url, options.method, headers, options.body);
-        return await this.handleResponse(response);
+        if (this.config.hooks?.onRequest) {
+          await this.config.hooks.onRequest(requestContext);
+        }
+        const startTime = Date.now();
+        const response = await this.executeRequest(
+          url,
+          options.method,
+          headers,
+          options.body,
+          options.signal
+        );
+        const durationMs = Date.now() - startTime;
+        const result = await this.handleResponse(response, requestContext, durationMs);
+        return result;
       } catch (error) {
         lastError = error;
-        if (error instanceof DispatchTicketsError) {
-          if (error instanceof AuthenticationError || error instanceof ValidationError || error instanceof NotFoundError || error instanceof ConflictError) {
-            throw error;
-          }
-          if (error instanceof RateLimitError && error.retryAfter) {
-            if (attempt < this.config.maxRetries) {
-              await this.sleep(error.retryAfter * 1e3);
-              attempt++;
-              continue;
-            }
-          }
-          if (error instanceof ServerError) {
-            if (attempt < this.config.maxRetries) {
-              await this.sleep(this.calculateBackoff(attempt));
-              attempt++;
-              continue;
-            }
-          }
+        if (this.config.hooks?.onError) {
+          await this.config.hooks.onError(lastError, requestContext);
         }
-        if (error instanceof NetworkError || error instanceof TimeoutError) {
-          if (attempt < this.config.maxRetries) {
-            await this.sleep(this.calculateBackoff(attempt));
-            attempt++;
-            continue;
+        if (attempt < this.retryConfig.maxRetries && this.shouldRetry(lastError)) {
+          const delay = this.calculateDelay(lastError, attempt);
+          if (this.config.hooks?.onRetry) {
+            await this.config.hooks.onRetry(requestContext, lastError, delay);
           }
+          await this.sleep(delay);
+          attempt++;
+          continue;
         }
-        throw error;
+        throw lastError;
       }
     }
     throw lastError || new NetworkError("Request failed after retries");
   }
+  /**
+   * Execute request and return response with rate limit info
+   */
+  async requestWithRateLimit(options) {
+    const data = await this.request(options);
+    return {
+      data,
+      rateLimit: this._lastRateLimit,
+      requestId: this._lastRequestId
+    };
+  }
+  shouldRetry(error) {
+    if (error instanceof AuthenticationError || error instanceof ValidationError || error instanceof NotFoundError || error instanceof ConflictError) {
+      return false;
+    }
+    if (error instanceof RateLimitError) {
+      return true;
+    }
+    if (error instanceof ServerError && error.statusCode) {
+      return this.retryConfig.retryableStatuses.includes(error.statusCode);
+    }
+    if (error instanceof NetworkError) {
+      return this.retryConfig.retryOnNetworkError;
+    }
+    if (error instanceof TimeoutError) {
+      return this.retryConfig.retryOnTimeout;
+    }
+    return false;
+  }
+  calculateDelay(error, attempt) {
+    if (error instanceof RateLimitError && error.retryAfter) {
+      return error.retryAfter * 1e3;
+    }
+    const baseDelay = this.retryConfig.initialDelayMs;
+    const delay = Math.min(
+      baseDelay * Math.pow(this.retryConfig.backoffMultiplier, attempt),
+      this.retryConfig.maxDelayMs
+    );
+    const jitter = delay * this.retryConfig.jitter * Math.random();
+    return delay + jitter;
+  }
   buildUrl(path, query) {
     const url = new URL(path, this.config.baseUrl);
     if (query) {
@@ -149,9 +261,11 @@ var HttpClient = class {
     }
     return headers;
   }
-  async executeRequest(url, method, headers, body) {
+  async executeRequest(url, method, headers, body, userSignal) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+    const abortHandler = () => controller.abort();
+    userSignal?.addEventListener("abort", abortHandler);
     try {
       if (this.config.debug) {
         console.log(`[DispatchTickets] ${method} ${url}`);
@@ -159,6 +273,9 @@ var HttpClient = class {
           console.log("[DispatchTickets] Body:", JSON.stringify(body, null, 2));
         }
       }
+      if (userSignal?.aborted) {
+        throw new Error("Request aborted");
+      }
       const response = await this.fetchFn(url, {
         method,
         headers,
@@ -169,6 +286,9 @@ var HttpClient = class {
     } catch (error) {
       if (error instanceof Error) {
         if (error.name === "AbortError") {
+          if (userSignal?.aborted) {
+            throw new NetworkError("Request aborted by user");
+          }
           throw new TimeoutError(`Request timed out after ${this.config.timeout}ms`);
         }
         throw new NetworkError(error.message);
@@ -176,11 +296,42 @@ var HttpClient = class {
       throw new NetworkError("Unknown network error");
     } finally {
       clearTimeout(timeoutId);
+      userSignal?.removeEventListener("abort", abortHandler);
     }
   }
-  async handleResponse(response) {
+  extractRateLimitInfo(response) {
+    const limit = response.headers.get("x-ratelimit-limit");
+    const remaining = response.headers.get("x-ratelimit-remaining");
+    const reset = response.headers.get("x-ratelimit-reset");
+    if (limit && remaining && reset) {
+      return {
+        limit: parseInt(limit, 10),
+        remaining: parseInt(remaining, 10),
+        reset: parseInt(reset, 10)
+      };
+    }
+    return void 0;
+  }
+  async handleResponse(response, requestContext, durationMs) {
     const contentType = response.headers.get("content-type");
     const isJson = contentType?.includes("application/json");
+    const requestId = response.headers.get("x-request-id") ?? void 0;
+    const rateLimitInfo = this.extractRateLimitInfo(response);
+    this._lastRequestId = requestId;
+    this._lastRateLimit = rateLimitInfo;
+    if (this.config.debug && requestId) {
+      console.log(`[DispatchTickets] Request ID: ${requestId}`);
+    }
+    if (response.ok && this.config.hooks?.onResponse) {
+      await this.config.hooks.onResponse({
+        request: requestContext,
+        status: response.status,
+        headers: response.headers,
+        requestId,
+        rateLimit: rateLimitInfo,
+        durationMs
+      });
+    }
     if (response.ok) {
       if (response.status === 204 || !isJson) {
         return void 0;
@@ -197,31 +348,36 @@ var HttpClient = class {
     const message = errorData.message || errorData.error || response.statusText;
     switch (response.status) {
       case 401:
-        throw new AuthenticationError(message);
+        throw new AuthenticationError(message, requestId);
       case 400:
       case 422:
-        throw new ValidationError(message, errorData.errors);
+        throw new ValidationError(message, errorData.errors, requestId);
       case 404:
-        throw new NotFoundError(message);
+        throw new NotFoundError(message, void 0, void 0, requestId);
       case 409:
-        throw new ConflictError(message);
+        throw new ConflictError(message, requestId);
       case 429: {
         const retryAfter = response.headers.get("retry-after");
-        throw new RateLimitError(message, retryAfter ? parseInt(retryAfter, 10) : void 0);
+        throw new RateLimitError(
+          message,
+          retryAfter ? parseInt(retryAfter, 10) : void 0,
+          requestId,
+          rateLimitInfo
+        );
       }
       default:
         if (response.status >= 500) {
-          throw new ServerError(message, response.status);
+          throw new ServerError(message, response.status, requestId);
         }
-        throw new DispatchTicketsError(message, "api_error", response.status, errorData);
+        throw new DispatchTicketsError(
+          message,
+          "api_error",
+          response.status,
+          errorData,
+          requestId
+        );
     }
   }
-  calculateBackoff(attempt) {
-    const baseDelay = 1e3;
-    const maxDelay = 3e4;
-    const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
-    return delay + Math.random() * delay * 0.25;
-  }
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
@@ -233,11 +389,12 @@ var BaseResource = class {
   constructor(http) {
     this.http = http;
   }
-  async _get(path, query) {
+  async _get(path, query, options) {
     return this.http.request({
       method: "GET",
       path,
-      query
+      query,
+      signal: options?.signal
     });
   }
   async _post(path, body, options) {
@@ -246,28 +403,32 @@ var BaseResource = class {
       path,
       body,
       idempotencyKey: options?.idempotencyKey,
-      query: options?.query
+      query: options?.query,
+      signal: options?.signal
     });
   }
-  async _patch(path, body) {
+  async _patch(path, body, options) {
     return this.http.request({
       method: "PATCH",
       path,
-      body
+      body,
+      signal: options?.signal
     });
   }
-  async _put(path, body) {
+  async _put(path, body, options) {
     return this.http.request({
       method: "PUT",
       path,
-      body
+      body,
+      signal: options?.signal
     });
   }
-  async _delete(path, query) {
+  async _delete(path, query, options) {
     return this.http.request({
       method: "DELETE",
       path,
-      query
+      query,
+      signal: options?.signal
     });
   }
 };
@@ -906,48 +1067,207 @@ var DispatchTickets = class {
   http;
   /**
    * Accounts resource for managing the current account and API keys
+   *
+   * @example
+   * ```typescript
+   * // Get current account
+   * const account = await client.accounts.me();
+   *
+   * // Get usage statistics
+   * const usage = await client.accounts.getUsage();
+   *
+   * // Create a new API key
+   * const newKey = await client.accounts.createApiKey({
+   *   name: 'Production',
+   *   allBrands: true,
+   * });
+   * ```
    */
   accounts;
   /**
    * Brands (workspaces) resource
+   *
+   * Brands are isolated containers for tickets. Each brand can have its own
+   * email address, categories, tags, and settings.
+   *
+   * @example
+   * ```typescript
+   * // List all brands
+   * const brands = await client.brands.list();
+   *
+   * // Create a new brand
+   * const brand = await client.brands.create({
+   *   name: 'Acme Support',
+   *   slug: 'acme',
+   * });
+   *
+   * // Get inbound email address
+   * const email = client.brands.getInboundEmail('br_abc123');
+   * // Returns: br_abc123@inbound.dispatchtickets.com
+   * ```
    */
   brands;
   /**
    * Tickets resource
+   *
+   * @example
+   * ```typescript
+   * // Create a ticket
+   * const ticket = await client.tickets.create('ws_abc123', {
+   *   title: 'Issue with billing',
+   *   body: 'I was charged twice...',
+   *   priority: 'high',
+   * });
+   *
+   * // Iterate through all tickets
+   * for await (const ticket of client.tickets.list('ws_abc123', { status: 'open' })) {
+   *   console.log(ticket.title);
+   * }
+   * ```
    */
   tickets;
   /**
    * Comments resource
+   *
+   * @example
+   * ```typescript
+   * // Add a comment
+   * const comment = await client.comments.create('ws_abc123', 'tkt_xyz', {
+   *   body: 'Thanks for your patience!',
+   *   authorType: 'AGENT',
+   * });
+   *
+   * // List comments
+   * const comments = await client.comments.list('ws_abc123', 'tkt_xyz');
+   * ```
    */
   comments;
   /**
    * Attachments resource
+   *
+   * @example
+   * ```typescript
+   * // Simple upload
+   * const attachment = await client.attachments.upload(
+   *   'ws_abc123',
+   *   'tkt_xyz',
+   *   fileBuffer,
+   *   'document.pdf',
+   *   'application/pdf'
+   * );
+   *
+   * // Get download URL
+   * const { downloadUrl } = await client.attachments.get('ws_abc123', 'tkt_xyz', 'att_abc');
+   * ```
    */
   attachments;
   /**
    * Webhooks resource
+   *
+   * @example
+   * ```typescript
+   * // Create a webhook
+   * const webhook = await client.webhooks.create('ws_abc123', {
+   *   url: 'https://example.com/webhook',
+   *   secret: 'your-secret',
+   *   events: ['ticket.created', 'ticket.updated'],
+   * });
+   * ```
    */
   webhooks;
   /**
    * Categories resource
+   *
+   * @example
+   * ```typescript
+   * // Create a category
+   * await client.categories.create('ws_abc123', { name: 'Billing', color: '#ef4444' });
+   *
+   * // Get category stats
+   * const stats = await client.categories.getStats('ws_abc123');
+   * ```
    */
   categories;
   /**
    * Tags resource
+   *
+   * @example
+   * ```typescript
+   * // Create a tag
+   * await client.tags.create('ws_abc123', { name: 'urgent', color: '#f59e0b' });
+   *
+   * // Merge tags
+   * await client.tags.merge('ws_abc123', 'tag_target', ['tag_source1', 'tag_source2']);
+   * ```
    */
   tags;
   /**
    * Customers resource
+   *
+   * @example
+   * ```typescript
+   * // Create a customer
+   * const customer = await client.customers.create('ws_abc123', {
+   *   email: 'user@example.com',
+   *   name: 'Jane Doe',
+   * });
+   *
+   * // Search customers
+   * const results = await client.customers.search('ws_abc123', 'jane');
+   * ```
    */
   customers;
   /**
    * Custom fields resource
+   *
+   * @example
+   * ```typescript
+   * // Get all field definitions
+   * const fields = await client.fields.getAll('ws_abc123');
+   *
+   * // Create a field
+   * await client.fields.create('ws_abc123', 'ticket', {
+   *   key: 'order_id',
+   *   label: 'Order ID',
+   *   type: 'text',
+   *   required: true,
+   * });
+   * ```
    */
   fields;
   /**
    * Static webhook utilities
+   *
+   * @example
+   * ```typescript
+   * // Verify webhook signature
+   * const isValid = DispatchTickets.webhooks.verifySignature(
+   *   rawBody,
+   *   req.headers['x-dispatch-signature'],
+   *   'your-secret'
+   * );
+   *
+   * // Generate signature for testing
+   * const signature = DispatchTickets.webhooks.generateSignature(
+   *   JSON.stringify(payload),
+   *   'your-secret'
+   * );
+   * ```
    */
   static webhooks = webhookUtils;
+  /**
+   * Create a new Dispatch Tickets client
+   *
+   * @param config - Client configuration options
+   * @throws Error if API key is not provided
+   *
+   * @example
+   * ```typescript
+   * const client = new DispatchTickets({
+   *   apiKey: 'sk_live_...',
+   * });
+   * ```
+   */
   constructor(config) {
     if (!config.apiKey) {
       throw new Error("API key is required");
@@ -956,9 +1276,11 @@ var DispatchTickets = class {
       baseUrl: config.baseUrl || "https://dispatch-tickets-api.onrender.com/v1",
       apiKey: config.apiKey,
       timeout: config.timeout ?? 3e4,
-      maxRetries: config.maxRetries ?? 3,
+      maxRetries: config.maxRetries ?? config.retry?.maxRetries ?? 3,
       debug: config.debug ?? false,
-      fetch: config.fetch
+      fetch: config.fetch,
+      retry: config.retry,
+      hooks: config.hooks
     };
     this.http = new HttpClient(httpConfig);
     this.accounts = new AccountsResource(this.http);
@@ -1025,9 +1347,18 @@ exports.ServerError = ServerError;
 exports.TimeoutError = TimeoutError;
 exports.ValidationError = ValidationError;
 exports.collectAll = collectAll;
+exports.isAuthenticationError = isAuthenticationError;
 exports.isCommentCreatedEvent = isCommentCreatedEvent;
+exports.isConflictError = isConflictError;
+exports.isDispatchTicketsError = isDispatchTicketsError;
+exports.isNetworkError = isNetworkError;
+exports.isNotFoundError = isNotFoundError;
+exports.isRateLimitError = isRateLimitError;
+exports.isServerError = isServerError;
 exports.isTicketCreatedEvent = isTicketCreatedEvent;
 exports.isTicketUpdatedEvent = isTicketUpdatedEvent;
+exports.isTimeoutError = isTimeoutError;
+exports.isValidationError = isValidationError;
 exports.parseWebhookEvent = parseWebhookEvent;
 exports.webhookUtils = webhookUtils;
 //# sourceMappingURL=index.cjs.map