# 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](/docs/shop/carts)                                         |
| A React checkout            | `@orbcart/react`      | [React checkout](/docs/shop/react-checkout)                       |
| An ERP link or support tool | `@orbcart/admin`      | [Orders & refunds](/docs/integrate/orders-and-refunds)            |
| Your commerce Worker        | `@orbcart/runtime`    | [Configuration](/docs/shop/configuration)                         |
| A DHL pickup finder         | `@orbcart/plugin-dhl` | [Shipping](/docs/shop/shipping#dhl-packstation-and-pickup-points) |

React is optional. The client works in any framework, on a server and in Node.

## Imports at a glance

In the storefront:

```ts
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:

```ts 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 →](/docs/shop/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 →](/docs/cart/http-api#authentication)

`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 →](/docs/shop/carts#handle-errors) · [Every code →](/docs/cart/errors)

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.

```ts
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.changes
```

## Retries

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](/docs/cart/how-it-works#when-something-goes-wrong)). You only pass your own key for refunds that
must survive a restart of your backend.

[Add the React checkout →](/docs/shop/react-checkout)