@sonic-commerce/storefront-types 0.23.3 → 0.24.0

package/README.md

@@ -1,6 +1,6 @@
 # @sonic-commerce/storefront-types
 
-TypeScript types for the Sonic Commerce storefront API (`/api/v1`).
+TypeScript types for the Sonic Commerce storefront 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
@@ -20,13 +20,20 @@ npm i openapi-fetch
 
 ## Use
 
+Every store is served from **one API host**. The store is named by the
+`x-store-id` header, not by the hostname.
+
 ```ts
 import createClient from "openapi-fetch";
 import type { paths, Product } from "@sonic-commerce/storefront-types";
 
+// Server-side only — the Store ID is not meant for a browser bundle.
 const api = createClient<paths>({
-  baseUrl: "https://acme.example.com/api/v1",
-  headers: { "x-publishable-key": process.env.PUBLISHABLE_KEY! },
+  baseUrl: "https://api.example.com/v1",
+  headers: {
+    "x-store-id": process.env.SONIC_STORE_ID!,
+    "x-publishable-key": process.env.PUBLISHABLE_KEY!,
+  },
 });
 
 // Path, query params and response are all typed and checked.
@@ -37,6 +44,27 @@ const { data, error } = await api.GET("/products", {
 const products: Product[] | undefined = data?.data;
 ```
 
+| Header | Send it | What it is |
+|---|---|---|
+| `x-store-id` | every request | The Store ID (`K7M2-QX9P`), from the admin under Settings → Store details. Keep it on your server |
+| `x-publishable-key` | every request | The client key issued in the admin |
+| `x-shopper-ip` | login, registration, cart creation, password reset, order tracking | The shopper's IP address. These endpoints are rate-limited per shopper and answer `400` without it |
+| `Idempotency-Key` | `POST /carts/{id}/complete` | A unique value you generate. A retry with the same key returns the first response instead of placing a second order |
+
+```ts
+// Your server is the caller, so say which shopper it is acting for.
+await api.POST("/carts", {
+  params: { header: { "x-shopper-ip": shopperIp } },
+  body: {},
+});
+```
+
+A missing or unknown Store ID or publishable key is answered `404 Not found`.
+
+A store with its own **custom domain** can use `https://<that domain>/v1`
+instead; there the hostname names the store and `x-store-id` / `x-shopper-ip`
+are not needed. Per-store subdomains are not served.
+
 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
@@ -65,14 +93,14 @@ 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.
+The package version tracks the API version: `0.23.0` describes the `/v1`
+surface as of release 0.23.0.
 
-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:
+While the API is pre-1.0, **breaking changes ship in a minor bump** (0.23 →
+0.24), per the project's versioning policy. Pin accordingly:
 
 ```jsonc
-{ "devDependencies": { "@sonic-commerce/storefront-types": "~0.10.1" } }
+{ "devDependencies": { "@sonic-commerce/storefront-types": "~0.23.0" } }
 ```
 
 `~` accepts patches and stays off the next minor. Switch to `^` once the API
@@ -81,4 +109,4 @@ 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.
+`GET /v1/openapi.json`. Any generator that reads OpenAPI can target it.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 // Generated by scripts/build.mjs from app/openapi/public-api.json — do not edit.
-// Spec version 0.23.3, 54 named schemas.
+// Spec version 0.24.0, 54 named schemas.
 
 export type { paths, components, operations } from "./schema";
 import type { components } from "./schema";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sonic-commerce/storefront-types",
-  "version": "0.23.3",
-  "description": "TypeScript types for the Sonic Commerce storefront API (/api/v1).",
+  "version": "0.24.0",
+  "description": "TypeScript types for the Sonic Commerce storefront API (/v1).",
   "keywords": ["sonic-commerce", "openapi", "types", "storefront"],
   "license": "UNLICENSED",
   "repository": {