@dispatchtickets/sdk 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -387,6 +387,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
  */
@@ -441,6 +569,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;
+    }>;
 }
 
 /**
@@ -1579,6 +1762,289 @@ declare class DispatchTickets {
     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
  */
@@ -1873,4 +2339,4 @@ declare const webhookUtils: {
  */
 declare function collectAll<T>(iterable: AsyncIterable<T>): Promise<T[]>;
 
-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 };
+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 };