@classytic/commerce-client 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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
+cursor pagination over Arc Next. Add the collections media folder. Browser
+entry points remain independent of React, MongoDB and server domain packages.
+
+Dependencies are already at the latest published (`arc-next` 0.18.0, `media-transform` 0.3.0, `primitives` 0.34.0). Dev toolchain: `typescript@7.1.0-beta`, which tsdown 0.23.2 needs to emit declarations with TypeScript 7.
+
 ## 0.1.1 — 2026-10-20
 
 Add tenant-scoped media removal through the guarded media resource, and type media folder, size and display metadata for Fluid library bindings. Report unsupported source formats and browser decoding failures before starting storage writes.

package/README.md

@@ -128,3 +128,47 @@ and sort. Restart pagination when filters change. Public calls always enforce th
 resolved store and published/priced visibility, and reject unknown query fields.
 Merchant `products.getAll({ params })` continues to use Arc's normal allowed query
 syntax, including tags, collections and base-price bracket filters.
+
+### Managed collections
+
+A collection is a store-owned merchandising group, independent of the category
+hierarchy. Enable `modules: { collections: true }` on the catalog engine and mount
+`createStorefrontCollectionResource` from `@spinekit/catalog/collections-storefront`.
+Disabled engines register no collection model or indexes. The SDK stays browser-safe
+and does not import catalog, MongoDB, React or the server modules.
+
+```ts
+const groups = await storefront.collections({ featured: true, limit: 8 });
+const collection = await storefront.collection('eid-picks');
+const products = await storefront.products({
+  collection: collection.slug,
+  category: 'children', // optional; intersects the collection
+  tag: 'cotton',        // optional
+  sort: 'newest',
+  limit: 20,
+});
+// Pass groups.next / products.next as `after`, retaining the same filters.
+```
+
+Only visible collections are public. Hidden or missing collection filters return
+404. `featured` and `displayOrder` are editorial settings, not sales rankings.
+A collection does not belong to a category: its products can span categories, or a
+frontend can intersect both filters. Storefront sections and page layout stay in
+the frontend.
+
+Merchant collection edits use the version returned by the management API:
+
+```ts
+await merchant.collections.update({
+  id: collection._id,
+  data: { name: 'Summer favourites' },
+  version: collection.__v,
+});
+```
+
+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/category-tree.d.ts

@@ -1,4 +1,3 @@
-//#region src/category-tree.d.ts
 export interface CategoryBranch {
   name: string;
   slug: string;
@@ -16,5 +15,4 @@ export declare function categoryNavigation(rows: readonly {
   name: string;
   slug: string;
   parent?: string | null;
-}[]): CategoryBranch[];
-//#endregion
+}[]): CategoryBranch[];

package/dist/category-tree.js

