/**
 * @shopkit/events - Event System Types
 *
 * Core infrastructure types for the EventBus: event type enum, envelope,
 * middleware, user data, cookies, and page context.
 *
 * Event payload interfaces (the data shapes for each event) live in
 * `./payloads.ts`.
 *
 * @packageDocumentation
 */

/**
 * All 13 standardized event types.
 *
 * Uses Facebook-standard PascalCase naming. The system emits these exact names —
 * each SDK (meta-pixel, ga4, etc.) subscribes to them and handles vendor-specific
 * mapping internally.
 *
 * E-commerce Funnel (priority order):
 *   PageView → ViewContent → AddToCart → InitiateCheckout → AddShippingInfo → AddPaymentInfo → Purchase
 *
 * Additional: Search, AddToWishlist, Lead, CompleteRegistration, Contact, Subscribe
 */
declare enum OpenStoreEventType {
    PAGE_VIEW = "PageView",
    VIEW_CONTENT = "ViewContent",
    ADD_TO_CART = "AddToCart",
    INITIATE_CHECKOUT = "InitiateCheckout",
    ADD_SHIPPING_INFO = "AddShippingInfo",
    ADD_PAYMENT_INFO = "AddPaymentInfo",
    PURCHASE = "Purchase",
    SEARCH = "Search",
    ADD_TO_WISHLIST = "AddToWishlist",
    LEAD = "Lead",
    COMPLETE_REGISTRATION = "CompleteRegistration",
    CONTACT = "Contact",
    SUBSCRIBE = "Subscribe"
}
/**
 * Raw user data passed through to SDK subscribers.
 * Each SDK decides how to consume this data (e.g., Meta CAPI hashes server-side).
 */
interface StandardUserData {
    /** User email address */
    email?: string;
    /** Phone number (with country code) */
    phone?: string;
    /** External customer ID from your system */
    external_id?: string;
    /** First name */
    first_name?: string;
    /** Last name */
    last_name?: string;
    /** City */
    city?: string;
    /** State/province */
    state?: string;
    /** Zip/postal code */
    zip_code?: string;
    /** ISO 3166-1 alpha-2 country code */
    country?: string;
    /** Date of birth (YYYYMMDD format) */
    date_of_birth?: string;
    /** Gender ("m" or "f") */
    gender?: string;
}
/**
 * Platform-specific tracking cookies.
 * Read by the User Enricher middleware. NOT hashed.
 */
interface StandardCookies {
    /** Google Analytics client ID (_ga cookie) */
    _ga?: string;
    /** Meta browser ID cookie */
    _fbp?: string;
    /** Meta click ID cookie */
    _fbc?: string;
    /** Google Ads click ID (from URL param or cookie) */
    gclid?: string;
}
/**
 * Page context automatically captured by the EventBus.
 */
interface PageContext {
    /** Full URL (window.location.href) */
    url: string;
    /** Path only (window.location.pathname) */
    path: string;
    /** Document title */
    title: string;
    /** Referrer URL */
    referrer: string;
    /** Page type detected from URL (home, product, collection, cart, checkout, search, page, account, other) */
    type?: string;
}
/**
 * The canonical event envelope.
 * Every event emitted through the EventBus is wrapped in this shape.
 * The envelope is auto-generated by EventBus.emit() — emitters only provide type + data.
 */
interface OpenStoreEvent<T extends OpenStoreEventType = OpenStoreEventType> {
    /** UUID v4, unique per event instance (used for deduplication) */
    event_id: string;
    /** The event type */
    event_type: T;
    /** Unix timestamp in milliseconds */
    timestamp: number;
    /** Session identifier (from sessionStorage) */
    session_id: string;
    /** Event-specific payload */
    data: T extends keyof OpenStoreEventMap ? OpenStoreEventMap[T] : unknown;
    /** Page context at time of emission */
    page: PageContext;
    /** User data (added by User Enricher middleware) */
    user_data?: StandardUserData;
    /** Tracking cookies (added by User Enricher middleware) */
    cookies?: StandardCookies;
    /** Event source */
    source: "client" | "server";
    /** Extensible metadata */
    meta?: Record<string, unknown>;
    /** Experiment/A/B test data (added by experiment-enricher middleware) */
    experiment?: Record<string, string | null>;
}
/**
 * Event handler function. Receives a fully-formed event envelope.
 */
type EventHandler<T extends OpenStoreEventType = OpenStoreEventType> = (event: OpenStoreEvent<T>) => void | Promise<void>;
/**
 * Middleware function. Receives event and next() callback.
 * Call next() to pass event to next middleware. Don't call next() to block.
 */
