ticketnation-sdk 1.0.5 → 1.1.0

package/dist/index.d.mts

@@ -291,44 +291,212 @@ interface ApiErrorResponse {
     requestId: string;
 }
 
+/**
+ * Manage events on the Ticketnation marketplace.
+ *
+ * @example
+ * ```ts
+ * // Create and publish in one call
+ * const event = await tn.events.createAndPublish({
+ *   name: 'Summer Fest',
+ *   dateTime: '2026-06-15T18:00:00Z',
+ *   tickets: [{ name: 'GA', price: 1000, quantity: 500, published: true }],
+ * });
+ * ```
+ */
 declare class EventsResource {
     private readonly client;
     constructor(client: HttpClient);
+    /**
+     * Create a new event in DRAFT status.
+     * Optionally include inline ticket types, gallery images, and venue.
+     *
+     * @param params - Event creation parameters
+     * @returns The created event (status: DRAFT)
+     *
+     * @example
+     * ```ts
+     * const event = await tn.events.create({
+     *   name: 'Summer Music Fest',
+     *   dateTime: '2026-06-15T18:00:00Z',
+     *   venueId: 'uuid',
+     *   imageUrl: 'https://example.com/banner.jpg',
+     *   galleryUrls: ['https://example.com/photo1.jpg'],
+     *   tickets: [
+     *     { name: 'GA', price: 1000, quantity: 500, published: true },
+     *     { name: 'VIP', price: 3500, quantity: 50, published: true },
+     *   ],
+     * });
+     * ```
+     */
     create(params: CreateEventParams): Promise<Event>;
+    /**
+     * Create an event and immediately publish it.
+     * Convenience method that calls create() then publish().
+     *
+     * @returns The published event (status: PUBLISHED)
+     */
+    createAndPublish(params: CreateEventParams): Promise<Event>;
+    /**
+     * List events for your organization (paginated).
+     *
+     * @example
+     * ```ts
+     * const { data, meta } = await tn.events.list({ status: 'PUBLISHED', page: 1 });
+     * console.log(`${meta.total} published events`);
+     * ```
+     */
     list(params?: ListEventsParams): Promise<PaginatedResponse<Event>>;
+    /**
+     * Get a single event by UUID or slug.
+     *
+     * @example
+     * ```ts
+     * const event = await tn.events.get('summer-music-fest');
+     * // or
+     * const event = await tn.events.get('uuid-event-id');
+     * ```
+     */
     get(idOrSlug: string): Promise<Event>;
+    /**
+     * Update event fields. Only provided fields are changed.
+     * Cannot update inline tickets — use `tn.tickets` methods instead.
+     */
     update(eventId: string, params: UpdateEventParams): Promise<Event>;
+    /**
+     * Publish a DRAFT event to the marketplace.
+     * The event becomes visible to buyers on ticketnation.ph.
+     */
     publish(eventId: string): Promise<Event>;
+    /**
+     * Revert a PUBLISHED event back to DRAFT.
+     * Removes it from the public marketplace.
+     */
     unpublish(eventId: string): Promise<Event>;
+    /**
+     * Archive an event. Hidden from marketplace but data is preserved.
+     */
     archive(eventId: string): Promise<Event>;
+    /**
+     * Delete a DRAFT event. Only works if no tickets have been sold.
+     * Published or archived events must be unpublished first.
+     */
     delete(eventId: string): Promise<DeletedResponse>;
 }
 
