@cohostvip/cohost-node 0.0.3 → 0.0.4

package/dist/index.d.mts

@@ -71,6 +71,405 @@ declare enum CostBucket {
     TAX = "tax"
 }
 
+type CalculatedCostComponent = {
+    base: string;
+    bucket: CostBucket;
+    /**
+     * A string representing a currency amount in the format `"USD,1000"` where:
+     * - `"USD"` is the 3-letter ISO currency code.
+     * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+     *
+     * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+     */
+    cost: string;
+    discount: null;
+    id: string;
+    name: string;
+    payer: CalculatedCostComponent.payer;
+    recipient: string;
+    value: number;
+    version: string;
+};
+declare namespace CalculatedCostComponent {
+    enum payer {
+        ATTENDEE = "attendee",
+        ORGANIZER = "organizer"
+    }
+}
+
+type CouponSummary = {
+    /**
+     * Fixed amount to deduct from the order total.
+     * This is a currency-less value that matches the event or order currency.
+     * Example: `10.00` = $10.00 off.
+     */
+    amountOff: number;
+    /**
+     * The code used to redeem this coupon during checkout.
+     * For public or coded discounts.
+     */
+    code: string;
+    /**
+     * Unique identifier for the record.
+     */
+    id: string;
+    /**
+     * List of offering IDs (e.g., ticket classes) this coupon applies to.
+     * If empty, the coupon applies to all eligible offerings in its context.
+     */
+    offeringIds: Array<string>;
+    /**
+     * Percentage to deduct from the item or order total.
+     * Range is 0–100. Use 0 for no percentage-based discount.
+     */
+    percentOff: number;
+};
+
+type Partial_Customer_ = {
+    age?: number;
+    birthdate?: string;
+    displayName?: string;
+    email?: string;
+    first?: string;
+    gender?: string;
+    last?: string;
+    name?: string;
+    phone?: string;
+    photoURL?: string;
+    uid?: string;
+};
+
+type Partial_OrderContext_ = {
+    /**
+     * The unique cart session ID assigned at the time the cart was created.
+     * Helps track cart attribution across systems.
+     */
+    cartSessionId?: string;
+    /**
+     * IP addresses associated with the user request.
+     * Typically includes forwarded IPs and direct client IP.
+     */
+    ipAddresses?: Array<string>;
+    /**
+     * (Optional) Origin domain name if embedded or white-labeled.
+     * Can help identify partner portals or iframe referrers.
+     */
+    originDomain?: string;
+    /**
+     * The referring URL from which the cart or checkout was initiated.
+     * May be a partner site, marketing page, or event listing.
+     */
+    referrer?: string;
+    /**
+     * (Optional) Campaign ID, UTM source, or tracking label.
+     * Useful for affiliate and analytics systems.
+     */
+    trackingId?: string;
+    /**
+     * Authenticated user ID, or null for anonymous guests.
+     */
+    uid?: string;
+    /**
+     * Raw User-Agent header from the client request.
+     */
+    userAgent?: string;
+};
+
+declare enum OfferingType {
+    ADMISSION = "admission",
+    DONATION = "donation",
+    DRINK = "drink",
+    MEMBERSHIP = "membership",
+    MERCH = "merch",
+    OTHER = "other",
+    PACKAGE = "package",
+    SERVICE = "service",
+    SKIP = "skip",
+    TC_TICKET = "tc-ticket",
+    TICKET = "ticket",
+    VOUCHER = "voucher"
+}
+
+/**
+ * Cost breakdown for a specific item in the order.
+ * Extends the standard `OfferingCosts` with totals calculated for quantity and discounts.
+ */
+type OrderItemCosts = {
+    /**
+     * A string representing a currency amount in the format `"USD,1000"` where:
+     * - `"USD"` is the 3-letter ISO currency code.
+     * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+     *
+     * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+     */
+    cost: string;
+    /**
+     * A string representing a currency amount in the format `"USD,1000"` where:
+     * - `"USD"` is the 3-letter ISO currency code.
+     * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+     *
+     * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+     */
+    delivery: string;
+    /**
+     * Total discount amount applied to this item.
+     */
+    discount: string;
+    /**
+     * A string representing a currency amount in the format `"USD,1000"` where:
+     * - `"USD"` is the 3-letter ISO currency code.
+     * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+     *
+     * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+     */
+    fee: string;
+    /**
+     * cost + fee - discount , not including tax
+     */
+    gross: string;
+    /**
+     * Total price before discounts.
+     * Equal to subtotal + fee, before subtracting discount.
+     */
+    preDiscount: string;
+    /**
+     * Total cost of tickets before taxes, fees, and discounts.
+     */
+    subtotal: string;
+    /**
+     * A string representing a currency amount in the format `"USD,1000"` where:
+     * - `"USD"` is the 3-letter ISO currency code.
+     * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+     *
+     * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+     */
+    tax: string;
+    /**
+     * total cost including tax
+     */
+    total: string;
+};
+
+/**
+ * Represents the costs associated with an offering.
+ */
+type OfferingCosts = {
+    /**
+     * A string representing a currency amount in the format `"USD,1000"` where:
+     * - `"USD"` is the 3-letter ISO currency code.
+     * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+     *
+     * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+     */
+    cost: string;
+    /**
+     * A string representing a currency amount in the format `"USD,1000"` where:
+     * - `"USD"` is the 3-letter ISO currency code.
+     * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+     *
+     * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+     */
+    delivery: string;
+    /**
+     * A string representing a currency amount in the format `"USD,1000"` where:
+     * - `"USD"` is the 3-letter ISO currency code.
+     * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+     *
+     * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+     */
+    fee: string;
+    /**
+     * cost + fee - discount , not including tax
+     */
+    gross: string;
+    /**
+     * A string representing a currency amount in the format `"USD,1000"` where:
+     * - `"USD"` is the 3-letter ISO currency code.
+     * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+     *
+     * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+     */
+    tax: string;
+    /**
+     * total cost including tax
+     */
+    total: string;
+};
+
+type OrderItemOffering = {
+    costs: OfferingCosts;
+    /**
+     * doc assicated with this offering in the DB.
+     */
+    docPath: string;
+    /**
+     * Offering name, can be ticket name, vaucher name, etc...
+     */
+    name: string;
+    type: OfferingType;
+};
+
+type Partial_OrderItem_ = {
+    /**
+     * Breakdown of cost components (e.g., base, service fee, delivery).
+     */
+    costComponents?: Array<CalculatedCostComponent>;
+    costs?: OrderItemCosts;
+    /**
+     * Unique ID for this order item.
+     */
+    id?: string;
+    /**
+     * If this item is included as part of a package, this is the ID of the parent item.
+     * Otherwise, null.
+     */
+    includedWithItemId?: string;
+    /**
+     * Any relevant metadata associated with this item.
+     * This can include custom fields or additional information.
+     */
+    meta?: any;
+    offering?: OrderItemOffering;
+    /**
+     * ID of the offering purchased.
+     */
+    offeringId?: string;
+    offeringType?: OfferingType;
+    /**
+     * Quantity purchased of this item.
+     */
+    quantity?: number;
+};
+
+/**
+ * Represents a temporary or persisted cart before order placement.
+ * Focuses on user intent and checkout prep, not post-purchase records.
+ */
+type CartSession = {
+    /**
+     * ISO 8601 timestamp indicating when the record was last updated, if applicable.
+     */
+    changed?: string;
+    context: Partial_OrderContext_;
+    /**
+     * Namespaced identifier indicating what the order is associated with.
+     * Format: "{type}_{id}", where type is "evt", "ven", or "org".
+     */
+    contextId: string;
+    /**
+     * Estimated totals based on current cart state.
+     * These values are subject to recalculation before checkout.
+     */
+    costs?: {
+        /**
+         * A string representing a currency amount in the format `"USD,1000"` where:
+         * - `"USD"` is the 3-letter ISO currency code.
+         * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+         *
+         * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+         */
+        delivery: string;
+        /**
+         * A string representing a currency amount in the format `"USD,1000"` where:
+         * - `"USD"` is the 3-letter ISO currency code.
+         * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+         *
+         * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+         */
+        discount: string;
+        /**
+         * A string representing a currency amount in the format `"USD,1000"` where:
+         * - `"USD"` is the 3-letter ISO currency code.
+         * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+         *
+         * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+         */
+        fee: string;
+        /**
+         * A string representing a currency amount in the format `"USD,1000"` where:
+         * - `"USD"` is the 3-letter ISO currency code.
+         * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+         *
+         * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+         */
+        subtotal: string;
+        /**
+         * A string representing a currency amount in the format `"USD,1000"` where:
+         * - `"USD"` is the 3-letter ISO currency code.
+         * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+         *
+         * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+         */
+        tax: string;
+        /**
+         * A string representing a currency amount in the format `"USD,1000"` where:
+         * - `"USD"` is the 3-letter ISO currency code.
+         * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
+         *
+         * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
+         */
+        total: string;
+    };
+    /**
+     * List of applied coupons used in the order.
+     * Supports multiple entries based on organizer preferences.
+     */
+    coupons?: Array<CouponSummary>;
+    /**
+     * ISO 8601 timestamp indicating when the record was created.
+     */
+    created: string;
+    /**
+     * The currency code used for this order in ISO 4217 format.
+     */
+    currency: string;
+    customer?: Partial_Customer_;
+    /**
+     * Partner-forwarded data (e.g. utm, session metadata).
+     */
+    forwarded?: any;
+    /**
+     * Unique identifier for the record.
+     */
+    id: string;
+    /**
+     * Items the user has added to their cart.
+     */
+    items: Array<Partial_OrderItem_>;
+    /**
+     * Internal metadata, flags, debug hints, or experimental context.
+     */
+    meta: Record<string, any>;
+    /**
+     * Stripe PaymentIntent client secret, used by frontend (e.g. Stripe.js).
+     * Required for completing the payment flow.
+     */
+    paymentIntentClientSecret?: string;
+    /**
+     * Stripe PaymentIntent ID linked to this cart, if created.
+     * Used for confirming payment on the backend.
+     */
+    paymentIntentId?: string;
+    status: CartSession.status;
+    /**
+     * Authenticated user ID, if available.
+     */
+    uid: string;
+    /**
+     * Schema version identifier for this record.
+     * Helps manage compatibility across client-server contracts.
+     */
+    version: string;
+};
+declare namespace CartSession {
+    enum status {
+        ABANDONED = "abandoned",
+        CANCELLED = "cancelled",
+        COMPLETED = "completed",
+        STARTED = "started"
+    }
+}
+
 type CostComponentCap = {
     op: string;
     type: CostComponentCap.type;
@@ -143,7 +542,7 @@ type CostComponent = {
     cap?: CostComponentCap;
     currency: string;
     details?: any;
-    id?: string;
+    id: string;
     name: string;
     payer: CostComponent.payer;
     recipient: string;
@@ -338,52 +737,6 @@ type EventProfile = {
     widgets: Array<EventFeature>;
 };
 
-/**
- * Represents the costs associated with an offering.
- */
-type OfferingCosts = {
-    /**
-     * A string representing a currency amount in the format `"USD,1000"` where:
-     * - `"USD"` is the 3-letter ISO currency code.
-     * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
-     *
-     * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
-     */
-    cost: string;
-    /**
-     * A string representing a currency amount in the format `"USD,1000"` where:
-     * - `"USD"` is the 3-letter ISO currency code.
-     * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
-     *
-     * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
-     */
-    delivery: string;
-    /**
-     * A string representing a currency amount in the format `"USD,1000"` where:
-     * - `"USD"` is the 3-letter ISO currency code.
-     * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
-     *
-     * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
-     */
-    fee: string;
-    /**
-     * cost + fee - discount , not including tax
-     */
-    gross: string;
-    /**
-     * A string representing a currency amount in the format `"USD,1000"` where:
-     * - `"USD"` is the 3-letter ISO currency code.
-     * - The number after the comma represents the value in **minor units** (e.g., cents for USD).
-     *
-     * For example, `"USD,1000"` equals $10.00 (i.e., 1000 cents).
-     */
-    tax: string;
-    /**
-     * total cost including tax
-     */
-    total: string;
-};
-
 declare enum OfferingStatus {
     DELETED = "deleted",
     DRAFT = "draft",
@@ -393,21 +746,6 @@ declare enum OfferingStatus {
     UNAVAILABLE = "unavailable"
 }
 
-declare enum OfferingType {
-    ADMISSION = "admission",
-    DONATION = "donation",
-    DRINK = "drink",
-    MEMBERSHIP = "membership",
-    MERCH = "merch",
-    OTHER = "other",
-    PACKAGE = "package",
-    SERVICE = "service",
-    SKIP = "skip",
-    TC_TICKET = "tc-ticket",
-    TICKET = "ticket",
-    VOUCHER = "voucher"
-}
-
 type PackageInclude = {
     description: string;
     id: string;
@@ -452,16 +790,27 @@ type Schedule = {
 type Ticket = {
     capacity: number;
     category: string;
+    /**
+     * ISO 8601 timestamp indicating when the record was last updated, if applicable.
+     */
     changed?: string;
     /**
      * Describe fees and other costs associated with purchasing tickets
      * to this offering
+     *
+     * --@schema array(z.any()).optional()
      */
     costComponents?: Array<CostComponent>;
     costs: OfferingCosts;
+    /**
+     * ISO 8601 timestamp indicating when the record was created.
+     */
     created: string;
     description?: string;
     display_name?: string;
+    /**
+     * Unique identifier for the record.
+     */
     id: string;
     included?: Array<PackageInclude>;
     instructions?: string;
@@ -489,21 +838,40 @@ type Ticket = {
 declare namespace Ticket {
     enum type {
         ADMISSION = "admission",
+        ADMISSION_TABLE_COMMITMENT = "admission.tableCommitment",
         PACKAGE = "package"
     }
 }
 
+type UpdatableCartSession = {
+    customer?: Partial_Customer_;
+    /**
+     * Items the user has added to their cart.
+     */
+    items: Array<Partial_OrderItem_>;
+};
+
 /**
  * Provides methods to interact with the Cohost Events API.
  *
  * Usage:
  * ```ts
  * const client = new CohostClient({ token: 'your-token' });
+ * const list = await client.events.list();
  * const event = await client.events.fetch('event-id');
  * const tickets = await client.events.tickets('event-id');
  * ```
  */
 declare class EventsAPI extends CohostEndpoint {
+    /**
+     * Fetch a list of all events.
+     *
+     * @returns A Promise resolving to an array of event objects
+     * @throws Will throw an error if the request fails
+     *
+     * @todo Implement pagination and filtering options
+     */
+    list(): Promise<EventProfile[]>;
     /**
      * Fetch a single event by ID.
      *
@@ -543,6 +911,58 @@ declare class OrdersAPI extends CohostEndpoint {
     fetch(id: string, uid: string): Promise<any>;
 }
 
+interface StartCartSessionInput {
+    contextId: string;
+    userAgent?: string;
+    referrer?: string;
+    ipAddresses?: string[];
+}
+
+/**
+ * Provides methods to interact with cart sessions in the Cohost API.
+ *
+ * Usage:
+ * ```ts
+ * const client = new CohostClient({ token: 'your-token' });
+ * const session = await client.sessions.start({ contextId: 'evt_abc123' });
+ * ```
+ */
+declare class SessionsAPI extends CohostEndpoint {
+    /**
+     * Start a new cart session.
+     *
+     * @param input - Data to start the session
+     * @returns The newly created cart session
+     * @throws Will throw an error if the request fails
+     */
+    start(input: StartCartSessionInput): Promise<CartSession>;
+    /**
+     * Get a cart session by its ID.
+     *
+     * @param id - The unique session ID
+     * @returns The cart session object
+     * @throws Will throw an error if the session is not found or request fails
+     */
+    get(id: string): Promise<CartSession>;
+    /**
+     * Update a cart session.
+     *
+     * @param id - The ID of the session to update
+     * @param input - Data to update the session
+     * @returns The updated session
+     * @throws Will throw an error if the update fails
+     */
+    update(id: string, input: UpdatableCartSession): Promise<CartSession>;
+    /**
+     * Cancel (soft delete) a cart session.
+     *
+     * @param id - The ID of the session to cancel
+     * @returns Nothing if successful
+     * @throws Will throw an error if the cancel operation fails
+     */
+    cancel(id: string): Promise<void>;
+}
+
 /**
  * Configuration options for instantiating a CohostClient.
  */
@@ -558,6 +978,7 @@ interface CohostClientOptions {
 declare class CohostClient {
     readonly events: EventsAPI;
     readonly orders: OrdersAPI;
+    readonly cart: SessionsAPI;
     private readonly baseOptions;
     constructor(options: CohostClientOptions, customRequestFn?: RequestFn);
     /**