@classytic/commerce-client 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.3.0 — 2026-10-24
+
+Add merchant `stock.read`, batched `stock.query` and guarded `stock.setQuantity` over Arc Next, product stock-tracking input and public per-variant availability types. Count retries require an explicit stable key. Browser bundles remain independent of server kernels.
+
 ## 0.2.0 — 2026-10-23
 
 Add typed merchant collection CRUD and public collection list/detail methods with

package/README.md

@@ -170,3 +170,5 @@ Arc Next sends `If-Match` for this version. A 412 response means another editor
 changed the collection: reload and review the latest record before saving again.
 Keep the original version with an open draft; do not silently retry with a newer
 version.
+
+Quantity inventory is documented in [management.md](management.md#stock).

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { DeliveryArea, DeliveryDistrict, DeliveryQuote, DeliveryQuoteInput } from "./delivery-types.js";
-import { a as StorefrontCategory, c as StorefrontCollectionQuery, d as StorefrontProductPage, f as StorefrontProductQuery, i as GuestOrderAccess, l as StorefrontOrder, m as StorefrontRequestOptions, n as GuestCheckoutOptions, o as StorefrontCollection, p as StorefrontProfile, r as GuestCheckoutResult, s as StorefrontCollectionPage, t as GuestCheckoutInput, u as StorefrontProduct } from "./types-CwAQqf0Z.js";
+import { a as StorefrontCategory, c as StorefrontCollectionQuery, d as StorefrontProductPage, f as StorefrontProductQuery, i as GuestOrderAccess, l as StorefrontOrder, m as StorefrontRequestOptions, n as GuestCheckoutOptions, o as StorefrontCollection, p as StorefrontProfile, r as GuestCheckoutResult, s as StorefrontCollectionPage, t as GuestCheckoutInput, u as StorefrontProduct } from "./types-Bz-eFZb2.js";
 import { ArcClientConfig } from "@classytic/arc-next/client";
 export interface StorefrontClientOptions {
   /** Full API mount, for example https://api.example.com/api/v1. */

package/dist/management-types.d.ts

@@ -1,7 +1,10 @@
-import { l as StorefrontOrder, u as StorefrontProduct } from "./types-CwAQqf0Z.js";
+import { l as StorefrontOrder, u as StorefrontProduct } from "./types-Bz-eFZb2.js";
 import { Address } from "@classytic/primitives/address";
 import { Money } from "@classytic/primitives/money";
 export interface ProductInput {
+  inventory?: {
+    stockTracked: boolean;
+  };
   name: string;
   slug: string;
   productType: 'physical';
@@ -35,6 +38,7 @@ export interface ProductInput {
   }>;
 }
 export interface MerchantProduct extends ProductInput {
+  stock?: ProductStock;
   _id: string;
   updatedAt: string;
 }
@@ -245,4 +249,18 @@ export interface MerchantOverview {
     count: number;
     orderValue: number;
   }>;
+}
+export interface ProductStock {
+  productId: string;
+  tracked: boolean;
+  items: Array<{
+    variantSku?: string;
+    attributes: Record<string, string>;
+    quantity: number;
+  }>;
+}
+export interface StockCountInput {
+  variantSku?: string;
+  quantity: number;
+  expectedQuantity: number;
 }

package/dist/management.d.ts

@@ -1,5 +1,5 @@
 import { DeliveryDistrict, DeliverySettings, DeliverySettingsUpdate } from "./delivery-types.js";
-import { AnalyticsWindow, ApiKeyInput, ApiKeyOptions, CategoryInput, CollectionInput, IntegrationProvider, IssuedApiKey, MerchantApiKey, MerchantCategory, MerchantCategoryTree, MerchantCollection, MerchantIntegration, MerchantMedia, MerchantOrder, MerchantOverview, MerchantProduct, NotificationDelivery, OrderCommand, ProductInput, StoreSettings } from "./management-types.js";
+import { AnalyticsWindow, ApiKeyInput, ApiKeyOptions, CategoryInput, CollectionInput, IntegrationProvider, IssuedApiKey, MerchantApiKey, MerchantCategory, MerchantCategoryTree, MerchantCollection, MerchantIntegration, MerchantMedia, MerchantOrder, MerchantOverview, MerchantProduct, NotificationDelivery, OrderCommand, ProductInput, ProductStock, StockCountInput, StoreSettings } from "./management-types.js";
 import { BaseApi } from "@classytic/arc-next/api";
 import { ArcClientConfig } from "@classytic/arc-next/client";
 export interface MerchantClientOptions {
@@ -43,6 +43,14 @@ export declare function createMerchantClient(options: MerchantClientOptions): {
     update: (data: DeliverySettingsUpdate) => Promise<DeliverySettings>;
     districts(signal?: AbortSignal): Promise<DeliveryDistrict[]>;
   };
+  stock: {
+    read: (productId: string, signal?: AbortSignal) => Promise<ProductStock>;
+    query(productIds: string[], signal?: AbortSignal): Promise<ProductStock[]>;
+    setQuantity(productId: string, data: StockCountInput, idempotencyKey: string): Promise<{
+      productId: string;
+      quantity: number;
+    }>;
+  };
   products: BaseApi<MerchantProduct, ProductInput, Partial<ProductInput>>;
   collections: BaseApi<MerchantCollection, CollectionInput, Partial<Omit<CollectionInput, "slug">>>;
   categories: BaseApi<MerchantCategory, CategoryInput, Partial<Omit<CategoryInput, "slug">>> & {

package/dist/management.js

@@ -1,5 +1,38 @@
 import { BaseApi } from "@classytic/arc-next/api";
 import { createClient } from "@classytic/arc-next/client";
+// src/management-stock.ts
+function createMerchantStock(client) {
+	const api = new BaseApi("inventory/products", {
+		client,
+		basePath: "",
+		cache: "no-store"
+	});
+	const id = (value) => {
+		if (!/^[a-f\d]{24}$/i.test(value)) throw new Error("A product ID is required.");
+		return value;
+	};
+	return { stock: {
+		read: (productId, signal) => api.request("GET", `${api.baseUrl}/${id(productId)}`, { options: { signal } }),
+		async query(productIds, signal) {
+			if (!productIds.length) return [];
+			if (productIds.length > 50) throw new Error("Read stock for at most 50 products at once.");
+			return (await api.request("POST", `${api.baseUrl}/query`, {
+				data: { productIds: productIds.map(id) },
+				options: { signal }
+			})).data;
+		},
+		setQuantity(productId, data, idempotencyKey) {
+			if (!idempotencyKey.trim()) throw new Error("Preserve an explicit idempotency key for stock retries.");
+			return api.request("POST", `${api.baseUrl}/${id(productId)}/action`, {
+				data: {
+					...data,
+					action: "set_quantity"
+				},
+				options: { headerOptions: { "Idempotency-Key": idempotencyKey } }
+			});
+		}
+	} };
+}
 // src/management-delivery.ts
 function createMerchantDelivery(client) {
 	const api = new BaseApi("stores/delivery", {
@@ -180,6 +213,7 @@ function createMerchantClient(options) {
 	const stores = new BaseApi("stores", config);
 	return {
 		...createMerchantAccess(client),
+		...createMerchantStock(client),
 		...createMerchantDelivery(client),
 		products,
 		collections: new BaseApi("collections", config),

package/dist/{types-CwAQqf0Z.d.ts → types-Bz-eFZb2.d.ts}

@@ -2,6 +2,14 @@ import { Address } from "@classytic/primitives/address";
 import { Money } from "@classytic/primitives/money";
 /** Public wire projections; merchant-only catalog and buyer fields are absent. */
 interface StorefrontProduct {
+  stock?: {
+    tracked: boolean;
+    quantity?: number;
+    variants?: Array<{
+      sku?: string;
+      quantity: number;
+    }>;
+  };
   id: string;
   name: string;
   slug: string;

package/dist/types.d.ts

@@ -1,2 +1,2 @@
-import { a as StorefrontCategory, c as StorefrontCollectionQuery, d as StorefrontProductPage, f as StorefrontProductQuery, i as GuestOrderAccess, l as StorefrontOrder, m as StorefrontRequestOptions, n as GuestCheckoutOptions, o as StorefrontCollection, p as StorefrontProfile, r as GuestCheckoutResult, s as StorefrontCollectionPage, t as GuestCheckoutInput, u as StorefrontProduct } from "./types-CwAQqf0Z.js";
+import { a as StorefrontCategory, c as StorefrontCollectionQuery, d as StorefrontProductPage, f as StorefrontProductQuery, i as GuestOrderAccess, l as StorefrontOrder, m as StorefrontRequestOptions, n as GuestCheckoutOptions, o as StorefrontCollection, p as StorefrontProfile, r as GuestCheckoutResult, s as StorefrontCollectionPage, t as GuestCheckoutInput, u as StorefrontProduct } from "./types-Bz-eFZb2.js";
 export { GuestCheckoutInput, GuestCheckoutOptions, GuestCheckoutResult, GuestOrderAccess, StorefrontCategory, StorefrontCollection, StorefrontCollectionPage, StorefrontCollectionQuery, StorefrontOrder, StorefrontProduct, StorefrontProductPage, StorefrontProductQuery, StorefrontProfile, StorefrontRequestOptions };

package/management.md

@@ -127,3 +127,31 @@ memberships. Upload cover images with `merchant.media.uploadImage(file,
 Existing string labels require the Brihot server's `collections:migrate` script
 before switching an existing storefront to managed collection navigation. It is a
 per-store dry run by default; it creates metadata without rewriting memberships.
+
+## Stock
+
+Brihot uses available quantities per product/variant. New products default to
+tracked; existing products keep their saved setting. Untracked products have no
+quantity limit. Set counts before enabling tracking on an existing product.
+
+```ts
+const stock = await merchant.stock.read(productId);
+const item = stock.items[0];
+await merchant.stock.setQuantity(productId, {
+  variantSku: item.variantSku, // omit for a simple product
+  quantity: 12,
+  expectedQuantity: item.quantity,
+}, crypto.randomUUID()); // create once; reuse on a transport retry
+await merchant.products.update({ id: productId, data: {
+  inventory: { stockTracked: true },
+} });
+```
+
+Use `stock.query(productIds)` for a table page (maximum 50 products), rather than
+one request per row. A stale count returns 409; reload before submitting a new
+count. Checkout deducts atomically and refuses insufficient stock. Canceling an
+unshipped order restores its quantity once; shipping does not deduct again.
+
+Storefront products optionally expose `stock: { tracked, quantity, variants }`.
+Use a selected variant's quantity, disable sold-out options and cap the quantity
+input. These values inform the UI; checkout always validates current stock.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/commerce-client",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Typed storefront and merchant clients for the Classytic Commerce API",
   "type": "module",
   "sideEffects": false,
@@ -63,7 +63,7 @@
     "esbuild": "^0.28.1",
     "publint": "^0.3.25",
     "tsdown": "^0.23.1",
-    "typescript": "^7.1.0-beta",
+    "typescript": "7.1.0-beta",
     "vitest": "^5.0.5"
   },
   "publishConfig": {