Bazaara Storefront JS/TS SDK

The official @xorblin.com/bazaara client library wraps the Bazaara storefront APIs, providing a clean, type-safe API for browsers and server runtimes (SSR). It automatically handles token persistence, guest session rotation, and API validation errors.

📦 Installation

Install the package via your preferred manager:

npm install @xorblin.com/bazaara

bun add @xorblin.com/bazaara

pnpm add @xorblin.com/bazaara

🚀 Initialization

Import and initialize the BazaaraStorefront client by passing your store ID:

import { BazaaraStorefront } from '@xorblin.com/bazaara';

const bazaara = new BazaaraStorefront({
  storeId: 'YOUR_STORE_UUID_HERE',
  // Optional: defaults to https://api.bazaara.store/api/v1
  baseUrl: 'https://api.bazaara.store/api/v1', 
});

📖 API Usage Reference

1. Catalog & Products

Retrieve store details or search the product inventory.

// Get store settings, support info, currency configuration
const { data: store } = await bazaara.catalog.getDetails();

// Get products with optional search and category filters
const { data: products, meta } = await bazaara.catalog.getProducts({
  page: 1,
  limit: 12,
  category: 'Apparel',
  search: 'cotton jacket',
  minPrice: 20,
  maxPrice: 150,
  sort: 'price_asc' // newest, price_asc, price_desc
});

// Get a single product details and variants
const { data: product } = await bazaara.catalog.getProduct('product-uuid');

// Quick autocomplete product search
const { data: suggestions } = await bazaara.catalog.autocomplete('blue');

2. Shopping Cart

Cart guest session tokens (X-Guest-Token) are monitored and persisted by the SDK automatically, keeping the buyer's session active across refreshes.

// Fetch current cart contents
const { data: cart } = await bazaara.cart.get();

// Add an item to the cart (quantity defaults to 1)
const { data: updatedCart } = await bazaara.cart.addItem('product-uuid', 2, {
  color: 'Navy',
  size: 'M'
});

// Update item quantities
await bazaara.cart.updateItem('cart-item-uuid', 3);

// Remove an item
await bazaara.cart.removeItem('cart-item-uuid');

// Empty the cart
await bazaara.cart.clear();

3. Customer Authentication & Accounts

// Register a new customer account
await bazaara.auth.signup({
  name: 'Jane Doe',
  email: 'jane@example.com',
  password: 'securepassword123'
});

// Login an existing customer (accessToken is saved automatically)
await bazaara.auth.login({
  email: 'jane@example.com',
  password: 'securepassword123'
});

// Fetch logged-in customer profile
const { data: profile } = await bazaara.auth.getProfile();

// Log out (clears access credentials from storage)
bazaara.auth.logout();

4. Checkout & Address Book

// Complete checkout and place order
const { data: order } = await bazaara.checkout.process({
  email: 'jane@example.com',
  phone: '1234567890',
  shippingAddress: {
    firstName: 'Jane',
    lastName: 'Doe',
    addressLine1: '456 Market St',
    city: 'San Francisco',
    state: 'CA',
    zipCode: '94103',
    country: 'US',
    phone: '1234567890'
  },
  paymentMethod: 'stripe',
  paymentId: 'pm_12345_token', // payment ID from Stripe Elements / UI integration
  couponCode: 'WELCOME10'
});

// Retrieve customer order history (requires login)
const { data: orders } = await bazaara.customer.getOrders();

🛠️ Advanced Configurations

Pluggable Storage (Next.js SSR & Cookies)

By default, the SDK uses localStorage in the browser, falling back to a memory buffer on server runtimes. If you need to persist tokens across cookies or server sessions (e.g., in Next.js Server Components), supply a custom storage interface:

import { BazaaraStorefront, BazaaraStorage } from '@xorblin.com/bazaara';

const cookieStorage: BazaaraStorage = {
  getItem: (key) => getCookie(key),
  setItem: (key, value) => setCookie(key, value, { path: '/' }),
  removeItem: (key) => deleteCookie(key)
};

const bazaara = new BazaaraStorefront({
  storeId: 'your-store-id',
  storage: cookieStorage
});

Structured Error Handling

All API issues and schema violations throw a BazaaraError carrying HTTP status details and validation error matrices:

import { BazaaraError } from '@xorblin.com/bazaara';

try {
  await bazaara.auth.login({ email: 'bad-email', password: '1' });
} catch (err) {
  if (BazaaraError.isBazaaraError(err)) {
    console.log(`HTTP ${err.status}: ${err.message}`);
    if (err.errors) {
      console.log('Validation detail:', err.errors); 
      // e.g. { email: ["Email is invalid."], password: ["Password must be at least 6 characters."] }
    }
  }
}