JSPM

  • Created
  • Published
  • Downloads 544
  • Score
    100M100P100Q102809F
  • License MIT

Official SDK for building e-commerce storefronts with Brainerce Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.

Package Exports

  • brainerce

Readme

brainerce

Official SDK for building e-commerce storefronts with Brainerce Platform.

This SDK provides a complete solution for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts to connect to Brainerce's unified commerce API.

🤖 AI Agents / Vibe Coders: See AI_BUILDER_PROMPT.md for a concise, copy-paste-ready prompt optimized for AI code generation. It contains the essential rules and complete code examples to build a working store.

Installation

npm install brainerce
# or
pnpm add brainerce
# or
yarn add brainerce

Quick Reference - Helper Functions

The SDK exports these utility functions for common UI tasks:

Function Purpose Example
formatPrice(amount, { currency?, locale? }) Format prices for display formatPrice("99.99", { currency: 'USD' })$99.99
getPriceDisplay(amount, currency?, locale?) Alias for formatPrice Same as above
getDescriptionContent(product) Get product description (HTML or text) getDescriptionContent(product)
isHtmlDescription(product) Check if description is HTML isHtmlDescription(product)true/false
getStockStatus(inventory) Get human-readable stock status getStockStatus(inventory)"In Stock"
getProductPrice(product) Get effective price (handles sales) getProductPrice(product)29.99
getProductPriceInfo(product) Get price + sale info + discount % { price, isOnSale, discountPercent }
getVariantPrice(variant, basePrice) Get variant price with fallback getVariantPrice(variant, '29.99')34.99
getCartTotals(cart, shippingPrice?) Calculate cart subtotal/discount/total { subtotal, discount, shipping, total }
getCartItemName(item) Get name from nested cart item getCartItemName(item)"Blue T-Shirt"
getCartItemImage(item) Get image URL from cart item getCartItemImage(item)"https://..."
getVariantOptions(variant) Get variant attributes as array [{ name: "Color", value: "Red" }]
isCouponApplicableToProduct(coupon, product) Check if coupon applies isCouponApplicableToProduct(coupon, product)
import {
  formatPrice,
  getDescriptionContent,
  getStockStatus,
  getProductPrice,
  getProductPriceInfo,
  getCartTotals,
  getCartItemName,
  getCartItemImage,
} from 'brainerce';

// Format price for display
const priceText = formatPrice(product.basePrice, { currency: 'USD' }); // "$99.99"

// Get product description (handles HTML vs plain text)
const description = getDescriptionContent(product);

// Get stock status text
const stockText = getStockStatus(product.inventory); // "In Stock", "Low Stock", "Out of Stock"

// Get effective price (handles sale prices automatically)
const price = getProductPrice(product); // Returns number: 29.99

// Get full price info including sale status
const priceInfo = getProductPriceInfo(product);
// { price: 19.99, originalPrice: 29.99, isOnSale: true, discountPercent: 33 }

// Calculate cart totals
const totals = getCartTotals(cart, shippingRate?.price);
// { subtotal: 59.98, discount: 10, shipping: 5.99, total: 55.97 }

// Access cart item details (handles nested structure)
const itemName = getCartItemName(cartItem); // "Blue T-Shirt - Large"
const itemImage = getCartItemImage(cartItem); // "https://..."

⚠️ DO NOT CREATE YOUR OWN UTILITY FILES! All helper functions above are exported from brainerce. Never create utils/format.ts, lib/helpers.ts, or similar files - use the SDK exports directly.


⚠️ CRITICAL: Payment Integration Required!

Your store will NOT work without payment integration. The store owner has already configured payment providers (Stripe/PayPal) - you just need to implement the payment page.

// On your checkout/payment page, ALWAYS call this first:
const { hasPayments, providers } = await omni.getPaymentProviders();

if (!hasPayments) {
  // Show error - payment is not configured
  return <div>Payment not configured for this store</div>;
}

// Show payment forms for available providers
const stripeProvider = providers.find(p => p.provider === 'stripe');
const paypalProvider = providers.find(p => p.provider === 'paypal');

See the Payment Integration section for complete implementation examples.


Quick Start

import { BrainerceClient } from 'brainerce';

// Initialize with your Connection ID
const omni = new BrainerceClient({
  connectionId: 'vc_YOUR_CONNECTION_ID',
});

// Fetch products
const { data: products } = await omni.getProducts();

Common Mistakes to Avoid

AI Agents / Vibe-Coders: Read this section carefully! These are common misunderstandings.

1. Guest Checkout - Don't Use createCheckout with Local Cart!

This is the #1 cause of "Cart not found" errors!

// ❌ WRONG - Local cart ID "__local__" doesn't exist on server!
const cart = await omni.smartGetCart(); // Returns { id: "__local__", ... }
const checkout = await omni.createCheckout({ cartId: cart.id }); // 💥 ERROR: Cart not found

// ✅ CORRECT - Use startGuestCheckout() for guest users
const result = await omni.startGuestCheckout();
if (result.tracked) {
  const checkout = await omni.getCheckout(result.checkoutId);
  // Continue with payment flow...
}

// ✅ ALTERNATIVE - Use submitGuestOrder() for simple checkout without payment UI
const order = await omni.submitGuestOrder();

Rule of thumb:

  • Guest user + Local cart → startGuestCheckout() or submitGuestOrder()
  • Logged-in user + Server cart → createCheckout({ cartId })

2. ⛔ NEVER Create Local Interfaces - Use SDK Types!

This causes type errors and runtime bugs!

// ❌ WRONG - Don't create your own interfaces!
interface CartItem {
  id: string;
  name: string; // WRONG - it's item.product.name!
  price: number; // WRONG - prices are strings!
}

// ❌ WRONG - Don't use 'as unknown as' casting!
const item = result as unknown as MyLocalType;

// ✅ CORRECT - Import ALL types from SDK
import type {
  Product,
  ProductVariant,
  Cart,
  CartItem,
  Checkout,
  CheckoutLineItem,
  Order,
  OrderItem,
  CustomerProfile,
  CustomerAddress,
  ShippingRate,
  PaymentProvider,
  PaymentIntent,
  PaymentStatus,
  SearchSuggestions,
  ProductSuggestion,
  CategorySuggestion,
  OAuthAuthorizeResponse,
  CustomerOAuthProvider,
} from 'brainerce';

⚠️ SDK Type Facts - Trust These!

What Correct Wrong
Prices string (use parseFloat()) number
Cart item name item.product.name item.name
Order item name item.name item.product.name
Cart item image item.product.images[0] item.image
Order item image item.image item.product.images
Address state/province region state or province
OAuth redirect URL authorizationUrl url
OAuth providers response { providers: [...] } [...] directly

If you think a type is "wrong", YOU are wrong. Read the SDK types!

3. formatPrice Expects Options Object

// ❌ WRONG
formatPrice(amount, 'USD');

// ✅ CORRECT
formatPrice(amount, { currency: 'USD' });

4. Cart/Checkout vs Order - Different Item Structures!

IMPORTANT: Cart and Checkout items have NESTED product data. Order items are FLAT.

// CartItem and CheckoutLineItem - NESTED product
cart.items.forEach((item) => {
  console.log(item.product.name); // ✅ Correct for Cart/Checkout
  console.log(item.product.sku);
  console.log(item.product.images);
});

// OrderItem - FLAT structure
order.items.forEach((item) => {
  console.log(item.name); // ✅ Correct for Orders
  console.log(item.sku);
  console.log(item.image); // singular, not images
});
Type Access Name Access Image
CartItem item.product.name item.product.images
CheckoutLineItem item.product.name item.product.images
OrderItem item.name item.image

5. Payment Status is 'succeeded', not 'completed'

// ❌ WRONG
if (status.status === 'completed')

// ✅ CORRECT
if (status.status === 'succeeded')

6. ProductSuggestion vs Product - Different Types

getSearchSuggestions() returns ProductSuggestion[], NOT Product[]. This is intentional - suggestions are lightweight for autocomplete.

// ProductSuggestion has:
{
  (id, name, slug, image, basePrice, salePrice, type);
}

// Product has many more fields

7. All Prices Are Strings - Use parseFloat()

// ❌ WRONG - assuming number
const total = item.price * quantity;

// ✅ CORRECT - parse first
const total = parseFloat(item.price) * quantity;

// Or use SDK helper
import { formatPrice } from 'brainerce';
const display = formatPrice(item.price, { currency: 'USD' });

8. Variant Attributes Are Record<string, string>

// Accessing variant attributes:
const color = variant.attributes?.['Color']; // string
const size = variant.attributes?.['Size']; // string

9. Address Uses region, NOT state

// ❌ WRONG
const address = {
  state: 'NY', // This field doesn't exist!
};

// ✅ CORRECT
const address: SetShippingAddressDto = {
  firstName: 'John',
  lastName: 'Doe',
  line1: '123 Main St',
  city: 'New York',
  region: 'NY', // Use 'region' for state/province
  postalCode: '10001',
  country: 'US',
};

10. OAuth - Use authorizationUrl, NOT url

// ❌ WRONG
const response = await omni.getOAuthAuthorizeUrl('GOOGLE', { redirectUrl });
window.location.href = response.url; // 'url' doesn't exist!

// ✅ CORRECT
const response = await omni.getOAuthAuthorizeUrl('GOOGLE', { redirectUrl });
window.location.href = response.authorizationUrl; // Correct property name

11. OAuth Provider Type is Exported

// ❌ WRONG - creating your own type
type Provider = 'google' | 'facebook'; // lowercase won't work!

// ✅ CORRECT - import from SDK
import { CustomerOAuthProvider } from 'brainerce';
// CustomerOAuthProvider = 'GOOGLE' | 'FACEBOOK' | 'GITHUB'  (UPPERCASE)

const provider: CustomerOAuthProvider = 'GOOGLE';
await omni.getOAuthAuthorizeUrl(provider, { redirectUrl });

12. getAvailableOAuthProviders Returns Object, Not Array

// ❌ WRONG - expecting array directly
const providers = await omni.getAvailableOAuthProviders();
providers.forEach(p => ...);  // Error! providers is not an array

// ✅ CORRECT - access the providers property
const response = await omni.getAvailableOAuthProviders();
response.providers.forEach(p => ...);  // response.providers is the array

13. SDK Uses null, Not undefined

Optional fields in SDK types use null, not undefined:

// SDK types use:
slug: string | null;
salePrice: string | null;

// So when checking:
if (product.slug !== null) {
  // ✅ Check for null
  // ...
}

14. Cart Has No total Field - Use getCartTotals() Helper

// ❌ WRONG - these fields don't exist on Cart
const total = cart.total; // ← 'total' doesn't exist!
const discount = cart.discount; // ← 'discount' doesn't exist! It's 'discountAmount'

// ✅ CORRECT - use the helper function (RECOMMENDED)
import { getCartTotals } from 'brainerce';
const totals = getCartTotals(cart, shippingPrice);
// Returns: { subtotal: 59.98, discount: 10, shipping: 5.99, total: 55.97 }

// ✅ CORRECT - or calculate manually
const subtotal = parseFloat(cart.subtotal);
const discount = parseFloat(cart.discountAmount); // ← Note: 'discountAmount', NOT 'discount'
const total = subtotal - discount;

Important Notes:

  • Cart field is discountAmount, NOT discount
  • Cart has NO total field - use getCartTotals() or calculate
  • Checkout DOES have a total field, but Cart does not
  • getCartTotals() only works with server Cart (which has subtotal and discountAmount fields). It does NOT work with LocalCart (guest cart from localStorage). For LocalCart, calculate totals manually:
    const subtotal = cart.items.reduce(
      (sum, item) => sum + parseFloat(item.price || '0') * item.quantity,
      0
    );

15. SearchSuggestions - Products Have price, Not basePrice

// In SearchSuggestions, ProductSuggestion has:
// - price: effective price (sale price if on sale, otherwise base price)
// - basePrice: original price
// - salePrice: sale price if on sale

// ✅ Use 'price' for display (it's already the correct price)
suggestions.products.map(p => (
  <div>{p.name} - {formatPrice(p.price, { currency })}</div>
));

16. Forgetting to Clear Cart After Payment

This causes "ghost items" in the cart after successful payment!

// ❌ WRONG - Cart items remain after payment!
// In your success page:
export default function SuccessPage() {
  return <div>Thank you for your order!</div>;
  // User goes back to shop → still sees purchased items in cart!
}

// ✅ CORRECT - Call completeGuestCheckout() on success page
export default function SuccessPage() {
  const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');

  useEffect(() => {
    if (checkoutId) {
      // Send order to server AND clear cart
      omni.completeGuestCheckout(checkoutId);
    }
  }, []);

  return <div>Thank you for your order!</div>;
}

Why is this needed?

  • completeGuestCheckout() sends the order to the server AND clears the local cart
  • Without it, the order is never created on the server (payment goes through but no order!)
  • For partial checkout (AliExpress-style), only the purchased items are removed
  • WARNING: Do NOT use handlePaymentSuccess() - it only clears localStorage and does NOT create the order

Checkout: Guest vs Logged-In Customer

⚠️ CRITICAL: There are TWO different checkout flows. Using the wrong one will cause errors!

Customer Type Cart Type With Payment (Stripe) Without Payment UI
Guest Local Cart (localStorage) startGuestCheckout() submitGuestOrder()
Logged In Server Cart createCheckout() completeCheckout()

❌ COMMON MISTAKE - Don't Do This!

// ❌ WRONG - This will FAIL with "Cart not found" error!
const cart = omni.getLocalCart(); // Returns cart with id: "__local__"
const checkout = await omni.createCheckout({ cartId: cart.id }); // ERROR!

// The "__local__" ID is virtual - it doesn't exist on the server!

✅ Correct Flow for Guest Checkout with Payment

// ✅ CORRECT - Use startGuestCheckout() for guests with local cart
const result = await omni.startGuestCheckout();

if (result.tracked) {
  // Now you have a REAL checkout on the server
  const checkout = await omni.getCheckout(result.checkoutId);

  // Continue with shipping, payment, etc.
  await omni.setShippingAddress(result.checkoutId, { ... });
  const intent = await omni.createPaymentIntent(result.checkoutId);
  // ... Stripe payment ...
}

Decision Flow

// ALWAYS check this at checkout!
if (isLoggedIn()) {
  // ✅ Logged-in customer → Server Cart + Checkout flow
  // Orders will be linked to their account
  const order = await completeServerCheckout();
} else {
  // ✅ Guest → Local Cart + submitGuestOrder
  // Orders are standalone (not linked to any account)
  const order = await omni.submitGuestOrder();
}

Guest Checkout (for visitors without account)

// Cart stored locally - NO API calls until checkout!

// Add to local cart (stored in localStorage)
omni.addToLocalCart({
  productId: products[0].id,
  quantity: 1,
  name: products[0].name,
  price: String(products[0].basePrice),
});

