@propeller-commerce/propeller-sdk-v2 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to `@propeller-commerce/propeller-sdk-v2` are documented her
 
 ---
 
+## [0.15.0] - 2026-08-04
+
+Exposes the backend inventory/stock filter so storefronts can filter catalogue
+and category listings by stock. Additive and backward-compatible — the filter
+is optional everywhere it appears.
+
+Filtering is applied server-side, so the pagination fields on the response
+(`itemsFound`, `pages`) describe the filtered set and can be used directly for
+paging.
+
+### Added
+
+- **`ProductSearchInventoryFilterInput`** — new exported type with
+  `totalQuantity`, `localQuantity` and `supplierQuantity`, each a
+  `NumberSearchInput`.
+- Optional `inventory` field on all five product-search inputs that accept it
+  upstream: `ProductSearchInput`, `CategoryProductSearchInput`,
+  `ProductSearchByCategoryInput`, `ProductSearchSearchInput` and
+  `SparePartsMachineProductSearchInput`. No service or operation changes were
+  needed — these inputs are already passed through as variables, so the filter
+  is reachable from `productService.getProducts({ input })`,
+  `productSearchByCategory({ input })` and the `categoryProductSearchInput`
+  variable on the category queries.
+- `docs/content/guides/stock-filtering.md` and a README section covering the
+  operator semantics.
+- `tests/service/ProductInventoryFilter.integration.test.ts` — guards that the
+  filter is applied server-side and that `lessThan` really is inclusive.
+
+### Notes
+
+`NumberSearchInput`'s range operators are **inclusive** despite their names:
+`greaterThan: N` is stock **>= N** and `lessThan: N` is stock **<= N**.
+Never-stocked products have no inventory record and count as **0**. So:
+
+- in stock — `{ totalQuantity: { greaterThan: 1 } }` (>= 1; correctly includes
+  products with exactly 1 left)
+- out of stock — `{ totalQuantity: { equal: 0 } }`, or
+  `{ totalQuantity: { lessThan: 0 } }` (<= 0) to also catch negative balances
+
+Do **not** use `lessThan: 1` for out-of-stock — it means <= 1 and includes
+in-stock products with one item remaining.
+
+The committed schema snapshot is refreshed to the production introspection that
+carries this filter.
+
+---
+
 ## [0.14.0] - 2026-07-28
 
 **Breaking.** Removes the entire deprecated surface — every operation, field

package/README.md

