brainerce 1.11.0 → 1.12.0

package/README.md

@@ -2827,11 +2827,70 @@ const brand = await client.createBrand({ name: 'Nike', slug: 'nike' });
 const tags = await client.listTags();
 const tag = await client.createTag({ name: 'Sale', slug: 'sale' });
 
-// Attributes (for variant options)
+// Attributes (for variant options like Size, Color, Material)
 const attributes = await client.listAttributes();
-const attribute = await client.createAttribute({ name: 'Color', slug: 'color' });
-const options = await client.getAttributeOptions('attr_id');
-await client.createAttributeOption('attr_id', { value: 'Red', slug: 'red' });
+
+// Create a color swatch attribute
+const colorAttr = await client.createAttribute({
+  name: 'Color',
+  displayType: 'COLOR_SWATCH', // Options: 'DEFAULT' | 'COLOR_SWATCH' | 'IMAGE_SWATCH'
+  source: 'GLOBAL',
+});
+
+// Add color swatch options
+await client.createAttributeOption(colorAttr.id, {
+  name: 'Red',
+  value: 'red',
+  swatchColor: '#FF0000',
+  source: 'GLOBAL',
+});
+
+// Gradient swatch (two colors)
+await client.createAttributeOption(colorAttr.id, {
+  name: 'Sunset',
+  value: 'sunset',
+  swatchColor: '#FF6B35',
+  swatchColor2: '#FFD700',
+  source: 'GLOBAL',
+});
+
+// Image swatch attribute
+const materialAttr = await client.createAttribute({
+  name: 'Material',
+  displayType: 'IMAGE_SWATCH',
+  source: 'GLOBAL',
+});
+await client.createAttributeOption(materialAttr.id, {
+  name: 'Leather',
+  value: 'leather',
+  swatchImageUrl: 'https://example.com/leather-texture.jpg',
+  source: 'GLOBAL',
+});
+
+// Default attribute (text buttons/dropdown)
+const sizeAttr = await client.createAttribute({
+  name: 'Size',
+  source: 'GLOBAL',
+});
+await client.createAttributeOption(sizeAttr.id, {
+  name: 'Large',
+  value: 'L',
+  source: 'GLOBAL',
+});
+
+// Get options, update, delete
+const options = await client.getAttributeOptions(colorAttr.id);
+await client.updateAttribute(colorAttr.id, { displayType: 'IMAGE_SWATCH' });
+await client.updateAttributeOption(colorAttr.id, options[0].id, { swatchColor: '#CC0000' });
+await client.deleteAttributeOption(colorAttr.id, options[0].id);
+await client.deleteAttribute(colorAttr.id);
+
+// Storefront: render swatches from product data
+import { getProductSwatches } from 'brainerce';
+
+const product = await client.getProductBySlug('my-product');
+const swatches = getProductSwatches(product);
+// Returns: [{ attributeName: 'Color', displayType: 'COLOR_SWATCH', options: [{ name: 'Red', swatchColor: '#FF0000', ... }] }]
 ```
 
 ### Shipping Configuration

package/dist/index.d.mts

@@ -135,6 +135,23 @@ interface StoreInfo {
      * 3. Call verifyEmail(code) with the code they received via email
      */
     requireEmailVerification?: boolean;
+    /** Upsell feature settings (storefront mode) */
+    upsell?: UpsellSettings;
+}
+/** Upsell feature configuration exposed to the storefront */
+interface UpsellSettings {
+    /** Minimum cart amount for free shipping (null = disabled) */
+    freeShippingThreshold: number | null;
+    /** Show free shipping progress bar in cart */
+    freeShippingBarEnabled: boolean;
+    /** Show "Frequently Bought Together" on product page */
+    frequentlyBoughtTogetherEnabled: boolean;
+    /** Show upgrade banner per cart item */
+    cartUpgradeBannerEnabled: boolean;
+    /** Show bundle offers in cart */
+    cartBundleEnabled: boolean;
+    /** Show order bump checkbox at checkout */
+    checkoutOrderBumpEnabled: boolean;
 }
 interface CustomerProfile {
     id: string;
@@ -218,7 +235,9 @@ interface Product {
     lastSyncedAt?: string | null;
     /** Menu/display order */
     menuOrder?: number | null;
-    /** Full attribute options for variant selection (admin mode only) */
+    /** Tax behavior: 'taxable' follows store setting, 'exempt' always skips tax */
+    taxBehavior?: 'taxable' | 'exempt';
+    /** Full attribute options for variant selection (admin, storefront, and vibe-coded modes) */
     productAttributeOptions?: Array<{
         id: string;
         attributeId: string;
@@ -227,11 +246,15 @@ interface Product {
         attribute: {
             id: string;
             name: string;
+            displayType?: string;
         } | null;
         attributeOption: {
             id: string;
             name: string;
             value?: string | null;
+            swatchColor?: string | null;
+            swatchColor2?: string | null;
+            swatchImageUrl?: string | null;
         } | null;
     }>;
     /** Vibe-coded sites this product is published to (admin mode only) */
@@ -244,6 +267,8 @@ interface Product {
     }>;
     /** Discount info from matching discount rules (storefront/VC mode only) */
     discount?: ProductDiscount | null;
+    /** Recommendations (upsells, cross-sells, related) — included in storefront/VC getProductBySlug response */
+    recommendations?: ProductRecommendationsResponse;
     createdAt: string;
     updatedAt: string;
 }
@@ -636,6 +661,22 @@ declare function getVariantOptions(variant: Pick<ProductVariant, 'attributes'> |
     name: string;
     value: string;
 }>;
+/**
+ * Get structured swatch data from product attribute options.
+ * Groups by attribute name and includes display type + swatch details.
+ * Useful for rendering swatch selectors in storefronts.
+ */
+declare function getProductSwatches(product: Pick<Product, 'productAttributeOptions'> | null | undefined): Array<{
+    attributeName: string;
+    displayType: string;
+    options: Array<{
+        name: string;
+        value?: string | null;
+        swatchColor?: string | null;
+        swatchColor2?: string | null;
+        swatchImageUrl?: string | null;
+    }>;
+}>;
 /**
  * Get a single metafield by definition key.
  */
@@ -1283,6 +1324,7 @@ interface RegisterCustomerDto {
     firstName?: string;
     lastName?: string;
     phone?: string;
+    acceptsMarketing?: boolean;
 }
 type CartStatus = 'ACTIVE' | 'MERGED' | 'CONVERTED' | 'ABANDONED';
 /**
@@ -2707,6 +2749,8 @@ interface Category {
     platformMetadata?: Record<string, Record<string, unknown>> | null;
     parentId?: string | null;
     isActive: boolean;
+    /** Tax behavior: 'taxable' follows store setting, 'exempt' always skips tax */
+    taxBehavior?: 'taxable' | 'exempt';
     deletedAt?: string | null;
     productCount?: number;
     products?: Array<{
@@ -2723,11 +2767,13 @@ interface CreateCategoryDto {
     storeId?: string;
     source?: string;
     isActive?: boolean;
+    taxBehavior?: 'taxable' | 'exempt';
 }
 interface UpdateCategoryDto {
     name?: string;
     parentId?: string | null;
     isActive?: boolean;
+    taxBehavior?: 'taxable' | 'exempt';
 }
 /**
  * Brand entity for product organization
@@ -2817,6 +2863,7 @@ interface Attribute {
     accountId: string;
     storeId?: string | null;
     name: string;
+    displayType?: string;
     source: AttributeSource;
     platform?: ConnectorPlatform | null;
     externalId?: string | null;
@@ -2833,6 +2880,9 @@ interface AttributeOption {
     attributeId: string;
     name: string;
     value?: string | null;
+    swatchColor?: string | null;
+    swatchColor2?: string | null;
+    swatchImageUrl?: string | null;
     source: AttributeSource;
     platform?: ConnectorPlatform | null;
     externalId?: string | null;
@@ -2845,6 +2895,7 @@ interface AttributeOption {
 }
 interface CreateAttributeDto {
     name: string;
+    displayType?: string;
     source: AttributeSource;
     platform?: ConnectorPlatform;
     storeId?: string;
@@ -2854,12 +2905,16 @@ interface CreateAttributeDto {
 }
 interface UpdateAttributeDto {
     name?: string;
+    displayType?: string;
     platformMetadata?: Record<string, unknown>;
     isActive?: boolean;
 }
 interface CreateAttributeOptionDto {
     name: string;
     value?: string;
+    swatchColor?: string;
+    swatchColor2?: string;
+    swatchImageUrl?: string;
     source: AttributeSource;
     platform?: ConnectorPlatform;
     externalId?: string;
@@ -2870,6 +2925,9 @@ interface CreateAttributeOptionDto {
 interface UpdateAttributeOptionDto {
     name?: string;
     value?: string;
+    swatchColor?: string | null;
+    swatchColor2?: string | null;
+    swatchImageUrl?: string | null;
     platformMetadata?: Record<string, unknown>;
     position?: number;
     isActive?: boolean;
@@ -3503,6 +3561,44 @@ interface ProductRecommendationsResponse {
 interface CartRecommendationsResponse {
     recommendations: ProductRecommendation[];
 }
+interface CartUpgradeSuggestion {
+    sourceProductId: string;
+    targetProduct: ProductRecommendation;
+    priceDelta: string;
+    deltaPercent: number;
+}
+interface CartUpgradesResponse {
+    upgrades: Record<string, CartUpgradeSuggestion>;
+}
+interface CartBundleOffer {
+    id: string;
+    name: string;
+    description: string | null;
+    sourceProductId: string;
+    bundleProduct: ProductRecommendation;
+    bundleVariantId: string | null;
+    discountType: 'PERCENTAGE' | 'FIXED_AMOUNT';
+    discountValue: string;
+    originalPrice: string;
+    discountedPrice: string;
+}
+interface CartBundlesResponse {
+    bundles: CartBundleOffer[];
+}
+interface OrderBump {
+    id: string;
+    title: string;
+    description: string | null;
+    bumpProduct: ProductRecommendation;
+    bumpVariantId: string | null;
+    originalPrice: string;
+    discountedPrice: string | null;
+    discountType: string | null;
+    discountValue: string | null;
+}
+interface CheckoutBumpsResponse {
+    bumps: OrderBump[];
+}
 interface BrainerceApiError {
     statusCode: number;
     message: string;
@@ -4766,6 +4862,61 @@ declare class BrainerceClient {
      * ```
      */
     getCartRecommendations(cartId: string, limit?: number): Promise<CartRecommendationsResponse>;
