@cohostvip/cohost-node 0.0.2 → 0.0.4

package/dist/index.d.mts

@@ -1,22 +1,17 @@
 /**
  * Supported HTTP methods.
  */
-type RequestMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+type RequestMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
 /**
  * A function that performs a request to the Cohost API.
+ * The generic <T> allows you to specify the expected response type.
  */
-type RequestFn = (
-/** Path of the request relative to baseUrl */
-path: string, options?: {
-    /** HTTP method (defaults to 'GET') */
+type RequestFn = <T = any>(path: string, options?: {
     method?: RequestMethod;
-    /** Request body data (auto-serialized as JSON) */
     data?: any;
-    /** Query parameters to be appended to the URL */
     query?: Record<string, string | number | boolean | undefined>;
-    /** Additional headers to merge into the request */
     headers?: Record<string, string>;
-}) => Promise<any>;
+}) => Promise<T>;
 
 /**
  * Optional settings for customizing the behavior of the CohostClient.
@@ -46,17 +41,837 @@ declare class CohostEndpoint {
     constructor(request: RequestFn, settings: CohostClientSettings);
 }
 
+type Address = {
+    address_1: string;
+    address_2?: string;
+    city: string;
+    country: string;
+    formattedAddress?: string;
+    localized_address_display?: string;
+    localized_area_display?: string;
+    localized_multi_line_address_display?: Array<string>;
+    postal_code: string;
+    premise?: string;
+    region: string;
+};
+
+type BuzzBuilder = {
+    countLabel: string;
+    profiles: Array<{
+        id: string;
+        name: string;
+        photoURL: string;
+    }>;
+};
+
+declare enum CostBucket {
+    DELIVERY = "delivery",
+    FEE = "fee",
+    ITEM = "item",
+    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;
+    /**
+     * 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.
+     *
+     * percentage value is represented as a decimal.
+     * For example, 10% is represented as 0.1.
+     */
+    value: number;
+};
+declare namespace CostComponentCap {
+    enum type {
+        ABSOLUTE = "absolute",
+        PERCENTAGE = "percentage"
+    }
+}
+
+/**
+ * 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)
+ */
+declare enum EqualOperator {
+    _ = "!="
+}
+
+type CostComponentRuleCondition = {
+    /**
+     * evaluator, will define a function or endpoint to evaluate the condition.
+     */
+    eval?: 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.
+     */
+    field: string;
+    operator: EqualOperator;
+    /**
+     * Can be a value such as number, currencyAmount, an ISO date string, etc...
+     */
+    value: any;
+};
+
+type CostComponentRule = {
+    /**
+     * The rule will be applied to the cost component if the conditions are met.
+     */
+    conditions: Array<CostComponentRuleCondition>;
+    /**
+     * Friendly name of the rule.
+     */
+    name: string;
+};
+
+type CostComponent = {
+    base: string;
+    bucket: CostBucket;
+    cap?: CostComponentCap;
+    currency: string;
+    details?: any;
+    id: string;
+    name: string;
+    payer: CostComponent.payer;
+    recipient: string;
+    rules: Array<CostComponentRule>;
+    version: string;
+};
+declare namespace CostComponent {
+    enum payer {
+        ATTENDEE = "attendee",
+        ORGANIZER = "organizer"
+    }
+}
+
+/**
+ * Status of the event lifecycle.
+ *
+ * - `archived`: The event is archived and no longer visible in listings.
+ * - `draft`: The event is still being edited and not yet published.
+ * - `live`: The event is published and accepting actions (e.g., ticket sales).
+ * - `started`: The event has begun.
+ * - `ended`: The event has ended.
+ * - `completed`: The event has concluded successfully and is finalized.
+ * - `canceled`: The event was canceled and is no longer active.
+ */
+declare enum EventStatus {
+    ARCHIVED = "archived",
+    CANCELED = "canceled",
+    COMPLETED = "completed",
+    DRAFT = "draft",
+    ENDED = "ended",
+    LIVE = "live",
+    STARTED = "started"
+}
+
+type GeometryPoint = {
+    lat: number;
+    lng: number;
+};
+
+type LocationGeometry = {
+    geoHash?: string;
+    lat: number;
+    lng: number;
+    locality?: string;
+    region?: string;
+    vicinity?: string;
+    viewport?: {
+        northeast: GeometryPoint;
+        southwest: GeometryPoint;
+    };
+    zoom?: number;
+};
+
+type Location = {
+    address: Address;
+    geometry: LocationGeometry;
+    name: string;
+    placeId: string;
+    timezone?: string;
+    venueId: string;
+};
+
+/**
+ * A photo object with resolution options and optional metadata.
+ */
+type Photo = {
+    /**
+     * High-resolution (2x) image URL.
+     */
+    '2x'?: string;
+    /**
+     * Optional caption for the image.
+     */
+    caption?: string;
+    /**
+     * Height of the image in pixels.
+     */
+    height?: number;
+    /**
+     * Internal photo ID, if stored in a media system.
+     */
+    id?: string;
+    /**
+     * Primary image URL.
+     * This is the default image URL to be used when no other resolution is specified.
+     */
+    url: string;
+    /**
+     * Width of the image in pixels.
+     */
+    width?: number;
+};
+
+type VenueBase = {
+    address: Address;
+    formattedAddress: string;
+    id: string;
+    logo: Photo;
+    name: string;
+    placeId?: string;
+    public: boolean;
+    slug: string;
+    tz: string;
+};
+
+type EventFeature = {
+    data: any;
+    description: string;
+    enabled: boolean;
+    iconName?: string;
+    id: string;
+    key: string;
+    logoUri?: string;
+    meta?: any;
+    order: number;
+    title: string;
+    type: string;
+    version?: string;
+    widgetUri: string;
+};
+
+/**
+ * A rich content object that supports multiple representations of text.
+ */
+type MultipartText = {
+    /**
+     * Optional rich editor blocks (if structured editing is supported).
+     */
+    blocks?: Array<any>;
+    /**
+     * HTML version of the content.
+     */
+    html?: string;
+    /**
+     * Markdown version of the content.
+     */
+    md?: string;
+    /**
+     * Plain text version of the content.
+     */
+    text?: string;
+};
+
+/**
+ * EventProfile respresent a public view of an event
+ */
+type EventProfile = {
+    buzzBuilder?: BuzzBuilder;
+    channels: Array<string>;
+    companyId: string;
+    /**
+     * Curerncy used for the event.
+     */
+    currency: string;
+    description: MultipartText;
+    /**
+     * The end date and time of the event in ISO 8601 format.
+     */
+    end: string;
+    flyer?: Photo;
+    id: string;
+    isSeries?: boolean;
+    location?: Location;
+    meta?: any;
+    name: string;
+    organizer: any;
+    priceRange?: {
+        max?: string;
+        min?: string;
+    };
+    /**
+     * Is the event public?
+     */
+    public: boolean;
+    searchTags: Array<string>;
+    sections: Array<string>;
+    slug: string;
+    /**
+     * The start date and time of the event in ISO 8601 format.
+     */
+    start: string;
+    status: EventStatus;
+    summary: string;
+    tags: Array<string>;
+    ticketPrices: Array<string>;
+    /**
+     * The timezone in which the event is taking place.
+     */
+    tz: string;
+    url?: string;
+    venue?: VenueBase;
+    widgets: Array<EventFeature>;
+};
+
+declare enum OfferingStatus {
+    DELETED = "deleted",
+    DRAFT = "draft",
+    HIDDEN = "hidden",
+    LIVE = "live",
+    SOLD_OUT = "sold-out",
+    UNAVAILABLE = "unavailable"
+}
+
+type PackageInclude = {
+    description: string;
+    id: string;
+    quantity: number;
+    ref?: any;
+    type: OfferingType;
+};
+
+declare enum PriceCategory {
+    DONATION = "donation",
+    FREE = "free",
+    OTHER = "other",
+    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>;
+    /**
+     * ISO-formatted UTC start datetime.
+     */
+    start: string;
+};
+
+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;
+    maximumQuantity: number;
+    minimumQuantity: number;
+    /**
+     * Offering name, can be ticket name, vaucher name, etc...
+     */
+    name: string;
+    order_confirmation_message?: string;
+    package?: boolean;
+    parentId?: string;
+    priceCategory: PriceCategory;
+    quantitySold: number;
+    refId?: string;
+    salesEnd: string;
+    salesStart: string;
+    schedule?: Schedule;
+    sorting: number;
+    source: string;
+    status: OfferingStatus;
+    ticketParentId?: string;
+    type: Ticket.type;
+};
+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.
      *