// Set customer info
omni.setLocalCartCustomer({ email: 'customer@example.com' });
omni.setLocalCartShippingAddress({
  firstName: 'John',
  lastName: 'Doe',
  line1: '123 Main St',
  city: 'New York',
  postalCode: '10001',
  country: 'US',
});

// Submit order (single API call!)
const order = await omni.submitGuestOrder();
console.log('Order created:', order.orderId);

Logged-In Customer Checkout (orders linked to account)

// 1. Make sure customer token is set (after login)
omni.setCustomerToken(authResponse.token);

// 2. Create server cart (auto-linked to customer!)
const cart = await omni.createCart();
localStorage.setItem('cartId', cart.id);

// 3. Add items to server cart
await omni.addToCart(cart.id, {
  productId: products[0].id,
  quantity: 1,
});

// 4. Create checkout from cart
const checkout = await omni.createCheckout({ cartId: cart.id });

// 5. Set customer info (REQUIRED - email is needed for order!)
await omni.setCheckoutCustomer(checkout.id, {
  email: 'customer@example.com',
  firstName: 'John',
  lastName: 'Doe',
});

// 6. Set shipping address
await omni.setShippingAddress(checkout.id, {
  firstName: 'John',
  lastName: 'Doe',
  line1: '123 Main St',
  city: 'New York',
  postalCode: '10001',
  country: 'US',
});

// 7. Get shipping rates and select one
const rates = await omni.getShippingRates(checkout.id);
await omni.selectShippingMethod(checkout.id, rates[0].id);

// 8. Complete checkout - order is linked to customer!
const { orderId } = await omni.completeCheckout(checkout.id);
console.log('Order created:', orderId);

// Customer can now see this order in omni.getMyOrders()

WARNING: Do NOT use submitGuestOrder() for logged-in customers! Their orders won't be linked to their account and won't appear in their order history.


Two Ways to Handle Cart

Option 1: Local Cart (Guest Users)

For guest users, the cart is stored in localStorage - exactly like Amazon, Shopify, and other major platforms do. This means:

  • ✅ No API calls when browsing/adding to cart
  • ✅ Cart persists across page refreshes
  • ✅ Single API call at checkout
  • ✅ No server load for window shoppers
// Add product to local cart
omni.addToLocalCart({ productId: 'prod_123', quantity: 2 });

// View cart
const cart = omni.getLocalCart();
console.log('Items:', cart.items.length);

// Update quantity
omni.updateLocalCartItem('prod_123', 5);

// Remove item
omni.removeFromLocalCart('prod_123');

// At checkout - submit everything in ONE API call
const order = await omni.submitGuestOrder();

Option 2: Server Cart (Logged-In Customers)

For logged-in customers, you MUST use server-side cart to link orders to their account:

  • ✅ Cart syncs across devices
  • ✅ Abandoned cart recovery
  • ✅ Orders linked to customer account
  • ✅ Customer can see orders in "My Orders"
// 1. Set customer token (after login)
omni.setCustomerToken(token);

// 2. Create cart (auto-linked to customer)
const cart = await omni.createCart();
localStorage.setItem('cartId', cart.id);

// 3. Add items
await omni.addToCart(cart.id, { productId: 'prod_123', quantity: 2 });

// 4. At checkout - create checkout and complete
const checkout = await omni.createCheckout({ cartId: cart.id });
// ... set shipping address, select shipping method ...
const { orderId } = await omni.completeCheckout(checkout.id);

⚠️ CRITICAL: If you use submitGuestOrder() for a logged-in customer, their order will NOT be linked to their account!


Complete Store Setup

Step 1: Create the Brainerce Client

Create a file lib/brainerce.ts:

import { BrainerceClient } from 'brainerce';

export const omni = new BrainerceClient({
  connectionId: 'vc_YOUR_CONNECTION_ID', // Your Connection ID from Brainerce
});

// ----- Guest Cart Helpers (localStorage) -----

export function getCartItemCount(): number {
  return omni.getLocalCartItemCount();
}

export function getCart() {
  return omni.getLocalCart();
}

// ----- For Registered Users (server cart) -----

export function getServerCartId(): string | null {
  if (typeof window === 'undefined') return null;
  return localStorage.getItem('cartId');
}

export function setServerCartId(id: string): void {
  localStorage.setItem('cartId', id);
}

export function clearServerCartId(): void {
  localStorage.removeItem('cartId');
}

// ----- Customer Token Helpers -----

export function setCustomerToken(token: string | null): void {
  if (token) {
    localStorage.setItem('customerToken', token);
    omni.setCustomerToken(token);
  } else {
    localStorage.removeItem('customerToken');
    omni.clearCustomerToken();
  }
}

export function restoreCustomerToken(): string | null {
  const token = localStorage.getItem('customerToken');
  if (token) omni.setCustomerToken(token);
  return token;
}

export function isLoggedIn(): boolean {
  return !!localStorage.getItem('customerToken');
}

Important: Cart & Checkout Data Structures

Nested Product/Variant Structure

Cart and Checkout items use a nested structure for product and variant data. This is a common pattern that prevents data duplication and ensures consistency.

Common Mistake:

// WRONG - product name is NOT at top level
const name = item.name; // undefined!
const sku = item.sku; // undefined!

Correct Access Pattern:

// CORRECT - access via nested objects
const name = item.product.name;
const sku = item.product.sku;
const variantName = item.variant?.name;
const variantSku = item.variant?.sku;

Field Mapping Reference

What You Want CartItem CheckoutLineItem
Product Name item.product.name item.product.name
Product SKU item.product.sku item.product.sku
Product ID item.productId item.productId
Product Images item.product.images item.product.images
Variant Name item.variant?.name item.variant?.name
Variant SKU item.variant?.sku item.variant?.sku
Variant ID item.variantId item.variantId
Unit Price item.unitPrice (string) item.unitPrice (string)
Quantity item.quantity item.quantity

Price Fields Are Strings

All monetary values in Cart and Checkout are returned as strings (e.g., "29.99") to preserve decimal precision across different systems. Use parseFloat() or the formatPrice() helper:

// Monetary fields that are strings:
// - CartItem: unitPrice, discountAmount
// - Cart: subtotal, discountAmount
// - CheckoutLineItem: unitPrice, discountAmount
// - Checkout: subtotal, discountAmount, shippingAmount, taxAmount, total
// - ShippingRate: price

import { formatPrice } from 'brainerce';

// Option 1: Using formatPrice helper (recommended)
const cart = await omni.getCart(cartId);
const total = formatPrice(cart.subtotal); // "$59.98"
const totalNum = formatPrice(cart.subtotal, { asNumber: true }); // 59.98

// Option 2: Manual parseFloat
const subtotal = parseFloat(cart.subtotal);
const discount = parseFloat(cart.discountAmount);
const total = subtotal - discount;

// Line item total
cart.items.forEach((item) => {
  const lineTotal = parseFloat(item.unitPrice) * item.quantity;
  console.log(`${item.product.name}: $${lineTotal.toFixed(2)}`);
});

Complete Cart Item Display Example

import type { CartItem } from 'brainerce';
import { formatPrice } from 'brainerce';

function CartItemRow({ item }: { item: CartItem }) {
  // Access nested product data
  const productName = item.product.name;
  const productSku = item.product.sku;
  const productImage = item.product.images?.[0]?.url;

  // Access nested variant data (if exists)
  const variantName = item.variant?.name;
  const displayName = variantName ? `${productName} - ${variantName}` : productName;

  // Format price using helper
  const unitPrice = formatPrice(item.unitPrice);
  const lineTotal = formatPrice(item.unitPrice, { asNumber: true }) * item.quantity;

  return (
    <div className="flex items-center gap-4">
      <img src={productImage} alt={displayName} className="w-16 h-16 object-cover" />
      <div className="flex-1">
        <h3 className="font-medium">{displayName}</h3>
        <p className="text-sm text-gray-500">SKU: {item.variant?.sku || productSku}</p>
      </div>
      <span className="text-gray-600">Qty: {item.quantity}</span>
      <span className="font-medium">${lineTotal.toFixed(2)}</span>
    </div>
  );
}

API Reference

Products

Get Products (with pagination)

import { omni } from '@/lib/brainerce';
import type { Product, PaginatedResponse } from 'brainerce';

const response: PaginatedResponse<Product> = await omni.getProducts({
  page: 1,
  limit: 12,
  search: 'shirt', // Optional: search by name
  status: 'active', // Optional: 'active' | 'draft' | 'archived'
  type: 'SIMPLE', // Optional: 'SIMPLE' | 'VARIABLE'
  sortBy: 'createdAt', // Optional: 'name' | 'createdAt' | 'updatedAt' | 'basePrice'
  sortOrder: 'desc', // Optional: 'asc' | 'desc'
});

console.log(response.data); // Product[]
console.log(response.meta.total); // Total number of products
console.log(response.meta.totalPages); // Total pages

Get Single Product

const product: Product = await omni.getProduct('product_id');

console.log(product.name);
console.log(product.basePrice);
console.log(product.salePrice); // null if no sale
console.log(product.images); // ProductImage[]
console.log(product.variants); // ProductVariant[] (for VARIABLE products)
console.log(product.inventory); // { total, reserved, available }

Search Suggestions (Autocomplete)

Get search suggestions for building autocomplete/search-as-you-type UI:

import type { SearchSuggestions } from 'brainerce';

// Basic autocomplete
const suggestions: SearchSuggestions = await omni.getSearchSuggestions('shirt');

console.log(suggestions.products);
// [{ id, name, image, basePrice, salePrice, type }]

console.log(suggestions.categories);
// [{ id, name, productCount }]

// With custom limit (default: 5, max: 10)
const suggestions = await omni.getSearchSuggestions('dress', 3);

Search covers: name, sku, description, categories, tags, and brands.

Example: Search Input with Suggestions

function SearchInput() {
  const [query, setQuery] = useState('');
  const [suggestions, setSuggestions] = useState<SearchSuggestions | null>(null);

  // Debounce search requests
  useEffect(() => {
    if (query.length < 2) {
      setSuggestions(null);
      return;
    }

    const timer = setTimeout(async () => {
      const results = await omni.getSearchSuggestions(query, 5);
      setSuggestions(results);
    }, 300);

    return () => clearTimeout(timer);
  }, [query]);

  return (
    <div>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search products..."
      />
      {suggestions && (
        <div className="suggestions">
          {suggestions.products.map((product) => (
            <a key={product.id} href={`/products/${product.slug}`}>
              <img src={product.image || '/placeholder.png'} alt={product.name} />
              <span>{product.name}</span>
              <span>${product.basePrice}</span>
            </a>
          ))}
          {suggestions.categories.map((category) => (
            <a key={category.id} href={`/category/${category.id}`}>
              {category.name} ({category.productCount} products)
            </a>
          ))}
        </div>
      )}
    </div>
  );
}

Product Type Definition

interface Product {
  id: string;
  name: string;
  description?: string | null;
  descriptionFormat?: 'text' | 'html' | 'markdown'; // Format of description content
  sku: string;
  basePrice: number;
  salePrice?: number | null;
  status: 'active' | 'draft' | 'archived';
  type: 'SIMPLE' | 'VARIABLE';
  images?: ProductImage[];
  inventory?: InventoryInfo | null;
  variants?: ProductVariant[];
  categories?: string[];
  tags?: string[];
  createdAt: string;
  updatedAt: string;
}

interface ProductImage {
  url: string;
  position?: number;
  isMain?: boolean;
}

interface ProductVariant {
  id: string;
  sku?: string | null;
  name?: string | null;
  price?: number | null;
  salePrice?: number | null;
  attributes?: Record<string, string>;
  inventory?: InventoryInfo | null;
}

interface InventoryInfo {
  total: number;
  reserved: number;
  available: number;
  trackingMode?: 'TRACKED' | 'UNLIMITED' | 'DISABLED';
  inStock: boolean; // Pre-calculated - use this for display!
  canPurchase: boolean; // Pre-calculated - use this for add-to-cart
}

Product Metafields (Custom Fields)

Products can have custom fields (metafields) defined by the store owner, such as "Material", "Care Instructions", or "Warranty".

import {
  getProductMetafield,
  getProductMetafieldValue,
  getProductMetafieldsByType,
} from 'brainerce';

const product = await omni.getProductBySlug('blue-shirt');

// Access all metafields
product.metafields?.forEach((field) => {
  console.log(`${field.definitionName}: ${field.value}`);
});

// Get a specific metafield by key
const material = getProductMetafieldValue(product, 'material'); // auto-parsed (string | number | boolean | null)
const careField = getProductMetafield(product, 'care_instructions'); // full ProductMetafield object

// Filter metafields by type
const textFields = getProductMetafieldsByType(product, 'TEXT');

// Fetch metafield definitions (schema) to build dynamic UI
const { definitions } = await omni.getPublicMetafieldDefinitions();
definitions.forEach((def) => {
  console.log(`${def.name} (${def.key}): ${def.type}, required: ${def.required}`);
});

Note: metafields may be empty if the store hasn't defined custom fields. Always use optional chaining (product.metafields?.forEach).

Displaying Price Range for Variable Products

For products with type: 'VARIABLE' and multiple variants with different prices, display a price range instead of a single price:

// Helper function to get price range from variants
function getPriceRange(product: Product): { min: number; max: number } | null {
  if (product.type !== 'VARIABLE' || !product.variants?.length) {
    return null;
  }

  const prices = product.variants
    .map(v => v.price ?? product.basePrice)
    .filter((p): p is number => p !== null);

  if (prices.length === 0) return null;

  const min = Math.min(...prices);
  const max = Math.max(...prices);

  // Return null if all variants have the same price
  return min !== max ? { min, max } : null;
}

// Usage in component
function ProductPrice({ product }: { product: Product }) {
  const priceRange = getPriceRange(product);

  if (priceRange) {
    // Variable product with different variant prices - show range
    return <span>${priceRange.min} - ${priceRange.max}</span>;
  }

  // Simple product or all variants same price - show single price
  return product.salePrice ? (
    <>
      <span className="text-red-600">${product.salePrice}</span>
      <span className="line-through text-gray-400 ml-2">${product.basePrice}</span>
    </>
  ) : (
    <span>${product.basePrice}</span>
  );
}

When to show price range:

  • Product type is 'VARIABLE'
  • Has 2+ variants with different prices
  • Example: T-shirt sizes S/M/L at $29, XL/XXL at $34 → Display "$29 - $34"

When to show single price:

  • Product type is 'SIMPLE'
  • Variable product where all variants have the same price

Rendering Product Descriptions

CRITICAL: Product descriptions from Shopify/WooCommerce contain HTML tags. If you render them as plain text, users will see raw <p>, <ul>, <li> tags instead of formatted content!

Use the SDK helper functions to handle this automatically:

import { isHtmlDescription, getDescriptionContent } from 'brainerce';

// Option 1: Using isHtmlDescription helper (recommended)
function ProductDescription({ product }: { product: Product }) {
  if (!product.description) return null;

  if (isHtmlDescription(product)) {
    // HTML from Shopify/WooCommerce - MUST use dangerouslySetInnerHTML
    return <div dangerouslySetInnerHTML={{ __html: product.description }} />;
  }

  // Plain text - render normally
  return <p>{product.description}</p>;
}

