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 support for newsletter unsubscribe workflow in Store SDK (#14329)

Damian Legawiec9b4414f8f678
diff --git a/packages/admin-sdk/CHANGELOG.md b/packages/admin-sdk/CHANGELOG.md
index 179792d1fd..6b18833338 100644
--- a/packages/admin-sdk/CHANGELOG.md
+++ b/packages/admin-sdk/CHANGELOG.md
@@ -1,5 +1,11 @@
# @spree/admin-sdk
+## 0.6.1
+
+### Patch Changes
+
+- `Customer` supports the new `newsletter_subscriber` expand — pass `expand: ['newsletter_subscriber']` to `customers.get`/`customers.list` to include the customer's store-scoped newsletter subscription.
+
## 0.6.0
This is the Admin API surface the 5.6 React Dashboard consumes — hosts installing `@spree/[email protected]` from the registry need this version; 0.5.0 lacks exports the dashboard imports.
diff --git a/packages/admin-sdk/package.json b/packages/admin-sdk/package.json
index 6b5769c344..11aef95e3e 100644
--- a/packages/admin-sdk/package.json
+++ b/packages/admin-sdk/package.json
@@ -1,6 +1,6 @@
{
"name": "@spree/admin-sdk",
- "version": "0.6.0",
+ "version": "0.6.1",
"description": "Official TypeScript SDK for Spree Commerce Admin API",
"type": "module",
"main": "./dist/index.cjs",
diff --git a/packages/sdk/.changeset/newsletter-unsubscribe.md b/packages/sdk/.changeset/newsletter-unsubscribe.md
new file mode 100644
index 0000000000..2aec38a62f
--- /dev/null
+++ b/packages/sdk/.changeset/newsletter-unsubscribe.md
@@ -0,0 +1,5 @@
+---
+"@spree/sdk": minor
+---
+
+Add newsletter unsubscribe endpoints. `newsletterSubscribers.requestUnsubscribe({ email })` asks the store to fire a `newsletter_subscriber.unsubscribe_requested` webhook event carrying an unsubscribe token (always 202, so email existence is never revealed). `newsletterSubscribers.delete(id, { token })` removes a subscription using that token from an email link, or — with a customer JWT instead of the token — removes the signed-in customer's own subscription. `Customer` now exposes the store-scoped `newsletter_subscriber` on `GET /customers/me`, which is where a signed-in customer reads the subscription id.
diff --git a/packages/sdk/src/store-client.ts b/packages/sdk/src/store-client.ts
index 0613634034..0f8f37d79d 100644
--- a/packages/sdk/src/store-client.ts
+++ b/packages/sdk/src/store-client.ts
@@ -631,6 +631,34 @@ export class StoreClient {
...options,
body: params,
}),
+
+ /**
+ * Request an unsubscribe link for an email address. When a subscriber
+ * exists, a `newsletter_subscriber.unsubscribe_requested` webhook event
+ * fires carrying the unsubscribe token; the response is always 202 to
+ * prevent email enumeration. `redirect_url` is dropped from the webhook
+ * payload when it's not in the store's allowed origins.
+ */
+ requestUnsubscribe: (
+ params: { email: string; redirect_url?: string },
+ options?: RequestOptions,
+ ): Promise<void> =>
+ this.request<void>('POST', '/newsletter_subscribers/request_unsubscribe', {
+ ...options,
+ body: params,
+ }),
+
+ /**
+ * Unsubscribe from the newsletter. Pass a JWT via `options.token` for a
+ * signed-in customer removing their own subscription (its id comes from
+ * `customer.newsletter_subscriber` on GET /customers/me), or
+ * `params.token` with the unsubscribe token from an email link.
+ */
+ delete: (id: string, params?: { token?: string }, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/newsletter_subscribers/${id}`, {
+ ...options,
+ params: params?.token ? { token: params.token } : undefined,
+ }),
}
readonly customer = {
diff --git a/packages/sdk/tests/mocks/handlers.ts b/packages/sdk/tests/mocks/handlers.ts
index 0aceb0dc40..165a7b8cb9 100644
--- a/packages/sdk/tests/mocks/handlers.ts
+++ b/packages/sdk/tests/mocks/handlers.ts
@@ -635,4 +635,14 @@ export const handlers = [
verified_at: '2026-01-02T00:00:00Z',
}),
),
+
+ http.post(
+ `${API_PREFIX}/newsletter_subscribers/request_unsubscribe`,
+ () => new HttpResponse(null, { status: 202 }),
+ ),
+
+ http.delete(
+ `${API_PREFIX}/newsletter_subscribers/:id`,
+ () => new HttpResponse(null, { status: 204 }),
+ ),
]
diff --git a/packages/sdk/tests/newsletter-subscribers.test.ts b/packages/sdk/tests/newsletter-subscribers.test.ts
index ecbb37a8d3..a30f48c659 100644
--- a/packages/sdk/tests/newsletter-subscribers.test.ts
+++ b/packages/sdk/tests/newsletter-subscribers.test.ts
@@ -110,4 +110,69 @@ describe('newsletterSubscribers', () => {
expect(capturedBody.token).toBe('verify-token-xyz')
})
})
+
+ describe('requestUnsubscribe', () => {
+ it('resolves on the always-202 response', async () => {
+ await expect(
+ client.newsletterSubscribers.requestUnsubscribe({ email: '[email protected]' }),
+ ).resolves.toBeUndefined()
+ })
+
+ it('sends the email and redirect_url in the request body', async () => {
+ let capturedBody: Record<string, unknown> = {}
+ server.use(
+ http.post(
+ `${API_PREFIX}/newsletter_subscribers/request_unsubscribe`,
+ async ({ request }) => {
+ capturedBody = (await request.json()) as Record<string, unknown>
+ return new HttpResponse(null, { status: 202 })
+ },
+ ),
+ )
+
+ await client.newsletterSubscribers.requestUnsubscribe({
+ email: '[email protected]',
+ redirect_url: 'https://storefront.example.com/newsletter/unsubscribed',
+ })
+
+ expect(capturedBody.email).toBe('[email protected]')
+ expect(capturedBody.redirect_url).toBe(
+ 'https://storefront.example.com/newsletter/unsubscribed',
+ )
+ })
+ })
+
+ describe('delete', () => {
+ it('unsubscribes with an unsubscribe token as a query param', async () => {
+ let capturedUrl: URL | null = null
+ server.use(
+ http.delete(`${API_PREFIX}/newsletter_subscribers/:id`, ({ request }) => {
+ capturedUrl = new URL(request.url)
+ return new HttpResponse(null, { status: 204 })
+ }),
+ )
+
+ await client.newsletterSubscribers.delete('sub_1', { token: 'unsubscribe-token-xyz' })
+
+ expect(capturedUrl?.pathname).toBe('/api/v3/store/newsletter_subscribers/sub_1')
+ expect(capturedUrl?.searchParams.get('token')).toBe('unsubscribe-token-xyz')
+ })
+
+ it('unsubscribes an authenticated customer via JWT without a token param', async () => {
+ let capturedAuth: string | null = null
+ let capturedUrl: URL | null = null
+ server.use(
+ http.delete(`${API_PREFIX}/newsletter_subscribers/:id`, ({ request }) => {
+ capturedAuth = request.headers.get('Authorization')
+ capturedUrl = new URL(request.url)
+ return new HttpResponse(null, { status: 204 })
+ }),
+ )
+
+ await client.newsletterSubscribers.delete('sub_1', undefined, { token: 'user-jwt' })
+
+ expect(capturedAuth).toBe('Bearer user-jwt')
+ expect(capturedUrl?.searchParams.has('token')).toBe(false)
+ })
+ })
})