@rovela-ai/sdk 0.19.7 → 0.20.0

package/docs/changelog/epoch-07-shipping-carriers.md

@@ -0,0 +1,125 @@
+# E7 Shipping carriers — 0.20.0..0.20.0
+
+## What landed
+Shipping became a carrier REGISTRY (the payments-registry model): multiple
+carriers coexist, each with its own zones + rates, and the global
+`store_settings.shipping_mode` either/or is retired (column kept, ignored).
+Colissimo (La Poste) is the first integrated carrier: label generation from
+the admin order page (home + point relais products), pickup-point (relay)
+delivery at checkout with a nested point picker, tracking links, and the
+order-shipped email carrying the tracking number. Relay offers are ordinary
+`shipping_rates` rows (`fulfillment='relay'`) — zones, cart thresholds and
+customer-group gating apply to every carrier through the one rate engine.
+
+## SDK-internal (free via pin bump)
+- Checkout `ShippingOptions` renders carrier groups as contained parent
+  cards (identity header w/ provider badge or merchant `logo_url`, child
+  option cards at full width) and sorts groups + options by price
+  descending. `renderOptionDetail` slot nests content under an option.
+- Quote API degrades gracefully: a Shippo outage drops its live quotes but
+  no longer blanks the other carriers' options.
+- `sendStatusNotification` logs shipped-email failures honestly (was an
+  unconditional "sent" log).
+- Order confirmation + shipped emails label relay orders' address block
+  "Point relais — {name}" instead of presenting the relay street as the
+  customer's home address.
+
+## Template contract
+- `app/api/checkout/colissimo-relays/route.ts` (NEW) — re-export of
+  `@rovela-ai/sdk/checkout/api/colissimo-relays`; the checkout relay picker
+  POSTs here. Without it, selecting a relay rate shows a permanent
+  "search failed" state.
+- `app/api/admin/shipping/colissimo/route.ts` (NEW) — GET/POST/DELETE
+  re-exports (`getColissimoConfig`/`saveColissimoSettings`/
+  `deleteColissimoSettings`); the ShippingSettings Colissimo panel reads and
+  writes through it.
+- `app/api/admin/orders/[id]/ship-with-colissimo/route.ts` (NEW) — POST
+  `shipWithColissimo`; `app/api/admin/orders/[id]/colissimo-defaults/route.ts`
+  (NEW) — GET `getColissimoDefaults`; `app/api/admin/orders/[id]/label/route.ts`
+  (NEW) — GET `downloadOrderLabel` (admin-gated label bytes; `orders.label_url`
+  points at this path for Colissimo labels).
+
+## Behavior contracts
+- `checkout/api/shipping` (quote) now UNIONS all active carriers' DB rates
+  with Shippo live quotes when a `provider='shippo'` carrier is active —
+  `store_settings.shipping_mode` no longer selects a path. A legacy
+  `shipping_mode='shippo'` store self-heals a shippo carrier row
+  (`ensureLegacyShippoCarrier`) on the first quote/admin-carriers read.
+  Response `mode` field is now the constant `'manual'` (legacy shape only).
+- `resolveShippingSelection` manual branch: rates from provider-bound
+  carriers stamp `orders.carrier` with the PROVIDER (`'colissimo'`), not the
+  carrier's slug. Rates with `fulfillment='relay'` REQUIRE
+  `selection.relayPointId`; the point is re-verified with the carrier and a
+  French mobile is required on the shipping address (PricingError
+  otherwise). The relay's address becomes the order's `shippingAddress`
+  snapshot ("Point relais — {name}" convention, mirroring §59 pickup); the
+  customer's own entered address is preserved as `billingAddress` when no
+  separate billing was given.
+- `ShippingOption.source` union is unchanged (`manual|shippo|pickup`) but
+  options gained `provider?`/`fulfillment?`/`relayPointId?` — custom
+  checkout code switching on `source` keeps working.
+- Admin `ShippingSettings` is carriers-first: the manual/shippo mode toggle
+  is GONE; Shippo config renders inside its carrier card (own transactional
+  Save), the AdminSaveBar document now tracks only `shippingCountries`.
+
+## Custom-code hazards
+- grep `shippingMode` in store code: any UI/logic branching on
+  `'manual' | 'shippo'` is dead — the quote response's `mode` is now a
+  constant. Replace with capability checks on the options themselves.
+- grep `source === 'relay'` (stores that adopted 0.20.0 pre-releases only):
+  the relay discriminator is `fulfillment === 'relay'`; `'relay'` was never
+  a published `source` value.
+- Stores with a custom checkout that forked `ShippingOptions`: the fork
+  misses the carrier-group containers and the `renderOptionDetail` slot —
+  relay rates will render without a point picker. Replace the fork or port
+  the slot.
+
+## DB
+- `shipping_carriers.provider varchar(20) NOT NULL DEFAULT 'manual'`,
+  `shipping_carriers.logo_url varchar(500)`,
+  `shipping_rates.fulfillment varchar(20) NOT NULL DEFAULT 'home'` — all
+  self-heal via `ensureShippingCarrierSchema()` at every carrier/zone/rate
+  chokepoint. Defaults make existing data behave identically.
+- `orders.relay jsonb` (`{provider,id,type,name}`) — rides
+  `ensurePaymentMethodsSchema()`.
+- `shipping_labels` (NEW table: order_id FK cascade, carrier, format,
+  data base64) — self-heals whole via `ensureShippingLabelsSchema()`.
+  Deliberately not a column on orders (drizzle full-row selects).
+- `store_settings`: `colissimo_contract_number varchar(20)`,
+  `colissimo_password varchar(64)` (SERVER-ONLY secret — stripped from the
+  admin settings GET; never `NEXT_PUBLIC_`, never client-side),
+  `colissimo_enabled boolean`, `colissimo_sender_address jsonb`,
+  `colissimo_default_weight_kg decimal` — ride `ensureStoreSettingsSchema()`.
+
+## New surfaces
+- The five routes in Template contract above. No new admin PAGES — the
+  Colissimo panel lives inside `/admin/shipping`'s carrier card and the
+  "Ship with Colissimo" card inside the existing order detail page.
+
+## MERCHANT-DATA HAZARD
+- A store that ran `shipping_mode='shippo'`: its Shippo config keeps working
+  through the self-healed carrier row, but the row is created ACTIVE — if
+  the merchant had abandoned Shippo (mode set but key removed), the quote
+  path silently skips it (no key → degraded, no options added). Audit: does
+  the store have `shippo_api_key` set AND `shipping_mode='shippo'`? If mode
+  is shippo but the key is gone, deactivate the self-healed carrier row.
+- Parcel weight for Colissimo labels reads the product `weight` METAFIELD
+  (kg, PrestaShop-import convention) with `colissimo_default_weight_kg` as
+  the per-item fallback — stores without weight metafields ship at the
+  default weight unless the admin overrides per label.
+
+## Verify
+- `/admin/shipping`: carriers list renders (no mode toggle); "Add carrier"
+  offers Manual/Colissimo/Shippo with duplicates disabled; a Colissimo
+  carrier card shows the Connection panel and its zones/rates; the rate
+  editor on a Colissimo carrier shows "Delivery type: Home / Pickup point".
+- Checkout with a FR address: carrier groups render with badges, sorted by
+  price desc; selecting a relay rate opens the nested point picker; continue
+  is blocked until a point is picked and the address has a FR mobile.
+- Place a relay order (manual payment path is fine): `orders.relay` set,
+  `shipping_address` = the relay's address, `carrier='colissimo'`.
+- Admin: mark paid → "Ship with Colissimo" (weight prefilled from
+  metafields) → Generate Label & Ship → tracking number appears (`6M`/`6H`
+  prefix for relay, `6A`/`6C` for home), label downloads from
+  `/api/admin/orders/{id}/label`, shipped email sent with tracking.
+- `npm run build` green.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rovela-ai/sdk",
-  "version": "0.19.7",
+  "version": "0.20.0",
   "description": "Rovela SDK - Pre-built e-commerce components for AI-powered store generation",
   "type": "module",
   "license": "MIT",
