Add docs/storefront-api.md

docs/storefront-api.md

@@ -0,0 +1,84 @@
+# Storefront API Sync
+
+The NotShop bundle uses the Shopify Storefront API to pull your product catalog during migration. It is **public and read-only** — no admin credentials required, cannot modify your Shopify store.
+
+---
+
+## Step 1: Create a Storefront API token
+
+1. Log into Shopify Admin
+2. Go to **Settings → Apps and sales channels → Develop apps**
+3. Create or select a headless app
+4. Under **Configuration → Storefront API access**, enable:
+   - `unauthenticated_read_product_listings`
+   - `unauthenticated_read_product_inventory`
+   - `unauthenticated_read_collection_listings`
+   - `unauthenticated_read_customers`
+   - `unauthenticated_read_checkouts`
+5. Save → Install app → Copy the **Storefront API access token**
+
+---
+
+## Step 2: Add to your environment
+
+In `.env` (or Replit Secrets):
+
+```
+SHOPIFY_STOREFRONT_TOKEN=your_access_token_here
+SHOPIFY_STORE_DOMAIN=yourstore.myshopify.com
+```
+
+---
+
+## Step 3: Run the catalog import
+
+```bash
+npm run catalog:import
+```
+
+### What gets imported
+
+| Data | Stored as |
+|---|---|
+| Products | `products` table |
+| Variants | `product_variants` table |
+| Collections | `collections` table |
+| Product images | `image_url` column (CDN URL reference) |
+| Inventory | `in_stock` boolean |
+
+### What is NOT imported
+
+- Customer purchase history
+- Order history (export from Shopify Admin as CSV before cancellation)
+- Draft orders
+- Cost prices
+
+---
+
+## Step 4: Keep catalog in sync during migration
+
+Re-run `npm run catalog:import` anytime. For real-time sync, register a Shopify webhook:
+
+- Topic: `products/update`
+- URL: `https://yourstore.com/webhooks/shopify/product-updated`
+
+Handler: `server/webhook-bridge.ts`
+
+---
+
+## API endpoint
+
+```
+POST https://{SHOPIFY_STORE_DOMAIN}/api/2024-01/graphql.json
+X-Shopify-Storefront-Access-Token: {SHOPIFY_STOREFRONT_TOKEN}
+```
+
+---
+
+## Troubleshooting
+
+**"Unauthorized"** — Check the token is set correctly and the app is installed.
+
+**Empty product list** — Ensure products are published to the Online Store channel in Shopify Admin.
+
+**Images stop loading after cancellation** — Shopify CDN URLs expire after account closure. Migrate images to Bunny.net or Vultr Object Storage before cancelling. Script: `npm run migrate:images`.