@sonic-commerce/storefront-types

TypeScript types for the Sonic Commerce storefront API (/api/v1).

Types only — no runtime code, nothing to import at run time, nothing added to your bundle. Generated from the API's OpenAPI document, which is itself generated from the Zod schemas that serialize every response, so these types describe what the server actually sends.

Install

npm i -D @sonic-commerce/storefront-types
npm i openapi-fetch

openapi-fetch (~6 kB) turns the paths type into a checked client. It is optional — the named types work with fetch, axios, or anything else.

Use

import createClient from "openapi-fetch";
import type { paths, Product } from "@sonic-commerce/storefront-types";

const api = createClient<paths>({
  baseUrl: "https://acme.example.com/api/v1",
  headers: { "x-publishable-key": process.env.PUBLISHABLE_KEY! },
});

// Path, query params and response are all typed and checked.
const { data, error } = await api.GET("/products", {
  params: { query: { limit: 20, sort: "-created_at" } },
});

const products: Product[] | undefined = data?.data;

Every named schema in the spec is exported as a type alias — Product, Cart, Order, Store, Category, Collection, AuthSession, the request bodies, and so on — alongside the raw paths, components and operations that openapi-typescript emits.

import type { Cart, CartTotals, AddCartItemBody } from "@sonic-commerce/storefront-types";

One openapi-fetch quirk

openapi-fetch (0.17.0, checked) drops properties typed as exactly null from the response types it infers. Two fields are affected: shipping_total on CartTotals and on OrderTotals, both deliberately null because shipping is not modelled — an absent charge, not a zero one.

They are still there at run time. If you need them in the type, annotate with the named schema rather than the inferred response:

import type { Cart } from "@sonic-commerce/storefront-types";

const { data } = await api.GET("/carts/{id}", { params: { path: { id } } });
const cart = data?.data as Cart | undefined;   // shipping_total present

Versioning

The package version tracks the API version: 0.10.1 describes the /api/v1 surface as of release 0.10.1.

While the API is pre-1.0, breaking changes ship in a minor bump (0.10 → 0.11), per the project's versioning policy. Pin accordingly:

{ "devDependencies": { "@sonic-commerce/storefront-types": "~0.10.1" } }

~ accepts patches and stays off the next minor. Switch to ^ once the API reaches 1.0.

Other languages

The OpenAPI 3.1 document these types are generated from is served live at GET /api/v1/openapi.json. Any generator that reads OpenAPI can target it.