@sonic-commerce/storefront-types 0.11.0

package/README.md

@@ -0,0 +1,84 @@
+# @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
+
+```bash
+npm i -D @sonic-commerce/storefront-types
+npm i openapi-fetch
+```
+
+[`openapi-fetch`](https://openapi-ts.dev/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
+
+```ts
+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.
+
+```ts
+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:
+
+```ts
+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:
+
+```jsonc
+{ "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.

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+// Generated by scripts/build.mjs from app/openapi/public-api.json — do not edit.
+// Spec version 0.11.0, 50 named schemas.
+
+export type { paths, components, operations } from "./schema";
+import type { components } from "./schema";
+
+export type AddCartItemBody = components["schemas"]["AddCartItemBody"];
+export type AuthSession = components["schemas"]["AuthSession"];
+export type Cart = components["schemas"]["Cart"];
+export type CartAddress = components["schemas"]["CartAddress"];
+export type CartAddressBody = components["schemas"]["CartAddressBody"];
+export type CartCodeBody = components["schemas"]["CartCodeBody"];
+export type CartDiscount = components["schemas"]["CartDiscount"];
+export type CartGiftCard = components["schemas"]["CartGiftCard"];
+export type CartTotals = components["schemas"]["CartTotals"];
+export type Category = components["schemas"]["Category"];
+export type CategorySummary = components["schemas"]["CategorySummary"];
+export type CategoryTreeNode = components["schemas"]["CategoryTreeNode"];
+export type Collection = components["schemas"]["Collection"];
+export type Country = components["schemas"]["Country"];
+export type CreateReturnBody = components["schemas"]["CreateReturnBody"];
+export type Currency = components["schemas"]["Currency"];
+export type Customer = components["schemas"]["Customer"];
+export type CustomerAddress = components["schemas"]["CustomerAddress"];
+export type Error = components["schemas"]["Error"];
+export type LineItem = components["schemas"]["LineItem"];
+export type LoginBody = components["schemas"]["LoginBody"];
+export type Order = components["schemas"]["Order"];
+export type OrderItem = components["schemas"]["OrderItem"];
+export type OrderListItem = components["schemas"]["OrderListItem"];
+export type OrderTaxLine = components["schemas"]["OrderTaxLine"];
+export type OrderTotals = components["schemas"]["OrderTotals"];
+export type OrderTracking = components["schemas"]["OrderTracking"];
+export type PaginationMeta = components["schemas"]["PaginationMeta"];
+export type PaymentMethod = components["schemas"]["PaymentMethod"];
+export type Product = components["schemas"]["Product"];
+export type ProductCategory = components["schemas"]["ProductCategory"];
+export type ProductCollection = components["schemas"]["ProductCollection"];
+export type ProductListItem = components["schemas"]["ProductListItem"];
+export type ProductOption = components["schemas"]["ProductOption"];
+export type ProductVariant = components["schemas"]["ProductVariant"];
+export type Region = components["schemas"]["Region"];
+export type RegionSummary = components["schemas"]["RegionSummary"];
+export type RegisterBody = components["schemas"]["RegisterBody"];
+export type Return = components["schemas"]["Return"];
+export type ReturnItem = components["schemas"]["ReturnItem"];
+export type RewardPoints = components["schemas"]["RewardPoints"];
+export type SalesChannel = components["schemas"]["SalesChannel"];
+export type Session = components["schemas"]["Session"];
+export type SetCartCustomerBody = components["schemas"]["SetCartCustomerBody"];
+export type SetCartRegionBody = components["schemas"]["SetCartRegionBody"];
+export type Store = components["schemas"]["Store"];
+export type TaxRate = components["schemas"]["TaxRate"];
+export type TaxSummary = components["schemas"]["TaxSummary"];
+export type UpdateCartItemBody = components["schemas"]["UpdateCartItemBody"];
+export type VariantPrice = components["schemas"]["VariantPrice"];