@puddle/storefront

🇿🇦 Puddle is upgrading the South African headless e-commerce landscape! The waitlist is available at puddle.co.za.

The official TypeScript SDK for the Puddle Storefront API. Built with full type safety and modern web standards.

Installation

npm install @puddle/storefront

Initialization

You can initialize the Storefront API client by providing your storefrontPublicKey. This key will automatically be passed as a Bearer token in the Authorization header for all requests.

import { PuddleStorefrontApi } from "@puddle/storefront";

const storefront = new PuddleStorefrontApi({
  storefrontPublicKey: "pk_storefront_test_...",
});

You can also pass additional default headers or configuration for the fetch client:

const storefront = new PuddleStorefrontApi({
  storefrontPublicKey: "pk_storefront_test_...",
  headers: {
    "x-puddle-storefront-host": "shop.example.com",
  },
});

Usage Examples

The SDK is grouped by top-level resources like accounts, cart, collections, products, content, and wishlist.

Here are some common examples of how to use it:

Get the current customer

const { data: customer } = await storefront.accounts.get({
  throwOnError: true,
});

console.log(customer);

Update the current customer

const { data } = await storefront.accounts.update({
  body: {
    firstName: "Jane",
    lastName: "Doe",
    phone: "+27123456789",
  },
  throwOnError: true,
});

List trending products

const { data: products } = await storefront.products.getTrendingProducts({
  throwOnError: true,
});

Get the current cart

const { data: cart } = await storefront.cart.get({
  throwOnError: true,
});

Add an item to the cart

const { data: updatedCart } = await storefront.cart.add({
  body: {
    productId: "product_123",
    productVariantId: "variant_123",
    quantity: 1,
  },
  throwOnError: true,
});

Request an OTP

await storefront.accounts.authRequestOtp({
  body: {
    email: "[email protected]",
  },
  throwOnError: true,
});

Error Handling

By default, the SDK returns a response object containing data and error. We highly recommend using the throwOnError: true option to automatically throw exceptions for non-2xx HTTP responses, which makes integration much simpler in modern frameworks.

try {
  const { data } = await storefront.cart.add({
    body: { productId: "invalid_123", quantity: 1 },
    throwOnError: true,
  });
} catch (error) {
  console.error("Failed to add to cart:", error);
}