@cohostvip/cohost-node 0.0.4 → 0.0.7

package/dist/index.d.mts

@@ -41,457 +41,224 @@ 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;
-    }>;
-};
+// Generated by dts-bundle-generator v9.5.1
 
-declare enum CostBucket {
-    DELIVERY = "delivery",
-    FEE = "fee",
-    ITEM = "item",
-    TAX = "tax"
+/**
+ * A namespaced identifier representing the entity an order is associated with.
+ *
+ * Must begin with one of the following prefixes:
+ * - "evt_" for events
+ * - "ven_" for venues
+ * - "org_" for organizers
+ *
+ * @example "evt_abc123"
+ * @example "org_def456"
+ *
+ * @schema string()
+ * @pattern ^((evt|ven|org)_[a-zA-Z0-9]+)$
+ */
+type ContextId = string;
+type ApiVersion = "2025-04-15";
+/**
+ * A rich content object that supports multiple representations of text.
+ */
+interface MultipartText {
+	/** HTML version of the content. */
+	html?: string;
+	/** Plain text version of the content. */
+	text?: string;
+	/** Markdown version of the content. */
+	md?: string;
+	/** Optional rich editor blocks (if structured editing is supported). */
+	blocks?: any[] | null;
 }
-
-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"
-    }
+/**
+ * A photo object with resolution options and optional metadata.
+ */
+interface Photo {
+	/** High-resolution (2x) image URL. */
+	"2x"?: string;
+	/** 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.
+	 *
+	 * @example "https://picsum.photos/500"
+	 *
+	 *
+	 * @x-faker image.imageUrl
+	 */
+	url: string;
+	/** Width of the image in pixels. */
+	width?: number;
+	/** Height of the image in pixels. */
+	height?: number;
+	/** Optional caption for the image. */
+	caption?: string;
 }
-
-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 repeating or structured date schedule for an event or item.
+ */
+interface Schedule {
+	/** Days of the week (0 = Sunday, 6 = Saturday). */
+	daysOfWeek?: number[];
+	/** ISO-formatted UTC start datetime. */
+	start: string;
+	/** ISO-formatted UTC end datetime. */
+	end: string;
+	/** Specific dates to exclude in "YYYY-MM-DD" format. */
+	excludeDates?: string[];
+	/** Specific dates to include in "YYYY-MM-DD" format. */
+	includeDates?: string[];
 }
-
 /**
- * Cost breakdown for a specific item in the order.
- * Extends the standard `OfferingCosts` with totals calculated for quantity and discounts.
+ * Base metadata for any record stored in the system.
+ * Includes an ID and timestamps for creation and optional updates.
+ *
+ * @export
  */
-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;
-};
-
+interface DataRecord {
+	/**
+	 * Unique identifier for the record.
+	 * @example "rec_123abc"
+	 */
+	id: string;
+	/**
+	 * ISO 8601 timestamp indicating when the record was created.
+	 * @example "2025-04-16T10:15:00Z"
+	 */
+	created: string;
+	/**
+	 * ISO 8601 timestamp indicating when the record was last updated, if applicable.
+	 * @example "2025-04-18T08:00:00Z"
+	 */
+	changed?: string;
+}
 /**
- * Represents the costs associated with an offering.
+ * Extension of `DataRecord` for resources returned from RESTful APIs.
+ * Includes a schema version to ensure compatibility with evolving formats.
+ *
+ * @export
  */
-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;
-};
-
+interface VersionedDataRecord extends DataRecord {
+	/**
+	 * Schema version identifier for this record.
+	 * Helps manage compatibility across client-server contracts.
+	 * @example "2025-01-10"
+	 */
+	version: ApiVersion;
+}
+interface VCDataRecord extends VersionedDataRecord {
+	companyId: string;
+}
 /**
- * Represents a temporary or persisted cart before order placement.
- * Focuses on user intent and checkout prep, not post-purchase records.
+ * Represents either an absolute or a relative time constraint.
+ *
+ * - If using `date`, `secondsBefore` must not be present.
+ * - If using `secondsBefore`, `date` must not be present.
+ *
+ * @export
  */
-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;
+type TimeOrOffset = {
+	/**
+	 * Absolute time in ISO 8601 format.
+	 * @example "2025-06-30T23:59:59"
+	 */
+	date: string;
+	secondsBefore?: never;
+} | {
+	/**
+	 * Relative time before an anchor point (e.g. event start), in seconds.
+	 * @example 3600
+	 */
+	secondsBefore: number;
+	date?: never;
 };