+/**
+ * Manage ticket types for events.
+ * Prices are in whole pesos (e.g., 1000 = ₱1,000).
+ *
+ * @example
+ * ```ts
+ * const ticket = await tn.tickets.create(eventId, {
+ *   name: 'VIP Pass',
+ *   price: 3500,     // ₱3,500
+ *   quantity: 100,
+ *   published: true,  // immediately available for sale
+ * });
+ * ```
+ */
 declare class TicketsResource {
     private readonly client;
     constructor(client: HttpClient);
+    /**
+     * Create a ticket type for an event.
+     * Individual ticket inventory is auto-generated based on quantity.
+     *
+     * @param eventId - The event UUID
+     * @param params - Ticket type details
+     * @returns The created ticket type
+     */
     create(eventId: string, params: CreateTicketParams): Promise<Ticket>;
+    /**
+     * List all ticket types for an event.
+     */
     list(eventId: string): Promise<Ticket[]>;
+    /**
+     * Get a single ticket type by ID.
+     */
     get(eventId: string, ticketId: string): Promise<Ticket>;
+    /**
+     * Update a ticket type. Price and quantity changes are validated
+     * against business rules (e.g., can't reduce below sold count).
+     */
     update(eventId: string, ticketId: string, params: UpdateTicketParams): Promise<Ticket>;
+    /**
+     * Make a ticket type available for purchase.
+     * The parent event must also be published for tickets to appear.
+     */
     publish(eventId: string, ticketId: string): Promise<Ticket>;
+    /**
+     * Mark a ticket type as sold out (sets remainingQuantity to 0).
+     * To restore availability, use update() to set a new quantity.
+     */
     markSoldOut(eventId: string, ticketId: string): Promise<Ticket>;
+    /**
+     * Delete a ticket type. Only works if no tickets have been sold.
+     */
     delete(eventId: string, ticketId: string): Promise<DeletedResponse>;
 }
 
+/**
+ * Read-only access to orders for your events.
+ * Orders are created when buyers purchase tickets on ticketnation.ph.
+ *
+ * @example
+ * ```ts
+ * const { data: orders } = await tn.orders.list(eventId, { status: 'COMPLETED' });
+ * for (const order of orders) {
+ *   console.log(`#${order.orderNumber}: ${order.user.firstName} — ₱${order.total}`);
+ * }
+ * ```
+ */
 declare class OrdersResource {
     private readonly client;
     constructor(client: HttpClient);
+    /**
+     * List orders for an event (paginated).
+     * Filter by status to get only completed, pending, or refunded orders.
+     *
+     * @param eventId - The event UUID
+     * @param params - Pagination and filter options
+     */
     list(eventId: string, params?: ListOrdersParams): Promise<PaginatedResponse<Order>>;
+    /**
+     * Get a single order by ID. Includes line items and payment details.
+     *
+     * @param orderId - The order UUID
+     */
     get(orderId: string): Promise<Order>;
 }
 
+/**
+ * Search public venues on Ticketnation.
+ * Use the returned venue ID when creating events with a physical location.
+ *
+ * @example
+ * ```ts
+ * const { data: venues } = await tn.venues.search({ query: 'Mall of Asia' });
+ * const event = await tn.events.create({
+ *   name: 'Concert',
+ *   dateTime: '2026-06-15T18:00:00Z',
+ *   venueId: venues[0].id,  // ← link the venue
+ * });
+ * ```
+ */
 declare class VenuesResource {
     private readonly client;
     constructor(client: HttpClient);
+    /**
+     * Search venues by name (case-insensitive substring match).
+     *
+     * @param params - Search query and pagination
+     * @returns Paginated list of matching venues with address and coordinates
+     */
     search(params: SearchVenuesParams): Promise<PaginatedResponse<Venue>>;
 }
 
