brainerce 1.53.1 → 1.55.0

package/dist/index.d.ts

@@ -246,7 +246,91 @@ interface StoreInfo {
      * Feeds Product JSON-LD `shippingDetails` — pass as `buildProductJsonLd(product, { ..., shipping: storeInfo.shipping })`.
      */
     shipping?: ShippingSummaryEntry[];
+    /**
+     * Marketing tag ids for this sales channel (sales-channel mode only).
+     *
+     * Resolved server-side from the marketplace apps the merchant already
+     * connected — connecting the Google & YouTube app runs GA4 discovery and the
+     * measurement id lands here on its own; same for the Meta and TikTok pixels.
+     * The merchant types nothing, and the storefront needs no redeploy: a newly
+     * connected app shows up here within 5 minutes.
+     *
+     * Pass the whole object to {@link BrainerceClient.initTracking} — it boots
+     * every tag that is present and skips the rest. Absent fields are the normal
+     * state (that app simply isn't connected), never an error.
+     */
+    tracking?: StoreTracking;
+}
+/**
+ * Marketing tag ids served by `GET /api/vc/:connectionId/info`.
+ *
+ * Every id here is public by nature — it renders into the page source of the
+ * storefront — and is format-validated by the backend before being served, so
+ * it is safe to interpolate into a tag bootstrap.
+ */
+interface StoreTracking {
+    /** GA4 measurement id, `G-XXXXXXX`. Auto-discovered by the Google & YouTube app. */
+    ga4MeasurementId?: string;
+    /**
+     * Google Tag Manager container id, `GTM-XXXXXX`. The one tag that cannot be
+     * auto-discovered — no OAuth surface exposes a container id — so it appears
+     * only when a merchant sets it on the sales channel.
+     */
+    gtmContainerId?: string;
+    /** Meta (Facebook) pixel id. Auto-discovered by the Meta Commerce app. */
+    metaPixelId?: string;
+    /** TikTok pixel id. Auto-discovered by the TikTok Shop app. */
+    tiktokPixelId?: string;
+}
+/**
+ * A normalized e-commerce event, fanned out by
+ * {@link BrainerceClient.trackMarketingEvent} to every tag that is loaded.
+ *
+ * Field names follow the GA4 e-commerce spec; the SDK translates them to each
+ * vendor's own vocabulary (`fbq` Meta standard events, `ttq` TikTok events) so
+ * you describe what happened once instead of three times.
+ */
+interface TrackingEventPayload {
+    /** ISO 4217, e.g. `ILS`. Required for `purchase` / `begin_checkout` to be usable in ad optimization. */
+    currency?: string;
+    /** Monetary value of the event. */
+    value?: number;
+    /**
+     * Order id, for `purchase` only. Used as GA4's `transaction_id`, Meta's
+     * `eventID` and TikTok's `event_id`, which makes a duplicate send (page
+     * refresh, back-button) de-duplicate on the vendor's side rather than
+     * double-counting revenue.
+     */
+    transactionId?: string;
+    /** Shipping charged on the order (`purchase`). */
+    shipping?: number;
+    /** Tax charged on the order (`purchase`). */
+    tax?: number;
+    /** Coupon code applied. */
+    coupon?: string;
+    /** Line items. `itemId` must match the id you sync to the ad platform's catalog. */
+    items?: TrackingEventItem[];
+}
+/** One line item inside a {@link TrackingEventPayload}. */
+interface TrackingEventItem {
+    /**
+     * The item id as the ad platform's catalog knows it.
+     *
+     * Use the product's SKU: that is what the Meta and Google catalog feeds
+     * publish as the item id, so anything else silently breaks attribution and
+     * dynamic remarketing — the pixel reports an id the catalog has never heard
+     * of, and the audience never builds.
+     */
+    itemId: string;
+    itemName?: string;
+    /** Unit price (GA4 multiplies by `quantity` itself — do not pre-multiply). */
+    price?: number;
+    quantity?: number;
+    itemVariant?: string;
+    itemCategory?: string;
 }