type Middleware = (event: OpenStoreEvent, next: () => void) => void;
/**
 * Unsubscribe function returned by subscribe().
 */
type Unsubscribe = () => void;

/**
 * @shopkit/events - Event Payloads
 *
 * Data shape interfaces for each of the 13 standardized events.
 * Uses Facebook-standard field names as the canonical format.
 *
 * @packageDocumentation
 */

/**
 * Which product identifier to send in content_ids for Meta Ads catalog matching.
 * Must match what the merchant configured in Meta Ads → Product Identifier setting.
 */
type ProductIdentifier = "product_id" | "sku" | "variant_id";
/**
 * Meta's contents[] array item for Dynamic Ads.
 * Used in AddToCart, InitiateCheckout, Purchase, ViewContent, AddToWishlist.
 */
interface ContentItem {
    /** Product SKU/ID */
    id: string;
    /** Item quantity */
    quantity: number;
    /** Unit price (used in Purchase for revenue attribution) */
    item_price?: number;
    /** Product display name (used by GA4 for product attribution) */
    name?: string;
}
/**
 * Lean mapper output — the fields emitters need to build Meta-canonical payloads.
 * Mappers convert platform-specific data (Shopify, etc.) into this shape.
 * Emitters then spread these into content_ids, contents[], etc.
 *
 * Carries all 3 possible identifiers so the emitter can resolve
 * the correct one based on the merchant's Meta Ads config.
 */
interface ProductFields {
    /** Product identifier (always the product-level ID) */
    item_id: string;
    /** Shopify variant-level ID (e.g., gid://shopify/ProductVariant/456) */
    variant_id?: string;
    /** Variant SKU string (e.g., "ABC-001") */
    sku?: string;
    /** Product display name */
    item_name: string;
    /** Primary product category */
    item_category?: string;
    /** Unit price (numeric, NOT { amount, currencyCode }) */
    price: number;
    /** Quantity */
    quantity: number;
    /** ISO 4217 currency code (e.g., "INR", "USD") */
    currency: string;
}
/**
 * Resolve the correct product identifier for content_ids based on Meta Ads config.
 * Falls back to item_id if the requested field is missing.
 */
declare function resolveContentId(product: ProductFields, identifier?: ProductIdentifier): string;
/**
 * PageView payload — extends PageContext with session_id.
 * PageContext fields (url, path, title, referrer, type) are also auto-attached
 * to every event via `event.page`.
 */
