@vio-live/web-sdk 0.1.0

package/dist/core/index.d.ts

@@ -0,0 +1,748 @@
+import { GraphQLClient } from 'graphql-request';
+
+/**
+ * Vio Configuration — singleton holding apiKey, environment, base URLs,
+ * and optional payment-vendor publishable keys.
+ *
+ * Mirrors `VioConfiguration.shared` in the iOS SDK. Initialised once via
+ * `Vio.init({ apiKey, ... })`; consumed via `Configuration.get()`.
+ *
+ * Secrets (apiKey) never come from inside the SDK — the consumer reads
+ * them from env vars / their config and passes them to `Vio.init`.
+ */
+type Environment = 'development' | 'testing' | 'production';
+interface VioConfig {
+    /** Vio API key for this client app (from the Vio dashboard). */
+    apiKey: string;
+    /** Target environment. Defaults to 'development'. */
+    environment?: Environment;
+    /** Override REST API base. Defaults are env-aware. */
+    apiBase?: string;
+    /** Override GraphQL base. Defaults are env-aware. */
+    graphQLBase?: string;
+    /**
+     * Stripe **publishable** key (`pk_test_xxx` or `pk_live_xxx`). Used for
+     * Apple Pay (via Payment Request) and Card flows. Public-safe — fine
+     * to expose in client bundles.
+     */
+    stripePublishableKey?: string;
+    /**
+     * Klarna **Client Identifier** for Express Checkout (KEC). Public-safe.
+     * From Merchant Portal → Payment settings → Client Identifiers. When set,
+     * the checkout shows the Klarna Express button; when absent it degrades
+     * to the plain method selector. Must match `klarnaEnvironment`.
+     */
+    klarnaClientId?: string;
+    /**
+     * Klarna environment for the Express button. `playground` = sandbox
+     * (test orders, no real money), `production` = live. Defaults to
+     * `playground` so dev/test never hits live Klarna by accident.
+     */
+    klarnaEnvironment?: 'playground' | 'production';
+}
+interface ResolvedConfig {
+    apiKey: string;
+    environment: Environment;
+    apiBase: string;
+    graphQLBase: string;
+    stripePublishableKey?: string;
+    klarnaClientId?: string;
+    klarnaEnvironment: 'playground' | 'production';
+}
+declare class ConfigurationSingleton {
+    private resolved;
+    init(input: VioConfig): void;
+    get(): ResolvedConfig;
+    get isInitialized(): boolean;
+    /** For tests only. */
+    reset(): void;
+}
+declare const Configuration: ConfigurationSingleton;
+
+/**
+ * Vio types — Product / Sponsor / Bootstrap shapes.
+ *
+ * Product types mirror the Vio Commerce GraphQL schema.
+ * Sponsor / Bootstrap shapes mirror the iOS SDK's bootstrap response so
+ * we stay aligned cross-platform.
+ */
+type ImageSize = 'thumbnail' | 'small' | 'medium' | 'large' | 'full';
+interface ProductPrice {
+    amount: number;
+    currency_code: string;
+    compare_at?: number | null;
+    amount_incl_taxes?: number | null;
+    compare_at_incl_taxes?: number | null;
+    tax_amount?: number | null;
+    tax_rate?: number | null;
+}
+interface ProductImage {
+    id: string;
+    url: string;
+    width?: number | null;
+    height?: number | null;
+    order?: number | null;
+}
+interface ProductOption {
+    id: number;
+    name: string;
+    order: number;
+    values: string[];
+}
+interface ProductCategory {
+    id: number;
+    name: string;
+}
+interface ProductVariant {
+    id: number;
+    barcode?: string | null;
+    quantity?: number | null;
+    sku?: string | null;
+    title?: string | null;
+    price: ProductPrice;
+    images: ProductImage[];
+}
+interface Product {
+    id: number;
+    brand?: string | null;
+    title: string;
+    description?: string | null;
+    tags?: string | null;
+    sku: string;
+    quantity?: number | null;
+    price: ProductPrice;
+    variants: ProductVariant[];
+    barcode?: string | null;
+    options: ProductOption[];
+    categories?: ProductCategory[] | null;
+    images: ProductImage[];
+}
+/** Per-sponsor commerce config sourced from Vio bootstrap. */
+interface SponsorCommerceBlock {
+    apiKey: string;
+    channelId?: string | null;
+    paymentMethods?: string[];
+}
+interface Sponsor {
+    id: number;
+    name: string;
+    description?: string | null;
+    avatarUrl?: string | null;
+    logoUrl?: string | null;
+    primaryColor?: string | null;
+    secondaryColor?: string | null;
+    commerce: SponsorCommerceBlock;
+}
+/**
+ * Response shape of `GET /v2/mobile/config` (and likely future `/v2/web/config`).
+ * Matches the iOS SDK's `SdkBootstrapResponse` model.
+ */
+interface BootstrapResponse {
+    campaignId?: number;
+    primarySponsor?: Sponsor;
+    secondarySponsors?: Sponsor[];
+    market?: {
+        countryCode: string;
+        currencyCode: string;
+    };
+}
+/**
+ * A placement component returned by `/v2/mobile/campaigns/:id/components`.
+ * Used by `<vio-product-carousel campaign-id="...">` to know which products
+ * to render at a given slot.
+ */
+interface PlacementComponent {
+    id: number;
+    componentType: string;
+    locationId: string;
+    sponsorId?: number;
+    config: {
+        productIds?: number[];
+        [key: string]: unknown;
+    };
+}
+/** Helper: extract a useful display price from a Product. */
+declare function displayPrice(product: Product): string;
+/** Format a numeric amount + currency for Norwegian style: "1 299 kr". */
+declare function formatPrice(amount: number, currency: string): string;
+/** Helper: pick the first image URL (variant first, then product). */
+declare function primaryImageUrl(product: Product): string | undefined;
+
+/**
+ * Vio REST API client — talks to `api-dev.vio.live` (or override).
+ *
+ * Endpoints (mirrors the iOS SDK's surface):
+ *   GET  /v2/mobile/config                                bootstrap (sponsors + market)
+ *   GET  /v2/mobile/campaigns/:id/components              placement components (TBD)
+ *   POST /v2/mobile/campaigns/:id/cart-intent             cross-device cart-intent (TBD)
+ *
+ * Auth: `X-API-Key: <apiKey>` header (the top-level Vio apiKey).
+ *
+ * Note: until the backend exposes a dedicated `/v2/web/*` surface we
+ * reuse the `/v2/mobile/*` paths — the apiKey identifies the client_app
+ * and the response shape is platform-agnostic enough.
+ */
+
+interface VioApiOptions {
+    /** REST API base URL, e.g. `https://api-dev.vio.live`. */
+    apiBase: string;
+    /** Top-level Vio apiKey for this client app. */
+    apiKey: string;
+}
+declare class VioApi {
+    private readonly apiBase;
+    private readonly apiKey;
+    constructor(options: VioApiOptions);
+    /**
+     * Bootstrap — fetches client app config (sponsors with commerce keys,
+     * default market, campaign id). Called once at SDK init.
+     */
+    bootstrap(): Promise<BootstrapResponse>;
+    /**
+     * Get placement components for a campaign. Used by the carousel auto-fetch
+     * mode (`<vio-product-carousel campaign-id="36" location="news-favorites">`).
+     */
+    getComponents(campaignId: number | string): Promise<PlacementComponent[]>;
+    private get;
+}
+declare class VioApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    readonly endpoint: string;
+    constructor(status: number, body: string, endpoint: string);
+}
+declare function createVioApi(options: VioApiOptions): VioApi;
+
+/**
+ * Commerce GraphQL client — talks to Vio Commerce.
+ *
+ * Mirrors the iOS SDK's `SdkClient.channel.product` surface, but uses
+ * `graphql-request` (lightweight) instead of Apollo. Auth header: `Authorization: <apiKey>`
+ * (per-sponsor commerce apiKey, NOT the top-level Vio apiKey).
+ *
+ * Usage:
+ *   const commerce = createCommerceClient({
+ *     endpoint: 'https://graph-ql-dev.vio.live',
+ *     apiKey: '<sponsor-commerce-apiKey>',  // sponsor's commerce apiKey
+ *   })
+ *   const products = await commerce.channel.product.getByIds({
+ *     product_ids: [408895, 408896],
+ *     currency: 'NOK',
+ *     image_size: 'large',
+ *   })
+ */
+
+interface CommerceClientOptions {
+    /** Vio Commerce GraphQL endpoint, e.g. `https://graph-ql-dev.vio.live`. */
+    endpoint: string;
+    /** Per-sponsor commerce apiKey (from bootstrap.primarySponsor.commerce.apiKey). */
+    apiKey: string;
+}
+interface GetProductsByIdsOptions {
+    product_ids: number[];
+    currency?: string | null;
+    image_size?: ImageSize | null;
+    useCache?: boolean;
+    shipping_country_code?: string | null;
+}
+declare class ChannelProduct {
+    private readonly client;
+    constructor(client: GraphQLClient);
+    /**
+     * Fetch a batch of products by their numeric ids.
+     * Returns an empty array if no ids are provided.
+     */
+    getByIds(options: GetProductsByIdsOptions): Promise<Product[]>;
+}
+declare class Channel {
+    readonly product: ChannelProduct;
+    constructor(client: GraphQLClient);
+}
+/** CommerceClient — namespaced facade, mirrors the iOS SdkClient. */
+declare class CommerceClient {
+    readonly channel: Channel;
+    /** Underlying graphql-request client (escape hatch for custom queries). */
+    readonly raw: GraphQLClient;
+    constructor(options: CommerceClientOptions);
+}
+declare function createCommerceClient(options: CommerceClientOptions): CommerceClient;
+
+/**
+ * Cart types — multi-sponsor line items.
+ *
+ * Mirrors the iOS SDK's `SponsorCart` + `CartLineItem` structure so the
+ * mental model stays consistent across platforms.
+ */
+interface CartLineItem {
+    /** Unique local id for this line item (used for update/remove). */
+    id: string;
+    /** Vio Commerce product id. */
+    productId: number;
+    /** Sponsor (merchant) id this line item belongs to. */
+    sponsorId: number;
+    /** Optional variant id. */
+    variantId?: number;
+    /** Display brand (e.g. "COS"). */
+    brand: string;
+    /** Display product name. */
+    name: string;
+    /** Numeric unit price (inclusive of taxes when available). */
+    unitPrice: number;
+    /** Currency code (e.g. "NOK"). */
+    currency: string;
+    /** Display image URL. */
+    imageUrl: string;
+    /** Quantity. */
+    quantity: number;
+}
+interface SponsorCartState {
+    sponsorId: number;
+    sponsorName?: string;
+    items: CartLineItem[];
+    currency: string;
+}
+
+/**
+ * CartManager — multi-sponsor cart state.
+ *
+ * Mirrors iOS's `CartManager` + `cartsBySponsor`. Holds local state in
+ * memory and persists to localStorage. Reactive: dispatches a `change`
+ * CustomEvent that UI components subscribe to (Web Components react via
+ * `requestUpdate()`).
+ *
+ * Server-side cart sync (Vio Commerce GraphQL CreateCart / AddToCart
+ * mutations) is deferred to checkout time via the CheckoutManager —
+ * this manager is purely client-side state for now.
+ */
+
+interface CartChangeDetail {
+    cartsBySponsor: Map<number, SponsorCartState>;
+    itemCount: number;
+}
+interface AddProductOptions {
+    product: Product;
+    sponsorId: number;
+    sponsorName?: string;
+    quantity?: number;
+    variantId?: number;
+}
+/** Minimal product shape — for callers who only have e.g. mock data, not a full Product. */
+interface AddManualOptions {
+    productId: number;
+    sponsorId: number;
+    sponsorName?: string;
+    brand: string;
+    name: string;
+    unitPrice: number;
+    currency: string;
+    imageUrl: string;
+    quantity?: number;
+    variantId?: number;
+}
+declare class CartManager extends EventTarget {
+    private cartsBySponsor;
+    constructor();
+    /** Add a Product DTO to a sponsor's cart. Bumps quantity if already present. */
+    addProduct(opts: AddProductOptions): CartLineItem;
+    /** Add a manually-specified line item (no Product DTO). */
+    addManual(opts: AddManualOptions): CartLineItem;
+    updateQuantity(lineItemId: string, sponsorId: number, quantity: number): void;
+    removeItem(lineItemId: string, sponsorId: number): void;
+    clearSponsorCart(sponsorId: number): void;
+    clearAllCarts(): void;
+    getAllCarts(): Map<number, SponsorCartState>;
+    getCart(sponsorId: number): SponsorCartState | undefined;
+    get itemCount(): number;
+    subtotalForSponsor(sponsorId: number): number;
+    get totalAcrossSponsors(): number;
+    get primaryCurrency(): string;
+    formatTotal(): string;
+    private persist;
+    private loadFromStorage;
+    private emit;
+}
+
+/**
+ * Apple Pay on the Web — via Stripe Payment Request API.
+ *
+ * Architecture decision (matches iOS Vio SDK pattern):
+ *   - One Stripe **publishable key** for the Vio platform (global, set
+ *     via `Vio.init({ stripePublishableKey })`).
+ *   - One **Stripe Connect account id** per sponsor — sourced from
+ *     `Vio.bootstrap()` response. Without it, the payment lands on the
+ *     platform account instead of the merchant.
+ *
+ * Apple Pay on the Web prerequisites (Stripe-managed for us):
+ *   - Stripe Connect account is enabled for Apple Pay
+ *   - Domain registration for Apple Pay (Stripe handles via Dashboard)
+ *   - Safari + macOS/iOS device with Apple Pay configured
+ *
+ * In Chrome / non-Apple browsers `canMakePayment()` returns null, so the
+ * UI hides the Apple Pay button automatically.
+ */
+interface ApplePayConfig {
+    /** Stripe platform publishable key (pk_live_xxx or pk_test_xxx). */
+    publishableKey: string;
+    /** Sponsor's Stripe Connect account (acct_xxx). Optional but recommended. */
+    connectedAccount?: string;
+    /** Amount in the smallest unit of the currency (e.g. øre for NOK, cents for USD). */
+    amount: number;
+    /** ISO currency code, lowercased internally for Stripe. */
+    currency: string;
+    /** Two-letter country code, e.g. "NO". */
+    country: string;
+    /** Label shown in the Apple Pay sheet (merchant or order name). */
+    label: string;
+    /** Whether to ask the user for payer name. */
+    requestPayerName?: boolean;
+    /** Whether to ask the user for payer email. */
+    requestPayerEmail?: boolean;
+    /** Whether to ask for shipping address. */
+    requestShipping?: boolean;
+    /**
+     * Shipping options shown natively in the Apple Pay sheet. `amount` is in the
+     * smallest unit (øre). When set, `requestShipping` is forced on and the sheet
+     * total = `amount` (items) + the selected option; switching options updates
+     * the total live (Apple Pay native shipping).
+     */
+    shippingOptions?: Array<{
+        id: string;
+        label: string;
+        detail?: string;
+        amount: number;
+    }>;
+}
+interface ApplePayResult {
+    /** Stripe PaymentMethod id (pm_xxx) — pass to backend to confirm the PaymentIntent. */
+    paymentMethodId: string;
+    payerName?: string;
+    payerEmail?: string;
+    payerPhone?: string;
+    shippingAddress?: {
+        line1?: string;
+        line2?: string;
+        city?: string;
+        postal_code?: string;
+        state?: string;
+        country?: string;
+    };
+}
+/**
+ * Check whether Apple Pay is available right now (Safari + supported device
+ * + Stripe configured + domain registered).
+ *
+ * Returns false on any failure path — never throws.
+ */
+declare function checkApplePayAvailability(config: ApplePayConfig): Promise<boolean>;
+/**
+ * Show the Apple Pay sheet. Resolves with the payment method id (`pm_xxx`)
+ * after the user authorises, or rejects on cancel / error.
+ *
+ * The backend must then confirm a Stripe PaymentIntent with this
+ * payment method id (server-side step, not handled here).
+ */
+declare function showApplePaySheet(config: ApplePayConfig): Promise<ApplePayResult>;
+
+/** One line in the express button's purchase data. Amounts in MINOR units. */
+interface KlarnaLineItem {
+    name: string;
+    quantity: number;
+    /** Line total (unitPrice × quantity), minor units (e.g. øre for NOK). */
+    totalAmount: number;
+    /** Per-unit price, minor units. Optional. */
+    unitPrice?: number;
+    /** Merchant SKU / product reference. Optional. */
+    reference?: string;
+    /** Absolute image URL. Optional. */
+    imageUrl?: string;
+}
+/** Payment request handed to the KEC button. Amounts in MINOR units. */
+interface KlarnaPaymentRequestData {
+    /** ISO currency code (e.g. "NOK"). */
+    currency: string;
+    /** Order total in minor units. */
+    amount: number;
+    /** Line items — shown in the Klarna sheet. */
+    supplementaryPurchaseData?: {
+        lineItems: KlarnaLineItem[];
+    };
+}
+interface KlarnaAuthorizeResult {
+    /** Authorization token — backend exchanges it for an order. */
+    authorizationToken: string;
+    /** Klarna may require a finalize step (multistep flows). */
+    finalizeRequired?: boolean;
+    /** Raw payload from the SDK, for debugging / forward-compat. */
+    raw?: unknown;
+}
+interface KlarnaButtonHandle {
+    unmount(): void;
+}
+
+interface KlarnaPaymentsCategory {
+    identifier: string;
+    name: string;
+    asset_urls?: {
+        descriptive?: string;
+        standard?: string;
+    };
+}
+interface KpLoadResult {
+    show_form?: boolean;
+    error?: unknown;
+}
+interface KpAuthorizeResult {
+    approved?: boolean;
+    show_form?: boolean;
+    authorization_token?: string;
+    finalize_required?: boolean;
+    error?: unknown;
+}
+interface KlarnaPaymentsApi {
+    init(opts: {
+        client_token: string;
+    }): void;
+    load(opts: {
+        container: string | HTMLElement;
+        payment_method_category?: string;
+    }, data: Record<string, unknown>, cb?: (res: KpLoadResult) => void): void;
+    authorize(opts: {
+        payment_method_category?: string;
+        auto_finalize?: boolean;
+    }, data: Record<string, unknown>, cb?: (res: KpAuthorizeResult) => void): void;
+}
+interface KlarnaGlobal {
+    Payments: KlarnaPaymentsApi;
+}
+declare global {
+    interface Window {
+        Klarna?: KlarnaGlobal;
+        klarnaAsyncCallback?: () => void;
+    }
+}
+
+/**
+ * Checkout types — multi-sponsor compatible.
+ *
+ * Each checkout is scoped to a single sponsor (one transaction = one
+ * merchant, same as iOS multi-sponsor model). Multiple sponsors → multiple
+ * sequential checkouts.
+ */
+type PaymentMethod = 'apple-pay' | 'klarna' | 'vipps' | 'card';
+interface CheckoutAddress {
+    firstName: string;
+    lastName: string;
+    email: string;
+    address: string;
+    postalCode: string;
+    city: string;
+    country?: string;
+}
+interface CheckoutState {
+    /** Sponsor id whose cart is being checked out. */
+    sponsorId: number;
+    /** Remote checkout id from Vio Commerce (set after CreateCheckout). */
+    remoteId?: string;
+    /** Snapshot of the delivery address. */
+    address?: CheckoutAddress;
+    /** Selected payment method. */
+    paymentMethod?: PaymentMethod;
+    /** Subtotal at open time (numeric). */
+    subtotal: number;
+    /** Currency code. */
+    currency: string;
+}
+
+/**
+ * CheckoutManager — orchestrates the checkout flow.
+ *
+ * Stable contract: open / setAddress / selectPaymentMethod / close.
+ * Per-vendor payment integrations plug into the corresponding method:
+ *   - Apple Pay → `startApplePay()` (Stripe Payment Request, this iteration)
+ *   - Klarna / Vipps / Card → land in subsequent iterations
+ *
+ * Dispatches `change` (state changes) and `payment-select` (user picked
+ * a method) and `payment-complete` (vendor sheet completed successfully).
+ */
+
+interface CheckoutChangeDetail {
+    state: CheckoutState | null;
+}
+interface PaymentSelectDetail {
+    method: PaymentMethod;
+    state: CheckoutState;
+}
+interface PaymentCompleteDetail {
+    method: PaymentMethod;
+    state: CheckoutState;
+    result: ApplePayResult | KlarnaAuthorizeResult | unknown;
+}
+/** Handle for the Klarna Payments (classic widget) flow. */
+interface KlarnaPaymentsHandle {
+    /** Categories offered by the session (pay_now / pay_later / pay_over_time). */
+    categories: KlarnaPaymentsCategory[];
+    /** Currently selected category. */
+    readonly selected: string;
+    /** (Re)load the widget for a category. */
+    load(category?: string): Promise<{
+        showForm: boolean;
+    }>;
+    /** Authorize the selected method and (on approval) create the order. */
+    authorize(): Promise<void>;
+    /** Tear down the mounted widget. */
+    unmount(): void;
+}
+declare class CheckoutManager extends EventTarget {
+    private readonly cartManager;
+    private state;
+    private applePayAvailableCache;
+    private klarnaAvailableCache;
+    private klarnaOrderInFlight;
+    constructor(cartManager: CartManager);
+    open(sponsorId: number): CheckoutState;
+    close(): void;
+    setAddress(address: CheckoutAddress): void;
+    selectPaymentMethod(method: PaymentMethod): void;
+    /**
+     * Returns true if Apple Pay can be shown on this device + Stripe config.
+     * Result is memoised — call `clearApplePayCache()` if config changes.
+     */
+    isApplePayAvailable(country?: string): Promise<boolean>;
+    clearApplePayCache(): void;
+    /**
+     * Prepare Apple Pay for the product-page express button (no active checkout
+     * needed). Pre-creates the Stripe PaymentRequest + resolves canMakePayment so
+     * the returned `show()` can fire synchronously inside the tap (Apple blocks
+     * the sheet if `show()` is reached after an await). `show()` resolves the
+     * sheet, then dispatches `payment-complete` (→ confirmation) or
+     * `payment-error`. `available` is true only when Apple Pay will actually work.
+     */
+    prepareApplePayFor(amount: number, currency: string, country?: string): Promise<{
+        available: boolean;
+        show: () => Promise<void>;
+    }>;
+    /**
+     * Prepare an Apple Pay express charge for an arbitrary amount (e.g. the whole
+     * cart) with NO active checkout. Unlike `prepareApplePayFor`, the returned
+     * `show()` RESOLVES with the result (or `null` on cancel/failure) and does
+     * NOT dispatch the global `payment-complete` — so no checkout overlay appears.
+     * The caller (the cart drawer) renders its own confirmation. `show()` must be
+     * called synchronously inside the tap (Apple's user-gesture rule).
+     */
+    prepareApplePayExpress(amount: number, currency: string, country?: string): Promise<{
+        available: boolean;
+        show: () => Promise<ApplePayResult | null>;
+    }>;
+    /**
+     * Launches the Apple Pay sheet. Resolves with the Stripe PaymentMethod
+     * id once the user authorises — the backend then confirms the
+     * PaymentIntent with that id to actually capture the funds.
+     */
+    startApplePay(options?: {
+        country?: string;
+        label?: string;
+    }): Promise<ApplePayResult>;
+    /**
+     * True if the Klarna Express button can be offered (clientId configured +
+     * SDK loads). Memoised per active checkout. Never throws.
+     */
+    isKlarnaExpressAvailable(): Promise<boolean>;
+    clearKlarnaCache(): void;
+    /**
+     * Build the Klarna payment request from the active cart — amounts in the
+     * currency's minor unit (øre/cents), one line item per cart line.
+     */
+    buildKlarnaPaymentRequest(): KlarnaPaymentRequestData;
+    /**
+     * Mount the Klarna Express button into `container`. On a successful
+     * authorization, fires `payment-complete` with the authorization token —
+     * the host (or vio-backend) then creates the Klarna order server-side.
+     *
+     * Returns the button handle so the UI can unmount on teardown.
+     */
+    mountKlarnaExpress(container: HTMLElement): Promise<KlarnaButtonHandle>;
+    /**
+     * Klarna Payments — classic widget flow (server client_token). Creates a
+     * session on vio-backend, then mounts Klarna's inline widget into
+     * `container`. Returns a handle to switch category and to authorize → which
+     * on approval creates the order via the same backend /orders route as KEC.
+     *
+     * Unlike `mountKlarnaExpress`, this needs no public `klarnaClientId` and no
+     * origin handshake — auth is the server-side API key.
+     */
+    mountKlarnaPayments(container: HTMLElement, opts?: {
+        withShipping?: boolean;
+        shippingId?: string;
+    }): Promise<KlarnaPaymentsHandle>;
+    /** True if the Klarna Payments widget lib can load (UI gate). */
+    klarnaPaymentsAvailable(): Promise<boolean>;
+    /** Cart snapshot + chosen shipping line/amount, for express purchases. */
+    private buildKlarnaInstantContext;
+    /**
+     * Express instant purchase — go straight to Klarna's own modal, no checkout
+     * overlay. Creates a session (with shipping options), loads the widget into a
+     * hidden container, then authorizes (which opens Klarna's confirm modal). On
+     * approval creates the order → `payment-complete` (host shows confirmation);
+     * on failure → `payment-error`. Call `open(sponsorId)` first.
+     */
+    startKlarnaInstant(): Promise<void>;
+    /**
+     * REDIRECT path: call once on app load. If a Klarna purchase was launched
+     * (pending context persisted) and we're back with a token — from the URL or
+     * the SDK's resumed `complete` event — finish creating the order + confirm.
+     */
+    resumeKlarnaReturn(): Promise<void>;
+    /** Snapshot of the active cart for redirect recovery (minor units). */
+    private buildKlarnaPendingContext;
+    /**
+     * POST the token + order lines to vio-backend (it holds the secret API key
+     * and creates the real Klarna order). On success → `payment-complete`; on
+     * failure → `payment-error`. Idempotent: clears the pending key so the
+     * popup and redirect paths can't double-fire.
+     */
+    private completeKlarnaOrder;
+    get currentState(): CheckoutState | null;
+    get items(): CartLineItem[];
+    /**
+     * Resolve the Stripe Connect account for the active sponsor — for now
+     * pulled from bootstrap cache if present. Returns undefined if not set
+     * (Stripe will route to the platform account in that case).
+     */
+    private findStripeConnectAccount;
+    private emit;
+}
+
+declare class VioFacade {
+    private apiInstance;
+    private commerceClients;
+    private bootstrapPromise;
+    private cachedBootstrap;
+    private cartManager;
+    private checkoutManager;
+    init(config: VioConfig): void;
+    get isInitialized(): boolean;
+    get config(): ResolvedConfig;
+    /** Multi-sponsor cart manager. Reactive — listen via addEventListener('change', ...). */
+    get cart(): CartManager;
+    /** Checkout flow manager. Subscribes to cart state via the CartManager. */
+    get checkout(): CheckoutManager;
+    /** Lazy VioApi for REST endpoints on `api-dev.vio.live`. */
+    get api(): VioApi;
+    /**
+     * Bootstrap — fetches client config and caches it. Dedupes in-flight
+     * concurrent requests.
+     */
+    bootstrap(): Promise<BootstrapResponse>;
+    get bootstrapCache(): BootstrapResponse | null;
+    /**
+     * Get a CommerceClient scoped to a specific sponsor (via bootstrap).
+     * Throws if bootstrap hasn't been called or the sponsor is unknown.
+     */
+    commerceFor(sponsorId: number): CommerceClient;
+    /** Get a CommerceClient using an explicit commerce apiKey (skip bootstrap). */
+    commerceWithKey(commerceApiKey: string): CommerceClient;
+    private findSponsor;
+}
+declare const Vio: VioFacade;
+
+export { type AddManualOptions, type AddProductOptions, type ApplePayConfig, type ApplePayResult, type BootstrapResponse, type CartChangeDetail, type CartLineItem, CartManager, type CheckoutAddress, type CheckoutChangeDetail, CheckoutManager, type CheckoutState, CommerceClient, Configuration, type Environment, type ImageSize, type PaymentCompleteDetail, type PaymentMethod, type PaymentSelectDetail, type PlacementComponent, type Product, type ProductCategory, type ProductImage, type ProductOption, type ProductPrice, type ProductVariant, type ResolvedConfig, type Sponsor, type SponsorCartState, type SponsorCommerceBlock, Vio, VioApi, VioApiError, type VioConfig, checkApplePayAvailability, createCommerceClient, createVioApi, displayPrice, formatPrice, primaryImageUrl, showApplePaySheet };