gitignore: ignore all .env.* files, not just .env

.env.dev (used for local dev config, see AGENTS.md's DEV_AUTH_ENABLED
setup) was showing up as untracked instead of being ignored like .env.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.gitignore

@@ -4,4 +4,5 @@
 node_modules
 
 .env
+.env.*
 .env.example

AGENTS.md

@@ -7,6 +7,78 @@ Wix, WooCommerce, Zoho) exists only as a **mock simulation layer** used for
 development, demos, and testing the sync/reporting logic without needing
 real store credentials. See `README.md` for the product-level roadmap.
 
+## Platform integration priority
+
+When picking the next mock platform to turn into a real integration (after
+Etsy), use this weighted ranking of the 12 not-yet-live mock platforms. It
+scores each on GMV/market opportunity (45%), API/inventory-sync completeness
+(30%), growth trajectory (15%), and integration cost (10%) - see
+`STORE_API_RESEARCH.md`'s "Weighted priority ranking" section for the full
+scoring table, per-criterion reasoning, and the market-size/API research
+it's built on.
+
+1. **Shopify** (9.15/10) - cleanest/most complete API (webhooks for both
+   order and inventory events, modern GraphQL), still-strong GMV growth
+   (+29-35% YoY), and a proven self-serve distribution channel (the Shopify
+   App Store, where inventory-sync apps are an established category) that
+   no other platform here has an equivalent of.
+2. **Amazon** (8.85/10) - largest raw dollar opportunity (~$575B in 2025
+   third-party GMV), and inventory-sync pain (suppressed listings, FBA
+   stranded-inventory fees) is one of the sharpest problems this tool could
+   solve there. `domains/amazon` already has the most real infrastructure
+   of any mock platform (the `ProcessEvents` LISTEN/NOTIFY loop, SSE
+   wiring), so a real SP-API integration reuses that instead of starting
+   from zero. Scores lower than Shopify mainly because SP-API auth (LWA +
+   AWS SigV4) and rate limiting are the most complex of any platform here,
+   and seller growth has gone flat.
+3. **Tiktok Shop** (7.15/10) - hypergrowth (global GMV nearly doubled in
+   2025, projected to double again in 2026) is what earns it this spot, but
+   its API details are the least confirmed of anything researched -
+   `partner.tiktokshop.com` didn't yield readable docs during this pass.
+   Needs a dedicated research pass to confirm exact webhook/endpoint names
+   before treating this ranking as actionable.
+4. **Walmart Marketplace** (6.35/10) - smaller in absolute GMV than the top
+   three, but growing ~50% YoY and a natural second-marketplace target for
+   sellers already on Amazon; full order+inventory webhook coverage.
+5. **Wix** (6.35/10) - tied with Walmart on score but behind it on the
+   growth tiebreaker; full inventory-webhook coverage and an easy API, just
+   a smaller/less certain GMV number.
+6. **WooCommerce** (5.95/10) - large store count (~4-6M) but no
+   platform-wide GMV figure exists (self-hosted plugin, no central ledger),
+   and no dedicated inventory webhook (relies on a `product.updated` proxy).
+7. **Square Online** (5.90/10) - full inventory-webhook coverage and
+   well-documented APIs (shared with the rest of Square's product line),
+   but its ecommerce-specific GMV can't be isolated from Square's much
+   larger in-person POS business.
+8. **Ebay** (5.75/10) - most sellers of any platform here (18.3M) but the
+   lowest GMV-per-seller by far, plus no dedicated inventory-change webhook.
+9. **Squarespace** (4.75/10) - smaller GMV, no inventory webhook.
+10. **Zoho** (3.85/10) - tiny confirmed store count (~2,196 globally).
+11. **Ecwid** (3.20/10) - shrinking (-20% YoY store count).
+12. **Big Cartel** (1.50/10) - last, and not close: no inventory API or
+    webhook at all is a structural dealbreaker for this tool's core use
+    case, independent of its (also declining, -41% YoY) market size.
+
+(BigCommerce, which appears in the API-capability table in
+`STORE_API_RESEARCH.md`, is excluded here - it isn't one of this codebase's
+actual mock platforms; that table predates the platform list settling on
+Tiktok instead.)
+
+Etsy isn't in the ranking above (it's already built), but scores 3.85/10 as
+a reference point if run through the same rubric - mid-pack-and-declining
+GMV, and the *only* platform researched with zero webhook/push support of
+any kind (order or inventory - confirmed directly against
+`domains/platforms/etsy/generated_client`, not external docs). That's not a
+retroactive case against having built Etsy - it was presumably chosen for
+reasons this rubric doesn't score (an existing relationship, an easier path
+to developer credentials) - but it's a reminder that the lack of any
+webhook system makes real order/inventory sync a polling loop, which is
+exactly the kind of integration cost this rubric undercounts once a
+platform is more than superficially wired up. Note also that the OAuth
+connection flow is the only part of Etsy that's actually built so far
+(`domains/platforms/etsy/etsy.go`) - polling-based receipt/inventory sync
+against the live API doesn't exist yet.
+
 ## Setup
 
 1. Postgres running locally, with an `app_client` role/database matching

