@rovela-ai/sdk 0.19.8 → 0.21.0

package/docs/changelog/epoch-08-integrations.md

@@ -0,0 +1,125 @@
+# E8 Integrations hub — 0.21.0..0.21.0
+
+## What landed
+The admin gained `/admin/integrations` — ONE surface where the merchant
+manages credentials for every external service connected to the store
+(Brevo, PayPal, Turnstile, GA4, Google Ads, Meta, TikTok, Klaviyo, Intercom,
+Trustpilot, plus chat-installed custom integrations). Before this, rotating
+a key meant re-running a Feature Store card (a paid AI turn) or a per-store
+custom settings page; now it is a 20-second admin edit. Installing or
+removing an integration stays a Features Store / chat action — this page
+manages what is installed, it is not a catalog.
+
+## SDK-internal (free via pin bump)
+- `IntegrationsManager` (exported from `@rovela-ai/sdk/admin`) — the page
+  component; renders its own `AdminPageHeader` (bare-mount page wrapper).
+- `admin/integrations/registry.ts` — the static registry of known providers.
+  Each entry names its storage: dedicated `store_settings` columns for
+  secrets (brevo_*, paypal_*, turnstile_*) or a slot in the `analytics`
+  JSONB (ga4, google_ads, meta, tiktok, klaviyo, intercom, trustpilot).
+  These storage locations are a CONTRACT with the platform's Feature Store
+  card prompts — never rename one side alone.
+- Presence semantics: an entry renders only when its storage is detectable
+  on the store (column exists / JSONB key present) — a store never sees
+  integrations it does not have.
+- Secrets: GET returns `{ hasValue, masked }` only; PUT is write-only
+  (blank keeps the stored value). Brevo (`GET /v3/account`) and PayPal
+  (OAuth token grant) are validated server-side BEFORE persisting — a dead
+  key is never saved.
+- AdminNav Configuration group gained the `integrations` item (after Tax).
+
+## Template contract
+- `app/admin/(dashboard)/integrations/page.tsx` (NEW) — bare mount of
+  `IntegrationsManager`.
+- `app/api/admin/integrations/route.ts` (NEW) — re-export
+  `getIntegrations as GET, saveIntegration as PUT` from
+  `@rovela-ai/sdk/admin/api`. Without it the page shows a permanent load
+  error.
+
+## Behavior contracts
+- NEW self-healed column `store_settings.custom_integrations jsonb NOT NULL
+  DEFAULT '[]'` — descriptor registry for integrations the SDK does not
+  know. Deliberately NOT in the drizzle schema (raw-SQL only, like
+  `analytics`), so `findSettings` full-row selects never depend on it; the
+  integrations API self-heals it at its own chokepoint. Descriptors carry
+  `{key, label, fields:[{id = store_settings column name, label, secret}]}`;
+  values ALWAYS live in dedicated store_settings columns (merchant-secret
+  rule). Malformed descriptors are skipped, never rendered.
+- Custom-integration writes validate every field id against live
+  `information_schema` before a quoted-identifier UPDATE.
+- Store-side Claude Code contract (sandbox CLAUDE.md §7.6 + build-feature
+  skill): NEVER build a settings page / credentials form / nav entry for
+  integration keys — persist to canonical storage and (for novel
+  integrations) register a descriptor so this page renders the form.
+
+## Custom-code hazards (audit greps for CC)
+- Grep `app/admin` for hand-built integration settings pages (e.g. a
+  `marketing/page.tsx` managing an API key) — they are superseded by
+  `/admin/integrations` when their storage matches a registry entry
+  (brevo_api_key/brevo_list_id/brevo_enabled for Brevo). Presentational-only
+  duplicates should be REMOVED (page + its API route + its `navItems`
+  entry); keep any business logic that is not credential management.
+- Grep `navItems` in `app/admin/(dashboard)/layout.tsx` for entries whose
+  page only managed credentials — drop them alongside the page.
+
+## MERCHANT-DATA HAZARD
+None — no existing data changes meaning. The page is a view/editor over
+storage that already exists; runtime readers are untouched.
+
+## Also in 0.21.0 — storefront + admin correctness batch
+
+SDK-internal (free via pin bump):
+- Products API `?category=` accepts a SLUG as well as a UUID (store-authored
+  mega-menu links carry slugs; pre-0.21 a slug silently matched nothing and
+  the link showed the FULL catalog). Unknown slug → honest empty result.
+- Products API + `useProducts` gained `onSale` (comparePrice > price), with
+  `countProducts` pagination parity — no more raw-SQL sale pages.
+- `VariantSelector` renders attribute values in FIRST-SEEN order, not
+  alphabetical (sizes read S / M / L again, not L / M / S / XL).
+- `VariantManager` sync compares variant combinations as KEY SETS, not
+  index-by-index — an order-only mismatch used to fire a normalizing
+  onChange right after ProductForm captured its dirty baseline, raising a
+  phantom "Unsaved changes" save bar on EVERY variant product open.
+- Discounts page empty state got the full first-run treatment (icon +
+  title); `compact` stays for its nested sub-panels only.
+- Admin conventions pass (shipping + integrations + order details):
+  Connected states are `admin-badge-success` pills (bare green text + icon
+  medallions removed), `admin-radio`/`admin-helper-text`/
+  `admin-label-required` adopted, `admin-spinner` replaces the animated
+  RefreshCw, sentence-case sweep, 16px icons, responsive form grids,
+  aria-labels on icon buttons, native select → AdminSelect and the
+  signature checkbox → AdminSwitch on the order ship card.
+- i18n catalogs gained `faqPage.q/a.*`, `terms.*`, `privacy.*`,
+  `legal.*`, and `listing.{category,onSale,clearFilter}` keys (en + fr).
+
+Template contract (new stores + SDK-update flow):
+- `app/products/page.tsx` now READS `?category=` and `?sale=1` from the URL
+  (with the required Suspense boundary around `useSearchParams`) and shows
+  an active-filter chip. This is the page half of the category-links fix.
+- `app/products/[slug]/ProductDetailClient.tsx` coerces prices to numbers
+  before the strikethrough comparison ('185.00' > '55.50' was
+  lexicographically false — the compare-at price never showed).
+- `app/{faq,terms,privacy}/page.tsx` body copy now renders from the i18n
+  catalogs (was English literals even on French-default stores); FAQ
+  country names/lists localize via Intl.DisplayNames/ListFormat.
+
+## Custom-code hazards (0.21.0 batch — audit greps for CC)
+- Grep custom pages/sections for hand-rolled category or sale filtering
+  (raw SQL, client-side filters) — `/api/products?category=<slug>` and
+  `?onSale=1` now do it natively.
+- Grep for links to `/products?category=` — they WORK now; stores that
+  worked around the bug with custom category pages can keep or migrate them.
+
+## Verify
+- `/admin/integrations` renders under Configuration in the admin nav.
+- A store with Brevo columns shows the Brevo card; entering a bad key
+  surfaces Brevo's rejection inline and persists nothing.
+- A saved secret displays as "ends in …xxxx"; saving with the secret blank
+  keeps the stored value.
+- `SELECT custom_integrations FROM store_settings` returns `[]` (or the
+  registered descriptors) — never an error.
+- `/products?category=<existing slug>` shows only that category;
+  `/products?sale=1` shows only discounted products (chip + clear visible).
+- A product with comparePrice > price shows the strikethrough on its PDP.
+- Opening a variant product in the admin does NOT raise the save bar.
+- `/faq`, `/terms`, `/privacy` render in French on a fr-default store.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rovela-ai/sdk",
-  "version": "0.19.8",
+  "version": "0.21.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

