brainerce 1.42.0 → 1.44.0

package/README.md

@@ -46,7 +46,7 @@ Every Brainerce storefront must include **all mandatory features** below. Featur
 | Forgot / reset password                                 | `client.forgotPassword()`, `client.resetPassword()`                                                           | ✅          |
 | OAuth sign-in buttons + callback handler                | `client.getAvailableOAuthProviders()`                                                                         | ✅          |
 | Account area (profile + order history)                  | `client.getMyProfile()`, `client.getMyOrders()`                                                               | ✅          |
-| Loyalty & rewards (points balance + redeem)             | `client.getLoyaltyStatus()`, `client.getAvailableRewards()`, `client.redeemLoyaltyReward(id)`                 | conditional |
+| Loyalty & rewards (points balance + tiers + redeem)     | `client.getLoyaltyStatus()`, `client.getAvailableRewards()`, `client.redeemLoyaltyReward(id)`, `client.reportSocialShare()` | conditional |
 | Global header: cart count + search autocomplete         | `client.getCart()`, `client.getSearchSuggestions(query)`                                                      | ✅          |
 | Discount banners + product badges                       | `client.getDiscountBanners()`, `client.getProductDiscountBadge(productId)`                                    | ✅          |
 | Product reviews on PDP + JSON-LD aggregateRating        | `client.listProductReviews(id)`, `client.submitProductReview(id, …)`                                          | ✅          |
@@ -120,7 +120,7 @@ These sequences are non-negotiable. The order of SDK calls matters.
 
 ### Checkout flow
 
-1. Collect customer email, billing address, shipping address (`line1`, `line2`, `city`, `region`, `postalCode`, `country`). `email` is required.
+1. Collect customer email, billing address, shipping address (`line1`, `line2`, `city`, `region`, `postalCode`, `country`). `email` is required. Include an optional **"Order notes"** textarea by default — its value lands on the order for the merchant.
 2. Submit address to get shipping rates:
    ```ts
    const { checkout, rates } = await client.setShippingAddress(checkoutId, {
@@ -132,6 +132,7 @@ These sequences are non-negotiable. The order of SDK calls matters.
      region,
      postalCode,
      country,
+     notes: orderNotes, // optional shopper note (max 2000 chars)
    });
    // rates = available shipping rates; checkout = updated checkout object
    ```
@@ -2920,25 +2921,68 @@ customers check their points balance, enroll, and redeem rewards for one-time
 coupons that apply at checkout.
 
 ```typescript
-// Current status — points balance + program display config.
-// `program` is null if the store has no loyalty program.
+// Current status — points balance + program display config + tier progress.
+// `program`/`tier`/`nextTier` are null if the store has no loyalty program
+// (or no tiers configured / the customer hasn't reached one yet).
 const status = await client.getLoyaltyStatus();
 if (status.enrolled) {
   console.log(`${status.pointsBalance} ${status.program?.pointsName}`);
+  if (status.nextTier) {
+    console.log(`${status.pointsToNextTier} to reach ${status.nextTier.name}`);
+  }
 }
 
-// Enroll (idempotent) — only if the program is ACTIVE.
+// Enroll (idempotent) — only if the program is ACTIVE. May grant a one-time
+// "join the program" bonus if the store has one configured.
 await client.enrollInLoyalty();
 
-// Rewards the customer can redeem, cheapest first.
+// Rewards the customer can redeem, cheapest first (already filtered to ones
+// their current tier qualifies for).
 const rewards = await client.getAvailableRewards();
 
 // Redeem → spends points, returns a one-time coupon code to apply to the cart.
-const { couponCode, discountValue, pointsBalance } =
+// `discountType` tells you how to interpret `discountValue` (currency amount
+// for FIXED_DISCOUNT, 0-100 percent for PERCENT_DISCOUNT).
+const { couponCode, discountType, discountValue, pointsBalance } =
   await client.redeemLoyaltyReward(rewards[0].id);
 await client.applyCoupon(cartId, couponCode);
+
+// Self-reported social share — grants the SOCIAL_SHARE bonus if configured
+// (once per customer).
+await client.reportSocialShare('instagram');
 ```
 
+#### Referrals & Birthday Gifts
+
+When the store enables referrals, `getLoyaltyStatus()` also returns the
+member's share code (`referralCode`) and — for customers who signed up via a
+referral link — their still-unused welcome coupon (`referralWelcomeCoupon`).
+
+```typescript
+// 1. The referrer shares a link you build around their code.
+const { referralCode } = await client.getLoyaltyStatus();
+const shareUrl = `https://your-store.com/?ref=${referralCode}`;
+
+// 2. On the landing page — public lookup, NO customerToken needed. Never
+// returns PII beyond the referrer's first name.
+const info = await client.getReferralInfo(refFromQuery);
+if (info.valid) {
+  // e.g. "Jane sent you a gift: 10% off your first order"
+}
+
+// 3. Pass the code at registration. Invalid codes never fail registration —
+// they're validated asynchronously server-side (with fraud checks).
+await client.registerCustomer({ email, password, referralCode: refFromQuery });
+
+// 4. After the referee's first qualifying order, the referrer earns a points
+// bonus (held through the program's pending window, like order points).
+```
+
+Birthday gifts need no SDK calls beyond profile data: set the customer's
+`birthMonth`/`birthDay` (1-12 / 1-31, no year) via `updateMyProfile()` and the
+platform emails a one-time gift coupon ahead of their birthday automatically
+(when the store has it enabled).
+
 #### Auth Response Type
 
 ```typescript