+/** E-commerce event names understood by {@link BrainerceClient.trackMarketingEvent}. */
+type TrackingEventName = 'view_item' | 'view_item_list' | 'add_to_cart' | 'remove_from_cart' | 'view_cart' | 'begin_checkout' | 'add_payment_info' | 'purchase' | 'search' | 'sign_up';
 /** One flat-rate/free shipping zone, as exposed by `StoreInfo.shipping`. */
 interface ShippingSummaryEntry {
     /** ISO 3166-1 alpha-2 country codes this rate applies to. */
@@ -1131,8 +1215,14 @@ declare function getCartTotals(cart: Pick<Cart, 'subtotal' | 'discountAmount'> |
 };
 /**
  * Get the display name for a cart item.
- * Handles the nested product/variant structure - uses variant name if available,
- * otherwise falls back to product name.
+ * Handles the nested product/variant structure - the product name identifies the
+ * line, with the variant name appended as a qualifier: `"Blue T-Shirt - Large"`.
+ *
+ * The suffix is omitted for products with no variant, and for variants whose name
+ * was copied from the product (so the name never renders twice).
+ *
+ * Need the two parts separately — e.g. to render the variant on its own line —
+ * read `item.product.name` and `item.variant?.name` directly.
  *
  * @param item - The cart item
  * @returns The display name for the item
@@ -1140,7 +1230,7 @@ declare function getCartTotals(cart: Pick<Cart, 'subtotal' | 'discountAmount'> |
  * @example
  * ```typescript
  * cart.items.forEach(item => {
- *   const name = getCartItemName(item);
+ *   const name = getCartItemName(item); // "Blue T-Shirt - Large"
  *   console.log(`${name} x ${item.quantity}`);
  * });
  * ```
@@ -4630,6 +4720,37 @@ interface AutoRegionResponse {
  * still runs at checkout against the full shipping address (state / postal /
  * per-class). Render with an "Estimate" affordance.
  */
+/**
+ * Manual per-region price override (regional pricing) — the merchant's
+ * hand-set price pair for one product or variant in one region, denominated
+ * in the REGION's currency. Replaces the automatic FX conversion for regions
+ * that actually charge their currency (presentment). Admin (api-key) surface.
+ */
+interface RegionPrice {
+    id: string;
+    productId: string;
+    /** null = the product-level price (covers every variant without its own row). */
+    variantId: string | null;
+    /** Regular price in the region currency (Decimal string). */
+    price: string;
+    /** Sale price in the region currency — always lower than price; null = no regional sale. */
+    salePrice: string | null;
+    updatedAt: string;
+}
+/** One bulk entry for `upsertRegionPrices`. `remove: true` deletes the row. */
+interface RegionPriceEntry {
+    productId: string;
+    variantId?: string;
+    /** Required unless `remove` — regular price in the region currency. */
+    price?: number;
+    /** Optional sale price — must be lower than `price`. */
+    salePrice?: number;
+    remove?: boolean;
+}
+interface UpsertRegionPricesResult {
+    upserted: number;
+    removed: number;
+}
 interface TaxEstimateResponse {
     appliesTax: boolean;
     /** Percent — e.g. 18 for 18%. `null` when no matching rule. */
@@ -6278,6 +6399,17 @@ declare global {
     interface Window {
         dataLayer?: unknown[];
         gtag?: (...args: unknown[]) => void;
+        /** Meta pixel queue, installed by `initTracking()` when a pixel id is configured. */
+        fbq?: ((...args: unknown[]) => void) & {
+            queue?: unknown[];
+            loaded?: boolean;
+            version?: string;
+        };
+        _fbq?: unknown;
+        /** TikTok pixel queue, installed by `initTracking()` when a pixel id is configured. */
+        ttq?: Record<string, unknown> & {
+            track?: (...args: unknown[]) => void;
+        };
     }
 }
 /**
@@ -6340,6 +6472,9 @@ declare class BrainerceClient {
     private _pendingRecoverCartId;
     private _ga4MeasurementId;
     private _ga4StitchPromise;
+    private _gtmContainerId;
+    private _metaPixelId;
+    private _tiktokPixelId;
     /**
      * Fields present on `getAddressDetails().address` that the address endpoints
      * do NOT accept — stripped by `stripResolvedOnlyAddressFields()` so a
@@ -6572,6 +6707,71 @@ declare class BrainerceClient {
      * consent.
      */
     private resolveGa4StitchIds;
+    /**
+     * Boot every marketing tag the merchant has configured — GA4, Google Tag
+     * Manager, the Meta pixel, the TikTok pixel — in one call.
+     *
+     * Pass `storeInfo.tracking` straight through. The ids in it are resolved
+     * server-side from the marketplace apps the merchant already connected, so
+     * for the common case nobody types an id anywhere and nobody redeploys the
+     * storefront: connect the Google app in the dashboard and this call starts
+     * loading GA4 on the next page render.
+     *
+     * Call it once, as early as possible (root layout / app entry). It is
+     * idempotent, a no-op during SSR, and never throws — a blocked or missing
+     * tag must never take a storefront down with it.
+     *
+     * GA4 goes through {@link loadGoogleAnalytics}, so the `client_id` /
+     * `session_id` stitch ids keep flowing onto cart and checkout calls and the
+     * server-side purchase conversion still lands in the right session.
+     *
+     * @example
+     * ```typescript
+     * const storeInfo = await client.getStoreInfo();
+     * client.initTracking(storeInfo.tracking);
+     * // …later, on the order confirmation page:
+     * client.trackMarketingEvent('purchase', {
+     *   transactionId: order.id,
+     *   currency: order.currency,
+     *   value: order.totalAmount,
+     *   items: order.items.map((i) => ({ itemId: i.sku, itemName: i.name, price: i.price, quantity: i.quantity })),
+     * });
+     * ```
+     */
+    initTracking(tracking?: StoreTracking | null): void;
+    /**
+     * Report one e-commerce event to every marketing tag that
+     * {@link initTracking} loaded (GA4/GTM, Meta, TikTok).
+     *
+     * Distinct from {@link trackEvent}, which posts a cookieless pageview/beacon
+     * to Brainerce's own storefront analytics. This one is about ad platforms —
+     * call both; they answer different questions.
+     *
+     * You describe what happened once, in GA4's vocabulary, and the SDK
+     * translates: a `dataLayer` push for GA4/GTM, the matching Meta standard
+     * event via `fbq`, and the matching TikTok event via `ttq`. Tags that aren't
+     * loaded are skipped silently, so the same call is correct whether the
+     * merchant has connected none, one, or all of them.
+     *
+     * Why this matters for ad spend: a GTM container with no `dataLayer` events
+     * is an empty container, and Meta cannot optimize a campaign it never sees a
+     * `Purchase` for. The value/currency/item-id triple in {@link TrackingEventPayload}
+     * is the whole input to that optimization.
+     *
+     * `purchase` is de-duplicated by the vendors on `transactionId` (GA4
+     * `transaction_id`, Meta `eventID`, TikTok `event_id`), so a shopper
+     * refreshing the confirmation page cannot double-count the order — pass the
+     * order id and the safety is automatic.
+     *
+     * SSR-safe and never throws.
+     */
+    trackMarketingEvent(name: TrackingEventName, payload?: TrackingEventPayload): void;
+    /** Install the GTM container loader. Idempotent; no-op if already present. */
+    private loadGtm;
+    /** Install the Meta pixel and fire its initial PageView. Idempotent. */
+    private loadMetaPixel;
+    /** Install the TikTok pixel and fire its initial page view. Idempotent. */
+    private loadTikTokPixel;
     /**
      * Merge the resolved GA4 stitch ids onto a request body — only for fields
      * the caller didn't already set explicitly (explicit values always win).
@@ -10474,6 +10674,24 @@ declare class BrainerceClient {
         appId: string;
         name?: string | null;
     }>>;
+    /**
+     * List a region's manual price overrides (regional pricing, admin). Prices
+     * are in the region's currency; `variantId: null` rows are product-level.
+     */
+    getRegionPrices(regionId: string, params?: {
+        productId?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<RegionPrice>>;
+    /**
+     * Bulk upsert/remove manual price overrides for a region (admin). Each
+     * entry: `price` = regular, `salePrice` = sale (must be lower), in the
+     * REGION's currency; `remove: true` deletes. A product/variant with no
+     * entry keeps automatic FX conversion.
+     */
+    upsertRegionPrices(regionId: string, entries: RegionPriceEntry[]): Promise<UpsertRegionPricesResult>;
+    /** Delete one manual price override by id (admin). */
+    deleteRegionPrice(regionId: string, priceId: string): Promise<void>;
     /**
      * List the store's ACTIVE regions (public, no apiKey). Works in storeId and
      * vibe-coded modes. Returns only storefront-safe fields (no internal flags).
@@ -11126,7 +11344,7 @@ declare class BrainerceError extends Error {
     constructor(message: string, statusCode: number, details?: unknown);
 }
 
-declare const SDK_VERSION = "1.53.1";
+declare const SDK_VERSION = "1.54.0";
 
 /**
  * Verify a webhook signature from Brainerce
@@ -11524,4 +11742,4 @@ interface CategorySitemapOptions {
  */
 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 BusinessHoursWindow, 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 DateAvailabilityConstraints, type DateFieldParseResult, 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 MetafieldFilter, type MetafieldFilterValue, type MetafieldFiltersResponse, 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 ParsedDateFieldValue, 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, computeAvailableSlots, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getBlogSitemapEntries, getBusinessHoursForDate, getCartItemImage, getCartItemName, getCartTotals, getCategorySitemapEntries, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCalendarDateAllowed, isCouponApplicableToProduct, isDateValueAllowed, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseDateFieldValue, parseWebhookEvent, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };
+export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BlogPost, type BlogPostListParams, type BlogPostListResponse, type BlogSitemapOptions, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type BusinessHoursWindow, 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 DateAvailabilityConstraints, type DateFieldParseResult, 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 MetafieldFilter, type MetafieldFilterValue, type MetafieldFiltersResponse, 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 ParsedDateFieldValue, 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 StoreTracking, 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 TrackingEventItem, type TrackingEventName, type TrackingEventPayload, 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, computeAvailableSlots, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getBlogSitemapEntries, getBusinessHoursForDate, getCartItemImage, getCartItemName, getCartTotals, getCategorySitemapEntries, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCalendarDateAllowed, isCouponApplicableToProduct, isDateValueAllowed, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseDateFieldValue, parseWebhookEvent, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };

package/dist/index.js

@@ -98,7 +98,7 @@ var CART_GUARDS = [
 var CART_ITEM_GUARDS = [
   {
     property: "name",
-    message: 'CartItem has no "name" field. Use item.product.name or getCartItemName(item).\nImport: import { getCartItemName } from "brainerce";'
+    message: 'CartItem has no "name" field. Use getCartItemName(item) for the full\n"Product - Variant" label, or item.product.name for the product name alone.\nImport: import { getCartItemName } from "brainerce";'
   },
   {
     property: "price",
@@ -201,11 +201,29 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.53.1";
+var SDK_VERSION = "1.54.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
 var DEFAULT_TIMEOUT = 3e4;
+var META_EVENT_NAMES = {
+  view_item: "ViewContent",
+  add_to_cart: "AddToCart",
+  begin_checkout: "InitiateCheckout",
+  add_payment_info: "AddPaymentInfo",
+  purchase: "Purchase",
+  search: "Search",
+  sign_up: "CompleteRegistration"
+};
+var TIKTOK_EVENT_NAMES = {
+  view_item: "ViewContent",
+  add_to_cart: "AddToCart",
+  begin_checkout: "InitiateCheckout",
+  add_payment_info: "AddPaymentInfo",
+  purchase: "CompletePayment",
+  search: "Search",
+  sign_up: "CompleteRegistration"
+};
 var RTL_LOCALES = /* @__PURE__ */ new Set(["ar", "he", "fa", "ur", "yi"]);
 function getDirectionForLocale(locale) {
   if (!locale) return "ltr";
@@ -260,6 +278,12 @@ var _BrainerceClient = class _BrainerceClient {
     // GA4 stitch state (see `loadGoogleAnalytics()` in the Analytics section).
     this._ga4MeasurementId = null;
     this._ga4StitchPromise = null;
+    // Marketing tags booted by `initTracking()`. Each holds the id already
+    // loaded, which is what makes a repeat call a no-op instead of a second
+    // pixel install (and a doubled PageView).
+    this._gtmContainerId = null;
+    this._metaPixelId = null;
+    this._tiktokPixelId = null;
     /** One warning per client, not per keystroke-driven address submit. */
     this._warnedResolvedOnlyAddressFields = false;
     /** localStorage key for session cart reference (sessionToken + cartId) */
@@ -1281,6 +1305,225 @@ var _BrainerceClient = class _BrainerceClient {
       }
     });
   }
+  /**
+   * Boot every marketing tag the merchant has configured — GA4, Google Tag
+   * Manager, the Meta pixel, the TikTok pixel — in one call.
+   *
+   * Pass `storeInfo.tracking` straight through. The ids in it are resolved
+   * server-side from the marketplace apps the merchant already connected, so
+   * for the common case nobody types an id anywhere and nobody redeploys the
+   * storefront: connect the Google app in the dashboard and this call starts
+   * loading GA4 on the next page render.
+   *
+   * Call it once, as early as possible (root layout / app entry). It is
+   * idempotent, a no-op during SSR, and never throws — a blocked or missing
+   * tag must never take a storefront down with it.
+   *
+   * GA4 goes through {@link loadGoogleAnalytics}, so the `client_id` /
+   * `session_id` stitch ids keep flowing onto cart and checkout calls and the
+   * server-side purchase conversion still lands in the right session.
+   *
+   * @example
+   * ```typescript
+   * const storeInfo = await client.getStoreInfo();
+   * client.initTracking(storeInfo.tracking);
+   * // …later, on the order confirmation page:
+   * client.trackMarketingEvent('purchase', {
+   *   transactionId: order.id,
+   *   currency: order.currency,
+   *   value: order.totalAmount,
+   *   items: order.items.map((i) => ({ itemId: i.sku, itemName: i.name, price: i.price, quantity: i.quantity })),
+   * });
+   * ```
+   */
+  initTracking(tracking) {
+    if (typeof window === "undefined" || !tracking) return;
+    if (tracking.ga4MeasurementId) {
+      this.loadGoogleAnalytics(tracking.ga4MeasurementId);
+    }
+    if (tracking.gtmContainerId) this.loadGtm(tracking.gtmContainerId);
+    if (tracking.metaPixelId) this.loadMetaPixel(tracking.metaPixelId);
+    if (tracking.tiktokPixelId) this.loadTikTokPixel(tracking.tiktokPixelId);
+  }
+  /**
+   * Report one e-commerce event to every marketing tag that
+   * {@link initTracking} loaded (GA4/GTM, Meta, TikTok).
+   *
+   * Distinct from {@link trackEvent}, which posts a cookieless pageview/beacon
+   * to Brainerce's own storefront analytics. This one is about ad platforms —
+   * call both; they answer different questions.
+   *
+   * You describe what happened once, in GA4's vocabulary, and the SDK
+   * translates: a `dataLayer` push for GA4/GTM, the matching Meta standard
+   * event via `fbq`, and the matching TikTok event via `ttq`. Tags that aren't
+   * loaded are skipped silently, so the same call is correct whether the
+   * merchant has connected none, one, or all of them.
+   *
+   * Why this matters for ad spend: a GTM container with no `dataLayer` events
+   * is an empty container, and Meta cannot optimize a campaign it never sees a
+   * `Purchase` for. The value/currency/item-id triple in {@link TrackingEventPayload}
+   * is the whole input to that optimization.
+   *
+   * `purchase` is de-duplicated by the vendors on `transactionId` (GA4
+   * `transaction_id`, Meta `eventID`, TikTok `event_id`), so a shopper
+   * refreshing the confirmation page cannot double-count the order — pass the
+   * order id and the safety is automatic.
+   *
+   * SSR-safe and never throws.
+   */
+  trackMarketingEvent(name, payload = {}) {
+    if (typeof window === "undefined") return;
+    try {
+      const items = payload.items ?? [];
+      window.dataLayer = window.dataLayer || [];
+      window.dataLayer.push({ ecommerce: null });
+      window.dataLayer.push({
+        event: name,
+        ecommerce: {
+          ...payload.currency ? { currency: payload.currency } : {},
+          ...payload.value !== void 0 ? { value: payload.value } : {},
+          ...payload.transactionId ? { transaction_id: payload.transactionId } : {},
+          ...payload.shipping !== void 0 ? { shipping: payload.shipping } : {},
+          ...payload.tax !== void 0 ? { tax: payload.tax } : {},
+          ...payload.coupon ? { coupon: payload.coupon } : {},
+          items: items.map((item) => ({
+            item_id: item.itemId,
+            ...item.itemName ? { item_name: item.itemName } : {},
+            ...item.price !== void 0 ? { price: item.price } : {},
+            ...item.quantity !== void 0 ? { quantity: item.quantity } : {},
+            ...item.itemVariant ? { item_variant: item.itemVariant } : {},
+            ...item.itemCategory ? { item_category: item.itemCategory } : {}
+          }))
+        }
+      });
+      if (window.gtag && this._ga4MeasurementId) {
+        window.gtag("event", name, {
+          ...payload.currency ? { currency: payload.currency } : {},
+          ...payload.value !== void 0 ? { value: payload.value } : {},
+          ...payload.transactionId ? { transaction_id: payload.transactionId } : {},
+          ...payload.shipping !== void 0 ? { shipping: payload.shipping } : {},
+          ...payload.tax !== void 0 ? { tax: payload.tax } : {},
+          ...payload.coupon ? { coupon: payload.coupon } : {},
+          items: items.map((item) => ({
+            item_id: item.itemId,
+            item_name: item.itemName,
+            price: item.price,
+            quantity: item.quantity
+          }))
+        });
+      }
+      const metaEvent = META_EVENT_NAMES[name];
+      if (window.fbq && metaEvent) {
+        const contents = items.map((item) => ({
+          id: item.itemId,
+          quantity: item.quantity ?? 1,
+          ...item.price !== void 0 ? { item_price: item.price } : {}
+        }));
+        window.fbq(
+          "track",
+          metaEvent,
+          {
+            ...payload.currency ? { currency: payload.currency } : {},
+            ...payload.value !== void 0 ? { value: payload.value } : {},
+            ...contents.length ? { contents, content_ids: contents.map((c) => c.id), content_type: "product" } : {}
+          },
+          // Meta de-dupes a browser event against a server (CAPI) event of the
+          // same eventID, and against a repeat send of the same page.
+          payload.transactionId ? { eventID: payload.transactionId } : void 0
+        );
+      }
+      const tiktokEvent = TIKTOK_EVENT_NAMES[name];
+      if (window.ttq?.track && tiktokEvent) {
+        window.ttq.track(
+          tiktokEvent,
+          {
+            ...payload.currency ? { currency: payload.currency } : {},
+            ...payload.value !== void 0 ? { value: payload.value } : {},
+            contents: items.map((item) => ({
+              content_id: item.itemId,
+              content_name: item.itemName,
+              quantity: item.quantity ?? 1,
+              price: item.price
+            }))
+          },
+          payload.transactionId ? { event_id: payload.transactionId } : void 0
+        );
+      }
+    } catch {
+    }
+  }
+  /** Install the GTM container loader. Idempotent; no-op if already present. */
+  loadGtm(containerId) {
+    if (this._gtmContainerId === containerId) return;
+    this._gtmContainerId = containerId;
+    try {
+      window.dataLayer = window.dataLayer || [];
+      window.dataLayer.push({ "gtm.start": Date.now(), event: "gtm.js" });
+      const script = document.createElement("script");
+      script.async = true;
+      script.src = `https://www.googletagmanager.com/gtm.js?id=${encodeURIComponent(containerId)}`;
+      document.head.appendChild(script);
+    } catch {
+    }
+  }
+  /** Install the Meta pixel and fire its initial PageView. Idempotent. */
+  loadMetaPixel(pixelId) {
+    if (this._metaPixelId === pixelId) return;
+    this._metaPixelId = pixelId;
+    try {
+      if (!window.fbq) {
+        const queue = [];
+        const fbq = ((...args) => {
+          if (fbq.callMethod) fbq.callMethod(...args);
+          else queue.push(args);
+        });
+        fbq.queue = queue;
+        fbq.loaded = true;
+        fbq.version = "2.0";
+        window.fbq = fbq;
+        window._fbq = fbq;
+        const script = document.createElement("script");
+        script.async = true;
+        script.src = "https://connect.facebook.net/en_US/fbevents.js";
+        document.head.appendChild(script);
+      }
+      window.fbq("init", pixelId);
+      window.fbq("track", "PageView");
+    } catch {
+    }
+  }
+  /** Install the TikTok pixel and fire its initial page view. Idempotent. */
+  loadTikTokPixel(pixelId) {
+    if (this._tiktokPixelId === pixelId) return;
+    this._tiktokPixelId = pixelId;
+    try {
+      const ttq = window.ttq ?? {};
+      ttq._i = ttq._i ?? {};
+      ttq._i[pixelId] = ttq._i[pixelId] ?? [];
+      ttq._t = ttq._t ?? {};
+      ttq._t[pixelId] = Date.now();
+      ttq._o = ttq._o ?? {};
+      ttq._o[pixelId] = {};
+      const methods = ["page", "track", "identify", "instances", "ready"];
+      ttq.methods = methods;
+      for (const method of methods) {
+        if (typeof ttq[method] !== "function") {
+          ttq[method] = (...args) => {
+            ttq._i?.[pixelId]?.push([method, ...args]);
+          };
+        }
+      }
+      window.ttq = ttq;
+      const script = document.createElement("script");
+      script.async = true;
+      script.src = `https://analytics.tiktok.com/i18n/pixel/events.js?sdkid=${encodeURIComponent(
+        pixelId
+      )}&lib=ttq`;
+      document.head.appendChild(script);
+      ttq.page?.();
+    } catch {
+    }
+  }
   /**
    * Merge the resolved GA4 stitch ids onto a request body — only for fields
    * the caller didn't already set explicitly (explicit values always win).
@@ -5201,9 +5444,7 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async setShippingAddress(checkoutId, address) {
-    const body = await this.withAnalyticsStitchIds(
-      this.stripResolvedOnlyAddressFields(address)
-    );
+    const body = await this.withAnalyticsStitchIds(this.stripResolvedOnlyAddressFields(address));
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
@@ -8260,6 +8501,42 @@ var _BrainerceClient = class _BrainerceClient {
       `/api/v1/regions/${encodePathSegment(regionId)}/compatible-providers`
     );
   }
+  /**
+   * List a region's manual price overrides (regional pricing, admin). Prices
+   * are in the region's currency; `variantId: null` rows are product-level.
+   */
+  async getRegionPrices(regionId, params = {}) {
+    return this.adminRequest(
+      "GET",
+      `/api/v1/regions/${encodePathSegment(regionId)}/prices`,
+      void 0,
+      {
+        productId: params.productId,
+        page: params.page,
+        limit: params.limit
+      }
+    );
+  }
+  /**
+   * Bulk upsert/remove manual price overrides for a region (admin). Each
+   * entry: `price` = regular, `salePrice` = sale (must be lower), in the
+   * REGION's currency; `remove: true` deletes. A product/variant with no
+   * entry keeps automatic FX conversion.
+   */
+  async upsertRegionPrices(regionId, entries) {
+    return this.adminRequest(
+      "PUT",
+      `/api/v1/regions/${encodePathSegment(regionId)}/prices`,
+      { entries }
+    );
+  }
+  /** Delete one manual price override by id (admin). */
+  async deleteRegionPrice(regionId, priceId) {
+    await this.adminRequest(
+      "DELETE",
+      `/api/v1/regions/${encodePathSegment(regionId)}/prices/${encodePathSegment(priceId)}`
+    );
+  }
   // -------------------- Regions (Storefront + vibe-coded, public — no apiKey) --------------------
   // storeId- or connectionId-based, no auth. Call these from a storefront to
   // detect the buyer's region (story S1), then pair with detectRegion(). Then
@@ -10209,7 +10486,10 @@ function getCartTotals(cart, shippingPrice) {
   return { subtotal, discount, shipping, total };
 }
 function getCartItemName(item) {
-  return item.variant?.name || item.product.name;
+  const productName = item.product.name;
+  const variantName = item.variant?.name?.trim();
+  if (!variantName || variantName === productName) return productName;
+  return `${productName} - ${variantName}`;
 }
 function getCartItemImage(item) {
   if (item.variant?.image) {