@core / shipping

1.0.0 ▾

1.0.0

verifiedMIT

GitHub

Shipping zones and rates (flat, weight, order value, free over X) with delivery estimates and tracking URLs

Code6 filesContext~445 tokensscan passed

~445 tokens→ src/lib/shipping/AGENTS.md→ .cursor/rules/genpm-core-shipping.mdc

This is exactly what your AI reads when it works in src/lib/shipping. Nothing else is added to its context.

@core/shipping — rules for AI agents

Purpose

Shipping zones (ISO country lists, * = rest of world) and rates per zone: flat price, weight and order-value ranges, free shipping over an amount (after discounts) and delivery estimates in days. Registers the shipping step (order 200) of the @core/cart totals pipeline and builds tracking URLs for common carriers. No label purchase or live carrier quotes. Tables: shipping_zones, shipping_rates.

Map

index.ts — public API: upsertZone, upsertRate, ratesFor, zoneFor, trackingUrl, CARRIERS, shippingAdminResources.
shipping.ts — rules and the totals step. admin.ts — admin resources. schema.ts — tables.

Integration

Migrations as in src/lib/db/AGENTS.md. Import this module at startup (it registers the totals step).
Create zones and rates in the admin (...shippingAdminResources() in src/genpm/admin.ts, permissions shipping:read|update).
At checkout, store the country and the chosen rate on the cart: setCartMeta(cart.id, { country: 'ES', shippingRateId }); list options with ratesFor(totals, country) and show minDays–maxDays before payment.
Tracking: trackingUrl(carrier, number) when marking an order shipped (@core/orders).
Verify: a cart with country ES gets the cheapest Spanish rate; one over the free threshold pays 0.

Conventions

Prices in minor units of STORE_CURRENCY; weights in grams from catalog variants.
Digital-only carts never get shipping.
Show no_shipping issues clearly and block checkout for those countries.

Don't

Don't hide delivery times or shipping costs until after payment (EU consumer law requires them upfront).
Don't trust a rate id or amount sent by the browser; the totals step recomputes it.

# @core/shipping — rules for AI agents

## Purpose
Shipping zones (ISO country lists, `*` = rest of world) and rates per zone: flat price, weight and order-value
ranges, free shipping over an amount (after discounts) and delivery estimates in days. Registers the `shipping`
step (order 200) of the @core/cart totals pipeline and builds tracking URLs for common carriers.
No label purchase or live carrier quotes. Tables: `shipping_zones`, `shipping_rates`.

## Map
- `index.ts` — public API: `upsertZone`, `upsertRate`, `ratesFor`, `zoneFor`, `trackingUrl`, `CARRIERS`, `shippingAdminResources`.
- `shipping.ts` — rules and the totals step. `admin.ts` — admin resources. `schema.ts` — tables.

## Integration
1. Migrations as in `src/lib/db/AGENTS.md`. Import this module at startup (it registers the totals step).
2. Create zones and rates in the admin (`...shippingAdminResources()` in `src/genpm/admin.ts`, permissions `shipping:read|update`).
3. At checkout, store the country and the chosen rate on the cart: `setCartMeta(cart.id, { country: 'ES', shippingRateId })`;
   list options with `ratesFor(totals, country)` and show `minDays–maxDays` before payment.
4. Tracking: `trackingUrl(carrier, number)` when marking an order shipped (@core/orders).
5. Verify: a cart with country `ES` gets the cheapest Spanish rate; one over the free threshold pays 0.

## Conventions
- Prices in minor units of `STORE_CURRENCY`; weights in grams from catalog variants.
- Digital-only carts never get shipping.
- Show `no_shipping` issues clearly and block checkout for those countries.

## Don't
- Don't hide delivery times or shipping costs until after payment (EU consumer law requires them upfront).
- Don't trust a rate id or amount sent by the browser; the totals step recomputes it.

The exact tree that will be injected, after .genpmignore. Pinned to

src/lib/shipping/index.tsread-only · 4e8e68d

// @core/shipping — API pública. Al importarlo se registra el paso de envío en @core/cart.
export { shippingAdminResources, shippingRatesAdminResource, shippingZonesAdminResource } from './admin.ts';
export {
  CARRIERS,
  RateInput,
  type RateOption,
  ratesFor,
  registerShippingStep,
  shippingStep,
  trackingUrl,
  upsertRate,
  upsertZone,
  ZoneInput,
  zoneFor,
} from './shipping.ts';
export { type ShippingRate, type ShippingZone, shippingRates, shippingZones } from './schema.ts';