@dispatchtickets/sdk 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,9 +1,17 @@
+/**
+ * Custom fetch function type
+ */
+type FetchFunction = typeof fetch;
 interface HttpClientConfig {
     baseUrl: string;
     apiKey: string;
     timeout: number;
     maxRetries: number;
     debug?: boolean;
+    /**
+     * Custom fetch implementation for testing/mocking
+     */
+    fetch?: FetchFunction;
 }
 interface RequestOptions {
     method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
@@ -18,6 +26,7 @@ interface RequestOptions {
  */
 declare class HttpClient {
     private readonly config;
+    private readonly fetchFn;
     constructor(config: HttpClientConfig);
     /**
      * Execute an HTTP request with retry logic
@@ -47,6 +56,104 @@ declare abstract class BaseResource {
     protected _delete<T>(path: string, query?: RequestOptions['query']): Promise<T>;
 }
 
+/**
+ * Account represents the organization/company using Dispatch Tickets
+ */
+interface Account {
+    id: string;
+    stackbeCustomerId: string;
+    stackbeOrganizationId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Usage statistics for the account
+ */
+interface AccountUsage {
+    ticketsThisMonth: number;
+    ticketsTotal: number;
+    brandsCount: number;
+    plan?: {
+        name: string;
+        ticketLimit: number;
+        brandLimit: number | null;
+    };
+}
+/**
+ * API key for programmatic access
+ */
+interface ApiKey {
+    id: string;
+    name: string;
+    keyPreview: string;
+    allBrands: boolean;
+    brandIds: string[];
+    lastUsedAt: string | null;
+    createdAt: string;
+}
+/**
+ * API key with the full key value (only returned on creation)
+ */
+interface ApiKeyWithSecret extends ApiKey {
+    key: string;
+}
+/**
+ * Input for creating an API key
+ */
+interface CreateApiKeyInput {
+    name: string;
+    /**
+     * If true, the API key can access all brands (current and future)
+     */
+    allBrands?: boolean;
+    /**
+     * Specific brand IDs this key can access (ignored if allBrands is true)
+     */
+    brandIds?: string[];
+}
+/**
+ * Input for updating API key scope
+ */
+interface UpdateApiKeyScopeInput {
+    allBrands?: boolean;
+    brandIds?: string[];
+}
+
+/**
+ * Accounts resource for managing the current account
+ */
+declare class AccountsResource extends BaseResource {
+    /**
+     * Get the current account
+     */
+    me(): Promise<Account>;
+    /**
+     * Get usage statistics for the current account
+     */
+    getUsage(): Promise<AccountUsage>;
+    /**
+     * List all API keys for the current account
+     */
+    listApiKeys(): Promise<ApiKey[]>;
+    /**
+     * Create a new API key
+     *
+     * Note: The full key value is only returned once on creation.
+     * Store it securely as it cannot be retrieved again.
+     */
+    createApiKey(data: CreateApiKeyInput): Promise<ApiKeyWithSecret>;
+    /**
+     * Update the brand scope for an API key
+     */
+    updateApiKeyScope(keyId: string, data: UpdateApiKeyScopeInput): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Revoke an API key
+     */
+    revokeApiKey(keyId: string): Promise<void>;
+}
+
 /**
  * Brand (workspace) resource
  */
@@ -144,6 +251,26 @@ declare class BrandsResource extends BaseResource {
      * Update the ticket schema for a brand
      */
     updateSchema(brandId: string, schema: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Get the inbound email address for a brand
+     *
+     * Emails sent to this address will automatically create tickets.
+     *
+     * @param brandId - The brand ID
+     * @param domain - Optional custom inbound domain (default: inbound.dispatchtickets.com)
+     * @returns The inbound email address
+     *
+     * @example
+     * ```typescript
+     * const email = client.brands.getInboundEmail('br_abc123');
+     * // Returns: br_abc123@inbound.dispatchtickets.com
+     *
+     * // With custom domain:
+     * const customEmail = client.brands.getInboundEmail('br_abc123', 'support.mycompany.com');
+     * // Returns: br_abc123@support.mycompany.com
+     * ```
+     */
+    getInboundEmail(brandId: string, domain?: string): string;
 }
 
 /**
@@ -185,9 +312,10 @@ type AuthorType = 'CUSTOMER' | 'AGENT' | 'SYSTEM';
  */
 type AttachmentStatus = 'PENDING' | 'UPLOADED' | 'FAILED';
 /**
- * Webhook event types
+ * Webhook event type strings (for subscription)
+ * @deprecated Use WebhookEventType from events.ts for typed event handling
  */
-type WebhookEvent = 'ticket.created' | 'ticket.updated' | 'ticket.deleted' | 'comment.created' | 'comment.updated' | 'comment.deleted' | 'attachment.created' | 'attachment.deleted';
+type WebhookEventName = 'ticket.created' | 'ticket.updated' | 'ticket.deleted' | 'ticket.comment.created' | 'comment.created' | 'comment.updated' | 'comment.deleted' | 'attachment.created' | 'attachment.deleted';
 /**
  * Custom field types
  */
@@ -655,7 +783,7 @@ interface Webhook {
     id: string;
     brandId: string;
     url: string;
-    events: WebhookEvent[];
+    events: WebhookEventName[];
     enabled: boolean;
     failureCount: number;
     lastTriggered?: string;
@@ -669,7 +797,7 @@ interface Webhook {
 interface CreateWebhookInput {
     url: string;
     secret: string;
-    events: WebhookEvent[];
+    events: WebhookEventName[];
 }
 /**
  * Webhook delivery record
@@ -677,7 +805,7 @@ interface CreateWebhookInput {
 interface WebhookDelivery {
     id: string;
     webhookId: string;
-    event: WebhookEvent;
+    event: WebhookEventName;
     payload: Record<string, unknown>;
     status: 'PENDING' | 'SUCCESS' | 'FAILED' | 'RETRYING';
     attempts: number;
@@ -922,6 +1050,10 @@ interface DispatchTicketsConfig {
      * @default false
      */
     debug?: boolean;
+    /**
+     * Custom fetch implementation for testing/mocking
+     */
+    fetch?: FetchFunction;
 }
 /**
  * Dispatch Tickets SDK client
@@ -951,6 +1083,10 @@ interface DispatchTicketsConfig {
  */
 declare class DispatchTickets {
     private readonly http;
+    /**
+     * Accounts resource for managing the current account and API keys
+     */
+    readonly accounts: AccountsResource;
     /**
      * Brands (workspaces) resource
      */
@@ -1065,6 +1201,136 @@ declare class NetworkError extends DispatchTicketsError {
     constructor(message?: string);
 }
 
+/**
+ * All supported webhook event types
+ */
+type WebhookEventType = 'ticket.created' | 'ticket.updated' | 'ticket.comment.created';
+/**
+ * Base webhook event envelope
+ */
+interface WebhookEventEnvelope<T extends WebhookEventType, D> {
+    /** Unique event ID */
+    id: string;
+    /** Event type */
+    event: T;
+    /** Brand ID that triggered the event */
+    brand_id: string;
+    /** Event data */
+    data: D;
+    /** ISO timestamp when event was created */
+    timestamp: string;
+}
+/**
+ * Customer info included in events
+ */
+interface EventCustomerInfo {
+    customerId: string | null;
+    customerEmail: string | null;
+    customerName: string | null;
+}
+/**
+ * Payload for ticket.created event
+ */
+interface TicketCreatedData extends EventCustomerInfo {
+    id: string;
+    ticketNumber: number;
+    title: string;
+    status: TicketStatus;
+    priority: TicketPriority;
+    source: TicketSource;
+    createdAt: string;
+}
+/**
+ * Payload for ticket.updated event
+ */
+interface TicketUpdatedData extends EventCustomerInfo {
+    id: string;
+    ticketNumber: number;
+    title: string;
+    status: TicketStatus;
+    priority: TicketPriority;
+    assigneeId: string | null;
+    updatedAt: string;
+    /** List of field names that were changed */
+    changes: string[];
+}
+/**
+ * Comment data in ticket.comment.created event
+ */
+interface EventCommentData {
+    id: string;
+    body: string;
+    authorId: string | null;
+    authorType: AuthorType;
+    createdAt: string;
+}
+/**
+ * Payload for ticket.comment.created event
+ */
+interface CommentCreatedData extends EventCustomerInfo {
+    ticketId: string;
+    /** Formatted ticket number (e.g., "ACME-123") */
+    ticketNumber: string;
+    comment: EventCommentData;
+}
+/**
+ * Ticket created webhook event
+ */
+type TicketCreatedEvent = WebhookEventEnvelope<'ticket.created', TicketCreatedData>;
+/**
+ * Ticket updated webhook event
+ */
+type TicketUpdatedEvent = WebhookEventEnvelope<'ticket.updated', TicketUpdatedData>;
+/**
+ * Comment created webhook event
+ */
+type CommentCreatedEvent = WebhookEventEnvelope<'ticket.comment.created', CommentCreatedData>;
+/**
+ * Union of all webhook events
+ */
+type WebhookEvent = TicketCreatedEvent | TicketUpdatedEvent | CommentCreatedEvent;
+/**
+ * Map of event types to their data types
+ */
+interface WebhookEventMap {
+    'ticket.created': TicketCreatedEvent;
+    'ticket.updated': TicketUpdatedEvent;
+    'ticket.comment.created': CommentCreatedEvent;
+}
+/**
+ * Type guard to check if event is a ticket.created event
+ */
+declare function isTicketCreatedEvent(event: WebhookEvent): event is TicketCreatedEvent;
+/**
+ * Type guard to check if event is a ticket.updated event
+ */
+declare function isTicketUpdatedEvent(event: WebhookEvent): event is TicketUpdatedEvent;
+/**
+ * Type guard to check if event is a ticket.comment.created event
+ */
+declare function isCommentCreatedEvent(event: WebhookEvent): event is CommentCreatedEvent;
+/**
+ * Parse and validate a webhook payload
+ *
+ * @param payload - Raw JSON payload string or parsed object
+ * @returns Typed webhook event
+ * @throws Error if payload is invalid
+ *
+ * @example
+ * ```typescript
+ * import { parseWebhookEvent, isTicketCreatedEvent } from '@dispatchtickets/sdk';
+ *
+ * app.post('/webhooks', (req, res) => {
+ *   const event = parseWebhookEvent(req.body);
+ *
+ *   if (isTicketCreatedEvent(event)) {
+ *     console.log('New ticket:', event.data.title);
+ *   }
+ * });
+ * ```
+ */
+declare function parseWebhookEvent(payload: string | object): WebhookEvent;
+
 /**
  * Webhook signature verification utilities
  */
@@ -1113,4 +1379,4 @@ declare const webhookUtils: {
  */
 declare function collectAll<T>(iterable: AsyncIterable<T>): Promise<T[]>;
 
-export { type Attachment, type AttachmentStatus, type AttachmentWithUrl, AuthenticationError, type AuthorType, type Brand, type BulkAction, type BulkActionResult, type Category, type CategoryStats, type Comment, type Company, ConflictError, type CreateBrandInput, type CreateCategoryInput, type CreateCommentInput, type CreateCommentOptions, type CreateCustomerInput, type CreateFieldInput, type CreateTagInput, type CreateTicketInput, type CreateTicketOptions, type CreateWebhookInput, type Customer, type DeleteBrandPreview, DispatchTickets, type DispatchTicketsConfig, DispatchTicketsError, type EntityType, type FieldDefinition, type FieldDefinitions, type FieldType, type InitiateUploadInput, type InitiateUploadResponse, type Link, type ListCustomersFilters, type ListTicketsFilters, type MergeTagsInput, type MergeTicketsInput, NetworkError, NotFoundError, type PaginatedResponse, RateLimitError, ServerError, type SortOrder, type Tag, type Ticket, type TicketPriority, type TicketSource, type TicketStatus, TimeoutError, type UpdateBrandInput, type UpdateCategoryInput, type UpdateCommentInput, type UpdateCustomerInput, type UpdateFieldInput, type UpdateTagInput, type UpdateTicketInput, ValidationError, type Webhook, type WebhookDelivery, type WebhookEvent, collectAll, webhookUtils };
+export { type Account, type AccountUsage, type ApiKey, type ApiKeyWithSecret, type 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 };