// Option 2: Using getDescriptionContent helper
function ProductDescription({ product }: { product: Product }) {
  const content = getDescriptionContent(product);
  if (!content) return null;

  if ('html' in content) {
    return <div dangerouslySetInnerHTML={{ __html: content.html }} />;
  }

  return <p>{content.text}</p>;
}
Source Platform descriptionFormat Rendering
Shopify 'html' Use dangerouslySetInnerHTML
WooCommerce 'html' Use dangerouslySetInnerHTML
TikTok 'text' Render as plain text
Manual entry 'text' Render as plain text

Common Mistake - DO NOT do this:

// WRONG - HTML will show as raw tags like <p>Hello</p>
<p>{product.description}</p>

The local cart stores everything in localStorage until checkout. This is the recommended approach for most storefronts.

Add to Local Cart

// Add item with product info (for display)
omni.addToLocalCart({
  productId: 'prod_123',
  variantId: 'var_456', // Optional: for products with variants
  quantity: 2,
  name: 'Cool T-Shirt', // Optional: for cart display
  price: '29.99', // Optional: for cart display
  image: 'https://...', // Optional: for cart display
});

Get Local Cart

const cart = omni.getLocalCart();

console.log(cart.items); // Array of cart items
console.log(cart.customer); // Customer info (if set)
console.log(cart.shippingAddress); // Shipping address (if set)
console.log(cart.couponCode); // Applied coupon (if any)

Update Item Quantity

// Set quantity to 5
omni.updateLocalCartItem('prod_123', 5);

// For variant products
omni.updateLocalCartItem('prod_123', 3, 'var_456');

// Set to 0 to remove
omni.updateLocalCartItem('prod_123', 0);

Remove Item

omni.removeFromLocalCart('prod_123');
omni.removeFromLocalCart('prod_123', 'var_456'); // With variant

Clear Cart

omni.clearLocalCart();

Set Customer Info

omni.setLocalCartCustomer({
  email: 'customer@example.com', // Required
  firstName: 'John', // Optional
  lastName: 'Doe', // Optional
  phone: '+1234567890', // Optional
});

Set Shipping Address

omni.setLocalCartShippingAddress({
  firstName: 'John',
  lastName: 'Doe',
  line1: '123 Main St',
  line2: 'Apt 4B', // Optional
  city: 'New York',
  region: 'NY', // Optional: State/Province
  postalCode: '10001',
  country: 'US',
  phone: '+1234567890', // Optional
});

Set Billing Address (Optional)

omni.setLocalCartBillingAddress({
  firstName: 'John',
  lastName: 'Doe',
  line1: '456 Business Ave',
  city: 'New York',
  postalCode: '10002',
  country: 'US',
});

Apply Coupon

omni.setLocalCartCoupon('SAVE20');

// Remove coupon
omni.setLocalCartCoupon(undefined);

Get Cart Item Count

const count = omni.getLocalCartItemCount();
console.log(`${count} items in cart`);

Local Cart Type Definition

interface LocalCart {
  items: LocalCartItem[];
  couponCode?: string;
  customer?: {
    email: string;
    firstName?: string;
    lastName?: string;
    phone?: string;
  };
  shippingAddress?: {
    firstName: string;
    lastName: string;
    line1: string;
    line2?: string;
    city: string;
    region?: string;
    postalCode: string;
    country: string;
    phone?: string;
  };
  billingAddress?: {
    /* same as shipping */
  };
  notes?: string;
  updatedAt: string;
}

interface LocalCartItem {
  productId: string;
  variantId?: string;
  quantity: number;
  name?: string;
  sku?: string;
  price?: string;
  image?: string;
  addedAt: string;
}

Guest Checkout (Submit Order)

Submit the local cart as an order with a single API call:

// Make sure cart has items, customer email, and shipping address
const order = await omni.submitGuestOrder();

console.log(order.orderId); // 'order_abc123...'
console.log(order.orderNumber); // 'ORD-12345'
console.log(order.status); // 'pending'
console.log(order.total); // 59.98
console.log(order.message); // 'Order created successfully'

// Cart is automatically cleared after successful order

🔄 Automatic Tracking: If "Track Guest Checkouts" is enabled in your connection settings (Brainerce Admin), submitGuestOrder() will automatically create a tracked checkout session before placing the order. This allows you to see abandoned carts and checkout sessions in your admin dashboard - no code changes needed!

Keep Cart After Order

// If you want to keep the cart data (e.g., for order review page)
const order = await omni.submitGuestOrder({ clearCartOnSuccess: false });

Create Order with Custom Data

If you manage cart state yourself instead of using local cart:

const order = await omni.createGuestOrder({
  items: [
    { productId: 'prod_123', quantity: 2 },
    { productId: 'prod_456', variantId: 'var_789', quantity: 1 },
  ],
  customer: {
    email: 'customer@example.com',
    firstName: 'John',
    lastName: 'Doe',
  },
  shippingAddress: {
    firstName: 'John',
    lastName: 'Doe',
    line1: '123 Main St',
    city: 'New York',
    postalCode: '10001',
    country: 'US',
  },
  couponCode: 'SAVE20', // Optional
  notes: 'Please gift wrap', // Optional
});

Guest Order Response Type

interface GuestOrderResponse {
  orderId: string;
  orderNumber: string;
  status: string;
  total: number;
  message: string;
}

Tracked Guest Checkout (Automatic)

Note: As of SDK v0.7.1, submitGuestOrder() automatically handles tracking. You don't need to use these methods unless you want explicit control over the checkout flow.

When "Track Guest Checkouts" is enabled in your connection settings, checkout sessions are automatically created on the server, allowing:

  • Visibility of checkout sessions in admin dashboard
  • Abandoned cart tracking
  • Future: abandoned cart recovery emails

How to Enable

  1. Go to Brainerce Admin → Integrations → Vibe-Coded Sites
  2. Click on your connection → Settings
  3. Enable "Track Guest Checkouts"
  4. Save - that's it! No code changes needed.

Advanced: Manual Tracking Control

If you need explicit control over the tracking flow (e.g., to track checkout steps before the user places an order):

// 1. Start tracked checkout (sends cart items to server)
const checkout = await omni.startGuestCheckout();

if (checkout.tracked) {
  // 2. Update with shipping address
  await omni.updateGuestCheckoutAddress(checkout.checkoutId, {
    shippingAddress: {
      firstName: 'John',
      lastName: 'Doe',
      line1: '123 Main St',
      city: 'New York',
      postalCode: '10001',
      country: 'US',
    },
  });

  // 3. Complete the checkout
  const order = await omni.completeGuestCheckout(checkout.checkoutId);
  console.log('Order created:', order.orderId);
} else {
  // Fallback to regular guest checkout
  const order = await omni.submitGuestOrder();
}

Response Types

type GuestCheckoutStartResponse =
  | {
      tracked: true;
      checkoutId: string;
      cartId: string;
      message: string;
    }
  | {
      tracked: false;
      message: string;
    };

Server Cart (Registered Users)

For logged-in customers who want cart sync across devices.

Create Cart

const cart = await omni.createCart();
setServerCartId(cart.id); // Save to localStorage

Get Cart

const cartId = getCartId();
if (cartId) {
  const cart = await omni.getCart(cartId);
  console.log(cart.items); // CartItem[]
  console.log(cart.itemCount); // Total items
  console.log(cart.subtotal); // Subtotal amount
}

Add to Cart

const cart = await omni.addToCart(cartId, {
  productId: 'product_id',
  variantId: 'variant_id', // Optional: for VARIABLE products
  quantity: 2,
  notes: 'Gift wrap please', // Optional
});

Update Cart Item

const cart = await omni.updateCartItem(cartId, itemId, {
  quantity: 3,
});

Remove Cart Item

const cart = await omni.removeCartItem(cartId, itemId);

Apply Coupon

const cart = await omni.applyCoupon(cartId, 'SAVE20');
console.log(cart.discountAmount); // Discount applied
console.log(cart.couponCode); // 'SAVE20'

Remove Coupon

const cart = await omni.removeCoupon(cartId);

Cart Type Definition

interface Cart {
  id: string;
  sessionToken?: string | null;
  customerId?: string | null;
  status: 'ACTIVE' | 'MERGED' | 'CONVERTED' | 'ABANDONED';
  currency: string;
  subtotal: string;
  discountAmount: string;
  couponCode?: string | null;
  items: CartItem[];
  itemCount: number;
  createdAt: string;
  updatedAt: string;
}

interface CartItem {
  id: string;
  productId: string;
  variantId?: string | null;
  quantity: number;
  unitPrice: string;
  discountAmount: string;
  notes?: string | null;
  product: {
    id: string;
    name: string;
    sku: string;
    images?: unknown[];
  };
  variant?: {
    id: string;
    name?: string | null;
    sku?: string | null;
  } | null;
}

Checkout

Create Checkout from Cart

const checkout = await omni.createCheckout({
  cartId: cartId,
});

Partial Checkout (AliExpress-style)

Allow customers to select which items to checkout from their cart. Only selected items are purchased - remaining items stay in the cart for later.

// 1. In your cart page, track selected items
const [selectedItems, setSelectedItems] = useState<Set<string>>(new Set());

// 2. Create checkout with only selected items
const checkout = await omni.createCheckout({
  cartId: cart.id,
  selectedItemIds: Array.from(selectedItems), // Only these items go to checkout
});

// 3. Before checkout, check stock ONLY for selected items
const stockCheck = await omni.checkCartStock(cart, Array.from(selectedItems));
if (!stockCheck.allAvailable) {
  // Handle out-of-stock items
}

// After successful payment:
// - Selected items are REMOVED from cart
// - Unselected items REMAIN in cart (cart stays ACTIVE)
// - Customer can continue shopping and checkout remaining items later

Set Customer Information

const checkout = await omni.setCheckoutCustomer(checkoutId, {
  email: 'customer@example.com',
  firstName: 'John',
  lastName: 'Doe',
  phone: '+1234567890', // Optional
});

Set Shipping Address

const { checkout, rates } = await omni.setShippingAddress(checkoutId, {
  firstName: 'John',
  lastName: 'Doe',
  line1: '123 Main St',
  line2: 'Apt 4B', // Optional
  city: 'New York',
  region: 'NY', // State/Province
  postalCode: '10001',
  country: 'US',
  phone: '+1234567890', // Optional
});

// rates contains available shipping options
console.log(rates); // ShippingRate[]

Select Shipping Method

const checkout = await omni.selectShippingMethod(checkoutId, rates[0].id);

Set Billing Address

// Same as shipping
const checkout = await omni.setBillingAddress(checkoutId, {
  ...shippingAddress,
  sameAsShipping: true, // Optional shortcut
});

Complete Checkout

const { orderId } = await omni.completeCheckout(checkoutId);
clearCartId(); // Clear cart from localStorage
console.log('Order created:', orderId);

Checkout Type Definition

interface Checkout {
  id: string;
  status: CheckoutStatus;
  email?: string | null;
  shippingAddress?: CheckoutAddress | null;
  billingAddress?: CheckoutAddress | null;
  shippingMethod?: ShippingRate | null;
  currency: string;
  subtotal: string;
  discountAmount: string;
  shippingAmount: string;
  taxAmount: string;
  total: string;
  couponCode?: string | null;
  items: CheckoutLineItem[];
  itemCount: number;
  availableShippingRates?: ShippingRate[];
}

type CheckoutStatus = 'PENDING' | 'SHIPPING_SET' | 'PAYMENT_PENDING' | 'COMPLETED' | 'FAILED';

interface ShippingRate {
  id: string;
  name: string;
  description?: string | null;
  price: string;
  currency: string;
  estimatedDays?: number | null;
}

Shipping Rates: Complete Flow

The shipping flow involves setting an address and then selecting from available rates:

// Step 1: Set shipping address - this returns available rates
const { checkout, rates } = await omni.setShippingAddress(checkoutId, {
  firstName: 'John',
  lastName: 'Doe',
  line1: '123 Main St',
  city: 'New York',
  region: 'NY',
  postalCode: '10001',
  country: 'US',
});

// Step 2: Handle empty rates (edge case)
if (rates.length === 0) {
  // No shipping options available for this address
  // This can happen when:
  // - Store doesn't ship to this address/country
  // - All shipping methods have restrictions that exclude this address
  // - Shipping rates haven't been configured in the store

  return (
    <div className="bg-yellow-50 p-4 rounded">
      <p className="font-medium">No shipping options available</p>
      <p className="text-sm text-gray-600">
        We currently cannot ship to this address. Please try a different address or contact us for
        assistance.
      </p>
    </div>
  );
}

// Step 3: Display available rates to customer
<div className="space-y-2">
  <h3 className="font-medium">Select Shipping Method</h3>
  {rates.map((rate) => (
    <label key={rate.id} className="flex items-center gap-3 p-3 border rounded cursor-pointer">
      <input
        type="radio"
        name="shipping"
        value={rate.id}
        checked={selectedRateId === rate.id}
        onChange={() => setSelectedRateId(rate.id)}
      />
      <div className="flex-1">
        <span className="font-medium">{rate.name}</span>
        {rate.description && <p className="text-sm text-gray-500">{rate.description}</p>}
        {rate.estimatedDays && (
          <p className="text-sm text-gray-500">Estimated delivery: {rate.estimatedDays} business days</p>
        )}
      </div>
      <span className="font-medium">${parseFloat(rate.price).toFixed(2)}</span>
    </label>
  ))}
</div>;

// Step 4: Select the shipping method
await omni.selectShippingMethod(checkoutId, selectedRateId);

Handling Empty Shipping Rates:

When no shipping rates are available, you have several options:

// Option 1: Show helpful message
if (rates.length === 0) {
  return <NoShippingAvailable address={shippingAddress} />;
}

// Option 2: Allow customer to contact store
if (rates.length === 0) {
  return (
    <div>
      <p>Shipping not available to your location.</p>
      <a href="/contact">Request a shipping quote</a>
    </div>
  );
}

// Option 3: Validate before proceeding
function canProceedToPayment(checkout: Checkout, rates: ShippingRate[]): boolean {
  if (rates.length === 0) return false;
  if (!checkout.shippingRateId) return false;
  if (!checkout.email) return false;
  return true;
}

Payment Integration (Vibe-Coded Sites)

For vibe-coded sites, the SDK provides payment integration with Stripe and PayPal. The store owner configures their payment provider(s) in the admin, and your site uses these methods to process payments.

⚠️ Important: Getting a Valid Checkout ID

Before creating a payment intent, you need a checkout ID. How you get it depends on the customer type:

// For GUEST users (local cart in localStorage):
const result = await omni.startGuestCheckout();
const checkoutId = result.checkoutId;

// For LOGGED-IN users (server cart):
const checkout = await omni.createCheckout({ cartId: serverCartId });
const checkoutId = checkout.id;

// Then continue with shipping and payment...

