@neowhale/storefront 0.2.43 → 0.2.45

package/dist/client-D7_7p7ja.d.cts

@@ -0,0 +1,669 @@
+interface PixelConfig {
+    provider: string;
+    pixel_id: string;
+    measurement_id?: string;
+}
+interface StorefrontConfig {
+    object: 'storefront_config';
+    pixels: PixelConfig[];
+    theme?: Record<string, unknown>;
+}
+
+interface PricingTier {
+    id: string;
+    unit: string;
+    label: string;
+    quantity: number;
+    sort_order: number;
+    default_price: number;
+}
+interface ProductVariation {
+    id: string;
+    product_id: string;
+    name: string;
+    sku: string | null;
+    price: number;
+    stock_quantity: number;
+    attributes: Record<string, string>;
+}
+interface Product {
+    id: string;
+    name: string;
+    slug: string;
+    sku: string | null;
+    description: string | null;
+    status: string;
+    type: string;
+    primary_category_id: string;
+    featured_image: string | null;
+    image_gallery: string[];
+    pricing_data: PricingTier[] | {
+        mode?: string;
+        tiers?: PricingTier[];
+    } | null;
+    custom_fields: Record<string, string | null>;
+    stock_quantity?: number;
+}
+interface Category {
+    id: string;
+    name: string;
+    slug: string;
+    parent_id: string | null;
+    description: string | null;
+    image_url: string | null;
+    sort_order: number;
+    product_count?: number;
+}
+interface CategoryTreeNode extends Category {
+    children: CategoryTreeNode[];
+}
+interface Review {
+    id: string;
+    product_id: string;
+    customer_id: string | null;
+    customer_name: string | null;
+    rating: number;
+    title: string | null;
+    body: string | null;
+    status: string;
+    created_at: string;
+    updated_at: string;
+}
+interface ReviewSummary {
+    average_rating: number;
+    total_reviews: number;
+    rating_distribution: Record<string, number>;
+}
+interface WishlistItem {
+    id: string;
+    product_id: string;
+    product: Product | null;
+    added_at: string;
+}
+interface LoyaltyAccount {
+    customer_id: string;
+    points_balance: number;
+    tier: string;
+    lifetime_points: number;
+    redemption_mode?: 'cash' | 'rewards_only';
+}
+interface LoyaltyReward {
+    id: string;
+    name: string;
+    description: string | null;
+    points_cost: number;
+    reward_type: string;
+    is_active: boolean;
+    reward_category?: string;
+    reward_product_tier?: string;
+}
+interface LoyaltyTransaction {
+    id: string;
+    customer_id: string;
+    points: number;
+    type: string;
+    description: string | null;
+    created_at: string;
+    order_id: string | null;
+}
+interface ShippingMethod {
+    id: string;
+    name: string;
+    description: string | null;
+    carrier: string | null;
+    estimated_days_min: number | null;
+    estimated_days_max: number | null;
+    is_active: boolean;
+}
+interface ShippingRate {
+    method_id: string;
+    method_name: string;
+    carrier: string | null;
+    rate: number;
+    estimated_days_min: number | null;
+    estimated_days_max: number | null;
+}
+interface DealValidation {
+    valid: boolean;
+    code: string;
+    deal_id?: string;
+    name?: string;
+    discount_type: string | null;
+    discount_value: number | null;
+    apply_to?: string;
+    badge_text?: string | null;
+    message: string | null;
+}
+/** @deprecated Use DealValidation instead */
+type CouponValidation = DealValidation;
+interface CheckoutSession {
+    id: string;
+    cart_id: string;
+    status: string;
+    customer_email: string | null;
+    shipping_address: Address | null;
+    billing_address: Address | null;
+    shipping_method_id: string | null;
+    coupon_code: string | null;
+    subtotal: number;
+    tax_amount: number;
+    shipping_amount: number;
+    discount_amount: number;
+    total: number;
+    created_at: string;
+    expires_at: string;
+}
+interface Recommendation {
+    product: Product;
+    score: number;
+    reason: string;
+}
+interface CartItem {
+    id: string;
+    product_id: string;
+    product_name: string;
+    image_url: string | null;
+    quantity: number;
+    unit_price: number;
+    tier_label: string | null;
+    line_total: number;
+}
+interface TaxBreakdown {
+    name: string;
+    rate: number;
+    type: string;
+    rate_decimal: number;
+}
+interface Cart {
+    id: string;
+    items: CartItem[];
+    item_count: number;
+    subtotal: number;
+    tax_rate: number;
+    tax_amount: number;
+    total: number;
+    tax_breakdown: TaxBreakdown[];
+    discount_amount: number;
+    customer_email: string | null;
+}
+interface Order {
+    id: string;
+    order_number: string;
+    status: string;
+    total_amount: number;
+    subtotal: number;
+    tax_amount: number;
+    discount_amount: number;
+    item_count?: number;
+    created_at: string;
+    payment_status?: string;
+    fulfillment_status?: string;
+    items?: OrderItem[];
+}
+interface OrderItem {
+    id: string;
+    product_name: string;
+    quantity: number;
+    unit_price?: number;
+    cost_per_unit?: number;
+    line_total: number;
+}
+interface Customer {
+    id: string;
+    first_name: string;
+    last_name: string;
+    email: string | null;
+    phone: string | null;
+    loyalty_points: number;
+    loyalty_tier: string;
+    total_spent: number;
+    total_orders: number;
+    lifetime_value?: number;
+    street_address?: string | null;
+    city?: string | null;
+    state?: string | null;
+    postal_code?: string | null;
+    date_of_birth?: string | null;
+    created_at?: string;
+    is_staff?: boolean;
+    email_consent?: boolean;
+    sms_consent?: boolean;
+}
+interface Address {
+    firstName: string;
+    lastName: string;
+    address: string;
+    city: string;
+    state: string;
+    zip: string;
+    country: string;
+}
+interface PaymentData {
+    payment_method: 'card' | 'cash';
+    opaque_data?: {
+        dataDescriptor: string;
+        dataValue: string;
+    };
+    billTo?: Address;
+    shipTo?: Address;
+}
+interface CustomerAnalytics {
+    customer_id: string;
+    customer_name: string;
+    total_orders: number;
+    lifetime_revenue: number;
+    avg_order_value: number;
+    ltv_tier: string;
+    rfm_segment: string;
+    churn_risk: string;
+    last_order_date: string;
+    recency_days: number;
+}
+interface Location {
+    id: string;
+    name: string;
+    address?: string;
+    city?: string;
+    state?: string;
+    zip?: string;
+    phone?: string;
+    is_active?: boolean;
+}
+interface SendCodeResponse {
+    sent: boolean;
+}
+interface VerifyCodeResponse {
+    object: string;
+    token_hash: string;
+    needs_profile: boolean;
+    customer: Customer | null;
+}
+interface StorefrontSession {
+    id: string;
+    store_id: string;
+    customer_id?: string;
+    started_at: string;
+    last_active_at: string;
+    latitude?: number;
+    longitude?: number;
+    geolocation_source?: 'browser_gps' | 'ip' | 'zip' | 'address' | 'manual';
+    geolocation_accuracy?: number;
+}
+interface ListResponse<T> {
+    object: 'list';
+    data: T[];
+    has_more: boolean;
+    cursors?: {
+        before?: string;
+        after?: string;
+    };
+    url?: string;
+}
+interface WhaleStorefrontConfig {
+    /** Store UUID */
+    storeId: string;
+    /** API key (wk_live_... or wk_test_...) */
+    apiKey: string;
+    /** Gateway base URL. Defaults to https://whale-gateway.fly.dev */
+    gatewayUrl?: string;
+    /** Client-side proxy path. Defaults to /api/gw */
+    proxyPath?: string;
+    /** Media signing secret for image/video proxy */
+    mediaSigningSecret?: string;
+    /** Supabase host for media URL detection */
+    supabaseHost?: string;
+    /** localStorage key prefix. Defaults to "whale" */
+    storagePrefix?: string;
+    /** Analytics session TTL in ms. Defaults to 30 minutes */
+    sessionTtl?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * Master toggle for all tracking (analytics, pixels, behavioral).
+     * When false every tracking call is a no-op.
+     * Defaults to true; can also be set via NEXT_PUBLIC_TRACKING_ENABLED env var.
+     */
+    trackingEnabled?: boolean;
+    /**
+     * Fraction of sessions that record full behavioral replays (0 – 1).
+     * 0 = never, 1 = every session. Defaults to 0.1 (10 %).
+     * Can also be set via NEXT_PUBLIC_RECORDING_RATE env var.
+     */
+    recordingRate?: number;
+}
+type EventType = 'page_view' | 'product_view' | 'add_to_cart' | 'remove_from_cart' | 'begin_checkout' | 'purchase' | 'category_view' | 'search' | 'lead' | 'cta_click';
+interface QRLandingPage {
+    title: string | null;
+    description: string | null;
+    image_url: string | null;
+    cta_text: string | null;
+    cta_url: string | null;
+    background_color: string | null;
+    text_color: string | null;
+    layout: string | null;
+    theme: string | null;
+    video_url: string | null;
+    gallery_urls: string[] | null;
+}
+interface QRLandingStore {
+    id: string;
+    name: string;
+    logo_url: string | null;
+    banner_url: string | null;
+    tagline: string | null;
+    brand_colors: Record<string, string> | null;
+    theme: Record<string, unknown> | null;
+}
+interface QRLandingData {
+    object: 'qr_landing_page';
+    qr_code: {
+        id: string;
+        code: string;
+        name: string;
+        type: string;
+        destination_url: string;
+        landing_page: QRLandingPage;
+        brand_color: string | null;
+        logo_url: string | null;
+        campaign_name: string | null;
+        tags: string[] | null;
+    };
+    store: QRLandingStore | null;
+    product: Record<string, unknown> | null;
+    coa: {
+        url: string;
+        viewer_url?: string | null;
+        document_name: string;
+    } | null;
+    landing_page: LandingPageConfig | null;
+}
+interface LandingSection {
+    id: string;
+    type: 'hero' | 'collage_hero' | 'text' | 'image' | 'video' | 'gallery' | 'cta' | 'stats' | 'product_card' | 'coa_viewer' | 'social_links' | 'divider' | 'lead_capture' | 'testimonials' | 'value_stack' | 'faq' | 'trust_badges' | 'countdown' | 'custom';
+    content: Record<string, unknown>;
+    order: number;
+    config?: Record<string, unknown>;
+}
+interface LandingPageConfig {
+    id: string;
+    slug: string;
+    name: string;
+    status: string;
+    layout: string;
+    theme: string;
+    sections: LandingSection[];
+    background_color: string | null;
+    text_color: string | null;
+    accent_color: string | null;
+    font_family: string | null;
+    custom_css: string | null;
+    page_title: string | null;
+    og_title: string | null;
+    og_description: string | null;
+    og_image_url: string | null;
+    total_views: number;
+    unique_views: number;
+}
+interface LandingPageRenderData {
+    object: 'landing_page';
+    landing_page: LandingPageConfig;
+    store: QRLandingStore | null;
+    product: Record<string, unknown> | null;
+    coa: {
+        url: string;
+        viewer_url?: string | null;
+        document_name: string;
+    } | null;
+}
+interface ReferralEnrollment {
+    object: 'referral_enrollment';
+    affiliate_id: string;
+    referral_code: string;
+    share_url: string;
+    qr_code_id: string;
+    wallet_pass_id: string;
+}
+interface ReferralStatus {
+    object: 'referral_status';
+    enrolled: boolean;
+    referral_code: string | null;
+    share_url: string | null;
+    total_referrals: number;
+    pending_referrals: number;
+    points_earned: number;
+    wallet_pass_id: string | null;
+    referred_by: {
+        affiliate_id: string;
+        referral_code: string;
+        referrer_name: string;
+    } | null;
+}
+
+/**
+ * Extended query methods and static utilities for WhaleClient.
+ * Extracted from client.ts to keep the core under 300 lines.
+ */
+
+/**
+ * Base64url-encode a URL string (works in both Node and browser).
+ */
+declare function encodeBase64Url(url: string): string;
+/**
+ * Quad-FNV (128-bit) media signing — matches gateway's media-signature.ts.
+ */
+declare function signMedia(signingSecret: string, encodedUrl: string, w: string, q: string, f: string): string;
+
+declare class WhaleClient {
+    readonly storeId: string;
+    readonly apiKey: string;
+    readonly gatewayUrl: string;
+    readonly proxyPath: string;
+    private _sessionToken;
+    constructor(config: WhaleStorefrontConfig);
+    setSessionToken(token: string | null): void;
+    getSessionToken(): string | null;
+    private get baseUrl();
+    private request;
+    listProducts(params?: {
+        limit?: number;
+        starting_after?: string;
+        status?: string;
+    }): Promise<ListResponse<Product>>;
+    getProduct(id: string): Promise<Product>;
+    getAllProducts(options?: {
+        status?: string;
+        maxPages?: number;
+        revalidate?: number;
+        filter?: (product: Product) => boolean;
+    }): Promise<Product[]>;
+    createCart(customerEmail?: string): Promise<Cart>;
+    getCart(cartId: string): Promise<Cart>;
+    addToCart(cartId: string, productId: string, quantity: number, options?: {
+        tier?: string;
+        unitPrice?: number;
+    }): Promise<CartItem>;
+    updateCartItem(cartId: string, itemId: string, quantity: number): Promise<Cart>;
+    removeCartItem(cartId: string, itemId: string): Promise<void>;
+    checkout(cartId: string, customerEmail?: string, payment?: PaymentData, referralCode?: string): Promise<Order>;
+    findCustomer(query: string): Promise<Customer[]>;
+    getCustomer(id: string): Promise<Customer>;
+    createCustomer(data: {
+        first_name: string;
+        last_name: string;
+        email: string;
+        phone?: string;
+    }): Promise<Customer>;
+    updateProfile(customerId: string, data: {
+        first_name: string;
+        last_name: string;
+        phone?: string;
+        date_of_birth?: string;
+    }): Promise<Customer>;
+    listOrders(params?: {
+        customer_id?: string;
+        limit?: number;
+        starting_after?: string;
+    }): Promise<ListResponse<Order>>;
+    getOrder(id: string): Promise<Order>;
+    getCustomerOrders(customerId: string): Promise<Order[]>;
+    sendCode(email: string): Promise<SendCodeResponse>;
+    verifyCode(email: string, code: string): Promise<VerifyCodeResponse>;
+    getCustomerAnalytics(customerId: string, customerName?: string): Promise<CustomerAnalytics | null>;
+    listLocations(): Promise<ListResponse<Location>>;
+    getCOAEmbedUrl(productId: string): string;
+    fetchStorefrontConfig(): Promise<StorefrontConfig>;
+    /** Fetch QR landing page data (public, no auth needed). */
+    fetchQRLandingData(code: string): Promise<QRLandingData>;
+    /** Fetch landing page data by slug (public, no auth needed). */
+    fetchLandingPage(slug: string): Promise<LandingPageRenderData>;
+    createSession(params: {
+        visitor_id?: string;
+        user_agent?: string;
+        referrer?: string;
+        page_url?: string;
+        device?: string;
+        utm_source?: string;
+        utm_medium?: string;
+        utm_campaign?: string;
+        utm_content?: string;
+        utm_term?: string;
+        gclid?: string;
+        fbclid?: string;
+        latitude?: number;
+        longitude?: number;
+        geolocation_source?: 'browser_gps' | 'ip' | 'zip' | 'address' | 'manual';
+        geolocation_accuracy?: number;
+    }): Promise<StorefrontSession>;
+    updateSession(sessionId: string, params: {
+        last_active_at?: string;
+        customer_id?: string;
+        customer_first_name?: string;
+        customer_last_name?: string;
+        cart_id?: string;
+        cart_item_count?: number;
+        cart_total?: number;
+        order_id?: string;
+        fingerprint_id?: string;
+        status?: string;
+        current_page?: string;
+        latitude?: number;
+        longitude?: number;
+        geolocation_source?: 'browser_gps' | 'ip' | 'zip' | 'address' | 'manual';
+        geolocation_accuracy?: number;
+    }): Promise<StorefrontSession>;
+    trackEvent(params: {
+        session_id: string;
+        event_type: EventType;
+        event_data?: Record<string, unknown>;
+        visitor_id?: string;
+    }): Promise<void>;
+    createCheckoutSession(params: {
+        cart_id: string;
+        customer_email?: string;
+        shipping_address?: Address;
+        billing_address?: Address;
+        shipping_method_id?: string;
+        coupon_code?: string;
+        referral_code?: string;
+        loyalty_reward_id?: string;
+        selected_product_id?: string;
+        visitor_id?: string;
+        session_id?: string;
+    }): Promise<CheckoutSession>;
+    getCheckoutSession(sessionId: string): Promise<CheckoutSession>;
+    updateCheckoutSession(sessionId: string, params: {
+        customer_email?: string;
+        shipping_address?: Address;
+        billing_address?: Address;
+        shipping_method_id?: string;
+        coupon_code?: string;
+    }): Promise<CheckoutSession>;
+    completeCheckout(sessionId: string, payment?: PaymentData, opts?: {
+        loyalty_reward_id?: string;
+        selected_product_id?: string;
+    }): Promise<Order>;
+    searchProducts(params: {
+        query: string;
+        category_id?: string;
+        min_price?: number;
+        max_price?: number;
+        sort_by?: string;
+        sort_order?: 'asc' | 'desc';
+        limit?: number;
+        starting_after?: string;
+    }): Promise<ListResponse<Product>>;
+    listCategories(): Promise<ListResponse<Category>>;
+    getCategory(id: string): Promise<Category>;
+    getLoyaltyAccount(customerId: string): Promise<LoyaltyAccount>;
+    listLoyaltyRewards(): Promise<ListResponse<LoyaltyReward>>;
+    listLoyaltyTransactions(customerId: string, params?: {
+        limit?: number;
+        starting_after?: string;
+    }): Promise<ListResponse<LoyaltyTransaction>>;
+    listLoyaltyProducts(params: {
+        category: string;
+        location_id: string;
+        tier?: string;
+    }): Promise<ListResponse<Product>>;
+    redeemLoyaltyReward(customerId: string, rewardId: string): Promise<{
+        success: boolean;
+        points_remaining: number;
+    }>;
+    listProductReviews(productId: string, params?: {
+        limit?: number;
+        starting_after?: string;
+        sort_by?: 'created_at' | 'rating';
+        sort_order?: 'asc' | 'desc';
+    }): Promise<ListResponse<Review> & {
+        summary?: ReviewSummary;
+    }>;
+    submitReview(productId: string, data: {
+        rating: number;
+        title?: string;
+        body?: string;
+        customer_name?: string;
+    }): Promise<Review>;
+    listWishlistItems(customerId: string): Promise<ListResponse<WishlistItem>>;
+    addWishlistItem(customerId: string, productId: string): Promise<WishlistItem>;
+    removeWishlistItem(customerId: string, productId: string): Promise<void>;
+    getRecommendations(params?: {
+        product_id?: string;
+        customer_id?: string;
+        limit?: number;
+        type?: 'similar' | 'frequently_bought_together' | 'personalized';
+    }): Promise<{
+        data: Recommendation[];
+    }>;
+    getLocation(id: string): Promise<Location>;
+    listShippingMethods(): Promise<ListResponse<ShippingMethod>>;
+    calculateShippingRates(params: {
+        cart_id: string;
+        shipping_address: Address;
+    }): Promise<{
+        data: ShippingRate[];
+    }>;
+    validateDeal(code: string, params?: {
+        cart_id?: string;
+    }): Promise<DealValidation>;
+    applyDeal(cartId: string, code: string): Promise<Cart>;
+    removeDeal(cartId: string): Promise<Cart>;
+    /** @deprecated Use validateDeal instead */
+    validateCoupon(code: string, params?: {
+        cart_id?: string;
+    }): Promise<DealValidation>;
+    /** @deprecated Use applyDeal instead */
+    applyCoupon(cartId: string, code: string): Promise<Cart>;
+    /** @deprecated Use removeDeal instead */
+    removeCoupon(cartId: string): Promise<Cart>;
+    enrollReferral(customerId: string): Promise<ReferralEnrollment>;
+    getReferralStatus(customerId: string): Promise<ReferralStatus>;
+    attributeReferral(customerId: string, referralCode: string): Promise<{
+        success: boolean;
+        affiliate_id?: string;
+        error?: string;
+    }>;
+    static encodeBase64Url: typeof encodeBase64Url;
+    static signMedia: typeof signMedia;
+}
+
+export { type Address as A, type StorefrontSession as B, type Cart as C, type DealValidation as D, type EventType as E, type WhaleStorefrontConfig as F, type WishlistItem as G, type ReferralStatus as H, type ReferralEnrollment as I, type LandingPageConfig as L, type Order as O, type PaymentData as P, type QRLandingData as Q, type Recommendation as R, type SendCodeResponse as S, type TaxBreakdown as T, type VerifyCodeResponse as V, WhaleClient as W, type CartItem as a, type Category as b, type CategoryTreeNode as c, type CheckoutSession as d, type CouponValidation as e, type Customer as f, type CustomerAnalytics as g, type LandingPageRenderData as h, type LandingSection as i, type ListResponse as j, type Location as k, type LoyaltyAccount as l, type LoyaltyReward as m, type LoyaltyTransaction as n, type OrderItem as o, type PixelConfig as p, type PricingTier as q, type Product as r, type ProductVariation as s, type QRLandingPage as t, type QRLandingStore as u, type Review as v, type ReviewSummary as w, type ShippingMethod as x, type ShippingRate as y, type StorefrontConfig as z };