STORE_API_RESEARCH.md

@@ -6,6 +6,7 @@ https://docs.google.com/spreadsheets/d/1xWfXn-wbiHTBeqyhnq0b46_sgLGyiYc_5N5mXKYD
 
 | Platform | Order Event: placed | Order Event: changed | Products List | Products Look up | Inventory Look up | Inventory Update | Inventory Event: change |
 |----------|----------|----------|----------|----------|----------|----------|----------|
+| **Etsy (live)** | N/A — no webhook/push system in API v3 at all; poll `GET /v3/application/shops/{shop_id}/receipts` (filter `min_created`) | poll same endpoint filtered by `min_last_modified` | `GET /v3/application/shops/{shop_id}/listings` | `GET /v3/application/listings/{listing_id}` | `GET /v3/application/listings/{listing_id}/inventory` | `PUT /v3/application/listings/{listing_id}/inventory` | N/A — no inventory-change webhook; poll the inventory endpoint |
 | Shopify | orders/create | orders/cancelled, orders/delete, orders/paid, etc  | /queries/products | /queries/product | /queries/product | /mutations/inventorySetQuantities | inventory_levels/update |
 | WooCommerce | webhook `order.created` | webhook `order.updated`, `order.deleted` | `GET /wp-json/wc/v3/products` | `GET /wp-json/wc/v3/products/<id>` | `stock_quantity` field on product resource | `PUT /wp-json/wc/v3/products/<id>` (stock_quantity), or `/products/batch` | `product.updated` (no dedicated inventory webhook) |
 | BigCommerce | webhook `store/order/created` | webhook `store/order/updated`, `store/order/statusUpdated` | `GET /v3/catalog/products` | `GET /v3/catalog/products/{product_id}` | `GET /v3/inventory/items` | `PUT /v3/inventory/adjustments/absolute` (also `/relative`) | `store/product/inventory/updated` |
@@ -23,6 +24,7 @@ https://docs.google.com/spreadsheets/d/1xWfXn-wbiHTBeqyhnq0b46_sgLGyiYc_5N5mXKYD
 
 | Platform | Docs | Webhooks | API |
 |----------|----------|----------|----------|
+| Etsy (live) | https://developer.etsy.com/documentation/ | N/A — no webhook/push mechanism exists in Etsy Open API v3 | https://developer.etsy.com/documentation/reference (confirmed directly against `domains/platforms/etsy/generated_client` in this repo, not external docs) |
 | Shopify | https://shopify.dev/docs/api | https://shopify.dev/docs/api/webhooks/latest?reference=toml | https://shopify.dev/docs/api/admin-graphql/latest |
 | WooCommerce | https://developer.woocommerce.com/docs/apis/rest-api/ | https://developer.woocommerce.com/docs/apis/rest-api/v2/webhooks/ | https://developer.woocommerce.com/docs/apis/rest-api/v3/products/ |
 | BigCommerce | https://developer.bigcommerce.com/docs | https://developer.bigcommerce.com/docs/integrations/webhooks/overview | https://developer.bigcommerce.com/docs/rest-catalog/products |
@@ -43,4 +45,165 @@ https://docs.google.com/spreadsheets/d/1xWfXn-wbiHTBeqyhnq0b46_sgLGyiYc_5N5mXKYD
 - **Big Cartel**: no true inventory API — only an `inventory_enabled` flag and `quantity_gte`/`quantity_lte` filters on products. No endpoint to set stock and no inventory-change webhook. Webhook access is gated per-app approval; exact topic names are inferred from integration examples since Big Cartel has no canonical published list.
 - **Amazon SP-API**: no separate "placed" vs "changed" order topics — both flow through a single `ORDER_CHANGE` notification, differentiated by payload content.
 - **WooCommerce / Ecwid**: neither has a dedicated inventory-change webhook; stock changes surface via the general `product.updated` event instead.
