@dispatchtickets/sdk 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -551,6 +551,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
@@ -1296,6 +1356,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";
@@ -1338,6 +1648,7 @@ async function collectAll(iterable) {
 
 exports.AuthenticationError = AuthenticationError;
 exports.ConflictError = ConflictError;
+exports.DispatchPortal = DispatchPortal;
 exports.DispatchTickets = DispatchTickets;
 exports.DispatchTicketsError = DispatchTicketsError;
 exports.NetworkError = NetworkError;