Use this method to get ALL enabled payment providers and build dynamic UI:

const { hasPayments, providers, defaultProvider } = await omni.getPaymentProviders();

// Returns:
// {
//   hasPayments: true,
//   providers: [
//     {
//       id: 'provider_xxx',
//       provider: 'stripe',
//       name: 'Stripe',
//       publicKey: 'pk_live_xxx...',
//       supportedMethods: ['card', 'ideal'],
//       testMode: false,
//       isDefault: true
//     },
//     {
//       id: 'provider_yyy',
//       provider: 'paypal',
//       name: 'PayPal',
//       publicKey: 'client_id_xxx...',
//       supportedMethods: ['paypal'],
//       testMode: false,
//       isDefault: false
//     }
//   ],
//   defaultProvider: { ... }  // The default provider (first one)
// }

// Build dynamic UI based on available providers
if (!hasPayments) {
  return <div>Payment not configured for this store</div>;
}

const stripeProvider = providers.find(p => p.provider === 'stripe');
const paypalProvider = providers.find(p => p.provider === 'paypal');

// Show Stripe payment form if available
if (stripeProvider) {
  const stripe = await loadStripe(stripeProvider.publicKey);
  // ... show Stripe Elements
}

// Show PayPal buttons if available
if (paypalProvider) {
  // ... show PayPal buttons with paypalProvider.publicKey as client-id
}

Get Payment Configuration (Single Provider)

If you only need the default provider, use this simpler method:

const config = await omni.getPaymentConfig();

// Returns:
// {
//   provider: 'stripe' | 'paypal',
//   publicKey: 'pk_live_xxx...',  // Stripe publishable key or PayPal client ID
//   supportedMethods: ['card', 'ideal', 'bancontact'],
//   testMode: false
// }

Create Payment Intent

After the customer fills in shipping details, create a payment intent:

const intent = await omni.createPaymentIntent(checkout.id);

// Returns:
// {
//   id: 'pi_xxx...',
//   clientSecret: 'pi_xxx_secret_xxx',  // Used by Stripe.js/PayPal SDK
//   amount: 9999,  // In cents
//   currency: 'USD',
//   status: 'requires_payment_method'
// }

Confirm Payment with Stripe.js

Use the client secret with Stripe.js to collect payment:

// Initialize Stripe.js with the public key from getPaymentConfig()
const stripe = await loadStripe(config.publicKey);

// Create Elements and Payment Element
const elements = stripe.elements({ clientSecret: intent.clientSecret });
const paymentElement = elements.create('payment');
paymentElement.mount('#payment-element');

// When customer submits payment
const { error } = await stripe.confirmPayment({
  elements,
  confirmParams: {
    return_url: `${window.location.origin}/checkout/success?checkout_id=${checkout.id}`,
  },
});

if (error) {
  console.error('Payment failed:', error.message);
}

Important: Orders are created asynchronously via webhook after Stripe confirms payment. This typically takes 1-5 seconds, but can vary. Follow these best practices:

Option 1: Optimistic Success Page (Recommended - Used by Amazon, Shopify, AliExpress)

Show success immediately without waiting for orderId. This is the industry standard:

// In your payment form, after stripe.confirmPayment() succeeds:
const { error } = await stripe.confirmPayment({
  elements,
  confirmParams: {
    return_url: `${window.location.origin}/checkout/success?checkout_id=${checkout.id}`,
  },
});

// On /checkout/success page - show confirmation IMMEDIATELY:
export default function CheckoutSuccessPage() {
  const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');

  return (
    <div className="text-center py-12">
      <h1 className="text-2xl font-bold text-green-600">Payment Received!</h1>
      <p className="mt-4">Your order is being processed.</p>
      <p className="mt-2 text-gray-600">
        Confirmation #{checkoutId?.slice(-8).toUpperCase()}
      </p>
      <p className="mt-4">A confirmation email will be sent shortly.</p>
      <a href="/orders" className="mt-6 inline-block text-blue-600">
        View Your Orders →
      </a>
    </div>
  );
}

Option 2: Wait for Order (For SPAs that need orderId)

Use waitForOrder() to poll in the background with exponential backoff:

// After payment succeeds, wait for order creation (max 30 seconds)
const result = await omni.waitForOrder(checkout.id, {
  maxWaitMs: 30000, // 30 seconds max
  onPollAttempt: (attempt, status) => {
    console.log(`Checking order status... (attempt ${attempt})`);
  },
  onOrderReady: (status) => {
    // Called immediately when order is created
    console.log('Order ready:', status.orderNumber);
  },
});

if (result.success) {
  // Order was created within timeout
  window.location.href = `/orders/${result.status.orderId}`;
} else {
  // Order not created yet - show optimistic success anyway
  // The email will be sent when order is ready
  showSuccessMessage('Payment received! Order confirmation coming soon.');
}

Option 3: Simple Status Check (Single poll)

For simple use cases where you just want to check once:

const status = await omni.getPaymentStatus(checkout.id);

// Returns:
// {
//   checkoutId: 'checkout_xxx',
//   status: 'succeeded' | 'pending' | 'failed' | 'canceled',
//   orderId: 'order_xxx',      // Only if order was created
//   orderNumber: 'ORD-123',    // Only if order was created
//   error: 'Payment declined'  // Only if payment failed
// }

if (status.status === 'succeeded' && status.orderId) {
  window.location.href = `/order-confirmation/${status.orderId}`;
} else if (status.status === 'succeeded') {
  // Payment succeeded but order not created yet
  showMessage('Payment received, processing your order...');
} else if (status.status === 'failed') {
  showError(status.error || 'Payment failed');
}

Why Optimistic Success? Stripe webhooks typically arrive within 1-5 seconds, but network issues can cause delays. Major e-commerce platforms (Amazon, Shopify) show success immediately and send order details via email. This provides better UX than making customers wait on a loading screen.

Complete Checkout with Payment Example

Note: This example assumes you already have a checkout_id. See below for how to create one.

How to get a checkout_id:

// For GUEST users (local cart):
const result = await omni.startGuestCheckout();
const checkoutId = result.checkoutId; // Use this!

// For LOGGED-IN users (server cart):
const checkout = await omni.createCheckout({ cartId: cart.id });
const checkoutId = checkout.id; // Use this!
'use client';
import { useState, useEffect } from 'react';
import { loadStripe, Stripe, StripeElements } from '@stripe/stripe-js';
import { Elements, PaymentElement, useStripe, useElements } from '@stripe/react-stripe-js';
import { omni } from '@/lib/brainerce';
import type { Checkout, PaymentConfig, PaymentIntent } from 'brainerce';

export default function CheckoutPaymentPage() {
  const [checkout, setCheckout] = useState<Checkout | null>(null);
  const [paymentConfig, setPaymentConfig] = useState<PaymentConfig | null>(null);
  const [paymentIntent, setPaymentIntent] = useState<PaymentIntent | null>(null);
  const [stripePromise, setStripePromise] = useState<Promise<Stripe | null> | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState('');

  useEffect(() => {
    async function initPayment() {
      try {
        // Get checkout_id from URL (set by previous step)
        const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
        if (!checkoutId) throw new Error('No checkout ID');

        // Get payment configuration
        const config = await omni.getPaymentConfig();
        setPaymentConfig(config);

        // Initialize Stripe
        if (config.provider === 'stripe') {
          setStripePromise(loadStripe(config.publicKey));
        }

        // Create payment intent
        const intent = await omni.createPaymentIntent(checkoutId);
        setPaymentIntent(intent);
      } catch (err) {
        setError(err instanceof Error ? err.message : 'Failed to initialize payment');
      } finally {
        setLoading(false);
      }
    }
    initPayment();
  }, []);

  if (loading) return <div>Loading payment...</div>;
  if (error) return <div className="text-red-600">{error}</div>;
  if (!paymentConfig || !paymentIntent || !stripePromise) return null;

  return (
    <div className="max-w-lg mx-auto p-6">
      <h1 className="text-2xl font-bold mb-6">Payment</h1>

      <Elements stripe={stripePromise} options={{ clientSecret: paymentIntent.clientSecret }}>
        <PaymentForm checkoutId={paymentIntent.id} />
      </Elements>
    </div>
  );
}

function PaymentForm({ checkoutId }: { checkoutId: string }) {
  const stripe = useStripe();
  const elements = useElements();
  const [processing, setProcessing] = useState(false);
  const [error, setError] = useState('');

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!stripe || !elements) return;

    setProcessing(true);
    setError('');

    const { error } = await stripe.confirmPayment({
      elements,
      confirmParams: {
        return_url: `${window.location.origin}/checkout/success?checkout_id=${checkoutId}`,
      },
    });

    if (error) {
      setError(error.message || 'Payment failed');
      setProcessing(false);
    }
    // If successful, Stripe redirects to return_url
  };

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement />

      {error && <div className="text-red-600 mt-4">{error}</div>}

      <button
        type="submit"
        disabled={!stripe || processing}
        className="w-full mt-6 bg-green-600 text-white py-3 rounded disabled:opacity-50"
      >
        {processing ? 'Processing...' : 'Pay Now'}
      </button>
    </form>
  );
}

Complete Order After Payment: completeGuestCheckout()

CRITICAL: After payment succeeds, you MUST call completeGuestCheckout() to create the order on the server and clear the cart.

WARNING: Do NOT use handlePaymentSuccess() - it only clears the local cart (localStorage) and does NOT send the order to the server. Your customer will pay but no order will be created!

// On your /checkout/success page:
export default function CheckoutSuccessPage() {
  const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');

  useEffect(() => {
    if (checkoutId) {
      // IMPORTANT: This sends the order to the server AND clears the cart
      // completeGuestCheckout() returns GuestOrderResponse (has .orderNumber directly)
      // This is different from waitForOrder() which returns WaitForOrderResult
      // (access orderNumber via .status.orderNumber instead)
      omni.completeGuestCheckout(checkoutId).then(result => {
        console.log('Order created:', result.orderNumber);
      }).catch(() => {
        // Order may already exist (e.g., page refresh) - safe to ignore
      });
    }
  }, []);

  return (
    <div className="text-center py-12">
      <h1 className="text-2xl font-bold text-green-600">Payment Received!</h1>
      {/* ... rest of success page */}
    </div>
  );
}

How it works:

User Type Cart Type Behavior
Guest (partial checkout) Local cart Creates order + removes only purchased items
Guest (full checkout) Local cart Creates order + clears entire cart
Logged-in Server cart Creates order + clears cart via SDK state

Why is this needed?

  • completeGuestCheckout() sends POST /checkout/:id/complete which creates the order on the server
  • Without it, payment goes through Stripe but no order is created in the system
  • The server also links the order to the customer (by email) so it appears in their order history
  • For partial checkout (AliExpress-style), only the purchased items are removed

Customer Authentication

Register Customer

const auth = await omni.registerCustomer({
  email: 'customer@example.com',
  password: 'securepassword123',
  firstName: 'John',
  lastName: 'Doe',
});

// Check if email verification is required
if (auth.requiresVerification) {
  localStorage.setItem('verificationToken', auth.token);
  window.location.href = '/verify-email';
} else {
  setCustomerToken(auth.token);
  // Redirect back to store, not /account
  window.location.href = '/';
}

Login Customer

const auth = await omni.loginCustomer('customer@example.com', 'password123');
setCustomerToken(auth.token);

// Best practice: redirect back to previous page or home
const returnUrl = localStorage.getItem('returnUrl') || '/';
localStorage.removeItem('returnUrl');
window.location.href = returnUrl;

Best Practice: Before showing login page, save the current URL with localStorage.setItem('returnUrl', window.location.pathname). After login, redirect back to that URL. This is how Amazon, Shopify, and most e-commerce sites work.

Logout Customer

setCustomerToken(null);
window.location.href = '/'; // Return to store home

Get Customer Profile

restoreCustomerToken(); // Restore from localStorage
const profile = await omni.getMyProfile();

console.log(profile.firstName);
console.log(profile.email);
console.log(profile.addresses);

Get Customer Orders

const { data: orders, meta } = await omni.getMyOrders({
  page: 1,
  limit: 10,
});

Auth Response Type

interface CustomerAuthResponse {
  customer: {
    id: string;
    email: string;
    firstName?: string;
    lastName?: string;
    emailVerified: boolean;
  };
  token: string;
  expiresAt: string;
  requiresVerification?: boolean; // true if email verification is required
}

Email Verification

If the store has email verification enabled, customers must verify their email after registration before they can fully use their account.

Registration with Email Verification

When requiresVerification is true in the registration response, the customer needs to verify their email:

const auth = await omni.registerCustomer({
  email: 'customer@example.com',
  password: 'securepassword123',
  firstName: 'John',
});

if (auth.requiresVerification) {
  // Save token for verification step
  localStorage.setItem('verificationToken', auth.token);
  // Redirect to verification page
  window.location.href = '/verify-email';
} else {
  // No verification needed - redirect back to store
  setCustomerToken(auth.token);
  window.location.href = '/';
}

Verify Email with Code

After the customer receives the 6-digit code via email:

// Get the token saved from registration
const token = localStorage.getItem('verificationToken');

// Verify email - pass the token directly (no need to call setCustomerToken first!)
const result = await omni.verifyEmail(code, token);

if (result.verified) {
  // Email verified! Now set the token for normal use
  setCustomerToken(token);
  localStorage.removeItem('verificationToken');
  // Redirect back to store (or returnUrl if saved)
  const returnUrl = localStorage.getItem('returnUrl') || '/';
  localStorage.removeItem('returnUrl');
  window.location.href = returnUrl;
}

Resend Verification Email

If the customer didn't receive the email or the code expired:

const token = localStorage.getItem('verificationToken');
await omni.resendVerificationEmail(token);
// Show success message - new code sent

Note: Resend is rate-limited to 3 requests per hour.

Complete Email Verification Page Example

'use client';
import { useState } from 'react';
import { omni, setCustomerToken } from '@/lib/brainerce';
import { toast } from 'sonner';

