6598691372
- Prisma: Zone (postal-code list or radius), Rate (zone- or distance-band
keyed), GeocodeCache (permanent address->lat/lng cache per
IMPLEMENTATION_PLAN.md §9), Location.shopifyLocationId (maps to
Shopify's own Location resource for inventory checks), Booking.zoneId
(needed for per-zone delivery-density counts, not just per-location).
- app/lib/geo.ts: pure haversine distance + postal-code matching, unit
tested against known city-to-city distances.
- app/services/zones.server.ts: geocoding (Google Maps Geocoding API,
cached — never re-geocodes the same address twice), zone eligibility,
nearest-location auto-assignment ranked by distance, delivery-density
threshold checks (a sparse zone doesn't unlock until minOrders bookings
have already routed through it), and inventory-based location exclusion
via Shopify's InventoryLevel API (locations without a mapped
shopifyLocationId are left in rather than false-negative excluded).
- app/services/rates.server.ts: pure rate resolution by zone or distance
band, cheapest-match-wins when bands overlap.
- apps.scheduling.availability.tsx: LOCAL_DELIVERY requests with a
postalCode/address now auto-assign to the nearest eligible,
density-qualified zone/location instead of the shop's default location;
response includes the matched rate. Also fixed a real gap left over from
Phase 4: this route never actually read Booking counts into
getAvailability's `consumed` map, so capacity always showed as fully
available regardless of existing bookings — now it does.
- extensions/datetime-widget: LOCAL_DELIVERY now asks for a postal code
before showing dates; PICKUP shows a Google Maps pin for the location
(both gated on an optional Maps API key — a block setting in the theme
editor, since it needs to be public/client-side, not an app secret);
confirmation display and cart attributes (dd_zone_id, dd_rate_label)
carry the resolved zone/rate through to checkout.
- extensions/delivery-customization: now appends the resolved rate to the
relabeled delivery option ("Local delivery — Aug 25 ($5.99)") when one's
configured — real Cart Transform-based fee *charging* stays deferred to
v2 per IMPLEMENTATION_PLAN.md §5.4, this is display-only.
- Admin: /app/zones and /app/rates (Polaris CRUD, mirroring Phase 1's
patterns), plus shopifyLocationId and auto-geocode-on-save added to the
location edit form.
Fixed one real bug caught only by `npm run build` (not tsc/vitest, which
both passed clean): app.rates._index.tsx's component called
formatPriceLabel from rates.server.ts, and Remix correctly refuses to
bundle anything imported from a .server.ts path for the client. Moved the
pure (no I/O, no Prisma) formatter to app/lib/currency.ts.
Verified: lint, typecheck, 86 unit tests (+21 new: geo, zones, rates,
delivery-customization's rate-label case with a real WASM fixture run),
16 integration tests against live Postgres (+8 new: geocode caching,
postal/radius zone matching, nearest-first ranking, density thresholds),
both builds, and a live script exercising the full
zone-match -> density-check -> rate-resolve -> availability pipeline
together against the Postgres container.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Delivery Date & Time
Shopify app: scheduling for Shipping / Local Delivery / Store Pickup, with date-time slots, capacity intelligence, and all-plan checkout enforcement via Cart/Checkout Validation Functions.
Read PRODUCT_STRATEGY.md (why) and IMPLEMENTATION_PLAN.md (how, phased build order) before making changes. CLAUDE.md holds the non-negotiables for AI-assisted work in this repo.
Getting started
npm install
cp .env.example .env # fill in Shopify app credentials after linking
docker compose up -d # local Postgres (5433) + Redis (6380)
npx prisma migrate dev
npm run dev # shopify app dev — requires `shopify auth login` first
Dev uses Postgres, same as prod, since the schema relies on Prisma enums and
(from Phase 5 on) array fields that SQLite can't express. npm run worker
runs the BullMQ worker (jobs/worker.ts) once Phase 4 makes it do anything.
Commands
| Command | Purpose |
|---|---|
npm run dev |
shopify app dev — local dev against a dev store |
npm test |
Vitest unit tests |
npm run test:e2e |
Playwright E2E |
npm run lint / npm run typecheck |
ESLint / tsc --noEmit |
npx prisma migrate dev |
DB migrations |
npm run deploy |
shopify app deploy — deploy extensions/functions |
npm run worker |
BullMQ worker (hold-expiry, notifications) |
npm run test:integration |
Redis/Postgres-backed tests (slot-hold concurrency, booking flow) — needs docker compose up -d |
npm run test:functions |
Real WASM build + function-runner tests for both Shopify Functions, against fixtures |
npm run typegen:functions |
Regenerate extensions/*/generated/api.ts from each Function's schema.graphql + .graphql query (also runs automatically before npm run typecheck) |
Before public launch
The 3 mandatory GDPR compliance webhooks (customers/data_request,
customers/redact, shop/redact) are commented out in shopify.app.toml
— Shopify refuses to push them until the org requests and is granted
Protected customer data access in the Partner Dashboard (Apps → this
app → API access → Protected customer data), which is a manual
questionnaire/approval step. The handlers already exist and are fully
wired (app/routes/webhooks.customers.*.tsx, webhooks.shop.redact.tsx) —
once that access is granted, uncomment the three [[webhooks.subscriptions]]
blocks near the bottom of the webhooks section. Required before any
public launch or Built-for-Shopify submission — don't ship without it.
Status
Phase 0 (scaffold & CI) through Phase 5 (zones, rates, auto-assignment) are
complete. See §6 of IMPLEMENTATION_PLAN.md for the phased build order and
acceptance criteria — next up is Phase 6 (ops/dispatch dashboard).
Phase 5's Google Maps / geocoding features (pickup-location map in the
widget, radius-zone eligibility, address auto-geocoding on Save Location)
are only live if GOOGLE_MAPS_API_KEY is set — either as an env var for
server-side geocoding, or as the "Google Maps API key" block setting in the
theme editor for the storefront map. Without a key, everything else in
Phase 5 (postal-code zones, distance-band rates, delivery-density
thresholds) still works — those don't need Maps at all.
The storefront widget's TypeScript source lives in widget-src/datetime-widget/,
not inside extensions/datetime-widget/ — a Theme App Extension's
directory may only contain assets, blocks, snippets, and locales
(the CLI hard-rejects anything else, e.g. a src/ folder, with "Only
assets, blocks, snippets, locales directories are allowed"). Editing the
widget? Run npm run build:widget to bundle it into
extensions/datetime-widget/assets/datetime-widget.js — it also runs
automatically before npm run dev / npm run deploy.
Functions are JavaScript, not Rust (extensions/validation-slot/,
extensions/delivery-customization/) — no Rust toolchain was available in
the environment that built Phase 4, and IMPLEMENTATION_PLAN.md §1
explicitly allows JS as a fallback. Both were generated with
shopify app generate extension (once a real Partner login was available)
and their business logic (src/evaluate.js in each) is verified two ways:
plain Vitest unit tests at the repo root (npm test) and real
function-runner fixture tests that compile actual WASM
(npm run test:functions, also in CI). extensions/*/generated/ and
extensions/*/dist/ aren't committed (matching the CLI's own
.gitignore for these extensions) — npm run typegen:functions
regenerates the types from the committed schema.graphql, and building
runs automatically as part of npm run dev / test:functions.