@rovela-ai/sdk 0.21.0 → 0.22.0

package/docs/changelog/epoch-09-catalog-tax.md

@@ -0,0 +1,91 @@
+# E9 Catalog & tax — 0.22.0..0.22.0
+
+## What landed
+Two catalog-commerce behaviors every PrestaShop-migrated store needs: the
+public category filter is now TREE-AWARE (a parent-category link includes its
+descendant categories' products — imported catalogs assign products to leaf
+categories), and TAX CLASSES bring per-product VAT rates (French 5.5%/20%
+food split): products carry a `tax_class`, tax zones carry per-class rates,
+and every money surface (quote, Stripe session, orders, emails, invoice,
+admin) computes and renders the per-rate VAT ventilation ("dont TVA par
+taux") French invoices legally require.
+
+## SDK-internal (free)
+- `findProducts`/`countProducts` accept `categoryId: string | string[]`
+  (IN-match). New `findCategoryDescendantIds(id)` (recursive CTE) and
+  `findTaxClassesByProductIds(ids)`.
+- `resolveTax` accepts optional `lines` — per-line computation grouped by
+  rate, order discount allocated pro-rata (largest-remainder, sums exact),
+  shipping taxed at the zone's base rate. Returns `taxBreakdown` +
+  `taxClassRates`. Without `lines`, or on a zone with no `class_rates`, the
+  original lump formula runs — cent-identical to 0.21.x.
+- `buildQuote` carries `taxBreakdown`/`taxClassRates` on the Quote; the
+  Stripe session divides each line by ITS OWN rate in tax-inclusive mode and
+  stamps `rovelaTaxBreakdown` metadata; both order writers persist
+  `orders.tax_breakdown`.
+- Admin: TaxSettings zone editor gains per-class rate rows; ProductForm
+  gains a Tax class field (datalist fed from the zones' class names);
+  tax-zones API accepts `classRates`; products API accepts `taxClass`.
+
+## Template contract
+- `app/account/orders/[id]/invoice/page.tsx` — the totals block renders one
+  `TVA {rate}%` row per `order.taxBreakdown` entry when the order carries a
+  multi-rate ventilation, else the single flat tax row (stock shape: gated
+  branch on `order.taxBreakdown?.length > 1`). Stores with a customized
+  invoice keep their layout and add the same branch.
+
+## Behavior contracts
+- **Public `/api/products?category=` is tree-aware.** A parent category id or
+  slug now returns its own products PLUS every descendant category's. Stores
+  whose nav deliberately relied on parent links showing ONLY directly-assigned
+  products (rare; usually a bug they worked around) will see more products.
+  Admin product filters are UNCHANGED (exact match).
+- **`OrderSummary` accepts `taxBreakdown`** and renders per-rate rows when
+  more than one rate is present; `CheckoutFlow` computes it from the estimate
+  response. Single-rate stores render byte-identically to 0.21.x.
+- The pre-checkout shipping estimate (`/api/checkout/shipping`) accepts an
+  optional `productId` per item and returns `tax.breakdown`. Clients that
+  omit `productId` get the previous base-rate estimate (totals unchanged in
+  tax-inclusive stores).
+
+## Custom-code hazards
+- `grep -rn "resolveTax(" app lib components` — custom callers keep working
+  (the `lines` param is optional; omitted = old math). If a custom checkout
+  displays tax recomputed from `taxRate` alone, it cannot reproduce a
+  multi-rate cart: read `tax.breakdown`/`quote.taxBreakdown` when present
+  (see CheckoutFlow's per-group recompute for the reference implementation).
+- `grep -rn "taxRate" app components` — any custom "TVA (20%)" label stays
+  correct for single-rate stores; multi-rate stores should render the
+  breakdown rows instead.
+- `grep -rn "category=" app components lib` — store-authored nav links to
+  PARENT categories now include leaf products (this is almost always the
+  desired fix, not a regression).
+
+## DB
+- `products.tax_class varchar(50)` NULL — self-heals via
+  `ensureCatalogTranslationsSchema` (every catalog chokepoint).
+- `tax_zones.class_rates jsonb NOT NULL DEFAULT '{}'` — self-heals via
+  `ensureVisibilityColumns`.
+- `orders.tax_breakdown jsonb` NULL — self-heals via
+  `ensurePaymentMethodsSchema`.
+- All three are additive with behavior-preserving defaults: no class rates
+  configured = 0.21.x math to the cent. Pre-applying is optional.
+
+## New surfaces
+- None. (TaxSettings/ProductForm gains are inside existing admin pages; no
+  new routes to mount.)
+
+## Verify
+1. `/products?category=<parent slug>` lists products assigned to child
+   categories; the admin Products page filtered to the same parent does NOT.
+2. Settings → Tax: add a class rate (e.g. `tva-5-5` = 5.5) on the active
+   zone; assign the class to one product (Product form → Pricing → Tax
+   class).
+3. Cart with one classed + one unclassed product → checkout review shows two
+   `TVA x%` rows summing to the receipt tax; totals unchanged
+   (tax-inclusive).
+4. Place a test order → `orders.tax_breakdown` populated; invoice page and
+   order-confirmation email render the ventilation; admin order detail shows
+   per-rate rows.
+5. A store that configures NO class rates: quote totals and every tax line
+   render exactly as before the update.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rovela-ai/sdk",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Rovela SDK - Pre-built e-commerce components for AI-powered store generation",
   "type": "module",
   "license": "MIT",

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

@@ -27,7 +27,7 @@ Usage: `nextjs_call` with `port="3000"` and `toolName="execute_sql"`
 
 | Table | Key Columns |
 |-------|-------------|
-| `products` | id, name, slug, price, status (`draft`/`active`/`archived`), categoryId, hasVariants, images (JSONB string[]), videos (JSONB string[]), metafields (JSONB key/label/value/type), translations (JSONB per-locale name/description) |
+| `products` | id, name, slug, price, status (`draft`/`active`/`archived`), categoryId, hasVariants, images (JSONB string[]), videos (JSONB string[]), metafields (JSONB key/label/value/type), translations (JSONB per-locale name/description), taxClass (0.22.0 — names a rate in tax_zones.class_rates; NULL = zone base rate) |
 | `product_variants` | id, productId (CASCADE), sku, name, price, inventory, attributes (JSONB), image, video |
 | `categories` | id, name, slug, parentId (self-ref), order, translations (JSONB) |
 | `orders` | id, customerId, email, status, total, currency (ISO snapshot — display orders in THIS currency), refundAmount, returnReason, shippingAddress (JSONB) |

package/templates/store-template/app/account/orders/[id]/invoice/page.tsx

@@ -42,6 +42,8 @@ interface InvoiceOrder {
   total: number
   subtotal: number
   tax: number
+  /** Per-rate VAT ventilation (0.22.0) — cents; null/absent = flat tax line. */
+  taxBreakdown?: Array<{ rate: number; baseCents: number; taxCents: number }> | null
   shipping: number
   discountAmount?: number | string
   discountCode?: string | null
@@ -245,10 +247,23 @@ function InvoiceContent({ orderId }: { orderId: string }) {
             <span>{t('common.shipping')}</span>
             <span>{order.shipping > 0 ? formatPrice(order.shipping, orderCurrency) : t('common.free')}</span>
           </div>
-          <div className="flex justify-between text-muted-foreground">
-            <span>{t('common.tax')}</span>
-            <span>{formatPrice(order.tax, orderCurrency)}</span>
-          </div>
+          {order.taxBreakdown && order.taxBreakdown.length > 1 ? (
+            // Per-rate VAT ventilation (0.22.0) — the legally required French
+            // invoice breakdown ("dont TVA par taux").
+            order.taxBreakdown.map((entry) => (
+              <div key={entry.rate} className="flex justify-between text-muted-foreground">
+                <span>
+                  {t('common.tax')} {entry.rate}%
+                </span>
+                <span>{formatPrice(entry.taxCents / 100, orderCurrency)}</span>
+              </div>
+            ))
+          ) : (
+            <div className="flex justify-between text-muted-foreground">
+              <span>{t('common.tax')}</span>
+              <span>{formatPrice(order.tax, orderCurrency)}</span>
+            </div>
+          )}
           <div className="flex justify-between border-t pt-2 text-base font-semibold text-foreground">
             <span>{t('common.total')}</span>
             <span>{formatPrice(order.total, orderCurrency)}</span>

package/templates/store-template/package.json

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