ticketnation-sdk 1.0.0

package/README.md

@@ -0,0 +1,208 @@
+# @ticketnation/sdk
+
+Official TypeScript SDK for the [Ticketnation](https://ticketnation.ph) Open API. Publish events, manage tickets, receive orders, and search venues programmatically.
+
+## Installation
+
+```bash
+npm install @ticketnation/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Ticketnation } from '@ticketnation/sdk';
+
+const tn = new Ticketnation({
+  apiKey: 'tn_live_your_api_key_here',
+});
+
+// Create an event with tickets
+const event = await tn.events.create({
+  name: 'Summer Music Fest 2025',
+  dateTime: '2025-06-15T18:00:00.000Z',
+  venueId: 'uuid-venue-id',
+  tickets: [
+    { name: 'General Admission', price: 150000, quantity: 500 },
+    { name: 'VIP', price: 500000, quantity: 50 },
+  ],
+});
+
+// Publish it
+await tn.events.publish(event.id);
+```
+
+## Configuration
+
+```typescript
+const tn = new Ticketnation({
+  apiKey: 'tn_live_...',             // Required
+  baseUrl: 'http://localhost:4000',  // Default: https://api.ticketnation.ph
+  timeout: 30000,                    // Default: 30s
+  retries: 2,                        // Default: 2 (retries on 5xx only)
+  debug: false,                      // Default: false (logs redacted requests)
+});
+```
+
+## API Reference
+
+### Account
+
+```typescript
+// Get API key info and organization details
+const info = await tn.me();
+// → { apiKey: { id, name, scopes, ... }, organization: { id, name, slug } }
+```
+
+### Events
+
+```typescript
+// Create
+const event = await tn.events.create({ name: '...', dateTime: '...' });
+
+// List (paginated)
+const { data, meta } = await tn.events.list({ page: 1, take: 10, status: 'PUBLISHED' });
+
+// Get by ID or slug
+const event = await tn.events.get('summer-music-fest-2025');
+
+// Update
+const updated = await tn.events.update(eventId, { name: 'New Name' });
+
+// Lifecycle
+await tn.events.publish(eventId);
+await tn.events.unpublish(eventId);
+await tn.events.archive(eventId);
+
+// Delete (DRAFT only, no sold tickets)
+await tn.events.delete(eventId);
+```
+
+### Tickets
+
+```typescript
+// Create a ticket type for an event
+const ticket = await tn.tickets.create(eventId, {
+  name: 'VIP Pass',
+  price: 500000,    // in centavos (5,000.00 PHP)
+  quantity: 100,
+});
+
+// List all ticket types
+const tickets = await tn.tickets.list(eventId);
+
+// Get single ticket
+const ticket = await tn.tickets.get(eventId, ticketId);
+
+// Update price or quantity
+await tn.tickets.update(eventId, ticketId, { price: 450000 });
+
+// Publish (make available for sale)
+await tn.tickets.publish(eventId, ticketId);
+
+// Mark as sold out (sets remainingQuantity to 0)
+await tn.tickets.markSoldOut(eventId, ticketId);
+
+// Delete (only if no tickets sold)
+await tn.tickets.delete(eventId, ticketId);
+```
+
+### Orders
+
+```typescript
+// List orders for an event (paginated)
+const { data, meta } = await tn.orders.list(eventId, { page: 1, status: 'COMPLETED' });
+
+// Get order details (includes line items and payment info)
+const order = await tn.orders.get(orderId);
+```
+
+### Venues
+
+```typescript
+// Search venues by name
+const { data, meta } = await tn.venues.search({ query: 'MOA Arena' });
+// Use venue.id when creating events with locationType: 'VENUE'
+```
+
+## Pagination Helper
+
+For iterating through all pages automatically:
+
+```typescript
+import { Ticketnation, paginate, fetchAllPages } from '@ticketnation/sdk';
+
+const tn = new Ticketnation({ apiKey: '...' });
+
+// Async iterator — processes one page at a time
+for await (const batch of paginate((p) => tn.events.list(p))) {
+  console.log(`Got ${batch.length} events`);
+}
+
+// Fetch all at once
+const allEvents = await fetchAllPages((p) => tn.events.list(p));
+```
+
+## Error Handling
+
+All API errors throw `TicketnationError` with structured details:
+
+```typescript
+import { Ticketnation, TicketnationError } from '@ticketnation/sdk';
+
+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_a1b2c3d4' (for support)
+  }
+}
+```
+
+### Error Codes
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `VALIDATION_ERROR` | 400 | Invalid input — check `error.details` for field-level errors |
+| `UNAUTHORIZED` | 401 | Missing or invalid API key |
+| `FORBIDDEN` | 403 | API key lacks required scope |
+| `NOT_FOUND` | 404 | Resource not found or not owned by your organization |
+| `RATE_LIMITED` | 429 | Too many requests — SDK auto-retries on 5xx, not 429 |
+| `INTERNAL_ERROR` | 500 | Server error — SDK auto-retries up to `retries` times |
+| `TIMEOUT` | 0 | Request exceeded `timeout` ms |
+| `NETWORK_ERROR` | 0 | DNS, connection, or other network failure |
+
+## Scopes
+
+Your API key needs the right scopes for each operation:
+
+| Scope | Operations |
+|-------|------------|
+| `events:read` | List/get events, search venues |
+| `events:write` | Create/update/publish/delete events |
+| `tickets:read` | List/get tickets |
+| `tickets:write` | Create/update/publish/delete/sold-out tickets |
+| `orders:read` | List/get orders |
+| `webhooks:manage` | Create/update/delete webhooks |
+
+## Authentication
+
+Get your API key from **Organizer Dashboard > Settings > API Keys**.
+
+The SDK sends the key via the `api-key` HTTP header. Keys are scoped to a single organization.
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+- TypeScript 5.0+ (optional but recommended)
+
+## Full Documentation
+
+For complete REST API reference with `curl` examples, webhook setup, and architecture overview, visit the [Ticketnation Developer Docs](https://docs.ticketnation.ph/developers/overview).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,372 @@
+interface ClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeout: number;
+    retries: number;
+    debug: boolean;
+}
+declare class HttpClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    request<T>(method: string, path: string, opts?: {
+        body?: unknown;
+        params?: Record<string, unknown>;
+    }): Promise<T>;
+    private doRequest;
+    private buildUrl;
+    private sleep;
+}
+
+interface TicketNationConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    retries?: number;
+    debug?: boolean;
+}
+interface PaginationMeta {
+    page: number;
+    take: number;
+    total: number;
+    totalPages: number;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    meta: PaginationMeta;
+}
+interface DataResponse<T> {
+    data: T;
+}
+interface PaginationParams {
+    page?: number;
+    take?: number;
+}
+type EventStatus = 'DRAFT' | 'PUBLISHED' | 'ARCHIVED';
+type EventType = 'PAID' | 'FREE';
+type EventJourneyType = 'STANDARD' | 'RSVP' | 'PRESELLING';
+type EventLocationType = 'VENUE' | 'ONLINE';
+type EventVisibility = 'PUBLIC' | 'PRIVATE';
+interface Event {
+    id: string;
+    name: string;
+    description: string | null;
+    dateTime: string;
+    endDateTime: string | null;
+    status: EventStatus;
+    type: EventType;
+    journeyType: EventJourneyType;
+    currency: string;
+    locationType: EventLocationType;
+    visibility: EventVisibility;
+    eventCapacity: number | null;
+    timezone: string;
+    absorbFees: boolean;
+    callbackUrl: string | null;
+    slug: string;
+    eventTickets: Ticket[];
+    venue: VenueRef | null;
+    slugV2: {
+        slug: string;
+    } | null;
+}
+interface CreateEventParams {
+    name: string;
+    description?: string;
+    dateTime: string;
+    endDateTime?: string;
+    start?: string;
+    end?: string;
+    type?: EventType;
+    journeyType?: EventJourneyType;
+    currency?: string;
+    locationType?: EventLocationType;
+    onlineMeetingUrl?: string;
+    onlineMeetingProvider?: string;
+    eventCapacity?: number;
+    visibility?: EventVisibility;
+    eventTicketLimit?: number;
+    timezone?: string;
+    absorbFees?: boolean;
+    callbackUrl?: string;
+    venueId?: string;
+    tickets?: CreateTicketParams[];
+}
+interface UpdateEventParams {
+    name?: string;
+    description?: string;
+    dateTime?: string;
+    endDateTime?: string;
+    start?: string;
+    end?: string;
+    type?: EventType;
+    journeyType?: EventJourneyType;
+    currency?: string;
+    locationType?: EventLocationType;
+    onlineMeetingUrl?: string;
+    onlineMeetingProvider?: string;
+    eventCapacity?: number;
+    visibility?: EventVisibility;
+    eventTicketLimit?: number;
+    timezone?: string;
+    absorbFees?: boolean;
+    callbackUrl?: string;
+    venueId?: string;
+}
+interface ListEventsParams extends PaginationParams {
+    status?: EventStatus;
+    search?: string;
+}
+type TicketSeatType = 'GENERAL_ADMISSION' | 'RESERVED_SEAT' | 'VIP';
+type TicketStatus = 'ACTIVE' | 'INACTIVE';
+interface Ticket {
+    id: string;
+    name: string;
+    description: string | null;
+    price: number;
+    originalPrice: number;
+    quantity: number;
+    remainingQuantity: number;
+    section: string;
+    row: string;
+    sectionGroup: string | null;
+    type: TicketSeatType;
+    status: TicketStatus;
+    published: boolean;
+    minimumPurchaseQuantity: number | null;
+    maximumPurchaseQuantity: number | null;
+    requiresApproval: boolean;
+    deliveryMethod: string;
+    eventId?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface CreateTicketParams {
+    name: string;
+    description?: string;
+    price: number;
+    quantity: number;
+    section?: string;
+    row?: string;
+    sectionGroup?: string;
+    type?: TicketSeatType;
+    minimumPurchaseQuantity?: number;
+    maximumPurchaseQuantity?: number;
+    requiresApproval?: boolean;
+    published?: boolean;
+}
+interface UpdateTicketParams {
+    name?: string;
+    description?: string;
+    price?: number;
+    quantity?: number;
+    section?: string;
+    row?: string;
+    sectionGroup?: string;
+    type?: TicketSeatType;
+    minimumPurchaseQuantity?: number;
+    maximumPurchaseQuantity?: number;
+    requiresApproval?: boolean;
+    published?: boolean;
+}
+type OrderStatus = 'PENDING' | 'COMPLETED' | 'CANCELLED' | 'REFUNDED';
+interface OrderItemTicket {
+    id: string;
+    name: string;
+    section: string;
+}
+interface OrderItem {
+    id: string;
+    quantity: number;
+    price: number;
+    eventTicket: OrderItemTicket | null;
+}
+interface OrderPayment {
+    id: string;
+    status: string;
+    method: string | null;
+    paidAt: string | null;
+}
+interface Order {
+    id: string;
+    orderNumber: string;
+    status: OrderStatus;
+    totalAmount: number;
+    currency: string;
+    quantity: number;
+    buyerName: string | null;
+    buyerEmail: string | null;
+    createdAt: string;
+    updatedAt: string;
+    eventId: string;
+    orderItems: OrderItem[];
+    payment?: OrderPayment | null;
+}
+interface ListOrdersParams extends PaginationParams {
+    status?: OrderStatus;
+}
+interface VenueRef {
+    id: string;
+    name: string;
+    address1: string | null;
+}
+interface Venue {
+    id: string;
+    name: string;
+    address1: string | null;
+    address2: string | null;
+    city: string | null;
+    state: string | null;
+    country: string | null;
+    zipCode: string | null;
+    latitude: number | null;
+    longitude: number | null;
+}
+interface SearchVenuesParams extends PaginationParams {
+    query: string;
+}
+type WebhookEventType = 'order.completed' | 'order.refunded' | 'event.sold_out' | 'ticket.inventory_low';
+interface Webhook {
+    id: string;
+    url: string;
+    events: WebhookEventType[];
+    isActive: boolean;
+    failureCount: number;
+    lastTriggeredAt: string | null;
+    lastFailedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface WebhookWithSecret extends Webhook {
+    secret: string;
+}
+interface CreateWebhookParams {
+    url: string;
+    events: WebhookEventType[];
+}
+interface UpdateWebhookParams {
+    url?: string;
+    events?: WebhookEventType[];
+    isActive?: boolean;
+}
+interface ApiKeyInfo {
+    id: string;
+    name: string;
+    description: string | null;
+    scopes: string[];
+    callbackUrl: string | null;
+    createdAt: string;
+    expiresAt: string | null;
+    lastUsedAt: string | null;
+}
+interface OrganizationInfo {
+    id: string;
+    name: string;
+    slug: string | null;
+}
+interface AccountInfo {
+    apiKey: ApiKeyInfo;
+    organization: OrganizationInfo;
+}
+interface DeletedResponse {
+    deleted: boolean;
+    id: string;
+}
+interface ApiErrorBody {
+    code: string;
+    message: string;
+    details?: Array<{
+        field: string;
+        message: string;
+    }>;
+}
+interface ApiErrorResponse {
+    error: ApiErrorBody;
+    requestId: string;
+}
+
+declare class EventsResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    create(params: CreateEventParams): Promise<Event>;
+    list(params?: ListEventsParams): Promise<PaginatedResponse<Event>>;
+    get(idOrSlug: string): Promise<Event>;
+    update(eventId: string, params: UpdateEventParams): Promise<Event>;
+    publish(eventId: string): Promise<Event>;
+    unpublish(eventId: string): Promise<Event>;
+    archive(eventId: string): Promise<Event>;
+    delete(eventId: string): Promise<DeletedResponse>;
+}
+
+declare class TicketsResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    create(eventId: string, params: CreateTicketParams): Promise<Ticket>;
+    list(eventId: string): Promise<Ticket[]>;
+    get(eventId: string, ticketId: string): Promise<Ticket>;
+    update(eventId: string, ticketId: string, params: UpdateTicketParams): Promise<Ticket>;
+    publish(eventId: string, ticketId: string): Promise<Ticket>;
+    markSoldOut(eventId: string, ticketId: string): Promise<Ticket>;
+    delete(eventId: string, ticketId: string): Promise<DeletedResponse>;
+}
+
+declare class OrdersResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(eventId: string, params?: ListOrdersParams): Promise<PaginatedResponse<Order>>;
+    get(orderId: string): Promise<Order>;
+}
+
+declare class VenuesResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    search(params: SearchVenuesParams): Promise<PaginatedResponse<Venue>>;
+}
+
+declare class TicketNationError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly requestId: string | null;
+    readonly details: Array<{
+        field: string;
+        message: string;
+    }> | undefined;
+    constructor(message: string, opts: {
+        code: string;
+        status: number;
+        requestId?: string;
+        details?: Array<{
+            field: string;
+            message: string;
+        }>;
+    });
+    static fromResponse(status: number, body: {
+        error: ApiErrorBody;
+        requestId?: string;
+    }): TicketNationError;
+    toJSON(): {
+        name: string;
+        code: string;
+        status: number;
+        message: string;
+        requestId: string | null;
+        details: {
+            field: string;
+            message: string;
+        }[] | undefined;
+    };
+}
+
+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[]>;
+
+declare class TicketNation {
+    readonly events: EventsResource;
+    readonly tickets: TicketsResource;
+    readonly orders: OrdersResource;
+    readonly venues: VenuesResource;
+    private readonly client;
+    constructor(config: TicketNationConfig);
+    me(): Promise<AccountInfo>;
+}
+
+export { type AccountInfo, type ApiErrorBody, type ApiErrorResponse, type ApiKeyInfo, type CreateEventParams, 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 OrganizationInfo, type PaginatedResponse, type PaginationMeta, type PaginationParams, type SearchVenuesParams, type Ticket, TicketNation, type TicketNationConfig, TicketNationError, type TicketSeatType, type TicketStatus, type UpdateEventParams, type UpdateTicketParams, type UpdateWebhookParams, type Venue, type VenueRef, type Webhook, type WebhookEventType, type WebhookWithSecret, fetchAllPages, paginate };