-declare namespace CartSession {
-    enum status {
-        ABANDONED = "abandoned",
-        CANCELLED = "cancelled",
-        COMPLETED = "completed",
-        STARTED = "started"
-    }
+/**
+ * @description 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).
+ *
+ * @example "USD,0"
+ * @example "USD,100"
+ * @example "USD,1000"
+ *
+ * @pattern ^\w{3},\d+$
+ * @zod .string()
+ */
+type CurrencyAmount = string;
+interface CostBase {
+	/**
+	 * The base value of the cost. This is the value before any operations are applied.
+	 * in OrderItem this is the cost of a single item.
+	 *
+	 * @example "USD,1000"
+	 */
+	cost: CurrencyAmount;
+	/**
+	 * Delivery fee for a single item.
+	 *
+	 * @example "USD,1000"
+	 */
+	delivery: CurrencyAmount;
+	/**
+	 * Fee per item.
+	 * @example "USD,1000"
+	 */
+	fee: CurrencyAmount;
+	/**
+	 * Total discount amount applied to this item.
+	 * @example "USD,1000"
+	 */
+	tax: CurrencyAmount;
 }
-
-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"
-    }
+interface CostComponentCap {
+	op: "cap";
+	type: "percentage" | "absolute";
+	/**
+	 * 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;
+}
+/**
+ * Represents a cost operation to be applied in a pricing formula.
+ *
+ * @example
+ * { op: '*', value: 0.9 }
+ */
+interface CostOp {
+	/**
+	 * The operation to apply to the cost value.
+	 *
+	 * Allowed values:
+	 * - "+" (addition)
+	 * - "-" (subtraction)
+	 * - "*" (multiplication)
+	 * - "/" (division)
+	 * @ignore
+	 * @enum {string}
+	 */
+	op: "+" | "-" | "*" | "/";
+	/**
+	 * The operand value used in the cost operation.
+	 *
+	 * The unit should match the denomination of the cost.
+	 * For example, if cost is expressed in cents, this value should also be in cents.
+	 *
+	 * @example 100
+	 */
+	value: number;
 }
-
 /**
  * A set of comparison operators used for evaluating conditional expressions.
  *
@@ -502,62 +269,330 @@ declare namespace CostComponentCap {
  * - '<=' (less than or equal to)
  * - '>' (greater than)
  * - '>=' (greater than or equal to)
+ * @enum {string}
+ * @ignore
  */
-declare enum EqualOperator {
-    _ = "!="
+type EqualOperator = "==" | "!=" | "<" | "<=" | ">" | ">=";
+interface CostComponentRuleCondition {
+	/**
+	 * 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: string | number | any;
+	/**
+	 * evaluator, will define a function or endpoint to evaluate the condition.
+	 */
+	eval?: string;
 }
-
-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"
-    }
+interface CostComponentRule {
+	/**
+	 * Friendly name of the rule.
+	 */
+	name: string;
+	/**
+	 * The rule will be applied to the cost component if the conditions are met.
+	 */
+	conditions: CostComponentRuleCondition[];
+}
+/**
+ * Represents the costs associated with an offering.
+ *
+ * @property {CurrencyAmount} delivery - The delivery cost.
+ * @property {CurrencyAmount} cost - The cost amount. In an order item, this is the cost of a single item.
+ * @property {CurrencyAmount} fee - The fee amount. In an order item, this is the fee of a single item.
+ * @property {CurrencyAmount} tax - The tax amount. In an order item, this is the tax per a single item.
+ * @property {CurrencyAmount} gross - The gross amount, which is the cost plus fee minus discount, not including tax.
+ * @property {CurrencyAmount} total - The total cost including tax.
+ */
+interface OfferingCosts extends CostBase {
+	/**
+	 * cost + fee - discount , not including tax
+	 *
+	 * In an order item, this is the gross cost of a single item.
+	 *
+	 * @x-faker {"random.arrayElement": ["\"USD,100000\"", "\"USD,25000\""]}
+	 */
+	gross: CurrencyAmount;
+	/**
+	 * total cost including tax
+	 *
+	 * In an order item, this is the total cost * Quantity.
+	 */
+	total: CurrencyAmount;
+}
+type CostBucket = "item" | "fee" | "tax" | "delivery";
+interface CostComponent {
+	id: string;
+	name: string;
+	details?: any;
+	currency: string | "*";
+	base: "order" | "item" | string;
+	bucket: CostBucket;
+	recipient: "organizer" | "platform" | "tax" | string;
+	payer: "attendee" | "organizer";
+	/**
+	 * @ignore
+	 */
+	ops: CostOp[];
+	cap?: CostComponentCap;
+	rules: CostComponentRule[];
+	version: "2025-03-25";
+}
+interface CalculatedCostComponent extends Omit<CostComponent, "ops" | "cap" | "rules" | "details" | "currency"> {
+	cost: CurrencyAmount;
+	value: number;
+	discount: null;
+}
+/**
+ * @zod .string()
+ */
+type OfferingType = "admission" | "package" | "skip" | "drink" | "ticket" | "tc-ticket" | "merch" | "donation" | "membership" | "voucher" | "service" | "other";
+type ActiveOfferingStatus = "live" | "hidden" | "sold-out";
+type OfferingStatus = ActiveOfferingStatus | "draft" | "deleted" | "unavailable";
+type PriceCategory = "donation" | "free" | "paid" | "other";
+interface Offering extends DataRecord {
+	/**
+	 * Offering name, can be ticket name, vaucher name, etc...
+	 * @example "General Admission" (ticket) | "T-shirt" (merch) | "Donation" (donation) | "Membership" (membership) | "Gift Card" (voucher) | "Service Fee" (service) | "Other" (other)
+	 *
+	 * @x-faker commerce.productName
+	 */
+	name: string;
+	type: OfferingType;
+	/**
+	 * @description The maximum number of tickets that can be sold for this offering.
+	 *
+	 * @example 100
+	 *
+	 * @x-faker {"datatype.number": { "min": 10, "max": 100 }}
+	 */
+	capacity: number;
+	quantitySold: number;
+	status: OfferingStatus;
+	priceCategory: PriceCategory;
+	sorting: number;
+	/**
+	 * @ignore
+	 */
+	schedule?: Schedule;
+	description?: string;
+	instructions?: string;
+	/**
+	 * @description Maximum number of tickets that can be purchased in a single order.
+	 *
+	 * @example 10
+	 *
+	 * @x-faker {"datatype.number": { "min": 4, "max": 15 }}
+	 */
+	maximumQuantity: number;
+	/**
+	 * @description Minimum number of tickets that can be purchased in a single order.
+	 *
+	 * @example 1
+	 *
+	 * @x-faker {"datatype.number": { "min": 1, "max": 4 }}
+	 */
+	minimumQuantity: number;
+	package?: boolean;
+	/**
+	 * @description Items, products ,and vouchers included in this offering.
+	 *
+	 *
+	 * @x-faker {"array.length": 0}
+	 */
+	included?: PackageInclude[];
+	/**
+	 * Any constraints that apply to this offering.
+	 * it can be time limit, quantity limit, etc...
+	 */
+	constraints?: any;
+	hidden: boolean;
+	order_confirmation_message?: string | null;
+	costs: OfferingCosts;
+	/**
+	 * Describe fees and other costs associated with purchasing tickets
+	 * to this offering
+	 *
+	 * @ignore
+	 */
+	costComponents?: CostComponent[];
+}
+interface PackageInclude {
+	id: string;
+	quantity: number;
+	type: OfferingType;
+	description: string;
+	ref?: any;
+}
+interface Ticket extends Omit<Offering, "hidden" | "constraints" | "type"> {
+	category: string;
+	type: "admission" | "package" | "admission.tableCommitment";
+	source: string;
+	display_name?: string;
+	description?: string;
+	ticketParentId?: string;
+	salesEnd: string;
+	salesStart: string;
+	parentId?: string;
+	refId?: string;
+}
+interface BuzzBuilder {
+	countLabel: string;
+	profiles: {
+		id: string;
+		name: string;
+		photoURL: string;
+	}[];
+}
+interface EventFeature {
+	id: string;
+	title: string;
+	enabled: boolean;
+	order: number;
+	widgetUri: string;
+	iconName?: string;
+	logoUri?: string;
+	description: string;
+	type: string;
+	version?: string;
+	key: string;
+	meta?: any;
+	data: any;
+}
+interface Address {
+	address_1: string;
+	address_2?: string;
+	city: string;
+	country: string;
+	premise?: string;
+	formattedAddress?: string;
+	localized_address_display?: string;
+	localized_area_display?: string;
+	localized_multi_line_address_display?: string[];
+	postal_code: string;
+	region: string;
 }
-
 /**
- * Status of the event lifecycle.
+ * A simple point geometry consisting of latitude and longitude.
+ *
+ * @typedef {Object} GeometryPoint
+ * @property {number} lat - Latitude of the point.
+ * @property {number} lng - Longitude of the point.
+ *
+ * @example
+ * {
+ *   lat: 40.7128,
+ *   lng: -74.0060
+ * }
+ */
+interface GeometryPoint {
+	lat: number;
+	lng: number;
+}
+/**
+ * Represents the geometry of a location, including optional viewport and zoom level.
+ *
+ * @typedef {Object} LocationGeometry
+ * @property {number} lat - Latitude of the location.
+ * @property {number} lng - Longitude of the location.
+ * @property {number} [zoom] - Optional zoom level representing map detail.
+ * @property {{ northeast: GeometryPoint, southwest: GeometryPoint }} [viewport] - Optional viewport rectangle surrounding the location.
+ * @property {string} [vicinity] - Optional vicinity description.
+ * @property {string} [region] - Optional region.
+ * @property {string} [locality] - Optional locality.
+ * @property {string} [geoHash] - Optional geohash for spatial indexing.
+ *
+ * @example
+ * {
+ *   lat: 37.7749,
+ *   lng: -122.4194,
+ *   zoom: 15,
+ *   viewport: {
+ *     northeast: { lat: 37.785, lng: -122.41 },
+ *     southwest: { lat: 37.765, lng: -122.43 }
+ *   },
+ *   vicinity: "Near Mission District",
+ *   region: "California",
+ *   locality: "San Francisco",
+ *   geoHash: "9q8yy"
+ * }
+ */
+interface LocationGeometry extends GeometryPoint {
+	zoom?: number;
+	viewport?: {
+		northeast: GeometryPoint;
+		southwest: GeometryPoint;
+	};
+	vicinity?: string;
+	region?: string;
+	locality?: string;
+	geoHash?: string;
+}
+/**
+ * A structured representation of a physical location, including address and coordinates.
+ *
+ * @typedef {Object} Location
+ * @property {string | null} venueId - The ID of the venue associated with this location.
+ * @property {string | null} placeId - The Google Place ID associated with this location.
+ * @property {string} name - Name of the location (e.g., venue or custom name).
+ * @property {LocationGeometry | null} geometry - Geospatial data including lat/lng, zoom, and viewport.
+ * @property {Address | null} address - Structured postal address.
+ * @property {string} [timezone] - IANA time zone (e.g., "America/New_York").
+ *
+ * @example
+ * {
+ *   venueId: "abc123",
+ *   placeId: "ChIJVXealLU_xkcRja_At0z9AGY",
+ *   name: "The Fillmore",
+ *   geometry: {
+ *     lat: 37.784,
+ *     lng: -122.433,
+ *     zoom: 14,
+ *     viewport: {
+ *       northeast: { lat: 37.788, lng: -122.429 },
+ *       southwest: { lat: 37.780, lng: -122.437 }
+ *     }
+ *   },
+ *   address: {
+ *     address_1: "1805 Geary Blvd",
+ *     city: "San Francisco",
+ *     state: "CA",
+ *     postalCode: "94115",
+ *     country: "USA"
+ *   },
+ *   timezone: "America/Los_Angeles"
+ * }
+ */
+interface Location {
+	venueId: string | null;
+	placeId: string | null;
+	name: string;
+	geometry: LocationGeometry | null;
+	address: Address | null;
+	timezone?: string;
+}
+interface VenueBase {
+	id: string;
+	name: string;
+	formattedAddress: string;
+	placeId?: string | null;
+	tz: string;
+	logo: Photo | null;
+	public: boolean;
+	address: Address | null;
+	slug: string | null;
+}
+/**
+ * @description 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.
@@ -567,289 +602,579 @@ declare namespace CostComponent {
  * - `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 EventStatus = "archived" | "draft" | "live" | "started" | "ended" | "completed" | "canceled";
+interface EventBase {
+	id: string;
+	/**
+	 * @example "Spring Concert"
+	 * @faker name.firstName
+	 * @x-faker name.firstName
+	 */
+	name: string;
+	summary: string;
+	companyId: string;
+	/**
+	 * @description The timezone in which the event is taking place.
+	 * @example "America/New_York"
+	 * @example "Europe/London"
+	 * @example "Asia/Tokyo"
+	 */
+	tz: string;
+	/**
+	 * @description The start date and time of the event in ISO 8601 format.
+	 * @example "2023-10-01T12:00:00Z"
+	 */
+	start: string;
+	/**
+	 * @description The end date and time of the event in ISO 8601 format.
+	 * @example "2023-10-01T14:00:00Z"
+	 */
+	end: string;
+	isSeries?: boolean;
+	/**
+	 * @description The status of the event in its lifecycle.
+	 * @example "draft"
+	 * @example "live"
+	 * @example "ended"
+	 */
+	status: EventStatus;
+	/**
+	 * @x-faker { url: faker.image.imageUrl() }
+	 */
+	flyer?: Photo | null;
+	venue?: VenueBase | null;
+	/**
+	 * @description Curerncy used for the event.
+	 * @example "USD"
+	 */
+	currency: string;
+	/**
+	 * @description Is the event public?
+	 * @example true
+	 */
+	public: boolean;
+	location?: Location;
 }
