@dispatchtickets/sdk 0.1.0 → 0.5.0

package/dist/index.d.ts

@@ -1,9 +1,124 @@
+/**
+ * Custom fetch function type
+ */
+type FetchFunction = typeof fetch;
+/**
+ * Request context passed to hooks
+ */
+interface RequestContext {
+    /** HTTP method */
+    method: string;
+    /** Full URL being requested */
+    url: string;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Request body (if any) */
+    body?: unknown;
+    /** Retry attempt number (0 = first attempt) */
+    attempt: number;
+}
+/**
+ * Response context passed to hooks
+ */
+interface ResponseContext {
+    /** The request that was made */
+    request: RequestContext;
+    /** HTTP status code */
+    status: number;
+    /** Response headers */
+    headers: Headers;
+    /** Request ID from server */
+    requestId?: string;
+    /** Rate limit info from server */
+    rateLimit?: RateLimitInfo;
+    /** Duration of the request in milliseconds */
+    durationMs: number;
+}
+/**
+ * Retry configuration options
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * HTTP status codes that should trigger a retry
+     * @default [429, 500, 502, 503, 504]
+     */
+    retryableStatuses?: number[];
+    /**
+     * Whether to retry on network errors
+     * @default true
+     */
+    retryOnNetworkError?: boolean;
+    /**
+     * Whether to retry on timeout errors
+     * @default true
+     */
+    retryOnTimeout?: boolean;
+    /**
+     * Initial delay between retries in milliseconds
+     * @default 1000
+     */
+    initialDelayMs?: number;
+    /**
+     * Maximum delay between retries in milliseconds
+     * @default 30000
+     */
+    maxDelayMs?: number;
+    /**
+     * Multiplier for exponential backoff
+     * @default 2
+     */
+    backoffMultiplier?: number;
+    /**
+     * Jitter factor (0-1) to add randomness to delays
+     * @default 0.25
+     */
+    jitter?: number;
+}
+/**
+ * Hooks for observability and customization
+ */
+interface Hooks {
+    /**
+     * Called before each request is sent
+     * Can modify the request or throw to abort
+     */
+    onRequest?: (context: RequestContext) => void | Promise<void>;
+    /**
+     * Called after each successful response
+     */
+    onResponse?: (context: ResponseContext) => void | Promise<void>;
+    /**
+     * Called when an error occurs (before retry)
+     */
+    onError?: (error: Error, context: RequestContext) => void | Promise<void>;
+    /**
+     * Called before each retry attempt
+     */
+    onRetry?: (context: RequestContext, error: Error, delayMs: number) => void | Promise<void>;
+}
 interface HttpClientConfig {
     baseUrl: string;
     apiKey: string;
     timeout: number;
     maxRetries: number;
     debug?: boolean;
+    /**
+     * Custom fetch implementation for testing/mocking
+     */
+    fetch?: FetchFunction;
+    /**
+     * Fine-grained retry configuration
+     */
+    retry?: RetryConfig;
+    /**
+     * Hooks for observability
+     */
+    hooks?: Hooks;
 }
 interface RequestOptions {
     method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
@@ -12,39 +127,201 @@ interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined>;
     headers?: Record<string, string>;
     idempotencyKey?: string;
+    /**
+     * AbortSignal to cancel the request
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Rate limit information from response headers
+ */
+interface RateLimitInfo {
+    /** Maximum requests allowed in the current window */
+    limit: number;
+    /** Remaining requests in the current window */
+    remaining: number;
+    /** Unix timestamp (seconds) when the rate limit resets */
+    reset: number;
 }
 /**
- * HTTP client with retry logic and error handling
+ * Response wrapper with rate limit info
+ */
+interface ResponseWithRateLimit<T> {
+    data: T;
+    rateLimit?: RateLimitInfo;
+    requestId?: string;
+}
+/**
+ * HTTP client with retry logic, hooks, and error handling
  */
 declare class HttpClient {
     private readonly config;
+    private readonly fetchFn;
+    private readonly retryConfig;
+    /** Rate limit info from the last response */
+    private _lastRateLimit?;
+    /** Request ID from the last response */
+    private _lastRequestId?;
     constructor(config: HttpClientConfig);
+    /**
+     * Get rate limit info from the last response
+     */
+    get lastRateLimit(): RateLimitInfo | undefined;
+    /**
+     * Get request ID from the last response
+     */
+    get lastRequestId(): string | undefined;
     /**
      * Execute an HTTP request with retry logic
      */
     request<T>(options: RequestOptions): Promise<T>;
+    /**
+     * Execute request and return response with rate limit info
+     */
+    requestWithRateLimit<T>(options: RequestOptions): Promise<ResponseWithRateLimit<T>>;
+    private shouldRetry;
+    private calculateDelay;
     private buildUrl;
     private buildHeaders;
     private executeRequest;
+    private extractRateLimitInfo;
     private handleResponse;
-    private calculateBackoff;
     private sleep;
 }
 
+/**
+ * Options for API requests
+ */
+interface ApiRequestOptions {
+    /**
+     * AbortSignal to cancel the request
+     *
+     * @example
+     * ```typescript
+     * const controller = new AbortController();
+     * setTimeout(() => controller.abort(), 5000);
+     *
+     * const ticket = await client.tickets.get('ws_abc', 'tkt_xyz', {
+     *   signal: controller.signal,
+     * });
+     * ```
+     */
+    signal?: AbortSignal;
+}
 /**
  * Base class for all resource classes
+ * @internal
  */
 declare abstract class BaseResource {
     protected readonly http: HttpClient;
     constructor(http: HttpClient);
-    protected _get<T>(path: string, query?: RequestOptions['query']): Promise<T>;
+    protected _get<T>(path: string, query?: RequestOptions['query'], options?: ApiRequestOptions): Promise<T>;
     protected _post<T>(path: string, body?: unknown, options?: {
         idempotencyKey?: string;
         query?: RequestOptions['query'];
+        signal?: AbortSignal;
     }): Promise<T>;
-    protected _patch<T>(path: string, body?: unknown): Promise<T>;
-    protected _put<T>(path: string, body?: unknown): Promise<T>;
-    protected _delete<T>(path: string, query?: RequestOptions['query']): Promise<T>;
+    protected _patch<T>(path: string, body?: unknown, options?: ApiRequestOptions): Promise<T>;
+    protected _put<T>(path: string, body?: unknown, options?: ApiRequestOptions): Promise<T>;
+    protected _delete<T>(path: string, query?: RequestOptions['query'], options?: ApiRequestOptions): Promise<T>;
+}
+
+/**
+ * Account represents the organization/company using Dispatch Tickets
+ */
+interface Account {
+    id: string;
+    stackbeCustomerId: string;
+    stackbeOrganizationId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Usage statistics for the account
+ */
+interface AccountUsage {
+    ticketsThisMonth: number;
+    ticketsTotal: number;
+    brandsCount: number;
+    plan?: {
+        name: string;
+        ticketLimit: number;
+        brandLimit: number | null;
+    };
+}
+/**
+ * API key for programmatic access
+ */
+interface ApiKey {
+    id: string;
+    name: string;
+    keyPreview: string;
+    allBrands: boolean;
+    brandIds: string[];
+    lastUsedAt: string | null;
+    createdAt: string;
+}
+/**
+ * API key with the full key value (only returned on creation)
+ */
+interface ApiKeyWithSecret extends ApiKey {
+    key: string;
+}
+/**
+ * Input for creating an API key
+ */
+interface CreateApiKeyInput {
+    name: string;
+    /**
+     * If true, the API key can access all brands (current and future)
+     */
+    allBrands?: boolean;
+    /**
+     * Specific brand IDs this key can access (ignored if allBrands is true)
+     */
+    brandIds?: string[];
+}
+/**
+ * Input for updating API key scope
+ */
+interface UpdateApiKeyScopeInput {
+    allBrands?: boolean;
+    brandIds?: string[];
+}
+
+/**
+ * Accounts resource for managing the current account
+ */
+declare class AccountsResource extends BaseResource {
+    /**
+     * Get the current account
+     */
+    me(): Promise<Account>;
+    /**
+     * Get usage statistics for the current account
+     */
+    getUsage(): Promise<AccountUsage>;
+    /**
+     * List all API keys for the current account
+     */
+    listApiKeys(): Promise<ApiKey[]>;
+    /**
+     * 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.
+     */
+    createApiKey(data: CreateApiKeyInput): Promise<ApiKeyWithSecret>;
+    /**
+     * Update the brand scope for an API key
+     */
+    updateApiKeyScope(keyId: string, data: UpdateApiKeyScopeInput): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Revoke an API key
+     */
+    revokeApiKey(keyId: string): Promise<void>;
 }
 
 /**
@@ -144,6 +421,26 @@ declare class BrandsResource extends BaseResource {
      * Update the ticket schema for a brand
      */
     updateSchema(brandId: string, schema: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * 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: string, domain?: string): string;
 }
 
 /**
@@ -185,9 +482,10 @@ type AuthorType = 'CUSTOMER' | 'AGENT' | 'SYSTEM';
  */
 type AttachmentStatus = 'PENDING' | 'UPLOADED' | 'FAILED';
 /**
- * Webhook event types
+ * Webhook event type strings (for subscription)
+ * @deprecated Use WebhookEventType from events.ts for typed event handling
  */
-type WebhookEvent = 'ticket.created' | 'ticket.updated' | 'ticket.deleted' | 'comment.created' | 'comment.updated' | 'comment.deleted' | 'attachment.created' | 'attachment.deleted';
+type WebhookEventName = 'ticket.created' | 'ticket.updated' | 'ticket.deleted' | 'ticket.comment.created' | 'comment.created' | 'comment.updated' | 'comment.deleted' | 'attachment.created' | 'attachment.deleted';
 /**
  * Custom field types
  */
@@ -655,7 +953,7 @@ interface Webhook {
     id: string;
     brandId: string;
     url: string;
-    events: WebhookEvent[];
+    events: WebhookEventName[];
     enabled: boolean;
     failureCount: number;
     lastTriggered?: string;
@@ -669,7 +967,7 @@ interface Webhook {
 interface CreateWebhookInput {
     url: string;
     secret: string;
-    events: WebhookEvent[];
+    events: WebhookEventName[];
 }
 /**
  * Webhook delivery record
@@ -677,7 +975,7 @@ interface CreateWebhookInput {
 interface WebhookDelivery {
     id: string;
     webhookId: string;
-    event: WebhookEvent;
+    event: WebhookEventName;
     payload: Record<string, unknown>;
     status: 'PENDING' | 'SUCCESS' | 'FAILED' | 'RETRYING';
     attempts: number;
@@ -896,10 +1194,30 @@ declare class FieldsResource extends BaseResource {
 
 /**
  * Configuration options for the Dispatch Tickets client
+ *
+ * @example
+ * ```typescript
+ * const client = new DispatchTickets({
+ *   apiKey: 'sk_live_...',
+ *   timeout: 30000,
+ *   retry: {
+ *     maxRetries: 5,
+ *     retryableStatuses: [429, 500, 502, 503, 504],
+ *   },
+ *   hooks: {
+ *     onRequest: (ctx) => console.log(`${ctx.method} ${ctx.url}`),
+ *     onResponse: (ctx) => console.log(`${ctx.status} in ${ctx.durationMs}ms`),
+ *   },
+ * });
+ * ```
  */
 interface DispatchTicketsConfig {
     /**
      * Your API key (required)
+     *
+     * Get your API key from the Dispatch Tickets dashboard.
+     * Keys starting with `sk_live_` are production keys.
+     * Keys starting with `sk_test_` are test keys.
      */
     apiKey: string;
     /**
@@ -915,18 +1233,90 @@ interface DispatchTicketsConfig {
     /**
      * Maximum number of retries for failed requests
      * @default 3
+     * @deprecated Use `retry.maxRetries` instead for fine-grained control
      */
     maxRetries?: number;
     /**
      * Enable debug logging
+     *
+     * When enabled, logs all requests, responses, and request IDs to console.
      * @default false
      */
     debug?: boolean;
+    /**
+     * Custom fetch implementation for testing/mocking
+     *
+     * @example
+     * ```typescript
+     * const mockFetch = vi.fn().mockResolvedValue({
+     *   ok: true,
+     *   status: 200,
+     *   headers: { get: () => 'application/json' },
+     *   json: () => Promise.resolve({ id: 'test' }),
+     * });
+     *
+     * const client = new DispatchTickets({
+     *   apiKey: 'sk_test_...',
+     *   fetch: mockFetch,
+     * });
+     * ```
+     */
+    fetch?: FetchFunction;
+    /**
+     * Fine-grained retry configuration
+     *
+     * @example
+     * ```typescript
+     * const client = new DispatchTickets({
+     *   apiKey: 'sk_live_...',
+     *   retry: {
+     *     maxRetries: 5,
+     *     retryableStatuses: [429, 500, 502, 503, 504],
+     *     initialDelayMs: 500,
+     *     maxDelayMs: 60000,
+     *     backoffMultiplier: 2,
+     *     jitter: 0.25,
+     *   },
+     * });
+     * ```
+     */
+    retry?: RetryConfig;
+    /**
+     * Hooks for observability and customization
+     *
+     * @example
+     * ```typescript
+     * const client = new DispatchTickets({
+     *   apiKey: 'sk_live_...',
+     *   hooks: {
+     *     onRequest: (ctx) => {
+     *       console.log(`[${new Date().toISOString()}] ${ctx.method} ${ctx.url}`);
+     *     },
+     *     onResponse: (ctx) => {
+     *       console.log(`[${ctx.requestId}] ${ctx.status} in ${ctx.durationMs}ms`);
+     *     },
+     *     onError: (error, ctx) => {
+     *       console.error(`Request failed: ${error.message}`);
+     *       // Send to error tracking service
+     *       Sentry.captureException(error);
+     *     },
+     *     onRetry: (ctx, error, delayMs) => {
+     *       console.log(`Retrying in ${delayMs}ms (attempt ${ctx.attempt + 1})`);
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    hooks?: Hooks;
 }
 /**
  * Dispatch Tickets SDK client
  *
- * @example
+ * The main entry point for interacting with the Dispatch Tickets API.
+ * Create a client instance with your API key and use the resource methods
+ * to manage tickets, comments, attachments, and more.
+ *
+ * @example Basic usage
  * ```typescript
  * import { DispatchTickets } from '@dispatchtickets/sdk';
  *
@@ -948,52 +1338,244 @@ interface DispatchTicketsConfig {
  *   console.log(ticket.title);
  * }
  * ```
+ *
+ * @example With request cancellation
+ * ```typescript
+ * const controller = new AbortController();
+ *
+ * // Cancel after 5 seconds
+ * setTimeout(() => controller.abort(), 5000);
+ *
+ * try {
+ *   const tickets = await client.tickets.listPage('ws_abc123', {}, {
+ *     signal: controller.signal,
+ *   });
+ * } catch (error) {
+ *   if (error.message === 'Request aborted by user') {
+ *     console.log('Request was cancelled');
+ *   }
+ * }
+ * ```
+ *
+ * @example With hooks for logging
+ * ```typescript
+ * const client = new DispatchTickets({
+ *   apiKey: 'sk_live_...',
+ *   hooks: {
+ *     onRequest: (ctx) => console.log(`→ ${ctx.method} ${ctx.url}`),
+ *     onResponse: (ctx) => console.log(`← ${ctx.status} (${ctx.durationMs}ms)`),
+ *   },
+ * });
+ * ```
  */
 declare class DispatchTickets {
     private readonly 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,
+     * });
+     * ```
+     */
+    readonly accounts: AccountsResource;
     /**
      * 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
+     * ```
      */
     readonly brands: BrandsResource;
     /**
      * 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);
+     * }
+     * ```
      */
     readonly tickets: TicketsResource;
     /**
      * 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');
+     * ```
      */
     readonly comments: CommentsResource;
     /**
      * 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');
+     * ```
      */
     readonly attachments: AttachmentsResource;
     /**
      * 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'],
+     * });
+     * ```
      */
     readonly webhooks: WebhooksResource;
     /**
      * 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');
+     * ```
      */
     readonly categories: CategoriesResource;
     /**
      * 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']);
+     * ```
      */
     readonly tags: TagsResource;
     /**
      * 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');
+     * ```
      */
     readonly customers: CustomersResource;
     /**
      * 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,
+     * });
+     * ```
      */
     readonly fields: FieldsResource;
     /**
      * 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 readonly webhooks: {
         verifySignature(payload: string, signature: string, secret: string): boolean;
         generateSignature(payload: string, secret: string): string;
     };
+    /**
+     * 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: DispatchTicketsConfig);
 }
 
@@ -1004,20 +1586,32 @@ declare class DispatchTicketsError extends Error {
     readonly code: string;
     readonly statusCode?: number;
     readonly details?: Record<string, unknown>;
-    constructor(message: string, code: string, statusCode?: number, details?: Record<string, unknown>);
+    /** Request ID for debugging with support */
+    readonly requestId?: string;
+    constructor(message: string, code: string, statusCode?: number, details?: Record<string, unknown>, requestId?: string);
 }
 /**
  * Thrown when API key is missing or invalid
  */
 declare class AuthenticationError extends DispatchTicketsError {
-    constructor(message?: string);
+    constructor(message?: string, requestId?: string);
 }
 /**
  * Thrown when rate limit is exceeded
  */
 declare class RateLimitError extends DispatchTicketsError {
     readonly retryAfter?: number;
-    constructor(message?: string, retryAfter?: number);
+    /** Rate limit ceiling */
+    readonly limit?: number;
+    /** Remaining requests in current window */
+    readonly remaining?: number;
+    /** Unix timestamp when rate limit resets */
+    readonly reset?: number;
+    constructor(message?: string, retryAfter?: number, requestId?: string, rateLimitInfo?: {
+        limit?: number;
+        remaining?: number;
+        reset?: number;
+    });
 }
 /**
  * Thrown when request validation fails
@@ -1030,7 +1624,7 @@ declare class ValidationError extends DispatchTicketsError {
     constructor(message?: string, errors?: Array<{
         field: string;
         message: string;
-    }>);
+    }>, requestId?: string);
 }
 /**
  * Thrown when a resource is not found
@@ -1038,19 +1632,19 @@ declare class ValidationError extends DispatchTicketsError {
 declare class NotFoundError extends DispatchTicketsError {
     readonly resourceType?: string;
     readonly resourceId?: string;
-    constructor(message?: string, resourceType?: string, resourceId?: string);
+    constructor(message?: string, resourceType?: string, resourceId?: string, requestId?: string);
 }
 /**
  * Thrown when there's a conflict (e.g., duplicate resource)
  */
 declare class ConflictError extends DispatchTicketsError {
-    constructor(message?: string);
+    constructor(message?: string, requestId?: string);
 }
 /**
  * Thrown when the server returns an unexpected error
  */
 declare class ServerError extends DispatchTicketsError {
-    constructor(message?: string, statusCode?: number);
+    constructor(message?: string, statusCode?: number, requestId?: string);
 }
 /**
  * Thrown when request times out
@@ -1064,6 +1658,172 @@ declare class TimeoutError extends DispatchTicketsError {
 declare class NetworkError extends DispatchTicketsError {
     constructor(message?: string);
 }
+/**
+ * Check if an error is a DispatchTicketsError
+ */
+declare function isDispatchTicketsError(error: unknown): error is DispatchTicketsError;
+/**
+ * Check if an error is an AuthenticationError
+ */
+declare function isAuthenticationError(error: unknown): error is AuthenticationError;
+/**
+ * Check if an error is a RateLimitError
+ */
+declare function isRateLimitError(error: unknown): error is RateLimitError;
+/**
+ * Check if an error is a ValidationError
+ */
+declare function isValidationError(error: unknown): error is ValidationError;
+/**
+ * Check if an error is a NotFoundError
+ */
+declare function isNotFoundError(error: unknown): error is NotFoundError;
+/**
+ * Check if an error is a ConflictError
+ */
+declare function isConflictError(error: unknown): error is ConflictError;
+/**
+ * Check if an error is a ServerError
+ */
+declare function isServerError(error: unknown): error is ServerError;
+/**
+ * Check if an error is a TimeoutError
+ */
+declare function isTimeoutError(error: unknown): error is TimeoutError;
+/**
+ * Check if an error is a NetworkError
+ */
+declare function isNetworkError(error: unknown): error is NetworkError;
+
+/**
+ * All supported webhook event types
+ */
+type WebhookEventType = 'ticket.created' | 'ticket.updated' | 'ticket.comment.created';
+/**
+ * Base webhook event envelope
+ */
+interface WebhookEventEnvelope<T extends WebhookEventType, D> {
+    /** Unique event ID */
+    id: string;
+    /** Event type */
+    event: T;
+    /** Brand ID that triggered the event */
+    brand_id: string;
+    /** Event data */
+    data: D;
+    /** ISO timestamp when event was created */
+    timestamp: string;
+}
+/**
+ * Customer info included in events
+ */
+interface EventCustomerInfo {
+    customerId: string | null;
+    customerEmail: string | null;
+    customerName: string | null;
+}
+/**
+ * Payload for ticket.created event
+ */
+interface TicketCreatedData extends EventCustomerInfo {
+    id: string;
+    ticketNumber: number;
+    title: string;
+    status: TicketStatus;
+    priority: TicketPriority;
+    source: TicketSource;
+    createdAt: string;
+}
+/**
+ * Payload for ticket.updated event
+ */
+interface TicketUpdatedData extends EventCustomerInfo {
+    id: string;
+    ticketNumber: number;
+    title: string;
+    status: TicketStatus;
+    priority: TicketPriority;
+    assigneeId: string | null;
+    updatedAt: string;
+    /** List of field names that were changed */
+    changes: string[];
+}
+/**
+ * Comment data in ticket.comment.created event
+ */
+interface EventCommentData {
+    id: string;
+    body: string;
+    authorId: string | null;
+    authorType: AuthorType;
+    createdAt: string;
+}
+/**
+ * Payload for ticket.comment.created event
+ */
+interface CommentCreatedData extends EventCustomerInfo {
+    ticketId: string;
+    /** Formatted ticket number (e.g., "ACME-123") */
+    ticketNumber: string;
+    comment: EventCommentData;
+}
+/**
+ * Ticket created webhook event
+ */
+type TicketCreatedEvent = WebhookEventEnvelope<'ticket.created', TicketCreatedData>;
+/**
+ * Ticket updated webhook event
+ */
+type TicketUpdatedEvent = WebhookEventEnvelope<'ticket.updated', TicketUpdatedData>;
+/**
+ * Comment created webhook event
+ */
+type CommentCreatedEvent = WebhookEventEnvelope<'ticket.comment.created', CommentCreatedData>;
+/**
+ * Union of all webhook events
+ */
+type WebhookEvent = TicketCreatedEvent | TicketUpdatedEvent | CommentCreatedEvent;
+/**
+ * Map of event types to their data types
+ */
+interface WebhookEventMap {
+    'ticket.created': TicketCreatedEvent;
+    'ticket.updated': TicketUpdatedEvent;
+    'ticket.comment.created': CommentCreatedEvent;
+}
+/**
+ * Type guard to check if event is a ticket.created event
+ */
+declare function isTicketCreatedEvent(event: WebhookEvent): event is TicketCreatedEvent;
+/**
+ * Type guard to check if event is a ticket.updated event
+ */
+declare function isTicketUpdatedEvent(event: WebhookEvent): event is TicketUpdatedEvent;
+/**
+ * Type guard to check if event is a ticket.comment.created event
+ */
+declare function isCommentCreatedEvent(event: WebhookEvent): event is CommentCreatedEvent;
+/**
+ * Parse and validate a webhook payload
+ *
+ * @param payload - Raw JSON payload string or parsed object
+ * @returns Typed webhook event
+ * @throws Error if payload is invalid
+ *
+ * @example
+ * ```typescript
+ * import { parseWebhookEvent, isTicketCreatedEvent } from '@dispatchtickets/sdk';
+ *
+ * app.post('/webhooks', (req, res) => {
+ *   const event = parseWebhookEvent(req.body);
+ *
+ *   if (isTicketCreatedEvent(event)) {
+ *     console.log('New ticket:', event.data.title);
+ *   }
+ * });
+ * ```
+ */
+declare function parseWebhookEvent(payload: string | object): WebhookEvent;
 
 /**
  * Webhook signature verification utilities
@@ -1113,4 +1873,4 @@ declare const webhookUtils: {
  */
 declare function collectAll<T>(iterable: AsyncIterable<T>): Promise<T[]>;
 
-export { type Attachment, type AttachmentStatus, type AttachmentWithUrl, AuthenticationError, type AuthorType, type Brand, type BulkAction, type BulkActionResult, type Category, type CategoryStats, type Comment, type Company, ConflictError, type CreateBrandInput, type CreateCategoryInput, type CreateCommentInput, type CreateCommentOptions, type CreateCustomerInput, type CreateFieldInput, type CreateTagInput, type CreateTicketInput, type CreateTicketOptions, type CreateWebhookInput, type Customer, type DeleteBrandPreview, DispatchTickets, type DispatchTicketsConfig, DispatchTicketsError, type EntityType, type FieldDefinition, type FieldDefinitions, type FieldType, type InitiateUploadInput, type InitiateUploadResponse, type Link, type ListCustomersFilters, type ListTicketsFilters, type MergeTagsInput, type MergeTicketsInput, NetworkError, NotFoundError, type PaginatedResponse, RateLimitError, ServerError, type SortOrder, type Tag, type Ticket, type TicketPriority, type TicketSource, type TicketStatus, TimeoutError, type UpdateBrandInput, type UpdateCategoryInput, type UpdateCommentInput, type UpdateCustomerInput, type UpdateFieldInput, type UpdateTagInput, type UpdateTicketInput, ValidationError, type Webhook, type WebhookDelivery, type WebhookEvent, collectAll, webhookUtils };
+export { type Account, type AccountUsage, type ApiKey, type ApiKeyWithSecret, type ApiRequestOptions, type Attachment, type AttachmentStatus, type AttachmentWithUrl, AuthenticationError, type AuthorType, type Brand, type BulkAction, type BulkActionResult, type Category, type CategoryStats, type Comment, type CommentCreatedData, type CommentCreatedEvent, type Company, ConflictError, type CreateApiKeyInput, type CreateBrandInput, type CreateCategoryInput, type CreateCommentInput, type CreateCommentOptions, type CreateCustomerInput, type CreateFieldInput, type CreateTagInput, type CreateTicketInput, type CreateTicketOptions, type CreateWebhookInput, type Customer, type DeleteBrandPreview, DispatchTickets, type DispatchTicketsConfig, DispatchTicketsError, type EntityType, type EventCommentData, type EventCustomerInfo, type FieldDefinition, type FieldDefinitions, type FieldType, type Hooks, type InitiateUploadInput, type InitiateUploadResponse, type Link, type ListCustomersFilters, type ListTicketsFilters, type MergeTagsInput, type MergeTicketsInput, NetworkError, NotFoundError, type PaginatedResponse, RateLimitError, type RateLimitInfo, type RequestContext, type ResponseContext, type RetryConfig, ServerError, type SortOrder, type Tag, type Ticket, type TicketCreatedData, type TicketCreatedEvent, type TicketPriority, type TicketSource, type TicketStatus, type TicketUpdatedData, type TicketUpdatedEvent, TimeoutError, type UpdateApiKeyScopeInput, type UpdateBrandInput, type UpdateCategoryInput, type UpdateCommentInput, type UpdateCustomerInput, type UpdateFieldInput, type UpdateTagInput, type UpdateTicketInput, ValidationError, type Webhook, type WebhookDelivery, type WebhookEvent, type WebhookEventEnvelope, type WebhookEventMap, type WebhookEventName, type WebhookEventType, collectAll, isAuthenticationError, isCommentCreatedEvent, isConflictError, isDispatchTicketsError, isNetworkError, isNotFoundError, isRateLimitError, isServerError, isTicketCreatedEvent, isTicketUpdatedEvent, isTimeoutError, isValidationError, parseWebhookEvent, webhookUtils };