Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Add collections to the storefront SDK

Damian Legawieca8b11ecb409a
diff --git a/.changeset/collections-sdk.md b/.changeset/collections-sdk.md
new file mode 100644
index 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.ts
index 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.ts
index 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?: string
diff --git a/packages/sdk/tests/collections.test.ts b/packages/sdk/tests/collections.test.ts
new file mode 100644
index 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.ts
index 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)),
+
// Countries
http.get(`${API_PREFIX}/countries`, () => HttpResponse.json({ data: [fixtures.country] })),