@shopstrix/storefront-sdk

The official, lightweight TypeScript/JavaScript SDK for interacting with ShopStrix Headless E-Commerce and Marketplace Storefront APIs.

✨ Features

• 🚀 100% Storefront API Coverage: Catalog search, category browsing, cart management, coupons, 3-step checkout, and customer auth.
• 🛡️ Typed Error System: Catch and handle domain-specific errors (CouponError, CartError, CheckoutError, AuthenticationError, ValidationError).
• ⚡ Zero External Dependencies: Native fetch with isomorphic compatibility (Browser, Node, Bun, Cloudflare Workers, Next.js).
• 🧩 Modular & Intuitive API: Clean namespace modules (sdk.catalog, sdk.cart, sdk.checkout, sdk.auth, sdk.stores) plus top-level convenience methods.
• 🔐 Automated Session Tracking: Automatic x-session-token capture and storage across guest carts and authenticated accounts.
• 🎨 Ready-Made React Recipes: Production-ready React + Tailwind CSS page components in @shopstrix/storefront-sdk/recipes.

📦 Installation

# Using npm
npm install @shopstrix/storefront-sdk

# Using bun
bun add @shopstrix/storefront-sdk

# Using yarn
yarn add @shopstrix/storefront-sdk

🚀 Quickstart

import { sdk } from '@shopstrix/storefront-sdk';

// 1. Search products
const { items: products } = await sdk.catalog.getProducts({
  search: 'hoodie',
  take: 10,
});

// 2. Add product variant to active cart
const cart = await sdk.cart.addItem(products[0].variants[0].id, 1);

// 3. Apply discount promo code
await sdk.cart.applyCoupon('SAVE20');

// 4. Complete 3-step checkout
await sdk.checkout.setCustomer({
  emailAddress: '[email protected]',
  firstName: 'Jane',
  lastName: 'Doe',
});

await sdk.checkout.setShippingAddress({
  fullName: 'Jane Doe',
  streetLine1: '123 Market St',
  city: 'San Francisco',
  postalCode: '94103',
  countryCode: 'US',
});

const order = await sdk.checkout.addPayment('standard-payment');
console.log('Order placed successfully! Order Code:', order.code);

🛠️ Custom Configuration

import { createShopStrixSDK } from '@shopstrix/storefront-sdk';

const customSdk = createShopStrixSDK({
  gatewayUrl: 'https://api.yourdomain.com',
  storeSlug: 'my-store-slug',
  timeoutMs: 15000,
  onSessionTokenChange: (token) => {
    console.log('Session token updated:', token);
  },
});

🎨 Using Ready-Made UI Recipes

import React from 'react';
import { CatalogPage, CartDrawer, CheckoutPage } from '@shopstrix/storefront-sdk/recipes';

export function StorefrontApp() {
  const [isCartOpen, setIsCartOpen] = React.useState(false);

  return (
    <div>
      <CatalogPage onAddToCart={() => setIsCartOpen(true)} />
      <CartDrawer isOpen={isCartOpen} onClose={() => setIsCartOpen(false)} />
    </div>
  );
}

📖 Complete Documentation & AI Guide

For detailed API signatures and zero-shot prompting guides for LLMs, refer to LLM_GUIDE.md.

📄 License

MIT © ShopStrix