@wocart/storefront

The storefront SDK for Wocart, the cash-on-delivery commerce platform for Algeria. It gives a storefront typed, validated access to a store's catalog, delivery prices, basket, checkout, OTP, order tracking and images — and keeps prices, rules and secrets on the server.

Documentation: docs.wocart.store/sdk/storefront — also in French and Arabic.

Install

npm install @wocart/storefront zod

zod 4 is a peer dependency. ESM only; Node 22.12 or newer for tooling.

Quick start

import { createStoreClient } from "@wocart/storefront/server";
import { mediaImageUrl } from "@wocart/storefront";

const store = createStoreClient({ serverUrl: env.COD_SERVER_URL, apiKey: env.STORE_API_KEY });

const config = await store.config.get();
const product = await store.products.get("blue-t-shirt");
const photo = product?.images[0];
const src = photo && config ? mediaImageUrl(photo.url, { width: 480, fit: "cover", format: "auto" }, config.media) ?? photo.url : null;

Reads never throw: they resolve to null, [] or {} and report through onError. Writes return { success, data } or a structured domainError.

Entry points

| Import | Runs in | Holds | | --- | --- | --- | | @wocart/storefront | browser and server | types and schemas, reference data, money and image helpers, basket and OTP state | | @wocart/storefront/server | server only | createStoreClient — the store API key lives here — preview and revalidation checks | | @wocart/storefront/astro | server only | proxy routes, form actions, placeOrderInput |

USAGE.md ships with the package for offline reading; CHANGELOG.md lists every release.

License

Apache-2.0 — see LICENSE and NOTICE.