-
-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.
+ * @openapi
+ * @description EventProfile respresent a public view of an event
  */
-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;
-};
-
+interface EventProfile extends EventBase {
+	meta?: any;
+	organizer: any;
+	url?: string;
+	slug: string;
+	channels: string[];
+	description: MultipartText;
+	widgets: EventFeature[];
+	ticketPrices: string[];
+	buzzBuilder?: BuzzBuilder | null;
+	venue?: VenueBase | null;
+	tags: string[];
+	searchTags: string[];
+	sections: string[];
+	priceRange?: {
+		min?: string;
+		max?: string;
+	};
+}
 /**
- * A rich content object that supports multiple representations of text.
+ * Represents a discount coupon that can be applied to one or more offerings in an event platform.
+ *
+ * @export
  */
-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;
-};
-
+interface Coupon extends VersionedDataRecord {
+	/**
+	 * ID of the company that issued this coupon.
+	 * @example "company_123abc"
+	 */
+	companyId: string;
+	/**
+	 * Internal description for the coupon.
+	 * This is not necessarily visible to users.
+	 * @example "Early bird discount for spring events"
+	 */
+	description: string;
+	/**
+	 * The code used to redeem this coupon during checkout.
+	 * For public or coded discounts.
+	 * @example "SPRING2025"
+	 */
+	code: string;
+	/**
+	 * Type of coupon — determines how it's distributed or applied.
+	 * @example "coded"
+	 */
+	type: "access" | "coded" | "public" | "hold";
+	/**
+	 * 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.
+	 * @minimum 0
+	 * @maximum 99999
+	 * @example 10.0
+	 */
+	amountOff: number;
+	/**
+	 * Percentage to deduct from the item or order total.
+	 * Range is 0–100. Use 0 for no percentage-based discount.
+	 * @minimum 0
+	 * @maximum 100
+	 * @example 20.0
+	 */
+	percentOff: number;
+	/**
+	 * Total number of times this coupon can be used.
+	 * A value of `0` means unlimited usage.
+	 * @example 100
+	 */
+	limit: number;
+	/**
+	 * Number of times this coupon has been redeemed.
+	 * Read-only field.
+	 * @readonly
+	 * @example 42
+	 */
+	quantitySold: number;
+	/**
+	 * List of offering IDs (e.g., ticket classes) this coupon applies to.
+	 * If empty, the coupon applies to all eligible offerings in its context.
+	 * @example ["off_123abc", "off_456def"]
+	 */
+	offeringIds: string[];
+	/**
+	 * List of context IDs (e.g., event, venue, or organizer) this coupon is valid for.
+	 * Follows the format: "evt_xxx", "org_xxx", etc.
+	 * @example ["evt_abc123", "org_def456"]
+	 */
+	contextIds: ContextId[];
+	/**
+	 * Time-based constraints that control when the coupon is active and when it expires.
+	 * Supports absolute dates or relative time offsets (in seconds) from event start.
+	 *
+	 * - If `start` is omitted, the coupon is valid immediately.
+	 * - If `end` is omitted, the coupon remains valid until the event ends.
+	 *
+	 * @example {
+	 *   start: { date: "2025-04-01T00:00:00" },
+	 *   end: { secondsBefore: 3600 }
+	 * }
+	 */
+	constraints: {
+		start?: TimeOrOffset;
+		end?: TimeOrOffset;
+	};
+	/**
+	 * Current status of the coupon for administrative purposes.
+	 * Determines whether it can be redeemed at checkout.
+	 * @example "active"
+	 */
+	status: "active" | "expired" | "disabled" | "sold_out";
+	/**
+	 * Schema version identifier.
+	 * Used to ensure compatibility between coupon formats.
+	 * @example "2025-01-10"
+	 */
+	version: ApiVersion;
+}
 /**
- * EventProfile respresent a public view of an event
+ * Captures metadata and request/session context at the time the cart is created.
+ * Supports fraud detection, attribution, analytics, and partner session tracking.
+ *
+ * This interface is extensible — additional custom fields may be included as needed.
+ *
+ * @export
  */
