@doswiftly/storefront-operations 11.0.0 → 11.2.0

package/AGENTS.md

@@ -27,10 +27,10 @@ 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**: 11.0.0
+- **Schema version**: 11.2.0
 - **Queries**: 48
-- **Mutations**: 39
-- **Fragments**: 99
+- **Mutations**: 40
+- **Fragments**: 100
 <!-- AUTOGEN:STATS:END -->
 
 ## Loading order

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 11.2.0
+
+### Minor Changes
+
+- 760f965: Added automatic stale-cart recovery to the core SDK so every consumer (React, Vue, mobile, CLI, SSR) gets the same protection against `CART_NOT_FOUND` / `ALREADY_COMPLETED` errors without re-implementing detection, cookie cleanup, and retry orchestration.
+
+  **What's new** (importable from `@doswiftly/storefront-sdk`):
+  - `isCartRecoverableError(err)` — type-safe predicate that inspects `err.userErrors[].code` (works across PL/EN/any backend locale, unlike message string matching).
+  - `CART_RECOVERABLE_ERROR_CODES` — readonly tuple of codes that warrant cart recreation; mirrored against the backend `CartErrorCode` enum by a drift test.
+  - `executeWithCartRecovery(opts)` — pure async orchestrator for any consumer.
+  - `createCartRecoveryRunner({ cartClient, cookieStore })` — DX-friendly factory that curries the dependencies, shares a Phase-0 concurrency mutex across operations, and exposes an `onExpired(listener)` subscription for global UI feedback.
+  - `CartCookieStore` — port interface (`get` / `set` / `clear`) the caller implements once per runtime. From `@doswiftly/storefront-sdk/react` we now also export `createBrowserCartCookieStore()` (SSR-safe).
+  - `CartRecoveryNotPossibleError` — thrown when an operation cannot be safely replayed (line-id / shipping-method references the dead cart). Carries `reason: 'state-dependent' | 'recreate-failed' | 'retry-also-failed'` for diagnostic UX.
+  - `recreateWithInput(input)` / `recreateWithLines(lines)` — sugar helpers for the most common atomic `cartCreate(payload)` recovery strategies.
+
+  **Per-operation taxonomy (decision is in the SDK, not in caller code):**
+
+  | Operation                                                                                    | Strategy                                                                                                                                         |
+  | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+  | `addItems`, `updateBuyerIdentity`, `setShippingAddress`, `updateDiscountCodes`, `updateNote` | Auto-replay via a single atomic `cartCreate(input)` — recovery is invisible to the caller                                                        |
+  | `updateItems`, `removeItems`                                                                 | Bail with `CartRecoveryNotPossibleError` and emit a `cart-expired` event — replaying on a fresh empty cart would silently lose the user's intent |
+
+  **React updates:**
+  - `useCartManager` now uses the recovery runner internally. Detection is code-based (no more PL/EN regression — previous implementation matched `'cart not found'` in the error message, which never matched a Polish backend response). Recovery now covers all mutations exposed by the hook, not just `addItem`. New methods: `updateBuyerIdentity`, `setShippingAddress`. New API: `onExpired(listener)` returning an unsubscribe function.
+  - `createCartStore` now recovers `addToCart` automatically. New optional `CartActions.createCartWithLines(lines)` lets templates wire the atomic single-round-trip path; without it the store falls back to `createCart()` + `addLines()`. `updateQuantity` and `removeFromCart` bail with the `cart-expired` event when the cart is gone (previously the store kept its local id pointing at a dead cart). `CartStoreConfig.onExpired?(event)` lets the consumer subscribe.
+
+  **Migration:**
+  - No required code changes for existing React consumers — `useCartManager` and `createCartStore` keep their public surface.
+  - If you previously caught `StorefrontError` to detect stale carts via message string matching, switch to `isCartRecoverableError(err)` (code-based, locale-proof) or — preferably — subscribe to `runner.onExpired(...)` / `useCartManager().onExpired(...)` / `createCartStore({ onExpired })`.
+  - Non-React consumers should wrap their cart mutations in `createCartRecoveryRunner` and implement a `CartCookieStore` adapter for their environment (browser via `createBrowserCartCookieStore()`, server-side via `next/headers`, CLI via in-memory `Map`, mobile via AsyncStorage).
+
+  `@doswiftly/storefront-operations` is bumped in lockstep (no code change — required because the packages are linked and ship together).
+
+## 11.1.0
+
+### Minor Changes
+
+- c2e80b2: Add `paymentCreate` — initiate a payment session for a completed order.
+
+  After `cartComplete` returns an order, call `paymentCreate` (when `order.canCreatePayment` is `true`) to start the payment. Orders with an offline payment method (cash on delivery, manual bank transfer) skip this step. The returned `PaymentSession` is flow-aware — branch on `session.flow`:
+  - `ONLINE_REDIRECT` → redirect the browser to `session.redirectUrl`
+  - `ONLINE_EMBEDDED` → render an in-page widget with `session.clientSecret`
+  - `INSTANT_DIRECT` → already settled, read `session.status`
+
+  **`@doswiftly/storefront-operations`** — new `PaymentCreate` mutation and `PaymentSession` fragment.
+
+  **`@doswiftly/storefront-sdk`** — new `CartClient.createPayment(input)` method, plus the `PaymentSession`, `PaymentCreateInput`, `PaymentInitiationFlow` and `PaymentErrorCode` types.
+
+  ```ts
+  const { order } = await cartClient.complete({ cartId });
+  if (order.canCreatePayment) {
+    const session = await cartClient.createPayment({
+      orderId: order.id,
+      returnUrl: "https://my-shop.example/checkout/complete",
+    });
+    if (session.flow === "ONLINE_REDIRECT") {
+      window.location.href = session.redirectUrl!;
+    }
+  }
+  ```
+
+  `paymentCreate` is idempotent on the order — re-calling returns the existing still-valid session instead of creating a duplicate, so it is safe to retry. `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop. The call throws on validation/business errors — inspect `error.userErrors[0].code` (`PaymentErrorCode`): `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`.
+
 ## 11.0.0
 
 ### Major Changes

package/README.md

@@ -381,6 +381,7 @@ full executable body of each operation.
 | `CartRemoveGiftCard` | Removes a gift card from the applied list and recalculates FIFO `appliedAmount` for the remaining cards. Since gift card balances are only debited at `cartComplete`, removing before completion has no effect on the underlying gift card balance. |
 | `CartUpdateGiftCardRecipient` | Sets per-line-item recipient details (name, email, message) for digital gift card products in the cart (line items where the variant represents a gift-card SKU). Required before `cartComplete` for any line item with a gift-card variant. Recipient details propagated to the resulting order. |
 | `CartComplete` | Finalizes the cart — creates the `Order`, deducts gift cards, sends order-created confirmation — all atomically. **Idempotent on `idempotencyKey`** (auto-generated from cartId + minute timestamp if caller omits it). Returns `order` field after completion. Note: `paymentUrl` is intentionally NOT in payload — for hosted gateways (online providers) the storefront calls a separate `paymentCreate` mutation after this returns (check `order.canCreatePayment` first). Errors: `EMAIL_REQUIRED`, `SHIPPING_ADDRESS_REQUIRED`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_REQUIRED`, `INSUFFICIENT_STOCK`, `ALREADY_COMPLETED`. |
