brainerce 1.56.0 → 1.58.0

package/README.md

@@ -290,6 +290,7 @@ The SDK exports these utility functions for common UI tasks:
 | `buildArticleJsonLd(post, opts)`               | schema.org Article JSON-LD for blog posts                                                    | See SEO section                                        |
 | `buildOrganizationJsonLd(store, opts)`         | schema.org Organization for the homepage                                                     | See SEO section                                        |
 | `buildBreadcrumbJsonLd(items)`                 | schema.org BreadcrumbList                                                                    | See SEO section                                        |
+| `buildProductFaqJsonLd(product)`               | schema.org FAQPage from `product.faq` (null when empty) — render the same pairs as visible text | `const faq = buildProductFaqJsonLd(product)`        |
 | `jsonLdScriptProps(data)`                      | XSS-safe `<script type="application/ld+json">` props                                         | `<script {...jsonLdScriptProps(data)} />`              |
 | `getBlogSitemapEntries(client, opts)`          | Paginate published posts into sitemap entries                                                | See SEO section                                        |
 | `getProductSitemapEntries(client, opts)`       | ALL published products into sitemap entries (no 100-item clamp)                              | See SEO section                                        |
@@ -495,6 +496,8 @@ import {
   buildOrganizationJsonLd,   // homepage
   buildCollectionPageJsonLd, // category landing pages
   buildBreadcrumbJsonLd,
+  buildProductFaqJsonLd,     // FAQPage from product.faq (returns null when empty);
+                             // ALWAYS render the same Q&A as visible text on the page
   jsonLdScriptProps,         // XSS-safe <script> props
 } from 'brainerce';
 
@@ -2457,6 +2460,10 @@ const checkout = await client.setCheckoutCustomer(checkoutId, {
   notes: 'Please leave the package at the door', // Optional order note (max 2000 chars)
   // analyticsClientId / analyticsSessionId: auto-attached if you called
   // loadGoogleAnalytics() — no need to pass these yourself.
+  // trafficReferrerHost / trafficUtm*: auto-attached from the SDK's own
+  // traffic-attribution capture (external referrer + utm, 30-day window) so
+  // the dashboard can report "orders from ChatGPT / Google / …". Nothing to
+  // wire up; pass explicitly only to override.
 });
 ```
 
@@ -4094,6 +4101,15 @@ const cart = await client.createCart();
 await client.addToCart(cart.id, { productId: 'prod_abc', quantity: 1 });
 ```
 