@@ -3878,6 +3922,11 @@ Merchants publish through the dashboard's per-row Platforms cell or via the
 admin SDK below.
 
 ```typescript
+// Publish a product to a sales channel (accepts record ID or vc_* connection ID)
+await client.publishProductToSalesChannel('prod_id', 'vc_conn_id');
+await client.publishCouponToSalesChannel('coupon_id', 'vc_conn_id');
+await client.unpublishProductFromSalesChannel('prod_id', 'vc_conn_id');
+
 // Publish a category to a specific vibe-coded site
 await client.publishCategoryToVibeCodedSite('cat_id', 'conn_id');
 // Tag, brand, metafield definition follow the same shape:

package/dist/index.d.mts

@@ -248,6 +248,21 @@ interface CustomerProfile {
     createdAt: string;
     updatedAt: string;
 }
+/** The membership tier a customer currently holds, or is progressing toward. */
+interface LoyaltyTierSummary {
+    id: string;
+    name: string;
+    /** Ordering; higher = better tier. */
+    level: number;
+    /** Points-earning multiplier this tier grants (e.g. 1.5 = 50% more points per order). */
+    pointsMultiplier: number;
+}
+/** The next tier up, including what it takes to qualify. */
+interface LoyaltyNextTierSummary extends LoyaltyTierSummary {
+    qualificationType: 'SPEND' | 'POINTS';
+    /** Threshold in store currency (SPEND) or points (POINTS). */
+    qualificationThreshold: number;
+}
 /** A store's loyalty program status for a logged-in customer. */
 interface LoyaltyStatus {
     /** Whether the customer has a membership in the program. */
@@ -264,21 +279,63 @@ interface LoyaltyStatus {
         currencyRatio: number;
         status: 'DRAFT' | 'ACTIVE' | 'PAUSED';
     } | null;
+    /** The customer's current tier, or null if untiered / no tiers configured. */
+    tier: LoyaltyTierSummary | null;
+    /** The next tier up, or null if already at the top tier (or no tiers configured). */
+    nextTier: LoyaltyNextTierSummary | null;
+    /** 0..1 progress toward nextTier; 1 if no nextTier and a tier is held. */
+    progressToNextTier: number;
+    /** Remaining spend/points needed to reach nextTier, or null if there's no nextTier. */
+    pointsToNextTier: number | null;
+    /**
+     * The customer's referral share code — build your referral link around it
+     * (e.g. `https://your-store.com/?ref=<code>`). Null when the program has
+     * referrals disabled or the customer isn't enrolled. Lazy-created on first
+     * read of this endpoint.
+     */
+    referralCode?: string | null;
+    /**
+     * The still-unused welcome coupon this customer received for registering via
+     * a referral link, or null (none / already used). `type` is the coupon type
+     * ('PERCENTAGE' | 'FIXED_AMOUNT').
+     */
+    referralWelcomeCoupon?: {
+        code: string;
+        type: string;
+        value: number;
+    } | null;
+}
+/** Public referral-link lookup result (no auth needed) — see getReferralInfo(). */
+interface ReferralInfo {
+    /** False for unknown codes, disabled referral programs, or inactive programs. */
+    valid: boolean;
+    /** Referrer's first name for "Jane sent you a gift" copy — never any other PII. */
+    referrerFirstName: string | null;
+    /** The welcome reward the referee will receive on signup, or null if none configured. */
+    reward: {
+        name: string;
+        type: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
+        value: number;
+        minOrderAmount: number | null;
+    } | null;
 }
-/** A reward a customer can redeem points for (fixed-amount discount coupon). */
+/** A reward a customer can redeem points for. */
 interface LoyaltyReward {
     id: string;
     name: string;
     description: string | null;
     /** Points required to redeem this reward. */
     pointsCost: number;
-    /** Fixed discount amount the minted coupon is worth, in store currency. */
+    /** FIXED_DISCOUNT: discountValue is a store-currency amount off. PERCENT_DISCOUNT: discountValue is a 0-100 percent off. */
+    type: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
     discountValue: number;
     /** Minimum order amount for the coupon to apply, or null. */
     minOrderAmount: number | null;
     /** How many times a single customer may redeem this reward. */
     maxUsesPerUser: number;
     isActive: boolean;
+    /** Minimum tier level required to redeem this reward, or null for no restriction. */
+    minTierLevel: number | null;
     createdAt: string;
     updatedAt: string;
 }
