anchi-kit 1.2.0 → 1.2.2

package/.cursor/skills/shopify/references/app-development.md

@@ -1,470 +0,0 @@
-# App Development Reference
-
-Guide for building Shopify apps with OAuth, GraphQL/REST APIs, webhooks, and billing.
-
-## OAuth Authentication
-
-### OAuth 2.0 Flow
-
-**1. Redirect to Authorization URL:**
-```
-https://{shop}.myshopify.com/admin/oauth/authorize?
-  client_id={api_key}&
-  scope={scopes}&
-  redirect_uri={redirect_uri}&
-  state={nonce}
-```
-
-**2. Handle Callback:**
-```javascript
-app.get('/auth/callback', async (req, res) => {
-  const { code, shop, state } = req.query;
-
-  // Verify state to prevent CSRF
-  if (state !== storedState) {
-    return res.status(403).send('Invalid state');
-  }
-
-  // Exchange code for access token
-  const accessToken = await exchangeCodeForToken(shop, code);
-
-  // Store token securely
-  await storeAccessToken(shop, accessToken);
-
-  res.redirect(`https://${shop}/admin/apps/${appHandle}`);
-});
-```
-
-**3. Exchange Code for Token:**
-```javascript
-async function exchangeCodeForToken(shop, code) {
-  const response = await fetch(`https://${shop}/admin/oauth/access_token`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      client_id: process.env.SHOPIFY_API_KEY,
-      client_secret: process.env.SHOPIFY_API_SECRET,
-      code
-    })
-  });
-
-  const { access_token } = await response.json();
-  return access_token;
-}
-```
-
-### Access Scopes
-
-**Common Scopes:**
-- `read_products`, `write_products` - Product catalog
-- `read_orders`, `write_orders` - Order management
-- `read_customers`, `write_customers` - Customer data
-- `read_inventory`, `write_inventory` - Stock levels
-- `read_fulfillments`, `write_fulfillments` - Order fulfillment
-- `read_shipping`, `write_shipping` - Shipping rates
-- `read_analytics` - Store analytics
-- `read_checkouts`, `write_checkouts` - Checkout data
-
-Full list: https://shopify.dev/api/usage/access-scopes
-
-### Session Tokens (Embedded Apps)
-
-For embedded apps using App Bridge:
-
-```javascript
-import { getSessionToken } from '@shopify/app-bridge/utilities';
-
-async function authenticatedFetch(url, options = {}) {
-  const app = createApp({ ... });
-  const token = await getSessionToken(app);
-
-  return fetch(url, {
-    ...options,
-    headers: {
-      ...options.headers,
-      'Authorization': `Bearer ${token}`
-    }
-  });
-}
-```
-
-## GraphQL Admin API
-
-### Making Requests
-
-```javascript
-async function graphqlRequest(shop, accessToken, query, variables = {}) {
-  const response = await fetch(
-    `https://${shop}/admin/api/2025-01/graphql.json`,
-    {
-      method: 'POST',
-      headers: {
-        'X-Shopify-Access-Token': accessToken,
-        'Content-Type': 'application/json'
-      },
-      body: JSON.stringify({ query, variables })
-    }
-  );
-
-  const data = await response.json();
-
-  if (data.errors) {
-    throw new Error(`GraphQL errors: ${JSON.stringify(data.errors)}`);
-  }
-
-  return data.data;
-}
-```
-
-### Product Operations
-
-**Create Product:**
-```graphql
-mutation CreateProduct($input: ProductInput!) {
-  productCreate(input: $input) {
-    product {
-      id
-      title
-      handle
-    }
-    userErrors {
-      field
-      message
-    }
-  }
-}
-```
-
-Variables:
-```json
-{
-  "input": {
-    "title": "New Product",
-    "productType": "Apparel",
-    "vendor": "Brand",
-    "status": "ACTIVE",
-    "variants": [
-      { "price": "29.99", "sku": "SKU-001", "inventoryQuantity": 100 }
-    ]
-  }
-}
-```
-
-**Update Product:**
-```graphql
-mutation UpdateProduct($input: ProductInput!) {
-  productUpdate(input: $input) {
-    product { id title }
-    userErrors { field message }
-  }
-}
-```
-
-**Query Products:**
-```graphql
-query GetProducts($first: Int!, $query: String) {
-  products(first: $first, query: $query) {
-    edges {
-      node {
-        id
-        title
-        status
-        variants(first: 5) {
-          edges {
-            node { id price inventoryQuantity }
-          }
-        }
-      }
-    }
-    pageInfo { hasNextPage endCursor }
-  }
-}
-```
-
-### Order Operations
-
-**Query Orders:**
-```graphql
-query GetOrders($first: Int!) {
-  orders(first: $first) {
-    edges {
-      node {
-        id
-        name
-        createdAt
-        displayFinancialStatus
-        totalPriceSet {
-          shopMoney { amount currencyCode }
-        }
-        customer { email firstName lastName }
-      }
-    }
-  }
-}
-```
-
-**Fulfill Order:**
-```graphql
-mutation FulfillOrder($input: FulfillmentInput!) {
-  fulfillmentCreate(input: $input) {
-    fulfillment { id status trackingInfo { number url } }
-    userErrors { field message }
-  }
-}
-```
-
-## Webhooks
-
-### Configuration
-
-In `shopify.app.toml`:
-```toml
-[webhooks]
-api_version = "2025-01"
-
-[[webhooks.subscriptions]]
-topics = ["orders/create"]
-uri = "/webhooks/orders/create"
-
-[[webhooks.subscriptions]]
-topics = ["products/update"]
-uri = "/webhooks/products/update"
-
-[[webhooks.subscriptions]]
-topics = ["app/uninstalled"]
-uri = "/webhooks/app/uninstalled"
-
-# GDPR mandatory webhooks
-[webhooks.privacy_compliance]
-customer_data_request_url = "/webhooks/gdpr/data-request"
-customer_deletion_url = "/webhooks/gdpr/customer-deletion"
-shop_deletion_url = "/webhooks/gdpr/shop-deletion"
-```
-
-### Webhook Handler
-
-```javascript
-import crypto from 'crypto';
-
-function verifyWebhook(req) {
-  const hmac = req.headers['x-shopify-hmac-sha256'];
-  const body = req.rawBody; // Raw body buffer
-
-  const hash = crypto
-    .createHmac('sha256', process.env.SHOPIFY_API_SECRET)
-    .update(body, 'utf8')
-    .digest('base64');
-
-  return hmac === hash;
-}
-
-app.post('/webhooks/orders/create', async (req, res) => {
-  if (!verifyWebhook(req)) {
-    return res.status(401).send('Unauthorized');
-  }
-
-  const order = req.body;
-  console.log('New order:', order.id, order.name);
-
-  // Process order...
-
-  res.status(200).send('OK');
-});
-```
-
-### Common Webhook Topics
-
-**Orders:**
-- `orders/create`, `orders/updated`, `orders/delete`
-- `orders/paid`, `orders/cancelled`, `orders/fulfilled`
-
-**Products:**
-- `products/create`, `products/update`, `products/delete`
-
-**Customers:**
-- `customers/create`, `customers/update`, `customers/delete`
-
-**Inventory:**
-- `inventory_levels/update`
-
-**App:**
-- `app/uninstalled` (critical for cleanup)
-
-## Billing Integration
-
-### App Charges
-
-**One-time Charge:**
-```graphql
-mutation CreateCharge($input: AppPurchaseOneTimeInput!) {
-  appPurchaseOneTimeCreate(input: $input) {
-    appPurchaseOneTime {
-      id
-      name
-      price { amount }
-      status
-      confirmationUrl
-    }
-    userErrors { field message }
-  }
-}
-```
-
-Variables:
-```json
-{
-  "input": {
-    "name": "Premium Feature",
-    "price": { "amount": 49.99, "currencyCode": "USD" },
-    "returnUrl": "https://your-app.com/billing/callback"
-  }
-}
-```
-
-**Recurring Charge (Subscription):**
-```graphql
-mutation CreateSubscription($input: AppSubscriptionCreateInput!) {
-  appSubscriptionCreate(input: $input) {
-    appSubscription {
-      id
-      name
-      status
-      confirmationUrl
-    }
-    userErrors { field message }
-  }
-}
-```
-
-Variables:
-```json
-{
-  "input": {
-    "name": "Monthly Subscription",
-    "returnUrl": "https://your-app.com/billing/callback",
-    "lineItems": [
-      {
-        "plan": {
-          "appRecurringPricingDetails": {
-            "price": { "amount": 29.99, "currencyCode": "USD" },
-            "interval": "EVERY_30_DAYS"
-          }
-        }
-      }
-    ]
-  }
-}
-```
-
-**Usage-based Billing:**
-```graphql
-mutation CreateUsageCharge($input: AppUsageRecordCreateInput!) {
-  appUsageRecordCreate(input: $input) {
-    appUsageRecord {
-      id
-      price { amount }
-      description
-    }
-    userErrors { field message }
-  }
-}
-```
-
-## Metafields
-
-### Create Metafield
-
-```graphql
-mutation CreateMetafield($input: MetafieldInput!) {
-  metafieldsSet(metafields: [$input]) {
-    metafields {
-      id
-      namespace
-      key
-      value
-    }
-    userErrors { field message }
-  }
-}
-```
-
-Variables:
-```json
-{
-  "input": {
-    "ownerId": "gid://shopify/Product/123",
-    "namespace": "custom",
-    "key": "instructions",
-    "value": "Handle with care",
-    "type": "single_line_text_field"
-  }
-}
-```
-
-**Metafield Types:**
-- `single_line_text_field`, `multi_line_text_field`
-- `number_integer`, `number_decimal`
-- `date`, `date_time`
-- `url`, `json`
-- `file_reference`, `product_reference`
-
-## Rate Limiting
-
-### GraphQL Cost-Based Limits
-
-**Limits:**
-- Available points: 2000
-- Restore rate: 100 points/second
-- Max query cost: 2000
-
-**Check Cost:**
-```javascript
-const response = await graphqlRequest(shop, token, query);
-const cost = response.extensions?.cost;
-
-console.log(`Cost: ${cost.actualQueryCost}/${cost.throttleStatus.maximumAvailable}`);
-```
-
-**Handle Throttling:**
-```javascript
-async function graphqlWithRetry(shop, token, query, retries = 3) {
-  for (let i = 0; i < retries; i++) {
-    try {
-      return await graphqlRequest(shop, token, query);
-    } catch (error) {
-      if (error.message.includes('Throttled') && i < retries - 1) {
-        await sleep(Math.pow(2, i) * 1000); // Exponential backoff
-        continue;
-      }
-      throw error;
-    }
-  }
-}
-```
-
-## Best Practices
-
-**Security:**
-- Store credentials in environment variables
-- Verify webhook HMAC signatures
-- Validate OAuth state parameter
-- Use HTTPS for all endpoints
-- Implement rate limiting on your endpoints
-
-**Performance:**
-- Cache access tokens securely
-- Use bulk operations for large datasets
-- Implement pagination for queries
-- Monitor GraphQL query costs
-
-**Reliability:**
-- Implement exponential backoff for retries
-- Handle webhook delivery failures
-- Log errors for debugging
-- Monitor app health metrics
-
-**Compliance:**
-- Implement GDPR webhooks (mandatory)
-- Handle customer data deletion requests
-- Provide data export functionality
-- Follow data retention policies