@doswiftly/storefront-sdk 21.0.1 → 22.1.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 22.1.0
+
+### Minor Changes
+
+- 32ee745: Forward the real buyer IP from server-rendered storefronts (per-buyer rate limiting)
+
+  A server-rendered (BFF) storefront fetches from its own server, so the API sees one
+  source IP for every buyer and per-IP rate limits collapse onto that single address.
+  The server client now forwards the real buyer IP to the API so rate limiting applies
+  per buyer again.
+
+  **Automatic on the server — no wiring, fully backward-compatible.** Call
+  `getStorefrontClient({ apiUrl, shopSlug })` as before; forwarding configures itself
+  and stays inert when it cannot apply, so existing setups are unaffected. Server-only.
+
+  Non-Next server runtimes can supply the buyer IP explicitly via `getBuyerIp` (and
+  `getForwardedIpSecret`). The lower-level `forwardedIpMiddleware` is also exported.
+
+  (`@doswiftly/storefront-operations` is a version-sync bump — no code change.)
+
+## 22.0.0
+
+### Major Changes
+
+- 49139e2: Remove the `pendingPoints` field from `LoyaltyPointsSummary` (GraphQL schema, the `LoyaltyPointsSummary` fragment and the generated types). The field was never populated — it always returned `0` — because purchase points are credited directly when the payment is captured, so there is no "pending" state to report.
+
+  **Migration:** if your storefront reads `points.pendingPoints` (or selects `pendingPoints` in a custom query or fragment), remove that usage and re-run your codegen. No replacement field is needed — `currentPoints` has always been the spendable balance.
+
+### Minor Changes
+
+- 49139e2: Referral program signup support — the loyalty referral program now works end-to-end:
+  - `customerSignup` accepts an optional `referralCode` in its input. When the shop's referral program is active, a valid code grants the configured bonus points to the new customer and, after their first paid order, rewards the referrer. An invalid, expired or own code is silently ignored — the signup always succeeds.
+  - New referral capture helpers in the SDK: `useReferralCapture()` / `captureReferralCode()` persist the `?ref=CODE` parameter from a referral landing link into the readable `referral-code` cookie (30 days by default), and `readReferralCodeCookie()` / `clearReferralCodeCookie()` read and clear it at signup time. A server-side `readReferralCodeCookie()` is available from `@doswiftly/storefront-sdk/react/server` for SSR-rendered signup forms. Core constants and the URL extractor (`REFERRAL_COOKIE_NAME`, `REFERRAL_COOKIE_MAX_AGE`, `extractReferralCodeFromUrl`) are exported from the framework-agnostic core entry.
+
+  The cookie lifetime is the _landing → signup_ window and is intentionally independent of the shop's referral validity setting, which starts at signup and is enforced by the API.
+
 ## 21.0.1
 
 ### Patch Changes

package/README.md

@@ -667,6 +667,50 @@ const {
 });
 ```
 
+## Referral program
+
+When the shop's loyalty referral program is enabled, customers share links like
+`https://shop.example/register?ref=REF-AB12CD34` (the code and share URL come
+from the `referralStats` / `loyaltyGenerateReferralCode` GraphQL operations).
+The SDK bridges the gap between landing on such a link and the actual signup:
+
+```tsx
+// 1. Capture the code on landing — mount once near the top of the app.
+'use client';
+import { useReferralCapture } from '@doswiftly/storefront-sdk/react';
+
+export function ReferralCapture() {
+  useReferralCapture(); // reads ?ref=... and stores it in the `referral-code` cookie (30 days)
+  return null;
+}
+```
+
+```tsx
+// 2. At signup, pass the stored code in the customerSignup input and clear it on success.
+import { getReferralCodeCookie, clearReferralCodeCookie } from '@doswiftly/storefront-sdk/react';
+
+const referralCode = getReferralCodeCookie();
+await signup({ email, password, firstName, lastName, referralCode: referralCode ?? undefined });
+clearReferralCodeCookie();
+```
+
+Codes are case-insensitive and an invalid, malformed, expired or own code is
+silently ignored by the API — the signup always succeeds. The capture step only
+persists values matching the platform code shape (letters, digits, dashes —
+`REFERRAL_CODE_PATTERN`), so junk `?ref=` values never reach the cookie. Server
+Components can read the stored code with the async `readReferralCodeCookie()`
+from `@doswiftly/storefront-sdk/react/server` (e.g. to pre-fill an SSR-rendered
+form) — note the deliberate naming split: synchronous `getReferralCodeCookie()`
+on the client entry vs server-first `readReferralCodeCookie()` on the server
+entry. Non-React runtimes can use the core helpers directly:
+`extractReferralCodeFromUrl(url)` plus the `REFERRAL_COOKIE_NAME` /
+`REFERRAL_COOKIE_MAX_AGE` constants.
+
+The cookie lifetime (30 days, override via `captureReferralCode({ maxAge })`)
+is the *landing → signup* window. It is independent of the shop's referral
+validity setting — that one starts at signup, limits the time the referred
+customer has to place their first order, and is enforced by the backend.
+
 ## Pre-built React components
 
 Headless, accessibility-aware, zero styling — pass `className` to integrate with
@@ -728,6 +772,11 @@ Middleware that reads mutable state takes a **lazy getter**
 (`authMiddleware(() => store.getState().accessToken)`) so rotated values are
 picked up without rebuilding the client.
 
+A server-only `forwardedIpMiddleware` is also available for server-rendered (BFF)
+storefronts — it forwards the real buyer IP to the backend so per-IP rate limits
+do not collapse onto the storefront server's address. See
+[Server-side](#server-side-reactserver).
+
 ## Core API
 
 ### createStorefrontClient
@@ -1026,6 +1075,40 @@ 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.
+
+**Automatic on the server — nothing to wire.** Call `getStorefrontClient` as usual:
+
+```typescript
+const client = getStorefrontClient({
+  apiUrl: process.env.DOSWIFTLY_API_URL!,
+  shopSlug: process.env.DOSWIFTLY_SHOP_SLUG!,
+});
+```
+
+It applies only inside a server request with forwarding configured by your
+deployment, and is otherwise an inert pass-through — existing setups are unaffected.
+**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.
+
 ## Caching
 
 ```typescript

package/dist/core/generated/operation-types.d.ts

@@ -1553,6 +1553,8 @@ export type CustomerCreateInput = {
     password: Scalars['String']['input'];
     /** Phone number (free-form). */
     phone?: InputMaybe<Scalars['String']['input']>;
+    /** Referral code of an existing customer, usually taken from a referral link's `ref` URL parameter (codes are case-insensitive). Optional — an invalid, malformed, expired or own code is silently ignored and the signup still succeeds; only a value longer than 50 characters is rejected. When the shop's referral program is active, a valid code grants the configured bonus points to the new customer and, after their first paid order, rewards the referrer. */
+    referralCode?: InputMaybe<Scalars['String']['input']>;
 };
 export type CustomerGroup = {
     /** Group code */
@@ -2092,8 +2094,6 @@ export type LoyaltyPointsSummary = {
     expiringPoints?: Maybe<Scalars['Int']['output']>;
     /** Next expiry date (ISO 8601) */
     nextExpiryDate?: Maybe<Scalars['DateTime']['output']>;
-    /** Points pending (from incomplete orders) */
-    pendingPoints: Scalars['Int']['output'];
     /** Points redeemed */
     redeemedPoints: Scalars['Int']['output'];
     /** Total points earned all-time */