+- **Etsy**: the one row in the first table sourced from this repo's actual code rather than external docs (`domains/platforms/etsy/generated_client`, generated from Etsy's own OpenAPI spec) - so it's the most reliable row here, not the least. Etsy Open API v3 has no webhook/push system whatsoever for anything, order or inventory alike; every other platform in the table has at least *some* real-time push. The live integration in this repo currently only implements the OAuth connection flow (`GenerateConnectionURLForNewAccount`/`HandleNewAuthCode` in `domains/platforms/etsy/etsy.go`) - polling-based order/inventory sync against `GetShopReceipts`/`GetListingInventory` isn't built yet.
 - **Ebay**: order-event names are less certain — developer.ebay.com pages repeatedly failed to load during research, so those values come from documented Platform Notifications event types found via search rather than a directly confirmed doc page.
+- **TikTok Shop**: not in the capability table above - `partner.tiktokshop.com/docv2` is JS-rendered and didn't return usable content via fetch, so exact webhook event names and endpoint paths aren't confirmed (unlike every other row in that table, which comes from readable docs). What is confirmed via secondary sources: TikTok Shop's Partner API has webhooks covering order, product, and inventory changes, and a Product/Inventory API for listing and stock management. Treat as directionally real but needing its own dedicated research pass - with confirmed endpoint names - before implementation.
+- **BigCommerce vs Tiktok**: the capability table above includes BigCommerce, but BigCommerce is not one of this codebase's actual mock platforms (see `AGENTS.md`'s platform list - `domains/accounts/platform.go`'s `allPlatforms` has `Tiktok`, not BigCommerce). BigCommerce's row is left in place since the research itself may still be useful, but it's excluded from the priority ranking below; Tiktok is included despite the weaker sourcing noted above, since it's a platform that actually exists in this codebase.
+
+## Market-size research (2026-08-20)
+
+Pulled to sanity-check which platforms are most worth integrating first, on
+top of the API-completeness comparison above. See `AGENTS.md`'s "Platform
+integration priority" section for the resulting ranking and reasoning.
+
+Figures are mid-2026 estimates for FY2025 (or most recent trailing period)
+unless noted. Anything not sourced from an SEC filing is a third-party
+estimate (StoreLeads, DemandSage, Marketplace Pulse, etc.) and should be
+treated as directional, not precise - methodology varies a lot between
+sources, especially for "number of stores/sellers."
+
+| Platform | Active sellers/stores | Most recent GMV | Source confidence |
+|---|---|---|---|
+| Amazon (3P) | ~1.9M active sellers | ~$575B (3P GMV, 2025); total Amazon GMV >$800B | Moderate - earnings-adjacent estimates |
+| Shopify | ~3-6.8M active stores (methodology varies) | $378.4B (FY2025, +29% YoY) | High - SEC filings |
+| eBay | ~18.3M active sellers | $79.6B (FY2025, +7% YoY) | High - SEC filings |
+| Etsy (already live) | 5.6M active sellers | $11.92B GMS (FY2025, -5.3%) | High - SEC filings |
+| Squarespace Commerce | ~353K live ecommerce sites | ~$7.2B (2026 est.) | Low - marketing estimate |
+| WooCommerce | ~4.2-6M active stores | ~$30-35B (2025 est.; average store is tiny, ~$7-8K/yr) | Low - third-party estimate, no central ledger |
+| Walmart Marketplace | ~200-250K sellers, +50% YoY growth | ~$10B (rough external estimate; Walmart doesn't break this out cleanly) | Low |
+| Wix eCommerce | ~760K-3M live stores | $4.1B-$12.4B (conflicting self-reported figures) | Low |
+| Tiktok Shop | ~15M sellers globally, ~500K registered / ~216K active in the US | $64.3B global (2025, nearly 2x 2024); $15.1B US (+68% YoY) | Low - third-party estimate, hypergrowth market |
+| BigCommerce *(not an actual mock platform here - see caveat above)* | ~37-42K *active* stores (shrinking, shifting to enterprise) | $34B+ | Moderate |
+| Square Online | n/a (bundled into Square's overall $250B GPV, mostly in-person POS) | Can't isolate | N/A |
+| Zoho Commerce | ~2,196 stores globally (285 US), +34% YoY US growth off a tiny base | Not disclosed; likely small given store count | Low |
+| Ecwid | ~130-164K live stores, declining (-20% YoY) | Not disclosed | Low |
+| Big Cartel | ~91-192K stores (estimates vary widely), declining sharply (-41% YoY in 2026 Q1) | Not disclosed; platform targets low-AOV indie sellers | Low |
+
+Key takeaways:
+
+- Amazon's 3P GMV ($575B) is ~1.5x Shopify's *total* GMV despite Shopify
+  having 2-3x more active stores - Amazon sellers skew toward larger,
+  more serious operations.
+- eBay has by far the most sellers (18.3M) but the lowest GMV-per-seller of
+  any major platform here ($79.6B / 18.3M), suggesting a lot of integration
+  surface for comparatively thin per-seller value - compounded by its weak
+  inventory-webhook story (see table above).
+- WooCommerce can't be sized financially at all - it's a WordPress plugin,
+  not a company with a ledger - so its case rests entirely on raw store
+  count, not proven revenue-per-integration.
+- Walmart Marketplace is small in absolute terms but growing fast (+50%
+  YoY) and is a natural "second marketplace" for sellers already on Amazon.
+
+## Weighted priority ranking (2026-08-20)
+
+Scores each of the 12 not-yet-live mock platforms (everything in
+`domains/accounts/platform.go`'s `allPlatforms` except Etsy) on four 0-10
+criteria, weighted and summed to a single composite score. This is a
+judgment call turned into numbers, not a precise formula - the weights and
+per-platform scores below are my read of the research above; treat the
+*ranking* as the useful output, not the second decimal place. BigCommerce is
+excluded (not an actual platform in this codebase, see caveat above).
+
+Etsy itself is scored too, as a **reference row only** - it's already the
+live integration, so it's not competing for "what to build next," but
+running it through the same rubric is a useful sanity check on the model.
+
+**Criteria & weights:**
+
+- **GMV / market opportunity (45%)** - bucketed from the GMV figures above
+  (>$500B=10, $300-500B=9, $50-100B=7, $25-50B=6, $8-15B=4, $5-8B=3,
+  undisclosed-and-small=1). This is weighted highest because "lucrative"
+  is fundamentally a dollar-opportunity question.
+- **API/inventory-sync completeness (30%)** - from the capability table at
+  the top of this doc: full order-webhook + dedicated inventory-webhook
+  coverage scores highest, missing inventory webhook scores mid, no
+  inventory API at all (Big Cartel) scores near-zero. This directly gates
+  how good a product experience is even possible on that platform.
+- **Growth trajectory (15%)** - YoY GMV/store growth; rewards fast-growing
+  platforms (Tiktok, Walmart) and penalizes shrinking ones (Ecwid, Big
+  Cartel) as a proxy for where future opportunity is heading.
+- **Integration cost, inverted (10%)** - auth complexity and existing
+  codebase head start (Amazon's `domains/amazon` background-processor
+  infra) score higher; gated/undocumented webhook access (Big Cartel)
+  scores lowest. Weighted lowest since it affects timeline more than
+  whether the integration is worth doing at all.
+
+**Scores:**
+
+| Platform | GMV (45%) | API (30%) | Growth (15%) | Cost (10%) | Weighted total |
+|---|---|---|---|---|---|
+| Shopify | 9 | 10 | 8 | 9 | **9.15** |
+| Amazon | 10 | 10 | 5 | 6 | **8.85** |
+| Tiktok Shop | 7 | 7 | 10 | 4 | **7.15** |
+| Walmart Marketplace | 4 | 9 | 9 | 5 | **6.35** |
+| Wix | 4 | 10 | 5 | 8 | **6.35** |
+| WooCommerce | 6 | 6 | 5 | 7 | **5.95** |
+| Square Online | 3 | 10 | 5 | 8 | **5.90** |
+| Ebay | 7 | 5 | 4 | 5 | **5.75** |
+| Squarespace | 3 | 6 | 6 | 7 | **4.75** |
+| *Etsy (reference, already live)* | *4* | *3* | *1* | *10* | *3.85* |
+| Zoho | 1 | 6 | 6 | 7 | **3.85** |
+| Ecwid | 1 | 6 | 1 | 8 | **3.20** |
+| Big Cartel | 1 | 2 | 1 | 3 | **1.50** |
+
+**Ranked priority order:**
+
+1. **Shopify** — 9.15
+2. **Amazon** — 8.85
+3. **Tiktok Shop** — 7.15
+4. **Walmart Marketplace** — 6.35
+5. **Wix** — 6.35 (behind Walmart on the growth tiebreaker: 9 vs 5)
+6. **WooCommerce** — 5.95
+7. **Square Online** — 5.90
+8. **Ebay** — 5.75
+9. **Squarespace** — 4.75
+10. **Etsy** — 3.85 (reference only - already live, not competing for "what to build next")
+11. **Zoho** — 3.85
+12. **Ecwid** — 3.20
+13. **Big Cartel** — 1.50
+
+Notable movement from the earlier qualitative pass: Shopify edges out Amazon
+once integration cost and growth are counted, not just raw GMV - Amazon's
+dollar opportunity is still bigger, but Shopify is cheaper to build, easier
+to get first customers through (App Store), and still growing faster.
+Tiktok Shop, unresearched until this pass, lands at #3 on the strength of
+its growth rate alone - but see the sourcing caveat above before acting on
+that; its API details need a dedicated research pass before it's actually
+buildable. Big Cartel is unambiguously last: no inventory API is a
+structural dealbreaker for this specific product, independent of its market
+size.
+
+**Etsy, run through the same rubric, scores 3.85 - tied with Zoho, below
+every platform except Ecwid and Big Cartel.** Its GMV is mid-pack and
+declining (-5.3% YoY), and - per the caveat above - it's the *only*
+platform researched with literally no webhook/push mechanism for anything,
+so it scores below every platform here except Big Cartel on API
+completeness too. The only criterion where it dominates is integration cost
+(10/10, since it's already built). This is a useful gut-check on the model,
+not a claim that building Etsy first was a mistake - Etsy was presumably
+chosen for reasons this rubric doesn't capture (an existing relationship, a
+founder's market knowledge, being the most approachable API to get
+developer credentials for), not for having the best growth/GMV/webhook
+profile. Worth remembering when weighing this ranking against Etsy's actual
+day-to-day integration cost, which - per the caveat above - has turned out
+to be nontrivial in practice: with no webhooks at all, real order/inventory
+sync has to be built as a polling loop, which is exactly the kind of
+integration cost this rubric's "Cost" column doesn't capture once a
+platform is more than superficially wired up.
+
+Sources:
+- [Shopify Statistics 2026: Market Share, $116B GMV, Employees](https://www.chargeflow.io/blog/shopify-statistics)
+- [Shopify 2026: $378.4B GMV, Store and Seller Data](https://termsandconditionstemplate.com/shopify-statistics-2026)
+- [Amazon Third-Party Sellers Generate $575 Billion in GMV](https://english.ebrun.com/20260719/688440.shtml)
+- [Amazon GMV Surpassed $800 Billion in 2025 - Marketplace Pulse](https://www.marketplacepulse.com/articles/amazon-gmv-surpassed-800-billion-in-2025)
+- [Top 1.6% of Sellers Drive 50% of Amazon's 3P GMV](https://www.marketplacepulse.com/articles/top-16-of-sellers-drive-50-of-amazons-3p-gmv)
+- [WooCommerce Market Share 2026: 33.4% Global Stats](https://redstagfulfillment.com/what-is-woocommerces-market-share/)
+- [BigCommerce Statistics 2026](https://www.chargeflow.io/blog/bigcommerce-statistics)
+- [How many Walmart Marketplace sellers are there in 2025?](https://redstagfulfillment.com/how-many-walmart-marketplace-sellers/)
+- [Walmart Marketplace Grows 50% in One Year - Marketplace Pulse](https://www.marketplacepulse.com/articles/walmart-marketplace-grows-50-in-one-year)
+- [eBay Gross Merchandise Volume (GMV) 2018-2026 - Marketplace Pulse](https://www.marketplacepulse.com/stats/ebay-gross-merchandise-volume-gmv)
+- [eBay Statistics (2026): Active Buyers, Listings, GMV, Revenue](https://expandedramblings.com/index.php/ebay-stats/)
+- [The State of Wix in 2026](https://storeleads.app/reports/wix)
+- [Squarespace Subscriber and Revenue Statistics for 2026](https://backlinko.com/squarespace-users)
+- [Etsy, Inc. Reports Fourth Quarter and Full Year 2025 Results](https://investors.etsy.com/news-events/press-releases/detail/218/etsy-inc-reports-fourth-quarter-and-full-year-2025-results)
+- [Block Statistics (2026): Sellers, GPV, Block Revenue](https://expandedramblings.com/index.php/square-statistics/)