@numueg/theme-sdk 0.12.0 → 0.13.0

package/dist/index.d.mts

@@ -1,10 +1,10 @@
-import { i as Store, e as Product, b as Collection, c as Customer, P as Page, M as Metafield, j as ArticleDetail, k as ArticleSummary, B as BlogSummary, S as SizeChart, g as ProductVariant, C as Cart } from './entities-1XRRUTlO.mjs';
-export { A as Address, a as CartItem, O as Order, d as OrderItem, f as ProductImage, l as ProductOption, h as SizeChartMode } from './entities-1XRRUTlO.mjs';
+import { i as Store, e as Product, b as Collection, c as Customer, P as Page, M as Metafield, j as ArticleDetail, k as ArticleSummary, B as BlogSummary, C as Cart, S as SizeChart, g as ProductVariant } from './entities-DRKn04q0.mjs';
+export { A as Address, a as CartItem, O as Order, d as OrderItem, f as ProductImage, l as ProductOption, h as SizeChartMode } from './entities-DRKn04q0.mjs';
 import { T as ThemeSettingsV3, c as SectionInstance, M as MountResult, B as BlockInstance, b as BlockSchema, a as BlockProps$1, f as SectionSchema, e as SectionProps$1 } from './theme-CNTB4KnU.mjs';
 export { E as ExternalThemeMetadata, h as MAX_BLOCK_DEPTH, P as PageTemplate, i as PresetBlock, S as SectionGroup, d as SectionPreset, g as SettingDefinition } from './theme-CNTB4KnU.mjs';
 export { KNOWN_SETTING_TYPES, KNOWN_TEMPLATES, REQUIRED_TEMPLATES, SDK_VERSION, THEME_CONTRACT_VERSION, ValidationIssue, ValidationResult, mergeResults, validateBuiltManifest, validateManifest, validateSectionSchema, validateSettingsAgainstSchema } from './validation.mjs';
-import { C as CartContextValue, L as LocalizationState, a as CurrencyState, T as ThemeMountContext, b as ThemeRenderArgs, M as MenuItemData } from './mount-DDFMacmj.mjs';
-export { c as CartContext, d as CartMutationResult, e as CollectionContext, f as CurrencyConfig, g as CurrencyContext, h as CustomerContext, i as LocalizationContext, N as NavigationContext, P as PageContext, j as ProductContext, S as ShopContext, k as ThemeMountPage, l as ThemeSettingsContext, m as buildThemeElement, n as mountTheme } from './mount-DDFMacmj.mjs';
+import { C as CartContextValue, L as LocalizationState, a as CurrencyState, T as ThemeMountContext, b as ThemeRenderArgs, M as MenuItemData } from './mount-BTaDtz8k.mjs';
+export { c as CartContext, d as CartMutationResult, e as CollectionContext, f as CurrencyConfig, g as CurrencyContext, h as CustomerContext, i as LocalizationContext, N as NavigationContext, P as PageContext, j as ProductContext, S as ShopContext, k as ThemeMountPage, l as ThemeSettingsContext, m as buildThemeElement, n as mountTheme } from './mount-BTaDtz8k.mjs';
 import * as react from 'react';
 import { ReactElement, ReactNode, ElementType, CSSProperties, ImgHTMLAttributes, AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, FormHTMLAttributes, ComponentType } from 'react';
 export { resolveThemeSettings } from './normalize.mjs';