+| `PaymentCreate` | Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`. |
 
 #### Return Mutations
 
@@ -503,6 +504,7 @@ full executable body of each operation.
 | --- | --- | --- |
 | `PaymentMethod` | `PaymentMethod` | Single payment method enabled for the shop — type (CARD / BANK_TRANSFER / BLIK / PAYPAL / APPLE_PAY / GOOGLE_PAY / CASH_ON_DELIVERY / OTHER), provider, icon, supported currencies, default flag, sort position. Spread on the checkout payment step. |
 | `AvailablePaymentMethods` | `AvailablePaymentMethods` | Active payment methods list with the merchant's `defaultMethod`. Returned by the `availablePaymentMethods` query. |
+| `PaymentSession` | `PaymentSession` | Initiated payment session for an order — returned by the `paymentCreate` mutation. Branch on `flow`: `ONLINE_REDIRECT` (redirect the browser to `redirectUrl`), `ONLINE_EMBEDDED` (render an in-page widget with `clientSecret`), `INSTANT_DIRECT` (settled with no UI — read `status`). `expiresAt` is ISO 8601, present when the gateway session has a TTL. |
 
 #### Shipments / Tracking
 

package/fragments.graphql

@@ -672,6 +672,18 @@ fragment AvailablePaymentMethods on AvailablePaymentMethods {
   }
 }
 
+# Initiated payment session for an order — returned by the `paymentCreate` mutation. Branch on `flow`: `ONLINE_REDIRECT` (redirect the browser to `redirectUrl`), `ONLINE_EMBEDDED` (render an in-page widget with `clientSecret`), `INSTANT_DIRECT` (settled with no UI — read `status`). `expiresAt` is ISO 8601, present when the gateway session has a TTL.
+fragment PaymentSession on PaymentSession {
+  id
+  orderId
+  flow
+  provider
+  redirectUrl
+  clientSecret
+  status
+  expiresAt
+}
+
 # ============================================
 # Discount Code Validation
 # ============================================

package/llms-full.txt

@@ -1,7 +1,7 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **11.0.0**
-> 48 queries · 39 mutations · 99 fragments
+> Schema version: **11.2.0**
+> 48 queries · 40 mutations · 100 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is
 regenerated on every release to match the published schema.
@@ -2011,6 +2011,31 @@ mutation CartComplete($input: CartCompleteInput!) {
 }
 ```
 