@@ -1,4 +1,4 @@
-//#region src/category-tree.ts
+// src/category-tree.ts
 /** Flatten a category tree into breadcrumb choices, excluding a complete subtree when editing its parent. */
 function categoryChoices(nodes, excludeSlug) {
 	function visit(items, path, seen) {
@@ -35,5 +35,4 @@ function categoryNavigation(rows) {
 	}
 	return roots;
 }
-//#endregion
 export { categoryChoices, categoryNavigation };

package/dist/delivery-types.d.ts

@@ -1,4 +1,3 @@
-//#region src/delivery-types.d.ts
 export interface DeliveryRules {
   mode: 'flat' | 'zones';
   zones: Array<{
@@ -44,5 +43,4 @@ export interface DeliveryQuote {
   currency: string;
   zone?: string;
   freeDelivery?: boolean;
-}
-//#endregion
+}

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import { DeliveryArea, DeliveryDistrict, DeliveryQuote, DeliveryQuoteInput } from "./delivery-types.js";
-import { a as StorefrontCategory, c as StorefrontProductPage, d as StorefrontRequestOptions, i as GuestOrderAccess, l as StorefrontProductQuery, n as GuestCheckoutOptions, o as StorefrontOrder, r as GuestCheckoutResult, s as StorefrontProduct, t as GuestCheckoutInput, u as StorefrontProfile } from "./types-C0cSi6Pk.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";
-//#region src/index.d.ts
 export interface StorefrontClientOptions {
   /** Full API mount, for example https://api.example.com/api/v1. */
   apiUrl: string;
@@ -14,6 +13,8 @@ export declare function createStorefrontClient(options: StorefrontClientOptions)
   profile: (request?: StorefrontRequestOptions) => Promise<StorefrontProfile>;
   products: (query?: StorefrontProductQuery, request?: StorefrontRequestOptions) => Promise<StorefrontProductPage>;
   product: (slug: string, request?: StorefrontRequestOptions) => Promise<StorefrontProduct>;
+  collections: (query?: StorefrontCollectionQuery, request?: StorefrontRequestOptions) => Promise<StorefrontCollectionPage>;
+  collection: (slug: string, request?: StorefrontRequestOptions) => Promise<StorefrontCollection>;
   categories: (request?: StorefrontRequestOptions) => Promise<StorefrontCategory[]>;
   deliveryDistricts: (request?: StorefrontRequestOptions) => Promise<{
     requiresArea: boolean;
@@ -26,5 +27,4 @@ export declare function createStorefrontClient(options: StorefrontClientOptions)
   checkout: (input: GuestCheckoutInput, request: GuestCheckoutOptions) => Promise<GuestCheckoutResult>;
   orderStatus: (access: GuestOrderAccess, request?: StorefrontRequestOptions) => Promise<StorefrontOrder>;
 };
-export type StorefrontClient = ReturnType<typeof createStorefrontClient>;
-//#endregion
+export type StorefrontClient = ReturnType<typeof createStorefrontClient>;

package/dist/index.js

@@ -1,6 +1,6 @@
 import { BaseApi } from "@classytic/arc-next/api";
 import { createClient } from "@classytic/arc-next/client";
-//#region src/index.ts
+// src/index.ts
 function segment(value) {
 	if (!value || value === "." || value === "..") throw new Error("A nonempty resource identifier is required.");
 	return encodeURIComponent(value);
@@ -33,6 +33,11 @@ function createStorefrontClient(options) {
 			options: request
 		}),
 		product: (slug, request = {}) => catalog.request("GET", `${catalog.baseUrl}/products/${segment(slug)}`, { options: request }),
+		collections: (query = {}, request = {}) => catalog.request("GET", `${catalog.baseUrl}/collections`, {
+			params: { ...query },
+			options: request
+		}),
+		collection: (slug, request = {}) => catalog.request("GET", `${catalog.baseUrl}/collections/${segment(slug)}`, { options: request }),
 		categories: async (request = {}) => {
 			return (await catalog.request("GET", `${catalog.baseUrl}/categories`, { options: request })).data;
 		},
@@ -62,5 +67,4 @@ function createStorefrontClient(options) {
 		} })
 	};
 }
-//#endregion
 export { createStorefrontClient };

package/dist/management-types.d.ts

@@ -1,8 +1,10 @@
-import { o as StorefrontOrder, s as StorefrontProduct } from "./types-C0cSi6Pk.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";
-//#region src/management-types.d.ts
 export interface ProductInput {
+  inventory?: {
+    stockTracked: boolean;
+  };
   name: string;
   slug: string;
   productType: 'physical';
@@ -36,6 +38,7 @@ export interface ProductInput {
   }>;
 }
 export interface MerchantProduct extends ProductInput {
+  stock?: ProductStock;
   _id: string;
   updatedAt: string;
 }
@@ -63,6 +66,26 @@ export interface MerchantCategoryTree extends MerchantCategory {
   children: MerchantCategoryTree[];
   totalProductCount: number;
 }
