@doswiftly/storefront-operations 16.0.0 → 16.1.0

package/AGENTS.md

@@ -27,7 +27,7 @@ consumer's `codegen.ts` references this package's `.graphql` files as
 live in the consumer's repo.
 
 <!-- AUTOGEN:STATS:BEGIN — auto-regenerated, do not edit by hand -->
-- **Schema version**: 16.0.0
+- **Schema version**: 16.1.0
 - **Queries**: 52
 - **Mutations**: 40
 - **Fragments**: 102

package/CHANGELOG.md

@@ -1,5 +1,135 @@
 # Changelog
 
+## 16.1.0
+
+### Minor Changes
+
+- 1e6062e: Read the gift card recipient back from the cart.
+
+  `cartUpdateGiftCardRecipient` already persisted the recipient (email, name,
+  personalised message) on a gift card line — but the `CartLine` type didn't
+  expose any field to read it. Storefronts that render the checkout server-side
+  (SSR, deep link, "back to cart" navigation) had no way to know that the buyer
+  had already filled in the recipient form on a previous visit. The recipient
+  dialog opened blank, like nothing had been saved.
+
+  **New field** — `CartLine.giftCardRecipient: GiftCardLineRecipient`
+
+  ```graphql
+  type GiftCardLineRecipient {
+    recipientEmail: String
+    recipientName: String
+    message: String
+  }
+  ```
+
+  All three fields are individually nullable so a partial set (email only, no
+  name or message) is representable as-is. The field on `CartLine` itself is
+  nullable — `null` means the buyer has not set a recipient yet, in which case
+  the gift card is delivered to the order `customerEmail` on completion.
+
+  `null` is also what you get for any non-gift-card line — there is no risk of
+  the field reporting a stale recipient from a previous line at the same index.
+
+  **Use it to seed your form**
+
+  ```tsx
+  const cart = await cartClient.get(cartId);
+  const giftLine = cart?.lines.edges.find(
+    (e) => e.node.productType === "GIFT_CARD",
+  );
+
+  <GiftRecipientForm
+    defaultValues={
+      giftLine?.node.giftCardRecipient ?? {
+        recipientEmail: "",
+        recipientName: "",
+        message: "",
+      }
+    }
+    onSubmit={(values) =>
+      cartClient.updateGiftCardRecipient(cartId, giftLine!.node.id, values)
+    }
+  />;
+  ```
+
+  **Migration**
+
+  Additive change — no rename, no signature change. The `CartLine` fragment
+  shipped by the SDK already includes the new field after this release, so
+  upgrading immediately unlocks the read path. No client code changes required
+  to keep existing flows working.
+
+- ac2e306: Distinguish recoverable session loss from permanent cart denial.
+
+  Adds a new `CART_UNAUTHENTICATED` code to the cart error envelope. Until now,
+  both "your sign-in expired" and "this cart belongs to someone else" surfaced
+  as `CART_FORBIDDEN`, so a storefront had no way to know whether to send the
+  buyer to `/login` (recoverable) or to drop the cart cookie (permanent).
+  After the typical ~24h session TTL, the buyer would silently lose their
+  checkout state instead of being prompted to re-authenticate.
+
+  **New code** — `CART_UNAUTHENTICATED`
+
+  | Condition                                                                             | Code                         | Recovery                                                    |
+  | ------------------------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------- |
+  | Anonymous request **or** expired/invalid session on a cart that belongs to a customer | `CART_UNAUTHENTICATED`       | Re-authenticate. Cart is preserved (`cart-id` cookie kept). |
+  | Authenticated as a **different** customer than the cart owner                         | `CART_FORBIDDEN` (unchanged) | Drop the cart cookie and start over.                        |
+
+  The cart resource itself is intact in the `CART_UNAUTHENTICATED` case — the
+  buyer's saved address, line items, discount codes, and gift cards return as
+  soon as they sign in.
+
+  **New SDK signal** — `runner.onSessionExpired(...)`
+
+  The recovery runner now exposes a separate event for session loss, distinct
+  from `onExpired` (which is for cart-resource lifecycle: cart not found, cart
+  already completed). Subscribe once at the provider level and route the buyer
+  to `/login` with a `return_to` parameter; the cart cookie stays put.
+
+  ```ts
+  // app/providers.tsx
+  const unsubExpired = runner.onExpired(() => {
+    // cart resource gone — start fresh
+    router.push("/cart/new");
+  });
+
+  const unsubSession = runner.onSessionExpired(() => {
+    // session gone, cart preserved — sign back in
+    router.push(`/login?return_to=${encodeURIComponent(location.pathname)}`);
+  });
+  ```
+
+  The session branch throws `CartSessionRequiredError` (re-exported alongside
+  `CartRecoveryNotPossibleError`) and does **not** invoke `recreateAndRun` —
+  recreating the cart on a stale session would discard the buyer's progress.
+
+  **Imperative handling**
+
+  If you handle mutation errors directly (Server Action, custom hook), add one
+  case to your existing switch:
+
+  ```ts
+  switch (err.userErrors[0]?.code) {
+    case "CART_UNAUTHENTICATED":
+      redirect(`/login?return_to=${encodeURIComponent("/checkout")}`);
+      break;
+    case "CART_FORBIDDEN":
+      cookies().delete("cart-id");
+      redirect("/cart/expired");
+      break;
+    // ...existing cases for CART_NOT_FOUND / ALREADY_COMPLETED
+  }
+  ```
+
+  **Migration**
+
+  Additive change — no rename, no signature change. Existing `case 'CART_FORBIDDEN'`
+  branches keep working as before. Opt in to the new code at your own pace; until
+  you add the case, anonymous and cross-customer denials fall into your existing
+  default branch (one will be recoverable, one will not — adding the case lets
+  you distinguish them).
+
 ## 16.0.0
 
 ### Major Changes