export default function VerifyEmailPage() {
  const [code, setCode] = useState('');
  const [loading, setLoading] = useState(false);

  const handleVerify = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);

    try {
      const token = localStorage.getItem('verificationToken');
      if (!token) {
        toast.error('No verification token found. Please register again.');
        return;
      }

      const result = await omni.verifyEmail(code, token);

      if (result.verified) {
        toast.success('Email verified!');
        setCustomerToken(token);
        localStorage.removeItem('verificationToken');
        // Redirect back to store
        const returnUrl = localStorage.getItem('returnUrl') || '/';
        localStorage.removeItem('returnUrl');
        window.location.href = returnUrl;
      }
    } catch (error) {
      toast.error(error instanceof Error ? error.message : 'Verification failed');
    } finally {
      setLoading(false);
    }
  };

  const handleResend = async () => {
    try {
      const token = localStorage.getItem('verificationToken');
      if (!token) {
        toast.error('No verification token found');
        return;
      }
      await omni.resendVerificationEmail(token);
      toast.success('Verification code sent!');
    } catch (error) {
      toast.error(error instanceof Error ? error.message : 'Failed to resend');
    }
  };

  return (
    <div className="max-w-md mx-auto mt-12">
      <h1 className="text-2xl font-bold mb-4">Verify Your Email</h1>
      <p className="text-gray-600 mb-6">
        We sent a 6-digit code to your email. Enter it below to verify your account.
      </p>

      <form onSubmit={handleVerify} className="space-y-4">
        <input
          type="text"
          placeholder="Enter 6-digit code"
          value={code}
          onChange={(e) => setCode(e.target.value)}
          maxLength={6}
          className="w-full border p-3 rounded text-center text-2xl tracking-widest"
          required
        />
        <button
          type="submit"
          disabled={loading || code.length !== 6}
          className="w-full bg-black text-white py-3 rounded disabled:opacity-50"
        >
          {loading ? 'Verifying...' : 'Verify Email'}
        </button>
      </form>

      <button onClick={handleResend} className="mt-4 text-blue-600 text-sm">
        Didn't receive the code? Resend
      </button>
    </div>
  );
}

Social Login (OAuth)

Allow customers to sign in with Google, Facebook, or GitHub. The store owner configures which providers are available in their Brainerce admin panel.

Check Available Providers

// Returns only the providers the store owner has enabled
const { providers } = await omni.getAvailableOAuthProviders();
// providers = ['GOOGLE', 'FACEBOOK'] - varies by store configuration

OAuth Login Flow

Step 1: User clicks "Sign in with Google"

// Save cart ID before redirect (user will leave your site!)
const cartId = localStorage.getItem('cartId');
if (cartId) sessionStorage.setItem('pendingCartId', cartId);

// Get authorization URL
const { authorizationUrl, state } = await omni.getOAuthAuthorizeUrl('GOOGLE', {
  redirectUrl: window.location.origin + '/auth/callback', // Where Google sends them back
});

// Save state for verification (CSRF protection)
sessionStorage.setItem('oauthState', state);

// Redirect to Google
window.location.href = authorizationUrl;

Step 2: Create callback page (/auth/callback)

// pages/auth/callback.tsx or app/auth/callback/page.tsx
'use client';
import { useEffect, useState } from 'react';
import { useSearchParams } from 'next/navigation';
import { omni, setCustomerToken } from '@/lib/brainerce';

export default function AuthCallback() {
  const searchParams = useSearchParams();
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    async function handleCallback() {
      const code = searchParams.get('code');
      const state = searchParams.get('state');
      const errorParam = searchParams.get('error');

      // Check for OAuth errors (user cancelled, etc.)
      if (errorParam) {
        window.location.href = '/login?error=cancelled';
        return;
      }

      if (!code || !state) {
        setError('Missing OAuth parameters');
        return;
      }

      // Verify state matches (CSRF protection)
      const savedState = sessionStorage.getItem('oauthState');
      if (state !== savedState) {
        setError('Invalid state - please try again');
        return;
      }

      try {
        // Exchange code for customer token
        const { customer, token, isNewCustomer } = await omni.handleOAuthCallback(
          'GOOGLE',
          code,
          state
        );

        // Save the customer token
        setCustomerToken(token);
        sessionStorage.removeItem('oauthState');

        // Link any pending cart to the now-logged-in customer
        const pendingCartId = sessionStorage.getItem('pendingCartId');
        if (pendingCartId) {
          try {
            await omni.linkCart(pendingCartId);
          } catch {
            // Cart may have expired - that's ok
          }
          sessionStorage.removeItem('pendingCartId');
        }

        // Redirect to return URL or home
        const returnUrl = localStorage.getItem('returnUrl') || '/';
        localStorage.removeItem('returnUrl');
        window.location.href = returnUrl;
      } catch (err) {
        setError(err instanceof Error ? err.message : 'Login failed');
      }
    }

    handleCallback();
  }, [searchParams]);

  if (error) {
    return (
      <div className="max-w-md mx-auto mt-12 text-center">
        <h1 className="text-xl font-bold text-red-600">Login Failed</h1>
        <p className="mt-2 text-gray-600">{error}</p>
        <a href="/login" className="mt-4 inline-block text-blue-600">
          Try again
        </a>
      </div>
    );
  }

  return (
    <div className="max-w-md mx-auto mt-12 text-center">
      <div className="animate-spin h-8 w-8 border-4 border-blue-600 border-t-transparent rounded-full mx-auto"></div>
      <p className="mt-4 text-gray-600">Completing login...</p>
    </div>
  );
}

Login Page with Social Buttons

'use client';
import { useState, useEffect } from 'react';
import { omni, setCustomerToken } from '@/lib/brainerce';

export default function LoginPage() {
  const [providers, setProviders] = useState<string[]>([]);
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState('');

  // Load available OAuth providers
  useEffect(() => {
    omni.getAvailableOAuthProviders()
      .then(({ providers }) => setProviders(providers))
      .catch(() => {}); // OAuth not configured - that's ok
  }, []);

  // Social login handler
  const handleSocialLogin = async (provider: string) => {
    try {
      // Save cart ID before redirect
      const cartId = localStorage.getItem('cartId');
      if (cartId) sessionStorage.setItem('pendingCartId', cartId);

      const { authorizationUrl, state } = await omni.getOAuthAuthorizeUrl(
        provider as 'GOOGLE' | 'FACEBOOK' | 'GITHUB',
        { redirectUrl: window.location.origin + '/auth/callback' }
      );

      sessionStorage.setItem('oauthState', state);
      window.location.href = authorizationUrl;
    } catch (err) {
      setError('Failed to start login');
    }
  };

  // Regular email/password login
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);
    setError('');
    try {
      const auth = await omni.loginCustomer(email, password);
      setCustomerToken(auth.token);
      const returnUrl = localStorage.getItem('returnUrl') || '/';
      localStorage.removeItem('returnUrl');
      window.location.href = returnUrl;
    } catch (err) {
      setError('Invalid email or password');
    } finally {
      setLoading(false);
    }
  };

  return (
    <div className="max-w-md mx-auto mt-12">
      <h1 className="text-2xl font-bold mb-6">Login</h1>

      {/* Social Login Buttons */}
      {providers.length > 0 && (
        <div className="space-y-3 mb-6">
          {providers.includes('GOOGLE') && (
            <button
              onClick={() => handleSocialLogin('GOOGLE')}
              className="w-full flex items-center justify-center gap-2 border py-3 rounded hover:bg-gray-50"
            >
              <GoogleIcon />
              Continue with Google
            </button>
          )}
          {providers.includes('FACEBOOK') && (
            <button
              onClick={() => handleSocialLogin('FACEBOOK')}
              className="w-full flex items-center justify-center gap-2 bg-[#1877F2] text-white py-3 rounded"
            >
              <FacebookIcon />
              Continue with Facebook
            </button>
          )}
          {providers.includes('GITHUB') && (
            <button
              onClick={() => handleSocialLogin('GITHUB')}
              className="w-full flex items-center justify-center gap-2 bg-[#24292F] text-white py-3 rounded"
            >
              <GithubIcon />
              Continue with GitHub
            </button>
          )}
          <div className="relative my-4">
            <div className="absolute inset-0 flex items-center">
              <div className="w-full border-t" />
            </div>
            <div className="relative flex justify-center text-sm">
              <span className="px-2 bg-white text-gray-500">or</span>
            </div>
          </div>
        </div>
      )}

      {/* Email/Password Form */}
      {error && <div className="bg-red-100 text-red-600 p-3 rounded mb-4">{error}</div>}
      <form onSubmit={handleSubmit} className="space-y-4">
        <input
          type="email"
          placeholder="Email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          required
          className="w-full border p-2 rounded"
        />
        <input
          type="password"
          placeholder="Password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          required
          className="w-full border p-2 rounded"
        />
        <button
          type="submit"
          disabled={loading}
          className="w-full bg-black text-white py-3 rounded"
        >
          {loading ? 'Logging in...' : 'Login'}
        </button>
      </form>

      <p className="mt-4 text-center">
        Don't have an account? <a href="/register" className="text-blue-600">Register</a>
      </p>
    </div>
  );
}

// Simple SVG icons (or use lucide-react)
const GoogleIcon = () => (
  <svg className="w-5 h-5" viewBox="0 0 24 24">
    <path fill="#4285F4" d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"/>
    <path fill="#34A853" d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"/>
    <path fill="#FBBC05" d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"/>
    <path fill="#EA4335" d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"/>
  </svg>
);

const FacebookIcon = () => (
  <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
    <path d="M24 12.073c0-6.627-5.373-12-12-12s-12 5.373-12 12c0 5.99 4.388 10.954 10.125 11.854v-8.385H7.078v-3.47h3.047V9.43c0-3.007 1.792-4.669 4.533-4.669 1.312 0 2.686.235 2.686.235v2.953H15.83c-1.491 0-1.956.925-1.956 1.874v2.25h3.328l-.532 3.47h-2.796v8.385C19.612 23.027 24 18.062 24 12.073z"/>
  </svg>
);

const GithubIcon = () => (
  <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
    <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/>
  </svg>
);

Account Linking (Add Social Account to Existing User)

Logged-in customers can link additional social accounts to their profile:

// Get currently linked accounts
const connections = await omni.getOAuthConnections();
// [{ provider: 'GOOGLE', email: 'user@gmail.com', linkedAt: '...' }]

// Link a new provider (redirects to OAuth flow)
const { authorizationUrl } = await omni.linkOAuthProvider('GITHUB');
window.location.href = authorizationUrl;

// Unlink a provider
await omni.unlinkOAuthProvider('GOOGLE');

Cart Linking After OAuth Login

When a customer logs in via OAuth, their guest cart should be linked to their account:

// omni.linkCart() associates a guest cart with the logged-in customer
await omni.linkCart(cartId);

This is automatically handled in the callback example above.

OAuth Method Reference

Method Description
getAvailableOAuthProviders() Get list of enabled providers for this store
getOAuthAuthorizeUrl(provider, options?) Get URL to redirect user to OAuth provider
handleOAuthCallback(provider, code, state) Exchange OAuth code for customer token
linkOAuthProvider(provider) Link social account to current customer
unlinkOAuthProvider(provider) Remove linked social account
getOAuthConnections() Get list of linked social accounts
linkCart(cartId) Link guest cart to logged-in customer

Customer Addresses

Get Addresses

const addresses = await omni.getMyAddresses();

Add Address

const address = await omni.addMyAddress({
  firstName: 'John',
  lastName: 'Doe',
  line1: '123 Main St',
  city: 'New York',
  region: 'NY',
  postalCode: '10001',
  country: 'US',
  isDefault: true,
});

Update Address

const updated = await omni.updateMyAddress(addressId, {
  line1: '456 New Street',
});

Delete Address

await omni.deleteMyAddress(addressId);

Store Info

const store = await omni.getStoreInfo();

console.log(store.name); // Store name
console.log(store.currency); // 'USD', 'ILS', etc.
console.log(store.language); // 'en', 'he', etc.

Admin API Reference

The Admin API requires an API key (apiKey) and provides full access to store configuration and management features.

// Initialize in Admin mode
const omni = new BrainerceClient({
  apiKey: process.env.OMNI_API_KEY, // 'omni_*' prefix
});

Taxonomy Management

// Categories
const categories = await omni.listCategories({ page: 1, limit: 20 });
const category = await omni.getCategory('cat_id');
const newCategory = await omni.createCategory({ name: 'Electronics', slug: 'electronics' });
await omni.updateCategory('cat_id', { name: 'Updated Name' });
await omni.deleteCategory('cat_id');

// Brands
const brands = await omni.listBrands();
const brand = await omni.createBrand({ name: 'Nike', slug: 'nike' });

// Tags
const tags = await omni.listTags();
const tag = await omni.createTag({ name: 'Sale', slug: 'sale' });

// Attributes (for variant options)
const attributes = await omni.listAttributes();
const attribute = await omni.createAttribute({ name: 'Color', slug: 'color' });
const options = await omni.getAttributeOptions('attr_id');
await omni.createAttributeOption('attr_id', { value: 'Red', slug: 'red' });

Shipping Configuration

// Shipping Zones
const zones = await omni.listShippingZones();
const zone = await omni.createShippingZone({
  name: 'US Domestic',
  countries: ['US'],
});

// Shipping Rates
const rates = await omni.getZoneShippingRates('zone_id');
await omni.createZoneShippingRate('zone_id', {
  name: 'Standard Shipping',
  type: 'flat',
  price: 5.99,
  estimatedDays: '3-5',
});

Tax Configuration

const rates = await omni.getTaxRates();
await omni.createTaxRate({
  name: 'CA Sales Tax',
  rate: 7.25,
  country: 'US',
  region: 'CA',
});

Metafield Definitions

// Define custom fields
const definitions = await omni.getMetafieldDefinitions();
await omni.createMetafieldDefinition({
  name: 'Care Instructions',
  key: 'care_instructions',
  type: 'multi_line_text',
});

// Set values on products
await omni.setProductMetafield('prod_id', 'def_id', {
  value: 'Machine wash cold',
});

Store Team Management

Each store has its own team with roles (OWNER, MANAGER, STAFF, VIEWER) and granular permissions.

// List team members + pending invitations for a store
const { members, invitations } = await omni.getStoreTeam('store_id');

// Invite a new member
const invitation = await omni.inviteStoreMember('store_id', {
  email: 'newmember@example.com',
  role: 'MANAGER', // 'MANAGER' | 'STAFF' | 'VIEWER'
});

// Update member role or set custom permissions
await omni.updateStoreMember('store_id', 'member_id', { role: 'STAFF' });
await omni.updateStoreMember('store_id', 'member_id', {
  permissions: ['VIEW_PRODUCTS', 'VIEW_ORDERS', 'FULFILL_ORDERS'], // overrides role defaults
});

// Remove a member
await omni.removeStoreMember('store_id', 'member_id');

// Manage invitations
await omni.resendStoreInvitation('store_id', 'inv_id');
await omni.revokeStoreInvitation('store_id', 'inv_id');

// Get all stores accessible to the current user (owned + shared)
const stores = await omni.getMyStores();
// [{ id, name, role: 'OWNER', context: 'owner' }, { id, name, role: 'MANAGER', context: 'member' }]

// Get user's permissions for a specific store
const { role, permissions } = await omni.getMyStorePermissions('store_id');

Note: The previous account-level team methods (getTeamMembers, inviteTeamMember, etc.) are deprecated. Use the store-level methods above instead.

Email Settings & Templates

// Get/update settings
const settings = await omni.getEmailSettings();
await omni.updateEmailSettings({
  emailsEnabled: true,
  defaultFromName: 'My Store',
  eventSettings: {
    ORDER_CONFIRMATION: { enabled: true, sendToCustomer: true },
  },
});

// Manage templates
const templates = await omni.getEmailTemplates();
await omni.createEmailTemplate({
  name: 'Order Confirmation',
  eventType: 'ORDER_CONFIRMATION',
  subject: 'Your order #{{orderNumber}}',
  htmlContent: '<h1>Thank you!</h1>...',
});