+export interface CollectionInput {
+  name: string;
+  /** Omit to derive from the name. Permanent after creation. */
+  slug?: string;
+  description?: string;
+  image?: {
+    url: string;
+    alt?: string;
+  } | null;
+  isActive?: boolean;
+  featured?: boolean;
+  displayOrder?: number;
+}
+export type CollectionUpdate = Partial<Omit<CollectionInput, 'slug'>>;
+export interface MerchantCollection extends CollectionInput {
+  _id: string;
+  /** Pass the version read by the editor to collections.update({ version }). */
+  __v: number;
+  slug: string;
+}
 export interface MerchantOrder extends StorefrontOrder {
   _id: string;
   customerSnapshot?: {
@@ -227,4 +250,17 @@ export interface MerchantOverview {
     orderValue: number;
   }>;
 }
-//#endregion
+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,8 +1,7 @@
 import { DeliveryDistrict, DeliverySettings, DeliverySettingsUpdate } from "./delivery-types.js";
-import { AnalyticsWindow, ApiKeyInput, ApiKeyOptions, CategoryInput, IntegrationProvider, IssuedApiKey, MerchantApiKey, MerchantCategory, MerchantCategoryTree, 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";
-//#region src/management.d.ts
 export interface MerchantClientOptions {
   apiUrl: string;
   token: string;
@@ -44,7 +43,16 @@ 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">>> & {
     tree: (options?: {
       signal?: AbortSignal;
@@ -92,9 +100,8 @@ export declare function createMerchantClient(options: MerchantClientOptions): {
       id: string;
       options?: Omit<import("@classytic/arc-next/api").RequestOptions, "token" | "organizationId">;
     }) => Promise<import("@classytic/repo-core/repository").DeleteResult>;
-    upload: (file: File, folder?: 'products' | 'categories') => Promise<MerchantMedia>;
-    uploadImage(file: File, folder?: 'products' | 'categories'): Promise<MerchantMedia>;
+    upload: (file: File, folder?: 'products' | 'categories' | 'collections') => Promise<MerchantMedia>;
+    uploadImage(file: File, folder?: 'products' | 'categories' | 'collections'): Promise<MerchantMedia>;
   };
 };
-export type MerchantClient = ReturnType<typeof createMerchantClient>;
-//#endregion
+export type MerchantClient = ReturnType<typeof createMerchantClient>;

package/dist/management.js

@@ -1,6 +1,39 @@
 import { BaseApi } from "@classytic/arc-next/api";
 import { createClient } from "@classytic/arc-next/client";
-//#region src/management-delivery.ts
+// 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", {
 		client,
@@ -15,8 +48,7 @@ function createMerchantDelivery(client) {
 		}
 	} };
 }
-//#endregion
-//#region src/management-access.ts
+// src/management-access.ts
 function key(value) {
 	if (!value || value === "." || value === "..") throw new Error("An identifier is required.");
 	return encodeURIComponent(value);
@@ -60,8 +92,7 @@ function createMerchantAccess(client) {
 		}
 	};
 }
