@veyralabs/skills 0.2.0 → 0.4.0

package/skills/shopify-suite/shopify-dev/references/graphql-queries.md

@@ -0,0 +1,298 @@
+# GraphQL Queries — shopify-dev Reference
+
+Ready-to-use queries for Storefront API and Admin API.
+Check API version in your app config before using — Shopify deprecates quarterly.
+
+---
+
+## Storefront API
+
+Use for: public-facing data, headless storefronts, Hydrogen.
+Auth: public Storefront API token (safe for frontend).
+
+### Products
+
+```graphql
+query GetProduct($handle: String!) {
+  product(handle: $handle) {
+    id
+    title
+    handle
+    description
+    descriptionHtml
+    vendor
+    productType
+    tags
+    priceRange {
+      minVariantPrice { amount currencyCode }
+      maxVariantPrice { amount currencyCode }
+    }
+    compareAtPriceRange {
+      minVariantPrice { amount currencyCode }
+    }
+    featuredImage { url altText width height }
+    images(first: 20) {
+      nodes { id url altText width height }
+    }
+    variants(first: 100) {
+      nodes {
+        id
+        title
+        availableForSale
+        quantityAvailable
+        price { amount currencyCode }
+        compareAtPrice { amount currencyCode }
+        selectedOptions { name value }
+        image { url altText }
+      }
+    }
+    seo { title description }
+  }
+}
+```
+
+### Collections
+
+```graphql
+query GetCollection($handle: String!, $cursor: String) {
+  collection(handle: $handle) {
+    id
+    title
+    handle
+    description
+    image { url altText }
+    products(first: 24, after: $cursor, sortKey: BEST_SELLING) {
+      pageInfo { hasNextPage endCursor }
+      nodes {
+        id
+        title
+        handle
+        featuredImage { url altText }
+        priceRange {
+          minVariantPrice { amount currencyCode }
+        }
+        availableForSale
+      }
+    }
+  }
+}
+```
+
+### Cart
+
+```graphql
+mutation CartCreate($lines: [CartLineInput!], $buyerIdentity: CartBuyerIdentityInput) {
+  cartCreate(input: { lines: $lines, buyerIdentity: $buyerIdentity }) {
+    cart {
+      id
+      checkoutUrl
+      totalQuantity
+      cost {
+        totalAmount { amount currencyCode }
+        subtotalAmount { amount currencyCode }
+      }
+      lines(first: 100) {
+        nodes {
+          id
+          quantity
+          merchandise {
+            ... on ProductVariant {
+              id
+              title
+              price { amount currencyCode }
+              product { title handle featuredImage { url } }
+            }
+          }
+        }
+      }
+    }
+    userErrors { field message }
+  }
+}
+```
+
+```graphql
+mutation CartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) {
+  cartLinesAdd(cartId: $cartId, lines: $lines) {
+    cart { id totalQuantity cost { totalAmount { amount currencyCode } } }
+    userErrors { field message }
+  }
+}
+```
+
+```graphql
+mutation CartLinesUpdate($cartId: ID!, $lines: [CartLineUpdateInput!]!) {
+  cartLinesUpdate(cartId: $cartId, lines: $lines) {
+    cart { id totalQuantity }
+    userErrors { field message }
+  }
+}
+```
+
+### Search (Predictive)
+
+```graphql
+query PredictiveSearch($query: String!) {
+  predictiveSearch(query: $query, limit: 5) {
+    products {
+      id
+      title
+      handle
+      featuredImage { url altText }
+      priceRange { minVariantPrice { amount currencyCode } }
+    }
+    collections { id title handle }
+    pages { id title handle }
+  }
+}
+```
+
+### Customer
+
+```graphql
+query GetCustomer($customerAccessToken: String!) {
+  customer(customerAccessToken: $customerAccessToken) {
+    id
+    firstName
+    lastName
+    email
+    orders(first: 10, sortKey: PROCESSED_AT, reverse: true) {
+      nodes {
+        id
+        orderNumber
+        processedAt
+        financialStatus
+        fulfillmentStatus
+        totalPrice { amount currencyCode }
+        lineItems(first: 5) {
+          nodes {
+            title
+            quantity
+            variant { image { url } price { amount currencyCode } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Admin API
+
+Use for: app backends, webhooks, bulk operations.
+Auth: Admin API access token (server-side only, never expose to client).
+
+### Product Create
+
+```graphql
+mutation ProductCreate($input: ProductInput!) {
+  productCreate(input: $input) {
+    product {
+      id
+      title
+      handle
+      status
+    }
+    userErrors { field message }
+  }
+}
+```
+
+Variables:
+```json
+{
+  "input": {
+    "title": "Product Title",
+    "descriptionHtml": "<p>Description</p>",
+    "vendor": "Brand Name",
+    "productType": "Category",
+    "status": "DRAFT",
+    "variants": [
+      {
+        "price": "29.99",
+        "sku": "SKU-001",
+        "inventoryQuantities": [{
+          "availableQuantity": 100,
+          "locationId": "gid://shopify/Location/YOUR_LOCATION_ID"
+        }]
+      }
+    ]
+  }
+}
+```
+
+### Metafields Set (bulk)
+
+```graphql
+mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) {
+  metafieldsSet(metafields: $metafields) {
+    metafields { key value namespace }
+    userErrors { field message }
+  }
+}
+```
+
+### Bulk Operations (for large datasets)
+
+```graphql
+mutation BulkOperationRunQuery($query: String!) {
+  bulkOperationRunQuery(query: $query) {
+    bulkOperation { id status }
+    userErrors { field message }
+  }
+}
+```
+
+Poll for completion:
+```graphql
+query BulkOperationStatus {
+  currentBulkOperation {
+    id
+    status
+    errorCode
+    objectCount
+    fileSize
+    url
+    partialDataUrl
+  }
+}
+```
+
+---
+
+## Common Patterns
+
+### Cursor-based pagination
+
+```typescript
+async function fetchAllProducts(storefront) {
+  let allProducts = [];
+  let cursor = null;
+  let hasNextPage = true;
+
+  while (hasNextPage) {
+    const { products } = await storefront.query(PRODUCTS_QUERY, {
+      variables: { cursor },
+    });
+    allProducts.push(...products.nodes);
+    hasNextPage = products.pageInfo.hasNextPage;
+    cursor = products.pageInfo.endCursor;
+  }
+
+  return allProducts;
+}
+```
+
+### Error handling for mutations
+
+```typescript
+const { data } = await admin.graphql(MUTATION, { variables });
+
+if (data.productCreate.userErrors.length > 0) {
+  throw new Error(
+    data.productCreate.userErrors.map(e => `${e.field}: ${e.message}`).join(', ')
+  );
+}
+```

package/skills/shopify-suite/shopify-dev/references/liquid-patterns.md

@@ -0,0 +1,286 @@
+# Liquid Patterns — shopify-dev Reference
+
+Common Liquid patterns, filters, and gotchas for Shopify theme development.
+
+---
+
+## Objects
+
+### Global objects (available everywhere)
+
+| Object | What it is |
+|--------|-----------|
+| `shop` | Store settings, name, currency, policies |
+| `cart` | Current cart (items, total, count) |
+| `customer` | Logged-in customer (nil if guest) |
+| `request` | Current request info (page_type, host) |
+| `settings` | Theme settings from settings_data.json |
+| `content_for_header` | Required in `<head>` — Shopify scripts injection |
+| `content_for_layout` | Required in layout — renders template content |
+
+### Template-specific objects
+
+| Template | Objects available |
+|----------|------------------|
+| product | `product`, `current_variant` |
+| collection | `collection`, `current_tags`, `current_vendor` |
+| article | `article`, `blog` |
+| page | `page` |
+| cart | `cart` |
+| order (customer) | `order` |
+
+---
+
+## Filters
+
+### String filters
+
+```liquid
+{{ product.title | upcase }}
+{{ product.title | downcase }}
+{{ product.title | capitalize }}
+{{ product.description | strip_html }}
+{{ product.description | truncate: 150 }}
+{{ product.description | truncate_words: 30 }}
+{{ "  padded  " | strip }}
+{{ product.handle | replace: "-", " " }}
+```
+
+### Number and money filters
+
+```liquid
+{{ product.price | money }}                 → "€29,99"
+{{ product.price | money_without_currency }} → "29,99"
+{{ product.price | money_with_currency }}    → "29,99 EUR"
+{{ product.price | divided_by: 100.0 }}      → raw float
+{{ 1.5 | round }}                            → 2
+{{ 1.5 | floor }}                            → 1
+{{ 1.5 | ceil }}                             → 2
+```
+
+Note: Shopify stores prices in cents. `product.price` = 2999 = €29.99. Always use `| money` for display.
+
+### URL filters
+
+```liquid
+{{ product.featured_image | img_url: '800x' }}
+{{ product.featured_image | img_url: '800x600', crop: 'center' }}
+{{ product.featured_image | image_url: width: 800 }}  ← new Liquid syntax
+{{ 'theme.css' | asset_url }}
+{{ 'custom.js' | asset_url | script_tag }}
+{{ product.url | within: collection }}  ← collection-scoped URL
+```
+
+### Array filters
+
+```liquid
+{{ product.tags | join: ", " }}
+{{ collection.products | size }}
+{{ product.images | first }}
+{{ product.images | last }}
+{{ product.variants | map: "title" | join: ", " }}
+{{ collection.products | where: "available", true }}
+{{ collection.products | sort: "price" }}
+{{ collection.products | reverse }}
+```
+
+### Date filters
+
+```liquid
+{{ article.created_at | date: "%B %d, %Y" }}   → "January 15, 2025"
+{{ article.created_at | date: "%Y-%m-%d" }}     → "2025-01-15"
+{{ "now" | date: "%s" | plus: 0 }}              → Unix timestamp
+```
+
+---
+
+## Tags
+
+### Conditionals
+
+```liquid
+{% if customer %}
+  Hello, {{ customer.first_name }}
+{% elsif request.page_type == "product" %}
+  Product page
+{% else %}
+  Guest
+{% endif %}
+
+{% unless product.available %}
+  Sold out
+{% endunless %}
+
+{% case product.type %}
+  {% when "Shirt" %}
+    ...
+  {% when "Pants", "Trousers" %}
+    ...
+  {% else %}
+    ...
+{% endcase %}
+```
+
+### Loops
+
+```liquid
+{% for product in collection.products %}
+  {{ product.title }}
+{% endfor %}
+
+{% for i in (1..5) %}
+  {{ i }}
+{% endfor %}
+
+{% for tag in product.tags limit: 3 offset: 1 %}
+  {{ tag }}
+{% endfor %}
+
+{% for product in collection.products %}
+  {% if forloop.first %}First{% endif %}
+  {% if forloop.last %}Last{% endif %}
+  {{ forloop.index }}  ← 1-based
+  {{ forloop.index0 }} ← 0-based
+{% endfor %}
+```
+
+### Content inclusion
+
+```liquid
+{% render 'card-product', product: product %}
+{% render 'icon', name: 'cart' %}
+
+{% section 'header' %}
+
+{% include 'snippet' %}   ← deprecated, use render
+```
+
+`render` is sandboxed — parent variables not accessible unless passed explicitly.
+
+### Pagination
+
+```liquid
+{% paginate collection.products by 24 %}
+  {% for product in collection.products %}
+    ...
+  {% endfor %}
+
+  {{ paginate | default_pagination }}
+{% endpaginate %}
+```
+
+Custom pagination:
+```liquid
+{% paginate collection.products by 24 %}
+  {% if paginate.previous %}
+    <a href="{{ paginate.previous.url }}">Previous</a>
+  {% endif %}
+
+  {% for part in paginate.parts %}
+    {% if part.is_link %}
+      <a href="{{ part.url }}">{{ part.title }}</a>
+    {% else %}
+      <span>{{ part.title }}</span>
+    {% endif %}
+  {% endfor %}
+
+  {% if paginate.next %}
+    <a href="{{ paginate.next.url }}">Next</a>
+  {% endif %}
+{% endpaginate %}
+```
+
+---
+
+## Gotchas
+
+### Blank vs nil vs false
+
+```liquid
+{% if product.metafields.custom.badge %}  ← true if value exists AND not empty
+{% if product.metafields.custom.badge != blank %}  ← safer
+{% if product.metafields.custom.badge == nil %}  ← only nil check
+```
+
+### Price display edge case
+
+Always check for variant availability before displaying compare_at_price:
+```liquid
+{% if product.compare_at_price_max > product.price_min %}
+  <s>{{ product.compare_at_price_max | money }}</s>
+{% endif %}
+```
+
+### render scope
+
+```liquid
+{% render 'card', product: product %}
+```
+
+Inside `card.liquid`, only `product` is accessible — not `collection`, `shop`, `settings`, etc. Pass each required variable explicitly.
+
+`settings` is an exception — globally accessible in rendered snippets.
+
+### Forloop and break
+
+Liquid has no `break` in for loops. Use `limit` to cap iterations, or build logic with conditionals and `continue`:
+
+```liquid
+{% for product in collection.products limit: 10 %}
+  {% if product.available == false %}{% continue %}{% endif %}
+  {{ product.title }}
+{% endfor %}
+```
+
+### Section settings output in JS
+
+```liquid
+<script>
+  const threshold = {{ section.settings.countdown_hours | times: 3600 }};
+  const color = {{ section.settings.text_color | json }};
+</script>
+```
+
+`| json` escapes strings correctly. Never interpolate raw strings into JS.
+
+### Metafield access
+
+```liquid
+{{ product.metafields.custom.size_guide }}
+{{ product.metafields["reviews"]["rating"] }}
+
+{% assign guide = product.metafields.custom.size_guide %}
+{% if guide %}
+  {{ guide.value }}
+{% endif %}
+```
+
+Metafield types in Liquid: `value` for single values, `.value.items` for list types.
+
+### Translation (i18n)
+
+```liquid
+{{ 'products.product.add_to_cart' | t }}
+{{ 'cart.items_count' | t: count: cart.item_count }}
+```
+
+Keys defined in `locales/en.default.json`. Always use `| t` for user-facing strings.
+
+---
+
+## Liquid Anti-Patterns
+
+**Using `include` instead of `render`:** `include` shares scope (can read parent variables), which creates hidden coupling. Use `render`.
+
+**Doing math with price in Liquid:** `product.price | times: 1.21` for VAT display — Liquid math on integers (cents) then format. Don't format first, then calculate.
+
+**Nested loops for lookups:** O(n²) in Liquid. Build a hash map instead:
+```liquid
+{% assign variant_map = "" %}
+{% for variant in product.variants %}
+  {% assign variant_map = variant_map | append: variant.id | append: ":" | append: variant.title | append: "," %}
+{% endfor %}
+```
+Or pass data to JS and handle there.
+
+**Long conditional chains in Liquid:** Move logic to a snippet with `render`, or handle in JS.