brainerce 1.13.0 → 1.15.0

package/README.md

@@ -2207,6 +2207,44 @@ export default function CheckoutSuccessPage() {
 
 ---
 
+#### Sandbox / Test Mode
+
+When `sandboxPaymentsEnabled` is turned on for a vibe-coded connection, `getPaymentProviders()` includes a sandbox provider that allows placing test orders without real payment.
+
+```typescript
+const { providers } = await client.getPaymentProviders();
+const sandboxProvider = providers.find((p) => p.provider === 'sandbox');
+
+if (sandboxProvider) {
+  // Sandbox is available — testMode will be true
+  console.log(sandboxProvider.testMode); // true
+  console.log(sandboxProvider.name); // "Sandbox (Test Orders)"
+}
+```
+
+When you create a payment intent with the sandbox provider, it returns `renderType: 'sandbox'`:
+
+```typescript
+const intent = await client.createPaymentIntent(checkoutId);
+
+if (intent.clientSdk?.renderType === 'sandbox') {
+  // Show a "Complete Test Order" button instead of real payment UI
+  // No real charges — call completeGuestCheckout() to finalize
+  await client.completeGuestCheckout(checkoutId);
+  // Redirect to order confirmation
+  window.location.href = `/order-confirmation?checkout_id=${checkoutId}`;
+}
+```
+
+**Important notes:**
+
+- Sandbox orders are marked `isTestOrder: true` in the database
+- Sandbox orders are automatically set to `financialStatus: 'paid'`
+- Test orders do not affect store analytics
+- The embedded `PaymentStep` template handles sandbox rendering automatically
+
+---
+
 ### Customer Authentication
 
 #### Register Customer

package/dist/index.d.mts

@@ -2454,8 +2454,8 @@ interface CustomApiTestResult {
  * The frontend dynamically loads the SDK script and calls init/render methods.
  */
 interface PaymentClientSdk {
-    /** How the payment UI is rendered: 'sdk-widget' (JS SDK), 'iframe', or 'redirect' */
-    renderType: 'sdk-widget' | 'iframe' | 'redirect';
+    /** How the payment UI is rendered: 'sdk-widget' (JS SDK), 'iframe', 'redirect', or 'sandbox' (test orders) */
+    renderType: 'sdk-widget' | 'iframe' | 'redirect' | 'sandbox';
     /** URL of the main SDK script to load */
     scriptUrl?: string;
     /** Name of the global variable set by the SDK script (e.g., 'growPayment') */

package/dist/index.d.ts

@@ -2454,8 +2454,8 @@ interface CustomApiTestResult {
  * The frontend dynamically loads the SDK script and calls init/render methods.
  */
 interface PaymentClientSdk {
-    /** How the payment UI is rendered: 'sdk-widget' (JS SDK), 'iframe', or 'redirect' */
-    renderType: 'sdk-widget' | 'iframe' | 'redirect';
+    /** How the payment UI is rendered: 'sdk-widget' (JS SDK), 'iframe', 'redirect', or 'sandbox' (test orders) */
+    renderType: 'sdk-widget' | 'iframe' | 'redirect' | 'sandbox';
     /** URL of the main SDK script to load */
     scriptUrl?: string;
     /** Name of the global variable set by the SDK script (e.g., 'growPayment') */

package/package.json

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