@dispatchtickets/sdk 0.3.0 → 0.7.0

package/dist/index.d.ts

@@ -2,6 +2,105 @@
  * 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;
@@ -12,6 +111,14 @@ interface HttpClientConfig {
      * 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';
@@ -20,40 +127,103 @@ interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined>;
     headers?: Record<string, string>;
     idempotencyKey?: string;
+    /**
+     * AbortSignal to cancel the request
+     */
+    signal?: AbortSignal;
 }
 /**
- * HTTP client with retry logic and error handling
+ * 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;
+}
+/**
+ * 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>;
 }
 
 /**
@@ -176,6 +346,8 @@ interface Brand {
     autoresponseBody?: string;
     fromName?: string;
     fromEmail?: string;
+    /** Allowed origins for portal API CORS */
+    portalOrigins: string[];
     createdAt: string;
     updatedAt: string;
 }
@@ -206,6 +378,8 @@ interface UpdateBrandInput {
     autoresponseBody?: string;
     metadata?: Record<string, unknown>;
     ticketSchema?: Record<string, unknown>;
+    /** Allowed origins for portal API CORS. Empty array = block all cross-origin requests. */
+    portalOrigins?: string[];
 }
 /**
  * Brand deletion preview result
@@ -217,6 +391,134 @@ interface DeleteBrandPreview {
     tagCount: number;
 }
 
+/**
+ * Portal API Types
+ *
+ * Types for the customer-facing portal API.
+ * Used with the DispatchPortal client.
+ */
+/**
+ * Response from portal token generation or verification
+ */
+interface PortalTokenResponse {
+    /** JWT portal token for Authorization header */
+    token: string;
+    /** ISO 8601 expiration timestamp */
+    expiresAt: string;
+    /** Customer ID */
+    customerId: string;
+    /** Customer email */
+    email: string;
+    /** Customer name (if provided) */
+    name?: string;
+}
+/**
+ * Input for generating a portal token
+ */
+interface GeneratePortalTokenInput {
+    /** Customer email address */
+    email: string;
+    /** Customer name (optional) */
+    name?: string;
+}
+/**
+ * Input for sending a magic link email
+ */
+interface SendMagicLinkInput {
+    /** Customer email address */
+    email: string;
+    /** URL to redirect to after verification (your portal URL) */
+    portalUrl: string;
+}
+/**
+ * Ticket summary (returned in list views)
+ */
+interface PortalTicket {
+    /** Ticket ID */
+    id: string;
+    /** Formatted ticket number (e.g., "TKT-1001") */
+    ticketNumber: string;
+    /** Ticket title */
+    title: string;
+    /** Current status */
+    status: string;
+    /** Priority level */
+    priority: string;
+    /** Number of comments on the ticket */
+    commentCount: number;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+}
+/**
+ * Ticket detail with body and comments
+ */
+interface PortalTicketDetail extends PortalTicket {
+    /** Ticket body/description */
+    body: string;
+    /** Brand information */
+    brand: {
+        /** Brand name */
+        name: string;
+    };
+    /** Comments on the ticket (excludes internal comments) */
+    comments: PortalComment[];
+}
+/**
+ * Comment on a ticket
+ */
+interface PortalComment {
+    /** Comment ID */
+    id: string;
+    /** Comment body */
+    body: string;
+    /** Author type */
+    authorType: 'CUSTOMER' | 'STAFF';
+    /** Author display name */
+    authorName: string;
+    /** Creation timestamp */
+    createdAt: string;
+}
+/**
+ * Input for creating a ticket via portal
+ */
+interface PortalCreateTicketInput {
+    /** Ticket title */
+    title: string;
+    /** Ticket body/description (optional) */
+    body?: string;
+}
+/**
+ * Filters for listing tickets
+ */
+interface PortalListTicketsFilters {
+    /** Filter by status */
+    status?: string;
+    /** Sort field */
+    sort?: 'createdAt' | 'updatedAt';
+    /** Sort order */
+    order?: 'asc' | 'desc';
+    /** Maximum results per page (1-50, default 20) */
+    limit?: number;
+    /** Pagination cursor */
+    cursor?: string;
+}
+/**
+ * Paginated list of tickets
+ */
+interface PortalTicketListResponse {
+    /** Array of tickets */
+    data: PortalTicket[];
+    /** Pagination info */
+    pagination: {
+        /** Whether more results are available */
+        hasMore: boolean;
+        /** Cursor for next page (null if no more) */
+        nextCursor: string | null;
+    };
+}
+
 /**
  * Brands resource for managing workspaces
  */
