@dispatchtickets/sdk 0.3.0 → 0.6.0

package/dist/index.js

@@ -5,33 +5,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;
   }
@@ -39,22 +51,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";
   }
 };
@@ -70,14 +82,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
@@ -87,43 +153,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) {
@@ -147,9 +259,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}`);
@@ -157,6 +271,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,
@@ -167,6 +284,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);
@@ -174,11 +294,42 @@ var HttpClient = class {
       throw new NetworkError("Unknown network error");
     } finally {
       clearTimeout(timeoutId);
+      userSignal?.removeEventListener("abort", abortHandler);
+    }
+  }
+  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) {
+  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;
@@ -195,31 +346,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));
   }
@@ -231,11 +387,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) {
@@ -244,28 +401,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
     });
   }
 };
@@ -388,6 +549,66 @@ var BrandsResource = class extends BaseResource {
   getInboundEmail(brandId, domain = "inbound.dispatchtickets.com") {
     return `${brandId}@${domain}`;
   }
+  // ===========================================================================
+  // Portal Token Management
+  // ===========================================================================
+  /**
+   * 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 });
+   * ```
+   */
+  async generatePortalToken(brandId, data) {
+    return this._post(`/brands/${brandId}/portal/token`, data);
+  }
+  /**
+   * 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)
+   * ```
+   */
+  async sendPortalMagicLink(brandId, data) {
+    return this._post(`/brands/${brandId}/portal/magic-link`, data);
+  }
 };
 
 // src/resources/tickets.ts
@@ -904,48 +1125,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");
@@ -954,9 +1334,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);
@@ -972,6 +1354,256 @@ var DispatchTickets = class {
   }
 };
 
+// src/resources/portal-tickets.ts
+var PortalTicketsResource = class 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 });
+   * ```
+   */
+  async list(filters, options) {
+    const query = this.buildListQuery(filters);
+    return this._get("/portal/tickets", query, options);
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async *listAll(filters) {
+    let cursor;
+    let hasMore = true;
+    while (hasMore) {
+      const response = await this.list({ ...filters, cursor });
+      for (const ticket of response.data) {
+        yield ticket;
+      }
+      cursor = response.pagination.nextCursor ?? void 0;
+      hasMore = response.pagination.hasMore;
+    }
+  }
+  /**
+   * 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`);
+   * ```
+   */
+  async get(ticketId, options) {
+    return this._get(`/portal/tickets/${ticketId}`, void 0, options);
+  }
+  /**
+   * 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...',
+   * });
+   * ```
+   */
+  async create(data, options) {
+    return this._post("/portal/tickets", data, {
+      idempotencyKey: options?.idempotencyKey,
+      signal: options?.signal
+    });
+  }
+  /**
+   * 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...'
+   * );
+   * ```
+   */
+  async addComment(ticketId, body, options) {
+    return this._post(`/portal/tickets/${ticketId}/comments`, { body }, {
+      idempotencyKey: options?.idempotencyKey,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Build query parameters from filters
+   */
+  buildListQuery(filters) {
+    if (!filters) return void 0;
+    const query = {};
+    if (filters.status) query.status = filters.status;
+    if (filters.sort) query.sort = filters.sort;
+    if (filters.order) query.order = filters.order;
+    if (filters.limit) query.limit = filters.limit;
+    if (filters.cursor) query.cursor = filters.cursor;
+    return Object.keys(query).length > 0 ? query : void 0;
+  }
+};
+
+// src/portal.ts
+var DEFAULT_BASE_URL = "https://dispatch-tickets-api.onrender.com/v1";
+var DEFAULT_TIMEOUT = 3e4;
+var DispatchPortal = class {
+  http;
+  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...');
+   * ```
+   */
+  tickets;
+  /**
+   * Create a new Dispatch Portal client
+   *
+   * @param config - Portal client configuration
+   * @throws Error if token is not provided
+   */
+  constructor(config) {
+    if (!config.token) {
+      throw new Error("Portal token is required");
+    }
+    this.config = config;
+    const httpConfig = {
+      baseUrl: config.baseUrl || DEFAULT_BASE_URL,
+      apiKey: config.token,
+      // HttpClient uses this as Bearer token
+      timeout: config.timeout ?? DEFAULT_TIMEOUT,
+      maxRetries: 2,
+      // Fewer retries for portal (end-user experience)
+      fetch: config.fetch
+    };
+    this.http = new HttpClient(httpConfig);
+    this.tickets = new PortalTicketsResource(this.http);
+  }
+  /**
+   * 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 async verify(magicLinkToken, baseUrl = DEFAULT_BASE_URL, fetchFn = fetch) {
+    const url = `${baseUrl}/portal/verify`;
+    const response = await fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Accept": "application/json"
+      },
+      body: JSON.stringify({ token: magicLinkToken })
+    });
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+      throw new Error(errorData.message || "Failed to verify magic link token");
+    }
+    return response.json();
+  }
+  /**
+   * 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 });
+   * ```
+   */
+  async refresh() {
+    return this.http.request({
+      method: "POST",
+      path: "/portal/refresh"
+    });
+  }
+  /**
+   * Get the current token
+   *
+   * Useful for storing/passing the token.
+   */
+  get token() {
+    return this.config.token;
+  }
+};
+
 // src/types/events.ts
 function isTicketCreatedEvent(event) {
   return event.event === "ticket.created";
@@ -1012,6 +1644,6 @@ async function collectAll(iterable) {
   return items;
 }
 
-export { AuthenticationError, ConflictError, DispatchTickets, DispatchTicketsError, NetworkError, NotFoundError, RateLimitError, ServerError, TimeoutError, ValidationError, collectAll, isCommentCreatedEvent, isTicketCreatedEvent, isTicketUpdatedEvent, parseWebhookEvent, webhookUtils };
+export { AuthenticationError, ConflictError, DispatchPortal, DispatchTickets, DispatchTicketsError, NetworkError, NotFoundError, RateLimitError, ServerError, TimeoutError, ValidationError, collectAll, isAuthenticationError, isCommentCreatedEvent, isConflictError, isDispatchTicketsError, isNetworkError, isNotFoundError, isRateLimitError, isServerError, isTicketCreatedEvent, isTicketUpdatedEvent, isTimeoutError, isValidationError, parseWebhookEvent, webhookUtils };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map