// Preview template
const preview = await omni.previewEmailTemplate('template_id', {
  variables: { orderNumber: '1001' },
});

Sync Conflict Resolution

// Product sync conflicts
const conflicts = await omni.getSyncConflicts();
await omni.resolveSyncConflict('conflict_id', 'MERGE'); // or 'CREATE_NEW'

// Metafield conflicts
const metafieldConflicts = await omni.getMetafieldConflicts();
await omni.resolveMetafieldConflict('conflict_id', {
  resolution: 'USE_INCOMING', // 'KEEP_EXISTING' | 'USE_INCOMING' | 'MERGE'
});
await omni.ignoreMetafieldConflict('conflict_id');

OAuth Provider Configuration

// Configure social login for customers
const providers = await omni.getOAuthProviders();
await omni.configureOAuthProvider({
  provider: 'GOOGLE',
  clientId: 'your-google-client-id',
  clientSecret: 'your-google-client-secret',
  isEnabled: true,
});
await omni.updateOAuthProvider('GOOGLE', { isEnabled: false });
await omni.deleteOAuthProvider('GOOGLE');

Complete Page Examples

Home Page

'use client';
import { useEffect, useState } from 'react';
import { omni } from '@/lib/brainerce';
import type { Product } from 'brainerce';

export default function HomePage() {
  const [products, setProducts] = useState<Product[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    async function loadProducts() {
      try {
        const { data } = await omni.getProducts({ limit: 8 });
        setProducts(data);
      } catch (err) {
        setError('Failed to load products');
      } finally {
        setLoading(false);
      }
    }
    loadProducts();
  }, []);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>{error}</div>;

  return (
    <div className="grid grid-cols-2 md:grid-cols-4 gap-6">
      {products.map((product) => (
        <a key={product.id} href={`/products/${product.slug}`} className="group">
          <img
            src={product.images?.[0]?.url || '/placeholder.jpg'}
            alt={product.name}
            className="w-full aspect-square object-cover"
          />
          <h3 className="mt-2 font-medium">{product.name}</h3>
          <p className="text-lg">
            {product.salePrice ? (
              <>
                <span className="text-red-600">${product.salePrice}</span>
                <span className="line-through text-gray-400 ml-2">${product.basePrice}</span>
              </>
            ) : (
              <span>${product.basePrice}</span>
            )}
          </p>
        </a>
      ))}
    </div>
  );
}

Products List with Pagination

'use client';
import { useEffect, useState } from 'react';
import { omni } from '@/lib/brainerce';
import type { Product, PaginatedResponse } from 'brainerce';

export default function ProductsPage() {
  const [data, setData] = useState<PaginatedResponse<Product> | null>(null);
  const [page, setPage] = useState(1);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function load() {
      setLoading(true);
      try {
        const result = await omni.getProducts({ page, limit: 12 });
        setData(result);
      } finally {
        setLoading(false);
      }
    }
    load();
  }, [page]);

  if (loading) return <div>Loading...</div>;
  if (!data) return <div>No products found</div>;

  return (
    <div>
      <div className="grid grid-cols-3 gap-6">
        {data.data.map((product) => (
          <a key={product.id} href={`/products/${product.slug}`}>
            <img src={product.images?.[0]?.url} alt={product.name} />
            <h3>{product.name}</h3>
            <p>${product.salePrice || product.basePrice}</p>
          </a>
        ))}
      </div>

      {/* Pagination */}
      <div className="flex gap-2 mt-8">
        <button onClick={() => setPage(p => Math.max(1, p - 1))} disabled={page === 1}>
          Previous
        </button>
        <span>Page {data.meta.page} of {data.meta.totalPages}</span>
        <button onClick={() => setPage(p => p + 1)} disabled={page >= data.meta.totalPages}>
          Next
        </button>
      </div>
    </div>
  );
}

Product Detail with Add to Cart (Local Cart)

'use client';
import { useEffect, useState } from 'react';
import { omni } from '@/lib/brainerce';
import { isHtmlDescription, getVariantPrice, getVariantOptions, formatPrice } from 'brainerce';
import type { Product, ProductVariant, StoreInfo } from 'brainerce';

// Route: /products/[slug]/page.tsx - uses URL-friendly slug instead of ID
export default function ProductPage({ params }: { params: { slug: string } }) {
  const [product, setProduct] = useState<Product | null>(null);
  const [selectedVariant, setSelectedVariant] = useState<ProductVariant | null>(null);
  const [storeInfo, setStoreInfo] = useState<StoreInfo | null>(null);
  const [quantity, setQuantity] = useState(1);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function load() {
      try {
        const [p, info] = await Promise.all([
          omni.getProductBySlug(params.slug),
          omni.getStoreInfo(),
        ]);
        setProduct(p);
        setStoreInfo(info);
        // Auto-select first variant for VARIABLE products
        if (p.type === 'VARIABLE' && p.variants && p.variants.length > 0) {
          setSelectedVariant(p.variants[0]);
        }
      } finally {
        setLoading(false);
      }
    }
    load();
  }, [params.slug]);

  // Get the image to display (variant image takes priority)
  const getDisplayImage = () => {
    // Use variant-specific image if available
    if (selectedVariant?.image) {
      const img = selectedVariant.image;
      return typeof img === 'string' ? img : img.url;
    }
    // Fall back to product's main image
    return product?.images?.[0]?.url || '/placeholder.jpg';
  };

  // Get the price to display (variant price takes priority)
  const getDisplayPrice = () => {
    if (!product) return '0';
    if (selectedVariant) {
      return getVariantPrice(selectedVariant, product.basePrice).toString();
    }
    return product.salePrice || product.basePrice;
  };

  const handleAddToCart = () => {
    if (!product) return;

    // Add to local cart (NO API call!)
    omni.addToLocalCart({
      productId: product.id,
      variantId: selectedVariant?.id,
      quantity,
      name: selectedVariant?.name
        ? `${product.name} - ${selectedVariant.name}`
        : product.name,
      price: getDisplayPrice(),
      image: getDisplayImage(),
    });

    alert('Added to cart!');
  };

  if (loading) return <div>Loading...</div>;
  if (!product) return <div>Product not found</div>;

  return (
    <div className="grid grid-cols-2 gap-8">
      {/* Images - updates when variant changes */}
      <div>
        <img
          src={getDisplayImage()}
          alt={product.name}
          className="w-full"
        />
      </div>

      {/* Details */}
      <div>
        <h1 className="text-3xl font-bold">{product.name}</h1>
        {/* Price updates based on selected variant */}
        <p className="text-2xl mt-4">
          {formatPrice(getDisplayPrice(), { currency: storeInfo?.currency || 'USD' })}
        </p>

        {/* IMPORTANT: Use isHtmlDescription() to render HTML descriptions correctly */}
        {product.description && (
          isHtmlDescription(product) ? (
            <div className="mt-4 text-gray-600" dangerouslySetInnerHTML={{ __html: product.description }} />
          ) : (
            <p className="mt-4 text-gray-600">{product.description}</p>
          )
        )}

        {/* Variant Selection - shows attribute-based buttons */}
        {product.type === 'VARIABLE' && product.variants && product.variants.length > 0 && (
          <div className="mt-6">
            {/* Extract unique attribute names from all variants */}
            {(() => {
              const allOptions = product.variants.map(v => getVariantOptions(v));
              const attributeNames = [...new Set(allOptions.flatMap(opts => opts.map(o => o.name)))];

              return attributeNames.map(attrName => {
                const uniqueValues = [...new Set(
                  allOptions.flatMap(opts => opts.filter(o => o.name === attrName).map(o => o.value))
                )];
                const currentValue = getVariantOptions(selectedVariant).find(o => o.name === attrName)?.value;

                return (
                  <div key={attrName} className="mb-4">
                    <label className="block font-medium mb-2">
                      {attrName}: {currentValue}
                    </label>
                    <div className="flex gap-2">
                      {uniqueValues.map(value => (
                        <button
                          key={value}
                          onClick={() => {
                            // Find variant matching the selected attribute value
                            const match = product.variants?.find(v => {
                              const opts = getVariantOptions(v);
                              return opts.some(o => o.name === attrName && o.value === value);
                            });
                            if (match) setSelectedVariant(match);
                          }}
                          className={`px-4 py-2 border rounded ${
                            currentValue === value
                              ? 'bg-black text-white border-black'
                              : 'bg-white text-black border-gray-300 hover:border-black'
                          }`}
                        >
                          {value}
                        </button>
                      ))}
                    </div>
                  </div>
                );
              });
            })()}
          </div>
        )}

        {/* Quantity */}
        <div className="mt-4">
          <label className="block font-medium mb-2">Quantity</label>
          <input
            type="number"
            min="1"
            value={quantity}
            onChange={(e) => setQuantity(Number(e.target.value))}
            className="border rounded p-2 w-20"
          />
        </div>

        {/* Add to Cart Button */}
        <button
          onClick={handleAddToCart}
          disabled={adding}
          className="mt-6 w-full bg-black text-white py-3 rounded disabled:opacity-50"
        >
          {adding ? 'Adding...' : 'Add to Cart'}
        </button>

        {/* Stock Status - use inStock which handles UNLIMITED variants */}
        {product.inventory && (
          <p className="mt-4 text-sm">
            {product.inventory.inStock
              ? (product.inventory.trackingMode === 'UNLIMITED'
                  ? 'In Stock'
                  : `${product.inventory.available} in stock`)
              : 'Out of stock'}
          </p>
        )}
      </div>
    </div>
  );
}

Cart Page (Local Cart)

'use client';
import { useState, useEffect } from 'react';
import { omni } from '@/lib/brainerce';
import type { LocalCart } from 'brainerce';

export default function CartPage() {
  // ⚠️ Do NOT use useState(omni.getLocalCart()) — causes hydration mismatch!
  // Server has no localStorage (empty cart) but client does (cart with items).
  const [cart, setCart] = useState<LocalCart>({ items: [], updatedAt: '' });

  useEffect(() => {
    setCart(omni.getLocalCart());
  }, []);

  const updateQuantity = (productId: string, quantity: number, variantId?: string) => {
    const updated = omni.updateLocalCartItem(productId, quantity, variantId);
    setCart(updated);
  };

  const removeItem = (productId: string, variantId?: string) => {
    const updated = omni.removeFromLocalCart(productId, variantId);
    setCart(updated);
  };

  // Calculate subtotal from local cart
  const subtotal = cart.items.reduce((sum, item) => {
    return sum + (parseFloat(item.price || '0') * item.quantity);
  }, 0);

  if (cart.items.length === 0) {
    return (
      <div className="text-center py-12">
        <h1 className="text-2xl font-bold">Your cart is empty</h1>
        <a href="/products" className="text-blue-600 mt-4 inline-block">Continue Shopping</a>
      </div>
    );
  }

  return (
    <div>
      <h1 className="text-2xl font-bold mb-6">Shopping Cart</h1>

      {cart.items.map((item) => (
        <div key={`${item.productId}-${item.variantId || ''}`} className="flex items-center gap-4 py-4 border-b">
          <img
            src={item.image || '/placeholder.jpg'}
            alt={item.name || 'Product'}
            className="w-20 h-20 object-cover"
          />
          <div className="flex-1">
            <h3 className="font-medium">{item.name || 'Product'}</h3>
            <p className="font-bold">${item.price}</p>
          </div>
          <div className="flex items-center gap-2">
            <button
              onClick={() => updateQuantity(item.productId, item.quantity - 1, item.variantId)}
              className="w-8 h-8 border rounded"
            >-</button>
            <span className="w-8 text-center">{item.quantity}</span>
            <button
              onClick={() => updateQuantity(item.productId, item.quantity + 1, item.variantId)}
              className="w-8 h-8 border rounded"
            >+</button>
          </div>
          <button
            onClick={() => removeItem(item.productId, item.variantId)}
            className="text-red-600"
          >Remove</button>
        </div>
      ))}

      <div className="mt-6 text-right">
        <p className="text-xl">Subtotal: <strong>${subtotal.toFixed(2)}</strong></p>
        {cart.couponCode && (
          <p className="text-green-600">Coupon applied: {cart.couponCode}</p>
        )}
        <a
          href="/checkout"
          className="mt-4 inline-block bg-black text-white px-8 py-3 rounded"
        >
          Proceed to Checkout
        </a>
      </div>
    </div>
  );
}

Universal Checkout (Handles Both Guest & Logged-In)

RECOMMENDED: Use this pattern to properly handle both guest and logged-in customers in a single checkout page.

'use client';
import { useState, useEffect } from 'react';
import { omni, isLoggedIn, getServerCartId, setServerCartId, restoreCustomerToken } from '@/lib/brainerce';