+    /**
+     * Get upgrade suggestions for cart items (upsell relations with small price delta).
+     * Returns a map keyed by source product ID with the best upgrade option.
+     *
+     * @param cartId - Cart ID
+     * @returns Map of upgrade suggestions keyed by source product ID
+     *
+     * @example
+     * ```typescript
+     * const { upgrades } = await client.getCartUpgrades('cart_123');
+     * for (const [productId, suggestion] of Object.entries(upgrades)) {
+     *   console.log(`Upgrade from ${productId} to ${suggestion.targetProduct.name} for +$${suggestion.priceDelta}`);
+     * }
+     * ```
+     */
+    getCartUpgrades(cartId: string): Promise<CartUpgradesResponse>;
+    /**
+     * Get matching bundle offers for cart items.
+     * Returns bundle products with discounted prices for items currently in the cart.
+     *
+     * @param cartId - Cart ID
+     * @returns Array of bundle offers
+     *
+     * @example
+     * ```typescript
+     * const { bundles } = await client.getCartBundles('cart_123');
+     * bundles.forEach(b => {
+     *   console.log(`Add ${b.bundleProduct.name} and save! Was ${b.originalPrice}, now ${b.discountedPrice}`);
+     * });
+     * ```
+     */
+    getCartBundles(cartId: string): Promise<CartBundlesResponse>;
+    /**
+     * Get matching order bumps for a checkout session.
+     *
+     * @param checkoutId - Checkout ID
+     * @returns Array of order bumps
+     */
+    getCheckoutBumps(checkoutId: string): Promise<CheckoutBumpsResponse>;
+    /**
+     * Add an order bump to the cart.
+     *
+     * @param cartId - Cart ID
+     * @param bumpConfigId - Order bump config ID
+     * @returns Updated cart
+     */
+    addOrderBump(cartId: string, bumpConfigId: string): Promise<Cart>;
+    /**
+     * Remove an order bump from the cart.
+     *
+     * @param cartId - Cart ID
+     * @param bumpConfigId - Order bump config ID
+     * @returns Updated cart
+     */
+    removeOrderBump(cartId: string, bumpConfigId: string): Promise<Cart>;
     /**
      * Check if customer is currently authenticated
      * Used internally by smart cart methods to determine storage strategy
@@ -6486,6 +6637,8 @@ declare class BrainerceError extends Error {
     constructor(message: string, statusCode: number, details?: unknown);
 }
 
+declare const SDK_VERSION = "1.11.2";
+
 /**
  * Verify a webhook signature from Brainerce
  *
@@ -6558,4 +6711,4 @@ declare function enableDevGuards(options?: {
     force?: boolean;
 }): void;
 
-export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type Attribute, type AttributeOption, type AttributeSource, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartAppliedDiscount, type CartItem, type CartNudge, type CartRecommendationsResponse, type CartStatus, type Category, type CategoryNode, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, 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 CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailVerificationResponse, type ExtendReservationResponse, type FormatPriceOptions, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type LocalCart, type LocalCartItem, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldPlatformMapping, type MetafieldType, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PickupLocation, type PlatformCouponCapabilities, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomerDto, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingZone, type ShippingZoneQueryParams, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type 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 UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, 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 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, createWebhookHandler, enableDevGuards, formatPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, formatPrice as getPriceDisplay, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getStockStatus, getVariantOptions, getVariantPrice, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, verifyWebhook };
+export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type Attribute, type AttributeOption, type AttributeSource, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartItem, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type Category, type CategoryNode, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, 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 CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailVerificationResponse, type ExtendReservationResponse, type FormatPriceOptions, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type LocalCart, type LocalCartItem, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldPlatformMapping, type MetafieldType, 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 PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PickupLocation, type PlatformCouponCapabilities, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomerDto, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingZone, type ShippingZoneQueryParams, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type 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 UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, 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 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, createWebhookHandler, enableDevGuards, formatPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, formatPrice as getPriceDisplay, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, verifyWebhook };

package/dist/index.d.ts

@@ -135,6 +135,23 @@ interface StoreInfo {
      * 3. Call verifyEmail(code) with the code they received via email
      */
     requireEmailVerification?: boolean;
