@doswiftly/storefront-sdk 22.1.0 → 22.2.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 22.2.0
+
+### Minor Changes
+
+- 27934d1: Server `getStorefrontClient`: forwarded-IP signing is now **opt-in** via `getBuyerIp`.
+
+  Previously the server client auto-read the buyer IP through `next/headers` on every
+  request. That is a dynamic API and is illegal in statically-generated / ISR routes —
+  it crashed such pages with "Page changed from static to dynamic at runtime".
+
+  Forwarded-IP is now wired only when you pass `getBuyerIp`, which you should do **only
+  on routes that are already dynamic** (per-request rendered). Without it the client is
+  a fully static-safe, inert pass-through.
+
+  Migration — to keep forwarding the buyer IP, pass `getBuyerIp` on your dynamic routes:
+
+  ```typescript
+  import { headers } from "next/headers";
+
+  getStorefrontClient({
+    apiUrl,
+    shopSlug,
+    getBuyerIp: async () => (await headers()).get("cf-connecting-ip"),
+  });
+  ```
+
 ## 22.1.0
 
 ### Minor Changes

package/README.md

@@ -1078,34 +1078,32 @@ middleware: [
 ### Forwarding the buyer IP for rate limiting
 
 When a storefront fetches on the server, the API sees the storefront server's IP for
-every buyer, so per-IP rate limits collapse onto a single address. The server client
-forwards the buyer's real IP so rate limiting applies per buyer again.
+every buyer, so per-IP rate limits collapse onto a single address. Forwarding the
+buyer's real IP restores per-buyer limits.
 
-**Automatic on the server — nothing to wire.** Call `getStorefrontClient` as usual:
+**Opt-in — supply `getBuyerIp`.** Reading the buyer IP requires a request-scoped
+dynamic API (e.g. `next/headers` `headers()`), which is **illegal in
+statically-generated / ISR routes** and would crash them ("static to dynamic at
+runtime"). So enable it **only on routes that are already dynamic** (per-request
+rendered):
 
 ```typescript
+import { headers } from 'next/headers';
+
+// In a DYNAMIC route/segment only — headers() forces dynamic rendering:
 const client = getStorefrontClient({
   apiUrl: process.env.DOSWIFTLY_API_URL!,
   shopSlug: process.env.DOSWIFTLY_SHOP_SLUG!,
+  getBuyerIp: async () => (await headers()).get('cf-connecting-ip'),
 });
 ```
 
-It applies only inside a server request with forwarding configured by your
-deployment, and is otherwise an inert pass-through — existing setups are unaffected.
+Without `getBuyerIp` the client never reads the IP and never signs — a fully
+static-safe, inert pass-through (static / ISR routes are unaffected). Signing also
+requires the secret `process.env.DOSWIFTLY_FORWARDED_IP_SECRET` (set by your
+deployment; override via `getForwardedIpSecret` for runtimes without `process.env`).
 **Server-only**: nothing IP-related reaches the browser.
 
-**Non-Next server runtimes** — supply the buyer IP yourself (e.g. from
-`cf-connecting-ip`), plus the signing secret if your runtime has no `process.env`:
-
-```typescript
-const client = getStorefrontClient({
-  apiUrl,
-  shopSlug,
-  getBuyerIp: () => incomingRequest.headers.get('cf-connecting-ip'),
-  // getForwardedIpSecret: () => ...
-});
-```
-
 The lower-level `forwardedIpMiddleware({ getBuyerIp, getSecret })` is also exported
 for fully custom clients.
 

package/dist/react/server/get-storefront-client.d.ts

@@ -41,12 +41,22 @@ export interface ServerClientOptions extends Omit<StorefrontClientConfig, 'middl
      */
     middleware?: Middleware[];
     /**
-     * OPTIONAL override for the buyer-IP source. Forwarded-IP signing is
-     * auto-configured: by default the SDK reads the request's `cf-connecting-ip`
-     * via `next/headers` (a server-rendered storefront would otherwise collapse
-     * every buyer onto its own server IP for rate limiting). Provide this only for
-     * non-Next server runtimes where `next/headers` is unavailable. May be async.
+     * Buyer-IP source that ENABLES forwarded-IP signing (opt-in). The forwarded-IP
+     * middleware is wired ONLY when this is provided — without it the client never
+     * reads the buyer IP and never signs (a fully static-safe, inert pass-through).
+     *
+     * Reading the buyer IP needs a request-scoped dynamic API (e.g. `next/headers`
+     * `headers()`), which is ILLEGAL in statically-generated / ISR routes — calling it
+     * there crashes the page ("static to dynamic at runtime"). So provide this ONLY on
+     * routes that are already dynamic (per-request rendered). A server-rendered
+     * storefront otherwise collapses every buyer onto its own server IP for rate
+     * limiting; forwarding the real IP restores per-buyer limits. May be async.
      * Server-side only.
+     *
+     * @example
+     * // ONLY on a dynamic route — `headers()` forces dynamic rendering:
+     * import { headers } from 'next/headers';
+     * getStorefrontClient({ apiUrl, shopSlug, getBuyerIp: async () => (await headers()).get('cf-connecting-ip') });
      */
     getBuyerIp?: () => string | null | undefined | Promise<string | null | undefined>;
     /**

package/dist/react/server/get-storefront-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-storefront-client.d.ts","sourceRoot":"","sources":["../../../src/react/server/get-storefront-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEpG,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAAC,sBAAsB,EAAE,YAAY,CAAC;IACrF;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;IAE1B;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAElF;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CAC7F;AAqBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,CA4BlF"}
+{"version":3,"file":"get-storefront-client.d.ts","sourceRoot":"","sources":["../../../src/react/server/get-storefront-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEpG,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAAC,sBAAsB,EAAE,YAAY,CAAC;IACrF;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;IAE1B;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAElF;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CAC7F;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,CAkClF"}

package/dist/react/server/get-storefront-client.js

@@ -24,25 +24,6 @@ import { retryMiddleware } from '../../core/middleware/retry';
 import { timeoutMiddleware } from '../../core/middleware/timeout';
 import { errorMiddleware } from '../../core/middleware/errors';
 import { forwardedIpMiddleware } from '../../core/middleware/forwarded-ip';
-/**
- * Default buyer-IP source: the request's `cf-connecting-ip` header, read via
- * `next/headers` (the same dynamic-import pattern used to read request cookies — a
- * graceful no-op outside a Next request scope or in runtimes without
- * `next/headers`). Override via `getBuyerIp` for other server frameworks.
- */
-async function readCfConnectingIp() {
-    try {
-        const { headers } = await import('next/headers');
-        const store = await headers();
-        // Prefer a forwarded client-IP header when present: if the request was
-        // proxied, the direct `cf-connecting-ip` is the proxy's address while this
-        // header carries the original client IP. Fall back to the direct connection IP.
-        return store.get('x-doswiftly-client-ip') ?? store.get('cf-connecting-ip');
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Create a StorefrontClient for server-side use.
  *
@@ -52,23 +33,29 @@ async function readCfConnectingIp() {
  */
 export function getStorefrontClient(options) {
     const { middleware: customMiddleware = [], getBuyerIp, getForwardedIpSecret, ...config } = options;
-    // Forward the real buyer IP for per-buyer rate limiting — fully self-configured,
-    // nothing for the storefront to wire. Buyer IP defaults to the request's
-    // `cf-connecting-ip` (via next/headers); the signing secret defaults to
-    // `process.env.DOSWIFTLY_FORWARDED_IP_SECRET` (set in the DoSwiftly deployment
-    // environment). The slug comes from the `X-Shop-Slug` header the client already
-    // sends, so the
-    // signed value matches what the backend verifies. The middleware signs ONLY when
-    // BOTH a buyer IP and a secret resolve at request time — so with no secret
-    // configured (or outside a Next request) it is an inert pass-through. Both
-    // getters can be overridden for non-Next runtimes.
-    const resolveBuyerIp = getBuyerIp ?? readCfConnectingIp;
-    const resolveSecret = getForwardedIpSecret ??
-        (() => (typeof process !== 'undefined' ? process.env?.DOSWIFTLY_FORWARDED_IP_SECRET : undefined));
+    // Forwarded-IP signing is OPT-IN: the middleware is wired ONLY when the caller
+    // supplies `getBuyerIp`. Reading the buyer IP needs a request-scoped dynamic API
+    // (`next/headers` `headers()`), which is illegal in statically-generated / ISR
+    // routes — auto-reading it there crashes the page ("static to dynamic at runtime").
+    // So the caller provides the IP source and uses it ONLY on dynamic routes; without
+    // `getBuyerIp` this client is a fully static-safe pass-through. The slug comes from
+    // the `X-Shop-Slug` header the client already sends, so the signed value matches
+    // what the backend verifies. The secret defaults to
+    // `process.env.DOSWIFTLY_FORWARDED_IP_SECRET` (override via `getForwardedIpSecret`);
+    // signing happens only when BOTH a buyer IP and a secret resolve at request time.
+    const forwardedIp = getBuyerIp
+        ? [
+            forwardedIpMiddleware({
+                getBuyerIp,
+                getSecret: getForwardedIpSecret ??
+                    (() => (typeof process !== 'undefined' ? process.env?.DOSWIFTLY_FORWARDED_IP_SECRET : undefined)),
+            }),
+        ]
+        : [];
     return createStorefrontClient({
         ...config,
         middleware: [
-            forwardedIpMiddleware({ getBuyerIp: resolveBuyerIp, getSecret: resolveSecret }),
+            ...forwardedIp,
             ...customMiddleware,
             retryMiddleware({ maxRetries: 2 }),
             timeoutMiddleware({ timeout: 10000 }), // Server-side: 10s timeout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-sdk",
-  "version": "22.1.0",
+  "version": "22.2.0",
   "description": "Storefront runtime SDK for DoSwiftly Commerce — layered transport, middleware pipeline, React providers, Zustand stores, cache strategies. 0 runtime dependencies in core.",
   "type": "module",
   "sideEffects": false,