ORBCART DOCUMENTATION
SDKs & tools
Which package for which job, and which key goes where.
All packages are TypeScript-first. Until the first release they are used from the source workspace; there is no npm install yet.
| You are building… | Package | Start here |
|---|---|---|
| A storefront, app or agent | @orbcart/client | Carts |
| A React checkout | @orbcart/react | React checkout |
| An ERP link or support tool | @orbcart/admin | Orders & refunds |
| Your commerce Worker | @orbcart/runtime | Configuration |
| A DHL pickup finder | @orbcart/plugin-dhl | Shipping |
React is optional. The client works in any framework, on a server and in Node.
Imports at a glance
In the storefront:
import { createCommerce, formatMoney, unitsIn, isSubmitted, CommerceError } from "@orbcart/client";
import { Checkout, CartProvider, useShoppingCart } from "@orbcart/react";
import "@orbcart/react/styles.css";
import { betterAuthIdentity } from "@orbcart/client/better-auth";On your server and in your Worker:
import { createAdmin } from "@orbcart/admin";
import { defineCommerce } from "@orbcart/runtime";
export * from "@orbcart/runtime/objects";Test helpers live in @orbcart/runtime/testing and @orbcart/client/testing. Testing →
Which key goes where
The publishable key goes in the browser, the Cart token in a session cookie, the secret key only on your server. Full table →
createCommerce refuses a secret key and createAdmin refuses a publishable one,
so a mix-up fails loudly in development.
Errors
Every SDK throws CommerceError for a failed request. Business outcomes, such as
a declined card or quote_changed, are return values, not exceptions.
Handle them → · Every code →
The checkout store of cart.checkout() puts a refusal where the buyer looks for it.
Its bag steps (add, setQuantity, remove, enterCode) throw it like the cart's
own, so the Line or the discount code shows it in place. Its checkout steps
(start, submitDetails, setShipping, placeOrder) never throw a refusal: they
show it in state.notice.
Words for buyers
describe(locale) turns codes into buyer-friendly sentences in English, German,
French and Dutch. Never show the API's detail text to buyers.
import { describe } from "@orbcart/client";
const words = describe("de-DE");
words.problem("code_invalid"); // a sentence for the buyer
words.paymentMethod("ideal"); // "iDEAL | Wero"
words.change(change); // explains one entry of cart.changesRetries
The SDKs add an Idempotency-Key to every change and repeat a request when the
network drops, so a retry never adds a Line twice or charges twice
(how). You only pass your own key for refunds that
must survive a restart of your backend.