@@ -926,6 +926,216 @@ interface UseCachedResourceOptions<T> {
  */
 declare function useCachedResource<T>(key: string | null | undefined, fetcher: CacheFetcher<T>, options?: UseCachedResourceOptions<T>): CachedResource<T>;
 
+/**
+ * Storefront promotion types — the shape the platform serves to every theme.
+ *
+ * Source of truth is the backend's offers-v2 engine. The host proxies it at
+ * `GET /api/storefront/promotions`, which returns the visitor's active
+ * promotions grouped by surface. Themes only ever *render* these; the engine
+ * decides what a cart costs, and the same engine runs at checkout. A theme
+ * that computes its own discount is telling the shopper a number the server
+ * will overrule.
+ *
+ * ⚠️ Every `*_cents` field here is in INTEGER CENTS, straight off the API —
+ * unlike `Cart`, which the SDK normalizes to major units. Convert with the
+ * helpers in `lib/promotions` rather than dividing ad hoc; a missed
+ * conversion is a silent 100x error.
+ */
+/** One step of a tiered "spend X, get Y%" rule. */
+interface DiscountTier {
+    threshold_cents: number;
+    percent: number;
+}
+/**
+ * The math behind a promotion. `kind` is an open string union on purpose:
+ * the platform adds kinds over time and older themes must degrade quietly
+ * rather than crash on one they've never heard of.
+ */
+interface DiscountRule {
+    kind: "percentage" | "fixed" | "free_shipping" | "bogo" | "tiered" | "multibuy" | (string & {});
+    value_cents?: number | null;
+    value_percent?: number | null;
+    min_subtotal_cents?: number | null;
+    max_discount_cents?: number | null;
+    buy_quantity?: number | null;
+    get_quantity?: number | null;
+    get_discount_percent?: number | null;
+    tiers?: DiscountTier[];
+    /** MULTIBUY: how many eligible items form one group (N). */
+    multibuy_quantity?: number | null;
+    /** MULTIBUY: the fixed total price for one complete group (P), in cents. */
+    multibuy_price_cents?: number | null;
+}
+/** A promotion resolved as active for the current visitor. */
+interface ActivePromotion {
+    promotion_id: string;
+    surface?: string;
+    priority?: number;
+    content?: Record<string, unknown>;
+    translated_content?: {
+        headline?: Record<string, string>;
+        body?: Record<string, string>;
+        [key: string]: unknown;
+    };
+    discount_rule?: DiscountRule | null;
+    coupon_code?: string | null;
+    /**
+     * Which catalog entries can take part in the rule. BOTH EMPTY (or absent,
+     * on an older backend) means the whole store qualifies.
+     *
+     * Needed so a scoped offer doesn't lie: without it a "3 for EGP 650 on
+     * scarves" offer counts every cart unit, and a shopper holding one
+     * ineligible item is told "add 2 more" and then doesn't get the discount.
+     */
+    eligible_product_ids?: string[];
+    eligible_category_ids?: string[];
+}
+/** The `/api/storefront/promotions` payload, grouped by surface. */
+interface ActivePromotionsPayload {
+    announcement_bars?: ActivePromotion[];
+    popups?: ActivePromotion[];
+    floating_widgets?: ActivePromotion[];
+    cookie_banner?: ActivePromotion | null;
+    /** Automatic (no code needed) discounts — where multibuy offers live. */
+    auto_discounts?: ActivePromotion[];
+    discount_codes_visible?: ActivePromotion[];
+}
+/**
+ * A validated multibuy offer, normalized for display.
+ *
+ * `groupPriceMajor` is in MAJOR units (EGP, not piastres) so it can go
+ * straight into `<Money>` / `formatMoney` — the conversion happened once,
+ * here, rather than in each theme.
+ */
+interface MultibuyOffer {
+    promotionId: string;
+    /** N — how many items make a group. */
+    quantity: number;
+    /** P in cents, as the engine stores it. */
+    groupPriceCents: number;
+    /** P in major units, ready to render. */
+    groupPriceMajor: number;
+    /** Merchant's bilingual headline, when they set one. */
+    headline?: Record<string, string>;
+    /** Products the offer is scoped to. Empty (with categories) = whole store. */
+    eligibleProductIds: string[];
+    /** Categories the offer is scoped to. Empty (with products) = whole store. */
+    eligibleCategoryIds: string[];
+    /** True when the offer applies to the entire catalogue. */
+    isStoreWide: boolean;
+    raw: ActivePromotion;
+}
+/** Where a shopper stands against one multibuy offer. */
+interface OfferProgress {
+    /** Eligible units currently in the cart. */
+    unitsInCart: number;
+    /** How many more units to complete the next group. 0 = just unlocked. */
+    unitsNeeded: number;
+    /** Complete groups the cart has already earned. */
+    groupsUnlocked: number;
+    /**
+     * What the engine says this offer actually saved, in MAJOR units. Read
+     * from `cart.applied_promotions` — never recomputed, so the number the
+     * shopper reads is the number they are charged.
+     */
+    savingMajor: number;
+}
+
+/**
+ * The store's active promotions for the current visitor.
+ *
+ * Reads the host proxy `GET /api/storefront/promotions` (never NUMU-api
+ * directly — the host owns credentials, caching and the store resolution).
+ * The backend groups by surface; the host already renders announcement bars,
+ * popups, the cookie banner and floating widgets in the shell, so what a
+ * theme normally wants is `auto_discounts` — the offers that price the cart
+ * with no code to type.
+ *
+ * SSR-safe: `useCachedResource` doesn't fetch during server render, so this
+ * resolves on hydrate. Sections must therefore tolerate a null first pass —
+ * render nothing (or a skeleton) rather than assuming data on first paint.
+ *
+ * Returns `null` on any miss (offline, 404, flag off). That is deliberate:
+ * a promotions outage should make an offer banner disappear, never break the
+ * page it sits on.
+ *
+ * @param page   page path used for page-targeted promotions (default "/")
+ * @param locale "ar" | "en" — selects the translated content
+ */
+declare function useActivePromotions(page?: string, locale?: string): ActivePromotionsPayload | null;
+
+/**
+ * Pure helpers for rendering platform promotions in a theme.
+ *
+ * These are headless by design — data and logic only, zero markup and zero
+ * styling — so every theme keeps its own look while sharing one correct
+ * implementation of the fiddly parts (unit counting, group math, the
+ * cents→major boundary).
+ *
+ * The hard rule these encode: **a theme never computes a discount.** The
+ * engine prices the cart and reports what it saved; helpers here only
+ * describe progress toward an offer and format what the engine already
+ * decided. Anything else eventually renders a number the server won't honour.
+ */
+
+/**
+ * Extract the usable multibuy offers ("any N for a fixed total P").
+ *
+ * Accepts either the whole `/api/storefront/promotions` payload or just an
+ * array of promotions, so callers don't have to reach into `auto_discounts`
+ * themselves. Anything that isn't a well-formed multibuy — a kind this SDK
+ * version doesn't know, a missing N or P — is skipped rather than thrown on:
+ * a theme built before a rule kind existed must keep rendering when a
+ * merchant starts using it.
+ */
+declare function multibuyOffers(promotions: ActivePromotionsPayload | ActivePromotion[] | null | undefined): MultibuyOffer[];
+/**
+ * Does this product take part in the offer?
+ *
+ * A store-wide offer includes everything. Otherwise the product must be named
+ * directly or sit in a named category. A scoped offer over a product whose
+ * `category_id` we don't know returns false — better to under-promise than to
+ * advertise a discount the server won't apply.
+ */
+declare function offerIncludesProduct(offer: MultibuyOffer | null | undefined, product: {
+    id?: string;
+    product_id?: string;
+    category_id?: string | null;
+}): boolean;
+/**
+ * How many cart UNITS actually qualify for the offer.
+ *
+ * Units, not lines — three of one product is a valid trio, the way the engine
+ * scores it. For a scoped offer this is what the nudge must count; counting
+ * the whole cart is how a shopper gets told "add 2 more" and then doesn't get
+ * the discount.
+ */
+declare function eligibleUnitsInCart(offer: MultibuyOffer | null | undefined, cart: Cart | null | undefined): number;
+/**
+ * Where the cart stands against one multibuy offer.
+ *
+ * Counts UNITS, not lines — three of the same product is a valid trio, the
+ * same way the engine scores it. `savingMajor` is read from the cart's
+ * engine-supplied `applied_promotions`, so an unlocked offer shows the real
+ * saving and a theme can never drift from the charged amount.
+ *
+ * Scoping is handled automatically: when the offer names products or
+ * categories, only qualifying units are counted (via `eligibleUnitsInCart`).
+ * Pass `eligibleUnits` explicitly to override that — e.g. when the theme has
+ * a better source of truth than the cart lines.
+ */
+declare function offerProgress(offer: MultibuyOffer | null | undefined, cart: Cart | null | undefined, eligibleUnits?: number): OfferProgress;
+/**
+ * Should a product page advertise this offer?
+ *
+ * Only when N of this product actually costs more than the group price —
+ * otherwise the "deal" is worse than just buying them, and §5 of the offer
+ * spec forbids advertising it (the engine likewise refuses to apply it).
+ *
+ * @param unitPriceMajor the product's price in MAJOR units, as a theme has it
+ */
+declare function offerBeatsRegularPrice(offer: MultibuyOffer | null | undefined, unitPriceMajor: number | null | undefined): boolean;
+
 /**
  * useProductSizeChart — resolve the size chart to show for a product.
  *
@@ -2733,4 +2943,4 @@ declare function pickTranslations(bundle: LocaleBundle, locale: string): LocaleM
  */
 declare function buildLocaleBundle<T extends Record<string, unknown>>(modules: T): LocaleBundle;
 
-export { AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, ArticleDetail, ArticleSummary, Block, BlockInstance, BlockProps$1 as BlockProps, BlockSchema, BlogSummary, type CacheFetcher, type CacheMutator, type CachedResource, type CachedResourceState, Cart, CartContextValue, type CheckoutAddress, type CheckoutApi, type CheckoutSessionState, type CheckoutStep, Collection, CollectionCard, type CollectionCardProps, type CollectionCardSlots, CollectionProvider, type ComputedStyleTokens, CurrencyState, CurrencySwitcher, type CurrencySwitcherProps, Customer, type CustomerAddress, type CustomerAddressesState, type DefineBlockInput, type DefineSectionInput, type DefinedBlock, type DefinedSection, type DynamicResolveContext, type DynamicSourceRef, EditableImage, type EditableImageProps, EditableText, type EditableTextProps, type FocalSrcOptions, Form, type FormatMoneyOptions, type GiftCardBalance, HeroMedia, type HeroMediaProps, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, LOGO_SHAPE_OPTIONS, LOGO_SIZE_OPTIONS, Link, type ListingHeading, type ListingHeadingOptions, type LocaleBundle, type LocaleMessages, LocaleSwitcher, type LocaleSwitcherProps, Logo, type LogoProps, type LogoShape, type LogoSize, type MaybeOrderedTemplate, MenuItemData, type MetafieldOwner, Money, MountResult, type MutateOptions, NAVIGATE_EVENT, type NavigateEventDetail, type NavigationItem, type NavigationState, NuMuProvider, type OrderDetail, type OrderListEntry, type OrderListState, type OrderState, Page, type PlaceOrderResult, Product, ProductCard, type ProductCardProps, type ProductCardSlots, ProductProvider, ProductVariant, type RelatedProductsState, type ReorderResult, type ReorderSkipReason, type ReorderSkippedItem, type ResolvedSection, RichText, type RichTextProps, type SearchResults, type SearchState, Section, SectionContext, type SectionGroupInstance, SectionInstance, SectionProps$1 as SectionProps, SectionSchema, type ShippingRateOption, type ShopWithHelpers, SizeChart, Store, type ThemeEntry, ThemeMountContext, ThemeRenderArgs, ThemeSettingsV3, type UseCachedResourceOptions, type UseGiftCardBalance, type UseReorder, type UseSearchOptions, type UseShippingRatesOptions, type UseShippingRatesState, type UseVariantSelection, type WishlistItem, type WishlistState, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, centsToMajor, clearSdkSingleton, collectBlocks, collectSections, collectionHref, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, formatMoney, formatMoneyMajor, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, logoImgStyle, logoStyleTokens, majorToCents, pickTranslations, productHref, publishVariantSelection, readVariantSelection, registerReactSingleton, registerSdkSingleton, requestNavigate, resolveDynamicValue, resolveFontStack, resolveSections, resolveSettingsMap, resolveSizeChart, resolveSourcePath, sanitizeHtml, selectChromeSections, selectTemplateSections, useAnalytics, useApp, useArticle, useArticles, useBlog, useBlogs, useCachedResource, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useListingHeading, useLocale, useLocalization, useMetafield, useMetafields, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionGroup, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };
+export { type ActivePromotion, type ActivePromotionsPayload, AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, ArticleDetail, ArticleSummary, Block, BlockInstance, BlockProps$1 as BlockProps, BlockSchema, BlogSummary, type CacheFetcher, type CacheMutator, type CachedResource, type CachedResourceState, Cart, CartContextValue, type CheckoutAddress, type CheckoutApi, type CheckoutSessionState, type CheckoutStep, Collection, CollectionCard, type CollectionCardProps, type CollectionCardSlots, CollectionProvider, type ComputedStyleTokens, CurrencyState, CurrencySwitcher, type CurrencySwitcherProps, Customer, type CustomerAddress, type CustomerAddressesState, type DefineBlockInput, type DefineSectionInput, type DefinedBlock, type DefinedSection, type DiscountRule, type DiscountTier, type DynamicResolveContext, type DynamicSourceRef, EditableImage, type EditableImageProps, EditableText, type EditableTextProps, type FocalSrcOptions, Form, type FormatMoneyOptions, type GiftCardBalance, HeroMedia, type HeroMediaProps, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, LOGO_SHAPE_OPTIONS, LOGO_SIZE_OPTIONS, Link, type ListingHeading, type ListingHeadingOptions, type LocaleBundle, type LocaleMessages, LocaleSwitcher, type LocaleSwitcherProps, Logo, type LogoProps, type LogoShape, type LogoSize, type MaybeOrderedTemplate, MenuItemData, type MetafieldOwner, Money, MountResult, type MultibuyOffer, type MutateOptions, NAVIGATE_EVENT, type NavigateEventDetail, type NavigationItem, type NavigationState, NuMuProvider, type OfferProgress, type OrderDetail, type OrderListEntry, type OrderListState, type OrderState, Page, type PlaceOrderResult, Product, ProductCard, type ProductCardProps, type ProductCardSlots, ProductProvider, ProductVariant, type RelatedProductsState, type ReorderResult, type ReorderSkipReason, type ReorderSkippedItem, type ResolvedSection, RichText, type RichTextProps, type SearchResults, type SearchState, Section, SectionContext, type SectionGroupInstance, SectionInstance, SectionProps$1 as SectionProps, SectionSchema, type ShippingRateOption, type ShopWithHelpers, SizeChart, Store, type ThemeEntry, ThemeMountContext, ThemeRenderArgs, ThemeSettingsV3, type UseCachedResourceOptions, type UseGiftCardBalance, type UseReorder, type UseSearchOptions, type UseShippingRatesOptions, type UseShippingRatesState, type UseVariantSelection, type WishlistItem, type WishlistState, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, centsToMajor, clearSdkSingleton, collectBlocks, collectSections, collectionHref, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, eligibleUnitsInCart, findVariantByOptions, flattenMessages, focalSrc, formatMoney, formatMoneyMajor, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, logoImgStyle, logoStyleTokens, majorToCents, multibuyOffers, offerBeatsRegularPrice, offerIncludesProduct, offerProgress, pickTranslations, productHref, publishVariantSelection, readVariantSelection, registerReactSingleton, registerSdkSingleton, requestNavigate, resolveDynamicValue, resolveFontStack, resolveSections, resolveSettingsMap, resolveSizeChart, resolveSourcePath, sanitizeHtml, selectChromeSections, selectTemplateSections, useActivePromotions, useAnalytics, useApp, useArticle, useArticles, useBlog, useBlogs, useCachedResource, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useListingHeading, useLocale, useLocalization, useMetafield, useMetafields, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionGroup, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { i as Store, e as Product, b as Collection, c as Customer, P as Page, M as Metafield, j as ArticleDetail, k as ArticleSummary, B as BlogSummary, S as SizeChart, g as ProductVariant, C as Cart } from './entities-1XRRUTlO.js';
-export { A as Address, a as CartItem, O as Order, d as OrderItem, f as ProductImage, l as ProductOption, h as SizeChartMode } from './entities-1XRRUTlO.js';
+import { i as Store, e as Product, b as Collection, c as Customer, P as Page, M as Metafield, j as ArticleDetail, k as ArticleSummary, B as BlogSummary, C as Cart, S as SizeChart, g as ProductVariant } from './entities-DRKn04q0.js';
+export { A as Address, a as CartItem, O as Order, d as OrderItem, f as ProductImage, l as ProductOption, h as SizeChartMode } from './entities-DRKn04q0.js';
 import { T as ThemeSettingsV3, c as SectionInstance, M as MountResult, B as BlockInstance, b as BlockSchema, a as BlockProps$1, f as SectionSchema, e as SectionProps$1 } from './theme-CNTB4KnU.js';
 export { E as ExternalThemeMetadata, h as MAX_BLOCK_DEPTH, P as PageTemplate, i as PresetBlock, S as SectionGroup, d as SectionPreset, g as SettingDefinition } from './theme-CNTB4KnU.js';
 export { KNOWN_SETTING_TYPES, KNOWN_TEMPLATES, REQUIRED_TEMPLATES, SDK_VERSION, THEME_CONTRACT_VERSION, ValidationIssue, ValidationResult, mergeResults, validateBuiltManifest, validateManifest, validateSectionSchema, validateSettingsAgainstSchema } from './validation.js';
-import { C as CartContextValue, L as LocalizationState, a as CurrencyState, T as ThemeMountContext, b as ThemeRenderArgs, M as MenuItemData } from './mount-qofjiBxw.js';
-export { c as CartContext, d as CartMutationResult, e as CollectionContext, f as CurrencyConfig, g as CurrencyContext, h as CustomerContext, i as LocalizationContext, N as NavigationContext, P as PageContext, j as ProductContext, S as ShopContext, k as ThemeMountPage, l as ThemeSettingsContext, m as buildThemeElement, n as mountTheme } from './mount-qofjiBxw.js';
+import { C as CartContextValue, L as LocalizationState, a as CurrencyState, T as ThemeMountContext, b as ThemeRenderArgs, M as MenuItemData } from './mount-CLQniVfc.js';
+export { c as CartContext, d as CartMutationResult, e as CollectionContext, f as CurrencyConfig, g as CurrencyContext, h as CustomerContext, i as LocalizationContext, N as NavigationContext, P as PageContext, j as ProductContext, S as ShopContext, k as ThemeMountPage, l as ThemeSettingsContext, m as buildThemeElement, n as mountTheme } from './mount-CLQniVfc.js';
 import * as react from 'react';
 import { ReactElement, ReactNode, ElementType, CSSProperties, ImgHTMLAttributes, AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, FormHTMLAttributes, ComponentType } from 'react';
 export { resolveThemeSettings } from './normalize.js';
@@ -926,6 +926,216 @@ interface UseCachedResourceOptions<T> {
  */
 declare function useCachedResource<T>(key: string | null | undefined, fetcher: CacheFetcher<T>, options?: UseCachedResourceOptions<T>): CachedResource<T>;
 
+/**
+ * Storefront promotion types — the shape the platform serves to every theme.
+ *
+ * Source of truth is the backend's offers-v2 engine. The host proxies it at
+ * `GET /api/storefront/promotions`, which returns the visitor's active
+ * promotions grouped by surface. Themes only ever *render* these; the engine
+ * decides what a cart costs, and the same engine runs at checkout. A theme
+ * that computes its own discount is telling the shopper a number the server
+ * will overrule.
+ *
+ * ⚠️ Every `*_cents` field here is in INTEGER CENTS, straight off the API —
+ * unlike `Cart`, which the SDK normalizes to major units. Convert with the
+ * helpers in `lib/promotions` rather than dividing ad hoc; a missed
+ * conversion is a silent 100x error.
+ */
+/** One step of a tiered "spend X, get Y%" rule. */
+interface DiscountTier {
+    threshold_cents: number;
+    percent: number;
+}
+/**
+ * The math behind a promotion. `kind` is an open string union on purpose:
+ * the platform adds kinds over time and older themes must degrade quietly
+ * rather than crash on one they've never heard of.
+ */
+interface DiscountRule {
+    kind: "percentage" | "fixed" | "free_shipping" | "bogo" | "tiered" | "multibuy" | (string & {});
+    value_cents?: number | null;
+    value_percent?: number | null;
+    min_subtotal_cents?: number | null;
+    max_discount_cents?: number | null;
+    buy_quantity?: number | null;
+    get_quantity?: number | null;
+    get_discount_percent?: number | null;
+    tiers?: DiscountTier[];
+    /** MULTIBUY: how many eligible items form one group (N). */
+    multibuy_quantity?: number | null;
+    /** MULTIBUY: the fixed total price for one complete group (P), in cents. */
+    multibuy_price_cents?: number | null;
+}
+/** A promotion resolved as active for the current visitor. */
+interface ActivePromotion {
+    promotion_id: string;
+    surface?: string;
+    priority?: number;
+    content?: Record<string, unknown>;
+    translated_content?: {
+        headline?: Record<string, string>;
+        body?: Record<string, string>;
+        [key: string]: unknown;
+    };
+    discount_rule?: DiscountRule | null;
+    coupon_code?: string | null;
+    /**
+     * Which catalog entries can take part in the rule. BOTH EMPTY (or absent,
+     * on an older backend) means the whole store qualifies.
+     *
+     * Needed so a scoped offer doesn't lie: without it a "3 for EGP 650 on
+     * scarves" offer counts every cart unit, and a shopper holding one
+     * ineligible item is told "add 2 more" and then doesn't get the discount.
+     */
+    eligible_product_ids?: string[];
+    eligible_category_ids?: string[];
+}
+/** The `/api/storefront/promotions` payload, grouped by surface. */
+interface ActivePromotionsPayload {
+    announcement_bars?: ActivePromotion[];
+    popups?: ActivePromotion[];
+    floating_widgets?: ActivePromotion[];
+    cookie_banner?: ActivePromotion | null;
+    /** Automatic (no code needed) discounts — where multibuy offers live. */
+    auto_discounts?: ActivePromotion[];
+    discount_codes_visible?: ActivePromotion[];
+}
+/**
+ * A validated multibuy offer, normalized for display.
+ *
+ * `groupPriceMajor` is in MAJOR units (EGP, not piastres) so it can go
+ * straight into `<Money>` / `formatMoney` — the conversion happened once,
+ * here, rather than in each theme.
+ */
+interface MultibuyOffer {
+    promotionId: string;
+    /** N — how many items make a group. */
+    quantity: number;
+    /** P in cents, as the engine stores it. */
+    groupPriceCents: number;
+    /** P in major units, ready to render. */
+    groupPriceMajor: number;
+    /** Merchant's bilingual headline, when they set one. */
+    headline?: Record<string, string>;
+    /** Products the offer is scoped to. Empty (with categories) = whole store. */
+    eligibleProductIds: string[];
+    /** Categories the offer is scoped to. Empty (with products) = whole store. */
+    eligibleCategoryIds: string[];
+    /** True when the offer applies to the entire catalogue. */
+    isStoreWide: boolean;
+    raw: ActivePromotion;
+}
+/** Where a shopper stands against one multibuy offer. */
+interface OfferProgress {
+    /** Eligible units currently in the cart. */
+    unitsInCart: number;
+    /** How many more units to complete the next group. 0 = just unlocked. */
+    unitsNeeded: number;
+    /** Complete groups the cart has already earned. */
+    groupsUnlocked: number;
+    /**
+     * What the engine says this offer actually saved, in MAJOR units. Read
+     * from `cart.applied_promotions` — never recomputed, so the number the
+     * shopper reads is the number they are charged.
+     */
+    savingMajor: number;
+}
+
+/**
+ * The store's active promotions for the current visitor.
+ *
+ * Reads the host proxy `GET /api/storefront/promotions` (never NUMU-api
+ * directly — the host owns credentials, caching and the store resolution).
+ * The backend groups by surface; the host already renders announcement bars,
+ * popups, the cookie banner and floating widgets in the shell, so what a
+ * theme normally wants is `auto_discounts` — the offers that price the cart
+ * with no code to type.
+ *
+ * SSR-safe: `useCachedResource` doesn't fetch during server render, so this
+ * resolves on hydrate. Sections must therefore tolerate a null first pass —
+ * render nothing (or a skeleton) rather than assuming data on first paint.
+ *
+ * Returns `null` on any miss (offline, 404, flag off). That is deliberate:
+ * a promotions outage should make an offer banner disappear, never break the
+ * page it sits on.
+ *
+ * @param page   page path used for page-targeted promotions (default "/")
+ * @param locale "ar" | "en" — selects the translated content
+ */
+declare function useActivePromotions(page?: string, locale?: string): ActivePromotionsPayload | null;
+
+/**
+ * Pure helpers for rendering platform promotions in a theme.
+ *
+ * These are headless by design — data and logic only, zero markup and zero
+ * styling — so every theme keeps its own look while sharing one correct
+ * implementation of the fiddly parts (unit counting, group math, the
+ * cents→major boundary).
+ *
+ * The hard rule these encode: **a theme never computes a discount.** The
+ * engine prices the cart and reports what it saved; helpers here only
+ * describe progress toward an offer and format what the engine already
+ * decided. Anything else eventually renders a number the server won't honour.
+ */
+
+/**
+ * Extract the usable multibuy offers ("any N for a fixed total P").
+ *
+ * Accepts either the whole `/api/storefront/promotions` payload or just an
+ * array of promotions, so callers don't have to reach into `auto_discounts`
+ * themselves. Anything that isn't a well-formed multibuy — a kind this SDK
+ * version doesn't know, a missing N or P — is skipped rather than thrown on:
+ * a theme built before a rule kind existed must keep rendering when a
+ * merchant starts using it.
+ */
+declare function multibuyOffers(promotions: ActivePromotionsPayload | ActivePromotion[] | null | undefined): MultibuyOffer[];
+/**
+ * Does this product take part in the offer?
+ *
+ * A store-wide offer includes everything. Otherwise the product must be named
+ * directly or sit in a named category. A scoped offer over a product whose
+ * `category_id` we don't know returns false — better to under-promise than to
+ * advertise a discount the server won't apply.
+ */
+declare function offerIncludesProduct(offer: MultibuyOffer | null | undefined, product: {
+    id?: string;
+    product_id?: string;
+    category_id?: string | null;
+}): boolean;
+/**
+ * How many cart UNITS actually qualify for the offer.
+ *
+ * Units, not lines — three of one product is a valid trio, the way the engine
+ * scores it. For a scoped offer this is what the nudge must count; counting
+ * the whole cart is how a shopper gets told "add 2 more" and then doesn't get
+ * the discount.
+ */
+declare function eligibleUnitsInCart(offer: MultibuyOffer | null | undefined, cart: Cart | null | undefined): number;
+/**
+ * Where the cart stands against one multibuy offer.
+ *
+ * Counts UNITS, not lines — three of the same product is a valid trio, the
+ * same way the engine scores it. `savingMajor` is read from the cart's
+ * engine-supplied `applied_promotions`, so an unlocked offer shows the real
+ * saving and a theme can never drift from the charged amount.
+ *
+ * Scoping is handled automatically: when the offer names products or
+ * categories, only qualifying units are counted (via `eligibleUnitsInCart`).
+ * Pass `eligibleUnits` explicitly to override that — e.g. when the theme has
+ * a better source of truth than the cart lines.
+ */
+declare function offerProgress(offer: MultibuyOffer | null | undefined, cart: Cart | null | undefined, eligibleUnits?: number): OfferProgress;
+/**
+ * Should a product page advertise this offer?
+ *
+ * Only when N of this product actually costs more than the group price —
+ * otherwise the "deal" is worse than just buying them, and §5 of the offer
+ * spec forbids advertising it (the engine likewise refuses to apply it).
+ *
+ * @param unitPriceMajor the product's price in MAJOR units, as a theme has it
+ */
+declare function offerBeatsRegularPrice(offer: MultibuyOffer | null | undefined, unitPriceMajor: number | null | undefined): boolean;
+
 /**
  * useProductSizeChart — resolve the size chart to show for a product.
  *
@@ -2733,4 +2943,4 @@ declare function pickTranslations(bundle: LocaleBundle, locale: string): LocaleM
  */
 declare function buildLocaleBundle<T extends Record<string, unknown>>(modules: T): LocaleBundle;
 
-export { AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, ArticleDetail, ArticleSummary, Block, BlockInstance, BlockProps$1 as BlockProps, BlockSchema, BlogSummary, type CacheFetcher, type CacheMutator, type CachedResource, type CachedResourceState, Cart, CartContextValue, type CheckoutAddress, type CheckoutApi, type CheckoutSessionState, type CheckoutStep, Collection, CollectionCard, type CollectionCardProps, type CollectionCardSlots, CollectionProvider, type ComputedStyleTokens, CurrencyState, CurrencySwitcher, type CurrencySwitcherProps, Customer, type CustomerAddress, type CustomerAddressesState, type DefineBlockInput, type DefineSectionInput, type DefinedBlock, type DefinedSection, type DynamicResolveContext, type DynamicSourceRef, EditableImage, type EditableImageProps, EditableText, type EditableTextProps, type FocalSrcOptions, Form, type FormatMoneyOptions, type GiftCardBalance, HeroMedia, type HeroMediaProps, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, LOGO_SHAPE_OPTIONS, LOGO_SIZE_OPTIONS, Link, type ListingHeading, type ListingHeadingOptions, type LocaleBundle, type LocaleMessages, LocaleSwitcher, type LocaleSwitcherProps, Logo, type LogoProps, type LogoShape, type LogoSize, type MaybeOrderedTemplate, MenuItemData, type MetafieldOwner, Money, MountResult, type MutateOptions, NAVIGATE_EVENT, type NavigateEventDetail, type NavigationItem, type NavigationState, NuMuProvider, type OrderDetail, type OrderListEntry, type OrderListState, type OrderState, Page, type PlaceOrderResult, Product, ProductCard, type ProductCardProps, type ProductCardSlots, ProductProvider, ProductVariant, type RelatedProductsState, type ReorderResult, type ReorderSkipReason, type ReorderSkippedItem, type ResolvedSection, RichText, type RichTextProps, type SearchResults, type SearchState, Section, SectionContext, type SectionGroupInstance, SectionInstance, SectionProps$1 as SectionProps, SectionSchema, type ShippingRateOption, type ShopWithHelpers, SizeChart, Store, type ThemeEntry, ThemeMountContext, ThemeRenderArgs, ThemeSettingsV3, type UseCachedResourceOptions, type UseGiftCardBalance, type UseReorder, type UseSearchOptions, type UseShippingRatesOptions, type UseShippingRatesState, type UseVariantSelection, type WishlistItem, type WishlistState, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, centsToMajor, clearSdkSingleton, collectBlocks, collectSections, collectionHref, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, findVariantByOptions, flattenMessages, focalSrc, formatMoney, formatMoneyMajor, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, logoImgStyle, logoStyleTokens, majorToCents, pickTranslations, productHref, publishVariantSelection, readVariantSelection, registerReactSingleton, registerSdkSingleton, requestNavigate, resolveDynamicValue, resolveFontStack, resolveSections, resolveSettingsMap, resolveSizeChart, resolveSourcePath, sanitizeHtml, selectChromeSections, selectTemplateSections, useAnalytics, useApp, useArticle, useArticles, useBlog, useBlogs, useCachedResource, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useListingHeading, useLocale, useLocalization, useMetafield, useMetafields, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionGroup, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };
+export { type ActivePromotion, type ActivePromotionsPayload, AddToCartButton, type AddressInput, type AnalyticsApi, type AnalyticsPayload, type AppManifestBlock, type AppPayload, type AppState, ArticleDetail, ArticleSummary, Block, BlockInstance, BlockProps$1 as BlockProps, BlockSchema, BlogSummary, type CacheFetcher, type CacheMutator, type CachedResource, type CachedResourceState, Cart, CartContextValue, type CheckoutAddress, type CheckoutApi, type CheckoutSessionState, type CheckoutStep, Collection, CollectionCard, type CollectionCardProps, type CollectionCardSlots, CollectionProvider, type ComputedStyleTokens, CurrencyState, CurrencySwitcher, type CurrencySwitcherProps, Customer, type CustomerAddress, type CustomerAddressesState, type DefineBlockInput, type DefineSectionInput, type DefinedBlock, type DefinedSection, type DiscountRule, type DiscountTier, type DynamicResolveContext, type DynamicSourceRef, EditableImage, type EditableImageProps, EditableText, type EditableTextProps, type FocalSrcOptions, Form, type FormatMoneyOptions, type GiftCardBalance, HeroMedia, type HeroMediaProps, ICON_NAMES, Icon, IconMap, type IconProps, Image, type ImageTransform, LOGO_SHAPE_OPTIONS, LOGO_SIZE_OPTIONS, Link, type ListingHeading, type ListingHeadingOptions, type LocaleBundle, type LocaleMessages, LocaleSwitcher, type LocaleSwitcherProps, Logo, type LogoProps, type LogoShape, type LogoSize, type MaybeOrderedTemplate, MenuItemData, type MetafieldOwner, Money, MountResult, type MultibuyOffer, type MutateOptions, NAVIGATE_EVENT, type NavigateEventDetail, type NavigationItem, type NavigationState, NuMuProvider, type OfferProgress, type OrderDetail, type OrderListEntry, type OrderListState, type OrderState, Page, type PlaceOrderResult, Product, ProductCard, type ProductCardProps, type ProductCardSlots, ProductProvider, ProductVariant, type RelatedProductsState, type ReorderResult, type ReorderSkipReason, type ReorderSkippedItem, type ResolvedSection, RichText, type RichTextProps, type SearchResults, type SearchState, Section, SectionContext, type SectionGroupInstance, SectionInstance, SectionProps$1 as SectionProps, SectionSchema, type ShippingRateOption, type ShopWithHelpers, SizeChart, Store, type ThemeEntry, ThemeMountContext, ThemeRenderArgs, ThemeSettingsV3, type UseCachedResourceOptions, type UseGiftCardBalance, type UseReorder, type UseSearchOptions, type UseShippingRatesOptions, type UseShippingRatesState, type UseVariantSelection, type WishlistItem, type WishlistState, applyGlobalStyleTokens, applyImageTransform, asImageTransform, assetUrl, availableValues, buildLocaleBundle, centsToMajor, clearSdkSingleton, collectBlocks, collectSections, collectionHref, computeGlobalStyleTokens, defaultVariant, defineBlock, defineSection, defineThemeEntry, dynamicSource, eligibleUnitsInCart, findVariantByOptions, flattenMessages, focalSrc, formatMoney, formatMoneyMajor, getReactSingleton, getSdkSingleton, isDefinedBlock, isDefinedSection, isDynamicSource, isSdkAvailable, logoImgStyle, logoStyleTokens, majorToCents, multibuyOffers, offerBeatsRegularPrice, offerIncludesProduct, offerProgress, pickTranslations, productHref, publishVariantSelection, readVariantSelection, registerReactSingleton, registerSdkSingleton, requestNavigate, resolveDynamicValue, resolveFontStack, resolveSections, resolveSettingsMap, resolveSizeChart, resolveSourcePath, sanitizeHtml, selectChromeSections, selectTemplateSections, useActivePromotions, useAnalytics, useApp, useArticle, useArticles, useBlog, useBlogs, useCachedResource, useCart, useCheckout, useCollection, useCollectionOptional, useCollections, useCurrency, useCurrentTemplate, useCustomer, useCustomerActions, useCustomerAddresses, useDirection, useFieldTranslation, useGiftCardBalance, useImage, useListingHeading, useLocale, useLocalization, useMetafield, useMetafields, useMoney, useNavigation, useNumberFormat, useOrder, useOrders, usePage, useProduct, useProductOptional, useProductSizeChart, useProducts, useRelatedProducts, useReorder, useResolvedSettings, useSearch, useSection, useSectionGroup, useSectionOptional, useShippingRates, useShop, useThemeSettings, useTranslation, useVariantSelection, useWishlist };