-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"
+interface OrderContext {
+	/**
+	 * IP addresses associated with the user request.
+	 * Typically includes forwarded IPs and direct client IP.
+	 * @example ["203.0.113.1", "10.0.0.1"]
+	 */
+	ipAddresses: string[];
+	/**
+	 * Raw User-Agent header from the client request.
+	 * @example "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
+	 */
+	userAgent: string;
+	/**
+	 * The referring URL from which the cart or checkout was initiated.
+	 * May be a partner site, marketing page, or event listing.
+	 * @example "https://partner.example.com/tickets/event123"
+	 */
+	referrer: string;
+	/**
+	 * Authenticated user ID, or null for anonymous guests.
+	 * @example "uid_456def"
+	 */
+	uid: string | null;
+	/**
+	 * The unique cart session ID assigned at the time the cart was created.
+	 * Helps track cart attribution across systems.
+	 * @example "cart_sess_abc123"
+	 */
+	cartSessionId: string;
+	/**
+	 * (Optional) Origin domain name if embedded or white-labeled.
+	 * Can help identify partner portals or iframe referrers.
+	 * @example "examplepartner.com"
+	 */
+	originDomain?: string;
+	/**
+	 * (Optional) Campaign ID, UTM source, or tracking label.
+	 * Useful for affiliate and analytics systems.
+	 * @example "utm_campaign=spring_launch"
+	 */
+	trackingId?: string;
+	/**
+	 * Allows custom fields for analytics, partners, or experiment data.
+	 */
+	[custom: string]: unknown;
 }
