@cimplify/sdk

The official TypeScript SDK for building storefronts with the Cimplify Commerce Engine.

Installation

npm install @cimplify/sdk
# or
yarn add @cimplify/sdk
# or
bun add @cimplify/sdk

Quick Start

import { createCimplifyClient } from "@cimplify/sdk";

const cimplify = createCimplifyClient();

// Fetch products
const productsResult = await cimplify.catalogue.getProducts();
if (!productsResult.ok) throw productsResult.error;
const products = productsResult.value.items;

// Fetch full catalogue envelope (products + categories + add-ons)
const catalogueResult = await cimplify.catalogue.getCatalogue();
if (!catalogueResult.ok) throw catalogueResult.error;
const { categories, add_ons } = catalogueResult.value;

// Add to cart
await cimplify.cart.addItem({ item_id: "product-id", quantity: 1 });

// Get cart
const cart = await cimplify.cart.get();

Pricing Guide

• See ./sdk-pricing-flow.md for the quote-first pricing flow and end-to-end examples.
• Runtime backend contract: ../../src/salesman/pricing-contract.md (quote/recompute behavior and channel mapping).

Services

Catalogue

// Products
// getProducts() is list-focused (items + pagination/truncation metadata)
const productsResult = await cimplify.catalogue.getProducts();
const featuredResult = await cimplify.catalogue.getProducts({ featured: true, limit: 10 });
if (!productsResult.ok || !featuredResult.ok) throw new Error("Failed to fetch products");
const products = productsResult.value.items;
const featured = featuredResult.value.items;

// Full catalogue envelope when you need categories/add-ons alongside products
const catalogueResult = await cimplify.catalogue.getCatalogue();
if (!catalogueResult.ok) throw catalogueResult.error;
const { categories, add_ons } = catalogueResult.value;

const product = await cimplify.catalogue.getProduct("product-id");
const product = await cimplify.catalogue.getProductBySlug("my-product");

// Variants
const variants = await cimplify.catalogue.getVariants("product-id");
const variant = await cimplify.catalogue.getVariantByAxisSelections("product-id", {
  Size: "Large",
  Color: "Red",
});

// Categories & Collections
const categories = await cimplify.catalogue.getCategories();
const collections = await cimplify.catalogue.getCollections();

// Bundles & Composites
const bundles = await cimplify.catalogue.getBundles();
const composites = await cimplify.catalogue.getComposites();

// Search
const results = await cimplify.catalogue.search("coffee");

Cart

const cart = await cimplify.cart.get();
const count = await cimplify.cart.getCount();

await cimplify.cart.addItem({
  item_id: "product-id",
  quantity: 2,
  configuration: {
    variant: { variant_id: "variant-id" },
    add_ons: [{ add_on_id: "addon-id", quantity: 1 }],
  },
});

await cimplify.cart.updateQuantity("cart-item-id", 3);
await cimplify.cart.removeItem("cart-item-id");
await cimplify.cart.clear();

await cimplify.cart.applyCoupon("SUMMER20");
await cimplify.cart.removeCoupon();

Orders

const orders = await cimplify.orders.getOrders();
const order = await cimplify.orders.getOrder("order-id");

Authentication

const status = await cimplify.auth.getStatus();
const user = await cimplify.auth.getCurrentUser();

await cimplify.auth.requestOtp("+1234567890", "phone");
const result = await cimplify.auth.verifyOtp("123456", "+1234567890");
await cimplify.auth.logout();

Business & Locations

const business = await cimplify.business.getBusiness();
const locations = await cimplify.business.getLocations();

Scheduling

const slots = await cimplify.scheduling.getAvailableSlots({
  location_id: "location-id",
  date: "2025-01-15",
  service_type: "delivery",
});

Inventory

const stock = await cimplify.inventory.checkStock("product-id", "location-id");

Price Utilities

import { formatPrice, formatPriceCompact, isOnSale, getDiscountPercentage } from "@cimplify/sdk";

formatPrice(29.99, "USD"); // "$29.99"
formatPrice(29.99, "GHS"); // "GH₵29.99"
formatPriceCompact(2500000, "USD"); // "$2.5M"

if (isOnSale(product)) {
  console.log(`${getDiscountPercentage(product)}% off!`);
}

Type-Safe Money

All monetary values use the branded Money type: string at runtime, distinct from plain string at compile time.

import { money, type Money } from "@cimplify/sdk";

const price = money("29.99");
const zero = money("0.00");

parseFloat(price); // 29.99
console.log(price); // "29.99"

// Compile-time safety:
// const bad: Money = "29.99";      // Error
// const bad2: Money = "coffee";    // Error

Error Handling

import { CimplifyError } from "@cimplify/sdk";

try {
  await cimplify.cart.addItem({ item_id: "invalid", quantity: 1 });
} catch (error) {
  if (error instanceof CimplifyError) {
    console.log(error.code); // "PRODUCT_NOT_FOUND"
    console.log(error.message); // "Product not found"
  }
}

TypeScript

import type {
  Product,
  ProductWithDetails,
  ProductVariant,
  Category,
  Collection,
  Bundle,
  Composite,
  Cart,
  CartItem,
  Order,
  Customer,
} from "@cimplify/sdk";

License

MIT