@@ -191,6 +191,25 @@ Active state is auto-detected from the URL — no extra config needed.
 | Admin API auth check with `getServerSession` | Admin pages are already protected by `AdminGuard` layout |
 | Forgot admin sidebar item | If feature has admin page, MUST add `navItems` to AdminLayout in layout.tsx |
 
+## External-service credentials (integrations)
+
+If the feature connects to an external service (API key, secret, tracking ID):
+
+- Persist credentials to `store_settings` — dedicated columns for secrets (`ALTER TABLE store_settings ADD COLUMN IF NOT EXISTS …`, read server-side at request time; NEVER `.env.local`, NEVER `NEXT_PUBLIC_`), or the `analytics` JSONB for public tracking IDs.
+- The merchant manages them at `/admin/integrations` (SDK page, already mounted). **Do NOT build a settings page, credentials form, or nav entry for keys.**
+- Known keys are auto-rendered (brevo, paypal, turnstile, ga4, google_ads, meta, tiktok, klaviyo, intercom, trustpilot). A NOVEL integration registers a descriptor (dedup by key, then append):
+
+```sql
+ALTER TABLE store_settings ADD COLUMN IF NOT EXISTS custom_integrations jsonb NOT NULL DEFAULT '[]'::jsonb;
+UPDATE store_settings SET custom_integrations =
+  (SELECT COALESCE(jsonb_agg(e), '[]'::jsonb)
+     FROM jsonb_array_elements(custom_integrations) e
+    WHERE e->>'key' <> '<key>')
+  || jsonb_build_array('{"key":"<key>","label":"<Label>","fields":[{"id":"<store_settings_column>","label":"API key","secret":true,"required":true}]}'::jsonb);
+```
+
+Field `id`s = the store_settings column names (ALTERed first); mark secrets `"secret": true`. Tell the merchant credentials live under **Configuration → Integrations**.
+
 ## Checklist
 
 - [ ] Tables created and verified with `list_objects`

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/app/admin/(dashboard)/integrations/page.tsx

