@doswiftly/storefront-operations 16.0.0 → 17.0.0

package/schema.graphql

@@ -880,7 +880,9 @@ type Cart implements Node {
   """
   attributes: [CartAttribute!]!
 
-  """Available payment methods dla tego cart (shop-configured providers)"""
+  """
+  Available payment methods dla tego carta — deduplikowane per type, sorted by merchant priority.
+  """
   availablePaymentMethods: [PaymentMethod!]!
 
   """
@@ -955,6 +957,11 @@ type Cart implements Node {
   """
   requiresShipping: Boolean!
 
+  """
+  Optional concrete instrument code selected within `selectedPaymentMethod` (e.g. `"blik"`, `"mb"`, `"154"`). Set gdy klient klika konkretny instrument tile na storefront (per `PaymentMethod.instruments`). Pre-payment intent: skopiowany do `Order.paymentInstrumentCode` przy `cartComplete`. Storefront może cross-reference z `availablePaymentMethods.methods[].instruments[]` żeby dostać `displayName` / `brandImageUrl`. Added by payment-instrument-preselection core sprint Req 3 AC7.
+  """
+  selectedPaymentInstrumentCode: String
+
   """
   The payment method currently selected on the cart. Null until the buyer picks a method via `cartSelectPaymentMethod`.
   """
@@ -982,6 +989,11 @@ type Cart implements Node {
 
   """When the cart was last modified (ISO 8601)."""
   updatedAt: DateTime!
+
+  """
+  Non-fatal advisories computed at query time. Currently emitted: `PAYMENT_SELECTION_STALE` when `selectedPaymentMethod` / `selectedPaymentInstrumentCode` are no longer in live gateway capabilities (storefront re-prompts the buyer). Read-only — backend state is not mutated. Added by payment-instrument-preselection-advanced sub-sprint Adv-2 Req 1.
+  """
+  warnings: [CartWarning!]!
 }
 
 """Result of `cartAddLines`."""
@@ -1171,6 +1183,30 @@ input CartBuyerIdentityInput {
   phone: String
 }
 
+"""
+Input for `cartClearPaymentSelection` — explicit deselect mutation. Use when the buyer goes back to the payment method picker w accordion UI bez hack typu re-selectując method. Atomic NULL na wszystkich payment selection fields (method type + provider code + instrument code + legacy method ID). Idempotent — wielokrotne wywołanie = same final state. Added by payment-instrument-preselection-advanced Adv-1 Req 3.1.
+"""
+input CartClearPaymentSelectionInput {
+  """ID of the cart to clear payment selection on."""
+  cartId: ID!
+}
+
+"""
+Result of `cartClearPaymentSelection`. `cart` populated on success z cleared selection fields (`selectedPaymentMethod === null`, `selectedPaymentInstrumentCode === null`). `userErrors` populated gdy cart locked (CONVERTED status → `ALREADY_COMPLETED` code).
+"""
+type CartClearPaymentSelectionPayload {
+  """The updated cart z cleared payment selection."""
+  cart: Cart
+
+  """
+  Business / validation errors carrying a stable `CartErrorCode` in `code` (e.g. `ALREADY_COMPLETED`).
+  """
+  userErrors: [UserError!]!
+
+  """Non-fatal advisories — the mutation itself succeeded."""
+  warnings: [CartWarning!]!
+}
+
 """Input for `cartComplete` — finalises the cart into an `Order`."""
 input CartCompleteInput {
   """ID of the cart to complete."""
@@ -1360,6 +1396,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`.
   """
@@ -1546,15 +1587,27 @@ type CartRemoveLinesPayload {
   warnings: [CartWarning!]!
 }
 
-"""Input for `cartSelectPaymentMethod`."""
+"""
+Input for `cartSelectPaymentMethod` (Intelligent Payment Methods). Method-centric: the buyer picks a category (BLIK, CARD, BANK_TRANSFER, ...) and the backend resolves the preferred provider from `MerchantPaymentConfig` (priority-sorted, merchant-configurable per shop). Optional `preferredProviderCode` + `preferredInstrumentCode` enable instrument-level deep-link na gateway hosted page (skipa default landing).
+"""
 input CartSelectPaymentMethodInput {
   """ID of the cart to update."""
   cartId: ID!
 
   """
-  ID of the chosen payment method (matches a `PaymentMethod.id` from `availablePaymentMethods`).
+  Category of the payment method the buyer picked (matches `PaymentMethod.type` from `availablePaymentMethods`).
+  """
+  methodType: PaymentMethodType!
+
+  """
+  Optional gateway-specific instrument code (`blik`, `mb`, `c`, `154`, ...) z `PaymentMethod.instruments[].instrumentCode`. Wymaga ustawienia `preferredProviderCode` — instrument code jest provider-specific. Bez restrictive regex (różne bramki używają `.` / `:` / `/` w przyszłości). SQL injection chroniona przez Prisma parametrized queries. Added by payment-instrument-preselection core sprint Req 3.1.
+  """
+  preferredInstrumentCode: String
+
   """
-  paymentMethodId: ID!
+  Optional override of `PaymentMethod.preferredProvider`. Pass a provider code (`payu`, `przelewy24`, ...) from `providersAvailable` when the buyer explicitly picks one (rare — usually the merchant priority is enough). Format: lowercase alphanumerics + underscore + hyphen, 2-50 characters. Renamed from `preferredProviderId` — `*Code` is reserved for lowercase string identifiers, `*Id` for UUIDs.
+  """
+  preferredProviderCode: String
 }
 
 """Result of `cartSelectPaymentMethod`."""
@@ -1802,6 +1855,7 @@ enum CartWarningCode {
   MERCHANDISE_NOT_AVAILABLE
   MERCHANDISE_NOT_ENOUGH_STOCK
   PAYMENTS_AMOUNT_REGION_MISMATCH
+  PAYMENT_SELECTION_STALE
   SHIPPING_METHOD_AUTO_CLEARED
 }
 
@@ -3025,6 +3079,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
@@ -3822,6 +3892,11 @@ type Mutation {
   """
   cartApplyGiftCard(input: CartApplyGiftCardInput!): CartApplyGiftCardPayload!
 
+  """
+  Clear all payment selection state on the cart in a single atomic operation. Use for accordion "back to method picker" flows w storefront UI. Idempotent — calling twice yields the same end state. Cart MUSI być `ACTIVE` (CONVERTED carts reject z `ALREADY_COMPLETED`).
+  """
+  cartClearPaymentSelection(input: CartClearPaymentSelectionInput!): CartClearPaymentSelectionPayload!
+
   """
   Finalise the cart into an `Order`. The cart is locked and no longer accepts mutations. Payment is initiated separately via `paymentCreate` — check `order.canCreatePayment` to decide whether to render a "Pay now" button or send the buyer directly to the confirmation page (for offline methods such as cash on delivery). Rate-limited to 5 requests per minute per IP+shop; pass an `idempotencyKey` to guard against duplicate orders on retry.
   """
@@ -3848,7 +3923,7 @@ type Mutation {
   cartRemoveLines(id: ID!, lineIds: [ID!]!): CartRemoveLinesPayload!
 
   """
-  Select a payment method on the cart. Validates against the active shop payment methods and currency. The selection is finalised at `cartComplete`; payment itself is initiated via a separate `paymentCreate` mutation after the order is created.
+  Select a payment method on the cart by category (BLIK, CARD, BANK_TRANSFER, ...). Backend resolves the preferred provider from `MerchantPaymentConfig` at `paymentCreate` time. Optional `preferredProviderCode` overrides the merchant priority when the buyer explicitly picks a gateway from `PaymentMethod.providersAvailable`. Optional `preferredInstrumentCode` enables instrument-level deep-link na gateway hosted page (BLIK ekran, mBank flow, etc.) — wymaga `preferredProviderCode`.
   """
   cartSelectPaymentMethod(input: CartSelectPaymentMethodInput!): CartSelectPaymentMethodPayload!
 
@@ -4316,9 +4391,14 @@ type PaymentCreatePayload {
   payment: PaymentSession
 
   """
-  Business / validation errors carrying a stable `PaymentErrorCode` in `code` (e.g. `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `PAYMENT_FAILED`).
+  Business / validation errors carrying a stable `PaymentErrorCode` in `code` (e.g. `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `PAYMENT_FAILED`, `INSTRUMENT_PRESELECTION_FAILED`).
   """
   userErrors: [UserError!]!
+
+  """
+  Non-blocking signals — backend state change context (e.g. instrument auto-cleared, server-side adjustment). Default empty array. Storefront branches per `code` for UI retry hints / analytics events. Added by payment-instrument-preselection-advanced Adv-1 Req 2.3.
+  """
+  warnings: [PaymentWarning!]!
 }
 
 """
@@ -4335,6 +4415,11 @@ enum PaymentInitiationFlow {
 A payment method offered to the buyer at checkout — what to render in the payment picker and pass to `cartSelectPaymentMethod`.
 """
 type PaymentMethod {
+  """
+  True when the buyer can actually pick this method right now. False when the resolving gateway is temporarily unavailable (incident/maintenance) or reported the method as disabled. Storefront UI should gray-out the tile when false instead of hiding it — gives merchants observability into routing failures.
+  """
+  available: Boolean!
+
   """
   Optional buyer-facing description shown under the name (e.g. "Pay with your bank app").
   """
@@ -4350,6 +4435,11 @@ type PaymentMethod {
   """
   id: ID!
 
+  """
+  Concrete instruments exposed by gateway providers w obrębie tej method (BLIK code, branded banks, wallets, card brands). Null gdy żaden provider nie expose'uje granular data dla tej method. Empty array gdy gateway expose'uje ale wszystkie instruments są disabled lub po post-filter (cross-provider leak prevention). Storefront może wyrenderować listę i pass `instrumentCode` jako `preferredInstrumentCode` w `cartSelectPaymentMethod` → gateway deep-link na ten ekran. Added by payment-instrument-preselection core sprint Req 1.
+  """
+  instruments: [PaymentMethodInstrument!]
+
   """
   True when the merchant has marked this method as the default. Pre-select it in the picker.
   """
@@ -4366,9 +4456,19 @@ type PaymentMethod {
   position: Float!
 
   """
-  Provider code (e.g. "payu", "stripe", "p24", "cash_on_delivery"). Identifies the integration behind the method; do not branch UI on it — use `type` instead.
+  Preferred provider code (UPPERCASE enum) that the backend will route to when the buyer picks this method type and does not specify `preferredProviderCode`. Populated only when at least one provider supports the type. Typed enum since core sprint payment-instrument-preselection (was `String` pre-v9.0).
   """
-  provider: String!
+  preferredProvider: ProviderCode
+
+  """
+  Provider code (e.g. `PAYU`, `STRIPE`, `PRZELEWY24`, `CASH_ON_DELIVERY`). Identifies the integration behind the method; do not branch UI on it — use `type` instead. Typed enum since core sprint payment-instrument-preselection (was `String` pre-v9.0).
+  """
+  provider: ProviderCode!
+
+  """
+  Provider codes (UPPERCASE enum: `PAYU`, `PRZELEWY24`, ...) that can fulfil this method type for the current shop, ordered by merchant priority. Pre-select `preferredProvider`; expose the rest only when the buyer wants to choose explicitly. Single-element array when only one provider supports the type. Typed enum since core sprint payment-instrument-preselection (was `[String]` pre-v9.0).
+  """
+  providersAvailable: [ProviderCode!]
 
   """
   ISO 4217 currency codes the method accepts. Null when the method accepts the shop currency without restriction.
@@ -4379,6 +4479,72 @@ type PaymentMethod {
   Category of the method (CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY, OTHER). Drives iconography and copy.
   """
   type: PaymentMethodType!
+
+  """
+  When `available` is false, this enum carries the diagnostic reason (GATEWAY_DOWN, GATEWAY_DISABLED, NO_INSTRUMENTS, CREDENTIALS_INVALID). Null when `available` is true. UI can render context-aware copy ("PayU is temporarily down" vs "Method not configured").
+  """
+  unavailableReason: PaymentMethodUnavailableReason
+}
+
+"""
+A single concrete instrument exposed by a gateway provider (e.g. BLIK code, mBank Pay-By-Link, Apple Pay) within a broader PaymentMethod. Pass `instrumentCode` jako `preferredInstrumentCode` w `cartSelectPaymentMethod` żeby gateway deep-link prosto na ten ekran.
+"""
+type PaymentMethodInstrument {
+  """
+  Optional brand image URL (bank logo, wallet icon). Storefront może użyć jako tile artwork. Null gdy gateway nie expose'uje albo instrument nie ma brand visual (BLIK code).
+  """
+  brandImageUrl: String
+
+  """
+  UX rendering hint — jak storefront powinien wyrenderować ten instrument (prominent button vs branded tile vs dropdown vs radio). Backend-agnostic mapping na visual treatment.
+  """
+  displayHint: PaymentMethodInstrumentDisplayHint!
+
+  """
+  Buyer-facing display name (e.g. "BLIK", "mBank", "ING Bank Śląski", "Apple Pay"). Lokalizacja zazwyczaj PL/EN — multi-language defer post-v1.
+  """
+  displayName: String!
+
+  """
+  True gdy instrument jest currently enabled w gateway live capabilities. Storefront może gray-out tile gdy false zamiast hide (observability dla merchant).
+  """
+  enabled: Boolean!
+
+  """
+  Gateway-specific instrument identifier (PayU: `"blik"`/`"mb"`/`"c"`, P24: numeric ID string `"154"`). Pass jako `preferredInstrumentCode` w `cartSelectPaymentMethod`. Stabilne per provider — gateway nie renumeruje.
+  """
+  instrumentCode: String!
+
+  """
+  Provider obsługujący ten instrument (UPPERCASE enum). Wymagane dla cross-provider dedupe (np. BLIK code dostępny zarówno przez PayU jak P24 — różne instrumenty mimo tej samej method type).
+  """
+  providerCode: ProviderCode!
+
+  """
+  Semantic type klasyfikujący instrument w obrębie method (BLIK code vs bank vs wallet vs card brand). Storefront-facing dispatch dla per-instrument UI components.
+  """
+  type: PaymentMethodInstrumentType!
+}
+
+"""
+UX rendering hint dla payment instrument — storefront może przełączać między prominent button / branded tile / dropdown / radio per hint. Backend-agnostic mapping na visual treatment.
+"""
+enum PaymentMethodInstrumentDisplayHint {
+  BRANDED_TILE
+  DROPDOWN_OPTION
+  PROMINENT_BUTTON
+  RADIO_OPTION
+}
+
+"""
+Klasyfikacja konkretnego instrumentu w obrębie PaymentMethod (BLIK kod vs bank vs wallet vs card brand). Storefront-facing typing dla per-instrument UI dispatch.
+"""
+enum PaymentMethodInstrumentType {
+  BANK
+  BLIK_CODE
+  CARD_BRAND
+  OTHER
+  WALLET
 }
 
 """
@@ -4392,6 +4558,16 @@ enum PaymentMethodType {
   OTHER
 }
 
+"""
+Why a payment method is currently unavailable. GATEWAY_DOWN/DISABLED/NO_INSTRUMENTS are transient (gateway-side); CREDENTIALS_INVALID needs merchant action in the admin panel.
+"""
+enum PaymentMethodUnavailableReason {
+  CREDENTIALS_INVALID
+  GATEWAY_DISABLED
+  GATEWAY_DOWN
+  NO_INSTRUMENTS
+}
+
 """
 Payment session created for an order. Branch on `flow` to launch payment: ONLINE_REDIRECT → redirect to `redirectUrl`; ONLINE_EMBEDDED → render an in-page widget using `clientSecret`; INSTANT_DIRECT → the payment is already settled, check `status`.
 """
@@ -4450,6 +4626,33 @@ type PaymentSettings {
   paymentProviders: [String!]!
 }
 
+"""
+Non-blocking signal emitted alongside `userErrors` — backend state change context (e.g. an auto-clear, a server-side adjustment) that the storefront may surface as a retry hint or analytics event. Always pre-translated by backend per shop locale.
+"""
+type PaymentWarning {
+  """
+  Machine-readable code — branch on this to dispatch UI retry hints. Add a new code only when there is a distinct UX response.
+  """
+  code: PaymentWarningCode!
+
+  """
+  Pre-translated user-facing message describing what happened (Polish-first per shop locale).
+  """
+  message: String!
+
+  """
+  Optional additional hint string for UI dispatch — currently unused for `INSTRUMENT_CLEARED_FOR_RETRY` (semantic encoded in `message`). Reserved for future warning codes (e.g. `SLOW_GATEWAY_RESPONSE` → "Retry in 30s").
+  """
+  retryHint: String
+}
+
+"""
+Machine-readable code for `PaymentWarning.code`. Non-blocking signals from payment mutations — branch on this to dispatch UI retry hints. `INSTRUMENT_CLEARED_FOR_RETRY` indicates backend auto-cleared a preselected payment instrument after gateway rejection; next `paymentCreate` will land on the gateway default page.
+"""
+enum PaymentWarningCode {
+  INSTRUMENT_CLEARED_FOR_RETRY
+}
+
 """
 A pickup point (parcel locker or staffed collection point) attached to a delivery address. The buyer picks it in the carrier widget; it is persisted on the cart shipping address and carried through to the order.
 """
@@ -5140,6 +5343,20 @@ enum ProductVisibility {
   PUBLIC
 }
 
+"""
+Canonical payment provider identifier (UPPERCASE per GraphQL convention). Use for `Order.paymentMethod`, `Payment.provider`, `PaymentMethod.providersAvailable`, `PaymentMethod.preferredProvider`. Add new providers in `@doswiftly/commerce-policy/provider-codes.ts` SSOT registry.
+"""
+enum ProviderCode {
+  BANK_TRANSFER
+  CASH_ON_DELIVERY
+  GIFT_CARD
+  MANUAL_PAYMENT
+  PAYU
+  PRZELEWY24
+  STRIPE
+  TEST_GATEWAY
+}
+
 type Query {
   """List of all currencies supported by the system (ECB rates)"""
   allSupportedCurrencies: [Currency!]!
@@ -5150,7 +5367,7 @@ type Query {
   attributeOptionsSearch(input: AttributeOptionsSearchInput!): AttributeFilterValueConnection!
 
   """
-  Payment methods active for the current shop, plus the merchant default. Shop-level — independent of cart contents in this iteration. Fetch once for the checkout payment step.
+  Payment methods active for the current shop, plus the merchant default. Returns one row per `PaymentMethodType` (BLIK, CARD, BANK_TRANSFER, ...) with `providersAvailable` (provider codes sorted by merchant priority) and `preferredProvider` (the head of the list). Shop-level — independent of cart contents.
   """
   availablePaymentMethods: AvailablePaymentMethods!