@doswiftly/storefront-operations 9.1.0 → 11.0.0

package/mutations.graphql

@@ -67,9 +67,9 @@ mutation CartRemoveLines($id: ID!, $lineIds: [ID!]!) {
   }
 }
 
-# Replaces (NOT appends) the cart's discount codes with the given list. Pass `[]` to clear all codes. Each code is validated against `discounts` table (existence, active status); invalid codes appear in `userErrors[]` as `DISCOUNT_CODE_INVALID`. Triggers cart re-pricing — discount allocations are recomputed and stored in `cart.discountAmount`.
-mutation CartApplyDiscountCodes($id: ID!, $discountCodes: [String!]!) {
-  cartApplyDiscountCodes(id: $id, discountCodes: $discountCodes) {
+# Replaces (NOT appends) the cart's discount codes with the given list. Pass `[]` to clear all codes. Each code is validated against the discounts table (existence, active status); invalid codes appear in `userErrors[]` as `DISCOUNT_CODE_INVALID`. Triggers cart re-pricing — discount allocations are recomputed and stored in `cart.discountAmount`. Single canonical replace-all entry point — prior append/single-remove variants were removed in favor of this explicit caller-controlled list semantics.
+mutation CartDiscountCodesUpdate($id: ID!, $discountCodes: [String!]!) {
+  cartDiscountCodesUpdate(id: $id, discountCodes: $discountCodes) {
     cart {
       ...Cart
     }
@@ -276,184 +276,131 @@ mutation CustomerResetPassword($token: String!, $newPassword: String!) {
 }
 
 # ============================================
-# Checkout Mutations
+# Cart Completion Mutations
 # ============================================
-
-# Creates a new checkout session for the given cart (or a fresh cart if `cartId` is omitted). Inherits applied discounts and gift cards from the cart by reference (not snapshot). Errors: `CART_NOT_FOUND`, `EMPTY_CART`, `ALREADY_COMPLETED` (cart already converted to order). NOT idempotent — multiple calls create multiple checkouts.
-mutation CheckoutCreate($input: CheckoutCreateInput!) {
-  checkoutCreate(input: $input) {
-    checkout {
-      ...Checkout
+#
+# Phase 3 unify-cart-graphql-surface: wszystkie fulfillment + payment + completion
+# operations teraz na Cart aggregate (zamiast Checkout dual-aggregate). Klient
+# robi typowy checkout flow: cart create/add items → setShipping/Billing/Method
+# → selectPayment → (optional) applyGiftCard → cartComplete → Order created.
+
+# Sets the shipping address on the cart (full replace, not patch). Triggers cart re-pricing (tax recalculation per address country/region). Address format validated against `CartAddressInput` constraints (firstName/lastName/streetLine1/city/country/postalCode required). Errors: `INVALID_ADDRESS`, `CART_NOT_FOUND`.
+mutation CartSetShippingAddress($input: CartSetShippingAddressInput!) {
+  cartSetShippingAddress(input: $input) {
+    cart {
+      ...Cart
     }
     userErrors {
       ...UserError
     }
-  }
-}
-
-# Sets the shipping address (full replace, not patch). Triggers cart re-pricing. Address format is NOT validated here — full validation runs at `checkoutComplete`.
-mutation CheckoutUpdateShippingAddress($id: ID!, $shippingAddress: CheckoutAddressInput!) {
-  checkoutUpdateShippingAddress(id: $id, shippingAddress: $shippingAddress) {
-    checkout {
-      ...Checkout
-    }
-    userErrors {
-      ...UserError
+    warnings {
+      ...CartWarning
     }
   }
 }
 
-# Sets the billing address (full replace). Independent of shipping address — pass it explicitly even when "billing same as shipping".
-mutation CheckoutUpdateBillingAddress($id: ID!, $billingAddress: CheckoutAddressInput!) {
-  checkoutUpdateBillingAddress(id: $id, billingAddress: $billingAddress) {
-    checkout {
-      ...Checkout
+# Sets the billing address on the cart (full replace). Independent of shipping address — pass it explicitly even when "billing same as shipping". Errors: `INVALID_ADDRESS`, `CART_NOT_FOUND`.
+mutation CartSetBillingAddress($input: CartSetBillingAddressInput!) {
+  cartSetBillingAddress(input: $input) {
+    cart {
+      ...Cart
     }
     userErrors {
       ...UserError
     }
-  }
-}
-
-# Sets or updates the contact email on the checkout (used for guest checkout, order confirmation, and tracking emails). Validated against a regex; returns `INVALID` for malformed format.
-mutation CheckoutUpdateEmail($id: ID!, $email: String!) {
-  checkoutUpdateEmail(id: $id, email: $email) {
-    checkout {
-      ...Checkout
-    }
-    userErrors {
-      ...UserError
+    warnings {
+      ...CartWarning
     }
   }
 }
 
-# Selects a shipping method by `rateId` (a stable shipping-method UUID, NOT an opaque per-request token). The id comes from `availableShippingMethods` query, computed for the current address + cart subtotal at request time.
-mutation CheckoutSelectShippingRate($id: ID!, $rateId: String!) {
-  checkoutSelectShippingRate(id: $id, rateId: $rateId) {
-    checkout {
-      ...Checkout
+# Selects a shipping method by `shippingMethodId` (typed `ID!`, a stable shipping-method UUID — NOT a per-request token). The id comes from a list of methods available for the current address + cart subtotal (queryable separately). Errors: `SHIPPING_METHOD_REQUIRED`, `ZIP_CODE_NOT_SUPPORTED`, `CART_NOT_FOUND`.
+mutation CartSelectShippingMethod($input: CartSelectShippingMethodInput!) {
+  cartSelectShippingMethod(input: $input) {
+    cart {
+      ...Cart
     }
     userErrors {
       ...UserError
     }
-  }
-}
-
-# Appends a discount code to the cart's `discount_codes` array. Note: while multiple codes can be stored, the pricing engine currently uses **only the first applied code** — codes do not stack. Validated for existence, active status, and customer usage limits.
-mutation CheckoutApplyDiscountCode($id: ID!, $discountCode: String!) {
-  checkoutApplyDiscountCode(id: $id, discountCode: $discountCode) {
-    checkout {
-      ...Checkout
-    }
-    userErrors {
-      ...UserError
+    warnings {
+      ...CartWarning
     }
   }
 }
 
-# Removes a code from the cart's `discount_codes` array (filters by exact match). Triggers re-pricing.
-mutation CheckoutRemoveDiscountCode($id: ID!, $discountCode: String!) {
-  checkoutRemoveDiscountCode(id: $id, discountCode: $discountCode) {
-    checkout {
-      ...Checkout
+# Selects a payment method by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence + active status; no pre-authorization performed here. Errors: `PAYMENT_METHOD_REQUIRED`, `INVALID_PAYMENT`, `CART_NOT_FOUND`.
+mutation CartSelectPaymentMethod($input: CartSelectPaymentMethodInput!) {
+  cartSelectPaymentMethod(input: $input) {
+    cart {
+      ...Cart
     }
     userErrors {
       ...UserError
     }
-  }
-}
-
-# READ-ONLY validation of a discount code against the current checkout — does NOT modify state. Returns `{ isValid, discount, error }` for previewing the effect (e.g. inline UI feedback as the user types).
-mutation CheckoutValidateDiscountCode($id: ID!, $discountCode: String!) {
-  checkoutValidateDiscountCode(id: $id, discountCode: $discountCode) {
-    result {
-      isValid
-      discount {
-        code
-        title
-        type
-        value
-        discountAmount {
-          amount
-          currencyCode
-        }
-      }
-      error {
-        code
-        message
-      }
-    }
-    userErrors {
-      ...UserError
+    warnings {
+      ...CartWarning
     }
   }
 }
 
-# Selects a payment method by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence and active status; no pre-authorization is performed here.
-mutation CheckoutSelectPaymentMethod($id: ID!, $paymentMethodId: ID!) {
-  checkoutSelectPaymentMethod(id: $id, paymentMethodId: $paymentMethodId) {
-    checkout {
-      ...Checkout
+# Applies a gift card to the cart, stackable with discount codes. Consumption is FIFO: each card consumes `min(remainingBalance, paymentDue)` against the current cart total in the order they were applied. The gift card balance is NOT debited yet — actual deduction happens atomically at `cartComplete`. Errors: `GIFT_CARD_NOT_FOUND`, `GIFT_CARD_DEPLETED`, `GIFT_CARD_UNUSABLE`.
+mutation CartApplyGiftCard($input: CartApplyGiftCardInput!) {
+  cartApplyGiftCard(input: $input) {
+    cart {
+      ...Cart
     }
     userErrors {
       ...UserError
     }
-  }
-}
-
-# Finalizes the checkout: creates the `Order`, deducts gift cards, sends order-created confirmation — all atomically. **Idempotent on `idempotencyKey`** (NOT on the checkout `id`); auto-generated if the caller omits it. The `paymentUrl` field is reserved but is NOT populated here — for hosted gateways (PayU, P24) the storefront calls a separate `paymentCreate` mutation after this returns.
-mutation CheckoutComplete($id: ID!, $input: CheckoutCompleteInput) {
-  checkoutComplete(id: $id, input: $input) {
-    checkout {
-      ...Checkout
-    }
-    order {
-      ...Order
-    }
-    paymentUrl
-    userErrors {
-      ...UserError
+    warnings {
+      ...CartWarning
     }
   }
 }
 
-# ============================================
-# Gift Card Checkout Mutations
-# ============================================
-
-# Applies a gift card to the cart, stackable with discount codes. Consumption is FIFO: each card consumes `min(remainingBalance, paymentDue)` against the current cart total in the order they were applied. The gift card balance is NOT debited yet — actual deduction happens atomically at `checkoutComplete`. Errors: `GIFT_CARD_NOT_FOUND`, `GIFT_CARD_DEPLETED`, `GIFT_CARD_UNUSABLE`, `GIFT_CARD_ALREADY_APPLIED`.
-mutation CheckoutApplyGiftCard($id: ID!, $giftCardCode: String!) {
-  checkoutApplyGiftCard(id: $id, giftCardCode: $giftCardCode) {
-    checkout {
-      ...Checkout
+# 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.
+mutation CartRemoveGiftCard($input: CartRemoveGiftCardInput!) {
+  cartRemoveGiftCard(input: $input) {
+    cart {
+      ...Cart
     }
     userErrors {
       ...UserError
     }
+    warnings {
+      ...CartWarning
+    }
   }
 }
 
-# Removes a gift card from the applied list and recalculates FIFO `appliedAmount` for the remaining cards. Since gift card balances are only debited at `checkoutComplete`, removing before completion has no effect on the underlying gift card balance.
-mutation CheckoutRemoveGiftCard($id: ID!, $giftCardCode: String!) {
-  checkoutRemoveGiftCard(id: $id, giftCardCode: $giftCardCode) {
-    checkout {
-      ...Checkout
+# 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.
+mutation CartUpdateGiftCardRecipient($input: CartUpdateGiftCardRecipientInput!) {
+  cartUpdateGiftCardRecipient(input: $input) {
+    cart {
+      ...Cart
     }
     userErrors {
       ...UserError
     }
+    warnings {
+      ...CartWarning
+    }
   }
 }
 
-# Sets per-line-item recipient details (name, email, message, delivery date) for digital gift card products in the cart (variants with `type: GIFT_CARD`). Required before `checkoutComplete` for any line item with a gift-card variant. Recipient details are associated with each gift-card line item and propagated to the resulting order.
-mutation CheckoutUpdateGiftCardRecipient($input: CheckoutGiftCardRecipientInput!) {
-  checkoutUpdateGiftCardRecipient(input: $input) {
-    checkout {
-      ...Checkout
+# 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`.
+mutation CartComplete($input: CartCompleteInput!) {
+  cartComplete(input: $input) {
+    order {
+      ...Order
     }
     userErrors {
       ...UserError
     }
+    warnings {
+      ...CartWarning
+    }
   }
 }