-//#endregion
-//#region src/management-media.ts
+// src/management-media.ts
 function createMerchantMedia(client, fetcher) {
 	const media = new BaseApi("media", {
 		client,
@@ -151,8 +182,7 @@ function createMerchantMedia(client, fetcher) {
 		}
 	};
 }
-//#endregion
-//#region src/management.ts
+// src/management.ts
 function orderKey(value) {
 	if (!value || value === "." || value === "..") throw new Error("An order number is required.");
 	return encodeURIComponent(value);
@@ -183,8 +213,10 @@ function createMerchantClient(options) {
 	const stores = new BaseApi("stores", config);
 	return {
 		...createMerchantAccess(client),
+		...createMerchantStock(client),
 		...createMerchantDelivery(client),
 		products,
+		collections: new BaseApi("collections", config),
 		categories: Object.assign(categories, { tree: (options = {}) => categories.request("GET", `${categories.baseUrl}/tree`, { options }) }),
 		analytics: { async overview(window, options = {}) {
 			const from = new Date(window.from);
@@ -261,5 +293,4 @@ function createMerchantClient(options) {
 		media: createMerchantMedia(client, fetcher)
 	};
 }
-//#endregion
 export { createMerchantClient };

package/dist/platform.d.ts

@@ -1,4 +1,3 @@
-//#region src/platform.d.ts
 export type OrganizationStatus = 'pending' | 'active' | 'rejected' | 'suspended';
 export type OrganizationAction = 'approve' | 'reject' | 'suspend' | 'reactivate';
 export interface PlatformOrganization {
@@ -32,5 +31,4 @@ export declare function createPlatformClient({ apiUrl, token }: {
       note: string;
     }): Promise<PlatformOrganization>;
   };
-};
-//#endregion
+};

package/dist/platform.js

@@ -1,6 +1,6 @@
 import { BaseApi } from "@classytic/arc-next/api";
 import { createClient } from "@classytic/arc-next/client";
-//#region src/platform.ts
+// src/platform.ts
 /** Platform administration uses a bearer identity without selecting a merchant organization. */
 function createPlatformClient({ apiUrl, token }) {
 	if (!token.trim()) throw new Error("A platform bearer token is required.");
@@ -25,5 +25,4 @@ function createPlatformClient({ apiUrl, token }) {
 		}
 	} };
 }
-//#endregion
 export { createPlatformClient };

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

@@ -1,8 +1,15 @@
 import { Address } from "@classytic/primitives/address";
 import { Money } from "@classytic/primitives/money";
-//#region src/types.d.ts
 /** 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;
@@ -45,6 +52,28 @@ interface StorefrontCategory {
   } | null;
   displayOrder?: number;
 }
+interface StorefrontCollection {
+  id: string;
+  slug: string;
+  name: string;
+  description?: string;
+  image?: {
+    url: string;
+    alt?: string;
+  } | null;
+  featured: boolean;
+  displayOrder: number;
+}
+interface StorefrontCollectionQuery {
+  limit?: number;
+  /** Opaque cursor; retain the same featured filter between pages. */
+  after?: string;
+  featured?: boolean;
+}
+interface StorefrontCollectionPage {
+  data: StorefrontCollection[];
+  next: string | null;
+}
 interface StorefrontProductPage {
   data: StorefrontProduct[];
   next: string | null;
@@ -124,5 +153,4 @@ interface GuestCheckoutOptions extends StorefrontRequestOptions {
   /** Create once per checkout attempt; preserve across retries and lost responses. */
   idempotencyKey: string;
 }
-//#endregion
-export { StorefrontCategory as a, StorefrontProductPage as c, StorefrontRequestOptions as d, GuestOrderAccess as i, StorefrontProductQuery as l, GuestCheckoutOptions as n, StorefrontOrder as o, GuestCheckoutResult as r, StorefrontProduct as s, GuestCheckoutInput as t, StorefrontProfile as u };
+export { StorefrontCategory as a, StorefrontCollectionQuery as c, StorefrontProductPage as d, StorefrontProductQuery as f, GuestOrderAccess as i, StorefrontOrder as l, StorefrontRequestOptions as m, GuestCheckoutOptions as n, StorefrontCollection as o, StorefrontProfile as p, GuestCheckoutResult as r, StorefrontCollectionPage as s, GuestCheckoutInput as t, StorefrontProduct as u };

package/dist/types.d.ts

@@ -1,2 +1,2 @@
-import { a as StorefrontCategory, c as StorefrontProductPage, d as StorefrontRequestOptions, i as GuestOrderAccess, l as StorefrontProductQuery, n as GuestCheckoutOptions, o as StorefrontOrder, r as GuestCheckoutResult, s as StorefrontProduct, t as GuestCheckoutInput, u as StorefrontProfile } from "./types-C0cSi6Pk.js";
-export { GuestCheckoutInput, GuestCheckoutOptions, GuestCheckoutResult, GuestOrderAccess, StorefrontCategory, StorefrontOrder, StorefrontProduct, StorefrontProductPage, StorefrontProductQuery, StorefrontProfile, StorefrontRequestOptions };
+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

@@ -98,3 +98,60 @@ the media resource's guarded delete; an in-use image is refused by the server.
 through media-transform before requesting storage writes. The server must accept
 every output format in its policy, including the browser encoder's fallback.
 Passthrough thresholds and dimensions belong to that policy, rather than the UI.
+
+## Managed collections
+
+```ts
+const collection = await merchant.collections.create({ data: {
+  name: 'Eid picks', // slug is generated when omitted
+  description: 'Pieces for the celebrations.',
+  isActive: true,
+  featured: true,
+  displayOrder: 10,
+} });
+await merchant.products.update({ id: productId, data: {
+  collections: [collection.slug], // replaces this product's memberships
+} });
+await merchant.collections.update({ id: collection._id, data: {
+  name: 'Our Eid edit', // preserves its permanent slug
+} });
+```
+
+Collections use the same store-bound bearer client and Arc Next CRUD/pagination
+contract as products. Create a new client when switching stores. Slug uniqueness
+is per store. An unknown or foreign collection cannot be assigned. A collection
+cannot be deleted until products release its slug; hide it instead when keeping
+memberships. Upload cover images with `merchant.media.uploadImage(file,
+'collections')` and pass `{ url, alt }` as `image`.
+
+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.1.1",
+  "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.0.2",
+    "typescript": "7.1.0-beta",
     "vitest": "^5.0.5"
   },
   "publishConfig": {