@doswiftly/storefront-operations 13.0.0 → 14.0.0

package/schema.graphql

@@ -63,7 +63,9 @@ type AttributeDefinition {
   """Attribute ID"""
   id: ID!
 
-  """Whether attribute is filterable"""
+  """
+  Whether attribute is filterable (admin toggle). For storefront UI rendering signal use `isUsableAsFilter` (computed).
+  """
   isFilterable: Boolean!
 
   """Whether attribute is visible on product pages"""
@@ -140,6 +142,34 @@ type AttributeFilterValue {
   value: String!
 }
 
+"""Paginated + searchable attribute options (Relay Connection)"""
+type AttributeFilterValueConnection {
+  """Paginated edges z cursorami"""
+  edges: [AttributeFilterValueEdge!]!
+
+  """Shortcut: edges.map(e => e.node)"""
+  nodes: [AttributeFilterValue!]!
+
+  """Relay pagination info (hasNextPage, hasPreviousPage, cursors)"""
+  pageInfo: PageInfo!
+
+  """
+  Total number of attribute options matching the filter (po zastosowaniu search + context). NIE zmienia się przy paginacji — pokazuje pełną liczbę dla counter UI.
+  """
+  totalCount: Int!
+}
+
+"""Edge w AttributeFilterValueConnection (Relay spec)"""
+type AttributeFilterValueEdge {
+  """
+  Opaque pagination cursor (base64-encoded). Echo as `after` for next page.
+  """
+  cursor: String!
+
+  """Attribute filter value (option + product count + swatch)"""
+  node: AttributeFilterValue!
+}
+
 """Attribute input"""
 input AttributeInput {
   """Attribute key"""
@@ -157,6 +187,37 @@ enum AttributeOptionSurchargeType {
   PERCENT
 }
 
+"""Input dla attributeOptionsSearch query"""
+input AttributeOptionsSearchInput {
+  """Opaque cursor z pageInfo.endCursor poprzedniej strony"""
+  after: String
+
+  """
+  Produktowy kontekst (categoryId/collectionId/searchQuery/currentFilters) dla accurate productCount. Exclude-self: gdy currentFilters zawiera ten sam atrybut, jest pomijany.
+  """
+  contextInput: AvailableFiltersInput
+
+  """Liczba zwracanych opcji (default 50, max 100)"""
+  first: Int
+
+  """Attribute handle (URL-friendly identifier, np. "licencja")"""
+  handle: String!
+
+  """Wyszukiwanie po value/label (case-insensitive ILIKE, max 100 znaków)"""
+  search: String
+
+  """
+  Sort — COUNT_DESC default (most popular first), LABEL_ASC dla alphabetical
+  """
+  sort: AttributeOptionsSearchSort
+}
+
+"""Sort order for attributeOptionsSearch results"""
+enum AttributeOptionsSearchSort {
+  COUNT_DESC
+  LABEL_ASC
+}
+
 """Min/max bounds for numeric attributes"""
 type AttributeRangeBounds {
   """Currency code for CURRENCY type"""
@@ -271,7 +332,7 @@ type AvailableFilters {
   availableCount: Int!
 
   """
-  Faza 3 (2026-05-17): canonical Brand entities z product counts w current context. Storefront UI renderuje checkbox list / dropdown z logo per brand. Klik → `filters: [{brand: {slug}}]`. Tylko brandy z >0 produktów w current product set + isActive=true.
+  Faza 3 (2026-05-17): canonical Brand entities z product counts w current context. Storefront UI renderuje checkbox list / dropdown z logo per brand. Klik → `filters: [{brand: {handle}}]`. Tylko brandy z >0 produktów w current product set + isActive=true.
   """
   brands: [BrandFilterValue!]
 
@@ -431,6 +492,9 @@ type BlogCategory {
   """Category description"""
   description: String
 
+  """URL-friendly handle"""
+  handle: String!
+
   """Category ID"""
   id: ID!
 
@@ -445,9 +509,6 @@ type BlogCategory {
 
   """SEO metadata"""
   seo: SEO
-
-  """URL-friendly slug"""
-  slug: String!
 }
 
 """Blog post"""
@@ -479,6 +540,9 @@ type BlogPost {
   """Featured image"""
   featuredImage: Image
 
+  """URL-friendly handle"""
+  handle: String!
+
   """Post ID"""
   id: ID!
 
@@ -494,9 +558,6 @@ type BlogPost {
   """SEO metadata"""
   seo: SEO
 
-  """URL-friendly slug"""
-  slug: String!
-
   """Post status"""
   status: BlogPostStatus!
 
@@ -552,6 +613,9 @@ enum BlogPostStatus {
 
 """Blog tag"""
 type BlogTag {
+  """URL-friendly handle"""
+  handle: String!
+
   """Tag ID"""
   id: ID!
 
@@ -560,9 +624,6 @@ type BlogTag {
 
   """Number of posts with this tag"""
   postCount: Int!
-
-  """URL-friendly slug"""
-  slug: String!
 }
 
 """Bot protection configuration (platform-level)"""
@@ -589,25 +650,21 @@ type BotProtectionProviderInfo {
   siteKey: String!
 }
 
-"""Shop brand metadata (logo, colors, slogan)"""
+"""
+Canonical product brand entity (np. Funko, Nike). Distinct od ShopBrand (shop branding metadata).
+"""
 type Brand {
-  """Primary + secondary brand colors"""
-  colors: BrandColors
-
-  """Cover image / hero banner"""
-  coverImage: Image
-
-  """Primary logo"""
-  logo: Image
+  """URL-friendly handle (e.g. "funko" → /brands/funko). Stable per-shop."""
+  handle: String!
 
-  """Short brand description"""
-  shortDescription: String
+  """Brand unique identifier"""
+  id: ID!
 
-  """Marketing slogan / tagline"""
-  slogan: String
+  """Brand logo URL (CDN-served, storefront-rendered)"""
+  logo: String
 
-  """Square logo variant (favicons, app tiles)"""
-  squareLogo: Image
+  """Brand display name (e.g. "Funko", "Nintendo")"""
+  name: String!
 }
 
 """Single brand color group (background + foreground hex)"""
@@ -627,17 +684,20 @@ type BrandColors {
 
 """Filter products po brand (canonical entity)"""
 input BrandFilter {
-  """Brand ID — exact UUID match"""
-  id: ID
-
   """
-  Brand slug — URL-friendly identifier. Preferowany over `id` dla storefront refetch (stable po URL share).
+  Brand handle — URL-friendly identifier. Preferowany over `id` dla storefront refetch (stable po URL share).
   """
-  slug: String
+  handle: String
+
+  """Brand ID — exact UUID match"""
+  id: ID
 }
 
 """Brand filter value z product count"""
 type BrandFilterValue {
+  """Brand handle (refetch payload — paste w ProductFilter.brand.handle)"""
+  handle: String!
+
   """Brand ID"""
   id: ID!
 
@@ -649,26 +709,6 @@ type BrandFilterValue {
 
   """Liczba produktów z tym brandem w current product set"""
   productCount: Int!
-
-  """Brand slug (refetch payload — paste w ProductFilter.brand.slug)"""
-  slug: String!
-}
-
-"""
-Brand summary — minimalna projekcja dla storefront catalog + filter rendering
-"""
-type BrandSummary {
-  """Brand unique identifier"""
-  id: ID!
-
-  """Brand logo URL (CDN-served, storefront-rendered)"""
-  logo: String
-
-  """Brand display name (e.g. "Funko", "Nintendo")"""
-  name: String!
-
-  """URL-friendly slug — używane dla future /marka/[slug] landing pages"""
-  slug: String!
 }
 
 """Business hours for a day"""
@@ -776,6 +816,11 @@ type Cart implements Node {
   """Available payment methods dla tego cart (shop-configured providers)"""
   availablePaymentMethods: [PaymentMethod!]!
 
+  """
+  Cart-aware shipping methods discovery. Returns empty methods + DIGITAL_ONLY_NO_SHIPPING user error when the cart contains only non-physical items (digital, gift card, service, subscription). Physical / mixed carts get the same method computation as the standalone `availableShippingMethods` query but with subtotal and weight pulled from the cart aggregate.
+  """
+  availableShippingMethods(address: ShippingAddressInput!): AvailableShippingMethodsPayload!
+
   """
   Billing address ustawiony przez cartSetBillingAddress (jeśli różny od shipping)
   """
@@ -821,6 +866,11 @@ type Cart implements Node {
   """Product recommendations based on cart contents"""
   recommendations(first: Int = 4): CartRecommendations
 
+  """
+  True if any line in the cart requires physical shipping. False when every line is non-physical (digital, gift card, service, subscription). Use as the single signal to render or skip the shipping picker in checkout.
+  """
+  requiresShipping: Boolean!
+
   """Selected payment method (PayU/Stripe/COD/etc.)"""
   selectedPaymentMethod: PaymentMethod
 
@@ -1139,6 +1189,11 @@ type CartLine {
   """Quantity of this item"""
   quantity: Int!
 
+  """
+  True if this line item requires physical shipping (productType=PHYSICAL). False for digital, gift card, service, and subscription items. Use to skip the shipping step in checkout when every line is non-physical.
+  """
+  requiresShipping: Boolean!
+
   """Product variant being purchased"""
   variant: ProductVariant!
 }
@@ -1491,6 +1546,7 @@ enum CartWarningCode {
   MERCHANDISE_NOT_AVAILABLE
   MERCHANDISE_NOT_ENOUGH_STOCK
   PAYMENTS_AMOUNT_REGION_MISMATCH
+  SHIPPING_METHOD_AUTO_CLEARED
 }
 
 """Product category - hierarchical organization"""
@@ -1501,6 +1557,11 @@ type Category {
   """Category description"""
   description: String
 
+  """
+  URL-friendly handle (e.g. "electronics" -> /categories/electronics). Stable per-shop.
+  """
+  handle: String!
+
   """Unique identifier"""
   id: ID!
 
@@ -1528,9 +1589,6 @@ type Category {
   """SEO metadata"""
   seo: SEO
 
-  """URL-friendly slug"""
-  slug: String!
-
   """Sort order within parent"""
   sortOrder: Int!
 }
@@ -1567,6 +1625,9 @@ input CategoryFilter {
 
 """Category filter option"""
 type CategoryFilterOption {
+  """URL-friendly handle"""
+  handle: String!
+
   """Category ID"""
   id: ID!
 
@@ -1581,9 +1642,6 @@ type CategoryFilterOption {
 
   """Number of products in this category"""
   productCount: Int!
-
-  """URL-friendly slug"""
-  slug: String!
 }
 
 """Collection - curated group of products"""
@@ -3015,6 +3073,9 @@ type LoyaltyReward {
   """Discount percentage (if discount type)"""
   discountPercent: Float
 
+  """URL-friendly handle"""
+  handle: String!
+
   """Reward ID"""
   id: ID!
 
@@ -3033,9 +3094,6 @@ type LoyaltyReward {
   """Redemptions remaining (null = unlimited)"""
   redemptionsRemaining: Int
 
-  """URL-friendly slug"""
-  slug: String!
-
   """Minimum tier required"""
   tierRequired: LoyaltyTier
 
@@ -3348,16 +3406,17 @@ type MenuItem {
   type: MenuItemType!
 
   """
-  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.
+  Pre-resolved URL path computed server-side using a standard route convention: /categories/<handle>, /collections/<handle>, /pages/<handle>, /products/<handle>, /brands/<handle>. Static types resolve to /, /search, /products, /blog. HTTP returns the manually stored URL. Null when type is a resource link and the underlying resource was deleted. If your storefront uses non-standard routing (e.g. single-segment /<handle>), prefer reading the `resource` field instead and build URLs yourself from `resource.__typename` + `handle`.
   """
   url: URL
 }
 
-union MenuItemResource = Category | Collection | Product | ShopPage
+union MenuItemResource = Brand | Category | Collection | Product | ShopPage
 
 """Menu item link type"""
 enum MenuItemType {
   BLOG
+  BRAND
   CATALOG
   CATEGORY
   COLLECTION
@@ -3994,7 +4053,7 @@ type Product implements Node {
   """
   Canonical brand entity (Faza 3, 2026-05-17). Resolved via DataLoader (N+1 safe dla list queries). Null gdy product nie ma przypisanego brand_id.
   """
-  brand: BrandSummary
+  brand: Brand
 
   """
   Wszystkie kategorie do których produkt należy (M2M przez ProductCategory junction). Posortowane po junction.sortOrder ASC. Empty list gdy produkt nie jest w żadnej kategorii.
@@ -4108,6 +4167,9 @@ type ProductAttributeDefinition {
   """Filling mode — MERCHANT | CUSTOMER | BOTH"""
   fillingMode: AttributeFillingMode!
 
+  """URL-friendly handle"""
+  handle: String!
+
   """Definition ID"""
   id: ID!
 
@@ -4134,9 +4196,6 @@ type ProductAttributeDefinition {
   """
   scopeProductId: ID
 
-  """URL-friendly slug"""
-  slug: String!
-
   """Tax class ID; null = inherit from variant"""
   taxClassId: ID
 
@@ -4522,6 +4581,11 @@ type Query {
   """List of all currencies supported by the system (ECB rates)"""
   allSupportedCurrencies: [Currency!]!
 
+  """
+  Paginated + searchable attribute options dla drill-into filter UI (np. dropdown z 800 licencjami + search input). Honors product context z exclude-self per attribute. Sort: COUNT_DESC default (most popular first), LABEL_ASC dla alfabetycznego z polskim collation.
+  """
+  attributeOptionsSearch(input: AttributeOptionsSearchInput!): AttributeFilterValueConnection!
+
   """Get available payment methods"""
   availablePaymentMethods: AvailablePaymentMethods!
 
@@ -4539,11 +4603,11 @@ type Query {
 
   """Get single blog post"""
   blogPost(
+    """Post handle"""
+    handle: String
+
     """Post ID"""
     id: ID
-
-    """Post slug"""
-    slug: String
   ): BlogPost
 
   """List blog posts"""
@@ -4554,8 +4618,8 @@ type Query {
     """Filter by author ID"""
     authorId: String
 
-    """Filter by category slug"""
-    categorySlug: String
+    """Filter by category handle"""
+    categoryHandle: String
 
     """Filter featured posts only"""
     featured: Boolean
@@ -4569,8 +4633,8 @@ type Query {
     """Sort key"""
     sortKey: BlogPostSortKey = PUBLISHED_AT
 
-    """Filter by tag slug"""
-    tagSlug: String
+    """Filter by tag handle"""
+    tagHandle: String
   ): BlogPostConnection!
 
   """List blog tags"""
@@ -4609,11 +4673,11 @@ type Query {
 
   """Get category by ID or slug"""
   category(
+    """Category handle (URL-friendly)"""
+    handle: String
+
     """Category ID"""
     id: ID
-
-    """Category slug"""
-    slug: String
   ): Category
 
   """Get single collection"""
@@ -5547,8 +5611,10 @@ type Shop {
   """Bot protection configuration (platform-level)"""
   botProtection: BotProtectionInfo
 
-  """Industry-standard brand metadata (logo + slogan + colors)"""
-  brand: Brand
+  """
+  Shop brand metadata (logo + slogan + colors). Tenant-scoped (vs canonical product `Brand` entity used in `Product.brand`).
+  """
+  brand: ShopBrand
 
   """Complete branding configuration"""
   branding: ShopBranding
@@ -5655,6 +5721,27 @@ type ShopAddress {
   streetLine2: String
 }
 
+"""Shop brand metadata (logo, colors, slogan)"""
+type ShopBrand {
+  """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
+}
+
 """Shop branding configuration"""
 type ShopBranding {
   """Brand colors"""