TypeScript SDK
Type-safe, browser-first client for the Cimplify Commerce API.
TS
import { createCimplifyClient } from '@cimplify/sdk'
const client = createCimplifyClient({ publicKey: 'pk_test_...' })
// Every method returns Result<T>
const result = await client.catalogue.getProducts({ limit: 10 })
if (!result.ok) {
console.error(result.error.code, result.error.message)
return
}
console.log(result.value.items)Installation
curl
npm install @cimplify/sdkResult Pattern
All SDK methods return a discriminated union. Check result.ok before accessing result.value.
TS
type Result<T> =
| { ok: true; value: T }
| { ok: false; error: CimplifyError }
type CimplifyError = {
code: string
message: string
retryable: boolean
suggestion?: string
docs_url?: string
}Services
| Service | Description |
|---|---|
client.business | Business info, locations, hours |
client.catalogue | Products, categories, collections, bundles, composites, quotes |
client.cart | Cart mutations, coupons, totals |
client.auth | OTP login, session status, profile updates |
client.checkout | Process checkout, poll payment status |
client.orders | List, get, and cancel orders |
client.link | Saved addresses, payment methods, sessions (like Shop Pay) |
client.fx | Exchange rates and currency conversion |
client.inventory | Stock levels and availability checks |
client.scheduling | Services, available time slots, bookings |
Configuration
| Option | Default | Description |
|---|---|---|
publicKey | NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY | Your public API key (pk_test_... or pk_live_...) |
baseUrl | auto-derived | Override storefront API base URL |
linkApiUrl | auto-derived | Override Link API base URL |
timeout | 30000 | Request timeout in ms |
maxRetries | 3 | Retry count for retryable errors |
retryDelay | 1000 | Base delay between retries (exponential backoff) |
hooks | {} | Observability hooks: onRequestStart, onRequestSuccess, onRequestError, onRetry, onSessionChange |
Package Exports
| Import | Contents |
|---|---|
@cimplify/sdk | createCimplifyClient, CimplifyError, generateIdempotencyKey |
@cimplify/sdk/react | React bindings: ElementsProvider, AuthElement, PaymentElement, AddressElement |
@cimplify/sdk/utils | formatPrice, parsePrice |
@cimplify/sdk/advanced | CheckoutResolver for low-level checkout orchestration |
Utilities
TS
import { formatPrice, parsePrice } from '@cimplify/sdk/utils'
formatPrice(1999, 'USD') // "$19.99"
parsePrice('19.99') // 19.99