@doswiftly/storefront-operations 5.4.1 → 6.0.0

package/schema.graphql

@@ -3,9 +3,29 @@
 # ------------------------------------------------------
 
 """
-Sets contextual hints on an operation (Shopify Storefront API parity). Currently supports preferredLocationId; country/language/buyer will follow.
+Sets contextual hints on an operation — country, language, currency, buyer, preferredLocationId. Resolution priority: directive > request header > cookie > auto-detect > shop default.
 """
 directive @inContext(
+  """
+  B2B / impersonation buyer context. Use for explicit auth (admin acting as customer) or company-location catalog scoping. Browser storefronts should prefer cookie / Bearer header.
+  """
+  buyer: BuyerInput
+
+  """
+  ISO 3166-1 alpha-2 country code (e.g. "PL", "DE"). Drives Markets pricing / shipping availability. Validated against shop config — unknown codes silently fall through to next priority layer.
+  """
+  country: String
+
+  """
+  ISO 4217 currency code (e.g. "EUR", "USD"). Constrained to `shop.supportedCurrencies` — unsupported codes silently fall through. Typically inferred from `country` via Markets.
+  """
+  currency: String
+
+  """
+  ISO 639-1 language code (e.g. "pl", "en"). Constrained to `shop.supportedLanguages` — unsupported codes silently fall through. Avoids `Accept-Language` ambiguity for SSR / Edge.
+  """
+  language: String
+
   """
   Biases field resolvers (e.g. storeAvailability) toward this location. Must reference an active InventoryLocation in the current shop — invalid / inactive IDs are silently ignored by resolvers.
   """
@@ -135,7 +155,7 @@ input AttributeInput {
 }
 
 """
-Surcharge calculation: FIXED (minor units) or PERCENT (thousandths of percent — Faza 2)
+Surcharge calculation: FIXED (minor units) or PERCENT (thousandths of percent)
 """
 enum AttributeOptionSurchargeType {
   FIXED
@@ -242,8 +262,10 @@ enum AttributeType {
 
 """Available filters for product listing"""
 type AvailableFilters {
-  """Number of currently active filters"""
-  activeFilterCount: Int!
+  """
+  Number of currently active filters (renamed from activeFilterCount in Storefront 5.0)
+  """
+  activeCount: Int!
 
   """Filterable attributes with values"""
   attributes: [AttributeDefinition!]!
@@ -251,11 +273,13 @@ type AvailableFilters {
   """Categories available for filtering"""
   categories: [CategoryFilterOption!]
 
+  """
+  Total products matching current context, before filters (renamed from totalProducts in Storefront 5.0)
+  """
+  matchCount: Int!
+
   """Price range for filtering"""
   priceRange: PriceRange
-
-  """Total products matching current context (before filters)"""
-  totalProducts: Int!
 }
 
 """Context for available filters query"""
@@ -326,12 +350,12 @@ type AvailableShippingMethodsPayload {
 
 """Live carrier shipping rates payload"""
 type AvailableShippingRatesPayload {
-  """Whether the result was served from cache"""
-  cached: Boolean!
-
   """Providers that failed to return rates"""
   errors: [CarrierRateError!]!
 
+  """Whether the result was served from cache"""
+  isCached: Boolean!
+
   """Available rates sorted by price"""
   rates: [CarrierShippingRate!]!
 }
@@ -431,11 +455,11 @@ type BlogPost {
   """Full content (HTML)"""
   content: String!
 
-  """Content type (html or markdown)"""
-  contentType: String!
+  """Format of stored content (HTML or MARKDOWN)"""
+  contentFormat: ContentFormat!
 
   """Created date (ISO 8601)"""
-  createdAt: String!
+  createdAt: DateTime!
 
   """Short excerpt/summary"""
   excerpt: String
@@ -450,10 +474,10 @@ type BlogPost {
   isFeatured: Boolean!
 
   """Published date (ISO 8601)"""
-  publishedAt: String
+  publishedAt: DateTime
 
   """Estimated reading time in minutes"""
-  readingTime: Int!
+  readingTimeMinutes: Int!
 
   """SEO metadata"""
   seo: SEO
@@ -471,7 +495,7 @@ type BlogPost {
   title: String!
 
   """Updated date (ISO 8601)"""
-  updatedAt: String!
+  updatedAt: DateTime!
 
   """View count"""
   viewCount: Int!
@@ -553,6 +577,42 @@ type BotProtectionProviderInfo {
   siteKey: String!
 }
 
+"""Shop brand metadata (logo, colors, slogan)"""
+type Brand {
+  """Primary + secondary brand colors"""
+  colors: BrandColors
+
+  """Cover image / hero banner"""
+  coverImage: Image
+
+  """Primary logo"""
+  logo: Image
+
+  """Short brand description"""
+  shortDescription: String
+
+  """Marketing slogan / tagline"""
+  slogan: String
+
+  """Square logo variant (favicons, app tiles)"""
+  squareLogo: Image
+}
+
+"""Single brand color group (background + foreground hex)"""
+type BrandColorGroup {
+  """Background color (hex, e.g. "#0F172A")"""
+  background: String
+
+  """Foreground/text color (hex)"""
+  foreground: String
+}
+
+"""Pair of brand color groups (primary + secondary)"""
+type BrandColors {
+  primary: BrandColorGroup
+  secondary: BrandColorGroup
+}
+
 """Business hours for a day"""
 type BusinessHour {
   """Closing time (HH:MM format)"""
@@ -601,6 +661,19 @@ type BusinessHoursWindow {
   openHour: Int!
 }
 
+"""
+Buyer context for `@inContext` — supports B2B impersonation and company-scoped catalog.
+"""
+input BuyerInput {
+  """B2B company location ID (planned — multi-location buyer scoping)."""
+  companyLocationId: ID
+
+  """
+  Customer JWT for explicit auth context (mobile / server-to-server / admin impersonation). For browser storefronts prefer the httpOnly `customerAccessToken` cookie or `Authorization: Bearer` header — directive args are propagated through query logs.
+  """
+  customerAccessToken: String
+}
+
 """Provider error when fetching rates"""
 type CarrierRateError {
   """Error message"""
@@ -612,14 +685,14 @@ type CarrierRateError {
 
 """Live shipping rate from a carrier"""
 type CarrierShippingRate {
-  """Whether cash on delivery is available"""
-  cashOnDeliveryAvailable: Boolean!
-
   """Estimated delivery in business days"""
   estimatedDeliveryDays: Int!
 
+  """Whether cash on delivery is available"""
+  isCashOnDeliveryAvailable: Boolean!
+
   """Whether pickup is available for this service"""
-  pickupAvailable: Boolean!
+  isPickupAvailable: Boolean!
 
   """Rate price"""
   price: Money!
@@ -635,7 +708,7 @@ type CarrierShippingRate {
 }
 
 """Shopping cart"""
-type Cart {
+type Cart implements Node {
   """Cart attributes"""
   attributes: [CartAttribute!]!
 
@@ -643,7 +716,7 @@ type Cart {
   buyerIdentity: CartBuyerIdentity
 
   """Checkout URL"""
-  checkoutUrl: String
+  checkoutUrl: URL
 
   """Cost breakdown"""
   cost: CartCost!
@@ -660,8 +733,8 @@ type Cart {
   """Unique cart identifier"""
   id: ID!
 
-  """Cart line items"""
-  lines(first: Float = 100): [CartLine!]!
+  """Cart line items (Relay Connection)"""
+  lines(after: String, before: String, first: Float, last: Float): CartLineConnection!
 
   """Cart note"""
   note: String
@@ -676,6 +749,34 @@ type Cart {
   updatedAt: DateTime!
 }
 
+"""Result of adding lines to cart"""
+type CartAddLinesPayload {
+  """Updated cart"""
+  cart: Cart
+
+  """
+  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  """
+  userErrors: [UserError!]!
+
+  """Non-fatal warnings"""
+  warnings: [CartWarning!]!
+}
+
+"""Result of applying discount codes"""
+type CartApplyDiscountCodesPayload {
+  """Updated cart"""
+  cart: Cart
+
+  """
+  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  """
+  userErrors: [UserError!]!
+
+  """Non-fatal warnings"""
+  warnings: [CartWarning!]!
+}
+
 """Cart line attribute"""
 type CartAttribute {
   """Attribute key"""
@@ -694,19 +795,10 @@ input CartAttributeInput {
   value: String
 }
 
-"""Result of updating cart attributes"""
-type CartAttributesUpdatePayload {
-  """Updated cart"""
-  cart: Cart
-
-  """User errors"""
-  userErrors: [UserError!]!
-}
-
 """Buyer identity information"""
 type CartBuyerIdentity {
-  """Country code (ISO 3166-1 alpha-2)"""
-  countryCode: String
+  """ISO 3166-1 alpha-2 country code"""
+  countryCode: CountryCode
 
   """Customer ID"""
   customerId: ID
@@ -714,14 +806,17 @@ type CartBuyerIdentity {
   """Customer email"""
   email: String
 
+  """ISO 639-1 preferred language code"""
+  languageCode: LanguageCode
+
   """Customer phone"""
   phone: String
 }
 
 """Input for buyer identity"""
 input CartBuyerIdentityInput {
-  """Country code (ISO 3166-1 alpha-2)"""
-  countryCode: String
+  """ISO 3166-1 alpha-2 country code"""
+  countryCode: CountryCode
 
   """Customer ID"""
   customerId: ID
@@ -729,35 +824,44 @@ input CartBuyerIdentityInput {
   """Customer email"""
   email: String
 
+  """ISO 639-1 preferred language code"""
+  languageCode: LanguageCode
+
   """Customer phone"""
   phone: String
 }
 
-"""Result of updating buyer identity"""
-type CartBuyerIdentityUpdatePayload {
-  """Updated cart"""
-  cart: Cart
-
-  """User errors"""
-  userErrors: [UserError!]!
-}
-
 """Cart cost breakdown"""
 type CartCost {
-  """Checkout charge amount"""
-  checkoutChargeAmount: PriceMoney
+  """Checkout charge amount."""
+  checkoutCharge: Money
 
-  """Subtotal before taxes and shipping (in customer currency)"""
-  subtotalAmount: PriceMoney!
+  """Opt-in: checkoutCharge with conversion transparency."""
+  checkoutChargeWithConversion: PriceMoney
 
-  """Total amount including taxes (in customer currency)"""
-  totalAmount: PriceMoney!
+  """Subtotal before taxes and shipping. Default field."""
+  subtotal: Money!
 
-  """Total duty amount"""
-  totalDutyAmount: PriceMoney
+  """Opt-in: subtotal with full conversion transparency."""
+  subtotalWithConversion: PriceMoney
 
-  """Total tax amount"""
-  totalTaxAmount: PriceMoney
+  """Total amount including taxes."""
+  total: Money!
+
+  """Total duty amount."""
+  totalDuty: Money
+
+  """Opt-in: totalDuty with conversion transparency."""
+  totalDutyWithConversion: PriceMoney
+
+  """Total tax amount."""
+  totalTax: Money
+
+  """Opt-in: totalTax with conversion transparency."""
+  totalTaxWithConversion: PriceMoney
+
+  """Opt-in: total with conversion transparency."""
+  totalWithConversion: PriceMoney
 }
 
 """Input for creating a cart"""
@@ -783,8 +887,13 @@ type CartCreatePayload {
   """Created cart"""
   cart: Cart
 
-  """User errors"""
+  """
+  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  """
   userErrors: [UserError!]!
+
+  """Non-fatal warnings"""
+  warnings: [CartWarning!]!
 }
 
 """Discount allocation showing how discount is applied"""
@@ -798,32 +907,19 @@ type CartDiscountAllocation {
 
 """Discount code applied to cart"""
 type CartDiscountCode {
-  """Whether the code is applicable"""
-  applicable: Boolean!
-
   """Discount code string"""
   code: String!
-}
-
-"""Result of updating discount codes"""
-type CartDiscountCodesUpdatePayload {
-  """Updated cart"""
-  cart: Cart
 
-  """User errors"""
-  userErrors: [UserError!]!
+  """Whether the code is applicable"""
+  isApplicable: Boolean!
 }
 
 """Single line item in the cart"""
 type CartLine {
-  """
-  Typed customer-filled attribute selections (Faza 1 R5 — surcharge + tax snapshot)
-  """
+  """Typed customer-filled attribute selections (surcharge + tax snapshot)"""
   attributeSelections: [AttributeSelection!]!
 
-  """
-  Shopify-compatible Line Item Properties — raw key/value pairs (e.g., gift wrap, engraving)
-  """
+  """Line Item Properties — raw key/value pairs"""
   attributes: [Attribute!]!
 
   """Cost information for this line"""
@@ -832,9 +928,6 @@ type CartLine {
   """Unique line identifier"""
   id: ID!
 
-  """Product variant being purchased"""
-  merchandise: ProductVariant!
-
   """Parent product handle (slug)"""
   productHandle: String
 
@@ -849,21 +942,60 @@ type CartLine {
 
   """Quantity of this item"""
   quantity: Int!
+
+  """Product variant being purchased"""
+  variant: ProductVariant!
+}
+
+"""Paginated cart lines"""
+type CartLineConnection {
+  """Cart line edges with cursors"""
+  edges: [CartLineEdge!]!
+
+  """Cart line nodes (shortcut for edges.map(e => e.node))"""
+  nodes: [CartLine!]!
+
+  """Pagination info"""
+  pageInfo: PageInfo!
+
+  """Total count of cart lines"""
+  totalCount: Int!
 }
 
 """Cost information for a single cart line"""
 type CartLineCost {
-  """Amount per quantity (in customer currency)"""
-  amountPerQuantity: PriceMoney!
+  """Compare-at price per unit if discounted."""
+  compareAtPricePerUnit: Money
 
-  """Original price per quantity if discounted"""
-  compareAtAmountPerQuantity: PriceMoney
+  """Opt-in: compareAtPricePerUnit with conversion transparency."""
+  compareAtPricePerUnitWithConversion: PriceMoney
 
-  """Subtotal before discounts (in customer currency)"""
-  subtotalAmount: PriceMoney!
+  """Price per unit. Default field — shop base currency."""
+  pricePerUnit: Money!
 
-  """Total after discounts (in customer currency)"""
-  totalAmount: PriceMoney!
+  """Opt-in: pricePerUnit with conversion transparency."""
+  pricePerUnitWithConversion: PriceMoney
+
+  """Subtotal before discounts."""
+  subtotal: Money!
+
+  """Opt-in: subtotal with conversion transparency."""
+  subtotalWithConversion: PriceMoney
+
+  """Total after discounts."""
+  total: Money!
+
+  """Opt-in: total with conversion transparency."""
+  totalWithConversion: PriceMoney
+}
+
+"""Edge in a CartLine connection"""
+type CartLineEdge {
+  """Cursor for pagination"""
+  cursor: String!
+
+  """Cart line node"""
+  node: CartLine!
 }
 
 """Input for adding a line to cart"""
@@ -871,14 +1003,14 @@ input CartLineInput {
   """Customer-filled AttributeDefinition selections (Faza 1 R5)"""
   attributeSelections: [AttributeSelectionInput!]
 
-  """Line attributes (Shopify Line Item Properties)"""
+  """Line attributes (Line Item Properties)"""
   attributes: [AttributeInput!]
 
-  """Product variant ID"""
-  merchandiseId: ID!
-
   """Quantity to add"""
   quantity: Int! = 1
+
+  """Product variant ID"""
+  variantId: ID!
 }
 
 """Input for updating a cart line"""
@@ -888,7 +1020,7 @@ input CartLineUpdateInput {
   """
   attributeSelections: [AttributeSelectionInput!]
 
-  """Updated Shopify Line Item Properties (null preserves)"""
+  """Updated Line Item Properties (null preserves)"""
   attributes: [AttributeInput!]
 
   """Cart line ID to update"""
@@ -898,61 +1030,114 @@ input CartLineUpdateInput {
   quantity: Int!
 }
 
-"""Result of adding lines to cart"""
-type CartLinesAddPayload {
+"""Recommendations based on cart contents"""
+type CartRecommendations {
+  """Products frequently bought together with cart items"""
+  frequentlyBoughtTogether: [ProductRecommendation!]!
+
+  """Products to consider adding"""
+  youMayAlsoLike: [ProductRecommendation!]!
+}
+
+"""Result of removing cart lines"""
+type CartRemoveLinesPayload {
   """Updated cart"""
   cart: Cart
 
-  """User errors"""
+  """
+  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  """
   userErrors: [UserError!]!
+
+  """Non-fatal warnings"""
+  warnings: [CartWarning!]!
 }
 
-"""Result of removing cart lines"""
-type CartLinesRemovePayload {
+"""Cart data for shipping calculation"""
+input CartShippingInput {
+  """Currency code (ISO 4217)"""
+  currencyCode: String
+
+  """Cart subtotal in cents"""
+  subtotal: Int
+
+  """Total weight in grams"""
+  totalWeight: Int
+}
+
+"""Result of updating cart attributes"""
+type CartUpdateAttributesPayload {
   """Updated cart"""
   cart: Cart
 
-  """User errors"""
+  """
+  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  """
   userErrors: [UserError!]!
+
+  """Non-fatal warnings"""
+  warnings: [CartWarning!]!
 }
 
-"""Result of updating cart lines"""
-type CartLinesUpdatePayload {
+"""Result of updating buyer identity"""
+type CartUpdateBuyerIdentityPayload {
   """Updated cart"""
   cart: Cart
 
-  """User errors"""
+  """
+  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  """
   userErrors: [UserError!]!
+
+  """Non-fatal warnings"""
+  warnings: [CartWarning!]!
 }
 
-"""Result of updating cart note"""
-type CartNoteUpdatePayload {
+"""Result of updating cart lines"""
+type CartUpdateLinesPayload {
   """Updated cart"""
   cart: Cart
 
-  """User errors"""
+  """
+  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  """
   userErrors: [UserError!]!
+
+  """Non-fatal warnings"""
+  warnings: [CartWarning!]!
 }
 
-"""Recommendations based on cart contents"""
-type CartRecommendations {
-  """Products frequently bought together with cart items"""
-  frequentlyBoughtTogether: [ProductRecommendation!]!
+"""Result of updating cart note"""
+type CartUpdateNotePayload {
+  """Updated cart"""
+  cart: Cart
 
-  """Products to consider adding"""
-  youMayAlsoLike: [ProductRecommendation!]!
+  """
+  User errors (code is namespaced — e.g. CART_NOT_FOUND, CART_LINE_NOT_FOUND)
+  """
+  userErrors: [UserError!]!
+
+  """Non-fatal warnings"""
+  warnings: [CartWarning!]!
 }
 
-"""Cart data for shipping calculation"""
-input CartShippingInput {
-  """Currency code (ISO 4217)"""
-  currencyCode: String
+"""Cart warning (non-fatal advisory)"""
+type CartWarning {
+  """Typed warning code"""
+  code: CartWarningCode!
 
-  """Cart subtotal in cents"""
-  subtotal: Int
+  """Warning message"""
+  message: String!
 
-  """Total weight in grams"""
-  totalWeight: Int
+  """Target identifier (cart line ID lub field path)"""
+  target: String!
+}
+
+"""Non-fatal cart warnings"""
+enum CartWarningCode {
+  MERCHANDISE_NOT_AVAILABLE
+  MERCHANDISE_NOT_ENOUGH_STOCK
+  PAYMENTS_AMOUNT_REGION_MISMATCH
 }
 
 """Product category - hierarchical organization"""
@@ -1018,6 +1203,12 @@ type CategoryEdge {
   node: Category!
 }
 
+"""Category filter"""
+input CategoryFilter {
+  """Category ID"""
+  id: ID
+}
+
 """Category filter option"""
 type CategoryFilterOption {
   """Category ID"""
@@ -1062,12 +1253,12 @@ type Checkout {
   """Billing address"""
   billingAddress: MailingAddress
 
-  """Whether checkout is completed"""
-  completed: Boolean!
-
   """Completed order ID"""
   completedOrderId: String
 
+  """Cost breakdown (subtotal/total/totalTax/totalShipping/totalDiscounts)"""
+  cost: CheckoutCost!
+
   """Created at"""
   createdAt: DateTime!
 
@@ -1089,6 +1280,12 @@ type Checkout {
   """Checkout ID"""
   id: ID!
 
+  """Whether checkout is completed"""
+  isCompleted: Boolean!
+
+  """Whether checkout is ready for payment"""
+  isReady: Boolean!
+
   """Line items"""
   lineItems: [CheckoutLineItem!]!
 
@@ -1101,9 +1298,6 @@ type Checkout {
   """Customer phone"""
   phone: String
 
-  """Whether checkout is ready for payment"""
-  ready: Boolean!
-
   """Selected payment method ID (Requirements: R23.5)"""
   selectedPaymentMethodId: ID
 
@@ -1116,30 +1310,15 @@ type Checkout {
   """Whether shipping rates are ready"""
   shippingRatesReady: Boolean!
 
-  """Subtotal before discounts and taxes"""
-  subtotalPrice: Money!
-
   """Tax breakdown"""
   taxLines: [TaxLine!]!
 
-  """Total discount amount"""
-  totalDiscounts: Money!
-
   """Total amount covered by gift cards"""
   totalGiftCardAmount: Money!
 
-  """Total price"""
-  totalPrice: Money!
-
   """Total quantity"""
   totalQuantity: Float!
 
-  """Total shipping price"""
-  totalShippingPrice: Money!
-
-  """Total tax amount"""
-  totalTax: Money!
-
   """Updated at"""
   updatedAt: DateTime!
 
@@ -1149,20 +1328,14 @@ type Checkout {
 
 """Mailing address input"""
 input CheckoutAddressInput {
-  """Address line 1"""
-  address1: String!
-
-  """Address line 2"""
-  address2: String
-
   """City"""
   city: String!
 
   """Company name"""
   company: String
 
-  """Country code (ISO)"""
-  country: String!
+  """ISO 3166-1 alpha-2 country code"""
+  country: CountryCode!
 
   """First name"""
   firstName: String
@@ -1173,20 +1346,39 @@ input CheckoutAddressInput {
   """Phone number"""
   phone: String
 
-  """Province/State"""
-  province: String
+  """Postal / ZIP code"""
+  postalCode: String!
+
+  """State / province"""
+  state: String
+
+  """First line of street address"""
+  streetLine1: String!
 
-  """ZIP/Postal code"""
-  zip: String!
+  """Second line of street address"""
+  streetLine2: String
 }
 
-"""Checkout billing address update payload"""
-type CheckoutBillingAddressUpdatePayload {
+"""Checkout discount code apply payload"""
+type CheckoutApplyDiscountCodePayload {
   """Updated checkout"""
   checkout: Checkout
 
-  """User errors"""
-  userErrors: [CheckoutUserError!]!
+  """
+  User errors (code is namespaced — e.g. CHECKOUT_NOT_FOUND, CHECKOUT_PAYMENT_FAILED)
+  """
+  userErrors: [UserError!]!
+}
+
+"""Checkout gift card apply payload"""
+type CheckoutApplyGiftCardPayload {
+  """Updated checkout"""
+  checkout: Checkout
+
+  """
+  User errors (code is namespaced — e.g. CHECKOUT_NOT_FOUND, CHECKOUT_PAYMENT_FAILED)
+  """
+  userErrors: [UserError!]!
 }
 
 """Checkout complete input"""
@@ -1209,8 +1401,28 @@ type CheckoutCompletePayload {
   """Payment redirect URL (if payment required)"""
   paymentUrl: String
 
-  """User errors"""
-  userErrors: [CheckoutUserError!]!
+  """
+  User errors (code is namespaced — e.g. CHECKOUT_NOT_FOUND, CHECKOUT_PAYMENT_FAILED)
+  """
+  userErrors: [UserError!]!
+}
+
+"""Checkout cost breakdown"""
+type CheckoutCost {
+  """Subtotal before discounts and taxes"""
+  subtotal: Money!
+
+  """Total amount (after discounts, including taxes and shipping)"""
+  total: Money!
+
+  """Total discount amount"""
+  totalDiscounts: Money!
+
+  """Total shipping cost"""
+  totalShipping: Money!
+
+  """Total tax amount"""
+  totalTax: Money!
 }
 
 """Checkout create input"""
@@ -1239,80 +1451,10 @@ type CheckoutCreatePayload {
   """Created checkout"""
   checkout: Checkout
 
-  """User errors"""
-  userErrors: [CheckoutUserError!]!
-}
-
-"""Checkout discount code apply payload"""
-type CheckoutDiscountCodeApplyPayload {
-  """Updated checkout"""
-  checkout: Checkout
-
-  """User errors"""
-  userErrors: [CheckoutUserError!]!
-}
-
-"""Checkout discount code remove payload"""
-type CheckoutDiscountCodeRemovePayload {
-  """Updated checkout"""
-  checkout: Checkout
-
-  """User errors"""
-  userErrors: [CheckoutUserError!]!
-}
-
-"""Checkout discount code validation result"""
-type CheckoutDiscountCodeValidatePayload {
-  """Validation result"""
-  result: DiscountValidationResult!
-
-  """User errors (for checkout-level issues)"""
-  userErrors: [CheckoutUserError!]!
-}
-
-"""Checkout email update payload"""
-type CheckoutEmailUpdatePayload {
-  """Updated checkout"""
-  checkout: Checkout
-
-  """User errors"""
-  userErrors: [CheckoutUserError!]!
-}
-
-"""Checkout error codes"""
-enum CheckoutErrorCode {
-  ALREADY_COMPLETED
-  BLANK
-  CART_NOT_FOUND
-  CHECKOUT_NOT_FOUND
-  CUSTOMER_ALREADY_USED_ONCE_PER_CUSTOMER_DISCOUNT_NOTICE
-  DISCOUNT_DISABLED
-  DISCOUNT_LIMIT_REACHED
-  DISCOUNT_NOT_FOUND
-  EMPTY_CART
-  GIFT_CARD_DEPLETED
-  GIFT_CARD_DISABLED
-  GIFT_CARD_EXPIRED
-  GIFT_CARD_NOT_FOUND
-  GIFT_CARD_UNUSABLE
-  INVALID
-  INVALID_PAYMENT_METHOD
-  INVALID_SHIPPING_ADDRESS
-  LINE_ITEM_NOT_FOUND
-  MISSING_SHIPPING_METHOD
-  NOT_ENOUGH_IN_STOCK
-  NO_PAYMENT_METHODS
-  SHIPPING_RATE_EXPIRED
-  TOO_LONG
-}
-
-"""Checkout gift card apply payload"""
-type CheckoutGiftCardApplyPayload {
-  """Updated checkout"""
-  checkout: Checkout
-
-  """User errors"""
-  userErrors: [CheckoutUserError!]!
+  """
+  User errors (code is namespaced — e.g. CHECKOUT_NOT_FOUND, CHECKOUT_PAYMENT_FAILED)
+  """
+  userErrors: [UserError!]!
 }
 
 """Gift card recipient input"""
@@ -1333,24 +1475,6 @@ input CheckoutGiftCardRecipientInput {
   recipientName: String
 }
 
-"""Checkout gift card recipient update payload"""
-type CheckoutGiftCardRecipientUpdatePayload {
-  """Updated checkout"""
-  checkout: Checkout
-
-  """User errors"""
-  userErrors: [CheckoutUserError!]!
-}
-
-"""Checkout gift card remove payload"""
-type CheckoutGiftCardRemovePayload {
-  """Updated checkout"""
-  checkout: Checkout
-
-  """User errors"""
-  userErrors: [CheckoutUserError!]!
-}
-
 """Checkout line item"""
 type CheckoutLineItem {
   """Line item ID"""
@@ -1359,6 +1483,9 @@ type CheckoutLineItem {
   """Product image"""
   image: Image
 
+  """Price per unit"""
+  pricePerUnit: Money!
+
   """Product ID"""
   productId: String
 
@@ -1371,11 +1498,8 @@ type CheckoutLineItem {
   """Product title"""
   title: String!
 
-  """Total price"""
-  totalPrice: Money!
-
-  """Unit price"""
-  unitPrice: Money!
+  """Total price for this line"""
+  total: Money!
 
   """Product variant"""
   variant: ProductVariant
@@ -1396,47 +1520,107 @@ input CheckoutLineItemInput {
   variantId: ID!
 }
 
-"""Checkout payment method update payload"""
-type CheckoutPaymentMethodUpdatePayload {
+"""Checkout discount code remove payload"""
+type CheckoutRemoveDiscountCodePayload {
   """Updated checkout"""
   checkout: Checkout
 
-  """User errors"""
-  userErrors: [CheckoutUserError!]!
+  """
+  User errors (code is namespaced — e.g. CHECKOUT_NOT_FOUND, CHECKOUT_PAYMENT_FAILED)
+  """
+  userErrors: [UserError!]!
 }
 
-"""Checkout shipping address update payload"""
-type CheckoutShippingAddressUpdatePayload {
+"""Checkout gift card remove payload"""
+type CheckoutRemoveGiftCardPayload {
   """Updated checkout"""
   checkout: Checkout
 
-  """User errors"""
-  userErrors: [CheckoutUserError!]!
+  """
+  User errors (code is namespaced — e.g. CHECKOUT_NOT_FOUND, CHECKOUT_PAYMENT_FAILED)
+  """
+  userErrors: [UserError!]!
+}
+
+"""Checkout payment method update payload"""
+type CheckoutSelectPaymentMethodPayload {
+  """Updated checkout"""
+  checkout: Checkout
+
+  """
+  User errors (code is namespaced — e.g. CHECKOUT_NOT_FOUND, CHECKOUT_PAYMENT_FAILED)
+  """
+  userErrors: [UserError!]!
 }
 
 """Checkout shipping line update payload"""
-type CheckoutShippingLineUpdatePayload {
+type CheckoutSelectShippingRatePayload {
   """Updated checkout"""
   checkout: Checkout
 
-  """User errors"""
-  userErrors: [CheckoutUserError!]!
+  """
+  User errors (code is namespaced — e.g. CHECKOUT_NOT_FOUND, CHECKOUT_PAYMENT_FAILED)
+  """
+  userErrors: [UserError!]!
 }
 
-"""Checkout user error"""
-type CheckoutUserError {
-  """Error code"""
-  code: CheckoutErrorCode
+"""Checkout billing address update payload"""
+type CheckoutUpdateBillingAddressPayload {
+  """Updated checkout"""
+  checkout: Checkout
+
+  """
+  User errors (code is namespaced — e.g. CHECKOUT_NOT_FOUND, CHECKOUT_PAYMENT_FAILED)
+  """
+  userErrors: [UserError!]!
+}
 
-  """Path to error field"""
-  field: [String!]!
+"""Checkout email update payload"""
+type CheckoutUpdateEmailPayload {
+  """Updated checkout"""
+  checkout: Checkout
 
-  """Error message"""
-  message: String!
+  """
+  User errors (code is namespaced — e.g. CHECKOUT_NOT_FOUND, CHECKOUT_PAYMENT_FAILED)
+  """
+  userErrors: [UserError!]!
+}
+
+"""Checkout gift card recipient update payload"""
+type CheckoutUpdateGiftCardRecipientPayload {
+  """Updated checkout"""
+  checkout: Checkout
+
+  """
+  User errors (code is namespaced — e.g. CHECKOUT_NOT_FOUND, CHECKOUT_PAYMENT_FAILED)
+  """
+  userErrors: [UserError!]!
+}
+
+"""Checkout shipping address update payload"""
+type CheckoutUpdateShippingAddressPayload {
+  """Updated checkout"""
+  checkout: Checkout
+
+  """
+  User errors (code is namespaced — e.g. CHECKOUT_NOT_FOUND, CHECKOUT_PAYMENT_FAILED)
+  """
+  userErrors: [UserError!]!
+}
+
+"""Checkout discount code validation result"""
+type CheckoutValidateDiscountCodePayload {
+  """Validation result"""
+  result: DiscountValidationResult!
+
+  """
+  User errors (for checkout-level issues; code is namespaced — e.g. CHECKOUT_NOT_FOUND)
+  """
+  userErrors: [UserError!]!
 }
 
 """Collection - curated group of products"""
-type Collection {
+type Collection implements Node {
   """Creation timestamp"""
   createdAt: DateTime!
 
@@ -1456,7 +1640,7 @@ type Collection {
   image: Image
 
   """Products in collection"""
-  products(after: String, first: Int = 20, reverse: Boolean = false, sortKey: ProductSortKeys = BEST_SELLING): ProductConnection!
+  products(after: String, before: String, filters: [ProductFilter!], first: Int, last: Int, reverse: Boolean = false, sortKey: ProductSortKeys = BEST_SELLING): ProductConnection!
 
   """SEO metadata"""
   seo: SEO
@@ -1503,6 +1687,12 @@ enum CompensationType {
   STORE_CREDIT
 }
 
+"""Format of stored content (HTML or MARKDOWN)"""
+enum ContentFormat {
+  HTML
+  MARKDOWN
+}
+
 """Price range in converted currency"""
 type ConvertedPriceRange {
   """Maximum variant price (converted)"""
@@ -1512,6 +1702,68 @@ type ConvertedPriceRange {
   minVariantPrice: PriceMoney!
 }
 
+"""Wspierany kraj sklepu (ISO 3166-1 alpha-2)"""
+type Country implements Node {
+  """Języki wspierane przez sklep dostępne w tym kraju"""
+  availableLanguages: [Language!]!
+
+  """Primary currency w tym kraju"""
+  currency: Currency!
+
+  """Globally-unique identifier (np. "country:PL")"""
+  id: ID!
+
+  """ISO 3166-1 alpha-2 country code"""
+  isoCode: CountryCode!
+
+  """English name kraju (np. "Poland", "Germany")"""
+  name: String!
+
+  """System jednostek (metric/imperial)"""
+  unitSystem: UnitSystem!
+}
+
+"""ISO 3166-1 alpha-2 country code"""
+enum CountryCode {
+  AT
+  AU
+  BE
+  BG
+  CA
+  CH
+  CY
+  CZ
+  DE
+  DK
+  EE
+  ES
+  FI
+  FR
+  GB
+  GR
+  HR
+  HU
+  IE
+  IS
+  IT
+  LI
+  LT
+  LU
+  LV
+  MT
+  NL
+  NO
+  NZ
+  PL
+  PT
+  RO
+  SE
+  SI
+  SK
+  US
+  ZZ
+}
+
 """Region to crop the image"""
 enum CropRegion {
   BOTTOM
@@ -1524,7 +1776,7 @@ enum CropRegion {
 """Currency information"""
 type Currency {
   """ISO 4217 currency code"""
-  code: String!
+  code: CurrencyCode!
 
   """Number of decimal places"""
   decimalPlaces: Float!
@@ -1535,8 +1787,179 @@ type Currency {
   """Currency symbol"""
   symbol: String!
 
-  """Symbol position relative to amount: before or after"""
-  symbolPosition: String!
+  """Symbol position relative to amount"""
+  symbolPosition: CurrencySymbolPosition!
+}
+
+"""ISO 4217 currency code"""
+enum CurrencyCode {
+  AED
+  AFN
+  ALL
+  AMD
+  ANG
+  AOA
+  ARS
+  AUD
+  AWG
+  AZN
+  BAM
+  BBD
+  BDT
+  BGN
+  BHD
+  BIF
+  BMD
+  BND
+  BOB
+  BOV
+  BRL
+  BSD
+  BTN
+  BWP
+  BYN
+  BZD
+  CAD
+  CDF
+  CHE
+  CHF
+  CHW
+  CLF
+  CLP
+  CNY
+  COP
+  COU
+  CRC
+  CUC
+  CUP
+  CVE
+  CZK
+  DJF
+  DKK
+  DOP
+  DZD
+  EGP
+  ERN
+  ETB
+  EUR
+  FJD
+  FKP
+  GBP
+  GEL
+  GHS
+  GIP
+  GMD
+  GNF
+  GTQ
+  GYD
+  HKD
+  HNL
+  HTG
+  HUF
+  IDR
+  ILS
+  INR
+  IQD
+  IRR
+  ISK
+  JMD
+  JOD
+  JPY
+  KES
+  KGS
+  KHR
+  KMF
+  KPW
+  KRW
+  KWD
+  KYD
+  KZT
+  LAK
+  LBP
+  LKR
+  LRD
+  LSL
+  LYD
+  MAD
+  MDL
+  MGA
+  MKD
+  MMK
+  MNT
+  MOP
+  MRU
+  MUR
+  MVR
+  MWK
+  MXN
+  MXV
+  MYR
+  MZN
+  NAD
+  NGN
+  NIO
+  NOK
+  NPR
+  NZD
+  OMR
+  PAB
+  PEN
+  PGK
+  PHP
+  PKR
+  PLN
+  PYG
+  QAR
+  RON
+  RSD
+  RUB
+  RWF
+  SAR
+  SBD
+  SCR
+  SDG
+  SEK
+  SGD
+  SHP
+  SLE
+  SOS
+  SRD
+  SSP
+  STN
+  SVC
+  SYP
+  SZL
+  THB
+  TJS
+  TMT
+  TND
+  TOP
+  TRY
+  TTD
+  TWD
+  TZS
+  UAH
+  UGX
+  USD
+  USN
+  UYI
+  UYU
+  UYW
+  UZS
+  VED
+  VES
+  VND
+  VUV
+  WST
+  XAF
+  XCD
+  XOF
+  XPF
+  XXX
+  YER
+  ZAR
+  ZMW
+  ZWG
 }
 
 """Currency conversion result"""
@@ -1576,10 +1999,16 @@ enum CurrencyRateSource {
   MANUAL
 }
 
+"""Whether the currency symbol renders before or after the amount."""
+enum CurrencySymbolPosition {
+  AFTER
+  BEFORE
+}
+
 """Customer - registered user"""
-type Customer {
-  """Saved addresses"""
-  addresses(first: Int = 10): [MailingAddress!]!
+type Customer implements Node {
+  """Saved addresses (Relay Connection)"""
+  addresses(after: String, before: String, first: Int, last: Int): MailingAddressConnection!
 
   """Account creation date"""
   createdAt: DateTime!
@@ -1594,10 +2023,7 @@ type Customer {
   email: String!
 
   """Email marketing consent state"""
-  emailMarketingState: String!
-
-  """Whether email is verified"""
-  emailVerified: Boolean!
+  emailMarketing: EmailMarketingState!
 
   """First name"""
   firstName: String
@@ -1605,18 +2031,24 @@ type Customer {
   """Unique identifier"""
   id: ID!
 
+  """Whether email is verified"""
+  isEmailVerified: Boolean!
+
   """Last name"""
   lastName: String
 
+  """Total orders count (UnsignedInt64 — BigInt-safe)"""
+  orderCount: UnsignedInt64!
+
   """Customer orders"""
   orders(after: String, first: Int = 10): OrderConnection!
 
-  """Total orders count"""
-  ordersCount: Int!
-
   """Phone number"""
   phone: String
 
+  """Customer tags for segmentation (e.g. vip, wholesale, b2b)"""
+  tags: [String!]!
+
   """Total amount spent"""
   totalSpent: Money!
 
@@ -1629,8 +2061,8 @@ type CustomerAccessToken {
   """Access token string"""
   accessToken: String!
 
-  """Token expiration"""
-  expiresAt: String!
+  """Token expiration (ISO 8601)"""
+  expiresAt: DateTime!
 }
 
 """Input for customer login"""
@@ -1642,60 +2074,30 @@ input CustomerAccessTokenCreateInput {
   password: String!
 }
 
-"""Result of customer login"""
-type CustomerAccessTokenCreatePayload {
-  """Access token"""
-  customerAccessToken: CustomerAccessToken
-
-  """User errors"""
-  userErrors: [UserError!]!
-}
-
-"""Result of token deletion (logout)"""
-type CustomerAccessTokenDeletePayload {
-  """Deleted access token"""
-  deletedAccessToken: String
-
-  """Deleted token ID"""
-  deletedCustomerAccessTokenId: String
-
-  """User errors"""
-  userErrors: [UserError!]!
-}
+"""
+Result of customerActivateByUrl mutation — admin-created customer sets initial password
+"""
+type CustomerActivatePayload {
+  """Activated customer"""
+  customer: Customer
 
-"""Result of token renewal"""
-type CustomerAccessTokenRenewPayload {
-  """New access token"""
+  """Auto-login access token"""
   customerAccessToken: CustomerAccessToken
 
-  """User errors"""
+  """
+  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  """
   userErrors: [UserError!]!
 }
 
 """Result of address creation"""
-type CustomerAddressCreatePayload {
+type CustomerAddAddressPayload {
   """Created address"""
   address: MailingAddress
 
-  """User errors"""
-  userErrors: [UserError!]!
-}
-
-"""Result of address deletion"""
-type CustomerAddressDeletePayload {
-  """Deleted address ID"""
-  deletedAddressId: ID
-
-  """User errors"""
-  userErrors: [UserError!]!
-}
-
-"""Result of address update"""
-type CustomerAddressUpdatePayload {
-  """Updated address"""
-  address: MailingAddress
-
-  """User errors"""
+  """
+  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  """
   userErrors: [UserError!]!
 }
 
@@ -1717,27 +2119,6 @@ input CustomerCreateInput {
   phone: String
 }
 
-"""Result of customer creation"""
-type CustomerCreatePayload {
-  """Created customer"""
-  customer: Customer
-
-  """Access token for new customer"""
-  customerAccessToken: CustomerAccessToken
-
-  """User errors"""
-  userErrors: [UserError!]!
-}
-
-"""Result of default address update"""
-type CustomerDefaultAddressUpdatePayload {
-  """Updated customer"""
-  customer: Customer
-
-  """User errors"""
-  userErrors: [UserError!]!
-}
-
 """Customer group for B2B pricing"""
 type CustomerGroup {
   """Group code"""
@@ -1759,21 +2140,108 @@ type CustomerGroup {
   taxExempt: Boolean!
 }
 
-"""Result of password recovery"""
-type CustomerRecoverPayload {
-  """User errors"""
+"""Result of customer login"""
+type CustomerLoginPayload {
+  """Access token"""
+  customerAccessToken: CustomerAccessToken
+
+  """
+  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  """
+  userErrors: [UserError!]!
+}
+
+"""Result of token deletion (logout)"""
+type CustomerLogoutPayload {
+  """Deleted access token"""
+  deletedAccessToken: String
+
+  """Deleted token ID"""
+  deletedCustomerAccessTokenId: String
+
+  """
+  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  """
+  userErrors: [UserError!]!
+}
+
+"""Result of token renewal"""
+type CustomerRefreshTokenPayload {
+  """New access token"""
+  customerAccessToken: CustomerAccessToken
+
+  """
+  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  """
+  userErrors: [UserError!]!
+}
+
+"""Result of address deletion"""
+type CustomerRemoveAddressPayload {
+  """Deleted address ID"""
+  deletedAddressId: ID
+
+  """
+  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  """
+  userErrors: [UserError!]!
+}
+
+"""Result of password recovery"""
+type CustomerRequestPasswordResetPayload {
+  """
+  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  """
+  userErrors: [UserError!]!
+}
+
+"""Result of customerResetByUrl mutation — password reset via signed URL"""
+type CustomerResetPasswordPayload {
+  """Customer with reset password"""
+  customer: Customer
+
+  """Auto-login access token"""
+  customerAccessToken: CustomerAccessToken
+
+  """
+  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  """
   userErrors: [UserError!]!
 }
 
-"""Result of password reset"""
-type CustomerResetPayload {
+"""Result of default address update"""
+type CustomerSetDefaultAddressPayload {
   """Updated customer"""
   customer: Customer
 
-  """New access token"""
+  """
+  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  """
+  userErrors: [UserError!]!
+}
+
+"""Result of customer creation"""
+type CustomerSignupPayload {
+  """Created customer"""
+  customer: Customer
+
+  """Access token for new customer"""
   customerAccessToken: CustomerAccessToken
 
-  """User errors"""
+  """
+  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  """
+  userErrors: [UserError!]!
+}
+
+"""Result of address update"""
+type CustomerUpdateAddressPayload {
+  """Updated address"""
+  address: MailingAddress
+
+  """
+  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  """
   userErrors: [UserError!]!
 }
 
@@ -1794,7 +2262,9 @@ type CustomerUpdatePayload {
   """Updated customer"""
   customer: Customer
 
-  """User errors"""
+  """
+  User errors (code is namespaced — e.g. CUSTOMER_NOT_FOUND, CUSTOMER_TOKEN_INVALID, CUSTOMER_PASSWORD_TOO_WEAK)
+  """
   userErrors: [UserError!]!
 }
 
@@ -1803,6 +2273,11 @@ A date-time string at UTC, such as 2019-12-03T09:54:33Z, compliant with the date
 """
 scalar DateTime
 
+"""
+Decimal money amount, JSON-serialized as String. Format: "{int}.{dec}" e.g. "10.50".
+"""
+scalar Decimal
+
 """Estimated delivery timeframe"""
 type DeliveryEstimate {
   """Human-readable delivery estimate"""
@@ -1847,9 +2322,6 @@ type DiscountApplication {
   """Items affected by this discount (for BXGY type)"""
   affectedItems: [DiscountAffectedItem!]
 
-  """Whether discount is applicable"""
-  applicable: Boolean!
-
   """Buy quantity for BXGY (e.g., 2 in "Buy 2 Get 1")"""
   buyQuantity: Int
 
@@ -1862,6 +2334,9 @@ type DiscountApplication {
   """Get quantity for BXGY (e.g., 1 in "Buy 2 Get 1")"""
   getQuantity: Int
 
+  """Whether discount is applicable"""
+  isApplicable: Boolean!
+
   """Discount title/description"""
   title: String
 
@@ -1882,11 +2357,11 @@ enum DiscountApplicationType {
 
 """Discount code applied to checkout"""
 type DiscountCode {
-  """Whether the code is currently applicable"""
-  applicable: Boolean!
-
   """Discount code string"""
   code: String!
+
+  """Whether the code is currently applicable"""
+  isApplicable: Boolean!
 }
 
 """Error codes for discount validation"""
@@ -1940,7 +2415,29 @@ type DiscountValidationResult {
   error: DiscountValidationError
 
   """Whether the discount code is valid"""
-  valid: Boolean!
+  isValid: Boolean!
+}
+
+"""Shop domain (host, full URL, SSL state)"""
+type Domain {
+  """Host name (e.g. "shop.example.com")"""
+  host: String!
+
+  """Whether HTTPS is enforced"""
+  isSslEnabled: Boolean!
+
+  """Full URL z protocol"""
+  url: URL!
+}
+
+"""Customer email marketing consent state (Prisma-derived)."""
+enum EmailMarketingState {
+  INVALID
+  NOT_SUBSCRIBED
+  PENDING
+  REDACTED
+  SUBSCRIBED
+  UNSUBSCRIBED
 }
 
 """Exchange rate between currencies"""
@@ -1961,6 +2458,60 @@ type ExchangeRate {
   updatedAt: DateTime!
 }
 
+"""Faceted filter for product listing"""
+type Filter {
+  """
+  Unique filter identifier (e.g., "filter.v.option.color", "filter.v.price")
+  """
+  id: ID!
+
+  """Display label (e.g., "Color", "Price", "Availability")"""
+  label: String!
+
+  """Display hint (SWATCH for COLOR, IMAGE for pattern, TEXT default)"""
+  presentation: FilterPresentation
+
+  """Filter type (LIST | PRICE_RANGE | BOOLEAN)"""
+  type: FilterType!
+
+  """Available values for this filter, with product counts"""
+  values: [FilterValue!]!
+}
+
+"""Filter presentation hint"""
+enum FilterPresentation {
+  IMAGE
+  SWATCH
+  TEXT
+}
+
+"""Type of filter"""
+enum FilterType {
+  BOOLEAN
+  LIST
+  PRICE_RANGE
+}
+
+"""Filter value with product count"""
+type FilterValue {
+  """Number of products matching this value in current result set"""
+  count: Int!
+
+  """Unique identifier within filter"""
+  id: ID!
+
+  """
+  Pre-built ProductFilter input — paste verbatim into `filters` arg to refetch with this value applied. Example: `{"variantOption":{"name":"Color","value":"Red"}}`
+  """
+  input: JSON!
+
+  """Display label (e.g., "Red", "Extra Large", "$50 - $200")"""
+  label: String!
+
+  """DoSwiftly: visual swatch (color hex or pattern image)"""
+  swatch: AttributeSwatch
+}
+
 """Free shipping progress indicator"""
 type FreeShippingProgress {
   """Current cart subtotal"""
@@ -1993,8 +2544,8 @@ type GenerateReferralCodePayload {
   """Whether generation was successful"""
   success: Boolean!
 
-  """Error messages if any"""
-  userErrors: [String!]!
+  """Typed user errors"""
+  userErrors: [UserError!]!
 }
 
 """Geographic coordinates (latitude/longitude)"""
@@ -2023,10 +2574,9 @@ type GiftCard {
   """Initial gift card amount"""
   initialAmount: Money!
 
-  """Last 4 characters of code"""
-  lastCharacters: String!
-
-  """Gift card code (masked for security)"""
+  """
+  Gift card code (masked for security; client may slice last 4 chars for display)
+  """
   maskedCode: String!
 
   """Personal message"""
@@ -2037,9 +2587,6 @@ type GiftCard {
 
   """Gift card status"""
   status: GiftCardStatus!
-
-  """Transaction history"""
-  transactions: [GiftCardTransaction!]!
 }
 
 """Gift card validation error"""
@@ -2062,15 +2609,6 @@ enum GiftCardErrorCode {
   NOT_FOUND
 }
 
-"""Result of gift card lookup"""
-type GiftCardPayload {
-  """Gift card if found"""
-  giftCard: GiftCard
-
-  """User errors"""
-  userErrors: [UserError!]!
-}
-
 """Gift card status"""
 enum GiftCardStatus {
   ACTIVE
@@ -2079,27 +2617,6 @@ enum GiftCardStatus {
   USED
 }
 
-"""Gift card transaction record"""
-type GiftCardTransaction {
-  """Transaction amount"""
-  amount: Money!
-
-  """Balance after transaction"""
-  balanceAfter: Money!
-
-  """Transaction timestamp"""
-  createdAt: DateTime!
-
-  """Transaction ID"""
-  id: ID!
-
-  """Order ID if related to order"""
-  orderId: ID
-
-  """Transaction type"""
-  type: String!
-}
-
 """Result of gift card validation"""
 type GiftCardValidatePayload {
   """User errors"""
@@ -2121,7 +2638,7 @@ type GiftCardValidation {
   giftCard: GiftCard
 
   """Whether the gift card is valid for use"""
-  valid: Boolean!
+  isValid: Boolean!
 }
 
 """Image with URL and metadata"""
@@ -2147,6 +2664,21 @@ type Image {
   width: Int
 }
 
+"""Paginated list of images (Relay Connection)"""
+type ImageConnection {
+  """Image edges with cursors"""
+  edges: [ImageEdge!]!
+
+  """Image nodes (shortcut for edges.map(e => e.node))"""
+  nodes: [Image!]!
+
+  """Pagination info"""
+  pageInfo: PageInfo!
+
+  """Total count of images"""
+  totalCount: Int!
+}
+
 """Image content type for output format"""
 enum ImageContentType {
   AVIF
@@ -2155,7 +2687,16 @@ enum ImageContentType {
   WEBP
 }
 
-"""Image transform options (Shopify-compatible)"""
+"""Edge in an Image connection"""
+type ImageEdge {
+  """Cursor for pagination"""
+  cursor: String!
+
+  """Image node"""
+  node: Image!
+}
+
+"""Image transform options"""
 input ImageTransformInput {
   """Crop region"""
   crop: CropRegion
@@ -2173,6 +2714,11 @@ input ImageTransformInput {
   scale: Int
 }
 
+"""
+Opaque JSON payload — shape documented per field. Klient parsuje strukturę sam.
+"""
+scalar JSON
+
 """Language configuration"""
 type Language {
   """Language code (ISO 639-1)"""
@@ -2194,6 +2740,31 @@ type Language {
   nativeName: String!
 }
 
+"""ISO 639-1 language code"""
+enum LanguageCode {
+  CS
+  DA
+  DE
+  EN
+  ES
+  FI
+  FR
+  HR
+  HU
+  IT
+  LT
+  LV
+  NL
+  NO
+  PL
+  PT
+  RO
+  SK
+  SL
+  SV
+  UK
+}
+
 """Text direction for the language"""
 enum LanguageDirection {
   LTR
@@ -2204,6 +2775,9 @@ enum LanguageDirection {
 Summary of a ProductVariant linked to an AttributeOption (Faza 1.5 configurator).
 """
 type LinkedVariantSummary {
+  """Available stock (stock − active reservations, zawsze ≥ 0)."""
+  availableStock: Int!
+
   """Variant ID (w tenant DB)."""
   id: ID!
 
@@ -2213,9 +2787,6 @@ type LinkedVariantSummary {
   """Parent product ID."""
   productId: ID!
 
-  """Dostępna ilość (stock − active reservations, zawsze ≥ 0)."""
-  quantityAvailable: Int!
-
   """SKU jeśli zdefiniowany."""
   sku: String
 
@@ -2228,13 +2799,28 @@ type LinkedVariantSummary {
 
 """Locale to currency mapping entry"""
 type LocaleCurrencyMapping {
-  """Currency code (e.g., "PLN", "USD")"""
-  currency: String!
+  """Currency code (ISO 4217)"""
+  currency: CurrencyCode!
 
   """Browser locale (e.g., "pl-PL", "en-US")"""
   locale: String!
 }
 
+"""Localization context dla storefronta"""
+type Localization {
+  """Wszystkie wsparte kraje (z aktywnych shipping zones)"""
+  availableCountries: [Country!]!
+
+  """Wszystkie wsparte języki sklepu"""
+  availableLanguages: [Language!]!
+
+  """Aktualny kraj klienta (z `@inContext` lub geo-detection)"""
+  country: Country!
+
+  """Aktualny język klienta (z `Accept-Language` lub `@inContext`)"""
+  language: Language!
+}
+
 """Inventory location (warehouse, store, pickup point)"""
 type Location {
   """Physical address and coordinates"""
@@ -2251,12 +2837,12 @@ type Location {
   """Location display name"""
   name: String!
 
-  """Whether this location supports BOPIS pickup"""
-  pickupEnabled: Boolean!
-
   """Optional merchant pickup instructions (e.g., "Show ID at counter")"""
   pickupInstructions: String
 
+  """Whether this location supports BOPIS pickup"""
+  supportsPickup: Boolean!
+
   """
   IANA timezone identifier (e.g., "Europe/Warsaw"). Falls back to shop timezone if null.
   """
@@ -2266,14 +2852,8 @@ type Location {
   type: LocationType!
 }
 
-"""Physical address of a location (Shopify LocationAddress parity)"""
+"""Physical address of a location"""
 type LocationAddress {
-  """Street address line 1"""
-  address1: String
-
-  """Street address line 2 (apartment, suite)"""
-  address2: String
-
   """City"""
   city: String
 
@@ -2295,14 +2875,20 @@ type LocationAddress {
   """Phone number"""
   phone: String
 
+  """Postal / ZIP code"""
+  postalCode: String
+
   """State / province name"""
-  province: String
+  state: String
 
   """State / province code (e.g., CA, MZ)"""
-  provinceCode: String
+  stateCode: String
 
-  """Postal / ZIP code"""
-  zip: String
+  """First line of street address"""
+  streetLine1: String
+
+  """Second line of street address (apartment, suite)"""
+  streetLine2: String
 }
 
 """Paginated location connection"""
@@ -2337,7 +2923,7 @@ enum LocationType {
 """Available point earning action"""
 type LoyaltyAction {
   """Whether action is enabled"""
-  enabled: Boolean!
+  isEnabled: Boolean!
 
   """Points awarded for this action (if fixed)"""
   points: Int
@@ -2355,13 +2941,13 @@ type LoyaltyMember {
   customerId: ID!
 
   """Enrollment date"""
-  enrolledAt: String!
+  enrolledAt: DateTime!
 
   """Member ID"""
   id: ID!
 
   """Last activity date"""
-  lastActivityAt: String
+  lastActivityAt: DateTime
 
   """Points summary"""
   points: LoyaltyPointsSummary!
@@ -2399,8 +2985,8 @@ type LoyaltyPointsSummary {
   """Points expiring soon (next 30 days)"""
   expiringPoints: Int
 
-  """Next expiry date"""
-  nextExpiryDate: String
+  """Next expiry date (ISO 8601)"""
+  nextExpiryDate: DateTime
 
   """Points pending (from incomplete orders)"""
   pendingPoints: Int!
@@ -2414,9 +3000,6 @@ type LoyaltyPointsSummary {
 
 """Redeemable loyalty reward"""
 type LoyaltyReward {
-  """Whether reward is available"""
-  available: Boolean!
-
   """Description"""
   description: String
 
@@ -2432,14 +3015,17 @@ type LoyaltyReward {
   """Reward image"""
   image: Image
 
+  """Whether reward is available"""
+  isAvailable: Boolean!
+
   """Reward name"""
   name: String!
 
   """Points required to redeem"""
   pointsCost: Int!
 
-  """Remaining redemptions (null = unlimited)"""
-  remainingRedemptions: Int
+  """Redemptions remaining (null = unlimited)"""
+  redemptionsRemaining: Int
 
   """URL-friendly slug"""
   slug: String!
@@ -2457,7 +3043,7 @@ type LoyaltySettings {
   availableActions: [LoyaltyAction!]!
 
   """Whether loyalty program is enabled"""
-  enabled: Boolean!
+  isEnabled: Boolean!
 
   """Months until points expire (null = no expiry)"""
   pointsExpiryMonths: Int
@@ -2517,13 +3103,13 @@ type LoyaltyTransaction {
   balanceAfter: Int!
 
   """Transaction date"""
-  createdAt: String!
+  createdAt: DateTime!
 
   """Description"""
   description: String
 
   """Expiry date for earned points"""
-  expiresAt: String
+  expiresAt: DateTime
 
   """Transaction ID"""
   id: ID!
@@ -2574,13 +3160,7 @@ enum LoyaltyTransactionType {
 }
 
 """Customer mailing address"""
-type MailingAddress {
-  """First line of address"""
-  address1: String
-
-  """Second line of address"""
-  address2: String
-
+type MailingAddress implements Node {
   """City"""
   city: String
 
@@ -2590,50 +3170,87 @@ type MailingAddress {
   """Country"""
   country: String
 
-  """Country code (ISO)"""
-  countryCode: String
+  """ISO 3166-1 alpha-2 country code"""
+  countryCode: CountryCode
 
   """First name"""
   firstName: String
 
+  """
+  Country-aware ordered address lines. Format zależy od country: PL = [name, streetLine1, "postalCode city"]; US = [name, streetLine1, "city, state postalCode"]; default = [name, streetLine1, streetLine2, city, postalCode, country]. Use bezpośrednio jako lines w UI bez ręcznego konstruowania.
+  """
+  formatted: [String!]!
+
+  """
+  Single-line area summary, e.g. "Warszawa, MZ, Poland"
+  """
+  formattedArea: String
+
   """Unique identifier"""
   id: ID!
 
-  """Whether this is default address"""
+  """Whether this is default address (DoSwiftly extension)"""
   isDefault: Boolean!
 
   """Last name"""
   lastName: String
 
+  """Computed full name (firstName + " " + lastName)"""
+  name: String
+
   """Phone number"""
   phone: String
 
-  """Province/State"""
-  province: String
+  """Postal / ZIP code"""
+  postalCode: String
+
+  """State / province"""
+  state: String
+
+  """State / province code (ISO 3166-2 subdivision)"""
+  stateCode: String
 
-  """Province code"""
-  provinceCode: String
+  """First line of street address"""
+  streetLine1: String
 
-  """ZIP/Postal code"""
-  zip: String
+  """Second line of street address"""
+  streetLine2: String
 }
 
-"""Input for mailing address"""
-input MailingAddressInput {
-  """First line of address"""
-  address1: String
+"""Paginated mailing addresses (Relay Connection)"""
+type MailingAddressConnection {
+  """Address edges with cursors"""
+  edges: [MailingAddressEdge!]!
+
+  """Address nodes (shortcut for edges.map(e => e.node))"""
+  nodes: [MailingAddress!]!
+
+  """Pagination info"""
+  pageInfo: PageInfo!
 
-  """Second line of address"""
-  address2: String
+  """Total count of addresses"""
+  totalCount: Int!
+}
+
+"""Edge in a MailingAddress connection"""
+type MailingAddressEdge {
+  """Cursor for pagination"""
+  cursor: String!
+
+  """MailingAddress node"""
+  node: MailingAddress!
+}
 
+"""Input for mailing address"""
+input MailingAddressInput {
   """City"""
   city: String
 
   """Company"""
   company: String
 
-  """Country code (ISO)"""
-  country: String
+  """ISO 3166-1 alpha-2 country code"""
+  country: CountryCode
 
   """First name"""
   firstName: String
@@ -2644,11 +3261,17 @@ input MailingAddressInput {
   """Phone"""
   phone: String
 
-  """Province/State"""
-  province: String
+  """Postal / ZIP code"""
+  postalCode: String
+
+  """State / province"""
+  state: String
+
+  """First line of street address"""
+  streetLine1: String
 
-  """ZIP/Postal code"""
-  zip: String
+  """Second line of street address"""
+  streetLine2: String
 }
 
 """Navigation menu"""
@@ -2662,9 +3285,6 @@ type Menu {
   """Top-level menu items"""
   items: [MenuItem!]!
 
-  """Total count of items across all levels"""
-  itemsCount: Int!
-
   """Menu title"""
   title: String!
 }
@@ -2680,7 +3300,9 @@ type MenuItem {
   """Child menu items (max 3 levels)"""
   items: [MenuItem!]!
 
-  """Linked resource object (lazy, via DataLoader)"""
+  """
+  Linked resource object resolved server-side via DataLoader (batched per resource type — no N+1). Null when type is HTTP/FRONTPAGE/SEARCH/CATALOG/BLOG, or when resourceId points to a deleted resource.
+  """
   resource: MenuItemResource
 
   """Linked resource ID"""
@@ -2692,8 +3314,10 @@ type MenuItem {
   """Link type"""
   type: MenuItemType!
 
-  """Resolved URL (always computed server-side)"""
-  url: String
+  """
+  Resolved URL path computed server-side (e.g., /categories/funko, /products/toy-1, /pages/about, /collections/sale). Static types resolve to /, /search, /products, /blog. HTTP type returns the manually stored URL. Null only when type is a resource link (CATEGORY/COLLECTION/PAGE/PRODUCT) and the resource was deleted.
+  """
+  url: URL
 }
 
 union MenuItemResource = Category | Collection | Product | ShopPage
@@ -2714,142 +3338,191 @@ enum MenuItemType {
 """Monetary value with currency"""
 type Money {
   """Decimal money amount"""
-  amount: String!
+  amount: Decimal!
 
-  """Currency code (ISO 4217)"""
-  currencyCode: String!
+  """ISO 4217 currency code"""
+  currencyCode: CurrencyCode!
 }
 
 type Mutation {
-  """Update cart attributes"""
-  cartAttributesUpdate(attributes: [CartAttributeInput!]!, cartId: ID!): CartAttributesUpdatePayload!
+  """Add lines to cart"""
+  cartAddLines(id: ID!, lines: [CartLineInput!]!): CartAddLinesPayload!
 
-  """Update buyer identity"""
-  cartBuyerIdentityUpdate(buyerIdentity: CartBuyerIdentityInput!, cartId: ID!): CartBuyerIdentityUpdatePayload!
+  """Apply discount codes"""
+  cartApplyDiscountCodes(discountCodes: [String!]!, id: ID!): CartApplyDiscountCodesPayload!
 
   """Create new cart"""
   cartCreate(input: CartCreateInput): CartCreatePayload!
 
-  """Update discount codes"""
-  cartDiscountCodesUpdate(cartId: ID!, discountCodes: [String!]!): CartDiscountCodesUpdatePayload!
+  """Remove lines from cart"""
+  cartRemoveLines(id: ID!, lineIds: [ID!]!): CartRemoveLinesPayload!
 
-  """Add lines to cart"""
-  cartLinesAdd(cartId: ID!, lines: [CartLineInput!]!): CartLinesAddPayload!
+  """Update cart attributes"""
+  cartUpdateAttributes(attributes: [CartAttributeInput!]!, id: ID!): CartUpdateAttributesPayload!
 
-  """Remove lines from cart"""
-  cartLinesRemove(cartId: ID!, lineIds: [ID!]!): CartLinesRemovePayload!
+  """Update buyer identity"""
+  cartUpdateBuyerIdentity(buyerIdentity: CartBuyerIdentityInput!, id: ID!): CartUpdateBuyerIdentityPayload!
 
   """Update cart lines"""
-  cartLinesUpdate(cartId: ID!, lines: [CartLineUpdateInput!]!): CartLinesUpdatePayload!
+  cartUpdateLines(id: ID!, lines: [CartLineUpdateInput!]!): CartUpdateLinesPayload!
 
   """Update cart note"""
-  cartNoteUpdate(cartId: ID!, note: String!): CartNoteUpdatePayload!
+  cartUpdateNote(id: ID!, note: String!): CartUpdateNotePayload!
 
-  """Update checkout billing address"""
-  checkoutBillingAddressUpdate(billingAddress: CheckoutAddressInput!, checkoutId: ID!): CheckoutBillingAddressUpdatePayload!
+  """Apply discount code to checkout"""
+  checkoutApplyDiscountCode(discountCode: String!, id: ID!): CheckoutApplyDiscountCodePayload!
+
+  """Apply gift card to checkout"""
+  checkoutApplyGiftCard(giftCardCode: String!, id: ID!): CheckoutApplyGiftCardPayload!
 
   """Complete checkout and create order"""
-  checkoutComplete(checkoutId: ID!, input: CheckoutCompleteInput): CheckoutCompletePayload!
+  checkoutComplete(id: ID!, input: CheckoutCompleteInput): CheckoutCompletePayload!
 
   """Create new checkout"""
   checkoutCreate(input: CheckoutCreateInput!): CheckoutCreatePayload!
 
-  """Apply discount code to checkout"""
-  checkoutDiscountCodeApply(checkoutId: ID!, discountCode: String!): CheckoutDiscountCodeApplyPayload!
-
   """Remove discount code from checkout"""
-  checkoutDiscountCodeRemove(checkoutId: ID!, discountCode: String!): CheckoutDiscountCodeRemovePayload!
+  checkoutRemoveDiscountCode(discountCode: String!, id: ID!): CheckoutRemoveDiscountCodePayload!
 
-  """Validate discount code without applying"""
-  checkoutDiscountCodeValidate(checkoutId: ID!, discountCode: String!): CheckoutDiscountCodeValidatePayload!
+  """Remove gift card from checkout"""
+  checkoutRemoveGiftCard(giftCardCode: String!, id: ID!): CheckoutRemoveGiftCardPayload!
 
-  """Update checkout email"""
-  checkoutEmailUpdate(checkoutId: ID!, email: String!): CheckoutEmailUpdatePayload!
+  """Select payment method for checkout"""
+  checkoutSelectPaymentMethod(id: ID!, paymentMethodId: ID!): CheckoutSelectPaymentMethodPayload!
 
-  """Apply gift card to checkout"""
-  checkoutGiftCardApply(checkoutId: ID!, giftCardCode: String!): CheckoutGiftCardApplyPayload!
+  """Select shipping rate for checkout"""
+  checkoutSelectShippingRate(
+    id: ID!
 
-  """Update gift card recipient info for a line item"""
-  checkoutGiftCardRecipientUpdate(input: CheckoutGiftCardRecipientInput!): CheckoutGiftCardRecipientUpdatePayload!
+    """Shipping rate handle/id from checkout.availableShippingRates"""
+    rateId: String!
+  ): CheckoutSelectShippingRatePayload!
 
-  """Remove gift card from checkout"""
-  checkoutGiftCardRemove(checkoutId: ID!, giftCardCode: String!): CheckoutGiftCardRemovePayload!
+  """Update checkout billing address"""
+  checkoutUpdateBillingAddress(billingAddress: CheckoutAddressInput!, id: ID!): CheckoutUpdateBillingAddressPayload!
+
+  """Update checkout email"""
+  checkoutUpdateEmail(email: String!, id: ID!): CheckoutUpdateEmailPayload!
 
-  """Update checkout payment method"""
-  checkoutPaymentMethodUpdate(checkoutId: ID!, paymentMethodId: ID!): CheckoutPaymentMethodUpdatePayload!
+  """Update gift card recipient info for a line item"""
+  checkoutUpdateGiftCardRecipient(input: CheckoutGiftCardRecipientInput!): CheckoutUpdateGiftCardRecipientPayload!
 
   """Update checkout shipping address"""
-  checkoutShippingAddressUpdate(checkoutId: ID!, shippingAddress: CheckoutAddressInput!): CheckoutShippingAddressUpdatePayload!
+  checkoutUpdateShippingAddress(id: ID!, shippingAddress: CheckoutAddressInput!): CheckoutUpdateShippingAddressPayload!
+
+  """Validate discount code without applying"""
+  checkoutValidateDiscountCode(discountCode: String!, id: ID!): CheckoutValidateDiscountCodePayload!
+
+  """
+  Activate customer account using raw activation token (admin-created flow)
+  """
+  customerActivate(
+    password: String!
 
-  """Update checkout shipping method"""
-  checkoutShippingLineUpdate(checkoutId: ID!, shippingRateHandle: String!): CheckoutShippingLineUpdatePayload!
+    """Raw activation token from the activation email"""
+    token: String!
+  ): CustomerActivatePayload!
+
+  """Add customer address"""
+  customerAddAddress(address: MailingAddressInput!): CustomerAddAddressPayload!
 
   """Login customer"""
-  customerAccessTokenCreate(input: CustomerAccessTokenCreateInput!): CustomerAccessTokenCreatePayload!
+  customerLogin(input: CustomerAccessTokenCreateInput!): CustomerLoginPayload!
 
-  """Logout customer"""
-  customerAccessTokenDelete(customerAccessToken: String!): CustomerAccessTokenDeletePayload!
+  """Logout customer (clears auth cookie)"""
+  customerLogout: CustomerLogoutPayload!
 
   """Refresh access token"""
-  customerAccessTokenRenew(customerAccessToken: String!): CustomerAccessTokenRenewPayload!
+  customerRefreshToken: CustomerRefreshTokenPayload!
 
-  """Create customer address"""
-  customerAddressCreate(address: MailingAddressInput!, customerAccessToken: String!): CustomerAddressCreatePayload!
+  """Remove customer address"""
+  customerRemoveAddress(id: ID!): CustomerRemoveAddressPayload!
 
-  """Delete customer address"""
-  customerAddressDelete(customerAccessToken: String!, id: ID!): CustomerAddressDeletePayload!
+  """Request password reset email"""
+  customerRequestPasswordReset(email: String!): CustomerRequestPasswordResetPayload!
 
-  """Update customer address"""
-  customerAddressUpdate(address: MailingAddressInput!, customerAccessToken: String!, id: ID!): CustomerAddressUpdatePayload!
+  """Reset customer password via signed URL from email"""
+  customerResetPassword(
+    newPassword: String!
 
-  """Register new customer"""
-  customerCreate(input: CustomerCreateInput!): CustomerCreatePayload!
+    """Raw password-reset token from the password-reset email"""
+    token: String!
+  ): CustomerResetPasswordPayload!
 
   """Set default address"""
-  customerDefaultAddressUpdate(addressId: ID!, customerAccessToken: String!): CustomerDefaultAddressUpdatePayload!
-
-  """Send password reset email"""
-  customerRecover(email: String!): CustomerRecoverPayload!
+  customerSetDefaultAddress(addressId: ID!): CustomerSetDefaultAddressPayload!
 
-  """Reset password"""
-  customerReset(id: ID!, input: String!, password: String!): CustomerResetPayload!
+  """Register new customer"""
+  customerSignup(input: CustomerCreateInput!): CustomerSignupPayload!
 
   """Update customer profile"""
-  customerUpdate(customer: CustomerUpdateInput!, customerAccessToken: String!): CustomerUpdatePayload!
+  customerUpdate(customer: CustomerUpdateInput!): CustomerUpdatePayload!
+
+  """Update customer address"""
+  customerUpdateAddress(address: MailingAddressInput!, id: ID!): CustomerUpdateAddressPayload!
 
   """Generate or retrieve referral code"""
-  generateReferralCode: GenerateReferralCodePayload!
+  loyaltyGenerateReferralCode: GenerateReferralCodePayload!
 
   """Redeem a loyalty reward"""
-  redeemLoyaltyReward(input: RedeemRewardInput!): RedeemRewardPayload!
+  loyaltyRedeemReward(input: RedeemRewardInput!): RedeemRewardPayload!
 
   """Cancel a return request"""
-  returnCancel(customerAccessToken: String!, id: ID!): ReturnCancelPayload!
+  returnCancel(id: ID!): ReturnCancelPayload!
 
   """Create a return request"""
-  returnCreate(customerAccessToken: String!, input: ReturnCreateInput!): ReturnCreatePayload!
+  returnCreate(input: ReturnCreateInput!): ReturnCreatePayload!
 
   """Create a product review"""
   reviewCreate(input: ReviewCreateInput!): ReviewPayload!
 
-  """Vote on review helpfulness"""
-  reviewVote(isHelpful: Boolean!, reviewId: ID!): ReviewPayload!
+  """
+  Mark review as not helpful (downvote). Replaces any prior vote by same customer.
+  """
+  reviewDownvote(reviewId: ID!): ReviewPayload!
+
+  """
+  Mark review as helpful (upvote). Replaces any prior vote by same customer.
+  """
+  reviewUpvote(reviewId: ID!): ReviewPayload!
 
   """Add item to wishlist"""
-  wishlistAddItem(input: WishlistItemInput!, wishlistId: ID!): WishlistPayload!
+  wishlistAddItem(id: ID!, input: WishlistItemInput!): WishlistPayload!
 
   """Create a new wishlist"""
   wishlistCreate(input: WishlistCreateInput!): WishlistPayload!
 
   """Delete a wishlist"""
-  wishlistDelete(wishlistId: ID!): WishlistPayload!
+  wishlistDelete(id: ID!): WishlistPayload!
 
   """Remove item from wishlist"""
-  wishlistRemoveItem(itemId: ID!, wishlistId: ID!): WishlistPayload!
+  wishlistRemoveItem(id: ID!, itemId: ID!): WishlistPayload!
+}
+
+"""GraphQL Node interface — universal ID-based lookup"""
+interface Node {
+  """Globally-unique identifier"""
+  id: ID!
+}
+
+"""
+Type discriminator dla node()/nodes() queries (UUID nie zawiera type prefix)
+"""
+enum NodeType {
+  ARTICLE
+  CART
+  CATEGORY
+  COLLECTION
+  CUSTOMER
+  MAILING_ADDRESS
+  ORDER
+  PAGE
+  PRODUCT
+  PRODUCT_VARIANT
 }
 
 """Customer order summary"""
-type Order {
+type Order implements Node {
   """When order was cancelled"""
   cancelledAt: DateTime
 
@@ -2859,9 +3532,6 @@ type Order {
   """When order expired"""
   expiredAt: DateTime
 
-  """Financial status"""
-  financialStatus: OrderFinancialStatus!
-
   """Fulfillment status"""
   fulfillmentStatus: OrderFulfillmentStatus!
 
@@ -2869,13 +3539,16 @@ type Order {
   id: ID!
 
   """Line items count"""
-  lineItemsCount: Int!
+  itemCount: Int!
 
   """Order number (human-readable)"""
   orderNumber: String!
 
-  """Order date"""
-  processedAt: String!
+  """Payment status"""
+  paymentStatus: OrderPaymentStatus!
+
+  """Order date (ISO 8601)"""
+  processedAt: DateTime!
 
   """Order shipments"""
   shipments: [Shipment!]!
@@ -2886,17 +3559,8 @@ type Order {
   """Order lifecycle status"""
   status: StorefrontOrderStatus!
 
-  """Order subtotal"""
-  subtotalPrice: Money!
-
-  """Order total"""
-  totalPrice: Money!
-
-  """Total shipping"""
-  totalShipping: Money
-
-  """Total tax"""
-  totalTax: Money
+  """Cost totals breakdown (subtotal/total/totalTax/totalShipping)"""
+  totals: OrderTotals!
 }
 
 """Paginated order connection"""
@@ -2920,8 +3584,20 @@ type OrderEdge {
   node: Order!
 }
 
-"""Financial status of an order"""
-enum OrderFinancialStatus {
+"""Fulfillment status of an order"""
+enum OrderFulfillmentStatus {
+  DELIVERED
+  FULFILLED
+  IN_TRANSIT
+  LOST
+  PARTIALLY_FULFILLED
+  PARTIALLY_RETURNED
+  RETURNED
+  UNFULFILLED
+}
+
+"""Payment status of an order"""
+enum OrderPaymentStatus {
   AUTHORIZED
   CHARGEBACK
   FAILED
@@ -2935,16 +3611,19 @@ enum OrderFinancialStatus {
   VOIDED
 }
 
-"""Fulfillment status of an order"""
-enum OrderFulfillmentStatus {
-  DELIVERED
-  FULFILLED
-  IN_TRANSIT
-  LOST
-  PARTIALLY_FULFILLED
-  PARTIALLY_RETURNED
-  RETURNED
-  UNFULFILLED
+"""Order cost totals breakdown"""
+type OrderTotals {
+  """Order subtotal (before tax and shipping)"""
+  subtotal: Money!
+
+  """Order total (after tax and shipping)"""
+  total: Money!
+
+  """Total shipping cost"""
+  totalShipping: Money
+
+  """Total tax amount"""
+  totalTax: Money
 }
 
 """Package dimensions for rate calculation"""
@@ -3026,6 +3705,23 @@ enum PaymentMethodType {
   PAYPAL
 }
 
+"""Shop payment configuration (currency, country, providers)"""
+type PaymentSettings {
+  """Country code sklepu — driver dostępności metod płatności"""
+  countryCode: CountryCode!
+
+  """Primary currency użyty do procesowania płatności"""
+  currencyCode: CurrencyCode!
+
+  """Waluty displayable on storefront (Money.currencyCode allowlist)"""
+  enabledPresentmentCurrencies: [CurrencyCode!]!
+
+  """
+  Kody aktywnych payment providerów dla tego sklepu (z IntegrationProvider table, type=PAYMENT). Np. ["payu", "cash_on_delivery"]. Storefront-dev używa do warunkowania UI checkout.
+  """
+  paymentProviders: [String!]!
+}
+
 """Points estimate for an order"""
 type PointsEstimate {
   """Base points to earn"""
@@ -3041,6 +3737,15 @@ type PointsEstimate {
   totalPoints: Int!
 }
 
+"""Predictive search result for typeahead UI"""
+type PredictiveSearchResult {
+  """Top matching products (FTS-ranked)"""
+  products: [Product!]!
+
+  """Top product title suggestions with highlighted query matches"""
+  queries: [SearchQuerySuggestion!]!
+}
+
 """Price with full conversion transparency"""
 type PriceMoney {
   """Price amount in display currency"""
@@ -3077,6 +3782,15 @@ type PriceRange {
   min: Money!
 }
 
+"""Price range filter (major units)"""
+input PriceRangeFilter {
+  """Maximum price (major units)"""
+  max: Float
+
+  """Minimum price (major units, e.g. 50.0 PLN)"""
+  min: Float
+}
+
 """Quantity-based pricing tier"""
 type PricingTier {
   """Discount percentage from retail"""
@@ -3093,8 +3807,8 @@ type PricingTier {
 }
 
 """Product - main catalog item"""
-type Product {
-  """Assigned AttributeSet ID (Hybrid Magento — shared template fields)"""
+type Product implements Node {
+  """Assigned AttributeSet ID (shared template fields)"""
   attributeSetId: ID
 
   """
@@ -3102,17 +3816,21 @@ type Product {
   """
   attributes(filter: ProductAttributeFilterInput): [ProductAttributeDefinition!]!
 
-  """Whether product is available for sale (any variant in stock)"""
-  availableForSale: Boolean!
-
   """Average rating (1-5)"""
   averageRating: Float
 
-  """Whether storefront checkout collects recipient data for this product"""
-  collectRecipientInfo: Boolean!
+  """
+  Product category (free-text classification, e.g. "Footwear", "Electronics")
+  """
+  category: String
+
+  """
+  Compare-at price range (Money pair). Null gdy żaden variant nie ma compareAtPrice.
+  """
+  compareAtPriceRange: ProductPriceRange
 
-  """Compare-at price range in customer preferred currency (auto-converted)"""
-  compareAtPriceRange: ConvertedPriceRange
+  """Opt-in: compare-at price range with conversion transparency."""
+  compareAtPriceRangeWithConversion: ConvertedPriceRange
 
   """Creation timestamp"""
   createdAt: DateTime!
@@ -3132,49 +3850,51 @@ type Product {
   """Unique identifier"""
   id: ID!
 
-  """All product images"""
-  images(first: Float = 10): [Image!]!
+  """Product images (Relay Connection)"""
+  images(after: String, before: String, first: Float, last: Float): ImageConnection!
+
+  """Whether product is available for sale (any variant in stock)"""
+  isAvailable: Boolean!
+
+  """
+  Whether the storefront should offer a direct purchase path (Add to cart / Buy now). Mirrors `visibility === PUBLIC`. BUNDLE_ONLY ("Komponent") products resolve to false — the PDP renders a Komponent banner explaining access is only via configurator.
+  """
+  isPurchasable: Boolean!
 
   """
   Per-product option definitions (Color, Size, …) with their available values. Use these to build a variant picker without aggregating `selectedOptions` manually.
   """
   options: [ProductOption!]!
 
-  """Original compare-at price range in shop base currency"""
-  originalCompareAtPriceRange: ProductPriceRange
-
-  """Original price range in shop base currency"""
-  originalPriceRange: ProductPriceRange
-
-  """Price range in customer preferred currency (auto-converted)"""
-  priceRange: ConvertedPriceRange!
-
-  """Product type/category (free text)"""
-  productType: String
+  """Price range (Money pair). Default field — industry-standard schema."""
+  priceRange: ProductPriceRange!
 
   """
-  Whether the storefront should offer a direct purchase path (Add to cart / Buy now). Mirrors `visibility === PUBLIC`. BUNDLE_ONLY ("Komponent") products resolve to false — the PDP renders a Komponent banner explaining access is only via configurator.
+  Opt-in: price range with full conversion transparency (exchangeRate, baseCurrency, isConverted). Use dla currency-converter UI gdy customer ma preferred currency inną niż shop base.
   """
-  purchasable: Boolean!
+  priceRangeWithConversion: ConvertedPriceRange
 
   """Similar products recommendations"""
   recommendations(first: Int = 4): ProductRecommendations
 
+  """Whether storefront checkout requires recipient data for this product"""
+  requiresRecipientInfo: Boolean!
+
   """Number of reviews"""
   reviewCount: Int
 
   """SEO metadata"""
   seo: SEO
 
+  """Total stock across all variants"""
+  stockTotal: Int
+
   """Product tags"""
   tags: [String!]!
 
   """Product title"""
   title: String!
 
-  """Total inventory across all variants"""
-  totalInventory: Int
-
   """
   Product type enum (PHYSICAL, DIGITAL, SERVICE, SUBSCRIPTION, GIFT_CARD)
   """
@@ -3183,8 +3903,8 @@ type Product {
   """Last update timestamp"""
   updatedAt: DateTime!
 
-  """Product variants"""
-  variants(first: Float = 100): [ProductVariant!]!
+  """Product variants (Relay Connection)"""
+  variants(after: String, before: String, first: Float, last: Float): ProductVariantConnection!
 
   """Vendor/brand name"""
   vendor: String
@@ -3196,7 +3916,7 @@ type Product {
 """Product attribute definition (configurator)"""
 type ProductAttributeDefinition {
   """Billing mode — BUNDLED | SEPARATE_LINE; null = informational only"""
-  billingMode: String
+  billingMode: AttributeBillingMode
 
   """Customer-facing description"""
   description: String
@@ -3205,7 +3925,7 @@ type ProductAttributeDefinition {
   displayOrder: Int!
 
   """Filling mode — MERCHANT | CUSTOMER | BOTH"""
-  fillingMode: String!
+  fillingMode: AttributeFillingMode!
 
   """Definition ID"""
   id: ID!
@@ -3248,7 +3968,7 @@ input ProductAttributeFilterInput {
   """
   Filter by filling mode — MERCHANT | CUSTOMER | BOTH (configurator UI uses CUSTOMER + BOTH)
   """
-  fillingMode: String
+  fillingMode: AttributeFillingMode
 }
 
 """Selectable option of a product attribute (configurator)"""
@@ -3284,7 +4004,7 @@ type ProductAttributeOption {
   surchargeAmount: Int
 
   """Surcharge type — FIXED | PERCENT (Faza 2)"""
-  surchargeType: String
+  surchargeType: AttributeOptionSurchargeType
 
   """Internal value (slug-style)"""
   value: String!
@@ -3292,9 +4012,17 @@ type ProductAttributeOption {
 
 """Paginated product list"""
 type ProductConnection {
-  """Product edges"""
+  """Product edges with cursors"""
   edges: [ProductEdge!]!
 
+  """
+  Faceted filters driven by current result set. Use FilterValue.input to construct refinement queries.
+  """
+  filters: [Filter!]!
+
+  """Product nodes (shortcut for edges.map(e => e.node))"""
+  nodes: [Product!]!
+
   """Pagination info"""
   pageInfo: PageInfo!
 
@@ -3311,52 +4039,49 @@ type ProductEdge {
   node: Product!
 }
 
-"""Product filter options"""
-input ProductFilterInput {
-  """Dynamic attribute filters (Requirements: R35.12, R35.13, R35.14)"""
+"""Single product filter"""
+input ProductFilter {
+  """
+  DoSwiftly: dynamic attribute filters (configurator system). Product/variant metafield filters will be added in Wave 5.
+  """
   attributes: [AttributeFilterInput!]
 
-  """Filter by availability"""
+  """Filter by availability for sale"""
   available: Boolean
 
-  """
-  Filter by category ID (supports comma-separated UUIDs for multi-category)
-  """
-  categoryId: ID
+  """Filter by category"""
+  category: CategoryFilter
 
   """
-  Filter by collection ID (supports comma-separated UUIDs for multi-collection)
+  DoSwiftly: filter by collection ID (supports comma-separated UUIDs). Use Collection.products(filters) for collection-scoped queries.
   """
   collectionId: ID
 
-  """Filter by maximum price"""
-  maxPrice: Float
+  """Filter by variant price range"""
+  price: PriceRangeFilter
 
-  """Filter by minimum price"""
-  minPrice: Float
+  """
+  Filter by product category (free-text classification, stored on Product.category). Distinct from `category: CategoryFilter` which selects by structured Category entity.
+  """
+  productCategory: String
 
-  """Filter by product type"""
-  productType: String
+  """
+  Filter by product type enum (PHYSICAL/DIGITAL/SERVICE/SUBSCRIPTION/GIFT_CARD). Distinct from `productCategory` (free-text classification).
+  """
+  productType: ProductTypeEnum
 
-  """Filter by product types"""
-  productTypes: [String!]
+  """
+  Filter by product vendor (renamed from legacy `vendor` in ProductFilterInput)
+  """
+  productVendor: String
 
-  """Filter by tag"""
+  """Filter by product tag"""
   tag: String
 
-  """Filter by tags"""
-  tags: [String!]
-
   """
-  Filter by per-product variant options (e.g. Color=Red, Size=M). Multiple entries are combined with AND across different option names and OR within the same name. Matching is case-insensitive. Shopify parity.
+  Filter by single variant option (e.g. Color=Red). For multi-value filtering use multiple ProductFilter entries.
   """
-  variantOption: [VariantOptionFilter!]
-
-  """Filter by vendor"""
-  vendor: String
-
-  """Filter by vendor names"""
-  vendors: [String!]
+  variantOption: VariantOptionFilter
 }
 
 """Product option"""
@@ -3369,10 +4094,10 @@ type ProductOption {
   """Option name (e.g. "Color", "Size")"""
   name: String!
 
-  """Sort position among the product's options"""
-  position: Int!
+  """Sort order among the product's options"""
+  sortOrder: Int!
 
-  """Available values, ordered by position"""
+  """Available values, ordered by sortOrder"""
   values: [ProductOptionValue!]!
 }
 
@@ -3396,8 +4121,8 @@ type ProductOptionValue {
   """Display name (e.g. "Red", "XL")"""
   name: String!
 
-  """Sort position (0-based)"""
-  position: Int!
+  """Sort order (0-based)"""
+  sortOrder: Int!
 }
 
 """Original price range in shop base currency"""
@@ -3447,7 +4172,7 @@ type ProductReview {
   """Review date"""
   createdAt: DateTime!
 
-  """Helpful votes count"""
+  """Helpful votes count (upvotes)"""
   helpfulCount: Int!
   id: ID!
 
@@ -3472,6 +4197,9 @@ type ProductReview {
 
   """Review title"""
   title: String
+
+  """Unhelpful votes count (downvotes)"""
+  unhelpfulCount: Int!
 }
 
 """Paginated reviews connection"""
@@ -3491,10 +4219,13 @@ type ProductReviewEdge {
 enum ProductSortKeys {
   BEST_SELLING
   CREATED_AT
+  ID
   PRICE
+  PRODUCT_TYPE
   RELEVANCE
   TITLE
   UPDATED_AT
+  VENDOR
 }
 
 """Product type classification"""
@@ -3508,14 +4239,19 @@ enum ProductTypeEnum {
 
 """Product variant - purchasable unit"""
 type ProductVariant {
-  """Whether variant is available for purchase"""
-  available: Boolean!
+  """
+  Available stock (computed: stock - reserved). Null when track is disabled.
+  """
+  availableStock: Int
 
   """Barcode"""
   barcode: String
 
-  """Compare at price in customer preferred currency"""
-  compareAtPrice: PriceMoney
+  """Compare at price (Money). Null gdy variant nie jest na promocji."""
+  compareAtPrice: Money
+
+  """Opt-in: compare-at price with conversion transparency."""
+  compareAtPriceWithConversion: PriceMoney
 
   """Unique identifier"""
   id: ID!
@@ -3523,20 +4259,16 @@ type ProductVariant {
   """Variant image"""
   image: Image
 
-  """Original compare at price in shop base currency"""
-  originalCompareAtPrice: Money
-
-  """Original price in shop base currency"""
-  originalPrice: Money
-
-  """Position in product variants list"""
-  position: Int
+  """Whether variant is available for purchase"""
+  isAvailable: Boolean!
 
-  """Price in customer preferred currency (auto-converted)"""
-  price: PriceMoney!
+  """Variant price (Money). Default field — industry-standard schema."""
+  price: Money!
 
-  """Quantity available in stock"""
-  quantityAvailable: Int
+  """
+  Opt-in: price with full conversion transparency. Use dla currency-converter UI.
+  """
+  priceWithConversion: PriceMoney
 
   """Selected options for this variant"""
   selectedOptions: [SelectedOption!]!
@@ -3544,8 +4276,11 @@ type ProductVariant {
   """SKU code"""
   sku: String
 
+  """Sort order among product variants"""
+  sortOrder: Int
+
   """
-  Per-location stock availability (Shopify StoreAvailability parity). Null for single-location shops. Resolved by StoreAvailabilityResolver with `near`, `locationType`, and `@inContext(preferredLocationId)` support.
+  Per-location stock availability. Null for single-location shops. Resolved by StoreAvailabilityResolver with `near`, `locationType`, and `@inContext(preferredLocationId)` support.
   """
   storeAvailability(
     """Cursor for pagination"""
@@ -3554,7 +4289,7 @@ type ProductVariant {
     """Number of locations to return"""
     first: Int! = 10
 
-    """Filter by location type (DoSwiftly extension beyond Shopify parity)"""
+    """Filter by location type (DoSwiftly extension)"""
     locationType: LocationType
 
     """Sort locations by proximity to these coordinates"""
@@ -3564,8 +4299,32 @@ type ProductVariant {
   """Variant title (e.g., "Large / Red")"""
   title: String!
 
-  """Weight in grams"""
-  weight: Float
+  """Variant weight (canonical unit GRAMS — Prisma stores integer grams)"""
+  weight: Weight
+}
+
+"""Paginated list of product variants (Relay Connection)"""
+type ProductVariantConnection {
+  """Variant edges with cursors"""
+  edges: [ProductVariantEdge!]!
+
+  """Variant nodes (shortcut for edges.map(e => e.node))"""
+  nodes: [ProductVariant!]!
+
+  """Pagination info"""
+  pageInfo: PageInfo!
+
+  """Total count of variants"""
+  totalCount: Int!
+}
+
+"""Edge in a ProductVariant connection"""
+type ProductVariantEdge {
+  """Cursor for pagination"""
+  cursor: String!
+
+  """Variant node"""
+  node: ProductVariant!
 }
 
 """Catalog placement — PUBLIC | HIDDEN | BUNDLE_ONLY (Faza 1.5)"""
@@ -3579,9 +4338,6 @@ type Query {
   """List of all currencies supported by the system (ECB rates)"""
   allSupportedCurrencies: [Currency!]!
 
-  """Get available filters for product listing"""
-  availableFilters(input: AvailableFiltersInput): AvailableFilters!
-
   """Get available payment methods"""
   availablePaymentMethods: AvailablePaymentMethods!
 
@@ -3639,13 +4395,6 @@ type Query {
   """Get cart by ID"""
   cart(id: ID!): Cart
 
-  """Get recommendations based on cart contents"""
-  cartRecommendations(
-    """Cart ID to base recommendations on"""
-    cartId: String!
-    first: Int = 4
-  ): CartRecommendations!
-
   """Get category tree"""
   categories(
     """Cursor for pagination"""
@@ -3721,14 +4470,14 @@ type Query {
     code: String!
   ): Currency
 
-  """Get authenticated customer"""
-  customer(customerAccessToken: String!): Customer
+  """Get authenticated customer (cookie / Authorization Bearer)"""
+  customer: Customer
 
   """Get available customer groups"""
   customerGroups: [CustomerGroup!]
 
   """Get single order for authenticated customer"""
-  customerOrder(customerAccessToken: String!, orderId: ID!): Order
+  customerOrder(orderId: ID!): Order
 
   """Estimate points for an order amount"""
   estimatePoints(
@@ -3745,8 +4494,8 @@ type Query {
     to: String!
   ): ExchangeRate
 
-  """Get gift card by code"""
-  giftCard(code: String!): GiftCardPayload!
+  """Get gift card by code (null if not found)"""
+  giftCard(code: String!): GiftCard
 
   """Validate gift card for use"""
   giftCardValidate(amount: Float, code: String!): GiftCardValidatePayload!
@@ -3754,6 +4503,9 @@ type Query {
   """Get available languages for this shop"""
   languages: [Language!]!
 
+  """Localization context (kraje, języki, aktualny kraj/język klienta)"""
+  localization: Localization!
+
   """
   Fetch a single active location by ID. Returns null when missing, inactive, or owned by another shop (tenant isolation via StorefrontShopGuard).
   """
@@ -3763,7 +4515,7 @@ type Query {
   ): Location
 
   """
-  Paginated locations for the current shop (Shopify parity). Supports proximity (`near`), pickup-only filter (`hasPickupEnabled`), and `locationType` filter.
+  Paginated locations for the current shop. Supports proximity (`near`), pickup-only filter (`hasPickupEnabled`), and `locationType` filter.
   """
   locations(
     """Cursor for pagination"""
@@ -3800,6 +4552,14 @@ type Query {
   """Get a navigation menu by handle"""
   menu(handle: String!): Menu
 
+  """Universal ID-based lookup (Relay Node spec)"""
+  node(id: ID!, type: NodeType!): Node
+
+  """
+  Batch ID-based lookup; same NodeType dla all IDs. Missing/wrong IDs → null entries (preserved length).
+  """
+  nodes(ids: [ID!]!, type: NodeType!): [Node]!
+
   """Get a page by handle or ID"""
   page(
     """Page handle"""
@@ -3827,6 +4587,9 @@ type Query {
     sortKey: PageSortKeys! = TITLE
   ): ShopPageConnection!
 
+  """Get personalized product recommendations for the current customer"""
+  personalizedRecommendations(first: Int = 10): ProductRecommendations!
+
   """Get single product by ID or handle"""
   product(
     """Product handle (slug)"""
@@ -3836,6 +4599,11 @@ type Query {
     id: ID
   ): Product
 
+  """
+  Get available filters for product listing (renamed from availableFilters in Storefront 5.0)
+  """
+  productFilters(input: AvailableFiltersInput): AvailableFilters!
+
   """Get recommended products similar to the given product"""
   productRecommendations(
     """Type of recommendations (SIMILAR, COMPLEMENTARY, UPSELL)"""
@@ -3851,62 +4619,84 @@ type Query {
   """Get product reviews"""
   productReviews(after: String, first: Int = 10, productId: ID!, reverse: Boolean = true, sortKey: ReviewSortKey = CREATED_AT): ProductReviewConnection!
 
-  """Search products"""
-  productSearch(
-    """Cursor for pagination"""
-    after: String
-
-    """Filter options"""
-    filters: ProductFilterInput
-
-    """Number of items to fetch"""
-    first: Int! = 20
-
-    """Search query"""
-    query: String!
-  ): ProductConnection!
-
   """List products with pagination and filtering"""
   products(
-    """Cursor for pagination"""
+    """Cursor for forward pagination"""
     after: String
 
-    """Product filters"""
-    filters: ProductFilterInput
+    """Cursor for backward pagination"""
+    before: String
 
-    """Number of items to fetch"""
-    first: Int! = 20
+    """Array of ProductFilter objects (multi-filter pattern)"""
+    filters: [ProductFilter!]
 
-    """Search query"""
+    """Number of items to fetch (forward pagination, max 100)"""
+    first: Int
+
+    """Number of items to fetch (backward pagination, max 100)"""
+    last: Int
+
+    """
+    Search query (syntax: tag:, product_type:, vendor:, available_for_sale:, variants.price:>10, AND/OR/NOT)
+    """
     query: String
 
     """Reverse sort order"""
     reverse: Boolean! = false
 
     """Sort key"""
-    sortKey: ProductSortKeys = BEST_SELLING
+    sortKey: ProductSortKeys = RELEVANCE
   ): ProductConnection!
 
-  """Get personalized product recommendations"""
-  recommendations(first: Int = 10): ProductRecommendations!
-
   """Get referral program statistics"""
   referralStats: ReferralStats
 
   """Get return by ID"""
-  return(customerAccessToken: String!, id: ID!): ReturnPayload!
+  return(id: ID!): ReturnPayload!
 
   """Get available return reasons"""
   returnReasons: [ReturnReasonOption!]!
 
   """Get returns for an order"""
-  returnsByOrder(customerAccessToken: String!, orderId: ID!): ReturnConnection!
+  returnsByOrder(orderId: ID!): ReturnConnection!
 
   """Get product review statistics"""
   reviewStats(productId: ID!): ReviewStats!
 
+  """Search products (DoSwiftly alias for products() with required query)"""
+  searchProducts(
+    """Cursor for forward pagination"""
+    after: String
+
+    """Cursor for backward pagination"""
+    before: String
+
+    """Array of ProductFilter objects"""
+    filters: [ProductFilter!]
+
+    """Number of items to fetch (forward pagination)"""
+    first: Int
+
+    """Number of items to fetch (backward pagination)"""
+    last: Int
+
+    """Search query (required)"""
+    query: String!
+  ): ProductConnection!
+
+  """
+  Search suggestions (typeahead) — top-N products + styled query suggestions (Products only). Powered by PostgreSQL FTS with prefix matching for Polish morphology coverage.
+  """
+  searchSuggestions(
+    """Maximum number of products to return (default 10, max 50)"""
+    limit: Int = 10
+
+    """Search query (typeahead input)"""
+    query: String!
+  ): PredictiveSearchResult!
+
   """Get shipment by ID"""
-  shipment(customerAccessToken: String!, id: ID!): ShipmentPayload!
+  shipment(id: ID!): ShipmentPayload!
 
   """Get shipment by tracking number"""
   shipmentByTrackingNumber(trackingNumber: String!): ShipmentPayload!
@@ -3917,14 +4707,6 @@ type Query {
   """Get currency configuration for the current shop"""
   shopCurrencyConfig: ShopCurrencyConfig!
 
-  """Get products similar to a specific product"""
-  similarProducts(
-    first: Int = 6
-
-    """Product ID to find similar products for"""
-    productId: String!
-  ): ProductRecommendations!
-
   """Get translations for a language"""
   translations(input: TranslationsInput!): Translations!
 
@@ -3944,7 +4726,13 @@ type Query {
   ): Wishlist
 
   """Get customer wishlists (requires customer auth)"""
-  wishlists: [Wishlist!]!
+  wishlists(
+    """Cursor: return items after this cursor"""
+    after: String
+
+    """First N items (1-100)"""
+    first: Int = 20
+  ): WishlistConnection!
 }
 
 """Type of product recommendations to return"""
@@ -3987,8 +4775,8 @@ type RedeemRewardPayload {
   """Whether redemption was successful"""
   success: Boolean!
 
-  """Error messages if any"""
-  userErrors: [String!]!
+  """Typed user errors"""
+  userErrors: [UserError!]!
 }
 
 """Referral program statistics"""
@@ -4334,6 +5122,15 @@ type SEO {
   title: String
 }
 
+"""Predictive search query suggestion (typeahead)"""
+type SearchQuerySuggestion {
+  """Suggestion with <mark> highlights matching the query prefix"""
+  styledText: String!
+
+  """Plain text suggestion (product title)"""
+  text: String!
+}
+
 """Selected product option"""
 type SelectedOption {
   """Option name (e.g., "Size", "Color")"""
@@ -4356,8 +5153,8 @@ type Shipment {
   """When the shipment was delivered"""
   deliveredAt: DateTime
 
-  """Estimated delivery date"""
-  estimatedDeliveryDate: DateTime
+  """Estimated delivery timestamp"""
+  estimatedDeliveryAt: DateTime
 
   """Tracking events timeline"""
   events: [ShipmentEvent!]
@@ -4492,14 +5289,11 @@ enum ShipmentStatus {
 
 """Address input for shipping calculation"""
 input ShippingAddressInput {
-  """Street address line 1"""
-  address1: String
-
   """City"""
   city: String
 
-  """Country code (ISO 3166-1 alpha-2)"""
-  country: String!
+  """ISO 3166-1 alpha-2 country code"""
+  country: CountryCode!
 
   """Email address"""
   email: String
@@ -4513,11 +5307,14 @@ input ShippingAddressInput {
   """Phone number"""
   phone: String
 
-  """Postal/ZIP code"""
+  """Postal / ZIP code"""
   postalCode: String
 
-  """Province/State/Region"""
-  province: String
+  """State / province / region"""
+  state: String
+
+  """First line of street address"""
+  streetLine1: String
 }
 
 """Shipping carrier information"""
@@ -4555,6 +5352,9 @@ type Shop {
   """Bot protection configuration (platform-level)"""
   botProtection: BotProtectionInfo
 
+  """Industry-standard brand metadata (logo + slogan + colors)"""
+  brand: Brand
+
   """Complete branding configuration"""
   branding: ShopBranding
 
@@ -4564,14 +5364,20 @@ type Shop {
   """Contact email address"""
   contactEmail: String
 
+  """Contact information policy"""
+  contactInformation: ShopPolicy
+
   """Contact phone number"""
   contactPhone: String
 
   """Default currency code (ISO 4217)"""
-  currencyCode: String!
+  currencyCode: CurrencyCode!
+
+  """Customer account URL (login/orders) — z primaryDomain"""
+  customerAccountUrl: URL
 
-  """Default language code"""
-  defaultLanguage: String
+  """Default language code (ISO 639-1)"""
+  defaultLanguage: LanguageCode
 
   """Shop description"""
   description: String
@@ -4579,26 +5385,55 @@ type Shop {
   """Shop unique identifier"""
   id: ID!
 
+  """Legal notice / impressum"""
+  legalNotice: ShopPolicy
+
   """Locale to currency mapping for auto-detection (SSOT)"""
   localeToCurrencyMap: [LocaleCurrencyMapping!]!
 
   """Shop logo"""
   logo: Image
 
+  """
+  Money display format z `{{amount}}` placeholder, np. "{{amount}} zł"
+  """
+  moneyFormat: String!
+
   """Shop name"""
   name: String!
 
   """Supported payment currencies"""
-  paymentCurrencies: [String!]!
+  paymentCurrencies: [CurrencyCode!]!
+
+  """Payment configuration (currency, accepted cards, digital wallets)"""
+  paymentSettings: PaymentSettings!
+
+  """Primary domain (host + URL + SSL state)"""
+  primaryDomain: Domain!
 
-  """Primary domain URL"""
-  primaryDomain: String
+  """Privacy policy"""
+  privacyPolicy: ShopPolicy
+
+  """Refund / return policy"""
+  refundPolicy: ShopPolicy
+
+  """Shipping policy"""
+  shippingPolicy: ShopPolicy
+
+  """Countries shop ships to (z shipping zones)"""
+  shipsToCountries: [CountryCode!]!
 
   """Supported currencies for price display"""
-  supportedCurrencies: [String!]!
+  supportedCurrencies: [CurrencyCode!]!
 
-  """Supported languages"""
-  supportedLanguages: [String!]
+  """Supported languages (ISO 639-1)"""
+  supportedLanguages: [LanguageCode!]
+
+  """Terms of sale"""
+  termsOfSale: ShopPolicy
+
+  """Terms of service"""
+  termsOfService: ShopPolicy
 
   """Shop timezone"""
   timezone: String
@@ -4606,23 +5441,23 @@ type Shop {
 
 """Shop physical address"""
 type ShopAddress {
-  """Street address line 1"""
-  address1: String
-
-  """Street address line 2"""
-  address2: String
-
   """City"""
   city: String
 
   """Country code (ISO 3166-1 alpha-2)"""
   country: String
 
-  """Postal/ZIP code"""
+  """Postal / ZIP code"""
   postalCode: String
 
-  """State/Province"""
+  """State / province"""
   state: String
+
+  """First line of street address"""
+  streetLine1: String
+
+  """Second line of street address"""
+  streetLine2: String
 }
 
 """Shop branding configuration"""
@@ -4687,11 +5522,11 @@ type ShopPage {
   """HTML body content"""
   body: String!
 
-  """Auto-generated plain text summary"""
-  bodySummary: String!
-
   """Created date (ISO 8601)"""
-  createdAt: String!
+  createdAt: DateTime!
+
+  """Auto-generated plain text summary"""
+  excerpt: String!
 
   """URL handle"""
   handle: String!
@@ -4700,7 +5535,7 @@ type ShopPage {
   id: ID!
 
   """Publish date (ISO 8601)"""
-  publishedAt: String
+  publishedAt: DateTime
 
   """SEO metadata"""
   seo: SEO
@@ -4709,7 +5544,7 @@ type ShopPage {
   title: String!
 
   """Updated date (ISO 8601)"""
-  updatedAt: String!
+  updatedAt: DateTime!
 }
 
 """Paginated shop pages"""
@@ -4733,6 +5568,24 @@ type ShopPageEdge {
   node: ShopPage!
 }
 
+"""Shop legal/info policy document"""
+type ShopPolicy implements Node {
+  """Policy body (markdown)"""
+  body: String!
+
+  """URL-friendly handle (slug)"""
+  handle: String!
+
+  """Globally-unique identifier"""
+  id: ID!
+
+  """Policy title (e.g. "Privacy Policy")"""
+  title: String!
+
+  """Canonical URL on storefront"""
+  url: URL!
+}
+
 """Shop social media links"""
 type SocialLinks {
   """Facebook page URL"""
@@ -4757,10 +5610,15 @@ type SocialLinks {
   youtube: String
 }
 
-"""Per-location stock availability (Shopify StoreAvailability parity)"""
+"""Per-location stock availability"""
 type StoreAvailability {
+  """
+  Available stock at this location (computed: stock - reserved). Token-gated: null for anonymous requests, Int for authenticated customer context.
+  """
+  availableStock: Int
+
   """Whether the variant is in stock at this location"""
-  available: Boolean!
+  isAvailable: Boolean!
 
   """Location where this stock resides"""
   location: Location!
@@ -4768,12 +5626,7 @@ type StoreAvailability {
   """
   Human-readable pickup readiness string, localized (e.g., "Usually ready in 2 hours"). Null if location does not support pickup.
   """
-  pickUpTime: String
-
-  """
-  Quantity available at this location. Token-gated: null for anonymous requests, Int for authenticated customer context (Shopify parity).
-  """
-  quantityAvailable: Int
+  pickupTime: String
 }
 
 """Paginated store availability connection"""
@@ -4887,6 +5740,22 @@ input TranslationsInput {
   namespaces: [String!]
 }
 
+"""
+URL string per RFC 3986 (e.g. "https://shop.example.com/products/foo").
+"""
+scalar URL
+
+"""Measurement system (metric vs imperial) — wpływa na display formats"""
+enum UnitSystem {
+  IMPERIAL_SYSTEM
+  METRIC_SYSTEM
+}
+
+"""
+Unsigned 64-bit integer, JSON-serialized as String (BigInt-safe). Format: "{integer}".
+"""
+scalar UnsignedInt64
+
 """URL redirect (SEO, store migration)"""
 type UrlRedirect {
   """Source path"""
@@ -4917,7 +5786,7 @@ type UserError {
   message: String!
 }
 
-"""Per-product variant option filter (Color, Size, …)"""
+"""Per-product variant option filter (e.g. Color=Red)"""
 input VariantOptionFilter {
   """Option name (e.g. "Color")"""
   name: String!
@@ -4926,6 +5795,23 @@ input VariantOptionFilter {
   value: String!
 }
 
+"""Weight value with unit"""
+type Weight {
+  """Weight unit"""
+  unit: WeightUnit!
+
+  """Weight value"""
+  value: Float!
+}
+
+"""Weight unit (GRAMS canonical, KILOGRAMS/OUNCES/POUNDS for display)"""
+enum WeightUnit {
+  GRAMS
+  KILOGRAMS
+  OUNCES
+  POUNDS
+}
+
 """Customer wishlist"""
 type Wishlist {
   """Created date"""
@@ -4951,12 +5837,36 @@ type Wishlist {
   updatedAt: DateTime!
 }
 
+"""Paginated list of wishlists"""
+type WishlistConnection {
+  """Wishlist edges with cursors"""
+  edges: [WishlistEdge!]!
+
+  """Wishlist nodes (shortcut for edges.map(e => e.node))"""
+  nodes: [Wishlist!]!
+
+  """Pagination info"""
+  pageInfo: PageInfo!
+
+  """Total count of wishlists"""
+  totalCount: Int!
+}
+
 """Input for creating a wishlist"""
 input WishlistCreateInput {
   isPublic: Boolean = false
   name: String = "My Wishlist"
 }
 
+"""Wishlist edge for pagination"""
+type WishlistEdge {
+  """Cursor for pagination"""
+  cursor: String!
+
+  """Wishlist node"""
+  node: Wishlist!
+}
+
 """Wishlist item"""
 type WishlistItem {
   """Date added"""
@@ -4970,7 +5880,7 @@ type WishlistItem {
   notifyOnSale: Boolean!
 
   """Price when added to wishlist"""
-  priceAtAdd: Money!
+  priceWhenAdded: Money!
 
   """Product details"""
   product: Product
@@ -4991,7 +5901,7 @@ input WishlistItemInput {
 
 """Wishlist mutation payload"""
 type WishlistPayload {
-  """User errors"""
-  userErrors: [String!]!
+  """Typed user errors"""
+  userErrors: [UserError!]!
   wishlist: Wishlist
 }