+    /** Upsell feature settings (storefront mode) */
+    upsell?: UpsellSettings;
+}
+/** Upsell feature configuration exposed to the storefront */
+interface UpsellSettings {
+    /** Minimum cart amount for free shipping (null = disabled) */
+    freeShippingThreshold: number | null;
+    /** Show free shipping progress bar in cart */
+    freeShippingBarEnabled: boolean;
+    /** Show "Frequently Bought Together" on product page */
+    frequentlyBoughtTogetherEnabled: boolean;
+    /** Show upgrade banner per cart item */
+    cartUpgradeBannerEnabled: boolean;
+    /** Show bundle offers in cart */
+    cartBundleEnabled: boolean;
+    /** Show order bump checkbox at checkout */
+    checkoutOrderBumpEnabled: boolean;
 }
 interface CustomerProfile {
     id: string;
@@ -218,7 +235,9 @@ interface Product {
     lastSyncedAt?: string | null;
     /** Menu/display order */
     menuOrder?: number | null;
-    /** Full attribute options for variant selection (admin mode only) */
+    /** Tax behavior: 'taxable' follows store setting, 'exempt' always skips tax */
+    taxBehavior?: 'taxable' | 'exempt';
+    /** Full attribute options for variant selection (admin, storefront, and vibe-coded modes) */
     productAttributeOptions?: Array<{
         id: string;
         attributeId: string;
@@ -227,11 +246,15 @@ interface Product {
         attribute: {
             id: string;
             name: string;
+            displayType?: string;
         } | null;
         attributeOption: {
             id: string;
             name: string;
             value?: string | null;
+            swatchColor?: string | null;
+            swatchColor2?: string | null;
+            swatchImageUrl?: string | null;
         } | null;
     }>;
     /** Vibe-coded sites this product is published to (admin mode only) */
@@ -244,6 +267,8 @@ interface Product {
     }>;
     /** Discount info from matching discount rules (storefront/VC mode only) */
     discount?: ProductDiscount | null;
+    /** Recommendations (upsells, cross-sells, related) — included in storefront/VC getProductBySlug response */
+    recommendations?: ProductRecommendationsResponse;
     createdAt: string;
     updatedAt: string;
 }
@@ -636,6 +661,22 @@ declare function getVariantOptions(variant: Pick<ProductVariant, 'attributes'> |
     name: string;
     value: string;
 }>;
+/**
+ * Get structured swatch data from product attribute options.
+ * Groups by attribute name and includes display type + swatch details.
+ * Useful for rendering swatch selectors in storefronts.
+ */
+declare function getProductSwatches(product: Pick<Product, 'productAttributeOptions'> | null | undefined): Array<{
+    attributeName: string;
+    displayType: string;
+    options: Array<{
+        name: string;
+        value?: string | null;
+        swatchColor?: string | null;
+        swatchColor2?: string | null;
+        swatchImageUrl?: string | null;
+    }>;
+}>;
 /**
  * Get a single metafield by definition key.
  */
@@ -1283,6 +1324,7 @@ interface RegisterCustomerDto {
     firstName?: string;
     lastName?: string;
     phone?: string;
+    acceptsMarketing?: boolean;
 }
 type CartStatus = 'ACTIVE' | 'MERGED' | 'CONVERTED' | 'ABANDONED';
 /**
@@ -2707,6 +2749,8 @@ interface Category {
     platformMetadata?: Record<string, Record<string, unknown>> | null;
     parentId?: string | null;
     isActive: boolean;
+    /** Tax behavior: 'taxable' follows store setting, 'exempt' always skips tax */
+    taxBehavior?: 'taxable' | 'exempt';
     deletedAt?: string | null;
     productCount?: number;
     products?: Array<{
@@ -2723,11 +2767,13 @@ interface CreateCategoryDto {
     storeId?: string;
     source?: string;
     isActive?: boolean;
+    taxBehavior?: 'taxable' | 'exempt';
 }
 interface UpdateCategoryDto {
     name?: string;
     parentId?: string | null;
     isActive?: boolean;
+    taxBehavior?: 'taxable' | 'exempt';
 }
 /**
  * Brand entity for product organization
@@ -2817,6 +2863,7 @@ interface Attribute {
     accountId: string;
     storeId?: string | null;
     name: string;
+    displayType?: string;
     source: AttributeSource;
     platform?: ConnectorPlatform | null;
     externalId?: string | null;
@@ -2833,6 +2880,9 @@ interface AttributeOption {
     attributeId: string;
     name: string;
     value?: string | null;
+    swatchColor?: string | null;
+    swatchColor2?: string | null;
+    swatchImageUrl?: string | null;
     source: AttributeSource;
     platform?: ConnectorPlatform | null;
     externalId?: string | null;
@@ -2845,6 +2895,7 @@ interface AttributeOption {
 }
 interface CreateAttributeDto {
     name: string;
+    displayType?: string;
     source: AttributeSource;
     platform?: ConnectorPlatform;
     storeId?: string;
@@ -2854,12 +2905,16 @@ interface CreateAttributeDto {
 }
 interface UpdateAttributeDto {
     name?: string;
+    displayType?: string;
     platformMetadata?: Record<string, unknown>;
     isActive?: boolean;
 }
 interface CreateAttributeOptionDto {
     name: string;
     value?: string;
+    swatchColor?: string;
+    swatchColor2?: string;
+    swatchImageUrl?: string;
     source: AttributeSource;
     platform?: ConnectorPlatform;
     externalId?: string;
@@ -2870,6 +2925,9 @@ interface CreateAttributeOptionDto {
 interface UpdateAttributeOptionDto {
     name?: string;
     value?: string;
+    swatchColor?: string | null;
+    swatchColor2?: string | null;
+    swatchImageUrl?: string | null;
     platformMetadata?: Record<string, unknown>;
     position?: number;
     isActive?: boolean;
@@ -3503,6 +3561,44 @@ interface ProductRecommendationsResponse {
 interface CartRecommendationsResponse {
     recommendations: ProductRecommendation[];
 }
+interface CartUpgradeSuggestion {
+    sourceProductId: string;
+    targetProduct: ProductRecommendation;
+    priceDelta: string;
+    deltaPercent: number;
+}
+interface CartUpgradesResponse {
+    upgrades: Record<string, CartUpgradeSuggestion>;
+}
+interface CartBundleOffer {
+    id: string;
+    name: string;
+    description: string | null;
+    sourceProductId: string;
+    bundleProduct: ProductRecommendation;
+    bundleVariantId: string | null;
+    discountType: 'PERCENTAGE' | 'FIXED_AMOUNT';
+    discountValue: string;
+    originalPrice: string;
+    discountedPrice: string;
+}
+interface CartBundlesResponse {
+    bundles: CartBundleOffer[];
+}
+interface OrderBump {
+    id: string;
+    title: string;
+    description: string | null;
+    bumpProduct: ProductRecommendation;
+    bumpVariantId: string | null;
+    originalPrice: string;
+    discountedPrice: string | null;
+    discountType: string | null;
+    discountValue: string | null;
+}
+interface CheckoutBumpsResponse {
+    bumps: OrderBump[];
+}
 interface BrainerceApiError {
     statusCode: number;
     message: string;
@@ -4766,6 +4862,61 @@ declare class BrainerceClient {
      * ```
      */
     getCartRecommendations(cartId: string, limit?: number): Promise<CartRecommendationsResponse>;
+    /**
+     * Get upgrade suggestions for cart items (upsell relations with small price delta).
+     * Returns a map keyed by source product ID with the best upgrade option.
+     *
+     * @param cartId - Cart ID
+     * @returns Map of upgrade suggestions keyed by source product ID
+     *
+     * @example
+     * ```typescript
+     * const { upgrades } = await client.getCartUpgrades('cart_123');
+     * for (const [productId, suggestion] of Object.entries(upgrades)) {
+     *   console.log(`Upgrade from ${productId} to ${suggestion.targetProduct.name} for +$${suggestion.priceDelta}`);
+     * }
+     * ```
+     */
+    getCartUpgrades(cartId: string): Promise<CartUpgradesResponse>;
+    /**
+     * Get matching bundle offers for cart items.
+     * Returns bundle products with discounted prices for items currently in the cart.
+     *
+     * @param cartId - Cart ID
+     * @returns Array of bundle offers
+     *
+     * @example
+     * ```typescript
+     * const { bundles } = await client.getCartBundles('cart_123');
+     * bundles.forEach(b => {
+     *   console.log(`Add ${b.bundleProduct.name} and save! Was ${b.originalPrice}, now ${b.discountedPrice}`);
+     * });
+     * ```
+     */
+    getCartBundles(cartId: string): Promise<CartBundlesResponse>;
+    /**
+     * Get matching order bumps for a checkout session.
+     *
+     * @param checkoutId - Checkout ID
+     * @returns Array of order bumps
+     */
+    getCheckoutBumps(checkoutId: string): Promise<CheckoutBumpsResponse>;
+    /**
+     * Add an order bump to the cart.
+     *
+     * @param cartId - Cart ID
+     * @param bumpConfigId - Order bump config ID
+     * @returns Updated cart
+     */
+    addOrderBump(cartId: string, bumpConfigId: string): Promise<Cart>;
+    /**
+     * Remove an order bump from the cart.
+     *
+     * @param cartId - Cart ID
+     * @param bumpConfigId - Order bump config ID
+     * @returns Updated cart
+     */
+    removeOrderBump(cartId: string, bumpConfigId: string): Promise<Cart>;
     /**
      * Check if customer is currently authenticated
      * Used internally by smart cart methods to determine storage strategy
@@ -6486,6 +6637,8 @@ declare class BrainerceError extends Error {
     constructor(message: string, statusCode: number, details?: unknown);
 }
 
+declare const SDK_VERSION = "1.11.2";
+
 /**
  * Verify a webhook signature from Brainerce
  *
@@ -6558,4 +6711,4 @@ declare function enableDevGuards(options?: {
     force?: boolean;
 }): void;
 
-export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type Attribute, type AttributeOption, type AttributeSource, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartAppliedDiscount, type CartItem, type CartNudge, type CartRecommendationsResponse, type CartStatus, type Category, type CategoryNode, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, 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 CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailVerificationResponse, type ExtendReservationResponse, type FormatPriceOptions, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type LocalCart, type LocalCartItem, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldPlatformMapping, type MetafieldType, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PickupLocation, type PlatformCouponCapabilities, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomerDto, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingZone, type ShippingZoneQueryParams, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type 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 UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, 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 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, createWebhookHandler, enableDevGuards, formatPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, formatPrice as getPriceDisplay, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getStockStatus, getVariantOptions, getVariantPrice, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, verifyWebhook };
+export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type Attribute, type AttributeOption, type AttributeSource, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartItem, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type Category, type CategoryNode, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, 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 CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailVerificationResponse, type ExtendReservationResponse, type FormatPriceOptions, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type LocalCart, type LocalCartItem, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldPlatformMapping, type MetafieldType, 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 PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PickupLocation, type PlatformCouponCapabilities, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomerDto, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingZone, type ShippingZoneQueryParams, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type 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 UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, 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 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, createWebhookHandler, enableDevGuards, formatPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, formatPrice as getPriceDisplay, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, verifyWebhook };

package/dist/index.js

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   BrainerceClient: () => BrainerceClient,
   BrainerceError: () => BrainerceError,
+  SDK_VERSION: () => SDK_VERSION,
   createWebhookHandler: () => createWebhookHandler,
   enableDevGuards: () => enableDevGuards,
   formatPrice: () => formatPrice,
@@ -45,6 +46,7 @@ __export(index_exports, {
   getProductMetafieldsByType: () => getProductMetafieldsByType,
   getProductPrice: () => getProductPrice,
   getProductPriceInfo: () => getProductPriceInfo,
+  getProductSwatches: () => getProductSwatches,
   getStockStatus: () => getStockStatus,
   getVariantOptions: () => getVariantOptions,
   getVariantPrice: () => getVariantPrice,
@@ -172,6 +174,9 @@ function isDevGuardsEnabled() {
   return _devGuardsEnabled;
 }
 
+// src/version.ts
+var SDK_VERSION = "1.11.2";
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
 var DEFAULT_TIMEOUT = 3e4;
@@ -339,7 +344,7 @@ var BrainerceClient = class {
       const headers = {
         Authorization: `Bearer ${this.apiKey}`,
         "Content-Type": "application/json",
-        "X-SDK-Version": "1.11.0",
+        "X-SDK-Version": SDK_VERSION,
         "ngrok-skip-browser-warning": "true"
       };
       if (this.origin) {
@@ -397,7 +402,7 @@ var BrainerceClient = class {
     try {
       const headers = {
         "Content-Type": "application/json",
-        "X-SDK-Version": "1.11.0",
+        "X-SDK-Version": SDK_VERSION,
         "ngrok-skip-browser-warning": "true"
       };
       if (this.origin) {
@@ -468,7 +473,7 @@ var BrainerceClient = class {
     try {
       const headers = {
         "Content-Type": "application/json",
-        "X-SDK-Version": "1.11.0",
+        "X-SDK-Version": SDK_VERSION,
         "ngrok-skip-browser-warning": "true"
       };
       if (this.origin) {
@@ -2419,6 +2424,101 @@ var BrainerceClient = class {
       400
     );
   }
+  /**
+   * Get upgrade suggestions for cart items (upsell relations with small price delta).
+   * Returns a map keyed by source product ID with the best upgrade option.
+   *
+   * @param cartId - Cart ID
+   * @returns Map of upgrade suggestions keyed by source product ID
+   *
+   * @example
+   * ```typescript
+   * const { upgrades } = await client.getCartUpgrades('cart_123');
+   * for (const [productId, suggestion] of Object.entries(upgrades)) {
+   *   console.log(`Upgrade from ${productId} to ${suggestion.targetProduct.name} for +$${suggestion.priceDelta}`);
+   * }
+   * ```
+   */
+  async getCartUpgrades(cartId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", `/cart/${cartId}/upgrades`);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", `/cart/${cartId}/upgrades`);
+    }
+    throw new BrainerceError("getCartUpgrades() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Get matching bundle offers for cart items.
+   * Returns bundle products with discounted prices for items currently in the cart.
+   *
+   * @param cartId - Cart ID
+   * @returns Array of bundle offers
+   *
+   * @example
+   * ```typescript
+   * const { bundles } = await client.getCartBundles('cart_123');
+   * bundles.forEach(b => {
+   *   console.log(`Add ${b.bundleProduct.name} and save! Was ${b.originalPrice}, now ${b.discountedPrice}`);
+   * });
+   * ```
+   */
+  async getCartBundles(cartId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", `/cart/${cartId}/bundles`);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", `/cart/${cartId}/bundles`);
+    }
+    throw new BrainerceError("getCartBundles() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Get matching order bumps for a checkout session.
+   *
+   * @param checkoutId - Checkout ID
+   * @returns Array of order bumps
+   */
+  async getCheckoutBumps(checkoutId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", `/checkout/${checkoutId}/bumps`);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", `/checkout/${checkoutId}/bumps`);
+    }
+    throw new BrainerceError("getCheckoutBumps() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Add an order bump to the cart.
+   *
+   * @param cartId - Cart ID
+   * @param bumpConfigId - Order bump config ID
+   * @returns Updated cart
+   */
+  async addOrderBump(cartId, bumpConfigId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("POST", `/cart/${cartId}/bump`, { bumpConfigId });
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("POST", `/cart/${cartId}/bump`, { bumpConfigId });
+    }
+    throw new BrainerceError("addOrderBump() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Remove an order bump from the cart.
+   *
+   * @param cartId - Cart ID
+   * @param bumpConfigId - Order bump config ID
+   * @returns Updated cart
+   */
+  async removeOrderBump(cartId, bumpConfigId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("DELETE", `/cart/${cartId}/bump/${bumpConfigId}`);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("DELETE", `/cart/${cartId}/bump/${bumpConfigId}`);
+    }
+    throw new BrainerceError("removeOrderBump() requires vibe-coded or storefront mode", 400);
+  }
   // -------------------- Smart Cart (Auto-sync) --------------------
   /**
    * Check if customer is currently authenticated
@@ -5933,6 +6033,34 @@ function getVariantOptions(variant) {
   ]);
   return Object.entries(variant.attributes).filter(([key, value]) => typeof value === "string" && !internalKeys.has(key)).map(([name, value]) => ({ name, value }));
 }
+function getProductSwatches(product) {
+  if (!product?.productAttributeOptions) return [];
+  const grouped = /* @__PURE__ */ new Map();
+  for (const pao of product.productAttributeOptions) {
+    if (!pao.attribute || !pao.attributeOption) continue;
+    const attrName = pao.attribute.name;
+    if (!grouped.has(attrName)) {
+      grouped.set(attrName, {
+        displayType: pao.attribute.displayType || "DEFAULT",
+        options: []
+      });
+    }
+    const entry = grouped.get(attrName);
+    if (!entry.options.some((o) => o.name === pao.attributeOption.name)) {
+      entry.options.push({
+        name: pao.attributeOption.name,
+        value: pao.attributeOption.value,
+        swatchColor: pao.attributeOption.swatchColor,
+        swatchColor2: pao.attributeOption.swatchColor2,
+        swatchImageUrl: pao.attributeOption.swatchImageUrl
+      });
+    }
+  }
+  return Array.from(grouped.entries()).map(([attributeName, data]) => ({
+    attributeName,
+    ...data
+  }));
+}
 function getProductMetafield(product, key) {
   return product.metafields?.find((m) => m.definitionKey === key);
 }
@@ -5965,6 +6093,7 @@ function isCouponApplicableToProduct(coupon, productId) {
 0 && (module.exports = {
   BrainerceClient,
   BrainerceError,
+  SDK_VERSION,
   createWebhookHandler,
   enableDevGuards,
   formatPrice,
@@ -5978,6 +6107,7 @@ function isCouponApplicableToProduct(coupon, productId) {
   getProductMetafieldsByType,
   getProductPrice,
   getProductPriceInfo,
+  getProductSwatches,
   getStockStatus,
   getVariantOptions,
   getVariantPrice,

package/dist/index.mjs

@@ -114,6 +114,9 @@ function isDevGuardsEnabled() {
   return _devGuardsEnabled;
 }
 
+// src/version.ts
+var SDK_VERSION = "1.11.2";
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
 var DEFAULT_TIMEOUT = 3e4;
@@ -281,7 +284,7 @@ var BrainerceClient = class {
       const headers = {
         Authorization: `Bearer ${this.apiKey}`,
         "Content-Type": "application/json",
-        "X-SDK-Version": "1.11.0",
+        "X-SDK-Version": SDK_VERSION,
         "ngrok-skip-browser-warning": "true"
       };
       if (this.origin) {
@@ -339,7 +342,7 @@ var BrainerceClient = class {
     try {
       const headers = {
         "Content-Type": "application/json",
-        "X-SDK-Version": "1.11.0",
+        "X-SDK-Version": SDK_VERSION,
         "ngrok-skip-browser-warning": "true"
       };
       if (this.origin) {
@@ -410,7 +413,7 @@ var BrainerceClient = class {
     try {
       const headers = {
         "Content-Type": "application/json",
-        "X-SDK-Version": "1.11.0",
+        "X-SDK-Version": SDK_VERSION,
         "ngrok-skip-browser-warning": "true"
       };
       if (this.origin) {
@@ -2361,6 +2364,101 @@ var BrainerceClient = class {
       400
     );
   }
+  /**
+   * Get upgrade suggestions for cart items (upsell relations with small price delta).
+   * Returns a map keyed by source product ID with the best upgrade option.
+   *
+   * @param cartId - Cart ID
+   * @returns Map of upgrade suggestions keyed by source product ID
+   *
+   * @example
+   * ```typescript
+   * const { upgrades } = await client.getCartUpgrades('cart_123');
+   * for (const [productId, suggestion] of Object.entries(upgrades)) {
+   *   console.log(`Upgrade from ${productId} to ${suggestion.targetProduct.name} for +$${suggestion.priceDelta}`);
+   * }
+   * ```
+   */
+  async getCartUpgrades(cartId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", `/cart/${cartId}/upgrades`);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", `/cart/${cartId}/upgrades`);
+    }
+    throw new BrainerceError("getCartUpgrades() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Get matching bundle offers for cart items.
+   * Returns bundle products with discounted prices for items currently in the cart.
+   *
+   * @param cartId - Cart ID
+   * @returns Array of bundle offers
+   *
+   * @example
+   * ```typescript
+   * const { bundles } = await client.getCartBundles('cart_123');
+   * bundles.forEach(b => {
+   *   console.log(`Add ${b.bundleProduct.name} and save! Was ${b.originalPrice}, now ${b.discountedPrice}`);
+   * });
+   * ```
+   */
+  async getCartBundles(cartId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", `/cart/${cartId}/bundles`);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", `/cart/${cartId}/bundles`);
+    }
+    throw new BrainerceError("getCartBundles() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Get matching order bumps for a checkout session.
+   *
+   * @param checkoutId - Checkout ID
+   * @returns Array of order bumps
+   */
+  async getCheckoutBumps(checkoutId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", `/checkout/${checkoutId}/bumps`);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", `/checkout/${checkoutId}/bumps`);
+    }
+    throw new BrainerceError("getCheckoutBumps() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Add an order bump to the cart.
+   *
+   * @param cartId - Cart ID
+   * @param bumpConfigId - Order bump config ID
+   * @returns Updated cart
+   */
+  async addOrderBump(cartId, bumpConfigId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("POST", `/cart/${cartId}/bump`, { bumpConfigId });
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("POST", `/cart/${cartId}/bump`, { bumpConfigId });
+    }
+    throw new BrainerceError("addOrderBump() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Remove an order bump from the cart.
+   *
+   * @param cartId - Cart ID
+   * @param bumpConfigId - Order bump config ID
+   * @returns Updated cart
+   */
+  async removeOrderBump(cartId, bumpConfigId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("DELETE", `/cart/${cartId}/bump/${bumpConfigId}`);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("DELETE", `/cart/${cartId}/bump/${bumpConfigId}`);
+    }
+    throw new BrainerceError("removeOrderBump() requires vibe-coded or storefront mode", 400);
+  }
   // -------------------- Smart Cart (Auto-sync) --------------------
   /**
    * Check if customer is currently authenticated
@@ -5875,6 +5973,34 @@ function getVariantOptions(variant) {
   ]);
   return Object.entries(variant.attributes).filter(([key, value]) => typeof value === "string" && !internalKeys.has(key)).map(([name, value]) => ({ name, value }));
 }
+function getProductSwatches(product) {
+  if (!product?.productAttributeOptions) return [];
+  const grouped = /* @__PURE__ */ new Map();
+  for (const pao of product.productAttributeOptions) {
+    if (!pao.attribute || !pao.attributeOption) continue;
+    const attrName = pao.attribute.name;
+    if (!grouped.has(attrName)) {
+      grouped.set(attrName, {
+        displayType: pao.attribute.displayType || "DEFAULT",
+        options: []
+      });
+    }
+    const entry = grouped.get(attrName);
+    if (!entry.options.some((o) => o.name === pao.attributeOption.name)) {
+      entry.options.push({
+        name: pao.attributeOption.name,
+        value: pao.attributeOption.value,
+        swatchColor: pao.attributeOption.swatchColor,
+        swatchColor2: pao.attributeOption.swatchColor2,
+        swatchImageUrl: pao.attributeOption.swatchImageUrl
+      });
+    }
+  }
+  return Array.from(grouped.entries()).map(([attributeName, data]) => ({
+    attributeName,
+    ...data
+  }));
+}
 function getProductMetafield(product, key) {
   return product.metafields?.find((m) => m.definitionKey === key);
 }
@@ -5906,6 +6032,7 @@ function isCouponApplicableToProduct(coupon, productId) {
 export {
   BrainerceClient,
   BrainerceError,
+  SDK_VERSION,
   createWebhookHandler,
   enableDevGuards,
   formatPrice,
@@ -5919,6 +6046,7 @@ export {
   getProductMetafieldsByType,
   getProductPrice,
   getProductPriceInfo,
+  getProductSwatches,
   getStockStatus,
   getVariantOptions,
   getVariantPrice,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.11.0",
+  "version": "1.12.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",