@webmate-studio/shop-sdk

Lightweight JavaScript SDK for the Webmate Studio Shop API. Zero dependencies, ~3KB gzipped.

Installation

npm install @webmate-studio/shop-sdk

Quick Start

import { createShopClient } from '@webmate-studio/shop-sdk';

// Create client - API URL is automatically detected from meta tag
const shop = createShopClient();

// Or with explicit configuration (overrides meta tag)
const shop = createShopClient({
  apiUrl: 'https://your-tenant.cms.example.com',
  tenantId: 'tenant-uuid' // Only needed for cross-origin requests
});

Configuration

The SDK automatically detects the API URL from the <meta name="webmate-api"> tag in the document:

<meta name="webmate-api" content="https://your-tenant.cms.example.com">

This meta tag is automatically set by:

• CMS Preview (/preview/[uuid]/)
• Webmate CLI Preview (wm dev)
• Website Build (generated HTML files)

If no meta tag is found and no apiUrl is provided, the SDK will throw an error.

Products

// List products
const products = await shop.products.list({
  collection: 'new-arrivals',  // Filter by collection slug
  search: 'shirt',             // Search in title, description
  tag: 'summer',               // Filter by tag
  productType: 'PHYSICAL',     // PHYSICAL or DIGITAL
  limit: 12,                   // Results per page (max 100)
  cursor: 'abc123'             // For pagination
});

// Get single product
const product = await shop.products.getBySlug('blue-t-shirt');

Collections

// List all collections
const collections = await shop.collections.list();

// Get collection with products
const collection = await shop.collections.getBySlug('summer-sale', {
  limit: 24
});

Cart

Cart session is managed automatically via localStorage.

// Get current cart (creates new one if needed)
const cart = await shop.cart.get();

// Add item to cart
const cart = await shop.cart.addItem({
  variantId: 'variant-uuid',
  quantity: 2
});

// Update item quantity
const cart = await shop.cart.updateItem('item-id', { quantity: 3 });

// Remove item
const cart = await shop.cart.removeItem('item-id');

// Apply discount code
const cart = await shop.cart.applyDiscount('SUMMER20');

// Remove discount
const cart = await shop.cart.removeDiscount();

// Clear cart completely
shop.cart.clear();

Checkout

// Get available payment providers
const providers = await shop.checkout.getPaymentProviders();

// Get shipping rates
const rates = await shop.checkout.getShippingRates({
  shippingAddress: {
    firstName: 'Max',
    lastName: 'Mustermann',
    address1: 'Musterstr. 1',
    city: 'Berlin',
    zip: '10115',
    country: 'DE'
  }
});

// Create checkout
const checkout = await shop.checkout.create({
  shippingAddress: { ... },
  billingAddress: { ... },      // Optional, defaults to shipping
  shippingRateId: 'rate-uuid',
  paymentProvider: 'stripe',    // stripe, paypal, manual
  email: '[email protected]' // For guest checkout
});

// After payment (e.g., Stripe confirmation)
const order = await shop.checkout.complete({
  orderId: checkout.orderId,
  paymentIntentId: 'pi_xxx'     // From Stripe
});

Customer Authentication

Customer tokens are managed automatically via localStorage.

// Check login status
if (shop.customers.isLoggedIn()) {
  console.log('Customer is logged in');
}

// Register
await shop.customers.register({
  email: '[email protected]',
  password: 'secure123',
  firstName: 'Max',
  lastName: 'Mustermann',
  acceptsMarketing: true
});

// Login
await shop.customers.login({
  email: '[email protected]',
  password: 'secure123'
});

// Logout (clears all session data)
shop.customers.logout();

// Get profile
const customer = await shop.customers.getMe();

// Update profile
await shop.customers.updateMe({
  firstName: 'Maximilian'
});

// Get orders
const orders = await shop.customers.getOrders({ limit: 10 });

// Password reset
await shop.customers.forgotPassword('[email protected]');
await shop.customers.resetPassword({
  token: 'token-from-email',
  password: 'newpassword123'
});

Addresses

// Get all addresses
const addresses = await shop.customers.getAddresses();

// Add address
const address = await shop.customers.addAddress({
  firstName: 'Max',
  lastName: 'Mustermann',
  address1: 'Musterstr. 1',
  address2: 'Apt 4',
  city: 'Berlin',
  zip: '10115',
  country: 'DE',
  isDefault: true
});

// Update address
await shop.customers.updateAddress('address-id', { city: 'Hamburg' });

// Delete address
await shop.customers.deleteAddress('address-id');

Error Handling

import { createShopClient, ShopAPIError } from '@webmate-studio/shop-sdk';

try {
  await shop.cart.addItem({ variantId: 'invalid' });
} catch (error) {
  if (error instanceof ShopAPIError) {
    console.log(error.message);  // "Product variant not found"
    console.log(error.status);   // 404
    console.log(error.data);     // Full error response
  }
}

Session Management

For advanced use cases, you can access session utilities directly:

import {
  getCartToken,
  setCartToken,
  getCustomerToken,
  setCustomerToken,
  clearSession
} from '@webmate-studio/shop-sdk';

// Or via the client
shop.session.getCartToken();
shop.session.clearSession();

Usage in Components

Vanilla JavaScript

<script type="module">
  import { createShopClient } from '@webmate-studio/shop-sdk';

  const shop = createShopClient();

  document.getElementById('add-to-cart').addEventListener('click', async () => {
    const variantId = this.dataset.variantId;
    const cart = await shop.cart.addItem({ variantId, quantity: 1 });
    updateCartUI(cart);
  });
</script>

Svelte

<script>
  import { createShopClient } from '@webmate-studio/shop-sdk';
  import { onMount } from 'svelte';

  const shop = createShopClient();
  let cart = null;

  onMount(async () => {
    cart = await shop.cart.get();
  });

  async function addToCart(variantId) {
    cart = await shop.cart.addItem({ variantId, quantity: 1 });
  }
</script>

Browser Support

Works in all modern browsers with ES Module support. Requires fetch and localStorage.

License

MIT