brainerce 1.58.1 → 1.59.0

package/dist/index.d.ts

@@ -2665,7 +2665,8 @@ interface AddToCartDto {
      * Modifier-group selections for restaurant / customizable products
      * (e.g., toppings, sauces, sides). The server validates against effective
      * group rules and rejects invalid payloads with a `MODIFIER_VALIDATION_FAILED`
-     * envelope (`BrainerceError.errorData`).
+     * envelope, readable at `BrainerceError.details` — see
+     * {@link ModifierValidationFailedError}.
      */
     selections?: ModifierSelection[];
     /**
@@ -3889,19 +3890,99 @@ interface StockAvailabilityResponse {
     allAvailable: boolean;
     results: StockAvailabilityResult[];
 }
+/**
+ * Body of a `409`/`400` stock rejection, as it actually arrives on the wire.
+ *
+ * This is the shape of `BrainerceError.details` — the SDK puts the **whole
+ * parsed response body** there, so you read `err.details.code` and the
+ * quantities under `err.details.details`:
+ *
+ * ```typescript
+ * try {
+ *   await client.addToCart(cartId, { productId, quantity: 5 });
+ * } catch (err) {
+ *   const body = (err as BrainerceError).details as InsufficientStockError;
+ *   if (body?.code === 'INSUFFICIENT_STOCK') {
+ *     // single-line rejection (add-to-cart, reservation)
+ *     console.log(body.details.available, body.details.requested);
+ *     // multi-line rejection (checkout) — every offending line
+ *     body.details.items?.forEach((i) => console.log(i.productId, i.available));
+ *   }
+ * }
+ * ```
+ *
+ * Which keys are populated depends on where the error came from:
+ *   - Cart add/update and inventory reservation reject **one** line, so they
+ *     send `available` + `requested`.
+ *   - Checkout validates the **whole** cart, so it sends `items[]`.
+ * Treat every key as optional and branch on what is present.
+ */
 interface InsufficientStockError {
     code: 'INSUFFICIENT_STOCK';
     message: string;
-    available: number;
-    requested: number;
-    productId?: string;
-    variantId?: string;
-    items?: Array<{
-        productId: string;
-        variantId?: string;
-        available: number;
-        requested: number;
-    }>;
+    details: {
+        /** Units actually purchasable. Single-line rejections only. */
+        available?: number;
+        /** Units the request asked for. Single-line rejections only. */
+        requested?: number;
+        productId?: string;
+        variantId?: string | null;
+        /** Per-line breakdown. Checkout-time rejections only. */
+        items?: Array<{
+            productId: string;
+            variantId?: string | null;
+            available?: number;
+            requested?: number;
+        }>;
+    };
+}
+/**
+ * Body of a `400` modifier-selection rejection (`MODIFIER_VALIDATION_FAILED`).
+ *
+ * Like every error body, this is what lands in `BrainerceError.details`, so
+ * the issue list is `err.details.details.errors`. Render each entry inline
+ * next to the group or modifier it names.
+ */
+interface ModifierValidationFailedError {
+    code: 'MODIFIER_VALIDATION_FAILED';
+    message: string;
+    details: {
+        errors: ModifierValidationError[];
+    };
+}
+/**
+ * Body of a `400` price-drift rejection (`PRICE_DRIFT`), raised by
+ * `createCheckout` when a cart line's snapshot price no longer matches the
+ * live price. Recover with `refreshCartSnapshots()` or by removing the lines.
+ */
+interface PriceDriftError {
+    code: 'PRICE_DRIFT';
+    message: string;
+    details: {
+        items: Array<{
+            itemId: string;
+            productId: string;
+            variantId?: string | null;
+            oldUnitPrice: string;
+            newUnitPrice: string;
+            delta: string;
+            direction: 'increased' | 'decreased';
+        }>;
+    };
+}
+/**
+ * Body of a `400` `PRODUCT_UNAVAILABLE` rejection — a line's product was
+ * deleted, unpublished, or has inventory tracking disabled.
+ */
+interface ProductUnavailableError {
+    code: 'PRODUCT_UNAVAILABLE';
+    message: string;
+    details?: {
+        items?: Array<{
+            productId: string;
+            variantId?: string | null;
+        }>;
+    };
 }
 interface PublishProductResponse {
     productId: string;
@@ -4682,7 +4763,8 @@ interface ShippingRateConfig {
     minDeliveryDays?: number | null;
     maxDeliveryDays?: number | null;
     handlingTime?: number | null;
-    taxStatus: 'TAXABLE' | 'NOT_TAXABLE';
+    /** Whether the delivery charge itself is taxed. `NONE` leaves postage untaxed; omitted (or `TAXABLE`) taxes it at the store's standard rate. */
+    taxStatus: 'TAXABLE' | 'NONE';
     minOrderAmount?: number | null;
     maxCost?: number | null;
     isActive: boolean;
@@ -4732,7 +4814,8 @@ interface CreateShippingRateDto {
     minDeliveryDays?: number;
     maxDeliveryDays?: number;
     handlingTime?: number;
-    taxStatus?: 'TAXABLE' | 'NOT_TAXABLE';
+    /** Whether the delivery charge itself is taxed. `NONE` leaves postage untaxed; omitted (or `TAXABLE`) taxes it at the store's standard rate. */
+    taxStatus?: 'TAXABLE' | 'NONE';
     minOrderAmount?: number;
     maxCost?: number;
     isActive?: boolean;
@@ -4745,7 +4828,8 @@ interface UpdateShippingRateDto {
     minDeliveryDays?: number | null;
     maxDeliveryDays?: number | null;
     handlingTime?: number | null;
-    taxStatus?: 'TAXABLE' | 'NOT_TAXABLE';
+    /** Whether the delivery charge itself is taxed. `NONE` leaves postage untaxed; omitted (or `TAXABLE`) taxes it at the store's standard rate. */
+    taxStatus?: 'TAXABLE' | 'NONE';
     minOrderAmount?: number | null;
     maxCost?: number | null;
     isActive?: boolean;
@@ -4767,16 +4851,29 @@ interface TaxRate {
     accountId: string;
     storeId: string;
     name: string;
-    /** Tax rate as decimal (e.g., 0.17 for 17%) */
+    /**
+     * Tax rate as a **percentage**, e.g. `"8.5"` for 8.5%. Range 0–100.
+     *
+     * Note this differs from {@link TaxBreakdownItem.rate}, which is a decimal
+     * fraction (`0.085`) because it is computed rather than stored.
+     */
     rate: string;
     /** ISO country code */
     country?: string | null;
     /** Region/state code */
     region?: string | null;
-    /** Postal code pattern */
+    /**
+     * Postal code, matched **exactly** (case-insensitive, spaces and hyphens
+     * ignored). Wildcards, prefixes and ranges are NOT supported — `941*` and
+     * `94100-94199` match nothing.
+     */
     postalCode?: string | null;
     taxType: string;
-    /** Whether this rate compounds on other rates */
+    /**
+     * @deprecated Not implemented. There is no `isCompound` column, nothing
+     * reads this value, and rates never compound. Sending it on a create or
+     * update request is rejected with a 400.
+     */
     isCompound: boolean;
     /** Whether tax is included in prices */
     isInclusive: boolean;
@@ -4791,11 +4888,17 @@ interface TaxRate {
 }
 interface CreateTaxRateDto {
     name: string;
+    /** Tax rate as a **percentage**, e.g. `8.5` for 8.5%. Range 0–100. */
     rate: number;
     country?: string;
     region?: string;
+    /** Matched exactly — wildcards, prefixes and ranges are NOT supported. */
     postalCode?: string;
     taxType?: string;
+    /**
+     * @deprecated Not implemented — the backend rejects this field with a 400.
+     * Rates never compound. Omit it.
+     */
     isCompound?: boolean;
     isInclusive?: boolean;
     /** Tax class this rate applies to. Omit/null = Standard. */
@@ -4806,11 +4909,17 @@ interface CreateTaxRateDto {
 }
 interface UpdateTaxRateDto {
     name?: string;
+    /** Tax rate as a **percentage**, e.g. `8.5` for 8.5%. Range 0–100. */
     rate?: number;
     country?: string | null;
     region?: string | null;
+    /** Matched exactly — wildcards, prefixes and ranges are NOT supported. */
     postalCode?: string | null;
     taxType?: string;
+    /**
+     * @deprecated Not implemented — the backend rejects this field with a 400.
+     * Rates never compound. Omit it.
+     */
     isCompound?: boolean;
     isInclusive?: boolean;
     priority?: number;
@@ -6637,11 +6746,13 @@ declare function getDirectionForLocale(locale: string | undefined | null): 'ltr'
  *
  * Three modes of operation:
  *
- * **Vibe-Coded Mode (Simplest)** - Use connectionId for vibe-coded sites:
+ * **Sales-Channel Mode (Simplest)** - Use salesChannelId for vibe-coded sites:
  * ```typescript
- * const client = new BrainerceClient({ connectionId: 'vc_abc123...' });
+ * const client = new BrainerceClient({ salesChannelId: 'vc_abc123...' });
  * const products = await client.getProducts();
  * ```
+ * (`connectionId` is a deprecated alias of `salesChannelId`. It still works but
+ * logs a deprecation warning on every construction and is removed in SDK 2.0.)
  *
  * **Storefront Mode (Frontend)** - Use storeId for public access:
  * ```typescript
@@ -8852,7 +8963,9 @@ declare class BrainerceClient {
      * try {
      *   await client.createCheckout(cartId);
      * } catch (err) {
-     *   if (err.code === 'PRICE_DRIFT') {
+     *   // BrainerceError.details is the whole response body — the code lives
+     *   // there, NOT on the error object itself.
+     *   if ((err as BrainerceError).details?.code === 'PRICE_DRIFT') {
      *     // ask user to confirm new prices, then:
      *     await client.refreshCartSnapshots(cartId);
      *     await client.createCheckout(cartId);
@@ -9633,12 +9746,18 @@ declare class BrainerceClient {
      * Get applicable custom field definitions for a checkout.
      * Returns fields filtered by visibility conditions (delivery type, products in cart).
      * Use these to render dynamic input fields in the checkout flow.
+     *
+     * **Vibe-coded or storefront mode only.** There is no checkout custom-field
+     * route on the API-key `/v1` surface; in admin mode this throws.
      */
     getCheckoutCustomFields(checkoutId: string): Promise<CheckoutCustomFieldDefinition[]>;
     /**
      * Set checkout custom field values and recalculate surcharges.
      * The checkout total is automatically updated to include surcharges.
      *
+     * **Vibe-coded or storefront mode only.** There is no checkout custom-field
+     * route on the API-key `/v1` surface; in admin mode this throws.
+     *
      * @example
      * ```typescript
      * const checkout = await client.setCheckoutCustomFields(checkoutId, {
@@ -11414,31 +11533,38 @@ declare class BrainerceClient {
         key: string;
     }>;
     /**
-     * @deprecated Use `getStoreTeam(storeId)` instead.
+     * @deprecated Retiring, but there is no API-key replacement yet: `getStoreTeam`
+     * is dashboard-only (403 for api_key). Keep using this until one ships.
      */
     getTeamMembers(): Promise<TeamMembersResponse>;
     /**
-     * @deprecated Use `getStoreTeam(storeId)` instead.
+     * @deprecated Retiring, but there is no API-key replacement yet: `getStoreTeam`
+     * is dashboard-only (403 for api_key). Keep using this until one ships.
      */
     getTeamInvitations(): Promise<TeamInvitationsResponse>;
     /**
-     * @deprecated Use `inviteStoreMember(storeId, data)` instead.
+     * @deprecated Retiring, but there is no API-key replacement yet: `inviteStoreMember`
+     * is dashboard-only (403 for api_key). Keep using this until one ships.
      */
     inviteTeamMember(data: InviteMemberDto): Promise<TeamInvitation>;
     /**
-     * @deprecated Use `resendStoreInvitation(storeId, invitationId)` instead.
+     * @deprecated Retiring, but there is no API-key replacement yet: `resendStoreInvitation`
+     * is dashboard-only (403 for api_key). Keep using this until one ships.
      */
     resendTeamInvitation(invitationId: string): Promise<TeamInvitation>;
     /**
-     * @deprecated Use `revokeStoreInvitation(storeId, invitationId)` instead.
+     * @deprecated Retiring, but there is no API-key replacement yet: `revokeStoreInvitation`
+     * is dashboard-only (403 for api_key). Keep using this until one ships.
      */
     revokeTeamInvitation(invitationId: string): Promise<void>;
     /**
-     * @deprecated Use `updateStoreMember(storeId, memberId, data)` instead.
+     * @deprecated Retiring, but there is no API-key replacement yet: `updateStoreMember`
+     * is dashboard-only (403 for api_key). Keep using this until one ships.
      */
     updateTeamMemberRole(memberId: string, data: UpdateMemberRoleDto): Promise<TeamMember>;
     /**
-     * @deprecated Use `removeStoreMember(storeId, memberId)` instead.
+     * @deprecated Retiring, but there is no API-key replacement yet: `removeStoreMember`
+     * is dashboard-only (403 for api_key). Keep using this until one ships.
      */
     removeTeamMember(memberId: string): Promise<void>;
     /**
@@ -12153,4 +12279,4 @@ interface CategorySitemapOptions {
  */
 declare function getCategorySitemapEntries(client: BrainerceClient, opts: CategorySitemapOptions): Promise<SitemapEntry[]>;
 
-export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BlogPost, type BlogPostListParams, type BlogPostListResponse, type BlogSitemapOptions, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkCreateProductsDto, type BulkCreateProductsError, type BulkCreateProductsJob, type BulkCreateProductsStatus, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type BusinessHoursWindow, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryDetail, type CategoryNode, type CategorySitemapOptions, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DateAvailabilityConstraints, type DateFieldParseResult, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type JsonLdOptions, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyStatus, type LoyaltyTierSummary, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldFilter, type MetafieldFilterValue, type MetafieldFiltersResponse, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type MyProductReview, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type ParsedDateFieldValue, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductSitemapOptions, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type StoreTracking, type SubmitProductReviewInput, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type TrackingEventItem, type TrackingEventName, type TrackingEventPayload, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, buildArticleJsonLd, buildBreadcrumbJsonLd, buildCollectionPageJsonLd, buildOrganizationJsonLd, buildProductFaqJsonLd, buildProductJsonLd, buildWebsiteJsonLd, computeAvailableSlots, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getBlogSitemapEntries, getBusinessHoursForDate, getCartItemImage, getCartItemName, getCartTotals, getCategorySitemapEntries, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSitemapEntries, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCalendarDateAllowed, isCouponApplicableToProduct, isDateValueAllowed, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseDateFieldValue, parseWebhookEvent, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };
+export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BlogPost, type BlogPostListParams, type BlogPostListResponse, type BlogSitemapOptions, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkCreateProductsDto, type BulkCreateProductsError, type BulkCreateProductsJob, type BulkCreateProductsStatus, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type BusinessHoursWindow, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryDetail, type CategoryNode, type CategorySitemapOptions, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DateAvailabilityConstraints, type DateFieldParseResult, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type JsonLdOptions, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyStatus, type LoyaltyTierSummary, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldFilter, type MetafieldFilterValue, type MetafieldFiltersResponse, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type ModifierValidationFailedError, type MyProductReview, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type ParsedDateFieldValue, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type PriceDriftError, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductSitemapOptions, type ProductSuggestion, type ProductUnavailableError, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type StoreTracking, type SubmitProductReviewInput, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type TrackingEventItem, type TrackingEventName, type TrackingEventPayload, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, buildArticleJsonLd, buildBreadcrumbJsonLd, buildCollectionPageJsonLd, buildOrganizationJsonLd, buildProductFaqJsonLd, buildProductJsonLd, buildWebsiteJsonLd, computeAvailableSlots, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getBlogSitemapEntries, getBusinessHoursForDate, getCartItemImage, getCartItemName, getCartTotals, getCategorySitemapEntries, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSitemapEntries, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCalendarDateAllowed, isCouponApplicableToProduct, isDateValueAllowed, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseDateFieldValue, parseWebhookEvent, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };

package/dist/index.js

@@ -4205,7 +4205,9 @@ var _BrainerceClient = class _BrainerceClient {
    * try {
    *   await client.createCheckout(cartId);
    * } catch (err) {
-   *   if (err.code === 'PRICE_DRIFT') {
+   *   // BrainerceError.details is the whole response body — the code lives
+   *   // there, NOT on the error object itself.
+   *   if ((err as BrainerceError).details?.code === 'PRICE_DRIFT') {
    *     // ask user to confirm new prices, then:
    *     await client.refreshCartSnapshots(cartId);
    *     await client.createCheckout(cartId);
@@ -6043,6 +6045,9 @@ var _BrainerceClient = class _BrainerceClient {
    * Get applicable custom field definitions for a checkout.
    * Returns fields filtered by visibility conditions (delivery type, products in cart).
    * Use these to render dynamic input fields in the checkout flow.
+   *
+   * **Vibe-coded or storefront mode only.** There is no checkout custom-field
+   * route on the API-key `/v1` surface; in admin mode this throws.
    */
   async getCheckoutCustomFields(checkoutId) {
     if (this.isVibeCodedMode()) {
@@ -6057,15 +6062,18 @@ var _BrainerceClient = class _BrainerceClient {
         `/checkout/${encodePathSegment(checkoutId)}/custom-fields`
       );
     }
-    return this.adminRequest(
-      "GET",
-      `/api/v1/checkouts/${encodePathSegment(checkoutId)}/custom-fields`
+    throw new BrainerceError(
+      "getCheckoutCustomFields is only available in vibe-coded or storefront mode",
+      400
     );
   }
   /**
    * Set checkout custom field values and recalculate surcharges.
    * The checkout total is automatically updated to include surcharges.
    *
+   * **Vibe-coded or storefront mode only.** There is no checkout custom-field
+   * route on the API-key `/v1` surface; in admin mode this throws.
+   *
    * @example
    * ```typescript
    * const checkout = await client.setCheckoutCustomFields(checkoutId, {
@@ -6093,10 +6101,9 @@ var _BrainerceClient = class _BrainerceClient {
         data
       );
     }
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/checkouts/${encodePathSegment(checkoutId)}/custom-fields`,
-      data
+    throw new BrainerceError(
+      "setCheckoutCustomFields is only available in vibe-coded or storefront mode",
+      400
     );
   }
   /**
@@ -8362,8 +8369,9 @@ var _BrainerceClient = class _BrainerceClient {
   //         /api/stores/:storeId/products/:productId/modifier-groups[/:attachmentId]
   //
   // Server-side validation failures arrive as a structured 400 envelope:
-  //   { code: 'MODIFIER_VALIDATION_FAILED', errors: ModifierValidationError[] }
-  // surfaced via BrainerceError.details.
+  //   { code: 'MODIFIER_VALIDATION_FAILED', message, details: { errors: [...] } }
+  // BrainerceError.details holds the WHOLE body, so the issue list is
+  // `err.details.details.errors` — see ModifierValidationFailedError.
   /**
    * List modifier groups in a store, paginated.
    * Requires Admin mode (apiKey).
@@ -9415,27 +9423,36 @@ var _BrainerceClient = class _BrainerceClient {
     throw new Error("uploadCustomizationFile requires storefront or vibe-coded mode");
   }
   // -------------------- Team Management (Admin) - DEPRECATED --------------------
-  // These account-level methods are deprecated. Use Store Team Management methods instead.
+  // Account-level team methods. These are the ONLY team endpoints reachable with
+  // a `brainerce_*` API key. The store-level equivalents (`getStoreTeam`,
+  // `inviteStoreMember`, `updateStoreMember`, ...) sit behind
+  // `DashboardOnlyGuard`, which rejects api_key principals by design — so they
+  // return 403 from the SDK, not 404, and "fixing" their path would not help.
+  // Do not migrate SDK code onto them.
   /**
-   * @deprecated Use `getStoreTeam(storeId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `getStoreTeam`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async getTeamMembers() {
     return this.adminRequest("GET", "/api/v1/team/members");
   }
   /**
-   * @deprecated Use `getStoreTeam(storeId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `getStoreTeam`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async getTeamInvitations() {
     return this.adminRequest("GET", "/api/v1/team/invitations");
   }
   /**
-   * @deprecated Use `inviteStoreMember(storeId, data)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `inviteStoreMember`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async inviteTeamMember(data) {
     return this.adminRequest("POST", "/api/v1/team/invitations", data);
   }
   /**
-   * @deprecated Use `resendStoreInvitation(storeId, invitationId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `resendStoreInvitation`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async resendTeamInvitation(invitationId) {
     return this.adminRequest(
@@ -9444,7 +9461,8 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * @deprecated Use `revokeStoreInvitation(storeId, invitationId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `revokeStoreInvitation`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async revokeTeamInvitation(invitationId) {
     await this.adminRequest(
@@ -9453,7 +9471,8 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * @deprecated Use `updateStoreMember(storeId, memberId, data)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `updateStoreMember`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async updateTeamMemberRole(memberId, data) {
     return this.adminRequest(
@@ -9463,7 +9482,8 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * @deprecated Use `removeStoreMember(storeId, memberId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `removeStoreMember`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async removeTeamMember(memberId) {
     await this.adminRequest("DELETE", `/api/v1/team/members/${encodePathSegment(memberId)}`);

package/dist/index.mjs

@@ -4117,7 +4117,9 @@ var _BrainerceClient = class _BrainerceClient {
    * try {
    *   await client.createCheckout(cartId);
    * } catch (err) {
-   *   if (err.code === 'PRICE_DRIFT') {
+   *   // BrainerceError.details is the whole response body — the code lives
+   *   // there, NOT on the error object itself.
+   *   if ((err as BrainerceError).details?.code === 'PRICE_DRIFT') {
    *     // ask user to confirm new prices, then:
    *     await client.refreshCartSnapshots(cartId);
    *     await client.createCheckout(cartId);
@@ -5955,6 +5957,9 @@ var _BrainerceClient = class _BrainerceClient {
    * Get applicable custom field definitions for a checkout.
    * Returns fields filtered by visibility conditions (delivery type, products in cart).
    * Use these to render dynamic input fields in the checkout flow.
+   *
+   * **Vibe-coded or storefront mode only.** There is no checkout custom-field
+   * route on the API-key `/v1` surface; in admin mode this throws.
    */
   async getCheckoutCustomFields(checkoutId) {
     if (this.isVibeCodedMode()) {
@@ -5969,15 +5974,18 @@ var _BrainerceClient = class _BrainerceClient {
         `/checkout/${encodePathSegment(checkoutId)}/custom-fields`
       );
     }
-    return this.adminRequest(
-      "GET",
-      `/api/v1/checkouts/${encodePathSegment(checkoutId)}/custom-fields`
+    throw new BrainerceError(
+      "getCheckoutCustomFields is only available in vibe-coded or storefront mode",
+      400
     );
   }
   /**
    * Set checkout custom field values and recalculate surcharges.
    * The checkout total is automatically updated to include surcharges.
    *
+   * **Vibe-coded or storefront mode only.** There is no checkout custom-field
+   * route on the API-key `/v1` surface; in admin mode this throws.
+   *
    * @example
    * ```typescript
    * const checkout = await client.setCheckoutCustomFields(checkoutId, {
@@ -6005,10 +6013,9 @@ var _BrainerceClient = class _BrainerceClient {
         data
       );
     }
-    return this.adminRequest(
-      "PATCH",
-      `/api/v1/checkouts/${encodePathSegment(checkoutId)}/custom-fields`,
-      data
+    throw new BrainerceError(
+      "setCheckoutCustomFields is only available in vibe-coded or storefront mode",
+      400
     );
   }
   /**
@@ -8274,8 +8281,9 @@ var _BrainerceClient = class _BrainerceClient {
   //         /api/stores/:storeId/products/:productId/modifier-groups[/:attachmentId]
   //
   // Server-side validation failures arrive as a structured 400 envelope:
-  //   { code: 'MODIFIER_VALIDATION_FAILED', errors: ModifierValidationError[] }
-  // surfaced via BrainerceError.details.
+  //   { code: 'MODIFIER_VALIDATION_FAILED', message, details: { errors: [...] } }
+  // BrainerceError.details holds the WHOLE body, so the issue list is
+  // `err.details.details.errors` — see ModifierValidationFailedError.
   /**
    * List modifier groups in a store, paginated.
    * Requires Admin mode (apiKey).
@@ -9327,27 +9335,36 @@ var _BrainerceClient = class _BrainerceClient {
     throw new Error("uploadCustomizationFile requires storefront or vibe-coded mode");
   }
   // -------------------- Team Management (Admin) - DEPRECATED --------------------
-  // These account-level methods are deprecated. Use Store Team Management methods instead.
+  // Account-level team methods. These are the ONLY team endpoints reachable with
+  // a `brainerce_*` API key. The store-level equivalents (`getStoreTeam`,
+  // `inviteStoreMember`, `updateStoreMember`, ...) sit behind
+  // `DashboardOnlyGuard`, which rejects api_key principals by design — so they
+  // return 403 from the SDK, not 404, and "fixing" their path would not help.
+  // Do not migrate SDK code onto them.
   /**
-   * @deprecated Use `getStoreTeam(storeId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `getStoreTeam`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async getTeamMembers() {
     return this.adminRequest("GET", "/api/v1/team/members");
   }
   /**
-   * @deprecated Use `getStoreTeam(storeId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `getStoreTeam`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async getTeamInvitations() {
     return this.adminRequest("GET", "/api/v1/team/invitations");
   }
   /**
-   * @deprecated Use `inviteStoreMember(storeId, data)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `inviteStoreMember`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async inviteTeamMember(data) {
     return this.adminRequest("POST", "/api/v1/team/invitations", data);
   }
   /**
-   * @deprecated Use `resendStoreInvitation(storeId, invitationId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `resendStoreInvitation`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async resendTeamInvitation(invitationId) {
     return this.adminRequest(
@@ -9356,7 +9373,8 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * @deprecated Use `revokeStoreInvitation(storeId, invitationId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `revokeStoreInvitation`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async revokeTeamInvitation(invitationId) {
     await this.adminRequest(
@@ -9365,7 +9383,8 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * @deprecated Use `updateStoreMember(storeId, memberId, data)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `updateStoreMember`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async updateTeamMemberRole(memberId, data) {
     return this.adminRequest(
@@ -9375,7 +9394,8 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * @deprecated Use `removeStoreMember(storeId, memberId)` instead.
+   * @deprecated Retiring, but there is no API-key replacement yet: `removeStoreMember`
+   * is dashboard-only (403 for api_key). Keep using this until one ships.
    */
   async removeTeamMember(memberId) {
     await this.adminRequest("DELETE", `/api/v1/team/members/${encodePathSegment(memberId)}`);

package/package.json

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