brainerce 1.46.2 → 1.47.3

package/dist/index.d.ts

@@ -76,6 +76,31 @@ interface BrainerceClientOptions {
         statusCode: number;
         path?: string;
     }) => void;
+    /**
+     * Callback fired when the SDK silently resets the guest session cart because
+     * the previously-stored cart could no longer be resolved as-is — either the
+     * fetch failed (network error, 404 — cart deleted/expired) or the cart was
+     * found but is no longer `ACTIVE` (e.g. a prior checkout on it already
+     * completed or the cart was abandoned/merged). In both cases the SDK
+     * transparently creates a fresh empty cart so `smartAddToCart()` /
+     * `smartGetCart()` keep working — this callback is your only signal that it
+     * happened, so the storefront can tell the shopper their cart expired
+     * instead of them just seeing it silently empty out.
+     *
+     * @example
+     * ```typescript
+     * const client = new BrainerceClient({
+     *   salesChannelId: 'vc_abc123...',
+     *   onCartReset: ({ previousCartId, reason }) => {
+     *     toast.warn('Your cart session expired — please re-add your items.');
+     *   },
+     * });
+     * ```
+     */
+    onCartReset?: (info: {
+        previousCartId: string;
+        reason: 'not_found' | 'not_active';
+    }) => void;
     /**
      * Origin header to send with requests.
      * Browsers add this automatically, but Node.js environments (SSR, scripts, npx)
@@ -194,6 +219,36 @@ interface StoreInfo {
     upsell?: UpsellSettings;
     /** Multi-language / i18n settings */
     i18n?: I18nSettings;
