@cohostvip/cohost-node 0.0.3 → 0.0.5

package/dist/index.d.mts

@@ -71,89 +71,402 @@ declare enum CostBucket {
     TAX = "tax"
 }
 
-type CostComponentCap = {
-    op: string;
-    type: CostComponentCap.type;
+type CalculatedCostComponent = {
+    base: string;
+    bucket: CostBucket;
     /**
-     * The value of the cap. If type is percentage, it is a percentage of the base value.
-     * If type is absolute, it is an absolute value.
-     *
-     * Absolute value is represented in the same denomination as the cost.
-     * i.e. if the cost is in cents, the absolute value should be in cents.
+     * 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).
      *
-     * percentage value is represented as a decimal.
-     * For example, 10% is represented as 0.1.
+     * 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 CostComponentCap {
-    enum type {
-        ABSOLUTE = "absolute",
-        PERCENTAGE = "percentage"
+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"
+}
+
 /**
- * A set of comparison operators used for evaluating conditional expressions.
- *
- * Supported operators:
- * - '==' (equal to)
- * - '!=' (not equal to)
- * - '<' (less than)
- * - '<=' (less than or equal to)
- * - '>' (greater than)
- * - '>=' (greater than or equal to)
+ * Cost breakdown for a specific item in the order.
+ * Extends the standard `OfferingCosts` with totals calculated for quantity and discounts.
  */
-declare enum EqualOperator {
-    _ = "!="
-}
+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;
+};
 
-type CostComponentRuleCondition = {
+/**
+ * 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;
     /**
-     * evaluator, will define a function or endpoint to evaluate the condition.
+     * 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).
      */
-    eval?: string;
+    fee: string;
     /**
-     * The field to evaluate the condition against.
-     * For example, "item.price" or "order.total".
-     * The field should be a valid path to the field in the cost component base.
+     * 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).
      */
-    field: string;
-    operator: EqualOperator;
+    tax: string;
     /**
-     * Can be a value such as number, currencyAmount, an ISO date string, etc...
+     * total cost including tax
      */
-    value: any;
+    total: string;
 };
 
-type CostComponentRule = {
+type OrderItemOffering = {
+    costs: OfferingCosts;
     /**
-     * The rule will be applied to the cost component if the conditions are met.
+     * doc assicated with this offering in the DB.
      */
-    conditions: Array<CostComponentRuleCondition>;
+    docPath: string;
     /**
-     * Friendly name of the rule.
+     * Offering name, can be ticket name, vaucher name, etc...
      */
     name: string;
+    type: OfferingType;
 };
 
-type CostComponent = {
-    base: string;
-    bucket: CostBucket;
-    cap?: CostComponentCap;
-    currency: string;
-    details?: any;
+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;
-    name: string;
-    payer: CostComponent.payer;
-    recipient: string;
-    rules: Array<CostComponentRule>;
+    /**
+     * 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 CostComponent {
-    enum payer {
-        ATTENDEE = "attendee",
-        ORGANIZER = "organizer"
+declare namespace CartSession {
+    enum status {
+        ABANDONED = "abandoned",
+        CANCELLED = "cancelled",
+        COMPLETED = "completed",
+        STARTED = "started"
     }
 }
 
@@ -338,52 +651,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 +660,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;
@@ -423,49 +675,39 @@ declare enum PriceCategory {
     PAID = "paid"
 }
 
-/**
- * A repeating or structured date schedule for an event or item.
- */
-type Schedule = {
-    /**
-     * Days of the week (0 = Sunday, 6 = Saturday).
-     */
-    daysOfWeek?: Array<number>;
-    /**
-     * ISO-formatted UTC end datetime.
-     */
-    end: string;
-    /**
-     * Specific dates to exclude in "YYYY-MM-DD" format.
-     */
-    excludeDates?: Array<string>;
-    /**
-     * Specific dates to include in "YYYY-MM-DD" format.
-     */
-    includeDates?: Array<string>;
+type Ticket = {
     /**
-     * ISO-formatted UTC start datetime.
+     * The maximum number of tickets that can be sold for this offering.
      */
-    start: string;
-};
-
-type Ticket = {
     capacity: number;
     category: string;
-    changed?: string;
     /**
-     * Describe fees and other costs associated with purchasing tickets
-     * to this offering
+     * ISO 8601 timestamp indicating when the record was last updated, if applicable.
      */
-    costComponents?: Array<CostComponent>;
+    changed?: string;
     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;
+    /**
+     * Items, products ,and vouchers included in this offering.
+     */
     included?: Array<PackageInclude>;
     instructions?: string;
+    /**
+     * Maximum number of tickets that can be purchased in a single order.
+     */
     maximumQuantity: number;
+    /**
+     * Minimum number of tickets that can be purchased in a single order.
+     */
     minimumQuantity: number;
     /**
      * Offering name, can be ticket name, vaucher name, etc...
@@ -479,7 +721,6 @@ type Ticket = {
     refId?: string;
     salesEnd: string;
     salesStart: string;
-    schedule?: Schedule;
     sorting: number;
     source: string;
     status: OfferingStatus;
@@ -489,21 +730,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 +803,83 @@ 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 {CartSession} The latest 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 {CartSession} The latest cart session
+     *
+     * @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 {CartSession} The latest cart 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>;
+    /**
+     * Update an item in the cart session.
+     *
+     * @param sessionId - The ID of the session
+     * @param props - Properties to update
+     * @returns {CartSession} The latest cart session
+     *
+     * @throws Will throw an error if the update fails
+     */
+    updateItem(sessionId: string, props: {
+        offeringId: string;
+        quantity: number;
+    }): Promise<CartSession>;
+    /**
+     * Remove an item from the cart session.
+     * The same as setting the quantity to 0.
+     *
+     * @param sessionId
+     * @param offeringId
+     * @returns {CartSession} The latest cart session
+     */
+    deleteItem(sessionId: string, offeringId: string): Promise<CartSession>;
+}
+
 /**
  * Configuration options for instantiating a CohostClient.
  */
@@ -558,6 +895,7 @@ interface CohostClientOptions {
 declare class CohostClient {
     readonly events: EventsAPI;
     readonly orders: OrdersAPI;
+    readonly cart: SessionsAPI;
     private readonly baseOptions;
     constructor(options: CohostClientOptions, customRequestFn?: RequestFn);
     /**
@@ -580,4 +918,4 @@ declare class CohostClient {
  */
 declare function createCohostClient(options: CohostClientOptions): CohostClient;
 
-export { CohostClient, createCohostClient };
+export { CohostClient, type CohostClientSettings, createCohostClient };