@shoppexio/storefront 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,5 +1,7 @@
+import { createApiClient } from '@shoppex/contracts';
 import { NavigationMenuSlot } from '@shoppex/contracts/navigation';
 export { NavigationMenuSlot } from '@shoppex/contracts/navigation';
+import * as src from 'src';
 
 /**
  * SDK Configuration Types
@@ -16,6 +18,7 @@ interface ShoppexInitOptions {
     currency?: string;
     apiBaseUrl?: string;
     checkoutBaseUrl?: string;
+    shopId?: string;
 }
 
 /**
@@ -49,6 +52,7 @@ interface Shop {
     average_score?: number | null;
     rating?: number | null;
     products_sold_count?: number;
+    customers_count?: number;
     hide_products_sold?: boolean;
     currency: string;
     tos_enabled?: boolean;
@@ -76,6 +80,18 @@ interface Shop {
     builder_settings?: Record<string, unknown> | null;
     feedback?: ShopFeedback;
     trusted_checks?: TrustedChecks | null;
+    available_gateways?: string[];
+    reward_program_summary?: RewardProgramSummary | null;
+}
+interface RewardProgramTeaserItem {
+    trigger_type: RewardReason;
+    action_type: RewardActionType;
+    label: string;
+}
+interface RewardProgramSummary {
+    enabled: boolean;
+    headline: string;
+    items: RewardProgramTeaserItem[];
 }
 interface ShopTheme {
     primary_color?: string;
@@ -160,6 +176,7 @@ interface Product {
     feedbacks?: Feedback[];
     feedback?: ProductFeedback;
     cdn_image_url?: string;
+    detail_image_url?: string | null;
     recurring_interval?: string | null;
     recurring_interval_count?: number | null;
     trial_period?: number | null;
@@ -189,7 +206,11 @@ interface ProductFeedback {
         message: string | null;
         reply: string | null;
         created_at: string | null;
+        createdAt?: string | null;
         updated_at: string | null;
+        updatedAt?: string | null;
+        is_automated?: boolean;
+        isAutomated?: boolean;
     }>;
 }
 interface ProductImage {
@@ -203,6 +224,16 @@ interface ProductVariant {
     title: string;
     price?: number;
     stock?: number;
+    quantity_min?: number;
+    quantity_max?: number;
+    quantityMin?: number;
+    quantityMax?: number;
+    image_id?: string | null;
+    imageId?: string | null;
+    cloudflare_image_id?: string | null;
+    cloudflareImageId?: string | null;
+    image_url?: string | null;
+    imageUrl?: string | null;
 }
 interface ProductAddon {
     id: string;
@@ -216,6 +247,17 @@ interface PriceVariant {
     label?: string;
     title?: string;
     price: number;
+    stock?: number;
+    quantity_min?: number;
+    quantity_max?: number;
+    quantityMin?: number;
+    quantityMax?: number;
+    image_id?: string | null;
+    imageId?: string | null;
+    cloudflare_image_id?: string | null;
+    cloudflareImageId?: string | null;
+    image_url?: string | null;
+    imageUrl?: string | null;
 }
 interface CustomFieldDefinition {
     id: string;
@@ -227,10 +269,19 @@ interface CustomFieldDefinition {
 interface Feedback {
     id: string;
     rating: number;
+    score?: number;
     author?: string;
+    customer_name?: string;
     comment?: string;
+    message?: string | null;
+    reply?: string | null;
     is_automated?: boolean;
+    isAutomated?: boolean;
+    product_id?: string | null;
+    product_title?: string | null;
+    cloudflare_image_id?: string | null;
     created_at: string;
+    updated_at?: string | number | null;
 }
 interface ProductBundle {
     id?: string;
@@ -238,7 +289,13 @@ interface ProductBundle {
     title?: string;
     discount_type?: 'PERCENTAGE' | 'FIXED';
     discount_amount?: number;
-    products?: Product[];
+    products?: ProductBundleProduct[];
+}
+interface ProductBundleProduct {
+    id?: string;
+    uniqid: string;
+    title?: string | null;
+    default_variant_id?: string;
 }
 interface ProductFaq {
     id?: string;
@@ -270,6 +327,7 @@ interface Invoice {
     gateway?: string;
     products: InvoiceProduct[];
     created_at: string;
+    rewards?: BuyerRewards | null;
 }
 interface InvoiceProduct {
     product_id: string;
@@ -277,10 +335,56 @@ interface InvoiceProduct {
     quantity: number;
     price: number;
 }
+type RewardActionType = 'WALLET_CREDIT' | 'COUPON';
+type RewardGrantStatus = 'PENDING' | 'FULFILLED' | 'FAILED' | 'REVOKED';
+type RewardReason = 'ORDER_COMPLETED' | 'ORDER_COUNT_REACHED' | 'SPEND_AMOUNT_REACHED' | 'POSITIVE_REVIEW_LEFT' | 'FIRST_PURCHASE_COMPLETED';
+interface BuyerRewardActivityItem {
+    id: string;
+    type: RewardActionType;
+    status: RewardGrantStatus;
+    amount: string | null;
+    currency: string | null;
+    coupon_code: string | null;
+    reason: RewardReason;
+    trigger_reference_type: string;
+    trigger_reference_id: string;
+    created_at: number;
+    fulfilled_at: number | null;
+    expires_at: number | null;
+}
+interface BuyerRewards {
+    summary: {
+        available: string;
+        pending: string;
+        lifetime_earned: string;
+        redeemed: string | null;
+        currency: string;
+    };
+    activity: BuyerRewardActivityItem[];
+    earned_after_invoice: BuyerRewardActivityItem[];
+    pending_after_invoice: BuyerRewardActivityItem[];
+}
 interface CouponValidation {
     valid: boolean;
     discount?: number;
     discount_type?: 'percentage' | 'fixed';
+    source?: 'COUPON' | 'AFFILIATE';
+    product_restricted?: boolean;
+    variant_restricted?: boolean;
+    restriction_scope?: 'all' | 'products' | 'variants' | 'products_and_variants';
+    allowed_product_ids?: string[];
+    allowed_variant_ids?: string[];
+    message?: string;
+}
+interface CouponValidationOptions {
+    productId?: string;
+    variantId?: string;
+}
+interface AffiliateValidation {
+    valid: boolean;
+    affiliate_code: string | null;
+    discount_active: boolean;
+    discount_percent: number;
     message?: string;
 }
 interface ProductGroup {
@@ -309,11 +413,16 @@ interface Category {
     image_storage?: string | null;
     cloudflare_image_id?: string | null;
     cdn_image_url?: string | null;
+    product_uniqids?: string[];
     products_bound?: Product[];
     products_count?: number;
     groups_bound?: ProductGroup[];
     groups_count?: number;
 }
+interface CursorPagination {
+    next_cursor: string | null;
+    has_more: boolean;
+}
 interface StorefrontAnnouncementBarAddon {
     id: string;
     type: 'announcement_bar';
@@ -420,20 +529,26 @@ interface StorefrontCouponPopupModalAddon {
         background_color: string;
         text_color: string;
         accent_color: string;
+        hero_image_url?: string | null;
+        discount_display?: string | null;
+        expires_at?: string | null;
     };
 }
 type StorefrontAddon = StorefrontAnnouncementBarAddon | StorefrontCountdownBarAddon | StorefrontPromoInfoCardAddon | StorefrontRecentPurchasePopupAddon | StorefrontCouponPopupModalAddon;
 interface StorefrontAddonBootstrap {
     items: StorefrontAddon[];
 }
-type StorefrontItem = (Product & {
-    item_type: 'PRODUCT';
-}) | (ProductGroup & {
-    item_type: 'GROUP';
-});
+type StorefrontItem = {
+    item_type: 'PRODUCT' | 'GROUP';
+    uniqid: string;
+    sort_priority?: number | null;
+    title?: string | null;
+    name?: string | null;
+};
 interface StorefrontData {
     shop: Shop;
     products: Product[];
+    products_pagination?: CursorPagination | null;
     groups: ProductGroup[];
     items: StorefrontItem[];
     categories: Category[];
@@ -457,6 +572,7 @@ interface Menu {
     shop_id: string;
     title: string;
     slot?: NavigationMenuSlot | null;
+    item_count?: number | null;
     items?: MenuItem[];
     created_at: number;
     updated_at: number;
@@ -468,12 +584,13 @@ interface MenuItem {
     page_id: string | null;
     title: string;
     url?: string | null;
-    link_type?: 'link' | 'page';
+    link_type?: 'LINK' | 'PAGE' | 'link' | 'page' | null;
     target?: '_self' | '_blank' | null;
     sort_order: number;
     page_slug: string | null;
     created_at: number;
     updated_at: number;
+    children?: MenuItem[];
 }
 
 /**
@@ -514,6 +631,53 @@ interface CartPayload {
     items: CartItem[];
     coupon?: string;
 }
+interface CartAppliedDiscount {
+    source: 'AUTOMATIC_PRODUCT_DEAL' | 'BUNDLE_DEAL' | 'COUPON';
+    source_id: string | null;
+    source_uniqid: string | null;
+    label: string;
+    amount: string;
+}
+interface EligibleCartDeal {
+    source?: 'AUTOMATIC_PRODUCT_DEAL';
+    deal_id: string;
+    deal_uniqid: string;
+    product_id: string;
+    product_uniqid: string | null;
+    label: string;
+    missing_quantity: number;
+    required_quantity: number;
+}
+interface EligibleBundleDealProduct {
+    product_id: string;
+    product_uniqid: string;
+    title: string;
+    quantity: number;
+    price: string;
+    currency: string;
+    default_variant_id: string;
+}
+interface EligibleBundleDeal {
+    source: 'BUNDLE_DEAL';
+    bundle_id: string;
+    bundle_uniqid: string;
+    label: string;
+    discount_type: 'PERCENTAGE' | 'FIXED';
+    discount_amount: string;
+    missing_products: EligibleBundleDealProduct[];
+    products: EligibleBundleDealProduct[];
+}
+interface CartQuote {
+    subtotal: string;
+    discount: string;
+    total: string;
+    currency: string;
+    applied_discounts: CartAppliedDiscount[];
+    automatic_product_deals: Array<Record<string, unknown>>;
+    bundle_deals: Array<Record<string, unknown>>;
+    eligible_deals: EligibleCartDeal[];
+    eligible_bundle_deals: EligibleBundleDeal[];
+}
 interface CartMetadata {
     created_at: number;
     last_modified: number;
@@ -538,6 +702,28 @@ interface CartStats {
 declare function getConfig(): ShoppexConfig;
 declare function isInitialized(): boolean;
 
+/**
+ * Typed OpenAPI client factory.
+ *
+ * Surfaces the generated `createApiClient` from `@shoppex/contracts` with the
+ * SDK's configured `apiBaseUrl`. This lets consumers of `@shoppexio/storefront`
+ * call any public Dev API endpoint with full end-to-end types without
+ * rebuilding a client from scratch.
+ *
+ * Prefer the high-level modules (`shoppex.getProducts()` etc.) for common
+ * read flows — they handle caching, pagination defaults, and storefront
+ * scoping. Drop down to `shoppex.client()` only when you need an endpoint
+ * the high-level API does not cover yet.
+ */
+
+type ApiClient = ReturnType<typeof createApiClient>;
+/**
+ * Return a typed OpenAPI client bound to the SDK's configured API base URL.
+ * The client is cached per base URL and recreated when the SDK is re-initialized
+ * against a different host.
+ */
+declare function getTypedClient(token?: string): ApiClient;
+
 /**
  * SDK Error Classes
  */