@@ -271,6 +573,61 @@ declare class BrandsResource extends BaseResource {
      * ```
      */
     getInboundEmail(brandId: string, domain?: string): string;
+    /**
+     * Generate a portal token for a customer
+     *
+     * Use this for "authenticated mode" where your backend already knows who the
+     * customer is (they're logged into your app). Generate a portal token and
+     * pass it to your frontend to initialize the DispatchPortal client.
+     *
+     * @param brandId - The brand ID
+     * @param data - Customer email and optional name
+     * @returns Portal token response with JWT token and expiry
+     *
+     * @example
+     * ```typescript
+     * // On your backend (Node.js, Next.js API route, etc.)
+     * const { token, expiresAt } = await client.brands.generatePortalToken(
+     *   'br_abc123',
+     *   {
+     *     email: req.user.email,
+     *     name: req.user.name,
+     *   }
+     * );
+     *
+     * // Return token to your frontend
+     * res.json({ portalToken: token });
+     * ```
+     */
+    generatePortalToken(brandId: string, data: GeneratePortalTokenInput): Promise<PortalTokenResponse>;
+    /**
+     * Send a magic link email to a customer
+     *
+     * Use this for "self-auth mode" where customers access the portal without
+     * being logged into your app. They receive an email with a link that
+     * authenticates them directly.
+     *
+     * @param brandId - The brand ID
+     * @param data - Customer email and portal URL to redirect to
+     * @returns Success status
+     *
+     * @example
+     * ```typescript
+     * // Customer requests access via your portal login form
+     * await client.brands.sendPortalMagicLink('br_abc123', {
+     *   email: 'customer@example.com',
+     *   portalUrl: 'https://yourapp.com/support/portal',
+     * });
+     *
+     * // Customer receives email with link like:
+     * // https://yourapp.com/support/portal?token=xyz...
+     *
+     * // Your portal page then calls DispatchPortal.verify(token)
+     * ```
+     */
+    sendPortalMagicLink(brandId: string, data: SendMagicLinkInput): Promise<{
+        success: boolean;
+    }>;
 }
 
 /**
@@ -1024,10 +1381,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;
     /**
@@ -1043,22 +1420,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';
  *
@@ -1080,59 +1525,530 @@ 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);
 }
 
+/**
+ * Options for creating a ticket via portal
+ */
+interface PortalCreateTicketOptions extends ApiRequestOptions {
+    /** Idempotency key to prevent duplicate creation */
+    idempotencyKey?: string;
+}
+/**
+ * Options for adding a comment via portal
+ */
+interface PortalAddCommentOptions extends ApiRequestOptions {
+    /** Idempotency key to prevent duplicate creation */
+    idempotencyKey?: string;
+}
+/**
+ * Portal tickets resource
+ *
+ * Provides methods for customers to manage their tickets via the portal API.
+ *
+ * @example
+ * ```typescript
+ * const portal = new DispatchPortal({ token: 'portal_token...' });
+ *
+ * // List tickets
+ * const { data: tickets } = await portal.tickets.list();
+ *
+ * // Create a ticket
+ * const ticket = await portal.tickets.create({
+ *   title: 'Need help with my order',
+ *   body: 'Order #12345 has not arrived...',
+ * });
+ *
+ * // Add a comment
+ * await portal.tickets.addComment(ticket.id, 'Any update on this?');
+ * ```
+ */
+declare class PortalTicketsResource extends BaseResource {
+    /**
+     * List the customer's tickets
+     *
+     * Returns a paginated list of tickets belonging to the authenticated customer.
+     *
+     * @param filters - Optional filters and pagination
+     * @param options - Request options
+     * @returns Paginated ticket list
+     *
+     * @example
+     * ```typescript
+     * // List all tickets
+     * const { data: tickets, pagination } = await portal.tickets.list();
+     *
+     * // Filter by status
+     * const openTickets = await portal.tickets.list({ status: 'open' });
+     *
+     * // Paginate
+     * const page2 = await portal.tickets.list({ cursor: pagination.nextCursor });
+     * ```
+     */
+    list(filters?: PortalListTicketsFilters, options?: ApiRequestOptions): Promise<PortalTicketListResponse>;
+    /**
+     * Iterate through all tickets with automatic pagination
+     *
+     * @param filters - Optional filters (cursor is managed automatically)
+     * @returns Async iterator of tickets
+     *
+     * @example
+     * ```typescript
+     * for await (const ticket of portal.tickets.listAll({ status: 'open' })) {
+     *   console.log(ticket.title);
+     * }
+     * ```
+     */
+    listAll(filters?: Omit<PortalListTicketsFilters, 'cursor'>): AsyncIterable<PortalTicket>;
+    /**
+     * Get a ticket by ID
+     *
+     * Returns the ticket with its comments (excludes internal comments).
+     *
+     * @param ticketId - Ticket ID
+     * @param options - Request options
+     * @returns Ticket detail with comments
+     *
+     * @example
+     * ```typescript
+     * const ticket = await portal.tickets.get('tkt_abc123');
+     * console.log(ticket.title);
+     * console.log(`${ticket.comments.length} comments`);
+     * ```
+     */
+    get(ticketId: string, options?: ApiRequestOptions): Promise<PortalTicketDetail>;
+    /**
+     * Create a new ticket
+     *
+     * @param data - Ticket data
+     * @param options - Request options including idempotency key
+     * @returns Created ticket
+     *
+     * @example
+     * ```typescript
+     * const ticket = await portal.tickets.create({
+     *   title: 'Need help with billing',
+     *   body: 'I was charged twice for my subscription...',
+     * });
+     * ```
+     */
+    create(data: PortalCreateTicketInput, options?: PortalCreateTicketOptions): Promise<PortalTicket>;
+    /**
+     * Add a comment to a ticket
+     *
+     * @param ticketId - Ticket ID
+     * @param body - Comment text
+     * @param options - Request options including idempotency key
+     * @returns Created comment
+     *
+     * @example
+     * ```typescript
+     * const comment = await portal.tickets.addComment(
+     *   'tkt_abc123',
+     *   'Here is the additional information you requested...'
+     * );
+     * ```
+     */
+    addComment(ticketId: string, body: string, options?: PortalAddCommentOptions): Promise<PortalComment>;
+    /**
+     * Build query parameters from filters
+     */
+    private buildListQuery;
+}
+
+/**
+ * Configuration options for the Dispatch Portal client
+ *
+ * @example
+ * ```typescript
+ * const portal = new DispatchPortal({
+ *   token: 'portal_token_from_backend...',
+ * });
+ * ```
+ */
+interface DispatchPortalConfig {
+    /**
+     * Portal token (required)
+     *
+     * Obtain this token by:
+     * 1. Your backend calls `client.brands.generatePortalToken()` with the customer's email
+     * 2. Pass the token to your frontend
+     * 3. Frontend creates DispatchPortal with this token
+     *
+     * Or for self-auth mode:
+     * 1. Customer clicks magic link email
+     * 2. Your portal page calls `DispatchPortal.verify()` with the URL token
+     * 3. Use the returned token to create DispatchPortal
+     */
+    token: string;
+    /**
+     * Base URL for the API
+     * @default 'https://dispatch-tickets-api.onrender.com/v1'
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Custom fetch implementation (for testing)
+     */
+    fetch?: FetchFunction;
+}
+/**
+ * Dispatch Portal SDK client
+ *
+ * Customer-facing client for interacting with the portal API.
+ * Use this to let customers view and manage their own tickets.
+ *
+ * @example Authenticated mode (backend generates token)
+ * ```typescript
+ * // On your backend:
+ * const client = new DispatchTickets({ apiKey: 'sk_live_...' });
+ * const { token } = await client.brands.generatePortalToken('br_abc123', {
+ *   email: 'customer@example.com',
+ *   name: 'Jane Doe',
+ * });
+ * // Pass token to frontend...
+ *
+ * // On your frontend:
+ * const portal = new DispatchPortal({ token });
+ * const { data: tickets } = await portal.tickets.list();
+ * ```
+ *
+ * @example Self-auth mode (magic link)
+ * ```typescript
+ * // Customer clicks magic link, lands on your portal with ?token=xyz
+ * const urlToken = new URLSearchParams(window.location.search).get('token');
+ *
+ * // Verify the magic link token
+ * const { token } = await DispatchPortal.verify(urlToken);
+ *
+ * // Now use the portal token
+ * const portal = new DispatchPortal({ token });
+ * const { data: tickets } = await portal.tickets.list();
+ * ```
+ */
+declare class DispatchPortal {
+    private readonly http;
+    private readonly config;
+    /**
+     * Tickets resource for viewing and creating tickets
+     *
+     * @example
+     * ```typescript
+     * // List tickets
+     * const { data: tickets } = await portal.tickets.list();
+     *
+     * // Create a ticket
+     * const ticket = await portal.tickets.create({
+     *   title: 'Need help',
+     *   body: 'Something is broken...',
+     * });
+     *
+     * // Add a comment
+     * await portal.tickets.addComment(ticket.id, 'Here is more info...');
+     * ```
+     */
+    readonly tickets: PortalTicketsResource;
+    /**
+     * Create a new Dispatch Portal client
+     *
+     * @param config - Portal client configuration
+     * @throws Error if token is not provided
+     */
+    constructor(config: DispatchPortalConfig);
+    /**
+     * Verify a magic link token and get a portal token
+     *
+     * Call this when the customer clicks the magic link and lands on your portal.
+     * The magic link contains a short-lived token that can be exchanged for a
+     * longer-lived portal token.
+     *
+     * @param magicLinkToken - The token from the magic link URL
+     * @param baseUrl - Optional API base URL
+     * @param fetchFn - Optional custom fetch function (for testing)
+     * @returns Portal token response
+     *
+     * @example
+     * ```typescript
+     * // Customer lands on: https://yourapp.com/portal?token=xyz
+     * const urlToken = new URLSearchParams(window.location.search).get('token');
+     *
+     * const { token, email, name } = await DispatchPortal.verify(urlToken);
+     *
+     * // Store token and create client
+     * localStorage.setItem('portalToken', token);
+     * const portal = new DispatchPortal({ token });
+     * ```
+     */
+    static verify(magicLinkToken: string, baseUrl?: string, fetchFn?: FetchFunction): Promise<PortalTokenResponse>;
+    /**
+     * Refresh the current portal token
+     *
+     * Call this before the token expires to get a new token with extended expiry.
+     * The new token will have the same customer context.
+     *
+     * @returns New portal token response
+     *
+     * @example
+     * ```typescript
+     * // Check if token is close to expiry and refresh
+     * const { token: newToken, expiresAt } = await portal.refresh();
+     *
+     * // Create new client with refreshed token
+     * const newPortal = new DispatchPortal({ token: newToken });
+     * ```
+     */
+    refresh(): Promise<PortalTokenResponse>;
+    /**
+     * Get the current token
+     *
+     * Useful for storing/passing the token.
+     */
+    get token(): string;
+}
+
 /**
  * Base error class for all Dispatch Tickets SDK errors
  */
@@ -1140,20 +2056,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
@@ -1166,7 +2094,7 @@ declare class ValidationError extends DispatchTicketsError {
     constructor(message?: string, errors?: Array<{
         field: string;
         message: string;
-    }>);
+    }>, requestId?: string);
 }
 /**
  * Thrown when a resource is not found
@@ -1174,19 +2102,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
@@ -1200,6 +2128,42 @@ 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
@@ -1379,4 +2343,4 @@ declare const webhookUtils: {
  */
 declare function collectAll<T>(iterable: AsyncIterable<T>): Promise<T[]>;
 
-export { type Account, type AccountUsage, type ApiKey, type ApiKeyWithSecret, 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 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 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, isCommentCreatedEvent, isTicketCreatedEvent, isTicketUpdatedEvent, parseWebhookEvent, 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, DispatchPortal, type DispatchPortalConfig, DispatchTickets, type DispatchTicketsConfig, DispatchTicketsError, type EntityType, type EventCommentData, type EventCustomerInfo, type FieldDefinition, type FieldDefinitions, type FieldType, type GeneratePortalTokenInput, type Hooks, type InitiateUploadInput, type InitiateUploadResponse, type Link, type ListCustomersFilters, type ListTicketsFilters, type MergeTagsInput, type MergeTicketsInput, NetworkError, NotFoundError, type PaginatedResponse, type PortalComment, type PortalCreateTicketInput, type PortalListTicketsFilters, type PortalTicket, type PortalTicketDetail, type PortalTicketListResponse, type PortalTokenResponse, RateLimitError, type RateLimitInfo, type RequestContext, type ResponseContext, type RetryConfig, type SendMagicLinkInput, 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 };