@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/schema.tsread-only · 4e8e68d

// Tablas de @core/shipping. Las recoge drizzle-kit vía src/lib/db/drizzle.config.ts.
import { boolean, index, integer, jsonb, pgTable, text } from 'drizzle-orm/pg-core';
import { primaryId, timestamps } from '../db/index.ts';

export const shippingZones = pgTable('shipping_zones', {
  id: primaryId('shz'),
  name: text('name').notNull(),
  /** Códigos ISO 3166-1 alpha-2; `*` = resto del mundo. */
  countries: jsonb('countries').$type<string[]>().notNull(),
  position: integer('position').notNull().default(0),
  ...timestamps,
});

export const shippingRates = pgTable(
  'shipping_rates',
  {
    id: primaryId('shr'),
    zoneId: text('zone_id')
      .notNull()
      .references(() => shippingZones.id, { onDelete: 'cascade' }),
    name: text('name').notNull(),
    /** Precio en unidades menores de la moneda de la tienda. */
    amount: integer('amount').notNull(),
    /** Gratis si el subtotal (tras descuentos) llega a este importe. */
    freeOver: integer('free_over'),
    /** Rango de aplicación por peso del carrito (gramos) y por subtotal. */
    minWeightGrams: integer('min_weight_grams'),
    maxWeightGrams: integer('max_weight_grams'),
    minSubtotal: integer('min_subtotal'),
    maxSubtotal: integer('max_subtotal'),
    /** Plazo de entrega estimado (días laborables), visible antes de pagar. */
    minDays: integer('min_days'),
    maxDays: integer('max_days'),
    active: boolean('active').notNull().default(true),
    position: integer('position').notNull().default(0),
    ...timestamps,
  },
  (t) => [index('shipping_rates_zone_idx').on(t.zoneId)],
);

export type ShippingZone = typeof shippingZones.$inferSelect;
export type ShippingRate = typeof shippingRates.$inferSelect;