@vodailoc/kilo-kit-mcp 1.1.0 → 1.2.0

package/skills/engineering/shopify/references/extensions.md

@@ -1,493 +1,493 @@
-# Extensions Reference
-
-Guide for building UI extensions and Shopify Functions.
-
-## Checkout UI Extensions
-
-Customize checkout and thank-you pages with native-rendered components.
-
-### Extension Points
-
-**Block Targets (Merchant-Configurable):**
-- `purchase.checkout.block.render` - Main checkout
-- `purchase.thank-you.block.render` - Thank you page
-
-**Static Targets (Fixed Position):**
-- `purchase.checkout.header.render-after`
-- `purchase.checkout.contact.render-before`
-- `purchase.checkout.shipping-option-list.render-after`
-- `purchase.checkout.payment-method-list.render-after`
-- `purchase.checkout.footer.render-before`
-
-### Setup
-
-```bash
-shopify app generate extension --type checkout_ui_extension
-```
-
-Configuration (`shopify.extension.toml`):
-```toml
-api_version = "2025-01"
-name = "gift-message"
-type = "ui_extension"
-
-[[extensions.targeting]]
-target = "purchase.checkout.block.render"
-
-[capabilities]
-network_access = true
-api_access = true
-```
-
-### Basic Example
-
-```javascript
-import { reactExtension, BlockStack, TextField, Checkbox, useApi } from '@shopify/ui-extensions-react/checkout';
-
-export default reactExtension('purchase.checkout.block.render', () => <Extension />);
-
-function Extension() {
-  const [message, setMessage] = useState('');
-  const [isGift, setIsGift] = useState(false);
-  const { applyAttributeChange } = useApi();
-
-  useEffect(() => {
-    if (isGift) {
-      applyAttributeChange({
-        type: 'updateAttribute',
-        key: 'gift_message',
-        value: message
-      });
-    }
-  }, [message, isGift]);
-
-  return (
-    <BlockStack spacing="loose">
-      <Checkbox checked={isGift} onChange={setIsGift}>
-        This is a gift
-      </Checkbox>
-      {isGift && (
-        <TextField
-          label="Gift Message"
-          value={message}
-          onChange={setMessage}
-          multiline={3}
-        />
-      )}
-    </BlockStack>
-  );
-}
-```
-
-### Common Hooks
-
-**useApi:**
-```javascript
-const { extensionPoint, shop, storefront, i18n, sessionToken } = useApi();
-```
-
-**useCartLines:**
-```javascript
-const lines = useCartLines();
-lines.forEach(line => {
-  console.log(line.merchandise.product.title, line.quantity);
-});
-```
-
-**useShippingAddress:**
-```javascript
-const address = useShippingAddress();
-console.log(address.city, address.countryCode);
-```
-
-**useApplyCartLinesChange:**
-```javascript
-const applyChange = useApplyCartLinesChange();
-
-async function addItem() {
-  await applyChange({
-    type: 'addCartLine',
-    merchandiseId: 'gid://shopify/ProductVariant/123',
-    quantity: 1
-  });
-}
-```
-
-### Core Components
-
-**Layout:**
-- `BlockStack` - Vertical stacking
-- `InlineStack` - Horizontal layout
-- `Grid`, `GridItem` - Grid layout
-- `View` - Container
-- `Divider` - Separator
-
-**Input:**
-- `TextField` - Text input
-- `Checkbox` - Boolean
-- `Select` - Dropdown
-- `DatePicker` - Date selection
-- `Form` - Form wrapper
-
-**Display:**
-- `Text`, `Heading` - Typography
-- `Banner` - Messages
-- `Badge` - Status
-- `Image` - Images
-- `Link` - Hyperlinks
-- `List`, `ListItem` - Lists
-
-**Interactive:**
-- `Button` - Actions
-- `Modal` - Overlays
-- `Pressable` - Click areas
-
-## Admin UI Extensions
-
-Extend Shopify admin interface.
-
-### Admin Action
-
-Custom actions on resource pages.
-
-```bash
-shopify app generate extension --type admin_action
-```
-
-```javascript
-import { reactExtension, AdminAction, Button } from '@shopify/ui-extensions-react/admin';
-
-export default reactExtension('admin.product-details.action.render', () => <Extension />);
-
-function Extension() {
-  const { data } = useData();
-
-  async function handleExport() {
-    const response = await fetch('/api/export', {
-      method: 'POST',
-      body: JSON.stringify({ productId: data.product.id })
-    });
-    console.log('Exported:', await response.json());
-  }
-
-  return (
-    <AdminAction
-      title="Export Product"
-      primaryAction={<Button onPress={handleExport}>Export</Button>}
-    />
-  );
-}
-```
-
-**Targets:**
-- `admin.product-details.action.render`
-- `admin.order-details.action.render`
-- `admin.customer-details.action.render`
-
-### Admin Block
-
-Embedded content in admin pages.
-
-```javascript
-import { reactExtension, BlockStack, Text, Badge } from '@shopify/ui-extensions-react/admin';
-
-export default reactExtension('admin.product-details.block.render', () => <Extension />);
-
-function Extension() {
-  const { data } = useData();
-  const [analytics, setAnalytics] = useState(null);
-
-  useEffect(() => {
-    fetchAnalytics(data.product.id).then(setAnalytics);
-  }, []);
-
-  return (
-    <BlockStack>
-      <Text variant="headingMd">Product Analytics</Text>
-      <Text>Views: {analytics?.views || 0}</Text>
-      <Text>Conversions: {analytics?.conversions || 0}</Text>
-      <Badge tone={analytics?.trending ? "success" : "info"}>
-        {analytics?.trending ? "Trending" : "Normal"}
-      </Badge>
-    </BlockStack>
-  );
-}
-```
-
-**Targets:**
-- `admin.product-details.block.render`
-- `admin.order-details.block.render`
-- `admin.customer-details.block.render`
-
-## POS UI Extensions
-
-Customize Point of Sale experience.
-
-### Smart Grid Tile
-
-Quick access action on POS home screen.
-
-```javascript
-import { reactExtension, SmartGridTile } from '@shopify/ui-extensions-react/pos';
-
-export default reactExtension('pos.home.tile.render', () => <Extension />);
-
-function Extension() {
-  function handlePress() {
-    // Navigate to custom workflow
-  }
-
-  return (
-    <SmartGridTile
-      title="Gift Cards"
-      subtitle="Manage gift cards"
-      onPress={handlePress}
-    />
-  );
-}
-```
-
-### POS Modal
-
-Full-screen workflow.
-
-```javascript
-import { reactExtension, Screen, BlockStack, Button, TextField } from '@shopify/ui-extensions-react/pos';
-
-export default reactExtension('pos.home.modal.render', () => <Extension />);
-
-function Extension() {
-  const { navigation } = useApi();
-  const [amount, setAmount] = useState('');
-
-  function handleIssue() {
-    // Issue gift card
-    navigation.pop();
-  }
-
-  return (
-    <Screen name="Gift Card" title="Issue Gift Card">
-      <BlockStack>
-        <TextField label="Amount" value={amount} onChange={setAmount} />
-        <TextField label="Recipient Email" />
-        <Button onPress={handleIssue}>Issue</Button>
-      </BlockStack>
-    </Screen>
-  );
-}
-```
-
-## Customer Account Extensions
-
-Customize customer account pages.
-
-### Order Status Extension
-
-```javascript
-import { reactExtension, BlockStack, Text, Button } from '@shopify/ui-extensions-react/customer-account';
-
-export default reactExtension('customer-account.order-status.block.render', () => <Extension />);
-
-function Extension() {
-  const { order } = useApi();
-
-  function handleReturn() {
-    // Initiate return
-  }
-
-  return (
-    <BlockStack>
-      <Text variant="headingMd">Need to return?</Text>
-      <Text>Start return for order {order.name}</Text>
-      <Button onPress={handleReturn}>Start Return</Button>
-    </BlockStack>
-  );
-}
-```
-
-**Targets:**
-- `customer-account.order-status.block.render`
-- `customer-account.order-index.block.render`
-- `customer-account.profile.block.render`
-
-## Shopify Functions
-
-Serverless backend customization.
-
-### Function Types
-
-**Discounts:**
-- `order_discount` - Order-level discounts
-- `product_discount` - Product-specific discounts
-- `shipping_discount` - Shipping discounts
-
-**Payment Customization:**
-- Hide/rename/reorder payment methods
-
-**Delivery Customization:**
-- Custom shipping options
-- Delivery rules
-
-**Validation:**
-- Cart validation rules
-- Checkout validation
-
-### Create Function
-
-```bash
-shopify app generate extension --type function
-```
-
-### Order Discount Function
-
-```javascript
-// input.graphql
-query Input {
-  cart {
-    lines {
-      quantity
-      merchandise {
-        ... on ProductVariant {
-          product {
-            hasTag(tag: "bulk-discount")
-          }
-        }
-      }
-    }
-  }
-}
-
-// function.js
-export default function orderDiscount(input) {
-  const targets = input.cart.lines
-    .filter(line => line.merchandise.product.hasTag)
-    .map(line => ({
-      productVariant: { id: line.merchandise.id }
-    }));
-
-  if (targets.length === 0) {
-    return { discounts: [] };
-  }
-
-  return {
-    discounts: [{
-      targets,
-      value: {
-        percentage: {
-          value: 10  // 10% discount
-        }
-      }
-    }]
-  };
-}
-```
-
-### Payment Customization Function
-
-```javascript
-export default function paymentCustomization(input) {
-  const hidePaymentMethods = input.cart.lines.some(
-    line => line.merchandise.product.hasTag
-  );
-
-  if (!hidePaymentMethods) {
-    return { operations: [] };
-  }
-
-  return {
-    operations: [{
-      hide: {
-        paymentMethodId: "gid://shopify/PaymentMethod/123"
-      }
-    }]
-  };
-}
-```
-
-### Validation Function
-
-```javascript
-export default function cartValidation(input) {
-  const errors = [];
-
-  // Max 5 items per cart
-  if (input.cart.lines.length > 5) {
-    errors.push({
-      localizedMessage: "Maximum 5 items allowed per order",
-      target: "cart"
-    });
-  }
-
-  // Min $50 for wholesale
-  const isWholesale = input.cart.lines.some(
-    line => line.merchandise.product.hasTag
-  );
-
-  if (isWholesale && input.cart.cost.totalAmount.amount < 50) {
-    errors.push({
-      localizedMessage: "Wholesale orders require $50 minimum",
-      target: "cart"
-    });
-  }
-
-  return { errors };
-}
-```
-
-## Network Requests
-
-Extensions can call external APIs.
-
-```javascript
-import { useApi } from '@shopify/ui-extensions-react/checkout';
-
-function Extension() {
-  const { sessionToken } = useApi();
-
-  async function fetchData() {
-    const token = await sessionToken.get();
-
-    const response = await fetch('https://your-app.com/api/data', {
-      headers: {
-        'Authorization': `Bearer ${token}`,
-        'Content-Type': 'application/json'
-      }
-    });
-
-    return await response.json();
-  }
-}
-```
-
-## Best Practices
-
-**Performance:**
-- Lazy load data
-- Memoize expensive computations
-- Use loading states
-- Minimize re-renders
-
-**UX:**
-- Provide clear error messages
-- Show loading indicators
-- Validate inputs
-- Support keyboard navigation
-
-**Security:**
-- Verify session tokens on backend
-- Sanitize user input
-- Use HTTPS for all requests
-- Don't expose sensitive data
-
-**Testing:**
-- Test on development stores
-- Verify mobile/desktop
-- Check accessibility
-- Test edge cases
-
-## Resources
-
-- Checkout Extensions: https://shopify.dev/docs/api/checkout-extensions
-- Admin Extensions: https://shopify.dev/docs/apps/admin/extensions
-- Functions: https://shopify.dev/docs/apps/functions
-- Components: https://shopify.dev/docs/api/checkout-ui-extensions/components
+# Extensions Reference
+
+Guide for building UI extensions and Shopify Functions.
+
+## Checkout UI Extensions
+
+Customize checkout and thank-you pages with native-rendered components.
+
+### Extension Points
+
+**Block Targets (Merchant-Configurable):**
+- `purchase.checkout.block.render` - Main checkout
+- `purchase.thank-you.block.render` - Thank you page
+
+**Static Targets (Fixed Position):**
+- `purchase.checkout.header.render-after`
+- `purchase.checkout.contact.render-before`
+- `purchase.checkout.shipping-option-list.render-after`
+- `purchase.checkout.payment-method-list.render-after`
+- `purchase.checkout.footer.render-before`
+
+### Setup
+
+```bash
+shopify app generate extension --type checkout_ui_extension
+```
+
+Configuration (`shopify.extension.toml`):
+```toml
+api_version = "2025-01"
+name = "gift-message"
+type = "ui_extension"
+
+[[extensions.targeting]]
+target = "purchase.checkout.block.render"
+
+[capabilities]
+network_access = true
+api_access = true
+```
+
+### Basic Example
+
+```javascript
+import { reactExtension, BlockStack, TextField, Checkbox, useApi } from '@shopify/ui-extensions-react/checkout';
+
+export default reactExtension('purchase.checkout.block.render', () => <Extension />);
+
+function Extension() {
+  const [message, setMessage] = useState('');
+  const [isGift, setIsGift] = useState(false);
+  const { applyAttributeChange } = useApi();
+
+  useEffect(() => {
+    if (isGift) {
+      applyAttributeChange({
+        type: 'updateAttribute',
+        key: 'gift_message',
+        value: message
+      });
+    }
+  }, [message, isGift]);
+
+  return (
+    <BlockStack spacing="loose">
+      <Checkbox checked={isGift} onChange={setIsGift}>
+        This is a gift
+      </Checkbox>
+      {isGift && (
+        <TextField
+          label="Gift Message"
+          value={message}
+          onChange={setMessage}
+          multiline={3}
+        />
+      )}
+    </BlockStack>
+  );
+}
+```
+
+### Common Hooks
+
+**useApi:**
+```javascript
+const { extensionPoint, shop, storefront, i18n, sessionToken } = useApi();
+```
+
+**useCartLines:**
+```javascript
+const lines = useCartLines();
+lines.forEach(line => {
+  console.log(line.merchandise.product.title, line.quantity);
+});
+```
+
+**useShippingAddress:**
+```javascript
+const address = useShippingAddress();
+console.log(address.city, address.countryCode);
+```
+
+**useApplyCartLinesChange:**
+```javascript
+const applyChange = useApplyCartLinesChange();
+
+async function addItem() {
+  await applyChange({
+    type: 'addCartLine',
+    merchandiseId: 'gid://shopify/ProductVariant/123',
+    quantity: 1
+  });
+}
+```
+
+### Core Components
+
+**Layout:**
+- `BlockStack` - Vertical stacking
+- `InlineStack` - Horizontal layout
+- `Grid`, `GridItem` - Grid layout
+- `View` - Container
+- `Divider` - Separator
+
+**Input:**
+- `TextField` - Text input
+- `Checkbox` - Boolean
+- `Select` - Dropdown
+- `DatePicker` - Date selection
+- `Form` - Form wrapper
+
+**Display:**
+- `Text`, `Heading` - Typography
+- `Banner` - Messages
+- `Badge` - Status
+- `Image` - Images
+- `Link` - Hyperlinks
+- `List`, `ListItem` - Lists
+
+**Interactive:**
+- `Button` - Actions
+- `Modal` - Overlays
+- `Pressable` - Click areas
+
+## Admin UI Extensions
+
+Extend Shopify admin interface.
+
+### Admin Action
+
+Custom actions on resource pages.
+
+```bash
+shopify app generate extension --type admin_action
+```
+
+```javascript
+import { reactExtension, AdminAction, Button } from '@shopify/ui-extensions-react/admin';
+
+export default reactExtension('admin.product-details.action.render', () => <Extension />);
+
+function Extension() {
+  const { data } = useData();
+
+  async function handleExport() {
+    const response = await fetch('/api/export', {
+      method: 'POST',
+      body: JSON.stringify({ productId: data.product.id })
+    });
+    console.log('Exported:', await response.json());
+  }
+
+  return (
+    <AdminAction
+      title="Export Product"
+      primaryAction={<Button onPress={handleExport}>Export</Button>}
+    />
+  );
+}
+```
+
+**Targets:**
+- `admin.product-details.action.render`
+- `admin.order-details.action.render`
+- `admin.customer-details.action.render`
+
+### Admin Block
+
+Embedded content in admin pages.
+
+```javascript
+import { reactExtension, BlockStack, Text, Badge } from '@shopify/ui-extensions-react/admin';
+
+export default reactExtension('admin.product-details.block.render', () => <Extension />);
+
+function Extension() {
+  const { data } = useData();
+  const [analytics, setAnalytics] = useState(null);
+
+  useEffect(() => {
+    fetchAnalytics(data.product.id).then(setAnalytics);
+  }, []);
+
+  return (
+    <BlockStack>
+      <Text variant="headingMd">Product Analytics</Text>
+      <Text>Views: {analytics?.views || 0}</Text>
+      <Text>Conversions: {analytics?.conversions || 0}</Text>
+      <Badge tone={analytics?.trending ? "success" : "info"}>
+        {analytics?.trending ? "Trending" : "Normal"}
+      </Badge>
+    </BlockStack>
+  );
+}
+```
+
+**Targets:**
+- `admin.product-details.block.render`
+- `admin.order-details.block.render`
+- `admin.customer-details.block.render`
+
+## POS UI Extensions
+
+Customize Point of Sale experience.
+
+### Smart Grid Tile
+
+Quick access action on POS home screen.
+
+```javascript
+import { reactExtension, SmartGridTile } from '@shopify/ui-extensions-react/pos';
+
+export default reactExtension('pos.home.tile.render', () => <Extension />);
+
+function Extension() {
+  function handlePress() {
+    // Navigate to custom workflow
+  }
+
+  return (
+    <SmartGridTile
+      title="Gift Cards"
+      subtitle="Manage gift cards"
+      onPress={handlePress}
+    />
+  );
+}
+```
+
+### POS Modal
+
+Full-screen workflow.
+
+```javascript
+import { reactExtension, Screen, BlockStack, Button, TextField } from '@shopify/ui-extensions-react/pos';
+
+export default reactExtension('pos.home.modal.render', () => <Extension />);
+
+function Extension() {
+  const { navigation } = useApi();
+  const [amount, setAmount] = useState('');
+
+  function handleIssue() {
+    // Issue gift card
+    navigation.pop();
+  }
+
+  return (
+    <Screen name="Gift Card" title="Issue Gift Card">
+      <BlockStack>
+        <TextField label="Amount" value={amount} onChange={setAmount} />
+        <TextField label="Recipient Email" />
+        <Button onPress={handleIssue}>Issue</Button>
+      </BlockStack>
+    </Screen>
+  );
+}
+```
+
+## Customer Account Extensions
+
+Customize customer account pages.
+
+### Order Status Extension
+
+```javascript
+import { reactExtension, BlockStack, Text, Button } from '@shopify/ui-extensions-react/customer-account';
+
+export default reactExtension('customer-account.order-status.block.render', () => <Extension />);
+
+function Extension() {
+  const { order } = useApi();
+
+  function handleReturn() {
+    // Initiate return
+  }
+
+  return (
+    <BlockStack>
+      <Text variant="headingMd">Need to return?</Text>
+      <Text>Start return for order {order.name}</Text>
+      <Button onPress={handleReturn}>Start Return</Button>
+    </BlockStack>
+  );
+}
+```
+
+**Targets:**
+- `customer-account.order-status.block.render`
+- `customer-account.order-index.block.render`
+- `customer-account.profile.block.render`
+
+## Shopify Functions
+
+Serverless backend customization.
+
+### Function Types
+
+**Discounts:**
+- `order_discount` - Order-level discounts
+- `product_discount` - Product-specific discounts
+- `shipping_discount` - Shipping discounts
+
+**Payment Customization:**
+- Hide/rename/reorder payment methods
+
+**Delivery Customization:**
+- Custom shipping options
+- Delivery rules
+
+**Validation:**
+- Cart validation rules
+- Checkout validation
+
+### Create Function
+
+```bash
+shopify app generate extension --type function
+```
+
+### Order Discount Function
+
+```javascript
+// input.graphql
+query Input {
+  cart {
+    lines {
+      quantity
+      merchandise {
+        ... on ProductVariant {
+          product {
+            hasTag(tag: "bulk-discount")
+          }
+        }
+      }
+    }
+  }
+}
+
+// function.js
+export default function orderDiscount(input) {
+  const targets = input.cart.lines
+    .filter(line => line.merchandise.product.hasTag)
+    .map(line => ({
+      productVariant: { id: line.merchandise.id }
+    }));
+
+  if (targets.length === 0) {
+    return { discounts: [] };
+  }
+
+  return {
+    discounts: [{
+      targets,
+      value: {
+        percentage: {
+          value: 10  // 10% discount
+        }
+      }
+    }]
+  };
+}
+```
+
+### Payment Customization Function
+
+```javascript
+export default function paymentCustomization(input) {
+  const hidePaymentMethods = input.cart.lines.some(
+    line => line.merchandise.product.hasTag
+  );
+
+  if (!hidePaymentMethods) {
+    return { operations: [] };
+  }
+
+  return {
+    operations: [{
+      hide: {
+        paymentMethodId: "gid://shopify/PaymentMethod/123"
+      }
+    }]
+  };
+}
+```
+
+### Validation Function
+
+```javascript
+export default function cartValidation(input) {
+  const errors = [];
+
+  // Max 5 items per cart
+  if (input.cart.lines.length > 5) {
+    errors.push({
+      localizedMessage: "Maximum 5 items allowed per order",
+      target: "cart"
+    });
+  }
+
+  // Min $50 for wholesale
+  const isWholesale = input.cart.lines.some(
+    line => line.merchandise.product.hasTag
+  );
+
+  if (isWholesale && input.cart.cost.totalAmount.amount < 50) {
+    errors.push({
+      localizedMessage: "Wholesale orders require $50 minimum",
+      target: "cart"
+    });
+  }
+
+  return { errors };
+}
+```
+
+## Network Requests
+
+Extensions can call external APIs.
+
+```javascript
+import { useApi } from '@shopify/ui-extensions-react/checkout';
+
+function Extension() {
+  const { sessionToken } = useApi();
+
+  async function fetchData() {
+    const token = await sessionToken.get();
+
+    const response = await fetch('https://your-app.com/api/data', {
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json'
+      }
+    });
+
+    return await response.json();
+  }
+}
+```
+
+## Best Practices
+
+**Performance:**
+- Lazy load data
+- Memoize expensive computations
+- Use loading states
+- Minimize re-renders
+
+**UX:**
+- Provide clear error messages
+- Show loading indicators
+- Validate inputs
+- Support keyboard navigation
+
+**Security:**
+- Verify session tokens on backend
+- Sanitize user input
+- Use HTTPS for all requests
+- Don't expose sensitive data
+
+**Testing:**
+- Test on development stores
+- Verify mobile/desktop
+- Check accessibility
+- Test edge cases
+
+## Resources
+
+- Checkout Extensions: https://shopify.dev/docs/api/checkout-extensions
+- Admin Extensions: https://shopify.dev/docs/apps/admin/extensions
+- Functions: https://shopify.dev/docs/apps/functions
+- Components: https://shopify.dev/docs/api/checkout-ui-extensions/components