brainerce 1.44.0 → 1.44.1

package/README.md

@@ -185,9 +185,22 @@ These sequences are non-negotiable. The order of SDK calls matters.
 
 1. Read `checkoutId` from URL or session.
 2. `await client.handlePaymentSuccess(checkoutId)` — mandatory, clears cart so purchased items don't show on next visit.
-3. `const order = await client.waitForOrder(checkoutId)` — polls until the webhook writes the order.
+3. `const result = await client.waitForOrder(checkoutId)` — polls until the webhook writes the order. `result.status.orderNumber` / `result.status.orderId` are available on success.
 4. Show a spinner during step 3 (webhook may lag). On timeout: show "we're still processing, check your email" with a link to order history — the order WILL appear there.
-5. On success: render order number and line items from the returned `order` object.
+5. On success: render the order number, or — if your design wants more than that — fetch full details:
+
+```typescript
+const result = await client.waitForOrder(checkoutId);
+if (result.success) {
+  const order = await client.getOrderByCheckout(checkoutId);
+  // order.items, order.shippingAddress, order.notes (the shopper's own
+  // order note, read-only), order.subtotal, order.shippingAmount,
+  // order.taxAmount / order.taxBreakdown, order.totalAmount
+}
+```
+
+`getOrderByCheckout` works for guests too — possession of the checkout id is
+the credential, no customer token needed.
 
 ### Password reset flow
 
@@ -2144,6 +2157,7 @@ const checkout = await client.setCheckoutCustomer(checkoutId, {
   firstName: 'John',
   lastName: 'Doe',
   phone: '+1234567890', // Optional
+  notes: 'Please leave the package at the door', // Optional order note (max 2000 chars)
 });
 ```
 
@@ -2160,12 +2174,21 @@ const { checkout, rates } = await client.setShippingAddress(checkoutId, {
   postalCode: '10001',
   country: 'US',
   phone: '+1234567890', // Optional
+  notes: 'Please leave the package at the door', // Optional order note (max 2000 chars)
 });
 
 // rates contains available shipping options
 console.log(rates); // ShippingRate[]
 ```
 
+> **Order notes:** every checkout page should render an optional **"Order
+> notes"** textarea by default. Send its value via `notes` on either
+> `setCheckoutCustomer` or `setShippingAddress` (whichever call your flow
+> makes last) — max 2000 chars, empty string clears a previously-set note.
+> The note is copied onto the order at completion (merchant sees it in the
+> dashboard, it's included in the confirmation email) and echoed back
+> read-only as `Order.notes` on buyer order responses.
+
 #### Select Shipping Method
 
 ```typescript
@@ -2243,6 +2266,7 @@ interface Checkout {
   taxBreakdown?: TaxBreakdown | null; // { totalTax, pricesIncludeTax, breakdown[] }
   total: string;
   couponCode?: string | null;
+  notes?: string | null;      // Order note from setCheckoutCustomer/setShippingAddress
   items: CheckoutLineItem[];
   itemCount: number;
   availableShippingRates?: ShippingRate[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.44.0",
+  "version": "1.44.1",
   "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",