Skip to main content

@acromedia/gesso-shopware-middleware

Server-side Gesso API-middleware provider for Shopware 6. It implements the Provider contract from @acromedia/gesso-api-middleware and routes /api/middleware/shopware/{action} to Shopware's REST Store API (/store-api) and, for elevated operations, its Admin API (/api).

It is the server-side companion to the browser-side @acromedia/gesso-shopware commerce plugin: anything that needs a secret (the Admin API client credentials) or a privileged lookup lives here, not in the bundle that ships to the browser.

Routing​

slug[0] is the provider key (shopware); slug[1] is the action.

ActionAPIEndpoint(s)Auth
addressStore API/store-api/account/addresssw-access-key + sw-context-token
customerStore API/store-api/account/customer, change-profilesw-access-key + sw-context-token
ordersStore API/store-api/ordersw-access-key + sw-context-token
customersAdmin API/api/search/customerOAuth2 client_credentials bearer
paymentsAdmin API/api/search/payment-methodOAuth2 client_credentials bearer

Storefront, customer-scoped actions (address, customer, orders) read the logged-in customer's sw-context-token from the next-auth session JWT (a forwarded sw-context-token request header is honoured as a fallback). Shopware rotates that token on stateful calls; the provider echoes the rotated value back in an sw-context-token response header so the client can persist it.

The admin-scoped actions (customers, payments) never touch the customer session — they authenticate the integration itself via the Admin API OAuth2 client_credentials grant.

Transport client (SW-0a outcome)​

This package uses the official @shopware/api-client SDK (pinned to an exact version) as a thin proxy for both APIs, wrapped in src/rest.ts:

  • storeClient() builds a per-request createAPIClient — sets the sales-channel sw-access-key, seeds the customer's sw-context-token, and reports the rotated token through the config's onContextChanged callback (backed by the SDK's onContextChanged hook). This mirrors how @acromedia/gesso-shopware wraps the same SDK.
  • adminClient() builds a createAdminAPIClient with a client_credentials grant. The SDK performs POST /api/oauth/token, attaches the Authorization: Bearer … header, and refreshes automatically once the bearer (expires_in, ≈ 600 s) lapses. A single memoized client per host + integration id keeps the token cached across requests, staying within Shopware SaaS's POST /api/oauth/token rate limit (10/min).

SW-0a spike result: @shopware/api-client was validated for this package's build and is used directly (no typed-fetch fallback was needed):

  • ESM/transpile — it builds cleanly through this package's dual ESM + CJS tsup pipeline (pnpm --filter @acromedia/gesso-shopware-middleware build).
  • Token forwarding — the MSW suite (src/rest.test.ts) asserts the sales-channel sw-access-key, the rotated sw-context-token, and the admin Authorization: Bearer header are all forwarded on the wire, and that the admin token is cached and refreshed on expiry. None of this needs a live store.

Configuration​

Read from the environment (see example.env):

Env varPurpose
NEXT_PUBLIC_SHOPWARE_STOREFRONT_URLBase host of the store. Store API and Admin API both live under it.
GESSO_SHOPWARE_ACCESS_KEYSales-channel access key, sent as sw-access-key (Store API).
GESSO_SHOPWARE_ADMIN_CLIENT_IDAdmin API integration id (OAuth client_credentials). Server-only.
GESSO_SHOPWARE_ADMIN_CLIENT_SECRETAdmin API integration secret. Server-only.
GESSO_JWT_SECRETnext-auth secret used to read the storefront session JWT.

NEXT_PUBLIC_SHOPWARE_ACCESS_KEY is accepted as a fallback for the access key so a single value can be shared with the browser-side @acromedia/gesso-shopware plugin. See the Shopware SaaS provisioning runbook (in the repo root) for how to obtain each credential.

Usage​

Register the provider with the Gesso API middleware in a Next.js catch-all route (pages/api/middleware/[...slug].ts):

import GessoAPIMiddleware from '@acromedia/gesso-api-middleware';
import shopware from '@acromedia/gesso-shopware-middleware';

export default GessoAPIMiddleware({ shopware });

Development​

pnpm --filter @acromedia/gesso-shopware-middleware type-check
pnpm --filter @acromedia/gesso-shopware-middleware lint
pnpm --filter @acromedia/gesso-shopware-middleware test   # Vitest + MSW
pnpm --filter @acromedia/gesso-shopware-middleware build  # tsup → dist + tarball

The test suite is Vitest + MSW; every Shopware response is mocked, so no live store is required. Set LIVE_TESTS=true (with the env vars above pointing at a real store) to disable the mocks.

References​