brainerce 1.22.0 → 1.23.11

package/dist/index.mjs

@@ -197,23 +197,31 @@ var BrainerceClient = class {
     // These methods store cart data in localStorage - NO API calls!
     // Use for guest users in vibe-coded sites
     this.LOCAL_CART_KEY = "brainerce_cart";
-    if (!options.apiKey && !options.storeId && !options.connectionId) {
-      throw new Error("BrainerceClient: either connectionId, apiKey, or storeId is required");
+    const resolvedSalesChannelId = options.salesChannelId ?? options.connectionId;
+    if (!options.apiKey && !options.storeId && !resolvedSalesChannelId) {
+      throw new Error(
+        "BrainerceClient: either salesChannelId, apiKey, or storeId is required"
+      );
     }
     if (options.apiKey && !options.apiKey.startsWith("brainerce_")) {
       console.warn('BrainerceClient: apiKey should start with "brainerce_"');
     }
-    if (options.connectionId && !options.connectionId.startsWith("vc_")) {
-      console.warn('BrainerceClient: connectionId should start with "vc_"');
+    if (resolvedSalesChannelId && !resolvedSalesChannelId.startsWith("vc_")) {
+      console.warn('BrainerceClient: salesChannelId should start with "vc_"');
+    }
+    if (!options.salesChannelId && options.connectionId) {
+      console.warn(
+        "BrainerceClient: `connectionId` is deprecated \u2014 use `salesChannelId` instead. `connectionId` will be removed in SDK 2.0."
+      );
     }
     if (options.apiKey && typeof window !== "undefined") {
       console.warn(
-        "BrainerceClient: WARNING - API key detected in browser environment. This is a security risk! Use connectionId or storeId for frontend applications."
+        "BrainerceClient: WARNING - API key detected in browser environment. This is a security risk! Use salesChannelId or storeId for frontend applications."
       );
     }
     this.apiKey = options.apiKey;
     this.storeId = options.storeId;
-    this.connectionId = options.connectionId;
+    this.connectionId = resolvedSalesChannelId;
     let resolvedBase = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
     if (resolvedBase.startsWith("/") && typeof window !== "undefined" && window.location?.origin) {
       resolvedBase = window.location.origin + resolvedBase;
@@ -300,11 +308,17 @@ var BrainerceClient = class {
   }
   // -------------------- Mode Detection --------------------
   /**
-   * Check if client is in vibe-coded mode (using connectionId)
+   * Check if client is in sales-channel mode (using salesChannelId / legacy connectionId).
    */
-  isVibeCodedMode() {
+  isSalesChannelMode() {
     return !!this.connectionId && !this.apiKey;
   }
+  /**
+   * @deprecated Use `isSalesChannelMode()` instead. Kept as a backwards-compatible alias.
+   */
+  isVibeCodedMode() {
+    return this.isSalesChannelMode();
+  }
   /**
    * Check if client is in storefront mode (using storeId)
    */
@@ -616,6 +630,18 @@ var BrainerceClient = class {
     const categories = Array.isArray(params?.categories) ? params.categories.join(",") : params?.categories;
     const brands = Array.isArray(params?.brands) ? params.brands.join(",") : params?.brands;
     const tags = Array.isArray(params?.tags) ? params.tags.join(",") : params?.tags;
+    let metafields;
+    if (params?.metafields && Object.keys(params.metafields).length > 0) {
+      const normalized = {};
+      for (const [key, raw] of Object.entries(params.metafields)) {
+        const arr = Array.isArray(raw) ? raw : [raw];
+        const strings = arr.map((v) => String(v)).filter(Boolean);
+        if (strings.length > 0) normalized[key] = strings;
+      }
+      if (Object.keys(normalized).length > 0) {
+        metafields = JSON.stringify(normalized);
+      }
+    }
     const queryParams = {
       page: params?.page,
       limit: params?.limit,
@@ -626,6 +652,7 @@ var BrainerceClient = class {
       tags,
       minPrice: params?.minPrice,
       maxPrice: params?.maxPrice,
+      metafields,
       sortBy: params?.sortBy,
       sortOrder: params?.sortOrder,
       // Admin-only params
@@ -1555,6 +1582,58 @@ var BrainerceClient = class {
   async getCustomerByEmail(email) {
     return this.request("GET", "/api/v1/customers/by-email", void 0, { email });
   }
+  /**
+   * List a customer's saved payment methods (vaulted cards).
+   *
+   * Returns display-only metadata — last4, brand, expiry, default flag,
+   * status. The underlying provider token is encrypted at rest and
+   * NEVER returned through this API.
+   *
+   * Apps mode requires `customers:read` and `payments:read` scopes.
+   *
+   * @param storeId - The store this customer belongs to
+   * @param customerId - The customer's ID
+   * @returns Array of saved payment methods
+   *
+   * @example
+   * ```typescript
+   * const methods = await client.listSavedPaymentMethods(storeId, customerId);
+   * methods.forEach((m) => {
+   *   console.log(`${m.brand} ending in ${m.last4} (expires ${m.expMonth}/${m.expYear})`);
+   * });
+   * ```
+   */
+  async listSavedPaymentMethods(storeId, customerId) {
+    return this.request(
+      "GET",
+      `/api/stores/${storeId}/customers/${customerId}/payment-methods`
+    );
+  }
+  /**
+   * Remove a customer's saved payment method.
+   *
+   * Hard-deletes the row. The provider may still hold the underlying
+   * token internally — we don't issue a delete-at-provider call because
+   * not every provider supports it. From the platform's perspective the
+   * token is gone; subsequent charges will fail.
+   *
+   * Apps mode requires `customers:write` scope.
+   *
+   * @param storeId - The store this customer belongs to
+   * @param customerId - The customer's ID
+   * @param paymentMethodId - The saved payment method ID to remove
+   *
+   * @example
+   * ```typescript
+   * await client.removeSavedPaymentMethod(storeId, customerId, methodId);
+   * ```
+   */
+  async removeSavedPaymentMethod(storeId, customerId, paymentMethodId) {
+    return this.request(
+      "DELETE",
+      `/api/stores/${storeId}/customers/${customerId}/payment-methods/${paymentMethodId}`
+    );
+  }
   /**
    * Login an existing customer (returns JWT token)
    * Works in vibe-coded, storefront, and admin mode
@@ -2407,6 +2486,82 @@ var BrainerceClient = class {
       "cart"
     );
   }
+  /**
+   * Recalculate cart totals against current product/variant prices and
+   * discount rules. Idempotent — does NOT mutate the per-item snapshot
+   * `unitPrice`. The returned cart's `hasPriceChanges` / `hasUnavailableItems`
+   * flags reflect the live state. Call this on cart load if you want to
+   * surface drift to the customer before they reach checkout.
+   *
+   * @example
+   * ```typescript
+   * const cart = await client.recalculateCart('cart_123');
+   * if (cart.hasPriceChanges) {
+   *   // show "prices have changed" banner
+   * }
+   * ```
+   */
+  async recalculateCart(cartId) {
+    if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      return this.withGuards(this.localCartToCart(this.getLocalCart()), "cart");
+    }
+    if (this.isVibeCodedMode()) {
+      return this.withGuards(
+        this.vibeCodedRequest("POST", `/cart/${cartId}/recalculate`),
+        "cart"
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.withGuards(
+        this.storefrontRequest("POST", `/cart/${cartId}/recalculate`),
+        "cart"
+      );
+    }
+    return this.withGuards(
+      this.adminRequest("POST", `/api/v1/cart/${cartId}/recalculate`),
+      "cart"
+    );
+  }
+  /**
+   * Refresh per-item `unitPrice` snapshots to current live prices. Use this
+   * after the customer accepts new prices in the drift-reconfirm flow. The
+   * subsequent `createCheckout` call will then succeed (it would otherwise
+   * throw `PRICE_DRIFT`).
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await client.createCheckout(cartId);
+   * } catch (err) {
+   *   if (err.code === 'PRICE_DRIFT') {
+   *     // ask user to confirm new prices, then:
+   *     await client.refreshCartSnapshots(cartId);
+   *     await client.createCheckout(cartId);
+   *   }
+   * }
+   * ```
+   */
+  async refreshCartSnapshots(cartId) {
+    if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      return this.withGuards(this.localCartToCart(this.getLocalCart()), "cart");
+    }
+    if (this.isVibeCodedMode()) {
+      return this.withGuards(
+        this.vibeCodedRequest("POST", `/cart/${cartId}/refresh-snapshots`),
+        "cart"
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.withGuards(
+        this.storefrontRequest("POST", `/cart/${cartId}/refresh-snapshots`),
+        "cart"
+      );
+    }
+    return this.withGuards(
+      this.adminRequest("POST", `/api/v1/cart/${cartId}/refresh-snapshots`),
+      "cart"
+    );
+  }
   /**
    * Link a cart to the currently logged-in customer.
    * Use this after customer logs in to associate their guest cart with their account.
@@ -2647,7 +2802,8 @@ var BrainerceClient = class {
    * ```typescript
    * const { bundles } = await client.getCartBundles('cart_123');
    * bundles.forEach(b => {
-   *   console.log(`Add ${b.bundleProduct.name} and save! Was ${b.originalPrice}, now ${b.discountedPrice}`);
+   *   const names = b.offeredProducts.map(p => p.name).join(', ');
+   *   console.log(`Add ${names} and save! Was ${b.totalOriginalPrice}, now ${b.totalDiscountedPrice}`);
    * });
    * ```
    */
@@ -2710,24 +2866,31 @@ var BrainerceClient = class {
     throw new BrainerceError("removeOrderBump() requires vibe-coded or storefront mode", 400);
   }
   /**
-   * Add a bundle offer product to the cart with its discount applied.
+   * Accept an N-product bundle offer: every offered product not yet in cart
+   * is added with the bundle discount applied.
    *
    * @param cartId - Cart ID
    * @param bundleOfferId - Bundle offer ID
-   * @param variantId - Optional variant ID (required when bundle product has variants and no admin-locked variant)
+   * @param variantSelections - Optional map of `productId → variantId` for offered products with variants
    * @returns Updated cart
    *
    * @example
    * ```typescript
    * const { bundles } = await client.getCartBundles('cart_123');
-   * // Simple product or locked variant:
-   * const cart = await client.addBundleToCart('cart_123', bundles[0].id);
-   * // Product with variants (customer selects):
-   * const cart = await client.addBundleToCart('cart_123', bundles[0].id, selectedVariantId);
+   * const bundle = bundles[0];
+   * // Simple products only:
+   * await client.addBundleToCart('cart_123', bundle.id);
+   * // Some offered products have variants:
+   * await client.addBundleToCart('cart_123', bundle.id, {
+   *   [variantProductId]: selectedVariantId,
+   * });
    * ```
    */
-  async addBundleToCart(cartId, bundleOfferId, variantId) {
-    const body = { bundleOfferId, ...variantId && { variantId } };
+  async addBundleToCart(cartId, bundleOfferId, variantSelections) {
+    const body = {
+      bundleOfferId,
+      ...variantSelections && Object.keys(variantSelections).length > 0 ? { variantSelections } : {}
+    };
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("POST", `/cart/${cartId}/bundle`, body);
     }
@@ -2843,6 +3006,9 @@ var BrainerceClient = class {
       couponCode: null,
       items: [],
       itemCount: 0,
+      hasPriceChanges: false,
+      hasUnavailableItems: false,
+      unavailableItemIds: [],
       expiresAt: null,
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
       updatedAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -3079,23 +3245,21 @@ var BrainerceClient = class {
    * ```
    */
   async smartAddToCart(item) {
+    const payload = {
+      productId: item.productId,
+      variantId: item.variantId,
+      quantity: item.quantity,
+      metadata: item.metadata,
+      ...item.selections && item.selections.length > 0 ? { selections: item.selections } : {},
+      ...item.nestedByModifierId ? { nestedByModifierId: item.nestedByModifierId } : {}
+    };
     if (this.isCustomerLoggedIn()) {
       const cart = await this.getOrCreateCustomerCart();
-      const updated = await this.addToCart(cart.id, {
-        productId: item.productId,
-        variantId: item.variantId,
-        quantity: item.quantity,
-        metadata: item.metadata
-      });
+      const updated = await this.addToCart(cart.id, payload);
       return updated;
     } else {
       const cart = await this.getOrCreateSessionCart();
-      const updated = await this.addToCart(cart.id, {
-        productId: item.productId,
-        variantId: item.variantId,
-        quantity: item.quantity,
-        metadata: item.metadata
-      });
+      const updated = await this.addToCart(cart.id, payload);
       this.updateSessionCartItemCount(updated.items?.length ?? 0);
       return updated;
     }
@@ -4138,6 +4302,16 @@ var BrainerceClient = class {
         variantId: item.variantId || null,
         quantity: item.quantity,
         unitPrice: item.price || "0",
+        // Local carts never reach the server, so they have no live price to
+        // compare against. Surface the snapshot as both values and flag
+        // everything as "unchanged + available" — the migration to a server
+        // cart on next load will run the real recalc.
+        currentUnitPrice: item.price || "0",
+        priceChanged: false,
+        priceDelta: "0",
+        priceDirection: "unchanged",
+        isAvailable: true,
+        unavailableReason: null,
         discountAmount: "0",
         promoDiscountAmount: "0",
         promoSource: null,
@@ -4160,6 +4334,9 @@ var BrainerceClient = class {
         updatedAt: item.addedAt
       })),
       itemCount: localCart.items.reduce((sum, i) => sum + i.quantity, 0),
+      hasPriceChanges: false,
+      hasUnavailableItems: false,
+      unavailableItemIds: [],
       expiresAt: null,
       createdAt: localCart.updatedAt || (/* @__PURE__ */ new Date()).toISOString(),
       updatedAt: localCart.updatedAt || (/* @__PURE__ */ new Date()).toISOString()
@@ -5506,6 +5683,204 @@ var BrainerceClient = class {
       `/api/v1/attributes/${attributeId}/options/${optionId}`
     );
   }
+  // -------------------- Modifier Groups (Admin) --------------------
+  // These methods require Admin mode (apiKey).
+  // Routes: /api/stores/:storeId/modifier-groups[/:id]
+  //         /api/stores/:storeId/modifier-groups/:groupId/modifiers[/:modifierId]
+  //         /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.
+  /**
+   * List modifier groups in a store, paginated.
+   * Requires Admin mode (apiKey).
+   *
+   * @example
+   * ```typescript
+   * const groups = await client.listModifierGroups('store_123', {
+   *   page: 1,
+   *   limit: 20,
+   *   search: 'pizza',
+   *   status: 'active',
+   * });
+   * ```
+   */
+  async listModifierGroups(storeId, params) {
+    return this.adminRequest(
+      "GET",
+      `/api/stores/${storeId}/modifier-groups`,
+      void 0,
+      params
+    );
+  }
+  /**
+   * Fetch a single modifier group (with its modifiers).
+   * Requires Admin mode (apiKey).
+   *
+   * Admin fetches include `internalName`; storefront responses strip it
+   * (PRD §5.2 invariant).
+   */
+  async getModifierGroup(storeId, groupId) {
+    return this.adminRequest(
+      "GET",
+      `/api/stores/${storeId}/modifier-groups/${groupId}`
+    );
+  }
+  /**
+   * Create a modifier group. Modifiers themselves are created separately via
+   * `createModifier(storeId, groupId, …)`.
+   * Requires Admin mode (apiKey).
+   *
+   * @example
+   * ```typescript
+   * const group = await client.createModifierGroup('store_123', {
+   *   name: 'Toppings',
+   *   internalName: 'Pizza toppings',
+   *   selectionType: 'MULTIPLE',
+   *   minSelections: 0,
+   *   maxSelections: 8,
+   *   freeQuantity: 3,
+   *   freeAllocationPolicy: 'EXPENSIVE_FREE',
+   * });
+   * ```
+   */
+  async createModifierGroup(storeId, data) {
+    return this.adminRequest("POST", `/api/stores/${storeId}/modifier-groups`, data);
+  }
+  /**
+   * Update a modifier group's metadata or selection rules. Pass `status: 'archived'`
+   * to soft-delete (the group becomes hidden from product attachments).
+   * Requires Admin mode (apiKey).
+   */
+  async updateModifierGroup(storeId, groupId, data) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/stores/${storeId}/modifier-groups/${groupId}`,
+      data
+    );
+  }
+  /**
+   * Hard-delete a modifier group. Server rejects deletion when the group is
+   * still attached to any product (detach the attachments first, or use
+   * `updateModifierGroup(..., { status: 'archived' })` to keep the row).
+   * Requires Admin mode (apiKey).
+   */
+  async deleteModifierGroup(storeId, groupId) {
+    await this.adminRequest("DELETE", `/api/stores/${storeId}/modifier-groups/${groupId}`);
+  }
+  /**
+   * Create a modifier inside a group (e.g., "Olives" inside the "Toppings" group).
+   * Requires Admin mode (apiKey).
+   *
+   * `priceDelta` is a decimal string. Negatives are accepted for downsell
+   * modifiers (e.g., `"-2.00"` for "no bread"); the server still enforces
+   * `unitPrice >= 0` at cart-line resolution and rejects negative deltas
+   * combined with a `referencedProductId`.
+   *
+   * @example
+   * ```typescript
+   * const olives = await client.createModifier('store_123', 'mg_toppings', {
+   *   name: 'Olives',
+   *   priceDelta: '5.00',
+   *   isDefault: false,
+   *   available: true,
+   * });
+   * ```
+   */
+  async createModifier(storeId, groupId, data) {
+    return this.adminRequest(
+      "POST",
+      `/api/stores/${storeId}/modifier-groups/${groupId}/modifiers`,
+      data
+    );
+  }
+  /**
+   * Update a modifier. Pass `status: 'archived'` to soft-delete.
+   * Requires Admin mode (apiKey).
+   */
+  async updateModifier(storeId, groupId, modifierId, data) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/stores/${storeId}/modifier-groups/${groupId}/modifiers/${modifierId}`,
+      data
+    );
+  }
+  /**
+   * Hard-delete a modifier. Use `updateModifier(..., { status: 'archived' })`
+   * if existing line items / order snapshots reference it.
+   * Requires Admin mode (apiKey).
+   */
+  async deleteModifier(storeId, groupId, modifierId) {
+    await this.adminRequest(
+      "DELETE",
+      `/api/stores/${storeId}/modifier-groups/${groupId}/modifiers/${modifierId}`
+    );
+  }
+  /**
+   * Flip the sold-out toggle on a modifier. Operational endpoint kept separate
+   * from `updateModifier` because the daily ops bar is intentionally lower
+   * (PRD §7.1 — STAFF role once the granular `TOGGLE_MODIFIER_AVAILABILITY`
+   * permission ships).
+   * Requires Admin mode (apiKey).
+   *
+   * @example
+   * ```typescript
+   * // Mark the egg modifier as out of stock during a busy lunch service
+   * await client.toggleModifierAvailability('store_123', 'mg_toppings', 'm_egg', false);
+   * ```
+   */
+  async toggleModifierAvailability(storeId, groupId, modifierId, available) {
+    return this.adminRequest(
+      "POST",
+      `/api/stores/${storeId}/modifier-groups/${groupId}/modifiers/${modifierId}/availability-toggle`,
+      { available }
+    );
+  }
+  /**
+   * Attach a modifier group to a product. Three patterns (PRD §5.4):
+   *
+   *   - `variantId` omitted → default attach (applies to all variants).
+   *   - `variantId` set + matching default attach already exists → variant override row.
+   *   - `variantId` set + no default attach → variant-only group.
+   *
+   * Override fields use `null` to mean inherit; any non-null value (including
+   * `0` or `false`) wins. The disable-for-variant convention is `maxOverride: 0` —
+   * the resolver returns the group with `effectiveMax=0` and the validator
+   * silently skips it on cart add.
+   *
+   * Requires Admin mode (apiKey).
+   */
+  async attachModifierGroup(storeId, productId, data) {
+    return this.adminRequest(
+      "POST",
+      `/api/stores/${storeId}/products/${productId}/modifier-groups`,
+      data
+    );
+  }
+  /**
+   * Update an existing attachment's overrides or position. The `modifierGroupId`
+   * and `variantId` are immutable — to swap groups or move between default /
+   * per-variant rows, detach and re-attach.
+   * Requires Admin mode (apiKey).
+   */
+  async updateAttachment(storeId, productId, attachmentId, data) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/stores/${storeId}/products/${productId}/modifier-groups/${attachmentId}`,
+      data
+    );
+  }
+  /**
+   * Detach a modifier group from a product (or remove a per-variant override row).
+   * Requires Admin mode (apiKey).
+   */
+  async detachModifierGroup(storeId, productId, attachmentId) {
+    await this.adminRequest(
+      "DELETE",
+      `/api/stores/${storeId}/products/${productId}/modifier-groups/${attachmentId}`
+    );
+  }
   // -------------------- Shipping: Zones and Rates (Admin) --------------------
   // These methods require Admin mode (apiKey)
   /**
@@ -5685,7 +6060,10 @@ var BrainerceClient = class {
         type: d.type,
         required: d.required,
         enumValues: d.enumValues || void 0,
-        position: d.position
+        position: d.position,
+        isCustomerInput: d.isCustomerInput,
+        appliesToAllProducts: d.appliesToAllProducts,
+        filterable: d.filterable
       }))
     };
   }
@@ -5741,6 +6119,107 @@ var BrainerceClient = class {
   async deleteMetafieldDefinition(definitionId) {
     await this.adminRequest("DELETE", `/api/v1/metafield-definitions/${definitionId}`);
   }
+  /**
+   * Replace the platform publishing configuration on a metafield definition.
+   * `publishedOn` is the source of truth for which sales channels the field
+   * appears on; `platformMetadata` carries the per-platform mapping config
+   * required for sync.
+   *
+   * Requires Admin mode (apiKey).
+   *
+   * @example
+   * ```typescript
+   * await client.setMetafieldPlatforms('def_123', {
+   *   publishedOn: ['SHOPIFY', 'WOOCOMMERCE'],
+   *   platformMetadata: {
+   *     SHOPIFY: { namespace: 'custom', key: 'warranty' },
+   *     WOOCOMMERCE: { key: '_warranty_info' },
+   *   },
+   * });
+   * ```
+   */
+  async setMetafieldPlatforms(definitionId, data) {
+    return this.adminRequest(
+      "PUT",
+      `/api/v1/metafield-definitions/${definitionId}/platforms`,
+      data
+    );
+  }
+  // -------------- Vibe-coded site publishing (Admin Mode) --------------
+  // Publish/unpublish category/tag/brand/metafield definitions to specific
+  // vibe-coded sites. Mirrors the per-channel control already available for
+  // Products/Coupons. When no publishes exist for an entity, it remains
+  // visible to all vibe-coded sites of the store (legacy default).
+  /**
+   * Publish a metafield definition to a vibe-coded site (admin mode).
+   * @example
+   * ```typescript
+   * await client.publishMetafieldDefinitionToVibeCodedSite('def_123', 'conn_456');
+   * ```
+   */
+  async publishMetafieldDefinitionToVibeCodedSite(definitionId, vibeCodedConnectionId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/metafield-definitions/${definitionId}/publish-vibe-coded`,
+      { vibeCodedConnectionId }
+    );
+  }
+  /** Unpublish a metafield definition from a vibe-coded site (admin mode). */
+  async unpublishMetafieldDefinitionFromVibeCodedSite(definitionId, vibeCodedConnectionId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/metafield-definitions/${definitionId}/unpublish-vibe-coded`,
+      { vibeCodedConnectionId }
+    );
+  }
+  /** Publish a category to a vibe-coded site (admin mode). */
+  async publishCategoryToVibeCodedSite(categoryId, vibeCodedConnectionId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/categories/${categoryId}/publish-vibe-coded`,
+      { vibeCodedConnectionId }
+    );
+  }
+  /** Unpublish a category from a vibe-coded site (admin mode). */
+  async unpublishCategoryFromVibeCodedSite(categoryId, vibeCodedConnectionId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/categories/${categoryId}/unpublish-vibe-coded`,
+      { vibeCodedConnectionId }
+    );
+  }
+  /** Publish a tag to a vibe-coded site (admin mode). */
+  async publishTagToVibeCodedSite(tagId, vibeCodedConnectionId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/tags/${tagId}/publish-vibe-coded`,
+      { vibeCodedConnectionId }
+    );
+  }
+  /** Unpublish a tag from a vibe-coded site (admin mode). */
+  async unpublishTagFromVibeCodedSite(tagId, vibeCodedConnectionId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/tags/${tagId}/unpublish-vibe-coded`,
+      { vibeCodedConnectionId }
+    );
+  }
+  /** Publish a brand to a vibe-coded site (admin mode). */
+  async publishBrandToVibeCodedSite(brandId, vibeCodedConnectionId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/brands/${brandId}/publish-vibe-coded`,
+      { vibeCodedConnectionId }
+    );
+  }
+  /** Unpublish a brand from a vibe-coded site (admin mode). */
+  async unpublishBrandFromVibeCodedSite(brandId, vibeCodedConnectionId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/brands/${brandId}/unpublish-vibe-coded`,
+      { vibeCodedConnectionId }
+    );
+  }
   /**
    * Replace the list of products a (customer-input) metafield definition is
    * attached to. Diff-scoped: only rows for this definition are touched, so
@@ -6310,6 +6789,55 @@ function createWebhookHandler(handlers) {
   };
 }
 
+// src/payment-url.ts
+var ALLOWED_PAYMENT_HOSTS = [
+  // Stripe
+  "checkout.stripe.com",
+  "js.stripe.com",
+  "hooks.stripe.com",
+  // PayPal
+  "www.paypal.com",
+  "www.sandbox.paypal.com",
+  // Cardcom
+  "secure.cardcom.solutions",
+  // Meshulam
+  "meshulam.co.il",
+  // Grow (Linktech)
+  "grow.link",
+  "grow.security",
+  // CreditGuard
+  "creditguard.co.il",
+  // Brainerce-hosted payment embeds (backend payment-embed proxy at
+  // `/api/payment/embed/...` that fronts provider apps' embed shells —
+  // e.g. cardcom-payments OpenFields wrapper). The match also covers
+  // subdomains like `api.brainerce.com`, `staging.brainerce.com`.
+  "brainerce.com"
+];
+function isAllowedPaymentUrl(url, options) {
+  if (!url || typeof url !== "string") return false;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  const hostname = parsed.hostname.toLowerCase();
+  if (options?.allowLocalhost && parsed.protocol === "http:" && (hostname === "localhost" || hostname === "127.0.0.1")) {
+    return true;
+  }
+  if (parsed.protocol !== "https:") return false;
+  const allowed = options?.extraHosts ? [...ALLOWED_PAYMENT_HOSTS, ...options.extraHosts] : ALLOWED_PAYMENT_HOSTS;
+  return allowed.some((host) => hostname === host || hostname.endsWith("." + host));
+}
+function safePaymentRedirect(url, options) {
+  if (!isAllowedPaymentUrl(url, options)) {
+    throw new Error("Payment redirect URL is not in the allowlist");
+  }
+  if (typeof window !== "undefined") {
+    window.location.href = url;
+  }
+}
+
 // src/types.ts
 function isHtmlDescription(product) {
   if (product?.descriptionFormat === "html") return true;
@@ -6549,9 +7077,11 @@ export {
   getStockStatus,
   getVariantOptions,
   getVariantPrice,
+  isAllowedPaymentUrl,
   isCouponApplicableToProduct,
   isHtmlDescription,
   isWebhookEventType,
   parseWebhookEvent,
+  safePaymentRedirect,
   verifyWebhook
 };