@veyralabs/skills 0.3.0 → 0.4.0

package/skills/shopify-suite/shopify-dev/references/app-architecture.md

@@ -0,0 +1,322 @@
+# App Architecture — shopify-dev Reference
+
+Decisions and patterns for Shopify app structure, auth, billing, and production readiness.
+
+---
+
+## Tech Stack (2025+)
+
+Shopify's recommended stack for new apps:
+
+| Layer | Tech |
+|-------|------|
+| Framework | Remix (replaces Express) |
+| UI | Polaris + App Bridge |
+| ORM | Prisma (SQLite dev, Postgres prod) |
+| Auth | OAuth client credentials (Dev Dashboard) |
+| Hosting | Fly.io, Railway, Vercel, Render |
+| Extensions | Checkout UI, Admin UI, Web Pixel |
+
+---
+
+## Project Structure
+
+```
+my-shopify-app/
+├── app/
+│   ├── routes/
+│   │   ├── app._index.tsx       ← main embedded page
+│   │   ├── app.products.tsx     ← products feature page
+│   │   ├── app.settings.tsx     ← settings
+│   │   ├── webhooks.tsx         ← webhook receiver
+│   │   └── auth.$.tsx           ← Shopify OAuth flow (auto-generated)
+│   ├── shopify.server.ts        ← auth config, API client
+│   ├── db.server.ts             ← Prisma client singleton
+│   └── root.tsx                 ← App wrapper with AppProvider
+├── extensions/
+│   └── checkout-ui/             ← checkout extension (if any)
+├── prisma/
+│   ├── schema.prisma
+│   └── migrations/
+├── .env                         ← never commit
+├── shopify.app.toml             ← app config for CLI
+└── remix.config.js
+```
+
+---
+
+## Authentication
+
+### How it works (OAuth client credentials, 2025+)
+
+1. Merchant installs app from App Store / Dev Dashboard
+2. Shopify redirects to your `/auth` route with shop domain
+3. Your app redirects to Shopify OAuth screen
+4. Merchant approves — Shopify redirects back with authorization code
+5. Your app exchanges code for session token
+6. Session stored in DB (per-shop)
+
+All this is handled by `@shopify/shopify-app-remix` — you don't implement it manually.
+
+### shopify.server.ts pattern
+
+```typescript
+import "@shopify/shopify-app-remix/adapters/node";
+import {
+  AppDistribution,
+  shopifyApp,
+  LATEST_API_VERSION,
+} from "@shopify/shopify-app-remix/server";
+import { PrismaSessionStorage } from "@shopify/shopify-app-session-storage-prisma";
+import { PrismaClient } from "@prisma/client";
+
+const prisma = new PrismaClient();
+
+const shopify = shopifyApp({
+  apiKey: process.env.SHOPIFY_API_KEY,
+  apiSecretKey: process.env.SHOPIFY_API_SECRET || "",
+  apiVersion: LATEST_API_VERSION,
+  scopes: process.env.SCOPES?.split(","),
+  appUrl: process.env.SHOPIFY_APP_URL || "",
+  authPathPrefix: "/auth",
+  sessionStorage: new PrismaSessionStorage(prisma),
+  distribution: AppDistribution.AppStore,
+});
+
+export default shopify;
+export const apiVersion = LATEST_API_VERSION;
+export const addDocumentResponseHeaders = shopify.addDocumentResponseHeaders;
+export const authenticate = shopify.authenticate;
+export const unauthenticated = shopify.unauthenticated;
+export const login = shopify.login;
+export const registerWebhooks = shopify.registerWebhooks;
+export const sessionStorage = shopify.sessionStorage;
+```
+
+### Using auth in routes
+
+```typescript
+// Embedded page (inside Shopify admin)
+export const loader = async ({ request }) => {
+  const { admin, session } = await authenticate.admin(request);
+  // admin.graphql() for API calls
+  // session.shop = "store-name.myshopify.com"
+};
+
+// Webhook (not embedded — different auth method)
+export const action = async ({ request }) => {
+  const { shop, topic, payload } = await authenticate.webhook(request);
+};
+
+// Public (no auth — for storefront-facing APIs)
+export const loader = async ({ request }) => {
+  const { storefront } = await unauthenticated.storefront("store.myshopify.com");
+};
+```
+
+---
+
+## Database
+
+### Prisma schema for session storage
+
+```prisma
+model Session {
+  id          String    @id
+  shop        String
+  state       String
+  isOnline    Boolean   @default(false)
+  scope       String?
+  expires     DateTime?
+  accessToken String
+  userId      BigInt?
+  firstName   String?
+  lastName    String?
+  email       String?
+  accountOwner Boolean  @default(false)
+  locale      String?
+  collaborator Boolean? @default(false)
+  emailVerified Boolean? @default(false)
+}
+```
+
+### App data example (products table)
+
+```prisma
+model ProductSetting {
+  id          String  @id @default(uuid())
+  shop        String
+  productId   String
+  badgeText   String?
+  isHidden    Boolean @default(false)
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  @@unique([shop, productId])
+}
+```
+
+### Dev vs prod DB
+
+- Dev: SQLite (zero setup, file-based)
+- Prod: Postgres (Railway, Supabase, PlanetScale)
+
+Switch in `prisma/schema.prisma`:
+```prisma
+datasource db {
+  provider = "postgresql"  // "sqlite" for dev
+  url      = env("DATABASE_URL")
+}
+```
+
+---
+
+## Billing
+
+Shopify billing API requires app to charge via Shopify (mandatory for App Store apps).
+
+### Create a subscription
+
+```typescript
+export const loader = async ({ request }) => {
+  const { billing } = await authenticate.admin(request);
+
+  const { hasActivePayment, appSubscriptions } = await billing.check({
+    plans: ["Basic Plan"],
+    isTest: process.env.NODE_ENV !== "production",
+  });
+
+  if (!hasActivePayment) {
+    await billing.request({
+      plan: "Basic Plan",
+      isTest: process.env.NODE_ENV !== "production",
+      returnUrl: `${process.env.SHOPIFY_APP_URL}/app`,
+    });
+  }
+};
+```
+
+### Define plans in shopify.server.ts
+
+```typescript
+const shopify = shopifyApp({
+  // ...existing config...
+  billing: {
+    "Basic Plan": {
+      amount: 9.99,
+      currencyCode: "USD",
+      interval: BillingInterval.Monthly,
+    },
+    "Pro Plan": {
+      amount: 29.99,
+      currencyCode: "USD",
+      interval: BillingInterval.Monthly,
+    },
+  },
+});
+```
+
+### Check subscription status in any route
+
+```typescript
+const { billing } = await authenticate.admin(request);
+const { hasActivePayment } = await billing.check({ plans: ["Pro Plan"] });
+
+if (!hasActivePayment) {
+  return redirect("/app/upgrade");
+}
+```
+
+---
+
+## Webhooks
+
+### Register in shopify.app.toml
+
+```toml
+[[webhooks.subscriptions]]
+topics = ["products/update", "products/delete"]
+uri = "/webhooks"
+
+[[webhooks.subscriptions]]
+topics = ["app/uninstalled"]
+uri = "/webhooks"
+```
+
+Or register programmatically:
+
+```typescript
+// root.tsx or entry point
+import { registerWebhooks } from "./shopify.server";
+
+export const action = async ({ request }) => {
+  const { topic, shop } = await authenticate.webhook(request);
+  await registerWebhooks({ session });
+};
+```
+
+### Webhook handler
+
+```typescript
+// app/routes/webhooks.tsx
+export const action = async ({ request }) => {
+  const { topic, shop, session, admin, payload } =
+    await authenticate.webhook(request);
+
+  if (!admin && topic !== "APP_UNINSTALLED") {
+    throw new Response();
+  }
+
+  switch (topic) {
+    case "APP_UNINSTALLED":
+      if (session) {
+        await db.session.deleteMany({ where: { shop } });
+      }
+      break;
+
+    case "PRODUCTS_UPDATE":
+      await syncProduct(shop, payload);
+      break;
+
+    default:
+      throw new Response("Unhandled webhook topic", { status: 404 });
+  }
+
+  return new Response();
+};
+```
+
+---
+
+## Production Checklist
+
+Before submitting to App Store:
+
+- [ ] `LATEST_API_VERSION` set and updated quarterly
+- [ ] Webhooks registered for `APP_UNINSTALLED`, `CUSTOMERS_DATA_REQUEST`, `CUSTOMERS_REDACT`, `SHOP_REDACT` (GDPR — mandatory)
+- [ ] Billing implemented if charging merchants
+- [ ] Session storage uses Postgres (not SQLite)
+- [ ] All Admin API calls handle `userErrors`
+- [ ] Rate limit handling: retry on 429 with exponential backoff
+- [ ] App URL set in `.env` and `shopify.app.toml`
+- [ ] Polaris `AppProvider` wraps entire app with i18n translations
+- [ ] No API keys or secrets in client-side code
+- [ ] App passes Shopify's built-in review checklist (run `shopify app build` and check output)
+
+---
+
+## Rate Limits
+
+Shopify Admin GraphQL: 1000 points/second per store.
+
+Query cost: each field costs 1 point; connections multiply by requested count.
+`products(first: 250)` = ~250 points. `products.variants.metafields` = ~250 × 250.
+
+```typescript
+// Check cost in response headers
+const response = await admin.graphql(QUERY);
+const headers = response.headers;
+// X-Shopify-Shop-Api-Call-Limit: used/max
+```
+
+For bulk operations (catalog exports, large migrations), use `bulkOperationRunQuery` — no rate limits.