@@ -64,7 +879,7 @@ declare class EventsAPI extends CohostEndpoint {
      * @returns A Promise resolving to the event object
      * @throws Will throw an error if the request fails or the event is not found
      */
-    fetch(id: string): Promise<any>;
+    fetch(id: string): Promise<EventProfile>;
     /**
      * List all tickets associated with a specific event.
      *
@@ -72,7 +887,7 @@ declare class EventsAPI extends CohostEndpoint {
      * @returns A Promise resolving to an array of ticket objects
      * @throws Will throw an error if the request fails or the event does not exist
      */
-    tickets(id: string): Promise<any>;
+    tickets(id: string): Promise<Ticket[]>;
 }
 
 /**
@@ -96,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.
  */
@@ -107,20 +974,21 @@ interface CohostClientOptions {
 }
 /**
  * CohostClient provides grouped access to various API modules such as Events and Orders.
- *
- * Usage:
- * ```ts
- * const client = new CohostClient({ token: 'your-token' });
- * const event = await client.events.fetch('event-id');
- * const order = await client.orders.fetch('order-id', 'user-id');
- * ```
  */
 declare class CohostClient {
-    /** Access to Event-related endpoints */
     readonly events: EventsAPI;
-    /** Access to Order-related endpoints */
     readonly orders: OrdersAPI;
-    constructor({ token, settings }: CohostClientOptions);
+    readonly cart: SessionsAPI;
+    private readonly baseOptions;
+    constructor(options: CohostClientOptions, customRequestFn?: RequestFn);
+    /**
+     * Returns a new CohostClient instance with overridden request behavior
+     */
+    requestWithOverrides(overrides: {
+        token?: string;
+        baseUrl?: string;
+        headers?: Record<string, string>;
+    }): CohostClient;
 }
 
 /**