interface PageViewPayload extends PageContext {
    session_id: string;
}
interface ViewContentPayload {
    /** REQUIRED — Array of product SKU/IDs */
    content_ids: string[];
    /** REQUIRED — 'product' or 'product_group' */
    content_type: string;
    /** Recommended — Product name */
    content_name?: string;
    /** Recommended — Product category */
    content_category?: string;
    /** For Dynamic Ads */
    contents?: ContentItem[];
    /** Recommended — Price */
    value?: number;
    /** REQUIRED if value present — ISO 4217 currency code */
    currency?: string;
}
interface AddToCartPayload {
    /** REQUIRED — Array of product SKU/IDs */
    content_ids: string[];
    /** REQUIRED — 'product' or 'product_group' */
    content_type: string;
    /** Recommended — Product name */
    content_name?: string;
    /** Recommended — Product category (e.g., product_type from API) */
    content_category?: string;
    /** REQUIRED — Cart total value */
    value: number;
    /** REQUIRED — ISO 4217 currency code */
    currency: string;
    /** REQUIRED for Dynamic Ads — Item details */
    contents: ContentItem[];
    /** Recommended — Total quantity */
    num_items?: number;
}
interface InitiateCheckoutPayload {
    /** REQUIRED — Array of product SKU/IDs */
    content_ids: string[];
    /** REQUIRED — 'product' or 'product_group' */
    content_type: string;
    /** Recommended — Product name */
    content_name?: string;
    /** REQUIRED — Cart total value */
    value: number;
    /** REQUIRED — ISO 4217 currency code */
    currency: string;
    /** REQUIRED — Total quantity */
    num_items: number;
    /** REQUIRED — Item details */
    contents: ContentItem[];
    /** Optional coupon code */
    coupon?: string;
}
/** Custom event (not in Meta spec). Tracks shipping info submission. */
interface AddShippingInfoPayload {
    /** REQUIRED — e.g., "standard", "express", "overnight" */
    shipping_method: string;
    /** REQUIRED — ISO 4217 currency code */
    currency: string;
    /** REQUIRED — Cart total value */
    value: number;
    /** Optional coupon code */
    coupon?: string;
}
/** Matches Meta's AddPaymentInfo. Tracks payment info submission. */
interface AddPaymentInfoPayload {
    /** REQUIRED — e.g., "credit_card", "upi", "cod" */
    payment_method: string;
    /** REQUIRED — ISO 4217 currency code */
    currency: string;
    /** REQUIRED — Cart total value */
    value: number;
    /** Optional coupon code */
    coupon?: string;
}
interface PurchasePayload {
    /** REQUIRED — Array of product SKU/IDs */
    content_ids: string[];
    /** REQUIRED — 'product' or 'product_group' */
    content_type: string;
    /** Recommended — Product name */
    content_name?: string;
    /** REQUIRED — Must be > 0 */
    value: number;
    /** REQUIRED — ISO 4217 currency code */
    currency: string;
    /** REQUIRED — Total quantity */
    num_items: number;
    /** REQUIRED — Item details with item_price */
    contents: ContentItem[];
    /** Strongly recommended — Unique order identifier */
    order_id: string;
    /** Tax amount */
    tax?: number;
    /** Shipping cost */
    shipping?: number;
    /** Coupon code */
    coupon?: string;
}
interface SearchPayload {
    /** The search query string */
    search_string: string;
    /** Number of results returned */
    results_count?: number;
}
interface AddToWishlistPayload {
    /** REQUIRED — Array of product SKU/IDs */
    content_ids: string[];
    /** REQUIRED — 'product' or 'product_group' */
    content_type: string;
    /** Recommended — Product name */
    content_name?: string;
    /** For Dynamic Ads */
    contents?: ContentItem[];
    /** Product price */
    value?: number;
    /** ISO 4217 currency code */
    currency?: string;
}
interface LeadPayload {
    /** Lead source or form identifier */
    lead_source?: string;
    /** Value of the lead */
    value?: number;
    /** Currency for the lead value */
    currency?: string;
}
interface CompleteRegistrationPayload {
    /** Registration method (e.g., "email", "phone", "social") */
    method?: string;
    /** Value of the registration */
    value?: number;
    /** Currency for the registration value */
    currency?: string;
}
interface ContactPayload {
    /** Contact method or form identifier */
    contact_method?: string;
}
interface SubscribePayload {
    /** Subscription type (e.g., "newsletter", "sms") */
    subscription_type?: string;
    /** Value of the subscription */
    value?: number;
    /** Currency for the subscription value */
    currency?: string;
}
/**
 * Maps each event type to its payload interface.
 * Used for type-safe subscribe() and emit() calls.
 */
interface OpenStoreEventMap {
    [OpenStoreEventType.PAGE_VIEW]: PageViewPayload;
    [OpenStoreEventType.VIEW_CONTENT]: ViewContentPayload;
    [OpenStoreEventType.ADD_TO_CART]: AddToCartPayload;
    [OpenStoreEventType.INITIATE_CHECKOUT]: InitiateCheckoutPayload;
    [OpenStoreEventType.ADD_SHIPPING_INFO]: AddShippingInfoPayload;
    [OpenStoreEventType.ADD_PAYMENT_INFO]: AddPaymentInfoPayload;
    [OpenStoreEventType.PURCHASE]: PurchasePayload;
    [OpenStoreEventType.SEARCH]: SearchPayload;
    [OpenStoreEventType.ADD_TO_WISHLIST]: AddToWishlistPayload;
    [OpenStoreEventType.LEAD]: LeadPayload;
    [OpenStoreEventType.COMPLETE_REGISTRATION]: CompleteRegistrationPayload;
    [OpenStoreEventType.CONTACT]: ContactPayload;
    [OpenStoreEventType.SUBSCRIBE]: SubscribePayload;
}

export { type AddPaymentInfoPayload as A, type CompleteRegistrationPayload as C, type EventHandler as E, type InitiateCheckoutPayload as I, type LeadPayload as L, type Middleware as M, type OpenStoreEvent as O, type ProductIdentifier as P, type SearchPayload as S, type Unsubscribe as U, type ViewContentPayload as V, type ProductFields as a, type AddShippingInfoPayload as b, type AddToCartPayload as c, type AddToWishlistPayload as d, type ContactPayload as e, type ContentItem as f, type OpenStoreEventMap as g, OpenStoreEventType as h, type PageContext as i, type PageViewPayload as j, type PurchasePayload as k, type StandardCookies as l, type StandardUserData as m, type SubscribePayload as n, resolveContentId as r };