-
-type PackageInclude = {
-    description: string;
-    id: string;
-    quantity: number;
-    ref?: any;
-    type: OfferingType;
-};
-
-declare enum PriceCategory {
-    DONATION = "donation",
-    FREE = "free",
-    OTHER = "other",
-    PAID = "paid"
+/**
+ * Cost breakdown for a specific item in the order.
+ * Extends the standard `OfferingCosts` with totals calculated for quantity and discounts.
+ *
+ * @export
+ */
+interface OrderItemCosts extends OfferingCosts {
+	/**
+	 * Total cost of tickets before taxes, fees, and discounts.
+	 * @example { amount: 5000, currency: "USD" }
+	 */
+	subtotal: CurrencyAmount;
+	/**
+	 * Total discount amount applied to this item.
+	 * @example { amount: 1000, currency: "USD" }
+	 */
+	discount: CurrencyAmount;
+	/**
+	 * Total price before discounts.
+	 * Equal to subtotal + fee, before subtracting discount.
+	 * @example { amount: 6000, currency: "USD" }
+	 */
+	preDiscount: CurrencyAmount;
 }
-
 /**
- * A repeating or structured date schedule for an event or item.
+ * Represents an individual item within an order.
+ *
+ * @export
  */
-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"
-    }
+interface OrderItem {
+	/**
+	 * Unique ID for this order item.
+	 * @example "item_abc123"
+	 */
+	id: string;
+	/**
+	 * Type of offering (e.g., ticket, package, merch).
+	 * @example "ticket"
+	 */
+	offeringType: OfferingType;
+	/**
+	 * ID of the offering purchased.
+	 * @example "evt_abc123_off_001"
+	 */
+	offeringId: string;
+	/**
+	 * Quantity purchased of this item.
+	 * @example 2
+	 */
+	quantity: number;
+	/**
+	 * Full cost breakdown for this item.
+	 */
+	costs: OrderItemCosts;
+	/**
+	 * If this item is included as part of a package, this is the ID of the parent item.
+	 * Otherwise, null.
+	 * @example null
+	 */
+	includedWithItemId: string | null;
+	/**
+	 * Breakdown of cost components (e.g., base, service fee, delivery).
+	 */
+	costComponents: CalculatedCostComponent[];
+	/**
+	 * Any relevant metadata associated with this item.
+	 * This can include custom fields or additional information.
+	 * @example { "customField": "value" }
+	 */
+	meta: any;
+	offering: OrderItemOffering;
 }