+    /**
+     * SEO Autopilot fields (sales-channel mode only).
+     * `indexNowKey`: serve this verbatim at `GET /indexnow-key.txt`
+     * (`text/plain`) so the platform can ping IndexNow when blog posts publish.
+     * Not a secret — the key file is public by protocol design. `null` until
+     * the store's SEO Autopilot generates one; return 404 while null.
+     */
+    seo?: {
+        indexNowKey: string | null;
+    };
+    /**
+     * Real merchant-configured shipping rates (sales-channel mode only) —
+     * flat-rate/free zones only, each with a single unconditional price.
+     * Weight/price-tiered and local-pickup rates are excluded because their
+     * cost depends on cart contents, so there's no single number to declare.
+     * Feeds Product JSON-LD `shippingDetails` — pass as `buildProductJsonLd(product, { ..., shipping: storeInfo.shipping })`.
+     */
+    shipping?: ShippingSummaryEntry[];
+}
+/** One flat-rate/free shipping zone, as exposed by `StoreInfo.shipping`. */
+interface ShippingSummaryEntry {
+    /** ISO 3166-1 alpha-2 country codes this rate applies to. */
+    countries: string[];
+    rateType: 'FLAT_RATE' | 'FREE';
+    /** Shipping cost in the store's currency. `0` for FREE, `null` if a FLAT_RATE has no configured amount. */
+    amount: number | null;
+    minDeliveryDays: number | null;
+    maxDeliveryDays: number | null;
+    /** Order-processing time in business days before the item ships. */
+    handlingTime: number | null;
 }
 /** Multi-language configuration exposed to the storefront */
 interface I18nSettings {
@@ -304,6 +359,64 @@ interface LoyaltyStatus {
         type: string;
         value: number;
     } | null;
+    /** Milestone badges this customer has earned (newest first; empty when none). */
+    badges?: LoyaltyBadge[];
+    /**
+     * The customer's paid premium membership, or null for free members.
+     * status PAST_DUE = the last recurring charge failed (perks paused until it
+     * clears); cancelAtPeriodEnd = perks continue until nextBillingAt, then end.
+     */
+    paidMembership?: PaidMembershipInfo | null;
+}
+/** A milestone badge a customer earned (display-only recognition). */
+interface LoyaltyBadge {
+    id: string;
+    name: string;
+    description: string | null;
+    iconUrl: string | null;
+    /** ISO timestamp of when this customer earned the badge. */
+    awardedAt: string;
+}
+/** A paid premium membership plan customers can subscribe to. */
+interface LoyaltyMembershipPlan {
+    id: string;
+    name: string;
+    perksDescription: string | null;
+    /** Recurring charge amount, in the store currency. */
+    priceAmount: number;
+    /** Days between recurring charges (default 30). */
+    billingIntervalDays: number;
+    /** Points-earning multiplier while the subscription is ACTIVE (composes with the tier multiplier). */
+    pointsMultiplier: number;
+}
+/** A customer's paid membership state (see LoyaltyStatus.paidMembership). */
+interface PaidMembershipInfo {
+    status: 'ACTIVE' | 'PAST_DUE' | 'CANCELLED';
+    /** True when the customer cancelled — perks continue until nextBillingAt, then end without a charge. */
+    cancelAtPeriodEnd: boolean;
+    /** ISO timestamp of the next recurring charge (null once cancelled). */
+    nextBillingAt: string | null;
+    plan: LoyaltyMembershipPlan | null;
+}
+/** A saved payment method (display fields only — never any card data). */
+interface StorefrontSavedPaymentMethod {
+    id: string;
+    /** 'credit_card' | 'paypal' | 'bank_account' */
+    paymentMethod: string;
+    brand: string | null;
+    last4: string | null;
+    expMonth: number | null;
+    expYear: number | null;
+    isDefault: boolean;
+}
+/** AI reward recommendation — always a reward from the store's real catalog. */
+interface LoyaltyRewardRecommendation {
+    /** The recommended reward, or null when the catalog is empty. */
+    reward: LoyaltyReward | null;
+    /** Short customer-facing explanation, or null (deterministic fallback picks have no reason). */
+    reason?: string | null;
+    /** 'ai' = model choice validated against the catalog; 'fallback' = deterministic pick. */
+    source?: 'ai' | 'fallback';
 }
 /** Public referral-link lookup result (no auth needed) — see getReferralInfo(). */
 interface ReferralInfo {
@@ -404,6 +517,10 @@ interface Product {
     description?: string | null;
     descriptionFormat?: 'text' | 'html' | 'markdown' | null;
     sku: string;
+    /** Global Trade Item Number (EAN/UPC/ISBN). Emitted in Product JSON-LD. */
+    gtin?: string | null;
+    /** Manufacturer Part Number. Emitted in Product JSON-LD. */
+    mpn?: string | null;
     /**
      * Base price as string (e.g., "29.99"). Use parseFloat() for calculations.
      *
@@ -425,6 +542,10 @@ interface Product {
      * `SIMPLE` products it is the product's own stored sale price.
      */
     salePrice?: string | null;
+    /** ISO 8601 — start of the sale-price effective window. `null` when unset (sale has no window). */
+    salePriceStartsAt?: string | null;
+    /** ISO 8601 — end of the sale-price effective window. Feeds Product JSON-LD `priceValidUntil`. `null` when unset. */
+    salePriceEndsAt?: string | null;
     /** Cost price as string. Use parseFloat() for calculations. */
     costPrice?: string | null;
     /** Lowest effective variant price (VARIABLE products only). String Decimal, e.g. "19.99". */
@@ -454,13 +575,15 @@ interface Product {
     inventory?: InventoryInfo | null;
     variants?: ProductVariant[];
     /**
-     * Categories as objects with `id` and `name`.
-     * NOT string[] - each category is `{ id: string; name: string }`.
-     * Access: `product.categories?.map(cat => cat.name)`
+     * Categories as objects with `id`, `name`, and `slug`.
+     * NOT string[] - each category is `{ id: string; name: string; slug?: string | null }`.
+     * Access: `product.categories?.map(cat => cat.name)`. Use `slug` to link to
+     * that category's `/category/{slug}` landing page.
      */
     categories?: Array<{
         id: string;
         name: string;
+        slug?: string | null;
     }>;
     /** Brands as objects with id and name */
     brands?: Array<{
@@ -632,6 +755,10 @@ interface ProductVariant {
     price?: string | null;
     /** Variant sale price as string. Use parseFloat() for calculations. */
     salePrice?: string | null;
+    /** Variant unit cost (COGS) override as string — falls back to the product
+     *  costPrice in margin analytics. Admin (apiKey) reads only; public
+     *  storefront responses never include it. */
+    costPrice?: string | null;
     /** PRD §23: variant price converted to the region's currency via the daily
      *  FX snapshot. Present only with `getProducts({ regionId })`. Display-only. */
     displayPrice?: string;
@@ -1169,9 +1296,35 @@ interface ProductSuggestion {
 interface CategoryNode {
     id: string;
     name: string;
+    /** URL-friendly handle — link a category page as `/category/${slug}`. */
+    slug?: string | null;
     parentId?: string | null;
+    image?: string | null;
     children: CategoryNode[];
 }
+/**
+ * Full category-page payload from {@link BrainerceClient.getCategoryBySlug}.
+ * Backs a storefront category (a.k.a. collection) landing page — the
+ * highest-leverage organic-SEO surface. The products themselves come from a
+ * separate `getProducts({ categories: [id] })` call, so this stays metadata.
+ */
+interface CategoryDetail {
+    id: string;
+    name: string;
+    slug: string | null;
+    /** Long-form category copy as sanitized HTML (render below the grid). */
+    description: string | null;
+    /** Meta description for the category page `<meta name="description">`. */
+    metaDescription: string | null;
+    image: string | null;
+    /** Ancestor chain (root → parent), for breadcrumb JSON-LD + UI. */
+    breadcrumb: Array<{
+        name: string;
+        slug: string | null;
+    }>;
+    /** Products published to this channel + active + in this category. */
+    productCount: number;
+}
 /**
  * Category suggestion for autocomplete.
  *
@@ -2985,15 +3138,14 @@ interface AddressDetailsResult {
         line1: string;
         city: string;
         /**
-         * Google's own administrative-area code for the resolved place (e.g.
-         * `"D"` for an Israeli address in the Southern District). Usually — but
-         * not guaranteed — the same ISO 3166-2 subdivision code this platform's
-         * own region lists use (`getShippingDestinations()`'s `regions`), since
-         * both ultimately derive from the same standard. Before assigning this
-         * into a `SetShippingAddressDto.region` field, validate it against the
-         * store's own `destinations.regions[country]` list (matching by `code`)
-         * — if it's not one of the known codes, leave the field for the shopper
-         * to pick manually rather than assigning an unrecognized value.
+         * This platform's own region `code` for the resolved place (the same
+         * code `getShippingDestinations()`'s `regions` list uses), already
+         * reconciled server-side from whatever raw text Google returned — empty
+         * string when nothing could be matched. Still validate it against
+         * `destinations.regions[country]` (matching by `code`) before assigning
+         * into a `SetShippingAddressDto.region` field rather than trusting it
+         * unconditionally — an empty/unresolved value should leave the field for
+         * the shopper to pick manually, not get assigned as-is.
          */
         region: string;
         postalCode: string;
@@ -3023,6 +3175,8 @@ interface CreateVariantDto {
     attributes?: Record<string, string>;
     price?: number;
     salePrice?: number;
+    /** Variant unit cost (COGS) override — falls back to product costPrice in margin analytics. */
+    costPrice?: number;
     inventory?: number;
     image?: unknown;
     position?: number;
@@ -3034,6 +3188,8 @@ interface UpdateVariantDto {
     attributes?: Record<string, string>;
     price?: number;
     salePrice?: number;
+    /** Variant unit cost (COGS) override. Pass null to clear (falls back to product costPrice). */
+    costPrice?: number | null;
     image?: string | unknown;
     position?: number;
     status?: VariantStatus;
@@ -3052,6 +3208,8 @@ interface BulkVariantInput {
     attributes: Record<string, string>;
     price?: number | null;
     salePrice?: number | null;
+    /** Variant unit cost (COGS) override. null clears (falls back to product costPrice). */
+    costPrice?: number | null;
     stock: number;
     position?: number;
     image?: unknown | null;
@@ -5915,6 +6073,7 @@ declare class BrainerceClient {
     private readonly origin?;
     private readonly proxyMode;
     private readonly onAuthError?;
+    private readonly onCartReset?;
     /** Active locale for content translation. When set, content endpoints return translated data. */
     private locale?;
     constructor(options: BrainerceClientOptions);
@@ -6126,6 +6285,23 @@ declare class BrainerceClient {
     }): Promise<{
         categories: CategoryNode[];
     }>;
+    /**
+     * Get one category by slug — the payload for a storefront category
+     * (collection) landing page: name, description HTML, meta, breadcrumb and
+     * product count. Fetch the products themselves with
+     * `getProducts({ categories: [category.id] })`. Vibe-coded mode only, like
+     * {@link getCategories}.
+     *
+     * @example
+     * ```typescript
+     * const category = await client.getCategoryBySlug('running-shoes').catch(() => null);
+     * if (!category) notFound();
+     * const { data: products } = await client.getProducts({ categories: [category.id] });
+     * ```
+     */
+    getCategoryBySlug(slug: string, options?: {
+        locale?: string;
+    }): Promise<CategoryDetail>;
     /**
      * Get available brands for filtering products
      * Works in vibe-coded mode
@@ -9015,15 +9191,18 @@ declare class BrainerceClient {
     }): Promise<CustomerProfile>;
     /**
      * Get the logged-in customer's loyalty status: enrollment, points balance,
-     * lifetime earned, and the program's display config (requires customerToken).
-     * Only available in storefront mode. `program` is null when the store has no
-     * loyalty program.
+     * lifetime earned, the program's display config, earned milestone `badges`,
+     * and the `paidMembership` subscription state (null for free members).
+     * Requires customerToken. Only available in storefront mode. `program` is
+     * null when the store has no loyalty program.
      *
      * @example
      * ```typescript
      * client.setCustomerToken(auth.token);
      * const status = await client.getLoyaltyStatus();
      * if (status.enrolled) console.log(`${status.pointsBalance} ${status.program?.pointsName}`);
+     * status.badges?.forEach((b) => console.log(`🏅 ${b.name}`));
+     * if (status.paidMembership?.status === 'ACTIVE') showPremiumPerks(status.paidMembership.plan);
      * ```
      */
     getLoyaltyStatus(): Promise<LoyaltyStatus>;
@@ -9093,6 +9272,98 @@ declare class BrainerceClient {
      * ```
      */
     getReferralInfo(code: string): Promise<ReferralInfo>;
+    /**
+     * AI-recommended reward for the logged-in customer — "recommended for you"
+     * at the top of the rewards list (requires customerToken). The result is
+     * ALWAYS a real reward from the store's catalog (the AI only ranks; a
+     * hallucinated pick falls back to a deterministic choice). Returns
+     * `{ reward: null }` when the catalog is empty. Rate-limited (5/min per
+     * customer — it spends the merchant's AI credits). Only available in
+     * storefront mode.
+     *
+     * @example
+     * ```typescript
+     * const { reward, reason } = await client.getRecommendedReward();
+     * if (reward) showRecommendation(reward, reason);
+     * ```
+     */
+    getRecommendedReward(): Promise<LoyaltyRewardRecommendation>;
+    /**
+     * List the paid membership plans the customer can subscribe to (requires
+     * customerToken). Empty when the store offers none or the program is not
+     * active. Only available in storefront mode.
+     *
+     * @example
+     * ```typescript
+     * const plans = await client.getMembershipPlans();
+     * ```
+     */
+    getMembershipPlans(): Promise<LoyaltyMembershipPlan[]>;
+    /**
+     * List the customer's saved payment methods (display fields only — brand /
+     * last4 / expiry, never card data) for the membership subscribe flow.
+     * Requires customerToken. Cards are vaulted by checking out with
+     * `saveCard: true`. Only available in storefront mode.
+     *
+     * @example
+     * ```typescript
+     * const methods = await client.getMySavedPaymentMethods();
+     * ```
+     */
+    getMySavedPaymentMethods(): Promise<StorefrontSavedPaymentMethod[]>;
+    /**
+     * Subscribe the customer to a paid membership plan — charges the saved card
+     * IMMEDIATELY and starts the recurring cycle (requires customerToken).
+     * Throws a 409 with a `code` ('card_declined' | 'requires_action' | ...)
+     * when the charge fails; 3D-Secure challenges are not supported off-session
+     * and surface as `requires_action`. Only available in storefront mode.
+     *
+     * @example
+     * ```typescript
+     * const membership = await client.subscribeToMembership({
+     *   planId: plan.id,
+     *   savedPaymentTokenId: method.id,
+     * });
+     * // membership.status === 'ACTIVE'
+     * ```
+     */
+    subscribeToMembership(params: {
+        planId: string;
+        savedPaymentTokenId: string;
+    }): Promise<PaidMembershipInfo>;
+    /**
+     * Cancel the customer's paid membership (requires customerToken).
+     * End-of-period semantics: perks continue until `nextBillingAt`, then the
+     * subscription ends without another charge (a PAST_DUE membership cancels
+     * immediately). Re-subscribing to the same plan before period end simply
+     * un-cancels. Only available in storefront mode.
+     *
+     * @example
+     * ```typescript
+     * const membership = await client.cancelMembership();
+     * // membership.cancelAtPeriodEnd === true
+     * ```
+     */
+    cancelMembership(): Promise<PaidMembershipInfo>;
+    /**
+     * Mint a short-lived session for the embeddable loyalty widget (Phase 5) and
+     * return the ready-to-use iframe URL. Requires customerToken. The returned
+     * `embedUrl` is safe to drop straight into an `<iframe src>` — it carries a
+     * scoped ~15-minute session token, never the real customerToken. Re-call this
+     * before the iframe reloads (e.g. on page navigation) to refresh it.
+     *
+     * @example
+     * ```typescript
+     * const { embedUrl } = await client.getLoyaltyWidgetSession();
+     * // <iframe src={embedUrl} width="360" height="420" />
+     * ```
+     */
+    getLoyaltyWidgetSession(): Promise<{
+        sessionId: string;
+        expiresAt: string;
+        storeId: string;
+        embedUrl: string;
+    }>;
     /**
      * Get the current customer's orders (requires customerToken)
      * Works in vibe-coded and storefront modes
@@ -10453,4 +10724,149 @@ declare function formatVariantPrice(variant: Pick<ProductVariant, 'price' | 'sal
 /** Format any numeric amount as currency. Useful for cart totals, fees, etc. */
 declare function formatMoney(amount: number, currency: string, locale?: string): string;
 
-export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryNode, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyStatus, type LoyaltyTierSummary, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type MyProductReview, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingZone, type ShippingZoneQueryParams, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type SubmitProductReviewInput, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, safePaymentRedirect, stripHtml, verifyWebhook };
+/**
+ * JSON-LD (schema.org) builders for storefronts.
+ *
+ * Structured data is the "organic visibility without a Merchant Center feed"
+ * lever: complete Product markup (Offer, availability, ratings) qualifies
+ * pages for Google merchant-listing surfaces directly, and Organization/
+ * Article/BreadcrumbList markup feeds rich results and AI-answer citations.
+ *
+ * Pure functions — no client dependency, framework-agnostic. Render with
+ * {@link jsonLdScriptProps}:
+ *
+ *     <script {...jsonLdScriptProps(buildProductJsonLd(product, { siteUrl, path }))} />
+ *
+ * Rules baked in (Google's structured-data guidelines):
+ *   - Product markup belongs on single-product pages only.
+ *   - `aggregateRating` is emitted ONLY when the product has visible reviews.
+ *   - Offers carry ISO-4217 currency and a positive price.
+ */
+
+interface JsonLdOptions {
+    /** Canonical site origin, e.g. "https://shop.com" (no trailing slash). */
+    siteUrl: string;
+    /** Path of the page being marked up, e.g. "/products/red-shoes". */
+    path?: string;
+}
+type JsonLd = Record<string, unknown>;
+/**
+ * schema.org/Article for a blog post. Emit on the article page
+ * (`/blog/[slug]`) alongside {@link buildBreadcrumbJsonLd}.
+ */
+declare function buildArticleJsonLd(post: BlogPost, opts: JsonLdOptions & {
+    organizationName?: string;
+}): JsonLd;
+/**
+ * schema.org/Product for a single-product page (PDP). Do NOT emit on
+ * category/listing pages — Google's Product rich results apply to
+ * single-product pages only.
+ */
+declare function buildProductJsonLd(product: Product, opts: JsonLdOptions & {
+    /** ISO-4217 currency code, e.g. "USD" / "ILS" (from StoreInfo.currency). */
+    currency: string;
+    /** Brand display name; falls back to product.brands[0]. */
+    brandName?: string;
+    /** Flat-rate/free shipping zones (from `StoreInfo.shipping`). Omitted entirely when not provided — no fabricated shipping cost. */
+    shipping?: ShippingSummaryEntry[];
+}): JsonLd;
+/**
+ * schema.org/Organization for the homepage (Knowledge Panel + AI-answer
+ * citation grounding).
+ */
+declare function buildOrganizationJsonLd(store: StoreInfo, opts: JsonLdOptions): JsonLd;
+/**
+ * schema.org/WebSite for the homepage. Establishes the site as a brand entity
+ * (an off-page "Authority" signal that grounds Google's Knowledge Panel and AI
+ * answers) and — when `searchUrlTemplate` is given — declares a SearchAction so
+ * Google can show a sitelinks search box for the brand.
+ *
+ * `searchUrlTemplate` must contain the literal token `{search_term_string}`,
+ * e.g. `"/products?search={search_term_string}"`. Only pass it when the site
+ * actually has a search results page at that URL.
+ */
+declare function buildWebsiteJsonLd(store: StoreInfo, opts: JsonLdOptions & {
+    searchUrlTemplate?: string;
+}): JsonLd;
+/**
+ * schema.org/CollectionPage for a category (collection) landing page. This is
+ * the correct markup for a listing page — never emit {@link buildProductJsonLd}
+ * here (Product rich results are single-product only). Pair with
+ * {@link buildBreadcrumbJsonLd} built from `category.breadcrumb`.
+ */
+declare function buildCollectionPageJsonLd(category: Pick<CategoryDetail, 'name' | 'description' | 'metaDescription' | 'image'>, opts: JsonLdOptions): JsonLd;
+/** schema.org/BreadcrumbList. Items in order from root to current page. */
+declare function buildBreadcrumbJsonLd(items: Array<{
+    name: string;
+    url: string;
+}>): JsonLd;
+/**
+ * Safe `<script type="application/ld+json">` props for React. Escapes `<` so
+ * malicious content can never close the script tag (XSS-safe serialization).
+ */
+declare function jsonLdScriptProps(data: JsonLd): {
+    type: 'application/ld+json';
+    dangerouslySetInnerHTML: {
+        __html: string;
+    };
+};
+
+/**
+ * Sitemap helpers for storefronts.
+ *
+ * `getBlogSitemapEntries` paginates the public blog API and returns entries
+ * structurally compatible with Next.js `MetadataRoute.Sitemap` — without
+ * importing Next (the SDK stays framework-agnostic).
+ *
+ *     // app/sitemap.ts
+ *     const blogPages = await getBlogSitemapEntries(client, { siteUrl }).catch(() => []);
+ *     return [...staticPages, ...productPages, ...blogPages];
+ */
+
+interface SitemapEntry {
+    url: string;
+    lastModified?: Date;
+    changeFrequency?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    priority?: number;
+}
+interface BlogSitemapOptions {
+    /** Canonical site origin, e.g. "https://shop.com" (no trailing slash). */
+    siteUrl: string;
+    /** Blog route prefix. Default '/blog'. */
+    basePath?: string;
+    /**
+     * Locales to emit locale-prefixed entries for (e.g. ['en','he']). When set
+     * with `defaultLocale`, the default locale is emitted unprefixed and every
+     * other locale as `/{locale}{basePath}/{slug}` — matching the product-page
+     * convention in the storefront template.
+     */
+    locales?: string[];
+    defaultLocale?: string;
+    /** Page size per API call (max 100). Default 100. */
+    pageSize?: number;
+    /** Safety cap on total entries. Default 5000. */
+    maxEntries?: number;
+}
+/**
+ * Fetch every published blog post and map to sitemap entries. Public mode
+ * only returns PUBLISHED posts, so no status filtering is needed.
+ */
+declare function getBlogSitemapEntries(client: BrainerceClient, opts: BlogSitemapOptions): Promise<SitemapEntry[]>;
+interface CategorySitemapOptions {
+    /** Canonical site origin, e.g. "https://shop.com" (no trailing slash). */
+    siteUrl: string;
+    /** Category route prefix. Default '/category'. */
+    basePath?: string;
+    /** Emit locale-prefixed variants for these (default locale stays unprefixed). */
+    locales?: string[];
+    defaultLocale?: string;
+}
+/**
+ * Category (collection) pages for the sitemap — high-priority organic-SEO
+ * surfaces. Walks the {@link BrainerceClient.getCategories} tree and emits one
+ * entry per category that has a slug. Categories carry no lastModified in the
+ * public tree, so entries omit it.
+ */
+declare function getCategorySitemapEntries(client: BrainerceClient, opts: CategorySitemapOptions): Promise<SitemapEntry[]>;
+
+export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BlogSitemapOptions, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryDetail, type CategoryNode, type CategorySitemapOptions, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type JsonLdOptions, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyStatus, type LoyaltyTierSummary, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type MyProductReview, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type SubmitProductReviewInput, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, buildArticleJsonLd, buildBreadcrumbJsonLd, buildCollectionPageJsonLd, buildOrganizationJsonLd, buildProductJsonLd, buildWebsiteJsonLd, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getBlogSitemapEntries, getCartItemImage, getCartItemName, getCartTotals, getCategorySitemapEntries, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseWebhookEvent, safePaymentRedirect, stripHtml, verifyWebhook };