package/skills/shopify-suite/shopify-dev/references/cli-workflows.md

@@ -0,0 +1,257 @@
+# CLI Workflows — shopify-dev Reference
+
+Shopify CLI commands for theme and app development. Verified against CLI 3.x.
+
+---
+
+## Installation
+
+```bash
+npm install -g @shopify/cli@latest
+shopify version
+```
+
+Requires Node 18+. Authentication is store-scoped (you authenticate per store).
+
+---
+
+## Theme Development
+
+### Basic workflow
+
+```bash
+# Authenticate and pull from live theme
+shopify theme dev --store your-store.myshopify.com
+
+# Start dev server on specific theme
+shopify theme dev --store your-store.myshopify.com --theme THEME_ID
+
+# Check what themes exist
+shopify theme list --store your-store.myshopify.com
+
+# Pull theme files to local
+shopify theme pull --store your-store.myshopify.com --theme THEME_ID
+
+# Push to a specific theme (NOT live — always push to unpublished theme first)
+shopify theme push --store your-store.myshopify.com --theme THEME_ID
+
+# Push to new theme (creates it)
+shopify theme push --unpublished --store your-store.myshopify.com
+
+# Publish a theme (makes it live)
+shopify theme publish --store your-store.myshopify.com --theme THEME_ID
+```
+
+### Targeting specific files
+
+```bash
+# Push only changed files
+shopify theme push --only sections/header.liquid
+
+# Ignore files during push/pull
+shopify theme push --ignore "config/settings_data.json"
+shopify theme pull --ignore "templates/*.json"
+```
+
+### Multiple environments
+
+Define in `shopify.theme.toml`:
+
+```toml
+[environments.development]
+store = "dev-store.myshopify.com"
+theme = "123456789"
+ignore = ["config/settings_data.json"]
+
+[environments.staging]
+store = "staging-store.myshopify.com"
+theme = "987654321"
+
+[environments.production]
+store = "prod-store.myshopify.com"
+theme = "111111111"
+```
+
+Then:
+```bash
+shopify theme dev --environment development
+shopify theme push --environment staging
+shopify theme push --environment production
+```
+
+### Check for errors
+
+```bash
+shopify theme check
+shopify theme check --output json
+
+# Check specific files
+shopify theme check sections/product-form.liquid
+```
+
+`theme check` validates Liquid syntax, section schemas, deprecated filters, accessibility issues.
+
+---
+
+## App Development
+
+### Scaffold a new app
+
+```bash
+npm init @shopify/app@latest
+# Prompts: app name, template (Remix recommended), language (TypeScript or JS)
+cd my-app
+npm install
+```
+
+### Start dev server
+
+```bash
+shopify app dev
+# Starts: local server + tunnel (Cloudflare ngrok) + updates app URLs in Dev Dashboard
+```
+
+Dev server requirements:
+- Authenticated Shopify Partner/Dev Dashboard account
+- App created in Dev Dashboard (first run prompts you to create)
+- `.shopify/project.toml` created automatically on first `dev`
+
+### Environment config
+
+`.env` file (auto-created, never commit):
+```
+SHOPIFY_API_KEY=your-client-id
+SHOPIFY_API_SECRET=your-client-secret
+SCOPES=write_products,read_orders
+```
+
+### Deploy to production
+
+```bash
+shopify app deploy
+# Builds, runs type check, deploys extensions to Shopify
+# Does NOT deploy the web server — deploy that to Vercel/Railway/etc.
+```
+
+### Generate extension scaffold
+
+```bash
+# Checkout UI extension
+shopify app generate extension --type checkout_ui_extension
+
+# Product subscription
+shopify app generate extension --type product_subscription
+
+# Admin action
+shopify app generate extension --type admin_action
+
+# Web pixel
+shopify app generate extension --type web_pixel_extension
+```
+
+### App info
+
+```bash
+shopify app info
+# Shows: app name, client ID, extensions, deployment status
+```
+
+---
+
+## Authentication
+
+```bash
+# Login to a store
+shopify auth login --store your-store.myshopify.com
+
+# Check current auth status
+shopify auth status
+
+# Logout
+shopify auth logout
+```
+
+First `shopify app dev` or `shopify theme dev` on a new machine prompts for auth.
+
+---
+
+## Useful Flags
+
+| Flag | Command | What it does |
+|------|---------|-------------|
+| `--store` | theme | Target store domain |
+| `--theme THEME_ID` | theme | Target specific theme |
+| `--environment` | theme | Use environment from .toml |
+| `--only file.liquid` | theme push/pull | Scope to specific files |
+| `--ignore "pattern"` | theme push/pull | Exclude files |
+| `--unpublished` | theme push | Create new unpublished theme |
+| `--live` | theme push | Push to currently active theme |
+| `--json` | most commands | Machine-readable output |
+| `--verbose` | most commands | Debug output |
+
+---
+
+## CI/CD Pattern
+
+### GitHub Actions — theme deploy
+
+```yaml
+name: Deploy Theme
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - name: Install Shopify CLI
+        run: npm install -g @shopify/cli@latest
+
+      - name: Deploy to staging
+        env:
+          SHOPIFY_CLI_THEME_TOKEN: ${{ secrets.SHOPIFY_CLI_THEME_TOKEN }}
+        run: |
+          shopify theme push \
+            --store ${{ secrets.SHOPIFY_STORE }} \
+            --theme ${{ secrets.STAGING_THEME_ID }} \
+            --allow-live \
+            --no-color
+```
+
+Generate `SHOPIFY_CLI_THEME_TOKEN`:
+1. Shopify Admin → Settings → Apps and sales channels → Develop apps
+2. Create app with `write_themes` scope
+3. Get Admin API access token
+
+### GitHub Actions — app deploy extensions
+
+```yaml
+- name: Deploy app extensions
+  env:
+    SHOPIFY_API_KEY: ${{ secrets.SHOPIFY_API_KEY }}
+    SHOPIFY_API_SECRET: ${{ secrets.SHOPIFY_API_SECRET }}
+  run: shopify app deploy --no-release
+```
+
+---
+
+## Common Errors
+
+**`Error: No store provided`** — add `--store` flag or set in `shopify.theme.toml`
+
+**`Error: Theme not found`** — wrong THEME_ID. Run `shopify theme list` to get correct ID.
+
+**`Error: Cannot push to live theme`** — use `--allow-live` flag explicitly, or push to unpublished theme first.
+
+**`Error: SHOPIFY_CLI_THEME_TOKEN not set`** — CI/CD needs token. See token generation above.
+
+**`Error: Extensions failed to deploy`** — check extension `shopify.extension.toml` for schema errors. Run `shopify app generate extension` again if structure is corrupted.