export default function CheckoutPage() {
  const [loading, setLoading] = useState(true);
  const [submitting, setSubmitting] = useState(false);
  const [customerLoggedIn, setCustomerLoggedIn] = useState(false);

  // Form state
  const [email, setEmail] = useState('');
  const [shippingAddress, setShippingAddress] = useState({
    firstName: '', lastName: '', line1: '', city: '', postalCode: '', country: 'US'
  });

  // Server checkout state (for logged-in customers)
  const [checkoutId, setCheckoutId] = useState<string | null>(null);
  const [shippingRates, setShippingRates] = useState<any[]>([]);
  const [selectedRate, setSelectedRate] = useState<string | null>(null);

  useEffect(() => {
    restoreCustomerToken();
    const loggedIn = isLoggedIn();
    setCustomerLoggedIn(loggedIn);

    async function initCheckout() {
      if (loggedIn) {
        // Logged-in customer: Create server cart + checkout
        let cartId = getServerCartId();

        if (!cartId) {
          // Create new cart (auto-linked to customer)
          const cart = await omni.createCart();
          cartId = cart.id;
          setServerCartId(cartId);

          // Migrate local cart items to server cart
          const localCart = omni.getLocalCart();
          for (const item of localCart.items) {
            await omni.addToCart(cartId, {
              productId: item.productId,
              variantId: item.variantId,
              quantity: item.quantity,
            });
          }
          omni.clearLocalCart(); // Clear local cart after migration
        }

        // Create checkout from server cart
        const checkout = await omni.createCheckout({ cartId });
        setCheckoutId(checkout.id);

        // Pre-fill from customer profile if available
        try {
          const profile = await omni.getMyOrders({ limit: 1 }); // Just to check auth works
        } catch (e) {
          console.log('Could not fetch profile');
        }
      }
      setLoading(false);
    }

    initCheckout();
  }, []);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setSubmitting(true);

    try {
      if (customerLoggedIn && checkoutId) {
        // ===== LOGGED-IN CUSTOMER: Server Checkout =====

        // 1. Set customer info (REQUIRED - even for logged-in customers!)
        await omni.setCheckoutCustomer(checkoutId, {
          email: email, // Get from form or customer profile
          firstName: shippingAddress.firstName,
          lastName: shippingAddress.lastName,
        });

        // 2. Set shipping address
        await omni.setShippingAddress(checkoutId, shippingAddress);

        // 3. Get and select shipping rate
        const rates = await omni.getShippingRates(checkoutId);
        if (rates.length > 0) {
          await omni.selectShippingMethod(checkoutId, selectedRate || rates[0].id);
        }

        // 4. Complete checkout - ORDER IS LINKED TO CUSTOMER!
        const { orderId } = await omni.completeCheckout(checkoutId);

        // Clear cart ID
        localStorage.removeItem('cartId');

        // Redirect to success page
        window.location.href = `/order-success?orderId=${orderId}`;

      } else {
        // ===== GUEST: Local Cart + submitGuestOrder =====

        // Set customer and shipping info on local cart
        omni.setLocalCartCustomer({ email });
        omni.setLocalCartShippingAddress(shippingAddress);

        // Submit guest order (single API call)
        const order = await omni.submitGuestOrder();

        // Redirect to success page
        window.location.href = `/order-success?orderId=${order.orderId}`;
      }
    } catch (error) {
      console.error('Checkout failed:', error);
      alert('Checkout failed. Please try again.');
    } finally {
      setSubmitting(false);
    }
  };

  if (loading) return <div>Loading checkout...</div>;

  return (
    <form onSubmit={handleSubmit}>
      {/* Show email field only for guests */}
      {!customerLoggedIn && (
        <input
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          placeholder="Email"
          required
        />
      )}

      {/* Shipping address fields */}
      <input value={shippingAddress.firstName} onChange={(e) => setShippingAddress({...shippingAddress, firstName: e.target.value})} placeholder="First Name" required />
      <input value={shippingAddress.lastName} onChange={(e) => setShippingAddress({...shippingAddress, lastName: e.target.value})} placeholder="Last Name" required />
      <input value={shippingAddress.line1} onChange={(e) => setShippingAddress({...shippingAddress, line1: e.target.value})} placeholder="Address" required />
      <input value={shippingAddress.city} onChange={(e) => setShippingAddress({...shippingAddress, city: e.target.value})} placeholder="City" required />
      <input value={shippingAddress.postalCode} onChange={(e) => setShippingAddress({...shippingAddress, postalCode: e.target.value})} placeholder="Postal Code" required />

      {/* Shipping rates (for logged-in customers) */}
      {customerLoggedIn && shippingRates.length > 0 && (
        <select value={selectedRate || ''} onChange={(e) => setSelectedRate(e.target.value)}>
          {shippingRates.map((rate) => (
            <option key={rate.id} value={rate.id}>
              {rate.name} - ${rate.price}
            </option>
          ))}
        </select>
      )}

      <button type="submit" disabled={submitting}>
        {submitting ? 'Processing...' : 'Place Order'}
      </button>

      {customerLoggedIn && (
        <p className="text-sm text-green-600">
          ✓ Logged in - Order will be saved to your account
        </p>
      )}
    </form>
  );
}

Key Points:

  • isLoggedIn() determines which flow to use
  • Logged-in customers use createCart()createCheckout()completeCheckout()
  • Guests use local cart + submitGuestOrder()
  • Local cart items are migrated to server cart when customer logs in

Guest Checkout (Single API Call)

This checkout is for guest users only. All cart data is in localStorage, and we submit it in one API call.

⚠️ WARNING: Do NOT use this for logged-in customers! Use the Universal Checkout pattern above instead.

'use client';
import { useState, useEffect } from 'react';
import { omni } from '@/lib/brainerce';
import type { LocalCart, GuestOrderResponse } from 'brainerce';

type Step = 'info' | 'review' | 'complete';

export default function CheckoutPage() {
  // ⚠️ Do NOT use useState(omni.getLocalCart()) — causes hydration mismatch!
  const [cart, setCart] = useState<LocalCart>({ items: [], updatedAt: '' });
  const [step, setStep] = useState<Step>('info');
  const [order, setOrder] = useState<GuestOrderResponse | null>(null);
  const [submitting, setSubmitting] = useState(false);
  const [error, setError] = useState('');

  // Form state
  const [email, setEmail] = useState('');
  const [firstName, setFirstName] = useState('');
  const [lastName, setLastName] = useState('');
  const [address, setAddress] = useState('');
  const [city, setCity] = useState('');
  const [postalCode, setPostalCode] = useState('');
  const [country, setCountry] = useState('US');

  // Load cart from localStorage after hydration
  useEffect(() => {
    const localCart = omni.getLocalCart();
    setCart(localCart);
    if (localCart.customer?.email) setEmail(localCart.customer.email);
    if (localCart.customer?.firstName) setFirstName(localCart.customer.firstName);
    if (localCart.customer?.lastName) setLastName(localCart.customer.lastName);
    if (localCart.shippingAddress?.line1) setAddress(localCart.shippingAddress.line1);
    if (localCart.shippingAddress?.city) setCity(localCart.shippingAddress.city);
    if (localCart.shippingAddress?.postalCode) setPostalCode(localCart.shippingAddress.postalCode);
    if (localCart.shippingAddress?.country) setCountry(localCart.shippingAddress.country);
  }, []);

  // Calculate subtotal
  const subtotal = cart.items.reduce((sum, item) => {
    return sum + (parseFloat(item.price || '0') * item.quantity);
  }, 0);

  // Redirect if cart is empty
  useEffect(() => {
    if (cart.items.length === 0 && step !== 'complete') {
      window.location.href = '/cart';
    }
  }, [cart.items.length, step]);

  const handleInfoSubmit = (e: React.FormEvent) => {
    e.preventDefault();

    // Save to local cart
    omni.setLocalCartCustomer({ email, firstName, lastName });
    omni.setLocalCartShippingAddress({
      firstName,
      lastName,
      line1: address,
      city,
      postalCode,
      country,
    });

    setStep('review');
  };

  const handlePlaceOrder = async () => {
    setSubmitting(true);
    setError('');

    try {
      // Single API call to create order!
      const result = await omni.submitGuestOrder();
      setOrder(result);
      setStep('complete');
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Failed to place order');
    } finally {
      setSubmitting(false);
    }
  };

  if (step === 'complete' && order) {
    return (
      <div className="text-center py-12">
        <h1 className="text-3xl font-bold text-green-600">Order Complete!</h1>
        <p className="mt-4">Order Number: <strong>{order.orderNumber}</strong></p>
        <p className="mt-2">Total: <strong>${order.total.toFixed(2)}</strong></p>
        <p className="mt-4 text-gray-600">A confirmation email will be sent to {email}</p>
        <a href="/" className="mt-6 inline-block text-blue-600">Continue Shopping</a>
      </div>
    );
  }

  return (
    <div className="max-w-2xl mx-auto">
      <h1 className="text-2xl font-bold mb-6">Checkout</h1>

      {error && (
        <div className="bg-red-100 text-red-600 p-3 rounded mb-4">{error}</div>
      )}

      {step === 'info' && (
        <form onSubmit={handleInfoSubmit} className="space-y-4">
          <h2 className="text-lg font-bold">Contact Information</h2>
          <input
            type="email"
            placeholder="Email"
            value={email}
            onChange={e => setEmail(e.target.value)}
            required
            className="w-full border p-2 rounded"
          />

          <h2 className="text-lg font-bold mt-6">Shipping Address</h2>
          <div className="grid grid-cols-2 gap-4">
            <input placeholder="First Name" value={firstName} onChange={e => setFirstName(e.target.value)} required className="border p-2 rounded" />
            <input placeholder="Last Name" value={lastName} onChange={e => setLastName(e.target.value)} required className="border p-2 rounded" />
          </div>
          <input placeholder="Address" value={address} onChange={e => setAddress(e.target.value)} required className="w-full border p-2 rounded" />
          <div className="grid grid-cols-2 gap-4">
            <input placeholder="City" value={city} onChange={e => setCity(e.target.value)} required className="border p-2 rounded" />
            <input placeholder="Postal Code" value={postalCode} onChange={e => setPostalCode(e.target.value)} required className="border p-2 rounded" />
          </div>
          <select value={country} onChange={e => setCountry(e.target.value)} className="w-full border p-2 rounded">
            <option value="US">United States</option>
            <option value="IL">Israel</option>
            <option value="GB">United Kingdom</option>
          </select>

          <button type="submit" className="w-full bg-black text-white py-3 rounded">
            Review Order
          </button>
        </form>
      )}

      {step === 'review' && (
        <div className="space-y-6">
          {/* Order Summary */}
          <div className="border p-4 rounded">
            <h3 className="font-bold mb-4">Order Summary</h3>
            {cart.items.map((item) => (
              <div key={`${item.productId}-${item.variantId || ''}`} className="flex justify-between py-2">
                <span>{item.name} x {item.quantity}</span>
                <span>${(parseFloat(item.price || '0') * item.quantity).toFixed(2)}</span>
              </div>
            ))}
            <hr className="my-2" />
            <div className="flex justify-between font-bold">
              <span>Total</span>
              <span>${subtotal.toFixed(2)}</span>
            </div>
          </div>

          {/* Shipping Info */}
          <div className="border p-4 rounded">
            <h3 className="font-bold mb-2">Shipping To</h3>
            <p>{firstName} {lastName}</p>
            <p>{address}</p>
            <p>{city}, {postalCode}, {country}</p>
            <button onClick={() => setStep('info')} className="text-blue-600 text-sm mt-2">Edit</button>
          </div>

          <button
            onClick={handlePlaceOrder}
            disabled={submitting}
            className="w-full bg-green-600 text-white py-3 rounded text-lg"
          >
            {submitting ? 'Processing...' : 'Place Order'}
          </button>
        </div>
      )}
    </div>
  );
}

Multi-Step Checkout (Server Cart - For Logged-In Customers Only)

IMPORTANT: This checkout pattern is ONLY for logged-in customers. For a checkout page that handles both guests and logged-in customers, see the "Universal Checkout" example above.

For logged-in users with server-side cart - orders will be linked to their account:

'use client';
import { useEffect, useState } from 'react';
import { omni, getServerCartId } from '@/lib/brainerce';
import type { Checkout, ShippingRate } from 'brainerce';

type Step = 'customer' | 'shipping' | 'payment' | 'complete';

export default function CheckoutPage() {
  const [checkout, setCheckout] = useState<Checkout | null>(null);
  const [step, setStep] = useState<Step>('customer');
  const [shippingRates, setShippingRates] = useState<ShippingRate[]>([]);
  const [loading, setLoading] = useState(true);
  const [submitting, setSubmitting] = useState(false);

  // Form state
  const [email, setEmail] = useState('');
  const [firstName, setFirstName] = useState('');
  const [lastName, setLastName] = useState('');
  const [address, setAddress] = useState('');
  const [city, setCity] = useState('');
  const [postalCode, setPostalCode] = useState('');
  const [country, setCountry] = useState('US');

  useEffect(() => {
    async function initCheckout() {
      const cartId = getServerCartId();
      if (!cartId) {
        window.location.href = '/cart';
        return;
      }
      try {
        const c = await omni.createCheckout({ cartId });
        setCheckout(c);
      } finally {
        setLoading(false);
      }
    }
    initCheckout();
  }, []);

  const handleCustomerSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!checkout) return;
    setSubmitting(true);
    try {
      await omni.setCheckoutCustomer(checkout.id, { email, firstName, lastName });
      setStep('shipping');
    } finally {
      setSubmitting(false);
    }
  };

  const handleShippingSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!checkout) return;
    setSubmitting(true);
    try {
      const { rates } = await omni.setShippingAddress(checkout.id, {
        firstName, lastName,
        line1: address,
        city, postalCode, country,
      });
      setShippingRates(rates);
      if (rates.length > 0) {
        await omni.selectShippingMethod(checkout.id, rates[0].id);
      }
      setStep('payment');
    } finally {
      setSubmitting(false);
    }
  };

  const handleCompleteOrder = async () => {
    if (!checkout) return;
    setSubmitting(true);
    try {
      const { orderId } = await omni.completeCheckout(checkout.id);
      setStep('complete');
    } catch (err) {
      alert('Failed to complete order');
    } finally {
      setSubmitting(false);
    }
  };

  if (loading) return <div>Loading checkout...</div>;
  if (!checkout) return <div>Failed to create checkout</div>;

  if (step === 'complete') {
    return (
      <div className="text-center py-12">
        <h1 className="text-3xl font-bold text-green-600">Order Complete!</h1>
        <p className="mt-4">Thank you for your purchase.</p>
        <a href="/" className="mt-6 inline-block text-blue-600">Continue Shopping</a>
      </div>
    );
  }

  return (
    <div className="max-w-2xl mx-auto">
      <h1 className="text-2xl font-bold mb-6">Checkout</h1>

      {step === 'customer' && (
        <form onSubmit={handleCustomerSubmit} className="space-y-4">
          <input type="email" placeholder="Email" value={email} onChange={e => setEmail(e.target.value)} required className="w-full border p-2 rounded" />
          <div className="grid grid-cols-2 gap-4">
            <input placeholder="First Name" value={firstName} onChange={e => setFirstName(e.target.value)} required className="border p-2 rounded" />
            <input placeholder="Last Name" value={lastName} onChange={e => setLastName(e.target.value)} required className="border p-2 rounded" />
          </div>
          <button type="submit" disabled={submitting} className="w-full bg-black text-white py-3 rounded">
            {submitting ? 'Saving...' : 'Continue to Shipping'}
          </button>
        </form>
      )}

      {step === 'shipping' && (
        <form onSubmit={handleShippingSubmit} className="space-y-4">
          <input placeholder="Address" value={address} onChange={e => setAddress(e.target.value)} required className="w-full border p-2 rounded" />
          <div className="grid grid-cols-2 gap-4">
            <input placeholder="City" value={city} onChange={e => setCity(e.target.value)} required className="border p-2 rounded" />
            <input placeholder="Postal Code" value={postalCode} onChange={e => setPostalCode(e.target.value)} required className="border p-2 rounded" />
          </div>
          <select value={country} onChange={e => setCountry(e.target.value)} className="w-full border p-2 rounded">
            <option value="US">United States</option>
            <option value="IL">Israel</option>
            <option value="GB">United Kingdom</option>
          </select>
          <button type="submit" disabled={submitting} className="w-full bg-black text-white py-3 rounded">
            {submitting ? 'Calculating Shipping...' : 'Continue to Payment'}
          </button>
        </form>
      )}

      {step === 'payment' && (
        <div className="space-y-6">
          <div className="border p-4 rounded">
            <h3 className="font-bold mb-2">Order Summary</h3>
            <p>Subtotal: ${checkout.subtotal}</p>
            <p>Shipping: ${checkout.shippingAmount}</p>
            <p className="text-xl font-bold mt-2">Total: ${checkout.total}</p>
          </div>
          <button onClick={handleCompleteOrder} disabled={submitting} className="w-full bg-green-600 text-white py-3 rounded text-lg">
            {submitting ? 'Processing...' : 'Complete Order'}
          </button>
        </div>
      )}
    </div>
  );
}

