brainerce 2.8.0 → 2.9.0

package/README.md

@@ -201,7 +201,7 @@ These sequences are non-negotiable. The order of SDK calls matters.
    ```ts
    const providers = await client.getPaymentProviders();
    ```
-   Each provider has a `renderType`: `'sdk-widget'` (Stripe, PayPal, Grow), `'iframe'` (Cardcom), `'redirect'`, `'sandbox'`. Branch on `renderType`, never on provider name.
+   Each provider has a `renderType`: `'sdk-widget'` (Stripe, PayPal, Grow), `'iframe'` (Cardcom), `'redirect'` (Morning, Takbull, iCredit), `'sandbox'`. Branch on `renderType`, never on provider name. A provider's `clientSdk.displayModes` lists every mode it can serve; you may ask for one with `createPaymentIntent(checkoutId, { preferredRenderType: 'iframe' | 'redirect' })`, and the platform honours it only from that list, so still branch on what comes back.
 5. Confirm payment using the provider's flow (Stripe Elements `stripe.confirmCardPayment`, PayPal button, redirect, etc.).
 6. On the confirmation page, **always call both**:
    ```ts
@@ -433,6 +433,7 @@ The SDK exports these utility functions for common UI tasks:
 | `isCouponApplicableToProduct(coupon, product)` | Check if coupon applies                                                                                                               | `isCouponApplicableToProduct(coupon, product)`                     |
 | `isAllowedPaymentUrl(url, options?)`           | Validate a payment URL host                                                                                                           | `isAllowedPaymentUrl(intent.clientSecret)` → `true`                |
 | `safePaymentRedirect(url, options?)`           | Validate then `window.location.href`                                                                                                  | `safePaymentRedirect(intent.clientSecret)`                         |
+| `resolveRenderType(clientSdk, preferred?)`     | Predict the `renderType` an intent will come back with (the platform's own rule), so you can pick `successUrl` before creating it    | `resolveRenderType(provider.clientSdk, 'iframe')` → `'iframe'`     |
 | `buildProductJsonLd(product, opts)`            | schema.org Product JSON-LD (PDPs only)                                                                                                | See SEO section                                                    |
 | `buildArticleJsonLd(post, opts)`               | schema.org Article JSON-LD for blog posts                                                                                             | See SEO section                                                    |
 | `buildOrganizationJsonLd(store, opts)`         | schema.org Organization for the homepage                                                                                              | See SEO section                                                    |
@@ -1323,9 +1324,9 @@ The SDK uses **server-side carts for all users**. Guests get automatic session c
 > operation — that one pushes to external platforms, not to your storefront.
 
 > **A shopper cart holds at most 50 distinct lines.** Adding a 51st _different_
-> product throws `400 "A cart can hold at most 50 different items. Remove
-> something before adding more."` It is a fixed platform limit with no per-store
-> setting. **It applies in channel (`salesChannelId: 'vc_*'`) and store
+> product throws a `400` carrying the error code `CART_LINE_LIMIT_REACHED`, with
+> the limit itself on `details.maxLines`. It is a fixed platform limit with no
+> per-store setting. **It applies in channel (`salesChannelId: 'vc_*'`) and store
 > (`storeId`) mode only — an admin (`apiKey: 'brainerce_*'`) cart is not
 > capped**, because a B2B or bulk-import cart legitimately runs long, so the same
 > call can succeed for one client and fail for another. The cap counts distinct
@@ -1337,6 +1338,23 @@ The SDK uses **server-side carts for all users**. Guests get automatic session c
 > the earlier products of that bundle in the cart, so re-read the cart after a
 > failed bundle add.
 
