TypeScript SDK

Type-safe wrapper around the Cimplify REST API. Single dependency, browser-safe, framework-agnostic core, with a React layer and a Server Components layer on top.

Install

bun add @cimplify/sdk          # bun (recommended)
npm install @cimplify/sdk
yarn add @cimplify/sdk

Construct a client

import { createCimplifyClient } from '@cimplify/sdk'

export const client = createCimplifyClient({
  publicKey: process.env.NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY!,
  // Optional:
  // baseUrl: 'https://api.cimplify.io',
  // fetch:   customFetch,            // injected fetch (testing harness uses this)
})

The same client construction works in browsers, Node, Bun, Deno, Workers, and React Server Components. For server-side keys (sk_…) prefer getServerClient.

Result type: never throws

Every method returns Result<T, CimplifyError>. Always check .ok:

const r = await client.catalogue.getProducts()
if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}
console.log(r.value.items)

Service surface

Service	Surface	Page
`client.catalogue`	Products, variants, categories, collections, bundles, composites, add-ons, deals, quotes	Catalogue →
`client.cart`	Add / update / remove items, apply coupon, get cart	Cart →
`client.checkout`	Process checkout, payment authorization, poll status	Checkout →
`client.auth`	OTP request/verify, profile, logout	Auth →
`client.orders`	List, get, cancel, attach customer, verify payment	Orders →
`client.scheduling`	Variant-aware slots, availability, bookings, reschedule, cancel	Scheduling →
`client.subscriptions`	List, cancel, pause, resume, skip-next	Subscriptions →
`client.activity`	Event recording, recommendations, dismissable messages	Activity →
`client.fx`	Spot rate, locked quote	FX →
`client.places`	Address autocomplete and details	Places →
`client.uploads`	Init / upload / confirm flow	Uploads →
`client.support`	Chat-widget conversations, send / list messages	Support →

Public exports

Subpath	Use
`@cimplify/sdk`	Browser-safe typed client + domain types + `Result`
`@cimplify/sdk/react`	90+ components + 30+ hooks
`@cimplify/sdk/server`	Server Components helpers, cache tags, revalidate*
`@cimplify/sdk/utils`	Money helpers, formatting, slug helpers
`@cimplify/sdk/advanced`	Lower-level escape hatches
`@cimplify/sdk/mock`	Programmatic mock for tests
`@cimplify/sdk/mock/msw`	MSW handlers wrapping the in-process mock
`@cimplify/sdk/testing`	Test harness: zod schemas, `createTestClient`, fixtures, `assertX` helpers
`@cimplify/sdk/testing/suite`	Pre-baked vitest suites: `createBrandSuite`, `createCartFlowSuite`, `createContractSuite`
`@cimplify/sdk/styles.css`	Pre-compiled Tailwind utilities for the React components

Cross-cutting concepts

Result<T, E> Why methods never throw, how to narrow
Money type Branded string, parsePrice / formatPrice
Idempotency Auto-keys for write methods, replay safety
Error handling CimplifyError shape, codes, retryable flag