package/fragments.graphql

@@ -427,6 +427,11 @@ fragment CartLine on CartLine {
   productHandle
   productType
   requiresShipping
+  giftCardRecipient {
+    recipientEmail
+    recipientName
+    message
+  }
 }
 
 # Buyer identity associated with the cart. Note: only `customerId` is currently persisted server-side; `email`, `phone`, `countryCode` are accepted in the input but ignored.

package/llms-full.txt

@@ -1,6 +1,6 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **16.0.0**
+> Schema version: **16.1.0**
 > 52 queries · 40 mutations · 102 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is
@@ -3052,6 +3052,11 @@ fragment CartLine on CartLine {
   productHandle
   productType
   requiresShipping
+  giftCardRecipient {
+    recipientEmail
+    recipientName
+    message
+  }
 }
 ```
 

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "16.0.0",
+  "schemaVersion": "16.1.0",
   "queries": [
     {
       "name": "Shop",
@@ -2124,7 +2124,7 @@
         "CartLineCost",
         "ProductVariant"
       ],
-      "body": "fragment CartLine on CartLine {\n  id\n  quantity\n  variant {\n    ...ProductVariant\n  }\n  cost {\n    ...CartLineCost\n  }\n  attributes {\n    key\n    value\n  }\n  attributeSelections {\n    ...AttributeSelection\n  }\n  productId\n  productTitle\n  productHandle\n  productType\n  requiresShipping\n}",
+      "body": "fragment CartLine on CartLine {\n  id\n  quantity\n  variant {\n    ...ProductVariant\n  }\n  cost {\n    ...CartLineCost\n  }\n  attributes {\n    key\n    value\n  }\n  attributeSelections {\n    ...AttributeSelection\n  }\n  productId\n  productTitle\n  productHandle\n  productType\n  requiresShipping\n  giftCardRecipient {\n    recipientEmail\n    recipientName\n    message\n  }\n}",
       "onType": "CartLine"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "16.0.0",
+  "version": "16.1.0",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {

package/schema.graphql

@@ -1360,6 +1360,11 @@ type CartLine {
   """
   cost: CartLineCost!
 
+  """
+  Recipient details captured for a `GIFT_CARD` line via `cartUpdateGiftCardRecipient`. Null for non-gift-card lines or when no recipient has been set yet — in that case the gift card is delivered to the order `customerEmail` on completion. Use to initialise the "gift recipient" form from cart state on SSR / page reload / deep link instead of keeping it in client-only state.
+  """
+  giftCardRecipient: GiftCardLineRecipient
+
   """
   Stable line identifier. Use it to address the line in `cartUpdateLines` / `cartRemoveLines`.
   """
@@ -3025,6 +3030,22 @@ enum GiftCardErrorCode {
   NOT_FOUND
 }
 
+"""
+Recipient details attached to a `GIFT_CARD` line — set with `cartUpdateGiftCardRecipient`. All fields are nullable individually so a partial set (e.g. email only) is representable.
+"""
+type GiftCardLineRecipient {
+  """Personalised message included with the gift card."""
+  message: String
+
+  """
+  Recipient email — where the gift card code will be delivered on order completion.
+  """
+  recipientEmail: String
+
+  """Recipient display name shown in the gift card email."""
+  recipientName: String
+}
+
 """Gift card status"""
 enum GiftCardStatus {
   ACTIVE