metatrondelivery/app/services/rates.server.ts
metatroncubeswdev 6598691372 feat: Phase 5 — multi-location, zones, rates, auto-assignment
- 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>
2026-08-24 03:27:21 -04:00

59 lines
2.0 KiB
TypeScript

import type { Method } from "@prisma/client";
// Pure rate resolution — no DB calls (CLAUDE.md: inject data). The caller
// (apps.scheduling.availability.tsx) fetches the shop's Rate rows for the
// method and passes them in here.
export interface RateLike {
id: string;
method: Method;
zoneId: string | null;
name: string;
priceCents: number;
keyedBy: string; // "zone" | "distance"
minDistanceKm: number | null;
maxDistanceKm: number | null;
}
export interface RateContext {
method: Method;
zoneId?: string;
distanceKm?: number;
}
/**
* Picks the rate that applies to a given method/zone/distance. Zone-keyed
* rates are matched by exact zoneId; distance-keyed rates by falling within
* [minDistanceKm, maxDistanceKm) (open-ended bounds are unbounded on that
* side). When more than one rate matches, the cheapest wins — a merchant
* with overlapping bands almost certainly wants the shopper quoted the best
* available price, not an arbitrary one.
*/
export function resolveRate(rates: RateLike[], context: RateContext): RateLike | null {
const candidates = rates.filter((rate) => {
if (rate.method !== context.method) return false;
if (rate.keyedBy === "zone") {
return context.zoneId !== undefined && rate.zoneId === context.zoneId;
}
if (rate.keyedBy === "distance") {
if (context.distanceKm === undefined) return false;
const min = rate.minDistanceKm ?? 0;
const max = rate.maxDistanceKm ?? Infinity;
return context.distanceKm >= min && context.distanceKm < max;
}
return false;
});
if (candidates.length === 0) return null;
return candidates.reduce((cheapest, candidate) => (candidate.priceCents < cheapest.priceCents ? candidate : cheapest));
}
// formatPriceLabel moved to app/lib/currency.ts (2026-08-24): it's pure/
// no-I/O, but a route *component* needs it (app.rates._index.tsx), and
// Remix refuses to bundle anything imported from a .server.ts path for the
// client — import it from lib/currency directly, not re-exported here.