+### Mutation: `PaymentCreate`
+
+**Section**: Cart Completion Mutations
+
+**Description**: Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`.
+
+**Variables**:
+- `$input`: `PaymentCreateInput!`
+
+**Fragments used**: `PaymentSession`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation PaymentCreate($input: PaymentCreateInput!) {
+  paymentCreate(input: $input) {
+    payment {
+      ...PaymentSession
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+```
+
 ### Mutation: `ReturnCreate`
 
 **Section**: Return Mutations
@@ -3315,6 +3340,26 @@ fragment AvailablePaymentMethods on AvailablePaymentMethods {
 }
 ```
 
+### Fragment: `PaymentSession` on `PaymentSession`
+
+**Section**: Payment Methods
+
+**Description**: Initiated payment session for an order — returned by the `paymentCreate` mutation. Branch on `flow`: `ONLINE_REDIRECT` (redirect the browser to `redirectUrl`), `ONLINE_EMBEDDED` (render an in-page widget with `clientSecret`), `INSTANT_DIRECT` (settled with no UI — read `status`). `expiresAt` is ISO 8601, present when the gateway session has a TTL.
+
+**GraphQL**:
+```graphql
+fragment PaymentSession on PaymentSession {
+  id
+  orderId
+  flow
+  provider
+  redirectUrl
+  clientSecret
+  status
+  expiresAt
+}
+```
+
 ### Fragment: `ShipmentEvent` on `ShipmentEvent`
 
 **Section**: Shipments / Tracking

package/mutations.graphql

@@ -404,6 +404,18 @@ mutation CartComplete($input: CartCompleteInput!) {
   }
 }
 
+# Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`.
+mutation PaymentCreate($input: PaymentCreateInput!) {
+  paymentCreate(input: $input) {
+    payment {
+      ...PaymentSession
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}
+
 # ============================================
 # Return Mutations
 # ============================================

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "11.0.0",
+  "schemaVersion": "11.2.0",
   "queries": [
     {
       "name": "Shop",
@@ -1540,6 +1540,24 @@
       ],
       "body": "mutation CartComplete($input: CartCompleteInput!) {\n  cartComplete(input: $input) {\n    order {\n      ...Order\n    }\n    userErrors {\n      ...UserError\n    }\n    warnings {\n      ...CartWarning\n    }\n  }\n}"
     },
+    {
+      "name": "PaymentCreate",
+      "kind": "mutation",
+      "section": "Cart Completion Mutations",
+      "description": "Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`.",
+      "variables": [
+        {
+          "name": "input",
+          "type": "PaymentCreateInput!",
+          "defaultValue": null
+        }
+      ],
+      "fragmentRefs": [
+        "PaymentSession",
+        "UserError"
+      ],
+      "body": "mutation PaymentCreate($input: PaymentCreateInput!) {\n  paymentCreate(input: $input) {\n    payment {\n      ...PaymentSession\n    }\n    userErrors {\n      ...UserError\n    }\n  }\n}"
+    },
     {
       "name": "ReturnCreate",
       "kind": "mutation",
@@ -2240,6 +2258,16 @@
       "body": "fragment AvailablePaymentMethods on AvailablePaymentMethods {\n  methods {\n    ...PaymentMethod\n  }\n  defaultMethod {\n    ...PaymentMethod\n  }\n}",
       "onType": "AvailablePaymentMethods"
     },
+    {
+      "name": "PaymentSession",
+      "kind": "fragment",
+      "section": "Payment Methods",
+      "description": "Initiated payment session for an order — returned by the `paymentCreate` mutation. Branch on `flow`: `ONLINE_REDIRECT` (redirect the browser to `redirectUrl`), `ONLINE_EMBEDDED` (render an in-page widget with `clientSecret`), `INSTANT_DIRECT` (settled with no UI — read `status`). `expiresAt` is ISO 8601, present when the gateway session has a TTL.",
+      "variables": [],
+      "fragmentRefs": [],
+      "body": "fragment PaymentSession on PaymentSession {\n  id\n  orderId\n  flow\n  provider\n  redirectUrl\n  clientSecret\n  status\n  expiresAt\n}",
+      "onType": "PaymentSession"
+    },
     {
       "name": "ShipmentEvent",
       "kind": "fragment",

package/package.json

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

package/schema.graphql

@@ -2272,6 +2272,7 @@ enum DiscountApplicationType {
 
 """Error codes for discount validation"""
 enum DiscountErrorCode {
+  CUSTOMER_GROUP_NOT_ELIGIBLE
   CUSTOMER_NOT_ELIGIBLE
   CUSTOMER_USAGE_LIMIT_REACHED
   DISCOUNT_COMBINATION_NOT_ALLOWED
@@ -3509,6 +3510,11 @@ type Mutation {
   """Redeem a loyalty reward"""
   loyaltyRedeemReward(input: RedeemRewardInput!): RedeemRewardPayload!
 
+  """
+  Initiate a payment session for an order — call after cartComplete when order.canCreatePayment is true
+  """
+  paymentCreate(input: PaymentCreateInput!): PaymentCreatePayload!
+
   """Cancel a return request"""
   returnCancel(id: ID!): ReturnCancelPayload!
 
@@ -3717,6 +3723,41 @@ enum PageSortKeys {
   UPDATED_AT
 }
 
+"""Input dla paymentCreate mutation"""
+input PaymentCreateInput {
+  """
+  URL powrotu klienta po anulowaniu płatności — musi być na zweryfikowanej domenie sklepu
+  """
+  cancelUrl: URL
+
+  """ID zamówienia (z cartComplete) do opłacenia"""
+  orderId: ID!
+
+  """
+  URL powrotu klienta po płatności — musi być na zweryfikowanej domenie sklepu
+  """
+  returnUrl: URL
+}
+
+"""Wynik paymentCreate mutation"""
+type PaymentCreatePayload {
+  """Utworzona sesja płatności (null gdy userErrors)"""
+  payment: PaymentSession
+
+  """Błędy walidacji / biznesowe"""
+  userErrors: [UserError!]!
+}
+
+"""
+Sposób uruchomienia płatności po stronie klienta — storefront rozgałęzia krok po tej wartości
+"""
+enum PaymentInitiationFlow {
+  INSTANT_DIRECT
+  OFFLINE_MANUAL
+  ONLINE_EMBEDDED
+  ONLINE_REDIRECT
+}
+
 """Payment method available for checkout"""
 type PaymentMethod {
   """Description for customers"""
@@ -3756,6 +3797,33 @@ enum PaymentMethodType {
   OTHER
 }
 
+"""Sesja płatności utworzona dla zamówienia"""
+type PaymentSession {
+  """Token/secret do widgetu in-page — wypełniony dla flow ONLINE_EMBEDDED"""
+  clientSecret: String
+
+  """Kiedy redirectUrl/clientSecret przestaje być ważny (ISO 8601)"""
+  expiresAt: String
+
+  """Sposób uruchomienia — storefront robi switch(flow)"""
+  flow: PaymentInitiationFlow!
+
+  """ID rekordu płatności"""
+  id: ID!
+
+  """ID zamówienia"""
+  orderId: ID!
+
+  """Kod providera płatności (np. PAYU)"""
+  provider: String!
+
+  """URL hosted gateway — wypełniony dla flow ONLINE_REDIRECT"""
+  redirectUrl: URL
+
+  """Status płatności zamówienia"""
+  status: OrderPaymentStatus!
+}
+
 """Shop payment configuration (currency, country, providers)"""
 type PaymentSettings {
   """Country code sklepu — driver dostępności metod płatności"""