@cohostvip/cohost-node 0.1.17 → 0.2.4

package/README.md

@@ -1,15 +1,21 @@
 # @cohostvip/cohost-node
 
-> Official Node.js SDK for interacting with the Cohost API
+> Official Node.js SDK for the Cohost API
+
+[![npm version](https://img.shields.io/npm/v/@cohostvip/cohost-node.svg)](https://www.npmjs.com/package/@cohostvip/cohost-node)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
 
 ---
 
 ## ✨ Features
 
-- TypeScript-first API client
-- Supports Node.js `>=18`
-- Automatically unwraps `{ status: 'ok', data: ... }` responses
-- Supports ESM and CommonJS
+- 🎯 **TypeScript-first** - Full type safety and IntelliSense support
+- 🔐 **Token authentication** - Secure API access with bearer tokens
+- 📦 **Dual module support** - Works with ESM and CommonJS
+- 🚀 **Promise-based** - Modern async/await API
+- 🔄 **Auto-unwrapping** - Automatically extracts data from API responses
+- 🛡️ **Error handling** - Custom error types with status codes
+- 📊 **Pagination** - Built-in support for paginated endpoints
 
 ---
 
@@ -19,56 +25,311 @@
 npm install @cohostvip/cohost-node
 # or
 pnpm add @cohostvip/cohost-node
+# or
+yarn add @cohostvip/cohost-node
 ```
 
 ---
 
-## 🧱 Usage
+## 🚀 Quick Start
 
-```ts
-import { CohostClient } from '@cohostvip/cohost-node';
+```typescript
+import { createCohostClient } from '@cohostvip/cohost-node';
 
-const client = new CohostClient({
+const client = createCohostClient({
   token: 'your-api-token',
+  settings: { debug: false } // optional
+});
+
+// Fetch events
+const events = await client.events.list();
+const event = await client.events.fetch('evt_123');
+
+// Create an event
+const newEvent = await client.events.create({
+  name: 'Summer Concert',
+  startDate: '2025-07-15T19:00:00Z',
+  venue: { name: 'City Arena' }
 });
 
-const event = await client.events.fetch('event-id');
-const tickets = await client.events.tickets('event-id');
-const order = await client.orders.fetch('order-id', 'user-id');
+// Create tickets
+await client.events.createTickets(newEvent.id, [
+  { name: 'General Admission', price: 50, quantity: 100 },
+  { name: 'VIP', price: 150, quantity: 20 }
+]);
 ```
 
 ---
 
-## 🧩 API Coverage
+## 📚 API Reference
+
+### Events API
+
+```typescript
+// List all events
+const events = await client.events.list();
+
+// Get single event
+const event = await client.events.fetch('evt_123');
+
+// Search events (with pagination)
+const results = await client.events.search({
+  page: 1,
+  size: 20
+});
+
+// Create event
+const newEvent = await client.events.create({
+  name: 'My Event',
+  startDate: '2025-12-01T18:00:00Z'
+});
+
+// Update event
+await client.events.update('evt_123', {
+  name: 'Updated Event Name'
+});
+
+// Get event tickets
+const tickets = await client.events.tickets('evt_123');
+
+// Create tickets
+const result = await client.events.createTickets('evt_123', {
+  name: 'General Admission',
+  price: 50,
+  currency: 'USD',
+  quantity: 100
+});
+
+// Update ticket
+await client.events.updateTicket('evt_123', 'tkt_456', {
+  price: 55
+});
+
+// Delete ticket
+await client.events.deleteTicket('evt_123', 'tkt_456');
+
+// Get attendees (requires authentication)
+const attendees = await client.events.attendees('evt_123', {
+  page: 1,
+  size: 50
+});
+```
+
+### Orders API
 
-This SDK currently supports:
+```typescript
+// List orders with filters
+const orders = await client.orders.list({
+  status: 'completed',
+  startDate: '2025-01-01',
+  endDate: '2025-12-31'
+});
+
+// Get order details
+const order = await client.orders.fetch('ord_123', 'user_456');
+
+// Get order attendees
+const attendees = await client.orders.attendees('ord_123', 'user_456');
+
+// Send order confirmation email
+await client.orders.sendConfirmation('ord_123');
+```
+
+### Cart/Checkout API
+
+```typescript
+// Start cart session
+const session = await client.cart.start({
+  contextId: 'evt_123'
+});
+
+// Get cart session
+const cart = await client.cart.get(session.id);
+
+// Update session (customer info)
+await client.cart.update(session.id, {
+  customer: {
+    email: 'customer@example.com',
+    name: 'John Doe'
+  }
+});
+
+// Add/update cart items
+await client.cart.updateItem(session.id, {
+  offeringId: 'tkt_456',
+  quantity: 2
+});
+
+// Apply coupon
+await client.cart.applyCoupon(session.id, 'SUMMER20');
+
+// Remove coupon
+await client.cart.deleteCoupon(session.id, 'cpn_789');
+
+// Pre-validate payment
+const validation = await client.cart.preValidate(session.id);
+
+// Process payment
+await client.cart.processPayment(session.id, {
+  paymentMethod: 'card',
+  // payment details...
+});
 
-- `events.fetch(id)` – Fetch a single event
-- `events.tickets(id)` – Fetch tickets for an event
-- `orders.fetch(id, uid)` – Fetch an order
+// Place order
+const result = await client.cart.placeOrder(session.id);
 
-More endpoints coming soon.
+// Cancel session
+await client.cart.cancel(session.id);
+```
+
+### Coupons API
+
+```typescript
+// List all coupons
+const coupons = await client.coupons.list();
+
+// List coupons for specific event
+const eventCoupons = await client.coupons.list({
+  eventId: 'evt_123'
+});
+
+// Create coupon
+const coupon = await client.coupons.create({
+  code: 'SUMMER2025',
+  discountType: 'percentage',
+  discountValue: 20,
+  maxUses: 100,
+  expiresAt: '2025-08-31T23:59:59Z'
+});
+
+// Update coupon
+await client.coupons.update('cpn_789', {
+  discountValue: 25,
+  maxUses: 150
+});
+
+// Delete coupon
+await client.coupons.delete('cpn_789');
+```
 
 ---
 
-## 🛠 Environment Requirements
+## 🔧 Configuration
+
+### Client Options
+
+```typescript
+import { createCohostClient } from '@cohostvip/cohost-node';
+
+const client = createCohostClient({
+  token: 'your-api-token',
+  settings: {
+    debug: true,                          // Enable debug logging
+    apiUrl: 'https://api.cohost.vip/v1'  // Custom API URL (optional)
+  }
+});
+```
 
-- Node.js 18 or later
-- An active Cohost API token
+### Runtime Overrides
+
+Override token, baseUrl, or headers for specific requests:
+
+```typescript
+const adminClient = client.requestWithOverrides({
+  token: 'admin-token',
+  headers: {
+    'X-Custom-Header': 'value'
+  }
+});
+
+const event = await adminClient.events.fetch('evt_123');
+```
 
 ---
 
-## 🗒️ Changelog
-See the latest changes [here](./CHANGELOG.md).
+## 🛡️ Error Handling
+
+```typescript
+import { CohostError } from '@cohostvip/cohost-node';
+
+try {
+  const event = await client.events.fetch('invalid-id');
+} catch (error) {
+  if (error instanceof CohostError) {
+    console.error('Error code:', error.errorCode);
+    console.error('Status code:', error.statusCode);
+    console.error('Message:', error.message);
+  }
+}
+```
+
+---
+
+## 📊 TypeScript Support
+
+Full TypeScript definitions included:
+
+```typescript
+import {
+  createCohostClient,
+  CohostClient,
+  EventProfile,
+  Ticket,
+  Coupon,
+  PaginatedResponse
+} from '@cohostvip/cohost-node';
+
+const client: CohostClient = createCohostClient({
+  token: 'your-token'
+});
+
+const events: EventProfile[] = await client.events.list();
+const tickets: Ticket[] = await client.events.tickets('evt_123');
+```
+
+---
+
+## 🛠 Environment Requirements
+
+- **Node.js**: 18 or later
+- **API Token**: Active Cohost API authentication token
 
 ---
 
 ## 🚧 Roadmap
-Planned features and improvements are tracked [here](./ROADMAP.md).
+
+See our [ROADMAP.md](./ROADMAP.md) for planned features and improvements.
+
+**Coming Soon:**
+- Workflows API integration
+- Webhook validation helpers
+- Enhanced retry logic and rate limiting
 
 ---
 
+## 📖 Documentation
+
+- [API Reference](https://docs.cohost.vip)
+- [Changelog](./CHANGELOG.md)
+- [Contributing Guidelines](./CONTRIBUTING.md)
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
+
+---
 
 ## 📄 License
 
 ISC © [Cohost](https://cohost.vip)
+
+---
+
+## 🔗 Links
+
+- [npm Package](https://www.npmjs.com/package/@cohostvip/cohost-node)
+- [GitHub Repository](https://github.com/cohostvip/cohost-node)
+- [API Documentation](https://docs.cohost.vip)
+- [Cohost Website](https://cohost.vip)

package/dist/index.d.mts

@@ -1163,7 +1163,7 @@ interface EventProfile extends EventBase {
  *
  * @export
  */
-interface Coupon extends VersionedDataRecord {
+interface Coupon$1 extends VersionedDataRecord {
     /**
      * ID of the company that issued this coupon.
      * @example "company_123abc"
@@ -1410,7 +1410,7 @@ interface ResolvedCartContextOffering {
     path: string;
     offering: Offering;
 }
-type CouponSummary = Pick<Coupon, "id" | "code" | "amountOff" | "percentOff" | "offeringIds">;
+type CouponSummary = Pick<Coupon$1, "id" | "code" | "amountOff" | "percentOff" | "offeringIds">;
 type OrderStatus = "placed" | "completed" | "attending" | "cancelled" | "refunded" | "started" | "pending" | "abandoned";
 interface OrderCosts {
     subtotal: CurrencyAmount;
@@ -1806,6 +1806,109 @@ declare class EventsAPI extends CohostEndpoint {
      */
     attendees(id: string, filters?: PaginatedRequest<any>): Promise<PaginatedResponse<Attendee>>;
     search(filters?: PaginatedRequest<any>): Promise<PaginatedResponse<EventProfile>>;
+    /**
+     * Create a new event.
+     *
+     * @param event - The event data to create (without id)
+     * @param context - Optional context information for event creation
+     * @returns A Promise resolving to an object with the created event ID
+     * @throws Will throw an error if the request fails or authentication is missing
+     *
+     * @example
+     * ```ts
+     * const result = await client.events.create({
+     *   name: 'Summer Concert',
+     *   startDate: '2025-07-15T19:00:00Z',
+     *   venue: { name: 'City Arena' }
+     * });
+     * console.log(result.id); // 'evt_abc123'
+     * ```
+     */
+    create(event: Omit<Partial<EventProfile>, 'id'>, context?: any): Promise<{
+        id: string;
+    }>;
+    /**
+     * Update an existing event.
+     *
+     * @param id - The unique identifier of the event to update
+     * @param event - Partial event data to update
+     * @param context - Optional context information for event update
+     * @returns A Promise resolving to an object with the updated event ID
+     * @throws Will throw an error if the request fails or event is not found
+     *
+     * @example
+     * ```ts
+     * const result = await client.events.update('evt_abc123', {
+     *   name: 'Summer Concert - Updated',
+     *   capacity: 5000
+     * });
+     * ```
+     */
+    update(id: string, event: Partial<EventProfile>, context?: any): Promise<{
+        id: string;
+    }>;
+    /**
+     * Create one or more tickets for an event.
+     *
+     * @param eventId - The unique identifier of the event
+     * @param tickets - Single ticket or array of tickets to create
+     * @param context - Optional context information for ticket creation
+     * @returns A Promise resolving to an object mapping reference IDs to created ticket IDs
+     * @throws Will throw an error if the request fails or validation fails
+     *
+     * @example
+     * ```ts
+     * // Create single ticket
+     * const result = await client.events.createTickets('evt_abc123', {
+     *   name: 'General Admission',
+     *   price: 50,
+     *   currency: 'USD',
+     *   quantity: 100
+     * });
+     *
+     * // Create multiple tickets
+     * const result = await client.events.createTickets('evt_abc123', [
+     *   { name: 'VIP', price: 150, quantity: 20 },
+     *   { name: 'Early Bird', price: 40, quantity: 50 }
+     * ]);
+     * ```
+     */
+    createTickets(eventId: string, tickets: Partial<Ticket> | Partial<Ticket>[], context?: any): Promise<{
+        ids: Record<string, string>;
+    }>;
+    /**
+     * Update an existing ticket.
+     *
+     * @param eventId - The unique identifier of the event
+     * @param ticketId - The unique identifier of the ticket to update
+     * @param ticket - Partial ticket data to update
+     * @param context - Optional context information for ticket update
+     * @returns A Promise resolving to the updated ticket
+     * @throws Will throw an error if the request fails or ticket is not found
+     *
+     * @example
+     * ```ts
+     * const result = await client.events.updateTicket('evt_abc123', 'tkt_xyz789', {
+     *   price: 55,
+     *   quantity: 120
+     * });
+     * ```
+     */
+    updateTicket(eventId: string, ticketId: string, ticket: Partial<Ticket>, context?: any): Promise<Ticket>;
+    /**
+     * Delete a ticket from an event.
+     *
+     * @param eventId - The unique identifier of the event
+     * @param ticketId - The unique identifier of the ticket to delete
+     * @returns A Promise resolving when the ticket is deleted (no content)
+     * @throws Will throw an error if the request fails or ticket is not found
+     *
+     * @example
+     * ```ts
+     * await client.events.deleteTicket('evt_abc123', 'tkt_xyz789');
+     * ```
+     */
+    deleteTicket(eventId: string, ticketId: string): Promise<void>;
 }
 
 /**
@@ -1851,6 +1954,22 @@ declare class OrdersAPI extends CohostEndpoint {
         page?: number;
         pageSize?: number;
     }): Promise<any>;
+    /**
+     * Send order confirmation email to customer.
+     *
+     * @param id - The unique identifier of the order
+     * @returns A Promise resolving to the confirmation response
+     * @throws Will throw an error if the request fails or order is not found
+     *
+     * @example
+     * ```ts
+     * const result = await client.orders.sendConfirmation('ord_abc123');
+     * console.log(result.response); // Confirmation sent status
+     * ```
+     */
+    sendConfirmation(id: string): Promise<{
+        response: any;
+    }>;
 }
 
 /**
@@ -1987,12 +2106,110 @@ declare class SessionsAPI extends CohostEndpoint {
     deleteCoupon(id: string, couponId: string): Promise<CartSession>;
 }
 
+/**
+ * Coupon interface for the Cohost API
+ */
+interface Coupon {
+    id: string;
+    code: string;
+    discountType: 'percentage' | 'fixed';
+    discountValue: number;
+    maxUses?: number;
+    usedCount?: number;
+    expiresAt?: string;
+    companyId: string;
+    eventId?: string;
+    status?: 'active' | 'inactive' | 'expired';
+    created?: string;
+    updated?: string;
+}
+/**
+ * Provides methods to interact with the Cohost Coupons API.
+ *
+ * Usage:
+ * ```ts
+ * const client = new CohostClient({ token: 'your-token' });
+ * const coupons = await client.coupons.list();
+ * const coupon = await client.coupons.create({ code: 'SUMMER2025', discountType: 'percentage', discountValue: 20 });
+ * ```
+ */
+declare class CouponsAPI extends CohostEndpoint {
+    /**
+     * List all coupons for the authenticated company.
+     *
+     * @param filters - Optional filters to apply when retrieving coupons
+     * @returns A Promise resolving to an array of coupon objects
+     * @throws Will throw an error if the request fails
+     *
+     * @example
+     * ```ts
+     * // List all coupons
+     * const allCoupons = await client.coupons.list();
+     *
+     * // List coupons for specific event
+     * const eventCoupons = await client.coupons.list({ eventId: 'evt_abc123' });
+     * ```
+     */
+    list(filters?: {
+        eventId?: string;
+    }): Promise<Coupon[]>;
+    /**
+     * Create a new coupon.
+     *
+     * @param coupon - The coupon data to create
+     * @returns A Promise resolving to the created coupon object
+     * @throws Will throw an error if the request fails or validation fails
+     *
+     * @example
+     * ```ts
+     * const coupon = await client.coupons.create({
+     *   code: 'SUMMER2025',
+     *   discountType: 'percentage',
+     *   discountValue: 20,
+     *   maxUses: 100,
+     *   expiresAt: '2025-08-31T23:59:59Z'
+     * });
+     * ```
+     */
+    create(coupon: Omit<Partial<Coupon>, 'id' | 'companyId' | 'created' | 'updated'>): Promise<Coupon>;
+    /**
+     * Update an existing coupon.
+     *
+     * @param id - The unique identifier of the coupon to update
+     * @param coupon - Partial coupon data to update
+     * @returns A Promise resolving to the updated coupon object
+     * @throws Will throw an error if the request fails or coupon is not found
+     *
+     * @example
+     * ```ts
+     * const updated = await client.coupons.update('cpn_xyz789', {
+     *   discountValue: 25,
+     *   maxUses: 150
+     * });
+     * ```
+     */
+    update(id: string, coupon: Omit<Partial<Coupon>, 'id' | 'companyId' | 'created' | 'updated'>): Promise<Coupon>;
+    /**
+     * Delete a coupon.
+     *
+     * @param id - The unique identifier of the coupon to delete
+     * @returns A Promise resolving when the coupon is deleted
+     * @throws Will throw an error if the request fails or coupon is not found
+     *
+     * @example
+     * ```ts
+     * await client.coupons.delete('cpn_xyz789');
+     * ```
+     */
+    delete(id: string): Promise<void>;
+}
+
 /**
  * Configuration options for instantiating a CohostClient.
  */
 interface CohostClientOptions {
-    /** API token used for authenticated requests. */
-    token: string;
+    /** API token used for authenticated requests. Defaults to COHOST_API_TOKEN or NEXT_PUBLIC_COHOST_API_TOKEN env var. */
+    token?: string;
     /** Optional client settings such as debug mode or custom API URL. */
     settings?: CohostClientSettings;
 }
@@ -2003,8 +2220,9 @@ declare class CohostClient {
     readonly events: EventsAPI;
     readonly orders: OrdersAPI;
     readonly cart: SessionsAPI;
+    readonly coupons: CouponsAPI;
     private readonly baseOptions;
-    constructor(options: CohostClientOptions, customRequestFn?: RequestFn);
+    constructor(options?: CohostClientOptions, customRequestFn?: RequestFn);
     /**
      * Returns a new CohostClient instance with overridden request behavior
      */