@@ -238,6 +238,25 @@ that the whole entity was fetched.
 > [`src/generated/operations/`](./src/generated/operations/) (or the
 > [API docs](https://propeller-commerce.github.io/propeller-sdk-v2/)).
 
+### Stock filtering
+
+Product searches take an `inventory` filter, applied server-side — so
+`itemsFound` and `pages` describe the filtered set and can be used directly for
+paging:
+
+```typescript
+const inStock = await products.getProducts({
+  input: { page: 1, offset: 24, inventory: { totalQuantity: { greaterThan: 1 } } },
+});
+```
+
+`greaterThan` and `lessThan` are **inclusive** (`greaterThan: N` is stock >= N,
+`lessThan: N` is stock <= N), and never-stocked products count as 0. So in stock
+is `greaterThan: 1` and out of stock is `equal: 0` (or `lessThan: 0` to include
+negative balances) — **not** `lessThan: 1`, which means <= 1 and would include
+products with one item left. Full detail in the
+[stock filtering guide](https://propeller-commerce.github.io/propeller-sdk-v2/guides/stock-filtering).
+
 ## Direct GraphQL access
 
 For ad-hoc queries that aren't covered by a service:

package/dist/cjs/type/CategoryProductSearchInput.d.ts

@@ -7,6 +7,7 @@ import { ProductPriceFilterInput } from './ProductPriceFilterInput';
 import { ProductSortInput } from './ProductSortInput';
 import { SearchFieldsInput } from './SearchFieldsInput';
 import { DateSearchInput } from './DateSearchInput';
+import { ProductSearchInventoryFilterInput } from './ProductSearchInventoryFilterInput';
 /**
  Input object for CategoryProductSearchInput
  */
@@ -76,4 +77,9 @@ export interface CategoryProductSearchInput {
     skus?: string[];
     /** [Deprecated] Category path for hierarchical navigation. */
     path?: string;
+    /** Server-side stock filter. Operators are inclusive: `greaterThan: N` is
+        stock >= N and `lessThan: N` is stock <= N. Never-stocked products count
+        as 0. Filtering is applied upstream, so `itemsFound` / `pages` reflect
+        the filtered set. */
+    inventory?: ProductSearchInventoryFilterInput;
 }

package/dist/cjs/type/ProductSearchByCategoryInput.d.ts

@@ -8,6 +8,7 @@ import { ProductSearchSortInput } from './ProductSearchSortInput';
 import { ProductSearchTextFilterInput } from './ProductSearchTextFilterInput';
 import { ProductStatus } from '../enum/ProductStatus';
 import { YesNo } from '../enum/YesNo';
+import { ProductSearchInventoryFilterInput } from './ProductSearchInventoryFilterInput';
 /**
  Input object for ProductSearchByCategoryInput
  */
@@ -82,4 +83,9 @@ export interface ProductSearchByCategoryInput {
     applyOrderlists?: boolean;
     /** Order list IDs to apply for filtering */
     orderlistIds?: number[];
+    /** Server-side stock filter. Operators are inclusive: `greaterThan: N` is
+        stock >= N and `lessThan: N` is stock <= N. Never-stocked products count
+        as 0. Filtering is applied upstream, so `itemsFound` / `pages` reflect
+        the filtered set. */
+    inventory?: ProductSearchInventoryFilterInput;
 }

package/dist/cjs/type/ProductSearchInput.d.ts

@@ -7,6 +7,7 @@ import { ProductPriceFilterInput } from './ProductPriceFilterInput';
 import { ProductSortInput } from './ProductSortInput';
 import { SearchFieldsInput } from './SearchFieldsInput';
 import { DateSearchInput } from './DateSearchInput';
+import { ProductSearchInventoryFilterInput } from './ProductSearchInventoryFilterInput';
 /**
  Input object for ProductSearchInput
  */
@@ -78,4 +79,9 @@ export interface ProductSearchInput {
     applyOrderlists?: boolean;
     /** List orderlists to apply */
     orderlistIds?: number[];
+    /** Server-side stock filter. Operators are inclusive: `greaterThan: N` is
+        stock >= N and `lessThan: N` is stock <= N. Never-stocked products count
+        as 0. Filtering is applied upstream, so `itemsFound` / `pages` reflect
+        the filtered set. */
+    inventory?: ProductSearchInventoryFilterInput;
 }

package/dist/cjs/type/ProductSearchInventoryFilterInput.d.ts

@@ -0,0 +1,30 @@
+import { NumberSearchInput } from './NumberSearchInput';
+/**
+ Input object for ProductSearchInventoryFilterInput
+
+ Server-side stock filter for product search. Because the filtering happens
+ upstream, the pagination counts on the response (`itemsFound`, `pages`)
+ describe the *filtered* set, so they can be used directly for paging.
+
+ Products that were never stocked have no inventory record and count as **0**.
+
+ `NumberSearchInput` operators are inclusive despite their names —
+ `greaterThan: N` means stock **>= N** and `lessThan: N` means stock **<= N**:
+
+ - In stock — `{ totalQuantity: { greaterThan: 1 } }` (>= 1). This includes
+   products with exactly 1 in stock, which is correct.
+ - Out of stock — `{ totalQuantity: { equal: 0 } }` (exactly 0, including
+   never-stocked products), or `{ totalQuantity: { lessThan: 0 } }` (<= 0) to
+   also catch negative balances.
+
+ Do **not** use `lessThan: 1` for out-of-stock: it means <= 1 and therefore
+ includes in-stock products that have exactly 1 remaining.
+ */
+export interface ProductSearchInventoryFilterInput {
+    /** Filter on the total available quantity across all warehouses */
+    totalQuantity?: NumberSearchInput;
+    /** Filter on the local warehouse quantity */
+    localQuantity?: NumberSearchInput;
+    /** Filter on the supplier warehouse quantity */
+    supplierQuantity?: NumberSearchInput;
+}

package/dist/cjs/type/ProductSearchInventoryFilterInput.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/type/ProductSearchSearchInput.d.ts

@@ -8,6 +8,7 @@ import { ProductSearchSortInput } from './ProductSearchSortInput';
 import { ProductSearchTextFilterInput } from './ProductSearchTextFilterInput';
 import { ProductStatus } from '../enum/ProductStatus';
 import { YesNo } from '../enum/YesNo';
+import { ProductSearchInventoryFilterInput } from './ProductSearchInventoryFilterInput';
 /**
  Input object for ProductSearchSearchInput
  */
@@ -84,4 +85,9 @@ export interface ProductSearchSearchInput {
     applyOrderlists?: boolean;
     /** Order list IDs to apply for filtering */
     orderlistIds?: number[];
+    /** Server-side stock filter. Operators are inclusive: `greaterThan: N` is
+        stock >= N and `lessThan: N` is stock <= N. Never-stocked products count
+        as 0. Filtering is applied upstream, so `itemsFound` / `pages` reflect
+        the filtered set. */
+    inventory?: ProductSearchInventoryFilterInput;
 }

package/dist/cjs/type/SparePartsMachineProductSearchInput.d.ts

@@ -7,6 +7,7 @@ import { ProductPriceFilterInput } from './ProductPriceFilterInput';
 import { ProductSortInput } from './ProductSortInput';
 import { SearchFieldsInput } from './SearchFieldsInput';
 import { DateSearchInput } from './DateSearchInput';
+import { ProductSearchInventoryFilterInput } from './ProductSearchInventoryFilterInput';
 /**
  Input object for SparePartsMachineProductSearchInput
  */
@@ -74,4 +75,9 @@ export interface SparePartsMachineProductSearchInput {
     skus?: string[];
     /** [Deprecated] Category path for hierarchical navigation. */
     path?: string;
+    /** Server-side stock filter. Operators are inclusive: `greaterThan: N` is
+        stock >= N and `lessThan: N` is stock <= N. Never-stocked products count
+        as 0. Filtering is applied upstream, so `itemsFound` / `pages` reflect
+        the filtered set. */
+    inventory?: ProductSearchInventoryFilterInput;
 }

package/dist/cjs/type/index.d.ts

@@ -531,6 +531,7 @@ export * from './ProductPrice';
 export * from './ProductPriceFilterInput';
 export * from './ProductRangeFilterInput';
 export * from './ProductSearchInput';
+export * from './ProductSearchInventoryFilterInput';
 export * from './ProductSortInput';
 export * from './ProductTextFilterInput';
 export * from './ProductsResponse';

package/dist/cjs/type/index.js

@@ -547,6 +547,7 @@ __exportStar(require("./ProductPrice"), exports);
 __exportStar(require("./ProductPriceFilterInput"), exports);
 __exportStar(require("./ProductRangeFilterInput"), exports);
 __exportStar(require("./ProductSearchInput"), exports);
+__exportStar(require("./ProductSearchInventoryFilterInput"), exports);
 __exportStar(require("./ProductSortInput"), exports);
 __exportStar(require("./ProductTextFilterInput"), exports);
 __exportStar(require("./ProductsResponse"), exports);

package/dist/esm/type/ProductSearchInventoryFilterInput.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/type/index.js

@@ -531,6 +531,7 @@ export * from './ProductPrice.js';
 export * from './ProductPriceFilterInput.js';
 export * from './ProductRangeFilterInput.js';
 export * from './ProductSearchInput.js';
+export * from './ProductSearchInventoryFilterInput.js';
 export * from './ProductSortInput.js';
 export * from './ProductTextFilterInput.js';
 export * from './ProductsResponse.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@propeller-commerce/propeller-sdk-v2",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "TypeScript GraphQL client for Propeller eCommerce V2 Platform - works with React, Vue, Angular and all JavaScript frameworks",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",