+**Detect a full cart by the code, not by the sentence.** The SDK hands the whole parsed
+error body back on `BrainerceError.details`, so the code is one level in and the limit sits
+beside it — `err.code` is NOT where it lives:
+
+```typescript
+catch (err) {
+  const body = (err as BrainerceError).details as
+    { code?: string; details?: { maxLines?: number } } | undefined;
+  if (body?.code === 'CART_LINE_LIMIT_REACHED') showCartFull(body.details?.maxLines ?? 50);
+}
+```
+
+⛔ **Keep any existing match on the message as a fallback.** The wording is byte-for-byte
+unchanged on purpose — storefronts written before the code existed still depend on it, and a
+storefront can be talking to a backend that has not been redeployed yet. Branch on the code
+first, then fall through to the prose match.
+
 ```typescript
 // Add to cart (guest or logged-in — same code!)
 await client.smartAddToCart({ productId: 'prod_123', quantity: 2 });
@@ -2627,8 +2645,10 @@ await client.smartAddToCart({
 > `MODIFIER_VALIDATION_FAILED` envelope on `BrainerceError.details`.
 >
 > **The 50-distinct-line cap applies here too** (channel and store mode; not
-> admin). A 51st different product throws `400 "A cart can hold at most 50
-> different items. Remove something before adding more."` — see
+> admin). A 51st different product throws a `400` carrying the error code
+> `CART_LINE_LIMIT_REACHED` on `BrainerceError.details.code`, with the limit on
+> `BrainerceError.details.details.maxLines`. Branch on the code and keep any existing match on
+> the (unchanged) message text as a fallback — see
 > [Cart (Unified for All Users)](#cart-unified-for-all-users) above.
 
 #### Get Cart
@@ -2895,9 +2915,11 @@ const cart = await client.addToCart(cartId, {
 ```
 
 > **Capped at 50 distinct lines** in channel and store mode (not admin): a 51st
-> different product throws `400 "A cart can hold at most 50 different items.
-> Remove something before adding more."` Quantity changes on an already-full cart
-> still work — only a new line is refused. See
+> different product throws a `400` carrying the error code
+> `CART_LINE_LIMIT_REACHED` on `BrainerceError.details.code`, with the limit on
+> `BrainerceError.details.details.maxLines`. Branch on the code and keep any existing match on
+> the (unchanged) message text as a fallback. Quantity changes on an already-full
+> cart still work — only a new line is refused. See
 > [Cart (Unified for All Users)](#cart-unified-for-all-users).
 
 #### Update Cart Item
@@ -3641,7 +3663,7 @@ const config = await client.getPaymentConfig();
 
 // Returns:
 // {
-//   provider: string,             // 'stripe' | 'paypal' | 'grow' | 'cardcom' | any
+//   provider: string,             // 'stripe' | 'paypal' | 'grow' | 'cardcom' | 'icredit' | any
 //                                 //  installed marketplace payment app — NOT a
 //                                 //  closed union. Never switch on it exhaustively.
 //   publicKey: 'pk_live_xxx...',  // Stripe publishable key or PayPal client ID
@@ -3666,6 +3688,7 @@ const intent = await client.createPaymentIntent(checkout.id);
 //   status: 'requires_payment_method',
 //   provider: 'stripe',                 // which processor took the intent
 //   clientSdk: { renderType: 'sdk-widget', /* … */ },  // HOW to render — see below
+//   renderModeResolution: 'provider-default',  // why renderType is what it is — see "Asking for a mode"
 // }
 ```
 
@@ -3687,6 +3710,48 @@ Branch on `clientSdk?.renderType`. **Never** branch on "does `clientSdk` exist":
 every provider returns one, sandbox included. And never hard-code by provider name.
 Only `provider === 'stripe'` has a `clientSdk.initConfig.publishableKey`.
 
+#### Asking for a mode (`preferredRenderType`)
+
+Some providers can present their payment surface more than one way. Each
+`getPaymentProviders()` entry carries `clientSdk.displayModes`, every mode the
+provider can serve, beside `clientSdk.renderType`, its default. Pass
+`preferredRenderType: 'iframe' | 'redirect'` and the platform returns that mode
+when `displayModes` lists it, and the provider's default otherwise. Asking is
+never an error. The intent's `renderModeResolution` tells you which happened:
+`'preferred'`, `'fallback'` (you asked for a mode the provider does not declare),
+or `'provider-default'` (you did not ask, or the intent is a sandbox one).
+
+An iframe intent returns the shopper **inside the frame**, to a same-origin page
+that posts `brainerce:payment-complete` to the parent; a redirect intent returns
+them straight to your confirmation page. So predict the mode **before** the call
+and pass the matching `successUrl`. `resolveRenderType()` is the platform's own
+rule, exported so the two never disagree:
+
+```typescript
+import { resolveRenderType } from 'brainerce';
+
+const { defaultProvider } = await client.getPaymentProviders();
+const expected = resolveRenderType(defaultProvider?.clientSdk, 'iframe');
+const successUrl =
+  expected === 'iframe'
+    ? `${origin}/payment-complete?checkout_id=${checkout.id}`
+    : `${origin}/order-confirmation?checkout_id=${checkout.id}`;
+
+const intent = await client.createPaymentIntent(checkout.id, {
+  preferredRenderType: 'iframe',
+  successUrl,
+});
+// Still branch on intent.clientSdk?.renderType — never on 'iframe'.
+```
+
+Omit the option to take the provider's default, which is exactly what every
+storefront did before it existed. There is no merchant-dashboard setting for
+this: the storefront knows whether it has a frame to render into, the merchant
+does not. Only ask for `'iframe'` when you do, and when the provider's iframe has
+been verified on a real checkout. Any other value is rejected with `400`;
+`'sdk-widget'`, `'embedded-fields'` and `'sandbox'` are integration mechanisms,
+not presentation preferences.
+
 #### Confirm an SDK / redirect payment
 
 ```typescript
@@ -3728,6 +3793,13 @@ Do **not** call it on your `cancelUrl`. The buyer abandoned; just let them retry
 > `getPaymentProviders()` and `waitForOrder()` are **sales-channel mode only**;
 > they throw `BrainerceError` 400 on a `storeId` or `apiKey` client.
 
+> **`createPaymentIntent()` can throw `BrainerceError` 503 with
+> `err.details.code === 'PAYMENTS_PAUSED'`.** The platform pauses a store's payments
+> while its ownership is being transferred, until the new owner connects a payment
+> provider, which can take days. Show `err.message` ("Payments are temporarily
+> unavailable for this store") at the payment step, keep the cart and checkout, and
+> do not retry in a loop: nothing the storefront does lifts it.
+
 **Routing to a specific provider (`providerId`).** With `getPaymentProviders()` you
 render additive **express buttons** (e.g. PayPal as a `WALLET`) alongside the primary
 card form. When the buyer taps one, pass that provider's `id` so the charge routes to
@@ -3747,6 +3819,9 @@ Omit `providerId` to settle through the primary card processor (`defaultProvider
 The platform scopes it to the store, so only that store's own installed providers are
 selectable.
 
+The full options object is `{ providerId?, successUrl?, cancelUrl?, saveCard?,
+preferredRenderType? }`.
+
 #### Confirm Payment with Stripe.js
 
 Use the client secret with Stripe.js to collect payment:
@@ -8397,6 +8472,7 @@ const handleCheckout = async () => {
 | `Product not found`            | Unknown product ID, or a valid one that is `draft`/`archived`, or not published to this sales channel. The 404 is identical for all three, so it cannot be used to probe another channel's catalogue. |
 | `Insufficient inventory`       | Not enough stock                   |
 | `Invalid quantity`             | Quantity < 1 or > available        |
+| `Payments are temporarily unavailable for this store` | `createPaymentIntent()` returned 503 `PAYMENTS_PAUSED`: the store is mid ownership transfer and stays paused until the new owner connects a payment provider. Show the message, keep the cart, do not retry in a loop. |
 
 ### Custom Hook for SDK Operations (Optional)
 

package/dist/index.d.mts

@@ -5030,9 +5030,38 @@ interface PublishProductResponse {
  * Returned by the backend in provider config and payment intents.
  * The frontend dynamically loads the SDK script and calls init/render methods.
  */
+/**
+ * Every way a provider can present its payment surface. `PaymentClientSdk.renderType`
+ * is one of these; `PaymentClientSdk.displayModes` lists the ones the provider
+ * can serve.
+ */
+type PaymentRenderType = 'sdk-widget' | 'iframe' | 'redirect' | 'sandbox' | 'embedded-fields';
+/**
+ * The render modes a storefront may ASK for via
+ * `createPaymentIntent(id, { preferredRenderType })`. Deliberately only the
+ * two presentation choices: `sdk-widget`, `embedded-fields` and `sandbox` are
+ * integration mechanisms a storefront cannot substitute at will.
+ */
+type PreferredRenderType = 'redirect' | 'iframe';
+/**
+ * Why the `clientSdk.renderType` on a `PaymentIntent` is what it is.
+ *
+ * - `'preferred'`        — you asked for a mode and the provider supports it.
+ * - `'fallback'`         — you asked for a mode the provider does not declare;
+ *                          you got the provider's default instead.
+ * - `'provider-default'` — you did not ask (or the intent is a sandbox one).
+ */
+type RenderModeResolution = 'preferred' | 'fallback' | 'provider-default';
 interface PaymentClientSdk {
     /** How the payment UI is rendered: 'sdk-widget' (JS SDK), 'iframe', 'redirect', 'sandbox' (test orders), or 'embedded-fields' (PCI-compliant provider-hosted fields embedded in merchant DOM, e.g. Cardcom OpenFields, Stripe Elements) */
-    renderType: 'sdk-widget' | 'iframe' | 'redirect' | 'sandbox' | 'embedded-fields';
+    renderType: PaymentRenderType;
+    /**
+     * Every render mode this provider can serve. `renderType` is the default;
+     * `preferredRenderType` on `createPaymentIntent` is honoured only if it is in
+     * this list. Absent on legacy manifests — treat as `[renderType]`, which is
+     * exactly what `resolveRenderType()` does.
+     */
+    displayModes?: PaymentRenderType[];
     /** URL of the main SDK script to load */
     scriptUrl?: string;
     /** Name of the global variable set by the SDK script (e.g., 'growPayment') */
@@ -5202,6 +5231,14 @@ interface PaymentIntent {
     provider?: string;
     /** Runtime client SDK overrides (merged with provider manifest config) */
     clientSdk?: PaymentClientSdk;
+    /**
+     * Why the returned `clientSdk.renderType` is what it is — see
+     * `RenderModeResolution`. Lets a storefront that asked for `iframe` and got
+     * `redirect` tell "the provider does not support iframe" (`'fallback'`) from
+     * "I never asked" (`'provider-default'`). Absent from older backends; always
+     * branch on the `renderType` you got back, never on what you asked for.
+     */
+    renderModeResolution?: RenderModeResolution;
 }
 /**
  * The stored payment-record vocabulary. **UPPERCASE.**
@@ -8182,8 +8219,20 @@ interface TrackEventPayload {
     /** Active dwell time in ms. Only meaningful for `eventType: 'engagement'`. Max 1 800 000 (30 min). */
     engagedMs?: number;
 }
+/**
+ * The JSON body of any non-2xx response. `BrainerceError.details` holds a value
+ * of this shape (the raw parsed body), so from a caught SDK error the code is
+ * at `err.details.code`, one level deeper than it sits on the wire.
+ */
 interface BrainerceApiError {
     statusCode: number;
+    /**
+     * The stable, machine-readable error code — switch on THIS, never on
+     * `message`, whose wording can change at any time. Always present: the API
+     * derives a generic code from the status when a route supplies none.
+     * The full list is at https://brainerce.com/docs/api/errors.
+     */
+    code?: string;
     message: string;
     error?: string;
     details?: unknown;
@@ -12145,6 +12194,25 @@ declare class BrainerceClient {
          * subscription features.
          */
         saveCard?: boolean;
+        /**
+         * How you would like the provider's payment surface presented. The
+         * platform honours it when the provider supports that mode (it is
+         * listed in the provider's `clientSdk.displayModes`), and otherwise
+         * falls back to the provider's default — so always branch on the
+         * `clientSdk.renderType` you get BACK, never on what you asked for.
+         * The response's `renderModeResolution` says which happened. Omit to
+         * take the provider's default.
+         *
+         * To pick the matching `successUrl` up front, call
+         * `resolveRenderType(provider.clientSdk, preferred)` on the entry from
+         * `getPaymentProviders()` — it applies the same rule the platform does.
+         * An iframe intent returns the shopper INSIDE the frame, so its
+         * `successUrl` must be a same-origin page that posts to the parent; a
+         * redirect intent can return straight to the confirmation page.
+         *
+         * A value outside `'redirect' | 'iframe'` is rejected with 400.
+         */
+        preferredRenderType?: PreferredRenderType;
     }): Promise<PaymentIntent>;
     /**
      * Get payment status for a checkout.
@@ -14303,7 +14371,7 @@ declare class BrainerceError extends Error {
     constructor(message: string, statusCode: number, details?: unknown);
 }
 
-declare const SDK_VERSION = "2.8.0";
+declare const SDK_VERSION = "2.9.0";
 
 /**
  * Verify a webhook signature from Brainerce
@@ -14406,6 +14474,40 @@ declare function isAllowedPaymentUrl(url: string, options?: PaymentUrlOptions):
  */
 declare function safePaymentRedirect(url: string, options?: PaymentUrlOptions): void;
 
+/**
+ * Predict the `clientSdk.renderType` the platform will return for a given
+ * provider and preference.
+ *
+ * Rules (identical to the platform's):
+ *  1. No preference → the provider default.
+ *  2. Preference declared in `displayModes` → the preference.
+ *  3. Preference NOT declared → the provider default (the platform reports
+ *     `renderModeResolution: 'fallback'` on the intent).
+ *  4. `displayModes` absent (legacy manifest) → treated as `[renderType]`.
+ *
+ * @param sdk - The `clientSdk` of an entry from `getPaymentProviders()`
+ *              (`defaultProvider.clientSdk` or `providers[i].clientSdk`).
+ * @param preferred - The mode you intend to pass as `preferredRenderType`.
+ * @returns The mode the intent will come back with. `'redirect'` when there is
+ *          no provider at all, so a storefront can always pick a return URL.
+ *
+ * @example
+ * ```typescript
+ * const { defaultProvider } = await client.getPaymentProviders();
+ * const expected = resolveRenderType(defaultProvider?.clientSdk, 'iframe');
+ * const successUrl = expected === 'iframe'
+ *   ? `${origin}/payment-complete?checkout_id=${checkoutId}`
+ *   : `${origin}/order-confirmation?checkout_id=${checkoutId}`;
+ * const intent = await client.createPaymentIntent(checkoutId, {
+ *   preferredRenderType: 'iframe',
+ *   successUrl,
+ * });
+ * // Still branch on what came BACK — never on what you asked for.
+ * if (intent.clientSdk?.renderType === 'iframe') { ... }
+ * ```
+ */
+declare function resolveRenderType(sdk: Pick<PaymentClientSdk, 'renderType' | 'displayModes'> | null | undefined, preferred?: PreferredRenderType): PaymentRenderType;
+
 interface FormatProductPriceOptions {
     /**
      * BCP-47 locale for `Intl.NumberFormat`. Controls number grouping and
@@ -14804,4 +14906,4 @@ interface CategorySitemapOptions {
  */
 declare function getCategorySitemapEntries(client: BrainerceClient, opts: CategorySitemapOptions): Promise<SitemapEntry[]>;
 
-export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AiTranslateBulkInput, type AiTranslateBulkResult, type AiTranslateSingleInput, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AssignTaxClassDto, type AttachModifierGroupInput, type Attribute, type AttributeDisplayType, type AttributeOption, type AttributeSource, type AutoRegionResponse, type AvailabilityClock, 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 CartBundleOfferOfferedProduct, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartItemUnavailableReason, 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 CheckoutTender, 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 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 CreateRegionDto, type CreateReturnLabelDto as CreateReturnLabelInput, type CreateReturnLabelResponse, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateStockAlertInput, type CreateTagDto as CreateTagInput, type CreateTaxClassDto, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type CustomizationFieldOption, type DateAvailabilityConstraints, type DateAvailabilitySurface, type DateFieldParseResult, type DeleteProductResponse, type DeliveryType, 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 GiftCardAdmin, type GiftCardAdminDetail, type GiftCardBalance, type GiftCardLiability, type GiftCardTransaction, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type I18nSettings, type IdempotentRequestOptions, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type IssueGiftCardAdminDto, type IssuedGiftCardAdmin, type JsonLdOptions, type ListModifierGroupsParams, type ListNewsletterBenefitGrantsParams, type LocalCart, type LocalCartItem, type LocaleTranslation, type LockedVariant, type LoyaltyBadge, type LoyaltyMembershipPlan, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyRewardRecommendation, 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 NestedModifierSelection, type NewsletterBenefitDiscountKind, type NewsletterBenefitGrant, type NewsletterBenefitGrantState, type NewsletterBenefitSettings, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthErrorCode, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomFieldDefinition, type OrderCustomFieldValues, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaidMembershipInfo, type ParsedDateFieldValue, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentRecordStatus, 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 ProductInventoryResponse, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductReviewImage, type ProductReviewImageAdmin, type ProductSitemapOptions, type ProductStatus, type ProductSuggestion, type ProductUnavailableError, type ProductVariant, type PublicMetafieldDefinition, type PublicNewsletterBenefitOffer, type PublicRegion, type PublicRegionDetail, type PublicRegionPaymentProvider, type PublicTaxClass, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type Region, type RegionPaymentProvider, type RegisterCustomerDto, type ReissuedGiftCardAdmin, type RelativeDateBounds, type ResendNewsletterBenefitResult, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type ReturnLabelParcel, type ReviewPhotoUpload, type ReviewStatus, type RichTextContent, SDK_VERSION, type SavedPaymentMethodSummary, 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 SetTranslationFields, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAlertResponse, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreCapabilities, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type StoreTracking, type StorefrontSavedPaymentMethod, type SubmitProductReviewInput, type SubscribeMarketingInput, type SubscribeMarketingResponse, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxClass, type TaxEstimateResponse, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type TrackingEventItem, type TrackingEventName, type TrackingEventPayload, type TranslatableEntityType, type TranslationStatusEntry, type TranslationsMap, 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 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 UpdateNewsletterBenefitSettingsInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateRegionDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxClassDto, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsellSettings, 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, resolveRelativeBounds, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };
+export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AiTranslateBulkInput, type AiTranslateBulkResult, type AiTranslateSingleInput, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AssignTaxClassDto, type AttachModifierGroupInput, type Attribute, type AttributeDisplayType, type AttributeOption, type AttributeSource, type AutoRegionResponse, type AvailabilityClock, 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 CartBundleOfferOfferedProduct, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartItemUnavailableReason, 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 CheckoutTender, 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 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 CreateRegionDto, type CreateReturnLabelDto as CreateReturnLabelInput, type CreateReturnLabelResponse, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateStockAlertInput, type CreateTagDto as CreateTagInput, type CreateTaxClassDto, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type CustomizationFieldOption, type DateAvailabilityConstraints, type DateAvailabilitySurface, type DateFieldParseResult, type DeleteProductResponse, type DeliveryType, 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 GiftCardAdmin, type GiftCardAdminDetail, type GiftCardBalance, type GiftCardLiability, type GiftCardTransaction, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type I18nSettings, type IdempotentRequestOptions, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type IssueGiftCardAdminDto, type IssuedGiftCardAdmin, type JsonLdOptions, type ListModifierGroupsParams, type ListNewsletterBenefitGrantsParams, type LocalCart, type LocalCartItem, type LocaleTranslation, type LockedVariant, type LoyaltyBadge, type LoyaltyMembershipPlan, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyRewardRecommendation, 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 NestedModifierSelection, type NewsletterBenefitDiscountKind, type NewsletterBenefitGrant, type NewsletterBenefitGrantState, type NewsletterBenefitSettings, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthErrorCode, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomFieldDefinition, type OrderCustomFieldValues, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaidMembershipInfo, type ParsedDateFieldValue, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentRecordStatus, type PaymentRenderType, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreferredRenderType, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type PriceDriftError, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductInventoryResponse, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductReviewImage, type ProductReviewImageAdmin, type ProductSitemapOptions, type ProductStatus, type ProductSuggestion, type ProductUnavailableError, type ProductVariant, type PublicMetafieldDefinition, type PublicNewsletterBenefitOffer, type PublicRegion, type PublicRegionDetail, type PublicRegionPaymentProvider, type PublicTaxClass, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type Region, type RegionPaymentProvider, type RegisterCustomerDto, type ReissuedGiftCardAdmin, type RelativeDateBounds, type RenderModeResolution, type ResendNewsletterBenefitResult, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type ReturnLabelParcel, type ReviewPhotoUpload, type ReviewStatus, type RichTextContent, SDK_VERSION, type SavedPaymentMethodSummary, 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 SetTranslationFields, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAlertResponse, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreCapabilities, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type StoreTracking, type StorefrontSavedPaymentMethod, type SubmitProductReviewInput, type SubscribeMarketingInput, type SubscribeMarketingResponse, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxClass, type TaxEstimateResponse, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type TrackingEventItem, type TrackingEventName, type TrackingEventPayload, type TranslatableEntityType, type TranslationStatusEntry, type TranslationsMap, 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 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 UpdateNewsletterBenefitSettingsInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateRegionDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxClassDto, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsellSettings, 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, resolveRelativeBounds, resolveRenderType, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };

package/dist/index.d.ts

@@ -5030,9 +5030,38 @@ interface PublishProductResponse {
  * Returned by the backend in provider config and payment intents.
  * The frontend dynamically loads the SDK script and calls init/render methods.
  */
+/**
+ * Every way a provider can present its payment surface. `PaymentClientSdk.renderType`
+ * is one of these; `PaymentClientSdk.displayModes` lists the ones the provider
+ * can serve.
+ */
+type PaymentRenderType = 'sdk-widget' | 'iframe' | 'redirect' | 'sandbox' | 'embedded-fields';
+/**
+ * The render modes a storefront may ASK for via
+ * `createPaymentIntent(id, { preferredRenderType })`. Deliberately only the
+ * two presentation choices: `sdk-widget`, `embedded-fields` and `sandbox` are
+ * integration mechanisms a storefront cannot substitute at will.
+ */
+type PreferredRenderType = 'redirect' | 'iframe';
+/**
+ * Why the `clientSdk.renderType` on a `PaymentIntent` is what it is.
+ *
+ * - `'preferred'`        — you asked for a mode and the provider supports it.
+ * - `'fallback'`         — you asked for a mode the provider does not declare;
+ *                          you got the provider's default instead.
+ * - `'provider-default'` — you did not ask (or the intent is a sandbox one).
+ */
+type RenderModeResolution = 'preferred' | 'fallback' | 'provider-default';
 interface PaymentClientSdk {
     /** How the payment UI is rendered: 'sdk-widget' (JS SDK), 'iframe', 'redirect', 'sandbox' (test orders), or 'embedded-fields' (PCI-compliant provider-hosted fields embedded in merchant DOM, e.g. Cardcom OpenFields, Stripe Elements) */
-    renderType: 'sdk-widget' | 'iframe' | 'redirect' | 'sandbox' | 'embedded-fields';
+    renderType: PaymentRenderType;
+    /**
+     * Every render mode this provider can serve. `renderType` is the default;
+     * `preferredRenderType` on `createPaymentIntent` is honoured only if it is in
+     * this list. Absent on legacy manifests — treat as `[renderType]`, which is
+     * exactly what `resolveRenderType()` does.
+     */
+    displayModes?: PaymentRenderType[];
     /** URL of the main SDK script to load */
     scriptUrl?: string;
     /** Name of the global variable set by the SDK script (e.g., 'growPayment') */
@@ -5202,6 +5231,14 @@ interface PaymentIntent {
     provider?: string;
     /** Runtime client SDK overrides (merged with provider manifest config) */
     clientSdk?: PaymentClientSdk;
+    /**
+     * Why the returned `clientSdk.renderType` is what it is — see
+     * `RenderModeResolution`. Lets a storefront that asked for `iframe` and got
+     * `redirect` tell "the provider does not support iframe" (`'fallback'`) from
+     * "I never asked" (`'provider-default'`). Absent from older backends; always
+     * branch on the `renderType` you got back, never on what you asked for.
+     */
+    renderModeResolution?: RenderModeResolution;
 }
 /**
  * The stored payment-record vocabulary. **UPPERCASE.**
@@ -8182,8 +8219,20 @@ interface TrackEventPayload {
     /** Active dwell time in ms. Only meaningful for `eventType: 'engagement'`. Max 1 800 000 (30 min). */
     engagedMs?: number;
 }
+/**
+ * The JSON body of any non-2xx response. `BrainerceError.details` holds a value
+ * of this shape (the raw parsed body), so from a caught SDK error the code is
+ * at `err.details.code`, one level deeper than it sits on the wire.
+ */
 interface BrainerceApiError {
     statusCode: number;
+    /**
+     * The stable, machine-readable error code — switch on THIS, never on
+     * `message`, whose wording can change at any time. Always present: the API
+     * derives a generic code from the status when a route supplies none.
+     * The full list is at https://brainerce.com/docs/api/errors.
+     */
+    code?: string;
     message: string;
     error?: string;
     details?: unknown;
@@ -12145,6 +12194,25 @@ declare class BrainerceClient {
          * subscription features.
          */
         saveCard?: boolean;
+        /**
+         * How you would like the provider's payment surface presented. The
+         * platform honours it when the provider supports that mode (it is
+         * listed in the provider's `clientSdk.displayModes`), and otherwise
+         * falls back to the provider's default — so always branch on the
+         * `clientSdk.renderType` you get BACK, never on what you asked for.
+         * The response's `renderModeResolution` says which happened. Omit to
+         * take the provider's default.
+         *
+         * To pick the matching `successUrl` up front, call
+         * `resolveRenderType(provider.clientSdk, preferred)` on the entry from
+         * `getPaymentProviders()` — it applies the same rule the platform does.
+         * An iframe intent returns the shopper INSIDE the frame, so its
+         * `successUrl` must be a same-origin page that posts to the parent; a
+         * redirect intent can return straight to the confirmation page.
+         *
+         * A value outside `'redirect' | 'iframe'` is rejected with 400.
+         */
+        preferredRenderType?: PreferredRenderType;
     }): Promise<PaymentIntent>;
     /**
      * Get payment status for a checkout.
@@ -14303,7 +14371,7 @@ declare class BrainerceError extends Error {
     constructor(message: string, statusCode: number, details?: unknown);
 }
 
-declare const SDK_VERSION = "2.8.0";
+declare const SDK_VERSION = "2.9.0";
 
 /**
  * Verify a webhook signature from Brainerce
@@ -14406,6 +14474,40 @@ declare function isAllowedPaymentUrl(url: string, options?: PaymentUrlOptions):
  */
 declare function safePaymentRedirect(url: string, options?: PaymentUrlOptions): void;
 
+/**
+ * Predict the `clientSdk.renderType` the platform will return for a given
+ * provider and preference.
+ *
+ * Rules (identical to the platform's):
+ *  1. No preference → the provider default.
+ *  2. Preference declared in `displayModes` → the preference.
+ *  3. Preference NOT declared → the provider default (the platform reports
+ *     `renderModeResolution: 'fallback'` on the intent).
+ *  4. `displayModes` absent (legacy manifest) → treated as `[renderType]`.
+ *
+ * @param sdk - The `clientSdk` of an entry from `getPaymentProviders()`
+ *              (`defaultProvider.clientSdk` or `providers[i].clientSdk`).
+ * @param preferred - The mode you intend to pass as `preferredRenderType`.
+ * @returns The mode the intent will come back with. `'redirect'` when there is
+ *          no provider at all, so a storefront can always pick a return URL.
+ *
+ * @example
+ * ```typescript
+ * const { defaultProvider } = await client.getPaymentProviders();
+ * const expected = resolveRenderType(defaultProvider?.clientSdk, 'iframe');
+ * const successUrl = expected === 'iframe'
+ *   ? `${origin}/payment-complete?checkout_id=${checkoutId}`
+ *   : `${origin}/order-confirmation?checkout_id=${checkoutId}`;
+ * const intent = await client.createPaymentIntent(checkoutId, {
+ *   preferredRenderType: 'iframe',
+ *   successUrl,
+ * });
+ * // Still branch on what came BACK — never on what you asked for.
+ * if (intent.clientSdk?.renderType === 'iframe') { ... }
+ * ```
+ */
+declare function resolveRenderType(sdk: Pick<PaymentClientSdk, 'renderType' | 'displayModes'> | null | undefined, preferred?: PreferredRenderType): PaymentRenderType;
+
 interface FormatProductPriceOptions {
     /**
      * BCP-47 locale for `Intl.NumberFormat`. Controls number grouping and
@@ -14804,4 +14906,4 @@ interface CategorySitemapOptions {
  */
 declare function getCategorySitemapEntries(client: BrainerceClient, opts: CategorySitemapOptions): Promise<SitemapEntry[]>;
 
-export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AiTranslateBulkInput, type AiTranslateBulkResult, type AiTranslateSingleInput, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AssignTaxClassDto, type AttachModifierGroupInput, type Attribute, type AttributeDisplayType, type AttributeOption, type AttributeSource, type AutoRegionResponse, type AvailabilityClock, 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 CartBundleOfferOfferedProduct, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartItemUnavailableReason, 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 CheckoutTender, 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 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 CreateRegionDto, type CreateReturnLabelDto as CreateReturnLabelInput, type CreateReturnLabelResponse, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateStockAlertInput, type CreateTagDto as CreateTagInput, type CreateTaxClassDto, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type CustomizationFieldOption, type DateAvailabilityConstraints, type DateAvailabilitySurface, type DateFieldParseResult, type DeleteProductResponse, type DeliveryType, 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 GiftCardAdmin, type GiftCardAdminDetail, type GiftCardBalance, type GiftCardLiability, type GiftCardTransaction, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type I18nSettings, type IdempotentRequestOptions, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type IssueGiftCardAdminDto, type IssuedGiftCardAdmin, type JsonLdOptions, type ListModifierGroupsParams, type ListNewsletterBenefitGrantsParams, type LocalCart, type LocalCartItem, type LocaleTranslation, type LockedVariant, type LoyaltyBadge, type LoyaltyMembershipPlan, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyRewardRecommendation, 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 NestedModifierSelection, type NewsletterBenefitDiscountKind, type NewsletterBenefitGrant, type NewsletterBenefitGrantState, type NewsletterBenefitSettings, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthErrorCode, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomFieldDefinition, type OrderCustomFieldValues, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaidMembershipInfo, type ParsedDateFieldValue, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentRecordStatus, 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 ProductInventoryResponse, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductReviewImage, type ProductReviewImageAdmin, type ProductSitemapOptions, type ProductStatus, type ProductSuggestion, type ProductUnavailableError, type ProductVariant, type PublicMetafieldDefinition, type PublicNewsletterBenefitOffer, type PublicRegion, type PublicRegionDetail, type PublicRegionPaymentProvider, type PublicTaxClass, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type Region, type RegionPaymentProvider, type RegisterCustomerDto, type ReissuedGiftCardAdmin, type RelativeDateBounds, type ResendNewsletterBenefitResult, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type ReturnLabelParcel, type ReviewPhotoUpload, type ReviewStatus, type RichTextContent, SDK_VERSION, type SavedPaymentMethodSummary, 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 SetTranslationFields, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAlertResponse, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreCapabilities, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type StoreTracking, type StorefrontSavedPaymentMethod, type SubmitProductReviewInput, type SubscribeMarketingInput, type SubscribeMarketingResponse, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxClass, type TaxEstimateResponse, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type TrackingEventItem, type TrackingEventName, type TrackingEventPayload, type TranslatableEntityType, type TranslationStatusEntry, type TranslationsMap, 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 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 UpdateNewsletterBenefitSettingsInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateRegionDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxClassDto, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsellSettings, 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, resolveRelativeBounds, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };
+export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AiTranslateBulkInput, type AiTranslateBulkResult, type AiTranslateSingleInput, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AssignTaxClassDto, type AttachModifierGroupInput, type Attribute, type AttributeDisplayType, type AttributeOption, type AttributeSource, type AutoRegionResponse, type AvailabilityClock, 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 CartBundleOfferOfferedProduct, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartItemUnavailableReason, 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 CheckoutTender, 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 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 CreateRegionDto, type CreateReturnLabelDto as CreateReturnLabelInput, type CreateReturnLabelResponse, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateStockAlertInput, type CreateTagDto as CreateTagInput, type CreateTaxClassDto, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type CustomizationFieldOption, type DateAvailabilityConstraints, type DateAvailabilitySurface, type DateFieldParseResult, type DeleteProductResponse, type DeliveryType, 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 GiftCardAdmin, type GiftCardAdminDetail, type GiftCardBalance, type GiftCardLiability, type GiftCardTransaction, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type I18nSettings, type IdempotentRequestOptions, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type IssueGiftCardAdminDto, type IssuedGiftCardAdmin, type JsonLdOptions, type ListModifierGroupsParams, type ListNewsletterBenefitGrantsParams, type LocalCart, type LocalCartItem, type LocaleTranslation, type LockedVariant, type LoyaltyBadge, type LoyaltyMembershipPlan, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyRewardRecommendation, 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 NestedModifierSelection, type NewsletterBenefitDiscountKind, type NewsletterBenefitGrant, type NewsletterBenefitGrantState, type NewsletterBenefitSettings, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthErrorCode, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomFieldDefinition, type OrderCustomFieldValues, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaidMembershipInfo, type ParsedDateFieldValue, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentRecordStatus, type PaymentRenderType, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreferredRenderType, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type PriceDriftError, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductInventoryResponse, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductReviewImage, type ProductReviewImageAdmin, type ProductSitemapOptions, type ProductStatus, type ProductSuggestion, type ProductUnavailableError, type ProductVariant, type PublicMetafieldDefinition, type PublicNewsletterBenefitOffer, type PublicRegion, type PublicRegionDetail, type PublicRegionPaymentProvider, type PublicTaxClass, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type Region, type RegionPaymentProvider, type RegisterCustomerDto, type ReissuedGiftCardAdmin, type RelativeDateBounds, type RenderModeResolution, type ResendNewsletterBenefitResult, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type ReturnLabelParcel, type ReviewPhotoUpload, type ReviewStatus, type RichTextContent, SDK_VERSION, type SavedPaymentMethodSummary, 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 SetTranslationFields, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAlertResponse, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreCapabilities, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type StoreTracking, type StorefrontSavedPaymentMethod, type SubmitProductReviewInput, type SubscribeMarketingInput, type SubscribeMarketingResponse, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxClass, type TaxEstimateResponse, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type TrackingEventItem, type TrackingEventName, type TrackingEventPayload, type TranslatableEntityType, type TranslationStatusEntry, type TranslationsMap, 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 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 UpdateNewsletterBenefitSettingsInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateRegionDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxClassDto, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsellSettings, 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, resolveRelativeBounds, resolveRenderType, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };

package/dist/index.js

@@ -79,6 +79,7 @@ __export(index_exports, {
   parseDateFieldValue: () => parseDateFieldValue,
   parseWebhookEvent: () => parseWebhookEvent,
   resolveRelativeBounds: () => resolveRelativeBounds,
+  resolveRenderType: () => resolveRenderType,
   resolveStoreLocalParts: () => resolveStoreLocalParts,
   safePaymentRedirect: () => safePaymentRedirect,
   stripHtml: () => stripHtml2,
@@ -204,7 +205,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.8.0";
+var SDK_VERSION = "2.9.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -11378,6 +11379,13 @@ function safePaymentRedirect(url, options) {
   }
 }
 
+// src/render-mode.ts
+function resolveRenderType(sdk, preferred) {
+  if (!sdk) return "redirect";
+  const declared = sdk.displayModes?.length ? sdk.displayModes : [sdk.renderType];
+  return preferred && declared.includes(preferred) ? preferred : sdk.renderType;
+}
+
 // src/format-price.ts
 var DEFAULT_LOCALE = "en";
 function formatProductPrice(product, options = {}) {
@@ -12420,6 +12428,7 @@ function isCouponApplicableToProduct(coupon, productId) {
   parseDateFieldValue,
   parseWebhookEvent,
   resolveRelativeBounds,
+  resolveRenderType,
   resolveStoreLocalParts,
   safePaymentRedirect,
   stripHtml,

package/dist/index.mjs

@@ -115,7 +115,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.8.0";
+var SDK_VERSION = "2.9.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -11289,6 +11289,13 @@ function safePaymentRedirect(url, options) {
   }
 }
 
+// src/render-mode.ts
+function resolveRenderType(sdk, preferred) {
+  if (!sdk) return "redirect";
+  const declared = sdk.displayModes?.length ? sdk.displayModes : [sdk.renderType];
+  return preferred && declared.includes(preferred) ? preferred : sdk.renderType;
+}
+
 // src/format-price.ts
 var DEFAULT_LOCALE = "en";
 function formatProductPrice(product, options = {}) {
@@ -12330,6 +12337,7 @@ export {
   parseDateFieldValue,
   parseWebhookEvent,
   resolveRelativeBounds,
+  resolveRenderType,
   resolveStoreLocalParts,
   safePaymentRedirect,
   stripHtml2 as stripHtml,

package/package.json

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