-
-type UpdatableCartSession = {
-    customer?: Partial_Customer_;
-    /**
-     * Items the user has added to their cart.
-     */
-    items: Array<Partial_OrderItem_>;
+interface OrderItemOffering extends Pick<Offering, "name" | "costs" | "type"> {
+	/**
+	 * doc assicated with this offering in the DB.
+	 *
+	 * @example "events/1234567890/tickets/0987654321"
+	 */
+	docPath: string;
+}
+/**
+ * Person interface
+ */
+interface Person {
+	name: string;
+	photoURL?: string | null;
+	displayName: string;
+	first: string;
+	last: string;
+	gender: null | string | "male" | "female" | "other";
+	birthdate?: string | null;
+	age?: number;
+}
+interface PersonContact {
+	email: string | null;
+	phone: string | null;
+}
+type Customer = Person & PersonContact & {
+	uid: string | null;
 };
+type CouponSummary = Pick<Coupon, "id" | "code" | "amountOff" | "percentOff" | "offeringIds">;
+type OrderStatus = "placed" | "completed" | "attending" | "cancelled" | "refunded" | "started" | "pending" | "abandoned";
+interface OrderCosts {
+	subtotal: CurrencyAmount;
+	fee: CurrencyAmount;
+	tax: CurrencyAmount;
+	discount: CurrencyAmount;
+	delivery: CurrencyAmount;
+	gross: CurrencyAmount;
+	preDiscount: CurrencyAmount;
+	total: CurrencyAmount;
+}
+/**
+ * Represents an order in the system.
+ *
+ * @export
+ */
+interface Order extends VCDataRecord {
+	/**
+	 * Human-readable order number for customer reference.
+	 * Often used in emails and receipts.
+	 * @example "GW-12345679"
+	 */
+	orderNumber: string;
+	/**
+	 * @description The currency code used for this order in ISO 4217 format.
+	 * @example "USD"
+	 *
+	 * @pattern ^[A-Z]{3}$
+	 */
+	currency: string;
+	/**
+	 * List of applied coupons used in the order.
+	 * Supports multiple entries based on organizer preferences.
+	 */
+	coupons?: CouponSummary[];
+	/**
+	 * Namespaced identifier indicating what the order is associated with.
+	 * Format: "{type}_{id}", where type is "evt", "ven", or "org".
+	 * @example "evt_56k2cf348"
+	 * @example "org_9912ff8"
+	 */
+	contextId: ContextId;
+	/**
+	 * Detailed cost breakdown for this order.
+	 */
+	costs: OrderCosts;
+	/**
+	 * Customer information related to this order.
+	 */
+	customer: Customer;
+	/**
+	 * The current status of the order.
+	 * @example "paid"
+	 */
+	status: OrderStatus;
+	/**
+	 * A list of individual items included in the order.
+	 */
+	items: OrderItem[];
+	/**
+	 * Agreement flags for terms and marketing opt-ins.
+	 */
+	agreements: {
+		/**
+		 * Whether the customer accepted the organizer’s custom terms.
+		 * @example true
+		 */
+		agreedToOrganizerTerms?: boolean;
+		/**
+		 * Whether the customer accepted the platform-wide terms of service.
+		 * @example true
+		 */
+		agreedToTerms?: boolean;
+		/**
+		 * Whether the customer opted in to receive marketing emails.
+		 * @example false
+		 */
+		emailOptIn?: boolean;
+		/**
+		 * Whether the customer opted in to receive marketing SMS messages.
+		 * @example false
+		 */
+		textOptIn?: boolean;
+	};
+	/**
+	 * Responses to dynamic questions during checkout (e.g. survey or registration).
+	 * @example { "tshirtSize": "M", "vipNewsletter": true }
+	 */
+	answers: {
+		[questionId: string]: string | boolean;
+	};
+	/**
+	 * Freeform object containing metadata forwarded from the partner site
+	 * or embedding context. Can include UTM tags, user traits, campaign IDs, etc.
+	 * @example { utm_campaign: "spring_launch", partner: "venue_123" }
+	 */
+	forwarded: any;
+	/**
+	 * Internal or computed metadata associated with the order.
+	 * May include fulfillment flags, debugging info, or derived calculations.
+	 * @example { preview: true, manuallyAdjusted: true }
+	 */
+	meta: any;
+	/**
+	 * Session and request context captured at the time of order creation.
+	 * Includes IPs, referrer, user agent, cart session ID, and tracking info.
+	 */
+	context: OrderContext;
+	version: ApiVersion;
+}
+/**
+ * Represents the resolved context associated with a cart session.
+ * This may be an event, venue, or organizer, and is used to enrich the cart with metadata
+ * needed for UI rendering and pricing logic without requiring repeated DB lookups.
+ *
+ * Typically stored in `cart.meta.resolvedContext`.
+ *
+ * @export
+ */
+interface ResolvedCartContext {
+	/**
+	 * Unique identifier of the context entity.
+	 * Typically matches the cart's `contextId` (e.g., "evt_abc123").
+	 * @example "evt_abc123"
+	 */
+	id: string;
+	/**
+	 * Human-readable title or name of the context entity.
+	 * Used for display in headers, summaries, and confirmations.
+	 * @example "Downtown Comedy Night"
+	 */
+	title: string;
+	/**
+	 * Optional physical or virtual location of the event or venue.
+	 * Can include address, coordinates, or virtual link.
+	 */
+	location?: Location;
+	/**
+	 * Optional logo, banner, or primary image representing the context.
+	 * Used in UI to visually identify the entity during checkout.
+	 */
+	logo?: Photo;
+	/**
+	 * A map of offerings relevant to this context (e.g., ticket types, merch).
+	 * Stored as a record keyed by offering ID to allow fast lookup.
+	 * Each value is a partial offering object, intended for display, validation, or pricing.
+	 * @example {
+	 *   "off_123abc": { path: "events/ev_1234/tickets/tkt_567", offering: { name: "VIP Ticket", price: 3000 }),
+	 *   "off_456def": { path: "events/ev_1234/tickets/tkt_567", offering: { name: "T-Shirt", price: 2000 }}
+	 * }
+	 */
+	offerings?: Record<string, ResolvedCartContextOffering>;
+}
+interface ResolvedCartContextOffering {
+	path: string;
+	offering: Offering;
+}
+/**
+ * Represents a temporary or persisted cart before order placement.
+ * Focuses on user intent and checkout prep, not post-purchase records.
+ *
+ * @export
+ */
+interface CartSession extends DataRecord, Pick<Order, "currency" | "contextId" | "version" | "coupons"> {
+	/**
+	 * Authenticated user ID, if available.
+	 * @example "uid_123abc"
+	 */
+	uid: string | null;
+	/**
+	 * Optional snapshot of customer info entered during cart fill.
+	 * Not required and not final.
+	 *
+	 * @schema lazy(() => customerSchema).optional()
+	 */
+	customer?: Partial<Customer>;
+	/**
+	 * @schema lazy(() => orderContextSchema).optional()
+	 */
+	context: Partial<OrderContext>;
+	/**
+	 * Items the user has added to their cart.
+	 */
+	items: Partial<OrderItem>[];
+	/**
+	 * Estimated totals based on current cart state.
+	 * These values are subject to recalculation before checkout.
+	 */
+	costs?: {
+		subtotal: CurrencyAmount;
+		discount: CurrencyAmount;
+		tax: CurrencyAmount;
+		fee: CurrencyAmount;
+		delivery: CurrencyAmount;
+		total: CurrencyAmount;
+	};
+	/**
+	 * Stripe PaymentIntent ID linked to this cart, if created.
+	 * Used for confirming payment on the backend.
+	 * @example "pi_1ABCXYZ..."
+	 */
+	paymentIntentId?: string;
+	/**
+	 * Stripe PaymentIntent client secret, used by frontend (e.g. Stripe.js).
+	 * Required for completing the payment flow.
+	 * @example "pi_1ABCXYZ..._secret_456"
+	 */
+	paymentIntentClientSecret?: string;
+	/**
+	 * Partner-forwarded data (e.g. utm, session metadata).
+	 */
+	forwarded?: any;
+	/**
+	 * Internal metadata, flags, debug hints, or experimental context.
+	 */
+	meta: {
+		/**
+		 * Display context (event, venue, organizer) for rendering and logic.
+		 */
+		resolvedContext?: ResolvedCartContext;
+		/**
+		 * Cost components to calculate the cart costs.
+		 *
+		 * @ignore
+		 */
+		costComponents?: CostComponent[];
+		/**
+		 * Snapshot of when pricing was calculated and locked.
+		 * Useful for honoring totals during a grace window.
+		 */
+		priceLock?: {
+			lockedAt: string;
+			ttl?: number;
+		};
+		/**
+		 * Any additional internal system flags, A/B test conditions, or
+		 * non-critical partner payloads.
+		 */
+		[key: string]: any;
+	};
+	status: "started" | "completed" | "abandoned" | "cancelled";
+}
+type UpdatableCartSession = Pick<CartSession, "customer" | "items">;
 
 /**
  * Provides methods to interact with the Cohost Events API.
@@ -932,7 +1257,8 @@ declare class SessionsAPI extends CohostEndpoint {
      * Start a new cart session.
      *
      * @param input - Data to start the session
-     * @returns The newly created cart session
+     * @returns {CartSession} The latest cart session
+     *
      * @throws Will throw an error if the request fails
      */
     start(input: StartCartSessionInput): Promise<CartSession>;
@@ -940,7 +1266,8 @@ declare class SessionsAPI extends CohostEndpoint {
      * Get a cart session by its ID.
      *
      * @param id - The unique session ID
-     * @returns The cart session object
+     * @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>;
@@ -949,7 +1276,8 @@ declare class SessionsAPI extends CohostEndpoint {
      *
      * @param id - The ID of the session to update
      * @param input - Data to update the session
-     * @returns The updated session
+     * @returns {CartSession} The latest cart session
+     *
      * @throws Will throw an error if the update fails
      */
     update(id: string, input: UpdatableCartSession): Promise<CartSession>;
@@ -961,6 +1289,28 @@ declare class SessionsAPI extends CohostEndpoint {
      * @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>;
 }
 
 /**
@@ -1001,4 +1351,4 @@ declare class CohostClient {
  */
 declare function createCohostClient(options: CohostClientOptions): CohostClient;
 
-export { CohostClient, createCohostClient };
+export { CohostClient, type CohostClientSettings, createCohostClient };