+### Traffic attribution (automatic, zero-config)
+
+The SDK also records where each visit came from — the external referrer host
+and any `utm_source`/`utm_medium`/`utm_campaign` — as a **last non-direct
+touch** (`brainerce_attr` in localStorage, 30-day window). The captured values
+are auto-attached to `setCheckoutCustomer()` / `setShippingAddress()` and end
+up on the order, powering the dashboard's "orders from ChatGPT / Google / …"
+reporting. Nothing to configure; a value you pass explicitly always wins.
+
 What this does:
 
 - Idempotently injects `gtag.js` and initializes `dataLayer` (skips injection if you're already loading `gtag.js` yourself — safe to call either way).

package/dist/index.d.mts

@@ -626,6 +626,16 @@ interface Product {
     gtin?: string | null;
     /** Manufacturer Part Number. Emitted in Product JSON-LD. */
     mpn?: string | null;
+    /**
+     * Product Q&A pairs (AI-generated from real product data or merchant-
+     * edited). Render as a visible FAQ section on the product page and emit
+     * `buildProductFaqJsonLd(product)` — the extractable question/answer format
+     * AI answer engines cite.
+     */
+    faq?: Array<{
+        q: string;
+        a: string;
+    }> | null;
     /**
      * Base price as string (e.g., "29.99"). Use parseFloat() for calculations.
      *
@@ -3294,6 +3304,16 @@ interface SetCheckoutCustomerDto {
      */
     analyticsClientId?: string;
     analyticsSessionId?: string;
+    /**
+     * Traffic attribution (last non-direct touch) — auto-attached by the SDK
+     * from its `brainerce_attr` capture (external referrer host + utm params,
+     * 30-day window). Lets the dashboard report "orders from ChatGPT/Google/…".
+     * Pass explicitly to override; omit to use the captured values.
+     */
+    trafficReferrerHost?: string;
+    trafficUtmSource?: string;
+    trafficUtmMedium?: string;
+    trafficUtmCampaign?: string;
 }
 /**
  * Shipping address with customer email (required for checkout).
@@ -3327,6 +3347,16 @@ interface SetShippingAddressDto {
      */
     analyticsClientId?: string;
     analyticsSessionId?: string;
+    /**
+     * Traffic attribution (last non-direct touch) — auto-attached by the SDK
+     * from its `brainerce_attr` capture (external referrer host + utm params,
+     * 30-day window). Lets the dashboard report "orders from ChatGPT/Google/…".
+     * Pass explicitly to override; omit to use the captured values.
+     */
+    trafficReferrerHost?: string;
+    trafficUtmSource?: string;
+    trafficUtmMedium?: string;
+    trafficUtmCampaign?: string;
     /**
      * The `placeId` of the autocomplete suggestion the shopper picked (from
      * `addressAutocomplete()`). Send it whenever the address came from the
@@ -6847,6 +6877,26 @@ declare class BrainerceClient {
      * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
      * called, or if it hasn't resolved any ids by the time this is awaited.
      */
+    /** localStorage key holding the last non-direct-touch attribution blob. */
+    private readonly TRAFFIC_ATTR_KEY;
+    /** Attribution older than this is stale and never forwarded (classic 30-day window). */
+    private static readonly TRAFFIC_ATTR_MAX_AGE_MS;
+    /**
+     * Record the visit's traffic origin — LAST NON-DIRECT TOUCH semantics: an
+     * external referrer or any utm_source overwrites the stored blob; a direct
+     * or internal navigation keeps the previous touch. Runs once per client
+     * construction (i.e. per page load in browser storefronts) and must never
+     * throw — attribution is telemetry, the storefront always wins.
+     */
+    private captureTrafficAttribution;
+    /** The stored attribution as request-body fields, or null when absent/stale. */
+    private getTrafficAttribution;
+    /**
+     * Merge the stored traffic attribution onto a request body — only for
+     * fields the caller didn't set explicitly (explicit values always win),
+     * mirroring `withAnalyticsStitchIds`. No-op outside the browser.
+     */
+    private withTrafficAttribution;
     private withAnalyticsStitchIds;
     /**
      * Drop the fields `getAddressDetails()` returns that no address endpoint
@@ -11799,6 +11849,18 @@ declare function buildWebsiteJsonLd(store: StoreInfo, opts: JsonLdOptions & {
  * {@link buildBreadcrumbJsonLd} built from `category.breadcrumb`.
  */
 declare function buildCollectionPageJsonLd(category: Pick<CategoryDetail, 'name' | 'description' | 'metaDescription' | 'image'>, opts: JsonLdOptions): JsonLd;
+/**
+ * schema.org/FAQPage from a product's Q&A pairs. Returns null when the
+ * product carries no Q&A, so callers can conditionally render the script tag.
+ * Keep the SAME pairs visible as text on the page — engines extract from
+ * rendered HTML; the schema is corroboration, not a substitute.
+ */
+declare function buildProductFaqJsonLd(product: {
+    faq?: Array<{
+        q: string;
+        a: string;
+    }> | null;
+}): JsonLd | null;
 /** schema.org/BreadcrumbList. Items in order from root to current page. */
 declare function buildBreadcrumbJsonLd(items: Array<{
     name: string;
@@ -11901,4 +11963,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 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 ProductSitemapOptions, 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, getProductSitemapEntries, 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 ProductSitemapOptions, 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, buildProductFaqJsonLd, 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, getProductSitemapEntries, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCalendarDateAllowed, isCouponApplicableToProduct, isDateValueAllowed, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseDateFieldValue, parseWebhookEvent, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };

package/dist/index.d.ts

@@ -626,6 +626,16 @@ interface Product {
     gtin?: string | null;
     /** Manufacturer Part Number. Emitted in Product JSON-LD. */
     mpn?: string | null;
+    /**
+     * Product Q&A pairs (AI-generated from real product data or merchant-
+     * edited). Render as a visible FAQ section on the product page and emit
+     * `buildProductFaqJsonLd(product)` — the extractable question/answer format
+     * AI answer engines cite.
+     */
+    faq?: Array<{
+        q: string;
+        a: string;
+    }> | null;
     /**
      * Base price as string (e.g., "29.99"). Use parseFloat() for calculations.
      *
@@ -3294,6 +3304,16 @@ interface SetCheckoutCustomerDto {
      */
     analyticsClientId?: string;
     analyticsSessionId?: string;
+    /**
+     * Traffic attribution (last non-direct touch) — auto-attached by the SDK
+     * from its `brainerce_attr` capture (external referrer host + utm params,
+     * 30-day window). Lets the dashboard report "orders from ChatGPT/Google/…".
+     * Pass explicitly to override; omit to use the captured values.
+     */
+    trafficReferrerHost?: string;
+    trafficUtmSource?: string;
+    trafficUtmMedium?: string;
+    trafficUtmCampaign?: string;
 }
 /**
  * Shipping address with customer email (required for checkout).
@@ -3327,6 +3347,16 @@ interface SetShippingAddressDto {
      */
     analyticsClientId?: string;
     analyticsSessionId?: string;
+    /**
+     * Traffic attribution (last non-direct touch) — auto-attached by the SDK
+     * from its `brainerce_attr` capture (external referrer host + utm params,
+     * 30-day window). Lets the dashboard report "orders from ChatGPT/Google/…".
+     * Pass explicitly to override; omit to use the captured values.
+     */
+    trafficReferrerHost?: string;
+    trafficUtmSource?: string;
+    trafficUtmMedium?: string;
+    trafficUtmCampaign?: string;
     /**
      * The `placeId` of the autocomplete suggestion the shopper picked (from
      * `addressAutocomplete()`). Send it whenever the address came from the
@@ -6847,6 +6877,26 @@ declare class BrainerceClient {
      * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
      * called, or if it hasn't resolved any ids by the time this is awaited.
      */
+    /** localStorage key holding the last non-direct-touch attribution blob. */
+    private readonly TRAFFIC_ATTR_KEY;
+    /** Attribution older than this is stale and never forwarded (classic 30-day window). */
+    private static readonly TRAFFIC_ATTR_MAX_AGE_MS;
+    /**
+     * Record the visit's traffic origin — LAST NON-DIRECT TOUCH semantics: an
+     * external referrer or any utm_source overwrites the stored blob; a direct
+     * or internal navigation keeps the previous touch. Runs once per client
+     * construction (i.e. per page load in browser storefronts) and must never
+     * throw — attribution is telemetry, the storefront always wins.
+     */
+    private captureTrafficAttribution;
+    /** The stored attribution as request-body fields, or null when absent/stale. */
+    private getTrafficAttribution;
+    /**
+     * Merge the stored traffic attribution onto a request body — only for
+     * fields the caller didn't set explicitly (explicit values always win),
+     * mirroring `withAnalyticsStitchIds`. No-op outside the browser.
+     */
+    private withTrafficAttribution;
     private withAnalyticsStitchIds;
     /**
      * Drop the fields `getAddressDetails()` returns that no address endpoint
@@ -11799,6 +11849,18 @@ declare function buildWebsiteJsonLd(store: StoreInfo, opts: JsonLdOptions & {
  * {@link buildBreadcrumbJsonLd} built from `category.breadcrumb`.
  */
 declare function buildCollectionPageJsonLd(category: Pick<CategoryDetail, 'name' | 'description' | 'metaDescription' | 'image'>, opts: JsonLdOptions): JsonLd;
+/**
+ * schema.org/FAQPage from a product's Q&A pairs. Returns null when the
+ * product carries no Q&A, so callers can conditionally render the script tag.
+ * Keep the SAME pairs visible as text on the page — engines extract from
+ * rendered HTML; the schema is corroboration, not a substitute.
+ */
+declare function buildProductFaqJsonLd(product: {
+    faq?: Array<{
+        q: string;
+        a: string;
+    }> | null;
+}): JsonLd | null;
 /** schema.org/BreadcrumbList. Items in order from root to current page. */
 declare function buildBreadcrumbJsonLd(items: Array<{
     name: string;
@@ -11901,4 +11963,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 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 ProductSitemapOptions, 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, getProductSitemapEntries, 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 ProductSitemapOptions, 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, buildProductFaqJsonLd, 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, getProductSitemapEntries, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCalendarDateAllowed, isCouponApplicableToProduct, isDateValueAllowed, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseDateFieldValue, parseWebhookEvent, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };

package/dist/index.js

@@ -38,6 +38,7 @@ __export(index_exports, {
   buildBreadcrumbJsonLd: () => buildBreadcrumbJsonLd,
   buildCollectionPageJsonLd: () => buildCollectionPageJsonLd,
   buildOrganizationJsonLd: () => buildOrganizationJsonLd,
+  buildProductFaqJsonLd: () => buildProductFaqJsonLd,
   buildProductJsonLd: () => buildProductJsonLd,
   buildWebsiteJsonLd: () => buildWebsiteJsonLd,
   computeAvailableSlots: () => computeAvailableSlots,
@@ -299,6 +300,14 @@ var _BrainerceClient = class _BrainerceClient {
      * This is needed because Stripe redirects lose in-memory state.
      */
     this.ACTIVE_CHECKOUT_KEY = "brainerce_active_checkout";
+    /**
+     * Merge the resolved GA4 stitch ids onto a request body — only for fields
+     * the caller didn't already set explicitly (explicit values always win).
+     * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
+     * called, or if it hasn't resolved any ids by the time this is awaited.
+     */
+    /** localStorage key holding the last non-direct-touch attribution blob. */
+    this.TRAFFIC_ATTR_KEY = "brainerce_attr";
     // -------------------- Contact Forms (schema) --------------------
     /**
      * List active contact forms configured for the store.
@@ -704,6 +713,7 @@ var _BrainerceClient = class _BrainerceClient {
     this.onCartReset = options.onCartReset;
     this.hydrateSessionCart();
     this.detectRecoverCartFromUrl();
+    this.captureTrafficAttribution();
   }
   // -------------------- Locale --------------------
   /**
@@ -1526,11 +1536,82 @@ var _BrainerceClient = class _BrainerceClient {
     }
   }
   /**
-   * Merge the resolved GA4 stitch ids onto a request body — only for fields
-   * the caller didn't already set explicitly (explicit values always win).
-   * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
-   * called, or if it hasn't resolved any ids by the time this is awaited.
+   * Record the visit's traffic origin — LAST NON-DIRECT TOUCH semantics: an
+   * external referrer or any utm_source overwrites the stored blob; a direct
+   * or internal navigation keeps the previous touch. Runs once per client
+   * construction (i.e. per page load in browser storefronts) and must never
+   * throw — attribution is telemetry, the storefront always wins.
+   */
+  captureTrafficAttribution() {
+    try {
+      if (typeof window === "undefined" || !window.localStorage) return;
+      const params = new URLSearchParams(window.location.search);
+      const utmSource = params.get("utm_source") || void 0;
+      const utmMedium = params.get("utm_medium") || void 0;
+      const utmCampaign = params.get("utm_campaign") || void 0;
+      let referrerHost;
+      if (document.referrer) {
+        try {
+          const ref = new URL(document.referrer);
+          if (ref.hostname && ref.hostname !== window.location.hostname) {
+            referrerHost = ref.hostname.toLowerCase().replace(/^www\./, "");
+          }
+        } catch {
+        }
+      }
+      if (!referrerHost && !utmSource) return;
+      window.localStorage.setItem(
+        this.TRAFFIC_ATTR_KEY,
+        JSON.stringify({ referrerHost, utmSource, utmMedium, utmCampaign, at: Date.now() })
+      );
+    } catch {
+    }
+  }
+  /** The stored attribution as request-body fields, or null when absent/stale. */
+  getTrafficAttribution() {
+    try {
+      if (typeof window === "undefined" || !window.localStorage) return null;
+      const raw = window.localStorage.getItem(this.TRAFFIC_ATTR_KEY);
+      if (!raw) return null;
+      const blob = JSON.parse(raw);
+      if (!blob || typeof blob !== "object") return null;
+      if (typeof blob.at !== "number" || Date.now() - blob.at > _BrainerceClient.TRAFFIC_ATTR_MAX_AGE_MS) {
+        return null;
+      }
+      const out = {};
+      if (typeof blob.referrerHost === "string" && blob.referrerHost) {
+        out.trafficReferrerHost = blob.referrerHost.slice(0, 253);
+      }
+      if (typeof blob.utmSource === "string" && blob.utmSource) {
+        out.trafficUtmSource = blob.utmSource.slice(0, 150);
+      }
+      if (typeof blob.utmMedium === "string" && blob.utmMedium) {
+        out.trafficUtmMedium = blob.utmMedium.slice(0, 150);
+      }
+      if (typeof blob.utmCampaign === "string" && blob.utmCampaign) {
+        out.trafficUtmCampaign = blob.utmCampaign.slice(0, 150);
+      }
+      return Object.keys(out).length > 0 ? out : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Merge the stored traffic attribution onto a request body — only for
+   * fields the caller didn't set explicitly (explicit values always win),
+   * mirroring `withAnalyticsStitchIds`. No-op outside the browser.
    */
+  withTrafficAttribution(dto) {
+    const attr = this.getTrafficAttribution();
+    if (!attr) return dto;
+    return {
+      ...dto ?? {},
+      trafficReferrerHost: dto?.trafficReferrerHost ?? attr.trafficReferrerHost,
+      trafficUtmSource: dto?.trafficUtmSource ?? attr.trafficUtmSource,
+      trafficUtmMedium: dto?.trafficUtmMedium ?? attr.trafficUtmMedium,
+      trafficUtmCampaign: dto?.trafficUtmCampaign ?? attr.trafficUtmCampaign
+    };
+  }
   async withAnalyticsStitchIds(dto) {
     if (!this._ga4StitchPromise) return dto;
     try {
@@ -5387,7 +5468,7 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async setCheckoutCustomer(checkoutId, data) {
-    const body = await this.withAnalyticsStitchIds(data);
+    const body = this.withTrafficAttribution(await this.withAnalyticsStitchIds(data));
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
@@ -5489,7 +5570,9 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async setShippingAddress(checkoutId, address) {
-    const body = await this.withAnalyticsStitchIds(this.stripResolvedOnlyAddressFields(address));
+    const body = this.withTrafficAttribution(
+      await this.withAnalyticsStitchIds(this.stripResolvedOnlyAddressFields(address))
+    );
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
@@ -9716,6 +9799,8 @@ _BrainerceClient.RESOLVED_ONLY_ADDRESS_FIELDS = [
   "lng",
   "formattedAddress"
 ];
+/** Attribution older than this is stale and never forwarded (classic 30-day window). */
+_BrainerceClient.TRAFFIC_ATTR_MAX_AGE_MS = 30 * 24 * 3600 * 1e3;
 var BrainerceClient = _BrainerceClient;
 var BrainerceError = class extends Error {
   constructor(message, statusCode, details) {
@@ -10340,6 +10425,21 @@ function buildCollectionPageJsonLd(category, opts) {
     ...category.image ? { image: [category.image] } : {}
   };
 }
+function buildProductFaqJsonLd(product) {
+  const pairs = (product.faq ?? []).filter(
+    (i) => typeof i?.q === "string" && typeof i?.a === "string" && i.q && i.a
+  );
+  if (pairs.length === 0) return null;
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: pairs.map((i) => ({
+      "@type": "Question",
+      name: i.q,
+      acceptedAnswer: { "@type": "Answer", text: i.a }
+    }))
+  };
+}
 function buildBreadcrumbJsonLd(items) {
   return {
     "@context": "https://schema.org",
@@ -10730,6 +10830,7 @@ function isCouponApplicableToProduct(coupon, productId) {
   buildBreadcrumbJsonLd,
   buildCollectionPageJsonLd,
   buildOrganizationJsonLd,
+  buildProductFaqJsonLd,
   buildProductJsonLd,
   buildWebsiteJsonLd,
   computeAvailableSlots,

package/dist/index.mjs

@@ -212,6 +212,14 @@ var _BrainerceClient = class _BrainerceClient {
      * This is needed because Stripe redirects lose in-memory state.
      */
     this.ACTIVE_CHECKOUT_KEY = "brainerce_active_checkout";
+    /**
+     * Merge the resolved GA4 stitch ids onto a request body — only for fields
+     * the caller didn't already set explicitly (explicit values always win).
+     * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
+     * called, or if it hasn't resolved any ids by the time this is awaited.
+     */
+    /** localStorage key holding the last non-direct-touch attribution blob. */
+    this.TRAFFIC_ATTR_KEY = "brainerce_attr";
     // -------------------- Contact Forms (schema) --------------------
     /**
      * List active contact forms configured for the store.
@@ -617,6 +625,7 @@ var _BrainerceClient = class _BrainerceClient {
     this.onCartReset = options.onCartReset;
     this.hydrateSessionCart();
     this.detectRecoverCartFromUrl();
+    this.captureTrafficAttribution();
   }
   // -------------------- Locale --------------------
   /**
@@ -1439,11 +1448,82 @@ var _BrainerceClient = class _BrainerceClient {
     }
   }
   /**
-   * Merge the resolved GA4 stitch ids onto a request body — only for fields
-   * the caller didn't already set explicitly (explicit values always win).
-   * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
-   * called, or if it hasn't resolved any ids by the time this is awaited.
+   * Record the visit's traffic origin — LAST NON-DIRECT TOUCH semantics: an
+   * external referrer or any utm_source overwrites the stored blob; a direct
+   * or internal navigation keeps the previous touch. Runs once per client
+   * construction (i.e. per page load in browser storefronts) and must never
+   * throw — attribution is telemetry, the storefront always wins.
+   */
+  captureTrafficAttribution() {
+    try {
+      if (typeof window === "undefined" || !window.localStorage) return;
+      const params = new URLSearchParams(window.location.search);
+      const utmSource = params.get("utm_source") || void 0;
+      const utmMedium = params.get("utm_medium") || void 0;
+      const utmCampaign = params.get("utm_campaign") || void 0;
+      let referrerHost;
+      if (document.referrer) {
+        try {
+          const ref = new URL(document.referrer);
+          if (ref.hostname && ref.hostname !== window.location.hostname) {
+            referrerHost = ref.hostname.toLowerCase().replace(/^www\./, "");
+          }
+        } catch {
+        }
+      }
+      if (!referrerHost && !utmSource) return;
+      window.localStorage.setItem(
+        this.TRAFFIC_ATTR_KEY,
+        JSON.stringify({ referrerHost, utmSource, utmMedium, utmCampaign, at: Date.now() })
+      );
+    } catch {
+    }
+  }
+  /** The stored attribution as request-body fields, or null when absent/stale. */
+  getTrafficAttribution() {
+    try {
+      if (typeof window === "undefined" || !window.localStorage) return null;
+      const raw = window.localStorage.getItem(this.TRAFFIC_ATTR_KEY);
+      if (!raw) return null;
+      const blob = JSON.parse(raw);
+      if (!blob || typeof blob !== "object") return null;
+      if (typeof blob.at !== "number" || Date.now() - blob.at > _BrainerceClient.TRAFFIC_ATTR_MAX_AGE_MS) {
+        return null;
+      }
+      const out = {};
+      if (typeof blob.referrerHost === "string" && blob.referrerHost) {
+        out.trafficReferrerHost = blob.referrerHost.slice(0, 253);
+      }
+      if (typeof blob.utmSource === "string" && blob.utmSource) {
+        out.trafficUtmSource = blob.utmSource.slice(0, 150);
+      }
+      if (typeof blob.utmMedium === "string" && blob.utmMedium) {
+        out.trafficUtmMedium = blob.utmMedium.slice(0, 150);
+      }
+      if (typeof blob.utmCampaign === "string" && blob.utmCampaign) {
+        out.trafficUtmCampaign = blob.utmCampaign.slice(0, 150);
+      }
+      return Object.keys(out).length > 0 ? out : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Merge the stored traffic attribution onto a request body — only for
+   * fields the caller didn't set explicitly (explicit values always win),
+   * mirroring `withAnalyticsStitchIds`. No-op outside the browser.
    */
+  withTrafficAttribution(dto) {
+    const attr = this.getTrafficAttribution();
+    if (!attr) return dto;
+    return {
+      ...dto ?? {},
+      trafficReferrerHost: dto?.trafficReferrerHost ?? attr.trafficReferrerHost,
+      trafficUtmSource: dto?.trafficUtmSource ?? attr.trafficUtmSource,
+      trafficUtmMedium: dto?.trafficUtmMedium ?? attr.trafficUtmMedium,
+      trafficUtmCampaign: dto?.trafficUtmCampaign ?? attr.trafficUtmCampaign
+    };
+  }
   async withAnalyticsStitchIds(dto) {
     if (!this._ga4StitchPromise) return dto;
     try {
@@ -5300,7 +5380,7 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async setCheckoutCustomer(checkoutId, data) {
-    const body = await this.withAnalyticsStitchIds(data);
+    const body = this.withTrafficAttribution(await this.withAnalyticsStitchIds(data));
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
@@ -5402,7 +5482,9 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async setShippingAddress(checkoutId, address) {
-    const body = await this.withAnalyticsStitchIds(this.stripResolvedOnlyAddressFields(address));
+    const body = this.withTrafficAttribution(
+      await this.withAnalyticsStitchIds(this.stripResolvedOnlyAddressFields(address))
+    );
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
@@ -9629,6 +9711,8 @@ _BrainerceClient.RESOLVED_ONLY_ADDRESS_FIELDS = [
   "lng",
   "formattedAddress"
 ];
+/** Attribution older than this is stale and never forwarded (classic 30-day window). */
+_BrainerceClient.TRAFFIC_ATTR_MAX_AGE_MS = 30 * 24 * 3600 * 1e3;
 var BrainerceClient = _BrainerceClient;
 var BrainerceError = class extends Error {
   constructor(message, statusCode, details) {
@@ -10253,6 +10337,21 @@ function buildCollectionPageJsonLd(category, opts) {
     ...category.image ? { image: [category.image] } : {}
   };
 }
+function buildProductFaqJsonLd(product) {
+  const pairs = (product.faq ?? []).filter(
+    (i) => typeof i?.q === "string" && typeof i?.a === "string" && i.q && i.a
+  );
+  if (pairs.length === 0) return null;
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: pairs.map((i) => ({
+      "@type": "Question",
+      name: i.q,
+      acceptedAnswer: { "@type": "Answer", text: i.a }
+    }))
+  };
+}
 function buildBreadcrumbJsonLd(items) {
   return {
     "@context": "https://schema.org",
@@ -10642,6 +10741,7 @@ export {
   buildBreadcrumbJsonLd,
   buildCollectionPageJsonLd,
   buildOrganizationJsonLd,
+  buildProductFaqJsonLd,
   buildProductJsonLd,
   buildWebsiteJsonLd,
   computeAvailableSlots,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.56.0",
+  "version": "1.58.0",
   "description": "Official SDK for building e-commerce storefronts with Brainerce Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",