@@ -0,0 +1,17 @@
+'use client'
+
+/**
+ * Admin Integrations Page
+ *
+ * Credentials for the external services connected to this store (Brevo,
+ * PayPal, analytics pixels, chat-installed custom integrations…). The
+ * IntegrationsManager renders the page header itself — this wrapper stays a
+ * bare mount. Installing or removing an integration is a Features Store /
+ * chat action on the Rovela platform; this page manages what is installed.
+ */
+
+import { IntegrationsManager } from '@rovela-ai/sdk/admin'
+
+export default function AdminIntegrationsPage() {
+  return <IntegrationsManager />
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Admin Integrations API Route
+ *
+ * GET /api/admin/integrations - Installed integrations with masked secrets
+ * PUT /api/admin/integrations - Save one integration's credentials/settings
+ *                               (provider-validated before persisting)
+ */
+
+export { getIntegrations as GET, saveIntegration as PUT } from '@rovela-ai/sdk/admin/api'

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/app/faq/page.tsx

@@ -1,6 +1,6 @@
-import { localizedAlternates, getRequestLocale } from '@rovela-ai/sdk/core/server'
 import type { Metadata } from 'next'
-import { LocaleLink as Link, getT } from '@rovela-ai/sdk/core'
+import { localizedAlternates, getRequestLocale } from '@rovela-ai/sdk/core/server'
+import { LocaleLink as Link, getT, intlLocaleFor } from '@rovela-ai/sdk/core'
 import { findSettings } from '@rovela-ai/sdk/core/server'
 import { buildFaqJsonLd, serializeJsonLd } from '@rovela-ai/sdk/core'
 import { storeConfig } from '@/lib/store-config'
@@ -19,9 +19,14 @@ import {
  *
  * Server Component (no 'use client') so the schema + content are in the initial
  * HTML — AI crawlers don't execute JavaScript.
+ *
+ * Every Q&A body comes from the i18n catalogs (they were English literals
+ * pre-0.21, which shipped an English FAQ on French-default stores). Country
+ * names + list joining use Intl.DisplayNames / Intl.ListFormat so they
+ * localize without a hand-maintained map.
  */
 
-export async function generateMetadata() {
+export async function generateMetadata(): Promise<Metadata> {
   const { locale } = await getRequestLocale()
   const t = getT(locale)
   return {
@@ -31,30 +36,22 @@ export async function generateMetadata() {
   }
 }
 
-const COUNTRY_NAMES: Record<string, string> = {
-  US: 'the United States',
-  CA: 'Canada',
-  GB: 'the United Kingdom',
-  AU: 'Australia',
-  NZ: 'New Zealand',
-  IE: 'Ireland',
-  DE: 'Germany',
-  FR: 'France',
-  ES: 'Spain',
-  IT: 'Italy',
-  NL: 'the Netherlands',
-}
-
-function formatCountries(codes: string[]): string {
-  const names = codes.map((c) => COUNTRY_NAMES[c] || c)
-  if (names.length === 1) return names[0]
-  if (names.length === 2) return `${names[0]} and ${names[1]}`
-  return `${names.slice(0, -1).join(', ')}, and ${names[names.length - 1]}`
+function formatCountries(codes: string[], intlLocale: string): string {
+  const display = new Intl.DisplayNames([intlLocale], { type: 'region' })
+  const names = codes.map((c) => {
+    try {
+      return display.of(c) || c
+    } catch {
+      return c
+    }
+  })
+  return new Intl.ListFormat(intlLocale, { style: 'long', type: 'conjunction' }).format(names)
 }
 
 export default async function FaqPage() {
   const { locale } = await getRequestLocale()
   const t = getT(locale)
+  const intlLocale = intlLocaleFor(locale)
   const settings = await findSettings().catch(() => null)
 
   const countries = shipsToCountries(settings)
@@ -67,49 +64,38 @@ export default async function FaqPage() {
 
   const faqs: Array<{ question: string; answer: string }> = [
     {
-      question: 'What payment methods do you accept?',
+      question: t('faqPage.q.payment'),
+      answer: t('faqPage.a.payment'),
+    },
+    {
+      question: t('faqPage.q.countries'),
+      answer: t('faqPage.a.countries', { countries: formatCountries(countries, intlLocale) }),
+    },
+    {
+      question: t('faqPage.q.shippingCost'),
       answer:
-        'We accept major credit and debit cards through our secure checkout. Your payment details are encrypted and handled by our payment provider — we never store full card numbers.',
+        freeThreshold > 0
+          ? t('faqPage.a.shippingCostFree', { threshold: freeThreshold, currency })
+          : t('faqPage.a.shippingCost'),
     },
     {
-      question: 'Which countries do you ship to?',
-      answer: `We currently ship to ${formatCountries(countries)}.`,
+      question: t('faqPage.q.delivery'),
+      answer: t('faqPage.a.delivery', { processing }),
     },
-    freeThreshold > 0
-      ? {
-          question: 'How much does shipping cost?',
-          answer: `Shipping is calculated at checkout based on your address. Orders over ${freeThreshold} ${currency} qualify for free shipping.`,
-        }
-      : {
-          question: 'How much does shipping cost?',
-          answer:
-            'Shipping is calculated at checkout based on your delivery address and the items in your order.',
-        },
     {
-      question: 'How long will my order take to arrive?',
-      answer: `Orders are typically processed within ${processing} business days and then shipped. Delivery time depends on your location and the carrier.`,
+      question: t('faqPage.q.returns'),
+      answer:
+        returnDays > 0
+          ? t('faqPage.a.returns', { days: returnDays })
+          : t('faqPage.a.noReturns'),
     },
-    returnDays > 0
-      ? {
-          question: 'What is your return policy?',
-          answer: `You can return unused items in their original condition within ${returnDays} days of delivery. Return shipping is the customer's responsibility unless the item arrived damaged or incorrect.`,
-        }
-      : {
-          question: 'What is your return policy?',
-          answer:
-            'All sales are final. If your item arrives damaged or incorrect, contact us right away and we will make it right.',
-        },
     {
-      question: 'Do I need an account to place an order?',
-      answer: guestCheckout
-        ? 'No account is required — you can check out as a guest. Creating an account lets you track orders and check out faster next time.'
-        : 'Please create an account at checkout so you can track your order and manage returns.',
+      question: t('faqPage.q.account'),
+      answer: guestCheckout ? t('faqPage.a.accountGuest') : t('faqPage.a.accountRequired'),
     },
     {
-      question: 'How can I contact you?',
-      answer: email
-        ? `Email us at ${email} and we'll get back to you as soon as we can. You can also use our contact page.`
-        : `Reach us through our contact page and we'll get back to you as soon as we can.`,
+      question: t('faqPage.q.contact'),
+      answer: email ? t('faqPage.a.contactEmail', { email }) : t('faqPage.a.contactPage'),
     },
   ]