Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add collections to the storefront SDK
Damian Legawieca8b11ecb409a
diff --git a/.changeset/collections-sdk.md b/.changeset/collections-sdk.mdnew file mode 100644index 0000000000..0c6eb424c3--- /dev/null+++ b/.changeset/collections-sdk.md@@ -0,0 +1,20 @@+---+'@spree/admin-sdk': patch+'@spree/sdk': minor+---++Collections reach both SDKs.++`@spree/sdk` (storefront):++- `collections.list()` / `collections.get(idOrPermalink)` — the flat, merchandising-driven groupings ("Summer Sale", "New Arrivals"), whether membership is curated by hand or maintained from rules.+- `collections.products.list(idOrPermalink, params)` — a collection's product listing page. Takes the same filters and sorts as `products.list`, and when `sort` is omitted the collection's own `sort_order` applies, so a shopper sees the ordering the merchant chose (including their manual arrangement).+- `in_collection` on `ProductListParams`, for composing a collection filter into a wider product query.++`@spree/admin-sdk` (back office):++- `collections` CRUD, with reordering as a plain 1-based `position` on update rather than a separate action — collections are a flat list. Nested `collections.products` covers membership, ordering and `reposition`, plus custom fields and translations.+- `collectionRules.types()` enumerates the registered rule kinds, so a rule a plugin registers shows up without an SDK release.+- `products.bulkAddToCollections` / `bulkRemoveFromCollections`, and `collection_ids` on product create/update.+- `rules` on a collection is expand-gated (`?expand=rules`), matching `custom_fields` — a listing no longer ships every collection's full rule set.+- `hide_from_nav` is gone from the category params. Nothing read it.diff --git a/packages/sdk/src/store-client.ts b/packages/sdk/src/store-client.tsindex ad6e86e18b..d53da63830 100644--- a/packages/sdk/src/store-client.ts+++ b/packages/sdk/src/store-client.ts@@ -16,6 +16,8 @@ import type {CategoryListParams,Channel,Claim,+ Collection,+ CollectionListParams,CompletePaymentSessionParams,CompletePaymentSetupSessionParams,Country,@@ -174,6 +176,57 @@ export class StoreClient {}),}+ /**+ * Collections — flat, merchandising-driven product groupings ("Summer Sale",+ * "New Arrivals"). Membership may be curated by the merchant or maintained+ * automatically from rules; either way it reads the same from the storefront.+ */+ readonly collections = {+ /**+ * List collections+ */+ list: (+ params?: CollectionListParams,+ options?: RequestOptions,+ ): Promise<PaginatedResponse<Collection>> =>+ this.request<PaginatedResponse<Collection>>('GET', '/collections', {+ ...options,+ params: transformListParams({ ...params }),+ }),++ /**+ * Get a collection by ID or permalink+ */+ get: (+ idOrPermalink: string,+ params?: { expand?: string[]; fields?: string[] },+ options?: RequestOptions,+ ): Promise<Collection> =>+ this.request<Collection>('GET', `/collections/${idOrPermalink}`, {+ ...options,+ params: getParams(params),+ }),++ products: {+ /**+ * List the products in a collection — the collection's product listing+ * page. Accepts the same filters and sorts as `products.list`; when+ * `sort` is omitted the collection's own `sort_order` applies, so a+ * merchant's chosen ordering (including their manual arrangement) is+ * what a shopper sees by default.+ */+ list: (+ idOrPermalink: string,+ params?: ProductListParams,+ options?: RequestOptions,+ ): Promise<PaginatedResponse<Product>> =>+ this.request<PaginatedResponse<Product>>('GET', `/collections/${idOrPermalink}/products`, {+ ...options,+ params: transformListParams({ ...params }),+ }),+ },+ }+// ============================================// Countries, Currencies & Locales// ============================================diff --git a/packages/sdk/src/types/index.ts b/packages/sdk/src/types/index.tsindex 5cebaab64c..49d96ef261 100644--- a/packages/sdk/src/types/index.ts+++ b/packages/sdk/src/types/index.ts@@ -10,6 +10,7 @@ export type {Channel,Claim,ClaimLineItem,+ Collection,Country,CreditCard,Currency,@@ -136,6 +137,12 @@ export interface ProductListParams extends ListParams {in_category?: string/** Filter: products in any of the given categories (includes descendants, OR logic) */in_categories?: string[]+ /**+ * Filter: products in a collection (flat — collections have no hierarchy).+ * Prefer `client.collections.products.list()` for a collection listing: it+ * applies the collection's own `sort_order` as the default.+ */+ in_collection?: string/** Any additional Ransack predicate */[key: string]: string | number | boolean | (string | number)[] | undefined}@@ -151,6 +158,15 @@ export interface CategoryListParams extends ListParams {[key: string]: string | number | boolean | (string | number)[] | undefined}+export interface CollectionListParams extends ListParams {+ /** Sort order, e.g. 'position', 'name', '-created_at' */+ sort?: string+ /** Filter: name contains */+ name_cont?: string+ /** Any additional Ransack predicate */+ [key: string]: string | number | boolean | (string | number)[] | undefined+}+export interface OrderListParams extends ListParams {/** Sort order, e.g. 'completed_at desc' */sort?: stringdiff --git a/packages/sdk/tests/collections.test.ts b/packages/sdk/tests/collections.test.tsnew file mode 100644index 0000000000..21f53a3183--- /dev/null+++ b/packages/sdk/tests/collections.test.ts@@ -0,0 +1,53 @@+import { beforeAll, describe, expect, it } from 'vitest'+import type { Client } from '../src'+import { createTestClient } from './helpers'+import { fixtures } from './mocks/handlers'++describe('collections', () => {+ let client: Client+ beforeAll(() => {+ client = createTestClient()+ })++ describe('list', () => {+ it('returns paginated collections', async () => {+ const result = await client.collections.list()++ expect(result.data).toHaveLength(1)+ expect(result.data[0].name).toBe(fixtures.collection.name)+ expect(result.meta.page).toBe(1)+ })+ })++ describe('get', () => {+ it('returns a collection by ID', async () => {+ const result = await client.collections.get('coll_1')+ expect(result.name).toBe(fixtures.collection.name)+ })++ it('returns a collection by permalink', async () => {+ const result = await client.collections.get('summer-sale')+ expect(result.permalink).toBe(fixtures.collection.permalink)+ })+ })++ describe('products.list', () => {+ it("returns the collection's products", async () => {+ const result = await client.collections.products.list('coll_1')++ expect(result.data).toHaveLength(1)+ expect(result.data[0].name).toBe(fixtures.product.name)+ expect(result.meta.page).toBe(1)+ })++ it('forwards filters and sort to the listing', async () => {+ const result = await client.collections.products.list('summer-sale', {+ sort: '-price',+ in_stock: true,+ limit: 10,+ })++ expect(result.data).toHaveLength(1)+ })+ })+})diff --git a/packages/sdk/tests/mocks/handlers.ts b/packages/sdk/tests/mocks/handlers.tsindex 0ade68a255..77d58dc05b 100644--- a/packages/sdk/tests/mocks/handlers.ts+++ b/packages/sdk/tests/mocks/handlers.ts@@ -87,6 +87,13 @@ export const fixtures = {permalink: 'clothing/shirts',position: 1,},+ collection: {+ id: 'coll_1',+ name: 'Summer Sale',+ permalink: 'summer-sale',+ position: 1,+ sort_order: 'best_selling',+ },country: {iso: 'US',iso3: 'USA',@@ -192,6 +199,17 @@ export const handlers = [http.get(`${API_PREFIX}/categories/:id`, () => HttpResponse.json(fixtures.category)),+ // Collections+ http.get(`${API_PREFIX}/collections`, () =>+ HttpResponse.json({ data: [fixtures.collection], meta: paginationMeta }),+ ),++ http.get(`${API_PREFIX}/collections/:id/products`, () =>+ HttpResponse.json({ data: [fixtures.product], meta: paginationMeta }),+ ),++ http.get(`${API_PREFIX}/collections/:id`, () => HttpResponse.json(fixtures.collection)),+// Countrieshttp.get(`${API_PREFIX}/countries`, () => HttpResponse.json({ data: [fixtures.country] })),