Login Page

'use client';
import { useState, useEffect } from 'react';
import { omni, setCustomerToken } from '@/lib/brainerce';

export default function LoginPage() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState('');
  const [loading, setLoading] = useState(false);

  // Save the page user came from (for redirect after login)
  useEffect(() => {
    const referrer = document.referrer;
    if (referrer && !referrer.includes('/login') && !referrer.includes('/register')) {
      const url = new URL(referrer);
      localStorage.setItem('returnUrl', url.pathname);
    }
  }, []);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);
    setError('');
    try {
      const auth = await omni.loginCustomer(email, password);
      setCustomerToken(auth.token);

      // Redirect back to previous page or home (like Amazon/Shopify do)
      const returnUrl = localStorage.getItem('returnUrl') || '/';
      localStorage.removeItem('returnUrl');
      window.location.href = returnUrl;
    } catch (err) {
      setError('Invalid email or password');
    } finally {
      setLoading(false);
    }
  };

  return (
    <div className="max-w-md mx-auto mt-12">
      <h1 className="text-2xl font-bold mb-6">Login</h1>
      {error && <div className="bg-red-100 text-red-600 p-3 rounded mb-4">{error}</div>}
      <form onSubmit={handleSubmit} className="space-y-4">
        <input type="email" placeholder="Email" value={email} onChange={e => setEmail(e.target.value)} required className="w-full border p-2 rounded" />
        <input type="password" placeholder="Password" value={password} onChange={e => setPassword(e.target.value)} required className="w-full border p-2 rounded" />
        <button type="submit" disabled={loading} className="w-full bg-black text-white py-3 rounded">
          {loading ? 'Logging in...' : 'Login'}
        </button>
      </form>
      <p className="mt-4 text-center">
        Don't have an account? <a href="/register" className="text-blue-600">Register</a>
      </p>
    </div>
  );
}

Register Page

'use client';
import { useState, useEffect } from 'react';
import { omni, setCustomerToken } from '@/lib/brainerce';

export default function RegisterPage() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [firstName, setFirstName] = useState('');
  const [lastName, setLastName] = useState('');
  const [error, setError] = useState('');
  const [loading, setLoading] = useState(false);

  // Save the page user came from (for redirect after registration)
  useEffect(() => {
    const referrer = document.referrer;
    if (referrer && !referrer.includes('/login') && !referrer.includes('/register')) {
      const url = new URL(referrer);
      localStorage.setItem('returnUrl', url.pathname);
    }
  }, []);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);
    setError('');
    try {
      const auth = await omni.registerCustomer({ email, password, firstName, lastName });

      // Check if email verification is required
      if (auth.requiresVerification) {
        // Save token for verification step
        localStorage.setItem('verificationToken', auth.token);
        window.location.href = '/verify-email';
      } else {
        // No verification needed - redirect back to store (like Amazon/Shopify)
        setCustomerToken(auth.token);
        const returnUrl = localStorage.getItem('returnUrl') || '/';
        localStorage.removeItem('returnUrl');
        window.location.href = returnUrl;
      }
    } catch (err) {
      setError('Registration failed. Email may already be in use.');
    } finally {
      setLoading(false);
    }
  };

  return (
    <div className="max-w-md mx-auto mt-12">
      <h1 className="text-2xl font-bold mb-6">Create Account</h1>
      {error && <div className="bg-red-100 text-red-600 p-3 rounded mb-4">{error}</div>}
      <form onSubmit={handleSubmit} className="space-y-4">
        <div className="grid grid-cols-2 gap-4">
          <input placeholder="First Name" value={firstName} onChange={e => setFirstName(e.target.value)} required className="border p-2 rounded" />
          <input placeholder="Last Name" value={lastName} onChange={e => setLastName(e.target.value)} required className="border p-2 rounded" />
        </div>
        <input type="email" placeholder="Email" value={email} onChange={e => setEmail(e.target.value)} required className="w-full border p-2 rounded" />
        <input type="password" placeholder="Password (min 8 characters)" value={password} onChange={e => setPassword(e.target.value)} required minLength={8} className="w-full border p-2 rounded" />
        <button type="submit" disabled={loading} className="w-full bg-black text-white py-3 rounded">
          {loading ? 'Creating Account...' : 'Create Account'}
        </button>
      </form>
      <p className="mt-4 text-center">
        Already have an account? <a href="/login" className="text-blue-600">Login</a>
      </p>
    </div>
  );
}

Account Page

'use client';
import { useEffect, useState } from 'react';
import { omni, restoreCustomerToken, setCustomerToken, isLoggedIn } from '@/lib/brainerce';
import type { CustomerProfile, Order } from 'brainerce';

export default function AccountPage() {
  const [profile, setProfile] = useState<CustomerProfile | null>(null);
  const [orders, setOrders] = useState<Order[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    restoreCustomerToken();
    if (!isLoggedIn()) {
      window.location.href = '/login';
      return;
    }

    async function load() {
      try {
        const [p, o] = await Promise.all([
          omni.getMyProfile(),
          omni.getMyOrders({ limit: 10 }),
        ]);
        setProfile(p);
        setOrders(o.data);
      } finally {
        setLoading(false);
      }
    }
    load();
  }, []);

  const handleLogout = () => {
    setCustomerToken(null);
    window.location.href = '/';
  };

  if (loading) return <div>Loading...</div>;
  if (!profile) return <div>Please log in</div>;

  return (
    <div>
      <div className="flex justify-between items-center mb-8">
        <h1 className="text-2xl font-bold">My Account</h1>
        <button onClick={handleLogout} className="text-red-600">Logout</button>
      </div>

      <div className="grid md:grid-cols-2 gap-8">
        <div className="border rounded p-6">
          <h2 className="text-xl font-bold mb-4">Profile</h2>
          <p><strong>Name:</strong> {profile.firstName} {profile.lastName}</p>
          <p><strong>Email:</strong> {profile.email}</p>
        </div>

        <div className="border rounded p-6">
          <h2 className="text-xl font-bold mb-4">Recent Orders</h2>
          {orders.length === 0 ? (
            <p className="text-gray-500">No orders yet</p>
          ) : (
            <div className="space-y-4">
              {orders.map((order) => (
                <div key={order.id} className="border-b pb-4">
                  <span className="font-medium">#{order.id.slice(-8)}</span>
                  <span className="ml-2 text-sm">{order.status}</span>
                  <p className="font-bold">${order.totalAmount}</p>
                </div>
              ))}
            </div>
          )}
        </div>
      </div>
    </div>
  );
}

Header Component with Cart Count (Local Cart)

'use client';
import { useState, useEffect } from 'react';
import { omni, isLoggedIn } from '@/lib/brainerce';

export function Header() {
  const [cartCount, setCartCount] = useState(0);
  const [loggedIn, setLoggedIn] = useState(false);

  useEffect(() => {
    setLoggedIn(isLoggedIn());
    // Get cart count from local storage (NO API call!)
    setCartCount(omni.getLocalCartItemCount());
  }, []);

  return (
    <header className="flex justify-between items-center p-4 border-b">
      <a href="/" className="text-xl font-bold">Store Name</a>
      <nav className="flex gap-6 items-center">
        <a href="/products">Shop</a>
        <a href="/cart" className="relative">
          Cart
          {cartCount > 0 && (
            <span className="absolute -top-2 -right-2 bg-red-600 text-white text-xs w-5 h-5 rounded-full flex items-center justify-center">
              {cartCount}
            </span>
          )}
        </a>
        {loggedIn ? (
          <a href="/account">Account</a>
        ) : (
          <a href="/login">Login</a>
        )}
      </nav>
    </header>
  );
}

Error Handling

import { BrainerceClient, BrainerceError } from 'brainerce';

try {
  const product = await omni.getProduct('invalid_id');
} catch (error) {
  if (error instanceof BrainerceError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status Code: ${error.statusCode}`);
    console.error(`Details:`, error.details);
  }
}

Webhooks

Receive real-time updates when products, orders, or inventory change.

Setup Webhook Endpoint

// api/webhooks/brainerce/route.ts (Next.js App Router)
import { verifyWebhook, createWebhookHandler } from 'brainerce';

const handler = createWebhookHandler({
  'product.updated': async (event) => {
    console.log('Product updated:', event.entityId);
    // Invalidate cache, update UI, etc.
  },
  'inventory.updated': async (event) => {
    console.log('Stock changed:', event.data);
  },
  'order.created': async (event) => {
    console.log('New order from:', event.platform);
  },
});

export async function POST(req: Request) {
  const signature = req.headers.get('x-omni-signature');
  const body = await req.json();

  // Verify signature
  if (!verifyWebhook(body, signature, process.env.OMNI_SYNC_WEBHOOK_SECRET!)) {
    return new Response('Invalid signature', { status: 401 });
  }

  // Process event
  await handler(body);

  return new Response('OK');
}

Webhook Events

Event Description
product.created New product created
product.updated Product details changed
product.deleted Product removed
inventory.updated Stock levels changed
order.created New order received
order.updated Order status changed
cart.abandoned Cart abandoned (no activity)
checkout.completed Checkout completed successfully

TypeScript Support

All types are exported for full TypeScript support:

import type {
  // Products
  Product,
  ProductImage,
  ProductVariant,
  InventoryInfo,
  ProductQueryParams,
  PaginatedResponse,

  // Local Cart (Guest Users)
  LocalCart,
  LocalCartItem,
  CreateGuestOrderDto,
  GuestOrderResponse,

  // Server Cart (Registered Users)
  Cart,
  CartItem,
  AddToCartDto,

  // Checkout
  Checkout,
  CheckoutStatus,
  ShippingRate,
  SetShippingAddressDto,

  // Customer
  Customer,
  CustomerProfile,
  CustomerAddress,
  CustomerAuthResponse,

  // Orders
  Order,
  OrderStatus,
  OrderItem,

  // Webhooks
  WebhookEvent,
  WebhookEventType,

  // Errors
  BrainerceError,
} from 'brainerce';

Environment Variables

# Required for vibe-coded sites
NEXT_PUBLIC_OMNI_CONNECTION_ID=vc_your_connection_id

# Optional: Override API URL (default: https://api.brainerce.com)
NEXT_PUBLIC_OMNI_API_URL=https://api.brainerce.com

# For webhooks (server-side only)
OMNI_SYNC_WEBHOOK_SECRET=your_webhook_secret

Required Pages Checklist

When building a store, implement these pages:

  • Home (/) - Product grid
  • Products (/products) - Product list with pagination
  • Product Detail (/products/[slug]) - Single product with Add to Cart (use getProductBySlug(slug))
  • Cart (/cart) - Cart items, update quantity, remove
  • Checkout (/checkout) - Multi-step checkout flow
  • ⚠️ Payment (/checkout/payment) - REQUIRED! Use getPaymentProviders() to show Stripe/PayPal forms
  • Login (/login) - Customer login + social login buttons (Google/Facebook/GitHub if available)
  • Register (/register) - Customer registration + social signup buttons
  • Auth Callback (/auth/callback) - Handle OAuth redirects from Google/Facebook/GitHub
  • Verify Email (/verify-email) - Email verification with 6-digit code (if store requires it)
  • Account (/account) - Profile and order history

⚠️ Payment Page is REQUIRED

Without a payment page, customers cannot complete orders! See Payment Integration for implementation.


Error Handling & Toast Notifications

For a polished user experience, use toast notifications to show success/error messages. We recommend Sonner - a lightweight toast library.

Setup Toast Notifications

npm install sonner

Add the Toaster component to your app layout:

// app/layout.tsx or App.tsx
import { Toaster } from 'sonner';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Toaster
          position="top-right"
          richColors
          closeButton
          toastOptions={{
            duration: 4000,
          }}
        />
      </body>
    </html>
  );
}

Handling SDK Errors

The SDK throws BrainerceError with helpful messages. Wrap SDK calls in try/catch:

import { toast } from 'sonner';
import { BrainerceError } from 'brainerce';

// Add to cart with toast feedback
const handleAddToCart = async (productId: string, quantity: number) => {
  try {
    omni.addToLocalCart({ productId, quantity });
    toast.success('Added to cart!');
  } catch (error) {
    if (error instanceof BrainerceError) {
      toast.error(error.message);
    } else {
      toast.error('Something went wrong');
    }
  }
};

// Checkout with toast feedback
const handleCheckout = async () => {
  try {
    const order = await omni.submitGuestOrder();
    toast.success(`Order placed! Order #${order.orderNumber}`);
    // Navigate to success page
  } catch (error) {
    if (error instanceof BrainerceError) {
      // Show specific error message from SDK
      toast.error(error.message);
    } else {
      toast.error('Failed to place order. Please try again.');
    }
  }
};

Common Error Messages

Error When it occurs
Cart is empty Trying to checkout with empty cart
Customer email is required Missing email at checkout
Shipping address is required Missing shipping address
Product not found Invalid product ID
Insufficient inventory Not enough stock
Invalid quantity Quantity < 1 or > available

Custom Hook for SDK Operations (Optional)

Create a reusable hook for SDK operations with automatic toast handling:

// hooks/useOmniAction.ts
import { useState } from 'react';
import { toast } from 'sonner';
import { BrainerceError } from 'brainerce';

export function useOmniAction<T>() {
  const [isLoading, setIsLoading] = useState(false);

  const execute = async (
    action: () => Promise<T>,
    options?: {
      successMessage?: string;
      errorMessage?: string;
      onSuccess?: (result: T) => void;
    }
  ): Promise<T | null> => {
    setIsLoading(true);
    try {
      const result = await action();
      if (options?.successMessage) {
        toast.success(options.successMessage);
      }
      options?.onSuccess?.(result);
      return result;
    } catch (error) {
      const message =
        error instanceof BrainerceError
          ? error.message
          : options?.errorMessage || 'Something went wrong';
      toast.error(message);
      return null;
    } finally {
      setIsLoading(false);
    }
  };

  return { execute, isLoading };
}

// Usage:
const { execute, isLoading } = useOmniAction();

const handlePlaceOrder = () => {
  execute(() => omni.submitGuestOrder(), {
    successMessage: 'Order placed successfully!',
    onSuccess: (order) => navigate(`/order/${order.orderId}`),
  });
};

Important Rules

DO:

  • Install brainerce and use it for ALL data
  • Import types from the SDK
  • Handle loading states and errors
  • Use toast notifications (Sonner) for user feedback on actions
  • Persist cart ID in localStorage
  • Persist customer token after login
  • Use isHtmlDescription(product) helper and render HTML with dangerouslySetInnerHTML when it returns true
  • Wrap SDK calls in try/catch and show error toasts

DON'T:

  • Create mock/hardcoded product data
  • Use localStorage for products
  • Skip implementing required pages
  • Write const products = [...] - use the API!
  • Use @apply group in CSS - Tailwind doesn't allow 'group' in @apply. Use className="group" on the element instead
  • Render product.description as plain text without using isHtmlDescription() - HTML will show as raw tags like <p>, <ul>, <li>!

License

MIT