@@ -560,6 +746,19 @@ declare class CartError extends ShoppexError {
     constructor(message: string);
 }
 
+interface StorefrontCustomField {
+    name: string;
+    type: string;
+    required: boolean;
+    defaultValue: string;
+    placeholder: string;
+    regex?: string;
+}
+declare function normalizeStorefrontCustomFields(raw: unknown): StorefrontCustomField[];
+declare function isStorefrontCheckboxCustomFieldValueChecked(value: string | undefined): boolean;
+declare function validateStorefrontCustomFieldValue(field: StorefrontCustomField, value: string): string | null;
+declare function buildStorefrontCustomFieldPayload(fields: StorefrontCustomField[], values: Record<string, string>): Record<string, string>;
+
 /**
  * Theme configuration types (framework agnostic)
  */
@@ -627,6 +826,28 @@ interface SectionDefinition {
     icon?: string;
     settings: Record<string, SettingField>;
 }
+interface BlockDefinition {
+    name: string;
+    description?: string;
+    icon?: string;
+    settings: Record<string, SettingField>;
+    allowedPages?: string[];
+    maxPerPage?: number;
+}
+interface BlockInstance {
+    id: string;
+    type: string;
+    visible?: boolean;
+    settings?: Record<string, SettingValue>;
+}
+interface PageLayout {
+    blocks: BlockInstance[];
+}
+interface ThemeBlockManifest {
+    pages: string[];
+    blocks: Record<string, BlockDefinition>;
+    defaultLayouts?: Record<string, PageLayout>;
+}
 interface ThemeConfig {
     id: string;
     name: string;
@@ -636,6 +857,9 @@ interface ThemeConfig {
     preview?: string;
     settings: Record<string, Record<string, SettingField>>;
     sections: Record<string, SectionDefinition>;
+    blocks?: Record<string, BlockDefinition>;
+    pageLayouts?: Record<string, PageLayout>;
+    builder?: ThemeBlockManifest;
 }
 type SettingValue = string | number | boolean | null | string[] | Record<string, unknown>;
 type ResolvedThemeSettings = {
@@ -650,9 +874,13 @@ type ResolvedThemeSettings = {
  * API methods for store data.
  */
 
+interface GetStorefrontOptions {
+    productsLimit?: number;
+    productsCursor?: string | null;
+}
 declare function getStore(): Promise<SDKResponse<Shop>>;
 declare function resolveStoreByDomain(domain?: string, apiBaseUrl?: string): Promise<SDKResponse<Shop>>;
-declare function getStorefront(): Promise<SDKResponse<StorefrontData>>;
+declare function getStorefront(options?: GetStorefrontOptions): Promise<SDKResponse<StorefrontData>>;
 declare function getStoreLogoUrl(): Promise<string | null>;
 declare function getStoreBannerUrl(): Promise<string | null>;
 
@@ -662,22 +890,25 @@ declare function getStoreBannerUrl(): Promise<string | null>;
  * API methods for product data.
  */
 
+interface GetStorefrontProductsPageOptions {
+    cursor?: string | null;
+    limit?: number;
+}
 declare function getProducts(): Promise<SDKResponse<Product[]>>;
+declare function getStorefrontProductsPage(options?: GetStorefrontProductsPageOptions): Promise<SDKResponse<{
+    products: Product[];
+    pagination: CursorPagination | null;
+}>>;
 declare function getProduct(idOrSlug: string): Promise<SDKResponse<Product>>;
 declare function getCategories(): Promise<SDKResponse<string[]>>;
 
-/**
- * Cart Module
- *
- * localStorage-based cart with support for Shoppex features:
- * - Addons (express shipping, gift wrap, etc.)
- * - Custom Fields (engraving, gift message, etc.)
- * - Price Variants (different pricing tiers)
- */
-
+declare function getCartCoupon(): string | null;
+declare function setCartCoupon(coupon: string | null | undefined): string | null;
+declare function clearCartCoupon(): void;
 declare function getCart(): CartItem[];
 declare function getCartItemCount(): number;
 declare function addToCart(productId: string, variantId: string, quantity?: number, options?: CartAddOptions): void;
+declare function setCartItem(productId: string, variantId: string, quantity?: number, options?: CartAddOptions): void;
 declare function updateCartItem(productId: string, variantId: string, updates: Partial<Omit<CartItem, 'product_id' | 'variant_id'>>): void;
 declare function removeFromCart(productId: string, variantId: string): void;
 declare function clearCart(): void;
@@ -687,6 +918,7 @@ declare function mergeBaskets(items: CartItem[]): CartItem[];
 declare function moveBasketItem(fromProductId: string, fromVariantId: string, toProductId: string, toVariantId: string): void;
 declare function validateCartIntegrity(): boolean;
 declare function getCartStats(): CartStats;
+declare function quoteCart(coupon?: string): Promise<src.SDKResponse<CartQuote>>;
 
 /**
  * Checkout Module
@@ -694,17 +926,20 @@ declare function getCartStats(): CartStats;
  * Creates invoice via backend API and redirects to hosted checkout page.
  * All checkout flows go through: checkout.shoppex.io/invoice/{invoiceId}
  */
+
 interface CheckoutOptions {
     autoRedirect?: boolean;
     locale?: string;
     email?: string;
     coupon?: string;
     affiliateCode?: string;
+    referralCode?: string;
 }
 interface CheckoutResult {
     success: boolean;
     redirectUrl?: string;
     invoiceId?: string;
+    rewards?: BuyerRewards | null;
     message?: string;
 }
 declare function checkout(couponOrOptions?: string | CheckoutOptions, options?: CheckoutOptions): Promise<CheckoutResult>;
@@ -719,8 +954,11 @@ declare function buildCheckoutUrl(couponOrOptions?: string | CheckoutOptions, op
  */
 declare function buildCheckoutUrlSync(): never;
 
+declare function setAffiliateCode(code: string | null | undefined, ttlDays?: number): string | null;
 declare function clearAffiliateCode(): void;
 declare function getAffiliateCode(): string | null;
+declare function validateAffiliateCode(code: string): Promise<SDKResponse<AffiliateValidation>>;
+declare function applyAffiliateCode(code: string): Promise<SDKResponse<AffiliateValidation>>;
 /**
  * Capture an affiliate code from the current URL and store it for 30 days (last-click).
  *
@@ -736,7 +974,7 @@ declare function captureAffiliateFromUrl(param?: string): Promise<string | null>
  * Coupon validation before checkout.
  */
 
-declare function validateCoupon(code: string, productId?: string): Promise<SDKResponse<CouponValidation>>;
+declare function validateCoupon(code: string, productOrOptions?: string | CouponValidationOptions): Promise<SDKResponse<CouponValidation>>;
 
 /**
  * Reviews Module
@@ -825,7 +1063,7 @@ declare function mergeSettings(defaults: ResolvedThemeSettings, overrides: Parti
  *
  * Usage:
  * ```html
- * <script src="https://cdn.shoppex.io/sdk/v1/shoppex.min.js"></script>
+ * <script src="https://cdn.shoppex.io/sdk/v0.3/shoppex.umd.js"></script>
  * <script>
  *   shoppex.init('my-store');
  *
@@ -850,17 +1088,23 @@ declare const shoppex: {
     init: typeof init;
     isInitialized: typeof isInitialized;
     getConfig: typeof getConfig;
+    client: typeof getTypedClient;
     getStore: typeof getStore;
     getStorefront: typeof getStorefront;
     getStoreLogoUrl: typeof getStoreLogoUrl;
     getStoreBannerUrl: typeof getStoreBannerUrl;
     resolveStoreByDomain: typeof resolveStoreByDomain;
     getProducts: typeof getProducts;
+    getStorefrontProductsPage: typeof getStorefrontProductsPage;
     getProduct: typeof getProduct;
     getCategories: typeof getCategories;
     getCart: typeof getCart;
     getCartItemCount: typeof getCartItemCount;
+    getCartCoupon: typeof getCartCoupon;
+    setCartCoupon: typeof setCartCoupon;
+    clearCartCoupon: typeof clearCartCoupon;
     addToCart: typeof addToCart;
+    setCartItem: typeof setCartItem;
     updateCartItem: typeof updateCartItem;
     removeFromCart: typeof removeFromCart;
     clearCart: typeof clearCart;
@@ -870,11 +1114,15 @@ declare const shoppex: {
     moveBasketItem: typeof moveBasketItem;
     getCartStats: typeof getCartStats;
     validateCartIntegrity: typeof validateCartIntegrity;
+    quoteCart: typeof quoteCart;
     checkout: typeof checkout;
     buildCheckoutUrl: typeof buildCheckoutUrl;
     buildCheckoutUrlSync: typeof buildCheckoutUrlSync;
     captureAffiliateFromUrl: typeof captureAffiliateFromUrl;
+    validateAffiliateCode: typeof validateAffiliateCode;
+    applyAffiliateCode: typeof applyAffiliateCode;
     getAffiliateCode: typeof getAffiliateCode;
+    setAffiliateCode: typeof setAffiliateCode;
     clearAffiliateCode: typeof clearAffiliateCode;
     validateCoupon: typeof validateCoupon;
     getShopReviews: typeof getShopReviews;
@@ -898,4 +1146,4 @@ declare const shoppex: {
     mergeSettings: typeof mergeSettings;
 };
 
-export { type ApiResponse, type CartAddOptions, type CartAddon, CartError, type CartItem, type CartMetadata, type CartPayload, type CartStats, type Category, type CouponValidation, type CustomFieldDefinition, type Feedback, type Invoice, type InvoiceProduct, type Menu, type MenuItem, NetworkError, NotInitializedError, type Page, type PriceVariant, type Product, type ProductAddon, type ProductBundle, type ProductCategory, type ProductFaq, type ProductFeedback, type ProductGroup, type ProductImage, type ProductVariant, type ResolvedThemeSettings, type SDKResponse, type SectionDefinition, type SettingField, type Shop, type ShopFeedback, type ShopTheme, type ShoppexConfig, ShoppexError, type ShoppexInitOptions, type StorefrontAddon, type StorefrontAddonBootstrap, type StorefrontAnnouncementBarAddon, type StorefrontCountdownBarAddon, type StorefrontCouponPopupModalAddon, type StorefrontData, type StorefrontItem, type StorefrontPromoInfoCardAddon, type StorefrontRecentPurchasePopupAddon, type Subscription, type SubscriptionFlags, type SubscriptionInterval, type ThemeConfig, type TrustedChecks, ValidationError, shoppex as default, fetchPublishedThemeSettings, getMenuBySlot, getMenuByTitle, getMenuSlotTitles, mergeSettings, resolveDefaults, shoppex, trackPageView };
+export { type AffiliateValidation, type ApiResponse, type BlockDefinition, type BlockInstance, type BuyerRewardActivityItem, type BuyerRewards, type CartAddOptions, type CartAddon, type CartAppliedDiscount, CartError, type CartItem, type CartMetadata, type CartPayload, type CartQuote, type CartStats, type Category, type CouponValidation, type CouponValidationOptions, type CursorPagination, type CustomFieldDefinition, type EligibleBundleDeal, type EligibleBundleDealProduct, type EligibleCartDeal, type Feedback, type Invoice, type InvoiceProduct, type Menu, type MenuItem, NetworkError, NotInitializedError, type Page, type PageLayout, type PriceVariant, type Product, type ProductAddon, type ProductBundle, type ProductBundleProduct, type ProductCategory, type ProductFaq, type ProductFeedback, type ProductGroup, type ProductImage, type ProductVariant, type ResolvedThemeSettings, type RewardActionType, type RewardGrantStatus, type RewardProgramSummary, type RewardProgramTeaserItem, type RewardReason, type SDKResponse, type SectionDefinition, type SettingField, type Shop, type ShopFeedback, type ShopTheme, type ShoppexConfig, ShoppexError, type ShoppexInitOptions, type StorefrontAddon, type StorefrontAddonBootstrap, type StorefrontAnnouncementBarAddon, type StorefrontCountdownBarAddon, type StorefrontCouponPopupModalAddon, type StorefrontCustomField, type StorefrontData, type StorefrontItem, type StorefrontPromoInfoCardAddon, type StorefrontRecentPurchasePopupAddon, type Subscription, type SubscriptionFlags, type SubscriptionInterval, type ThemeBlockManifest, type ThemeConfig, type TrustedChecks, ValidationError, buildStorefrontCustomFieldPayload, shoppex as default, fetchPublishedThemeSettings, getMenuBySlot, getMenuByTitle, getMenuSlotTitles, isStorefrontCheckboxCustomFieldValueChecked, mergeSettings, normalizeStorefrontCustomFields, resolveDefaults, shoppex, trackPageView, validateStorefrontCustomFieldValue };