@@ -90,6 +90,10 @@
       "types": "./dist/checkout/api/pickup-locations.d.ts",
       "import": "./dist/checkout/api/pickup-locations.js"
     },
+    "./checkout/api/colissimo-relays": {
+      "types": "./dist/checkout/api/colissimo-relays.d.ts",
+      "import": "./dist/checkout/api/colissimo-relays.js"
+    },
     "./checkout/server": {
       "types": "./dist/checkout/server/index.d.ts",
       "import": "./dist/checkout/server/index.js"
@@ -292,6 +296,7 @@
   },
   "scripts": {
     "build": "tsc && cp -r src/admin/styles dist/admin/",
+    "prepublishOnly": "npm run build && cd ../.. && bash scripts/check-prompts.sh",
     "dev": "tsc --watch",
     "clean": "rm -rf dist tsconfig.tsbuildinfo",
     "db:push": "drizzle-kit push",

package/templates/store-template/.claude/skills/build-feature/SKILL.md

@@ -123,6 +123,8 @@ export default function AdminMyFeaturePage() {
   useEffect(() => {
     fetch('/api/admin/my-feature')
       .then(res => res.ok ? res.json() : Promise.reject(res))
+      // Admin API responses are ENVELOPED: { data: … }. Always unwrap — reading
+      // the top level fails silently (your own null-guard hides the miss).
       .then(json => setData(json.data || []))
       .catch(() => setLoadError('Could not load. Refresh to retry.'))
       .finally(() => setLoading(false))

package/templates/store-template/.claude/skills/manage-products/SKILL.md

@@ -33,7 +33,7 @@ Usage: `nextjs_call` with `port="3000"` and `toolName="execute_sql"`
 | `orders` | id, customerId, email, status, total, currency (ISO snapshot — display orders in THIS currency), refundAmount, returnReason, shippingAddress (JSONB) |
 | `order_items` | id, orderId (CASCADE), productId, variantId, name, price, quantity |
 | `customers` | id, email (unique), name, passwordHash, phone, groupId, locale, stripeCustomerId, emailVerified |
-| `store_settings` | id, storeName, storeEmail, storeCurrency, storeTimezone, storeCountry, defaultLocale, enabledLocales, taxIncludedInPrices, shippingMode |
+| `store_settings` | id, storeName, storeEmail, storeCurrency, storeTimezone, storeCountry, defaultLocale, enabledLocales, taxIncludedInPrices, shippingMode (retired — the shipping_carriers registry decides; carriers have provider manual/shippo/colissimo, rates have fulfillment home/relay) |
 
 **Money contract (load-bearing)**: `price`, `total` etc. are DECIMAL CURRENCY UNITS — `29.99`, NEVER cents (`2999`). No ×100/÷100 anywhere except the Stripe API boundary. On multilingual stores (`enabled_locales`), catalog content can carry per-locale `translations` — when editing names/descriptions, keep every enabled locale in sync (CLAUDE.md §5.5).
 

package/templates/store-template/.claude/skills/override-sdk-component/SKILL.md

@@ -135,6 +135,13 @@ Import: `@rovela-ai/sdk/auth`
 Import: `@rovela-ai/sdk/media`
 
 ### Other modules (rarely overridden)
+**Cart-reading contract (any component that touches the cart):** read via
+`useCart((s) => s.items)` selectors — NEVER read the cart's localStorage during
+render (hydration mismatch) and never call `persist.rehydrate()` yourself
+(`CartProvider` hydrates pre-paint). A page that redirects on an empty cart
+gates the redirect on `useCartHydrated()` first, or it ejects real carts on
+reload.
+
 The SDK has 11 modules total. Also available: `core` (StoreSettingsProvider, i18n `useT`/`LocaleLink`, cookie consent), `analytics` (AnalyticsProvider + admin views), `emails` (templates + the merchant-editable layer — edited at `/admin/emails`, not by overriding components), `admin` (the dashboard kit — admin components are NOT candidates for copy-and-modify overrides; custom admin pages compose the kit per CLAUDE.md §7.6 instead), `shipping`, `theme`.
 
 ## Common Overrides

package/templates/store-template/app/api/admin/orders/[id]/colissimo-defaults/route.ts

@@ -0,0 +1,6 @@
+/**
+ * Pre-fill data for the "Ship with Colissimo" card (weight suggestion, relay)
+ */
+import { getColissimoDefaults } from '@rovela-ai/sdk/admin/api'
+
+export { getColissimoDefaults as GET }

package/templates/store-template/app/api/admin/orders/[id]/label/route.ts

@@ -0,0 +1,6 @@
+/**
+ * Download the stored carrier label for an order (admin-gated — labels carry PII)
+ */
+import { downloadOrderLabel } from '@rovela-ai/sdk/admin/api'
+
+export { downloadOrderLabel as GET }

package/templates/store-template/app/api/admin/orders/[id]/ship-with-colissimo/route.ts

@@ -0,0 +1,6 @@
+/**
+ * Generate a Colissimo shipping label for an order
+ */
+import { shipWithColissimo } from '@rovela-ai/sdk/admin/api'
+
+export { shipWithColissimo as POST }

package/templates/store-template/app/api/admin/shipping/colissimo/route.ts

@@ -0,0 +1,10 @@
+/**
+ * Colissimo configuration (connection, sender address, relay delivery)
+ */
+import {
+  getColissimoConfig,
+  saveColissimoSettings,
+  deleteColissimoSettings,
+} from '@rovela-ai/sdk/admin/api'
+
+export { getColissimoConfig as GET, saveColissimoSettings as POST, deleteColissimoSettings as DELETE }

package/templates/store-template/app/api/checkout/colissimo-relays/route.ts

@@ -0,0 +1,4 @@
+/**
+ * Colissimo pickup-point search (checkout relay picker)
+ */
+export { POST } from '@rovela-ai/sdk/checkout/api/colissimo-relays'

package/templates/store-template/package.json

@@ -9,7 +9,7 @@
     "lint": "eslint ."
   },
   "dependencies": {
-    "@rovela-ai/sdk": "0.19.7",
+    "@rovela-ai/sdk": "0.20.0",
     "@tailwindcss/forms": "0.5.11",
     "@tailwindcss/typography": "0.5.19",
     "autoprefixer": "10.4.24",