+/** Delivery record for a webhook event. */
 interface WebhookDelivery {
     id: string;
     eventType: string;
@@ -337,34 +505,75 @@ interface WebhookDelivery {
     attempts: number;
     createdAt: string;
 }
+/** Result of testing a webhook endpoint. */
 interface WebhookTestResult {
     success: boolean;
     statusCode: number | null;
     message: string;
 }
+/**
+ * Manage webhook endpoints for real-time notifications.
+ *
+ * @example
+ * ```ts
+ * // Create a webhook — store the secret securely!
+ * const webhook = await tn.webhooks.create({
+ *   url: 'https://api.example.com/webhooks/ticketnation',
+ *   events: ['order.completed', 'event.sold_out'],
+ * });
+ * console.log(webhook.secret); // whsec_... (only shown once)
+ *
+ * // Test it
+ * const result = await tn.webhooks.test(webhook.id);
+ * console.log(result.success); // true
+ * ```
+ */
 declare class WebhooksResource {
     private readonly client;
     constructor(client: HttpClient);
+    /**
+     * Create a webhook endpoint.
+     * The response includes a `secret` field for HMAC signature verification.
+     *
+     * **Important:** The secret is only returned on creation. Store it securely.
+     */
     create(params: CreateWebhookParams): Promise<WebhookWithSecret>;
+    /** List all webhooks for your API key. */
     list(): Promise<Webhook[]>;
+    /** Update a webhook's URL, events, or active status. */
     update(webhookId: string, params: UpdateWebhookParams): Promise<Webhook>;
+    /** Delete a webhook and its delivery history. */
     delete(webhookId: string): Promise<DeletedResponse>;
+    /** Send a test payload to verify your webhook endpoint works. */
     test(webhookId: string): Promise<WebhookTestResult>;
+    /**
+     * View delivery history for a webhook (paginated).
+     * Useful for debugging failed deliveries.
+     */
     deliveries(webhookId: string, params?: {
         page?: number;
         take?: number;
     }): Promise<PaginatedResponse<WebhookDelivery>>;
 }
 
+/** Parameters for creating a performer. */
 interface CreatePerformerParams {
+    /** Performer/artist name */
     name: string;
+    /** Bio or description */
     description?: string;
+    /** Performer type */
     type?: 'SOLO' | 'GROUP' | 'DJ' | 'BAND' | 'SPEAKER' | 'HOST' | 'COMEDIAN' | 'OTHER';
+    /** Public URL to performer image (hosted on your end) */
     imageUrl?: string;
+    /** Facebook profile URL */
     facebook?: string;
+    /** YouTube channel URL */
     youtube?: string;
+    /** Instagram profile URL */
     instagram?: string;
 }
+/** Performer details. */
 interface Performer {
     id: string;
     name: string;
@@ -379,24 +588,60 @@ interface Performer {
         url: string | null;
     } | null;
 }
+/**
+ * Manage performers/artists/speakers for events.
+ *
+ * @example
+ * ```ts
+ * await tn.performers.create(eventId, {
+ *   name: 'DJ Shadow',
+ *   type: 'SOLO',
+ *   imageUrl: 'https://example.com/dj-shadow.jpg',
+ * });
+ *
+ * const performers = await tn.performers.list(eventId);
+ * ```
+ */
 declare class PerformersResource {
     private readonly client;
     constructor(client: HttpClient);
+    /**
+     * Add a performer to an event.
+     * If `imageUrl` is provided, it will be displayed on the event page.
+     *
+     * @param eventId - The event UUID
+     * @param params - Performer details
+     */
     create(eventId: string, params: CreatePerformerParams): Promise<Performer>;
+    /** List all performers for an event. */
     list(eventId: string): Promise<Performer[]>;
+    /**
+     * Remove a performer from an event.
+     * This unlinks the performer — it doesn't delete the performer record.
+     */
     remove(eventId: string, performerId: string): Promise<DeletedResponse>;
 }
 
+/** Parameters for creating a schedule item. */
 interface CreateScheduleParams {
+    /** Schedule item title (e.g., "Doors Open", "DJ Shadow Live") */
     title: string;
+    /** Description of this schedule block */
     description?: string;
+    /** Start time (ISO 8601) */
     startTime: string;
+    /** End time (ISO 8601) */
     endTime: string;
+    /** Emoji or icon name */
     icon?: string;
+    /** Hex color code (e.g., "#4f46e5") */
     color?: string;
+    /** Sort position (auto-assigned if not provided) */
     sortOrder?: number;
+    /** Link this schedule item to a performer */
     performerId?: string;
 }
+/** Parameters for updating a schedule item. All fields optional. */
 interface UpdateScheduleParams {
     title?: string;
     description?: string;
@@ -407,6 +652,7 @@ interface UpdateScheduleParams {
     sortOrder?: number;
     performerId?: string;
 }
+/** Schedule item details. */
 interface Schedule {
     id: string;
     title: string;
@@ -424,22 +670,59 @@ interface Schedule {
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * Manage event schedule / timeline items.
+ *
+ * @example
+ * ```ts
+ * // Create a full event schedule
+ * await tn.schedules.create(eventId, {
+ *   title: 'Doors Open',
+ *   startTime: '2026-09-15T19:00:00Z',
+ *   endTime: '2026-09-15T19:30:00Z',
+ *   icon: '🎵',
+ * });
+ *
+ * await tn.schedules.create(eventId, {
+ *   title: 'DJ Shadow Live',
+ *   startTime: '2026-09-15T21:00:00Z',
+ *   endTime: '2026-09-15T23:00:00Z',
+ *   performerId: performer.id,  // link to a performer
+ * });
+ * ```
+ */
 declare class SchedulesResource {
     private readonly client;
     constructor(client: HttpClient);
+    /**
+     * Add a schedule item to an event.
+     *
+     * @param eventId - The event UUID
+     * @param params - Schedule item details
+     */
     create(eventId: string, params: CreateScheduleParams): Promise<Schedule>;
+    /** List all schedule items for an event, ordered by sortOrder. */
     list(eventId: string): Promise<Schedule[]>;
+    /** Update a schedule item. Only provided fields are changed. */
     update(eventId: string, scheduleId: string, params: UpdateScheduleParams): Promise<Schedule>;
+    /** Delete a schedule item. */
     remove(eventId: string, scheduleId: string): Promise<DeletedResponse>;
 }
 
+/** Parameters for creating a brand partner. */
 interface CreateBrandParams {
+    /** Brand/sponsor name */
     name: string;
+    /** Brand description */
     description?: string;
+    /** Brand website URL */
     url?: string;
+    /** Public URL to brand logo (hosted on your end) */
     imageUrl?: string;
+    /** Display position (lower = first) */
     position?: number;
 }
+/** Brand partner details. */
 interface Brand {
     id: string;
     name: string;
@@ -452,22 +735,69 @@ interface Brand {
     } | null;
     position: number | null;
 }
+/**
+ * Manage brand partners / sponsors for events.
+ *
+ * @example
+ * ```ts
+ * await tn.brands.create(eventId, {
+ *   name: 'Red Bull',
+ *   url: 'https://redbull.com',
+ *   imageUrl: 'https://example.com/redbull-logo.png',
+ * });
+ * ```
+ */
 declare class BrandsResource {
     private readonly client;
     constructor(client: HttpClient);
+    /**
+     * Add a brand partner to an event.
+     * If a brand with the same name already exists in your org, it will be reused.
+     *
+     * @param eventId - The event UUID
+     * @param params - Brand details
+     */
     create(eventId: string, params: CreateBrandParams): Promise<Brand>;
+    /** List all brand partners for an event. */
     list(eventId: string): Promise<Brand[]>;
+    /**
+     * Remove a brand from an event.
+     * This unlinks the brand — it doesn't delete the brand record.
+     */
     remove(eventId: string, brandId: string): Promise<DeletedResponse>;
 }
 
+/**
+ * Error thrown by the Ticketnation SDK for all API and network errors.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await tn.events.get('nonexistent');
+ * } catch (error) {
+ *   if (error instanceof TicketnationError) {
+ *     console.log(error.code);      // 'NOT_FOUND'
+ *     console.log(error.status);    // 404
+ *     console.log(error.message);   // 'Event not found: nonexistent'
+ *     console.log(error.requestId); // 'req_abc123' (for support)
+ *   }
+ * }
+ * ```
+ */
 declare class TicketnationError extends Error {
+    /** Machine-readable error code (e.g., 'NOT_FOUND', 'VALIDATION_ERROR', 'RATE_LIMITED') */
     readonly code: string;
+    /** HTTP status code (0 for network/timeout errors) */
     readonly status: number;
+    /** Unique request ID for debugging (include in support tickets) */
     readonly requestId: string | null;
+    /** Field-level validation errors (only for VALIDATION_ERROR) */
     readonly details: Array<{
         field: string;
         message: string;
     }> | undefined;
+    /** Suggested fix for common errors */
+    readonly hint: string | null;
     constructor(message: string, opts: {
         code: string;
         status: number;
@@ -481,6 +811,8 @@ declare class TicketnationError extends Error {
         error: ApiErrorBody;
         requestId?: string;
     }): TicketnationError;
+    private static getHint;
+    /** Serialize error for logging or API responses. */
     toJSON(): {
         name: string;
         code: string;
@@ -491,24 +823,111 @@ declare class TicketnationError extends Error {
             field: string;
             message: string;
         }[] | undefined;
+        hint: string | null;
     };
+    /** Human-readable error summary. */
+    toString(): string;
 }
 
 declare function paginate<T>(fetchPage: (params: PaginationParams) => Promise<PaginatedResponse<T>>, initialParams?: PaginationParams): AsyncGenerator<T[], void, undefined>;
 declare function fetchAllPages<T>(fetchPage: (params: PaginationParams) => Promise<PaginatedResponse<T>>, initialParams?: PaginationParams): Promise<T[]>;
 
+/**
+ * Format a price value to a human-readable Philippine Peso string.
+ *
+ * @example
+ * ```ts
+ * formatPeso(1000)  // "₱1,000.00"
+ * formatPeso(3500)  // "₱3,500.00"
+ * formatPeso(0)     // "Free"
+ * ```
+ */
+declare function formatPeso(amount: number): string;
+/**
+ * Validate that a price is a non-negative integer.
+ * Ticketnation prices are whole pesos (e.g., 1000 = ₱1,000).
+ *
+ * @throws Error if price is invalid
+ */
+declare function validatePrice(price: number, fieldName?: string): void;
+
+/**
+ * Ticketnation SDK — publish events, manage tickets, and receive orders programmatically.
+ *
+ * @example
+ * ```ts
+ * import { Ticketnation } from 'ticketnation-sdk';
+ *
+ * const tn = new Ticketnation({ apiKey: 'tn_live_...' });
+ *
+ * // Create and publish an event in one call
+ * const event = await tn.events.createAndPublish({
+ *   name: 'Summer Fest 2026',
+ *   dateTime: '2026-06-15T18:00:00Z',
+ *   imageUrl: 'https://example.com/banner.jpg',
+ *   tickets: [
+ *     { name: 'GA', price: 1000, quantity: 500, published: true },
+ *   ],
+ * });
+ *
+ * // Add performers and schedule
+ * const dj = await tn.performers.create(event.id, { name: 'DJ Shadow', type: 'SOLO' });
+ * await tn.schedules.create(event.id, {
+ *   title: 'DJ Shadow Live',
+ *   startTime: '2026-06-15T21:00:00Z',
+ *   endTime: '2026-06-15T23:00:00Z',
+ *   performerId: dj.id,
+ * });
+ *
+ * // Check orders
+ * const { data: orders } = await tn.orders.list(event.id);
+ * ```
+ *
+ * @see https://docs.ticketnation.ph/developers/overview
+ */
 declare class Ticketnation {
+    /** Create, list, update, publish, and delete events. */
     readonly events: EventsResource;
+    /** Create, list, update, and manage ticket types. Prices are in whole pesos. */
     readonly tickets: TicketsResource;
+    /** Read-only access to orders placed by buyers. */
     readonly orders: OrdersResource;
+    /** Search public venues by name. */
     readonly venues: VenuesResource;
+    /** Manage webhook endpoints for real-time notifications. */
     readonly webhooks: WebhooksResource;
+    /** Add and manage performers/artists/speakers for events. */
     readonly performers: PerformersResource;
+    /** Create event schedule / timeline items. */
     readonly schedules: SchedulesResource;
+    /** Add brand partners / sponsors to events. */
     readonly brands: BrandsResource;
     private readonly client;
+    /**
+     * Create a new Ticketnation SDK instance.
+     *
+     * @param config - SDK configuration
+     * @param config.apiKey - Your API key from Organizer Dashboard > Settings > API Keys
+     * @param config.baseUrl - API base URL (default: https://api.ticketnation.ph)
+     * @param config.timeout - Request timeout in ms (default: 30000)
+     * @param config.retries - Retry count on 5xx errors (default: 2)
+     * @param config.debug - Log requests with redacted API key (default: false)
+     */
     constructor(config: TicketnationConfig);
+    /**
+     * Get information about your API key and organization.
+     * Useful for verifying your key is correctly configured.
+     *
+     * @returns API key details (name, scopes, expiry) and organization info
+     *
+     * @example
+     * ```ts
+     * const info = await tn.me();
+     * console.log(`Org: ${info.organization.name}`);
+     * console.log(`Scopes: ${info.apiKey.scopes.join(', ')}`);
+     * ```
+     */
     me(): Promise<AccountInfo>;
 }
 
-export { type AccountInfo, type ApiErrorBody, type ApiErrorResponse, type ApiKeyInfo, type Brand, type CreateBrandParams, type CreateEventParams, type CreatePerformerParams, type CreateScheduleParams, type CreateTicketParams, type CreateWebhookParams, type DataResponse, type DeletedResponse, type Event, type EventJourneyType, type EventLocationType, type EventStatus, type EventType, type EventVisibility, type ListEventsParams, type ListOrdersParams, type Order, type OrderItem, type OrderItemTicket, type OrderPayment, type OrderStatus, type OrderUser, type OrganizationInfo, type PaginatedResponse, type PaginationMeta, type PaginationParams, type Performer, type Schedule, type SearchVenuesParams, type Ticket, type TicketSeatType, type TicketStatus, Ticketnation, type TicketnationConfig, TicketnationError, type UpdateEventParams, type UpdateScheduleParams, type UpdateTicketParams, type UpdateWebhookParams, type Venue, type VenueRef, type Webhook, type WebhookEventType, type WebhookWithSecret, fetchAllPages, paginate };
+export { type AccountInfo, type ApiErrorBody, type ApiErrorResponse, type ApiKeyInfo, type Brand, type CreateBrandParams, type CreateEventParams, type CreatePerformerParams, type CreateScheduleParams, type CreateTicketParams, type CreateWebhookParams, type DataResponse, type DeletedResponse, type Event, type EventJourneyType, type EventLocationType, type EventStatus, type EventType, type EventVisibility, type ListEventsParams, type ListOrdersParams, type Order, type OrderItem, type OrderItemTicket, type OrderPayment, type OrderStatus, type OrderUser, type OrganizationInfo, type PaginatedResponse, type PaginationMeta, type PaginationParams, type Performer, type Schedule, type SearchVenuesParams, type Ticket, type TicketSeatType, type TicketStatus, Ticketnation, type TicketnationConfig, TicketnationError, type UpdateEventParams, type UpdateScheduleParams, type UpdateTicketParams, type UpdateWebhookParams, type Venue, type VenueRef, type Webhook, type WebhookDelivery, type WebhookEventType, type WebhookTestResult, type WebhookWithSecret, fetchAllPages, formatPeso, paginate, validatePrice };