Skip to main content
@opencals/storefront-sdk is the official TypeScript client for the Storefront API — generated from the OpenAPI spec, fully typed, with Zod runtime validation and formatting helpers for prices, durations, and timezones. MIT licensed.
npm ↗ · SDK guide
Each feature ships in a specific SDK version. To use a feature, install that version or higher — for example, add-ons require v0.3.0+ and discounts require v0.3.2+. Older versions don’t include those methods or types.

​
Version history

​
AuthRate limits
Forward the buyer’s IP. A new buyerIp option on setupOpencals takes a function that returns the IP of the visitor a request is made for. The SDK sends it as X-Opencals-Buyer-Ip, and with a private storefront key (spk_) the API then counts rate limits and sign-up, login and email protection per visitor instead of per server. Next.js apps can use the ready-made nextBuyerIp from the new @opencals/storefront-sdk/next entry point. See Forward the buyer’s IP.One key setting, two kinds of key. apiKey / OPENCALS_API_KEY takes either a private storefront key (spk_, for server code) or a public one (sfk_, for browser code). The SDK warns when a private key is passed in a browser, where anyone could read it. See API keys.OpencalsApiError.code carries the API’s machine-readable reason when there is one, for example CODE_EXPIRED for a rejected discount code.No breaking changes.
​
DeprecationBreaking
Staff contact details removed. The Storefront API no longer returns staff email, userId or refreshToken, and staff detail no longer includes the linked user. Storefront keys ship in browsers, so these were readable by anyone. The fields are gone from every *StaffMember type, and the StaffMemberDetailUser type is removed. If you used email for avatar initials, use firstName / lastName instead.Appointment externalOrderId / externalOrderName deprecated. These fields predate orders. Read the platform order from appointment.order instead (order.externalId, order.externalName).
  • Both fields stay in appointment responses and are now filled from the linked order, so they’re correct again for new bookings. They’re marked @deprecated in the types.
  • AppointmentService.findByExternalOrderName is deprecated. It now only returns appointments from the store making the request, and it returns 404 instead of 400 when nothing matches.
​
Custom Attributes
Custom attributes on appointments. Ships support for the new custom attributes feature.
  • CreateAppointment accepts an optional customAttributes map (string keys → string values) to attach arbitrary data at booking time
  • Appointment responses now echo customAttributes
​
DiscountsAuth
Discounts & passwordless auth. Ships support for the new discounts feature and magic-link sign-in.
  • CartService.applyDiscountCode() and CartService.removeDiscountCode()
  • New discount types: AppliedDiscount, ApplyCode, CartItemAppliedDiscount, OrderLineItemDiscount, OrderLineItemDiscountWritable
  • Passwordless / magic-link auth: AuthService.requestLoginCode(), AuthService.verifyLoginCode(), AuthService.resolveLink(), with RequestLoginCode, VerifyLoginCode, ResolveLinkResponse types
​
Fix
  • Fixed the AppointmentAddOn type, which was missing fields due to a backend OpenAPI schema name collision (the DTO was renamed to CreateAppointmentAddOnDto)
​
Add-Ons
Add-ons support. First version with the Add-Ons feature.
  • AddonService, with CartAddOnItem, AppointmentAddOn, and OrderAddOnLineItem types
  • StoreService.getStorePublicSettings() for storefront currency and public store settings
​
API change
Service classes. Released alongside the public Storefront API v1.
  • Grouped SDK methods into *Service classes by tag (e.g. ProductService, AuthService, CartService)
  • Stripped the controller prefix from operation IDs (e.g. ProductService.list() instead of productList())
  • Fixed Auth operations missing from the spec (tag collision with the admin controller)
  • Rewrote the README with updated examples and a service table
​
Initial
Initial releases of the auto-generated TypeScript client.
  • v0.1.0 — auto-generated client, Zod validation schemas, setupOpencals() one-line init, API-key/error/logging interceptors, and helpers (formatPrice, formatDuration, timezone conversion). Full support for products, cart, checkout, customer auth, appointments, orders, and feedback.
  • v0.1.1 — renamed external_domain → externalDomain on StorePublicSettings.
  • v0.1.2 — renamed client_secret → clientSecret on CheckoutStartResponse.
Last modified on October 24, 2026