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 customer returns and claims to the storefront SDK
Damian Legawiec680a0eda9bd0
diff --git a/packages/sdk/src/store-client.ts b/packages/sdk/src/store-client.tsindex c99759ca8b..ad6e86e18b 100644--- a/packages/sdk/src/store-client.ts+++ b/packages/sdk/src/store-client.ts@@ -15,6 +15,7 @@ import type {Category,CategoryListParams,Channel,+ Claim,CompletePaymentSessionParams,CompletePaymentSetupSessionParams,Country,@@ -44,6 +45,7 @@ import type {RegisterParams,RequestPasswordResetParams,ResetPasswordParams,+ Return,StockLocation,StoreCredit,UpdateCartParams,@@ -651,6 +653,102 @@ export class StoreClient {...options,params: getParams(params),}),++ /**+ * Returns the customer opened on this order.+ *+ * Opening one is all a customer can do — approving, receiving and+ * refunding are the merchant's, through the Admin API. Whether they may+ * open one at all is store policy, enforced by a `returns.create.validate`+ * handler on the server; a rejected request comes back as a 422.+ */+ returns: {+ list: (+ orderId: string,+ params?: ListParams & Record<string, unknown>,+ options?: RequestOptions,+ ): Promise<PaginatedResponse<Return>> =>+ this.request<PaginatedResponse<Return>>('GET', `/orders/${orderId}/returns`, {+ ...options,+ params: params ? transformListParams({ ...params }) : undefined,+ }),++ get: (+ orderId: string,+ id: string,+ params?: { expand?: string[] },+ options?: RequestOptions,+ ): Promise<Return> =>+ this.request<Return>('GET', `/orders/${orderId}/returns/${id}`, {+ ...options,+ params: getParams(params),+ }),++ /**+ * @param params.items the fulfilled units coming back. `fulfillment_item_id`+ * rather than a line item id, because a return is against a shipped unit.+ */+ create: (+ orderId: string,+ params: {+ items: Array<{ fulfillment_item_id: string; quantity: number }>+ reason_id?: string+ memo?: string+ },+ options?: RequestOptions,+ ): Promise<Return> =>+ this.request<Return>('POST', `/orders/${orderId}/returns`, {+ ...options,+ body: params,+ }),+ },++ /**+ * Claims the customer filed on this order — a damaged, missing or wrong+ * item. Nothing has to come back, so unlike a return this works whether or+ * not the order shipped. Approving, denying and resolving are the+ * merchant's.+ */+ claims: {+ list: (+ orderId: string,+ params?: ListParams & Record<string, unknown>,+ options?: RequestOptions,+ ): Promise<PaginatedResponse<Claim>> =>+ this.request<PaginatedResponse<Claim>>('GET', `/orders/${orderId}/claims`, {+ ...options,+ params: params ? transformListParams({ ...params }) : undefined,+ }),++ get: (+ orderId: string,+ id: string,+ params?: { expand?: string[] },+ options?: RequestOptions,+ ): Promise<Claim> =>+ this.request<Claim>('GET', `/orders/${orderId}/claims/${id}`, {+ ...options,+ params: getParams(params),+ }),++ /**+ * @param params.claim_type one of the store's configured claim types+ * (`damaged`, `missing`, `wrong_item`, `other` by default)+ */+ create: (+ orderId: string,+ params: {+ items: Array<{ line_item_id: string; quantity: number; description?: string }>+ claim_type?: string+ memo?: string+ },+ options?: RequestOptions,+ ): Promise<Claim> =>+ this.request<Claim>('POST', `/orders/${orderId}/claims`, {+ ...options,+ body: params,+ }),+ },}// ============================================diff --git a/packages/sdk/src/types/index.ts b/packages/sdk/src/types/index.tsindex 2d03292604..5cebaab64c 100644--- a/packages/sdk/src/types/index.ts+++ b/packages/sdk/src/types/index.ts@@ -8,6 +8,8 @@ export type {Cart,Category,Channel,+ Claim,+ ClaimLineItem,Country,CreditCard,Currency,@@ -41,8 +43,10 @@ export type {Product,Promotion,Refund,+ Return,ReturnAuthorization,ReturnItem,+ ReturnLineItem,State,StockLocation,StoreCredit,diff --git a/packages/sdk/tests/mocks/handlers.ts b/packages/sdk/tests/mocks/handlers.tsindex 8f8a991270..0ade68a255 100644--- a/packages/sdk/tests/mocks/handlers.ts+++ b/packages/sdk/tests/mocks/handlers.ts@@ -37,6 +37,25 @@ export const fixtures = {payment_status: 'paid',items: [],},+ return: {+ id: 'ret_1',+ number: 'RET123456789',+ status: 'requested',+ order_id: 'or_1',+ refund_total: '19.99',+ display_refund_total: '$19.99',+ return_line_items: [],+ },+ claim: {+ id: 'claim_1',+ number: 'CLM123456789',+ status: 'open',+ claim_type: 'damaged',+ order_id: 'or_1',+ refund_total: '19.99',+ display_refund_total: '$19.99',+ claim_line_items: [],+ },lineItem: {id: 'li_1',quantity: 2,@@ -385,6 +404,28 @@ export const handlers = [// Orders (read-only, single lookup)http.get(`${API_PREFIX}/orders/:id`, () => HttpResponse.json(fixtures.order)),+ // Customer self-service returns and claims+ http.get(`${API_PREFIX}/orders/:orderId/returns`, () =>+ HttpResponse.json({+ data: [fixtures.return],+ meta: { page: 1, limit: 25, count: 1, pages: 1, from: 1, to: 1 },+ }),+ ),+ http.get(`${API_PREFIX}/orders/:orderId/returns/:id`, () => HttpResponse.json(fixtures.return)),+ http.post(`${API_PREFIX}/orders/:orderId/returns`, () =>+ HttpResponse.json(fixtures.return, { status: 201 }),+ ),+ http.get(`${API_PREFIX}/orders/:orderId/claims`, () =>+ HttpResponse.json({+ data: [fixtures.claim],+ meta: { page: 1, limit: 25, count: 1, pages: 1, from: 1, to: 1 },+ }),+ ),+ http.get(`${API_PREFIX}/orders/:orderId/claims/:id`, () => HttpResponse.json(fixtures.claim)),+ http.post(`${API_PREFIX}/orders/:orderId/claims`, () =>+ HttpResponse.json(fixtures.claim, { status: 201 }),+ ),+// Customerhttp.get(`${API_PREFIX}/customers/me`, () => HttpResponse.json(fixtures.user)),diff --git a/packages/sdk/tests/post-sale.test.ts b/packages/sdk/tests/post-sale.test.tsnew file mode 100644index 0000000000..dd3be3a788--- /dev/null+++ b/packages/sdk/tests/post-sale.test.ts@@ -0,0 +1,81 @@+import { beforeAll, describe, expect, it } from 'vitest'+import type { Client } from '../src'+import { createTestClient } from './helpers'++describe('customer self-service returns and claims', () => {+ let client: Client+ beforeAll(() => {+ client = createTestClient()+ })++ const opts = { token: 'user-jwt' }++ describe('returns', () => {+ it('lists returns the customer opened on an order', async () => {+ const result = await client.orders.returns.list('or_abc123', undefined, opts)++ expect(result.data).toHaveLength(1)+ expect(result.data[0].number).toBe('RET123456789')+ expect(result.data[0].status).toBe('requested')+ })++ it('fetches a single return', async () => {+ const result = await client.orders.returns.get('or_abc123', 'ret_1', undefined, opts)++ expect(result.id).toBe('ret_1')+ })++ // Against fulfilled units, not line items — a return is of something shipped.+ it('opens a return for fulfilled units', async () => {+ const result = await client.orders.returns.create(+ 'or_abc123',+ {+ items: [{ fulfillment_item_id: 'fi_1', quantity: 1 }],+ memo: 'Wrong size',+ },+ opts,+ )++ expect(result.status).toBe('requested')+ expect(result.number).toMatch(/^RET/)+ })++ it('works for a guest holding the order token', async () => {+ const result = await client.orders.returns.list('or_abc123', undefined, {+ spreeToken: 'guest-token',+ })++ expect(result.data).toBeDefined()+ })+ })++ describe('claims', () => {+ it('lists claims on an order', async () => {+ const result = await client.orders.claims.list('or_abc123', undefined, opts)++ expect(result.data).toHaveLength(1)+ expect(result.data[0].claim_type).toBe('damaged')+ })++ it('fetches a single claim', async () => {+ const result = await client.orders.claims.get('or_abc123', 'claim_1', undefined, opts)++ expect(result.id).toBe('claim_1')+ })++ // Against ordered line items — nothing has to have shipped to report a problem.+ it('files a claim against ordered items', async () => {+ const result = await client.orders.claims.create(+ 'or_abc123',+ {+ items: [{ line_item_id: 'li_1', quantity: 1, description: 'Arrived cracked' }],+ claim_type: 'damaged',+ },+ opts,+ )++ expect(result.status).toBe('open')+ expect(result.number).toMatch(/^CLM/)+ })+ })+})