fix: ship-blocker P1 — default shipping zone now covers US addresses (10001, 90210, etc)

[cavewebs]

Ship-blocker P1 Fix: Checkout shipping zones

Fixes: Demo checkout rejects US ZIP codes 10001 (NY) and 90210 (CA) with "We don't ship to that location yet."

📋 Comprehensive fix documentation: See SHIPPING_FIX_SUMMARY.md for detailed root cause analysis, verification steps, and live demo remediation options.

Root Cause

The install hook created a default shipping zone with locations: [] (empty array), which matched NO addresses. The matchesZone() function returns false for any address when the locations array is empty, causing all checkout attempts to fail.

Changes

1. Updated ensureDefaultShippingZone() in hooks/install.ts:

   • Creates a proper US-wide zone with locations: [{ country: 'US' }] that matches all US states
   • Also creates a default $5 flat-rate shipping method (us-flat-rate) for the US zone
   • Ensures both zone and method are created together on first install

2. Added comprehensive test coverage (test/shipping-zones.test.ts):

   • 7 new tests covering country-only matching, region-specific zones, empty locations, multiple locations, order precedence
   • Specifically tests the P1 cases: NY 10001 and CA 90210 now match US-wide zone

Verification

✅ All 92 tests pass (including 7 new shipping zone tests)
✅ Typecheck clean
✅ Build succeeds

To verify the fix:

1. Fresh install or seed will now have proper US shipping zone + method
2. Checkout with address US, NY, 10001 → ✅ matches zone, shows "Standard Shipping $5.00"
3. Checkout with address US, CA, 90210 → ✅ matches zone, shows "Standard Shipping $5.00"

Verification Demo

🧪 Shipping Zone Fix Verification

OLD zone (locations: []) — should fail all addresses:
────────────────────────────────────────────────────────────
❌ New York 10001            → NO MATCH
❌ California 90210          → NO MATCH
❌ Texas 75001               → NO MATCH

NEW zone (locations: [{ country: "US" }]) — should match US addresses:
────────────────────────────────────────────────────────────
✅ New York 10001            → MATCH (CORRECT)
✅ California 90210          → MATCH (CORRECT)
✅ Texas 75001               → MATCH (CORRECT)
❌ Toronto, Canada           → NO MATCH (CORRECT)

📋 Summary:
  - Old zone matched 0/3 US addresses → ❌ BROKEN
  - New zone matches 3/3 US addresses → ✅ FIXED
  - Canadian address correctly excluded → ✅ CORRECT

Live Demo Impact

The existing Railway/Neon deployment has the old broken zone. After merge:

Option 1: Redeploy (Recommended)

• Redeploy from main after merge
• Note: Install hook will skip (zone already exists)
• Need manual fix via Option 2 or 3

Option 2: Manual SQL Fix

UPDATE shipping_zones 
SET locations = '[{"country":"US"}]'::jsonb,
    name = 'United States (Domestic)',
    updated_at = NOW()
WHERE id = 'default';

INSERT INTO shipping_methods (
  id, zone_id, title, type, enabled, config, "order", created_at, updated_at
) VALUES (
  'us-flat-rate', 'default', 'Standard Shipping', 'flat_rate', true, 
  '{"type":"flat_rate","amount":{"currency":"USD","amount":500}}'::jsonb,
  0, NOW(), NOW()
) ON CONFLICT (id) DO NOTHING;

Option 3: Admin UI (if shipping admin is deployed)

1. Go to DashCommerce → Shipping
2. Edit "Default zone" → Add location: US (all regions)
3. Add method: Flat Rate, $5.00

Benefits

• New installs ship to common US addresses out of the box
• No manual shipping configuration required for demo purposes
• Seed hardening improves DX for all new stores
• Backward compatible: existing installs with custom zones unaffected

Files Changed

• packages/core/src/hooks/install.ts — Updated ensureDefaultShippingZone()
• packages/core/test/shipping-zones.test.ts — New test file (7 tests)
• SHIPPING_FIX_SUMMARY.md — Comprehensive fix documentation

  

[cavewebs]

Eng review (COMMENT)

Root cause looks real: empty locations: [] never matches in matchesZone — that explains the US zip FAIL. Tests on matchesZone/pickZone for 10001/90210 are the right acceptance shape.

CI: Typecheck + Build PASS; EmDash Compatibility (0.37.0) PASS.

Notes before mark-ready

1. Live demo will not self-heal on redeploy alone — ensureDefaultShippingZone still early-returns when any zone exists, so the broken default row stays. Keep the SQL/admin remediation as a required post-merge step (PR body is clear; good).
2. SQL snippet targets id = 'default' while new installs create us-domestic — correct for the live DB; call that out so nobody runs the wrong id after a wipe.
3. SHIPPING_FIX_SUMMARY.md at repo root — prefer docs/ (or PR-only) so we don't ship a one-off ops memo at package root. Non-blocking if you want a tiny follow-up.
4. Install hook itself isn't unit-tested (only matchesZone) — acceptable for this P1; optional later.

No code blockers for the install-hook change itself. Hold draft until Bot/Tim greenlight merge + demo remediation plan.