@@ -286,7 +343,9 @@ interface LoyaltyReward {
 interface RedeemRewardResult {
     /** The minted one-time coupon code to apply at checkout. */
     couponCode: string;
-    /** Fixed discount amount the coupon is worth. */
+    /** Matches the redeemed reward's `type` — tells you how to interpret discountValue. */
+    discountType: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
+    /** Currency amount (FIXED_DISCOUNT) or percent 0-100 (PERCENT_DISCOUNT) the coupon is worth. */
     discountValue: number;
     /** Points spent on this redemption. */
     pointsSpent: number;
@@ -1249,6 +1308,12 @@ interface Order {
      */
     taxBreakdown?: TaxBreakdown | null;
     createdAt: string;
+    /**
+     * The shopper's own order note from checkout, echoed back read-only
+     * (e.g., "Please leave at the door"). Display it in order history /
+     * confirmation views; it cannot be edited after purchase.
+     */
+    notes?: string | null;
     /** Payment method used (e.g., "card", "paypal", "cash_on_delivery"). */
     paymentMethod?: string | null;
     /** Financial status: "pending", "paid", "refunded", "partially_refunded", "voided". */
@@ -1823,6 +1888,12 @@ interface RegisterCustomerDto {
     lastName?: string;
     phone?: string;
     acceptsMarketing?: boolean;
+    /**
+     * Loyalty referral share code (REF-XXXXXXXX) from a referrer's link.
+     * Validated asynchronously after registration — an invalid code never fails
+     * the registration itself.
+     */
+    referralCode?: string;
 }
 type CartStatus = 'ACTIVE' | 'MERGED' | 'CONVERTED' | 'ABANDONED';
 /**
@@ -2673,6 +2744,11 @@ interface Checkout {
     customFieldValues?: Record<string, unknown> | null;
     /** Applied coupon code */
     couponCode?: string | null;
+    /**
+     * Order-level note from the shopper (set via setCheckoutCustomer).
+     * Copied onto the order at completion and shown to the merchant.
+     */
+    notes?: string | null;
     /** Line items with nested product/variant data */
     lineItems: CheckoutLineItem[];
     /** Total item count */
@@ -2771,6 +2847,13 @@ interface SetCheckoutCustomerDto {
     lastName?: string;
     phone?: string;
     acceptsMarketing?: boolean;
+    /**
+     * Order-level note from the shopper ("Please leave at the door").
+     * Copied onto the order at completion — visible to the merchant in the
+     * dashboard and included in the confirmation email. Max 2000 chars.
+     * Send an empty string to clear a previously-set note.
+     */
+    notes?: string;
 }
 /**
  * Shipping address with customer email (required for checkout).
@@ -2791,6 +2874,13 @@ interface SetShippingAddressDto {
     phone?: string;
     /** Whether customer accepts marketing emails */
     acceptsMarketing?: boolean;
+    /**
+     * Order-level note from the shopper ("Please leave at the door").
+     * Rides along with the address step so single-page checkouts need no extra
+     * call. Copied onto the order at completion — visible to the merchant in
+     * the dashboard and included in the confirmation email. Max 2000 chars.
+     */
+    notes?: string;
 }
 /**
  * Billing address (email not required - already set in shipping address)
@@ -7862,12 +7952,18 @@ declare class BrainerceClient {
     /**
      * Set customer information on checkout
      *
+     * Also accepts an optional order-level `notes` field — every checkout page
+     * should include an optional "Order notes" textarea by default and send its
+     * value here. The note is copied onto the order at completion, shown to the
+     * merchant in the dashboard, and included in the confirmation email.
+     *
      * @example
      * ```typescript
      * const checkout = await client.setCheckoutCustomer('checkout_123', {
      *   email: 'customer@example.com',
      *   firstName: 'John',
      *   lastName: 'Doe',
+     *   notes: 'Please leave the package at the door', // optional order notes
      * });
      * ```
      */
@@ -7905,6 +8001,10 @@ declare class BrainerceClient {
      * **This is the first step of the simplified checkout flow.**
      * Email is required and will be used for order confirmation.
      *
+     * Also accepts an optional order-level `notes` field — every checkout page
+     * should include an optional "Order notes" textarea by default and send its
+     * value here (or via `setCheckoutCustomer`). The note lands on the order.
+     *
      * @example
      * ```typescript
      * const { checkout, rates } = await client.setShippingAddress('checkout_123', {
@@ -7916,6 +8016,7 @@ declare class BrainerceClient {
      *   region: 'NY',
      *   postalCode: '10001',
      *   country: 'US',
+     *   notes: 'Please leave the package at the door', // optional order notes
      * });
      * console.log('Available rates:', rates);
      * ```
@@ -8280,6 +8381,27 @@ declare class BrainerceClient {
      * ```
      */
     waitForOrder(checkoutId: string, options?: WaitForOrderOptions): Promise<WaitForOrderResult>;
+    /**
+     * Get the full order created by a completed checkout.
+     *
+     * Use this on the order-confirmation page (after `waitForOrder` succeeds)
+     * when you want to render more than the order number — line items, shipping
+     * address, financial breakdown, and the shopper's order note are all
+     * included (the buyer-safe order shape, same as `getMyOrders`).
+     *
+     * Works for guests too: possession of the checkout id is the credential —
+     * no customer token needed.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.waitForOrder(checkoutId);
+     * if (result.success) {
+     *   const order = await client.getOrderByCheckout(checkoutId);
+     *   // order.items, order.shippingAddress, order.notes, order.totalAmount, ...
+     * }
+     * ```
+     */
+    getOrderByCheckout(checkoutId: string): Promise<Order>;
     private readonly LOCAL_CART_KEY;
     /**
      * Check if localStorage is available (browser environment)
@@ -8607,12 +8729,17 @@ declare class BrainerceClient {
     /**
      * Update the current customer's profile (requires customerToken)
      * Only available in storefront mode
+     *
+     * `birthMonth`/`birthDay` (1-12 / 1-31, no year — privacy) power the loyalty
+     * birthday gift; they must be provided together.
      */
     updateMyProfile(data: {
         firstName?: string;
         lastName?: string;
         phone?: string;
         acceptsMarketing?: boolean;
+        birthMonth?: number;
+        birthDay?: number;
     }): Promise<CustomerProfile>;
     /**
      * Get the logged-in customer's loyalty status: enrollment, points balance,
@@ -8662,6 +8789,38 @@ declare class BrainerceClient {
      * ```
      */
     redeemLoyaltyReward(rewardId: string): Promise<RedeemRewardResult>;
+    /**
+     * Report a social share, granting the SOCIAL_SHARE earning-rule bonus if the
+     * store has one configured (requires customerToken). Self-reported — no
+     * share-tracking infra — and capped at once per customer per program. Only
+     * available in storefront mode.
+     *
+     * @example
+     * ```typescript
+     * await client.reportSocialShare('instagram');
+     * ```
+     */
+    reportSocialShare(platform?: string): Promise<{
+        awarded: boolean;
+        points: number;
+    }>;
+    /**
+     * Public referral-link lookup: who referred the visitor and what welcome
+     * reward awaits them. No customerToken needed (like getStoreInfo/trackEvent)
+     * — safe to call on a referral landing page before signup. Returns
+     * `{ valid: false }` for unknown codes or stores with referrals disabled.
+     * Only available in storefront mode.
+     *
+     * @example
+     * ```typescript
+     * const info = await client.getReferralInfo(searchParams.get('ref')!);
+     * if (info.valid) {
+     *   showBanner(`${info.referrerFirstName ?? 'A friend'} sent you a gift!`);
+     *   // later: client.registerCustomer({ ...form, referralCode })
+     * }
+     * ```
+     */
+    getReferralInfo(code: string): Promise<ReferralInfo>;
     /**
      * Get the current customer's orders (requires customerToken)
      * Works in vibe-coded and storefront modes
@@ -9444,6 +9603,30 @@ declare class BrainerceClient {
     unpublishMetafieldDefinitionFromVibeCodedSite(definitionId: string, vibeCodedConnectionId: string): Promise<{
         success: boolean;
     }>;
+    /**
+     * Publish a product to a sales channel (admin mode) — makes it visible on
+     * that vibe-coded storefront. Accepts the sales-channel record ID or its
+     * public `vc_*` connection ID.
+     */
+    publishProductToSalesChannel(productId: string, salesChannelId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Unpublish a product from a sales channel (admin mode). */
+    unpublishProductFromSalesChannel(productId: string, salesChannelId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Publish a coupon to a sales channel (admin mode) — makes it redeemable on
+     * that vibe-coded storefront. Accepts the sales-channel record ID or its
+     * public `vc_*` connection ID.
+     */
+    publishCouponToSalesChannel(couponId: string, salesChannelId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Unpublish a coupon from a sales channel (admin mode). */
+    unpublishCouponFromSalesChannel(couponId: string, salesChannelId: string): Promise<{
+        success: boolean;
+    }>;
     /** Publish a category to a vibe-coded site (admin mode). */
     publishCategoryToVibeCodedSite(categoryId: string, vibeCodedConnectionId: string): Promise<{
         success: boolean;
@@ -9966,4 +10149,4 @@ declare function formatVariantPrice(variant: Pick<ProductVariant, 'price' | 'sal
 /** Format any numeric amount as currency. Useful for cart totals, fees, etc. */
 declare function formatMoney(amount: number, currency: string, locale?: string): string;
 
-export { type AddToCartDto, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryNode, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type MyProductReview, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingZone, type ShippingZoneQueryParams, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type SubmitProductReviewInput, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, safePaymentRedirect, stripHtml, verifyWebhook };
+export { type AddToCartDto, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryNode, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyStatus, type LoyaltyTierSummary, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type MyProductReview, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingZone, type ShippingZoneQueryParams, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type SubmitProductReviewInput, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, safePaymentRedirect, stripHtml, verifyWebhook };

package/dist/index.d.ts

@@ -248,6 +248,21 @@ interface CustomerProfile {
     createdAt: string;
     updatedAt: string;
 }
+/** The membership tier a customer currently holds, or is progressing toward. */
+interface LoyaltyTierSummary {
+    id: string;
+    name: string;
+    /** Ordering; higher = better tier. */
+    level: number;
+    /** Points-earning multiplier this tier grants (e.g. 1.5 = 50% more points per order). */
+    pointsMultiplier: number;
+}
+/** The next tier up, including what it takes to qualify. */
+interface LoyaltyNextTierSummary extends LoyaltyTierSummary {
+    qualificationType: 'SPEND' | 'POINTS';
+    /** Threshold in store currency (SPEND) or points (POINTS). */
+    qualificationThreshold: number;
+}
 /** A store's loyalty program status for a logged-in customer. */
 interface LoyaltyStatus {
     /** Whether the customer has a membership in the program. */
@@ -264,21 +279,63 @@ interface LoyaltyStatus {
         currencyRatio: number;
         status: 'DRAFT' | 'ACTIVE' | 'PAUSED';
     } | null;
+    /** The customer's current tier, or null if untiered / no tiers configured. */
+    tier: LoyaltyTierSummary | null;
+    /** The next tier up, or null if already at the top tier (or no tiers configured). */
+    nextTier: LoyaltyNextTierSummary | null;
+    /** 0..1 progress toward nextTier; 1 if no nextTier and a tier is held. */
+    progressToNextTier: number;
+    /** Remaining spend/points needed to reach nextTier, or null if there's no nextTier. */
+    pointsToNextTier: number | null;
+    /**
+     * The customer's referral share code — build your referral link around it
+     * (e.g. `https://your-store.com/?ref=<code>`). Null when the program has
+     * referrals disabled or the customer isn't enrolled. Lazy-created on first
+     * read of this endpoint.
+     */
+    referralCode?: string | null;
+    /**
+     * The still-unused welcome coupon this customer received for registering via
+     * a referral link, or null (none / already used). `type` is the coupon type
+     * ('PERCENTAGE' | 'FIXED_AMOUNT').
+     */
+    referralWelcomeCoupon?: {
+        code: string;
+        type: string;
+        value: number;
+    } | null;
+}
+/** Public referral-link lookup result (no auth needed) — see getReferralInfo(). */
+interface ReferralInfo {
+    /** False for unknown codes, disabled referral programs, or inactive programs. */
+    valid: boolean;
+    /** Referrer's first name for "Jane sent you a gift" copy — never any other PII. */
+    referrerFirstName: string | null;
+    /** The welcome reward the referee will receive on signup, or null if none configured. */
+    reward: {
+        name: string;
+        type: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
+        value: number;
+        minOrderAmount: number | null;
+    } | null;
 }
-/** A reward a customer can redeem points for (fixed-amount discount coupon). */
+/** A reward a customer can redeem points for. */
 interface LoyaltyReward {
     id: string;
     name: string;
     description: string | null;
     /** Points required to redeem this reward. */
     pointsCost: number;
-    /** Fixed discount amount the minted coupon is worth, in store currency. */
+    /** FIXED_DISCOUNT: discountValue is a store-currency amount off. PERCENT_DISCOUNT: discountValue is a 0-100 percent off. */
+    type: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
     discountValue: number;
     /** Minimum order amount for the coupon to apply, or null. */
     minOrderAmount: number | null;
     /** How many times a single customer may redeem this reward. */
     maxUsesPerUser: number;
     isActive: boolean;
+    /** Minimum tier level required to redeem this reward, or null for no restriction. */
+    minTierLevel: number | null;
     createdAt: string;
     updatedAt: string;
 }
@@ -286,7 +343,9 @@ interface LoyaltyReward {
 interface RedeemRewardResult {
     /** The minted one-time coupon code to apply at checkout. */
     couponCode: string;
-    /** Fixed discount amount the coupon is worth. */
+    /** Matches the redeemed reward's `type` — tells you how to interpret discountValue. */
+    discountType: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
+    /** Currency amount (FIXED_DISCOUNT) or percent 0-100 (PERCENT_DISCOUNT) the coupon is worth. */
     discountValue: number;
     /** Points spent on this redemption. */
     pointsSpent: number;
@@ -1249,6 +1308,12 @@ interface Order {
      */
     taxBreakdown?: TaxBreakdown | null;
     createdAt: string;
+    /**
+     * The shopper's own order note from checkout, echoed back read-only
+     * (e.g., "Please leave at the door"). Display it in order history /
+     * confirmation views; it cannot be edited after purchase.
+     */
+    notes?: string | null;
     /** Payment method used (e.g., "card", "paypal", "cash_on_delivery"). */
     paymentMethod?: string | null;
     /** Financial status: "pending", "paid", "refunded", "partially_refunded", "voided". */
@@ -1823,6 +1888,12 @@ interface RegisterCustomerDto {
     lastName?: string;
     phone?: string;
     acceptsMarketing?: boolean;
+    /**
+     * Loyalty referral share code (REF-XXXXXXXX) from a referrer's link.
+     * Validated asynchronously after registration — an invalid code never fails
+     * the registration itself.
+     */
+    referralCode?: string;
 }
 type CartStatus = 'ACTIVE' | 'MERGED' | 'CONVERTED' | 'ABANDONED';
 /**
@@ -2673,6 +2744,11 @@ interface Checkout {
     customFieldValues?: Record<string, unknown> | null;
     /** Applied coupon code */
     couponCode?: string | null;
+    /**
+     * Order-level note from the shopper (set via setCheckoutCustomer).
+     * Copied onto the order at completion and shown to the merchant.
+     */
+    notes?: string | null;
     /** Line items with nested product/variant data */
     lineItems: CheckoutLineItem[];
     /** Total item count */
@@ -2771,6 +2847,13 @@ interface SetCheckoutCustomerDto {
     lastName?: string;
     phone?: string;
     acceptsMarketing?: boolean;
+    /**
+     * Order-level note from the shopper ("Please leave at the door").
+     * Copied onto the order at completion — visible to the merchant in the
+     * dashboard and included in the confirmation email. Max 2000 chars.
+     * Send an empty string to clear a previously-set note.
+     */
+    notes?: string;
 }
 /**
  * Shipping address with customer email (required for checkout).
@@ -2791,6 +2874,13 @@ interface SetShippingAddressDto {
     phone?: string;
     /** Whether customer accepts marketing emails */
     acceptsMarketing?: boolean;
+    /**
+     * Order-level note from the shopper ("Please leave at the door").
+     * Rides along with the address step so single-page checkouts need no extra
+     * call. Copied onto the order at completion — visible to the merchant in
+     * the dashboard and included in the confirmation email. Max 2000 chars.
+     */
+    notes?: string;
 }
 /**
  * Billing address (email not required - already set in shipping address)
@@ -7862,12 +7952,18 @@ declare class BrainerceClient {
     /**
      * Set customer information on checkout
      *
+     * Also accepts an optional order-level `notes` field — every checkout page
+     * should include an optional "Order notes" textarea by default and send its
+     * value here. The note is copied onto the order at completion, shown to the
+     * merchant in the dashboard, and included in the confirmation email.
+     *
      * @example
      * ```typescript
      * const checkout = await client.setCheckoutCustomer('checkout_123', {
      *   email: 'customer@example.com',
      *   firstName: 'John',
      *   lastName: 'Doe',
+     *   notes: 'Please leave the package at the door', // optional order notes
      * });
      * ```
      */
@@ -7905,6 +8001,10 @@ declare class BrainerceClient {
      * **This is the first step of the simplified checkout flow.**
      * Email is required and will be used for order confirmation.
      *
+     * Also accepts an optional order-level `notes` field — every checkout page
+     * should include an optional "Order notes" textarea by default and send its
+     * value here (or via `setCheckoutCustomer`). The note lands on the order.
+     *
      * @example
      * ```typescript
      * const { checkout, rates } = await client.setShippingAddress('checkout_123', {
@@ -7916,6 +8016,7 @@ declare class BrainerceClient {
      *   region: 'NY',
      *   postalCode: '10001',
      *   country: 'US',
+     *   notes: 'Please leave the package at the door', // optional order notes
      * });
      * console.log('Available rates:', rates);
      * ```
@@ -8280,6 +8381,27 @@ declare class BrainerceClient {
      * ```
      */
     waitForOrder(checkoutId: string, options?: WaitForOrderOptions): Promise<WaitForOrderResult>;
+    /**
+     * Get the full order created by a completed checkout.
+     *
+     * Use this on the order-confirmation page (after `waitForOrder` succeeds)
+     * when you want to render more than the order number — line items, shipping
+     * address, financial breakdown, and the shopper's order note are all
+     * included (the buyer-safe order shape, same as `getMyOrders`).
+     *
+     * Works for guests too: possession of the checkout id is the credential —
+     * no customer token needed.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.waitForOrder(checkoutId);
+     * if (result.success) {
+     *   const order = await client.getOrderByCheckout(checkoutId);
+     *   // order.items, order.shippingAddress, order.notes, order.totalAmount, ...
+     * }
+     * ```
+     */
+    getOrderByCheckout(checkoutId: string): Promise<Order>;
     private readonly LOCAL_CART_KEY;
     /**
      * Check if localStorage is available (browser environment)
@@ -8607,12 +8729,17 @@ declare class BrainerceClient {
     /**
      * Update the current customer's profile (requires customerToken)
      * Only available in storefront mode
+     *
+     * `birthMonth`/`birthDay` (1-12 / 1-31, no year — privacy) power the loyalty
+     * birthday gift; they must be provided together.
      */
     updateMyProfile(data: {
         firstName?: string;
         lastName?: string;
         phone?: string;
         acceptsMarketing?: boolean;
+        birthMonth?: number;
+        birthDay?: number;
     }): Promise<CustomerProfile>;
     /**
      * Get the logged-in customer's loyalty status: enrollment, points balance,
@@ -8662,6 +8789,38 @@ declare class BrainerceClient {
      * ```
      */
     redeemLoyaltyReward(rewardId: string): Promise<RedeemRewardResult>;
+    /**
+     * Report a social share, granting the SOCIAL_SHARE earning-rule bonus if the
+     * store has one configured (requires customerToken). Self-reported — no
+     * share-tracking infra — and capped at once per customer per program. Only
+     * available in storefront mode.
+     *
+     * @example
+     * ```typescript
+     * await client.reportSocialShare('instagram');
+     * ```
+     */
+    reportSocialShare(platform?: string): Promise<{
+        awarded: boolean;
+        points: number;
+    }>;
+    /**
+     * Public referral-link lookup: who referred the visitor and what welcome
+     * reward awaits them. No customerToken needed (like getStoreInfo/trackEvent)
+     * — safe to call on a referral landing page before signup. Returns
+     * `{ valid: false }` for unknown codes or stores with referrals disabled.
+     * Only available in storefront mode.
+     *
+     * @example
+     * ```typescript
+     * const info = await client.getReferralInfo(searchParams.get('ref')!);
+     * if (info.valid) {
+     *   showBanner(`${info.referrerFirstName ?? 'A friend'} sent you a gift!`);
+     *   // later: client.registerCustomer({ ...form, referralCode })
+     * }
+     * ```
+     */
+    getReferralInfo(code: string): Promise<ReferralInfo>;
     /**
      * Get the current customer's orders (requires customerToken)
      * Works in vibe-coded and storefront modes
@@ -9444,6 +9603,30 @@ declare class BrainerceClient {
     unpublishMetafieldDefinitionFromVibeCodedSite(definitionId: string, vibeCodedConnectionId: string): Promise<{
         success: boolean;
     }>;
+    /**
+     * Publish a product to a sales channel (admin mode) — makes it visible on
+     * that vibe-coded storefront. Accepts the sales-channel record ID or its
+     * public `vc_*` connection ID.
+     */
+    publishProductToSalesChannel(productId: string, salesChannelId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Unpublish a product from a sales channel (admin mode). */
+    unpublishProductFromSalesChannel(productId: string, salesChannelId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Publish a coupon to a sales channel (admin mode) — makes it redeemable on
+     * that vibe-coded storefront. Accepts the sales-channel record ID or its
+     * public `vc_*` connection ID.
+     */
+    publishCouponToSalesChannel(couponId: string, salesChannelId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Unpublish a coupon from a sales channel (admin mode). */
+    unpublishCouponFromSalesChannel(couponId: string, salesChannelId: string): Promise<{
+        success: boolean;
+    }>;
     /** Publish a category to a vibe-coded site (admin mode). */
     publishCategoryToVibeCodedSite(categoryId: string, vibeCodedConnectionId: string): Promise<{
         success: boolean;
@@ -9966,4 +10149,4 @@ declare function formatVariantPrice(variant: Pick<ProductVariant, 'price' | 'sal
 /** Format any numeric amount as currency. Useful for cart totals, fees, etc. */
 declare function formatMoney(amount: number, currency: string, locale?: string): string;
 
-export { type AddToCartDto, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryNode, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type MyProductReview, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingZone, type ShippingZoneQueryParams, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type SubmitProductReviewInput, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, safePaymentRedirect, stripHtml, verifyWebhook };
+export { type AddToCartDto, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryNode, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyStatus, type LoyaltyTierSummary, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type MyProductReview, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingZone, type ShippingZoneQueryParams, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type SubmitProductReviewInput, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, safePaymentRedirect, stripHtml, verifyWebhook };

package/dist/index.js

@@ -4771,12 +4771,18 @@ var BrainerceClient = class {
   /**
    * Set customer information on checkout
    *
+   * Also accepts an optional order-level `notes` field — every checkout page
+   * should include an optional "Order notes" textarea by default and send its
+   * value here. The note is copied onto the order at completion, shown to the
+   * merchant in the dashboard, and included in the confirmation email.
+   *
    * @example
    * ```typescript
    * const checkout = await client.setCheckoutCustomer('checkout_123', {
    *   email: 'customer@example.com',
    *   firstName: 'John',
    *   lastName: 'Doe',
+   *   notes: 'Please leave the package at the door', // optional order notes
    * });
    * ```
    */
@@ -4848,6 +4854,10 @@ var BrainerceClient = class {
    * **This is the first step of the simplified checkout flow.**
    * Email is required and will be used for order confirmation.
    *
+   * Also accepts an optional order-level `notes` field — every checkout page
+   * should include an optional "Order notes" textarea by default and send its
+   * value here (or via `setCheckoutCustomer`). The note lands on the order.
+   *
    * @example
    * ```typescript
    * const { checkout, rates } = await client.setShippingAddress('checkout_123', {
@@ -4859,6 +4869,7 @@ var BrainerceClient = class {
    *   region: 'NY',
    *   postalCode: '10001',
    *   country: 'US',
+   *   notes: 'Please leave the package at the door', // optional order notes
    * });
    * console.log('Available rates:', rates);
    * ```
@@ -5524,6 +5535,44 @@ var BrainerceClient = class {
       waitedMs: Date.now() - startTime
     };
   }
+  /**
+   * Get the full order created by a completed checkout.
+   *
+   * Use this on the order-confirmation page (after `waitForOrder` succeeds)
+   * when you want to render more than the order number — line items, shipping
+   * address, financial breakdown, and the shopper's order note are all
+   * included (the buyer-safe order shape, same as `getMyOrders`).
+   *
+   * Works for guests too: possession of the checkout id is the credential —
+   * no customer token needed.
+   *
+   * @example
+   * ```typescript
+   * const result = await client.waitForOrder(checkoutId);
+   * if (result.success) {
+   *   const order = await client.getOrderByCheckout(checkoutId);
+   *   // order.items, order.shippingAddress, order.notes, order.totalAmount, ...
+   * }
+   * ```
+   */
+  async getOrderByCheckout(checkoutId) {
+    if (this.isVibeCodedMode()) {
+      return this.withGuards(
+        this.vibeCodedRequest("GET", `/checkout/${encodePathSegment(checkoutId)}/order`),
+        "order"
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.withGuards(
+        this.storefrontRequest("GET", `/checkout/${encodePathSegment(checkoutId)}/order`),
+        "order"
+      );
+    }
+    throw new BrainerceError(
+      "getOrderByCheckout() requires vibe-coded or storefront mode",
+      400
+    );
+  }
   /**
    * Check if localStorage is available (browser environment)
    */
@@ -6296,6 +6345,9 @@ var BrainerceClient = class {
   /**
    * Update the current customer's profile (requires customerToken)
    * Only available in storefront mode
+   *
+   * `birthMonth`/`birthDay` (1-12 / 1-31, no year — privacy) power the loyalty
+   * birthday gift; they must be provided together.
    */
   async updateMyProfile(data) {
     if (!this.customerToken && !this.proxyMode) {
@@ -6411,6 +6463,57 @@ var BrainerceClient = class {
     }
     throw new BrainerceError("redeemLoyaltyReward is only available in storefront mode", 400);
   }
+  /**
+   * Report a social share, granting the SOCIAL_SHARE earning-rule bonus if the
+   * store has one configured (requires customerToken). Self-reported — no
+   * share-tracking infra — and capped at once per customer per program. Only
+   * available in storefront mode.
+   *
+   * @example
+   * ```typescript
+   * await client.reportSocialShare('instagram');
+   * ```
+   */
+  async reportSocialShare(platform) {
+    if (!this.customerToken && !this.proxyMode) {
+      throw new BrainerceError(
+        "Customer token required. Call setCustomerToken() after login.",
+        401
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "POST",
+        "/loyalty/social-share",
+        platform ? { platform } : {}
+      );
+    }
+    throw new BrainerceError("reportSocialShare is only available in storefront mode", 400);
+  }
+  /**
+   * Public referral-link lookup: who referred the visitor and what welcome
+   * reward awaits them. No customerToken needed (like getStoreInfo/trackEvent)
+   * — safe to call on a referral landing page before signup. Returns
+   * `{ valid: false }` for unknown codes or stores with referrals disabled.
+   * Only available in storefront mode.
+   *
+   * @example
+   * ```typescript
+   * const info = await client.getReferralInfo(searchParams.get('ref')!);
+   * if (info.valid) {
+   *   showBanner(`${info.referrerFirstName ?? 'A friend'} sent you a gift!`);
+   *   // later: client.registerCustomer({ ...form, referralCode })
+   * }
+   * ```
+   */
+  async getReferralInfo(code) {
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", "/loyalty/referral-info", void 0, {
+        code
+      });
+    }
+    throw new BrainerceError("getReferralInfo is only available in storefront mode", 400);
+  }
   /**
    * Get the current customer's orders (requires customerToken)
    * Works in vibe-coded and storefront modes
@@ -7821,52 +7924,92 @@ var BrainerceClient = class {
       { vibeCodedConnectionId }
     );
   }
+  /**
+   * Publish a product to a sales channel (admin mode) — makes it visible on
+   * that vibe-coded storefront. Accepts the sales-channel record ID or its
+   * public `vc_*` connection ID.
+   */
+  async publishProductToSalesChannel(productId, salesChannelId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/products/${encodePathSegment(productId)}/publish-sales-channel`,
+      { salesChannelId }
+    );
+  }
+  /** Unpublish a product from a sales channel (admin mode). */
+  async unpublishProductFromSalesChannel(productId, salesChannelId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/products/${encodePathSegment(productId)}/unpublish-sales-channel`,
+      { salesChannelId }
+    );
+  }
+  /**
+   * Publish a coupon to a sales channel (admin mode) — makes it redeemable on
+   * that vibe-coded storefront. Accepts the sales-channel record ID or its
+   * public `vc_*` connection ID.
+   */
+  async publishCouponToSalesChannel(couponId, salesChannelId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/coupons/${encodePathSegment(couponId)}/publish-sales-channel`,
+      { salesChannelId }
+    );
+  }
+  /** Unpublish a coupon from a sales channel (admin mode). */
+  async unpublishCouponFromSalesChannel(couponId, salesChannelId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/coupons/${encodePathSegment(couponId)}/unpublish-sales-channel`,
+      { salesChannelId }
+    );
+  }
   /** Publish a category to a vibe-coded site (admin mode). */
   async publishCategoryToVibeCodedSite(categoryId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/categories/${encodePathSegment(categoryId)}/publish-vibe-coded`,
-      { vibeCodedConnectionId }
+      `/api/v1/categories/${encodePathSegment(categoryId)}/publish-sales-channel`,
+      { salesChannelId: vibeCodedConnectionId }
     );
   }
   /** Unpublish a category from a vibe-coded site (admin mode). */
   async unpublishCategoryFromVibeCodedSite(categoryId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/categories/${encodePathSegment(categoryId)}/unpublish-vibe-coded`,
-      { vibeCodedConnectionId }
+      `/api/v1/categories/${encodePathSegment(categoryId)}/unpublish-sales-channel`,
+      { salesChannelId: vibeCodedConnectionId }
     );
   }
   /** Publish a tag to a vibe-coded site (admin mode). */
   async publishTagToVibeCodedSite(tagId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/tags/${encodePathSegment(tagId)}/publish-vibe-coded`,
-      { vibeCodedConnectionId }
+      `/api/v1/tags/${encodePathSegment(tagId)}/publish-sales-channel`,
+      { salesChannelId: vibeCodedConnectionId }
     );
   }
   /** Unpublish a tag from a vibe-coded site (admin mode). */
   async unpublishTagFromVibeCodedSite(tagId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/tags/${encodePathSegment(tagId)}/unpublish-vibe-coded`,
-      { vibeCodedConnectionId }
+      `/api/v1/tags/${encodePathSegment(tagId)}/unpublish-sales-channel`,
+      { salesChannelId: vibeCodedConnectionId }
     );
   }
   /** Publish a brand to a vibe-coded site (admin mode). */
   async publishBrandToVibeCodedSite(brandId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/brands/${encodePathSegment(brandId)}/publish-vibe-coded`,
-      { vibeCodedConnectionId }
+      `/api/v1/brands/${encodePathSegment(brandId)}/publish-sales-channel`,
+      { salesChannelId: vibeCodedConnectionId }
     );
   }
   /** Unpublish a brand from a vibe-coded site (admin mode). */
   async unpublishBrandFromVibeCodedSite(brandId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/brands/${encodePathSegment(brandId)}/unpublish-vibe-coded`,
-      { vibeCodedConnectionId }
+      `/api/v1/brands/${encodePathSegment(brandId)}/unpublish-sales-channel`,
+      { salesChannelId: vibeCodedConnectionId }
     );
   }
   /**

package/dist/index.mjs

@@ -4701,12 +4701,18 @@ var BrainerceClient = class {
   /**
    * Set customer information on checkout
    *
+   * Also accepts an optional order-level `notes` field — every checkout page
+   * should include an optional "Order notes" textarea by default and send its
+   * value here. The note is copied onto the order at completion, shown to the
+   * merchant in the dashboard, and included in the confirmation email.
+   *
    * @example
    * ```typescript
    * const checkout = await client.setCheckoutCustomer('checkout_123', {
    *   email: 'customer@example.com',
    *   firstName: 'John',
    *   lastName: 'Doe',
+   *   notes: 'Please leave the package at the door', // optional order notes
    * });
    * ```
    */
@@ -4778,6 +4784,10 @@ var BrainerceClient = class {
    * **This is the first step of the simplified checkout flow.**
    * Email is required and will be used for order confirmation.
    *
+   * Also accepts an optional order-level `notes` field — every checkout page
+   * should include an optional "Order notes" textarea by default and send its
+   * value here (or via `setCheckoutCustomer`). The note lands on the order.
+   *
    * @example
    * ```typescript
    * const { checkout, rates } = await client.setShippingAddress('checkout_123', {
@@ -4789,6 +4799,7 @@ var BrainerceClient = class {
    *   region: 'NY',
    *   postalCode: '10001',
    *   country: 'US',
+   *   notes: 'Please leave the package at the door', // optional order notes
    * });
    * console.log('Available rates:', rates);
    * ```
@@ -5454,6 +5465,44 @@ var BrainerceClient = class {
       waitedMs: Date.now() - startTime
     };
   }
+  /**
+   * Get the full order created by a completed checkout.
+   *
+   * Use this on the order-confirmation page (after `waitForOrder` succeeds)
+   * when you want to render more than the order number — line items, shipping
+   * address, financial breakdown, and the shopper's order note are all
+   * included (the buyer-safe order shape, same as `getMyOrders`).
+   *
+   * Works for guests too: possession of the checkout id is the credential —
+   * no customer token needed.
+   *
+   * @example
+   * ```typescript
+   * const result = await client.waitForOrder(checkoutId);
+   * if (result.success) {
+   *   const order = await client.getOrderByCheckout(checkoutId);
+   *   // order.items, order.shippingAddress, order.notes, order.totalAmount, ...
+   * }
+   * ```
+   */
+  async getOrderByCheckout(checkoutId) {
+    if (this.isVibeCodedMode()) {
+      return this.withGuards(
+        this.vibeCodedRequest("GET", `/checkout/${encodePathSegment(checkoutId)}/order`),
+        "order"
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.withGuards(
+        this.storefrontRequest("GET", `/checkout/${encodePathSegment(checkoutId)}/order`),
+        "order"
+      );
+    }
+    throw new BrainerceError(
+      "getOrderByCheckout() requires vibe-coded or storefront mode",
+      400
+    );
+  }
   /**
    * Check if localStorage is available (browser environment)
    */
@@ -6226,6 +6275,9 @@ var BrainerceClient = class {
   /**
    * Update the current customer's profile (requires customerToken)
    * Only available in storefront mode
+   *
+   * `birthMonth`/`birthDay` (1-12 / 1-31, no year — privacy) power the loyalty
+   * birthday gift; they must be provided together.
    */
   async updateMyProfile(data) {
     if (!this.customerToken && !this.proxyMode) {
@@ -6341,6 +6393,57 @@ var BrainerceClient = class {
     }
     throw new BrainerceError("redeemLoyaltyReward is only available in storefront mode", 400);
   }
+  /**
+   * Report a social share, granting the SOCIAL_SHARE earning-rule bonus if the
+   * store has one configured (requires customerToken). Self-reported — no
+   * share-tracking infra — and capped at once per customer per program. Only
+   * available in storefront mode.
+   *
+   * @example
+   * ```typescript
+   * await client.reportSocialShare('instagram');
+   * ```
+   */
+  async reportSocialShare(platform) {
+    if (!this.customerToken && !this.proxyMode) {
+      throw new BrainerceError(
+        "Customer token required. Call setCustomerToken() after login.",
+        401
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "POST",
+        "/loyalty/social-share",
+        platform ? { platform } : {}
+      );
+    }
+    throw new BrainerceError("reportSocialShare is only available in storefront mode", 400);
+  }
+  /**
+   * Public referral-link lookup: who referred the visitor and what welcome
+   * reward awaits them. No customerToken needed (like getStoreInfo/trackEvent)
+   * — safe to call on a referral landing page before signup. Returns
+   * `{ valid: false }` for unknown codes or stores with referrals disabled.
+   * Only available in storefront mode.
+   *
+   * @example
+   * ```typescript
+   * const info = await client.getReferralInfo(searchParams.get('ref')!);
+   * if (info.valid) {
+   *   showBanner(`${info.referrerFirstName ?? 'A friend'} sent you a gift!`);
+   *   // later: client.registerCustomer({ ...form, referralCode })
+   * }
+   * ```
+   */
+  async getReferralInfo(code) {
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", "/loyalty/referral-info", void 0, {
+        code
+      });
+    }
+    throw new BrainerceError("getReferralInfo is only available in storefront mode", 400);
+  }
   /**
    * Get the current customer's orders (requires customerToken)
    * Works in vibe-coded and storefront modes
@@ -7751,52 +7854,92 @@ var BrainerceClient = class {
       { vibeCodedConnectionId }
     );
   }
+  /**
+   * Publish a product to a sales channel (admin mode) — makes it visible on
+   * that vibe-coded storefront. Accepts the sales-channel record ID or its
+   * public `vc_*` connection ID.
+   */
+  async publishProductToSalesChannel(productId, salesChannelId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/products/${encodePathSegment(productId)}/publish-sales-channel`,
+      { salesChannelId }
+    );
+  }
+  /** Unpublish a product from a sales channel (admin mode). */
+  async unpublishProductFromSalesChannel(productId, salesChannelId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/products/${encodePathSegment(productId)}/unpublish-sales-channel`,
+      { salesChannelId }
+    );
+  }
+  /**
+   * Publish a coupon to a sales channel (admin mode) — makes it redeemable on
+   * that vibe-coded storefront. Accepts the sales-channel record ID or its
+   * public `vc_*` connection ID.
+   */
+  async publishCouponToSalesChannel(couponId, salesChannelId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/coupons/${encodePathSegment(couponId)}/publish-sales-channel`,
+      { salesChannelId }
+    );
+  }
+  /** Unpublish a coupon from a sales channel (admin mode). */
+  async unpublishCouponFromSalesChannel(couponId, salesChannelId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/coupons/${encodePathSegment(couponId)}/unpublish-sales-channel`,
+      { salesChannelId }
+    );
+  }
   /** Publish a category to a vibe-coded site (admin mode). */
   async publishCategoryToVibeCodedSite(categoryId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/categories/${encodePathSegment(categoryId)}/publish-vibe-coded`,
-      { vibeCodedConnectionId }
+      `/api/v1/categories/${encodePathSegment(categoryId)}/publish-sales-channel`,
+      { salesChannelId: vibeCodedConnectionId }
     );
   }
   /** Unpublish a category from a vibe-coded site (admin mode). */
   async unpublishCategoryFromVibeCodedSite(categoryId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/categories/${encodePathSegment(categoryId)}/unpublish-vibe-coded`,
-      { vibeCodedConnectionId }
+      `/api/v1/categories/${encodePathSegment(categoryId)}/unpublish-sales-channel`,
+      { salesChannelId: vibeCodedConnectionId }
     );
   }
   /** Publish a tag to a vibe-coded site (admin mode). */
   async publishTagToVibeCodedSite(tagId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/tags/${encodePathSegment(tagId)}/publish-vibe-coded`,
-      { vibeCodedConnectionId }
+      `/api/v1/tags/${encodePathSegment(tagId)}/publish-sales-channel`,
+      { salesChannelId: vibeCodedConnectionId }
     );
   }
   /** Unpublish a tag from a vibe-coded site (admin mode). */
   async unpublishTagFromVibeCodedSite(tagId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/tags/${encodePathSegment(tagId)}/unpublish-vibe-coded`,
-      { vibeCodedConnectionId }
+      `/api/v1/tags/${encodePathSegment(tagId)}/unpublish-sales-channel`,
+      { salesChannelId: vibeCodedConnectionId }
     );
   }
   /** Publish a brand to a vibe-coded site (admin mode). */
   async publishBrandToVibeCodedSite(brandId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/brands/${encodePathSegment(brandId)}/publish-vibe-coded`,
-      { vibeCodedConnectionId }
+      `/api/v1/brands/${encodePathSegment(brandId)}/publish-sales-channel`,
+      { salesChannelId: vibeCodedConnectionId }
     );
   }
   /** Unpublish a brand from a vibe-coded site (admin mode). */
   async unpublishBrandFromVibeCodedSite(brandId, vibeCodedConnectionId) {
     return this.adminRequest(
       "POST",
-      `/api/v1/brands/${encodePathSegment(brandId)}/unpublish-vibe-coded`,
-      { vibeCodedConnectionId }
+      `/api/v1/brands/${encodePathSegment(brandId)}/unpublish-sales-channel`,
+      { salesChannelId: vibeCodedConnectionId }
     );
   }
   /**

package/package.json

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