@doswiftly/storefront-sdk 21.0.1 → 22.0.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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

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 */