toga-ai 1.0.123 → 1.0.124

package/knowledge/2.0/apps/toga2-commerce/INDEX.md

@@ -0,0 +1,5 @@
+# toga2-commerce (TOGa Commerce) — 2.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/stores/useEmailOptionsStore.ts, src/stores/useCartSalesQuoteZu.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts |

package/knowledge/2.0/apps/toga2-commerce/features/cart-notification-emails.md

@@ -0,0 +1,79 @@
+---
+title: Cart Notification Emails — duplicate prevention
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-06-18
+owners: ["bala"]
+files:
+  - src/pages/Cart/CartPage.tsx
+  - src/pages/Cart/view/cartForm/CartForm.tsx
+  - src/stores/useEmailOptionsStore.ts
+  - src/stores/useCartSalesQuoteZu.ts
+  - src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts
+related: []
+---
+
+## Summary
+On the cart "Notifications" section a user can add CC email addresses to an order. Adding the
+same address twice (often with different casing) used to slip through to the API and blow up on
+submit with a MySQL 1062 duplicate-key error on the `SalesOrderEmailAddresses.salesOrderId_emailAddress`
+unique index (whose collation `utf8mb4_0900_ai_ci` is case-insensitive). This feature blocks
+duplicates case-insensitively in the frontend and shows a sapphire info message instead of letting
+the error reach the user.
+
+## Key files / entry points
+- `CartPage.tsx` — `handleAddEmail`: validates the email regex, then on success calls
+  `addEmailOption` (UI options list) and `addEmail` (the cart sales-quote store that builds the
+  `salesOrderEmailAddresses` payload). Normalizes the input once with `.trim()`.
+- `CartForm.tsx` — owns the duplicate UX. `handleAddEmailWithDuplicateCheck` wraps the passed-in
+  `handleAddEmail`: it case-insensitively checks the existing `emails` list and, on a match, shows
+  the message instead of adding. The **Add Email** button calls this wrapper.
+- `useEmailOptionsStore.ts` — `addEmailOption` de-dupes the checkbox list.
+- `useCartSalesQuoteZu.ts` — `addEmail` de-dupes the actual `salesOrderEmailAddresses` payload.
+
+## How it works
+1. **Before (manual add):** clicking Add Email runs `handleAddEmailWithDuplicateCheck` in
+   `CartForm`. It compares `(e.email ?? "").trim().toLowerCase()` against the normalized input. On a
+   match it sets `duplicateEmailMessage` and returns (does not add).
+2. **After (auto-add on user select):** when the order user is chosen, their email (and manager's)
+   is auto-added via `addEmailOption`. Both stores de-dupe case-insensitively, so a case-variant of
+   an already-present address is silently dropped rather than duplicated.
+3. **Display:** the message renders via the shared `InfoBanner` component (the same one used for the
+   "view as" / "edit order" banners), styled `text-sapphire-700 text-xs`, no icon. It is NOT a
+   toaster and NOT a red `setError` validation — it is a sapphire info message.
+4. The message text comes from the `notifications.duplicateEmailAddressError.label` field config,
+   present in every `CARTPAGE.ts` (all client/role/language variants, English + French).
+5. A `useEffect` clears the message when the input, selected user (`orderForUser?.uuid`), or email
+   list (`emails.length`) changes.
+
+## Data model
+Frontend only. The payload list maps to the `SalesOrderEmailAddresses` table (api2/backend), which
+has a case-insensitive unique index on `(salesOrderId, emailAddress)`.
+
+## Client variations
+The de-dupe mechanism is uniform across clients. Only the message label text differs per client
+config: English `"This email has already been added"`; French (Compass Canada)
+`"Cette adresse e-mail a déjà été ajoutée"`. The label must exist in every `CARTPAGE.ts` variant or
+the message resolves to `undefined` and renders blank.
+
+## Gotchas / known issues
+- The real source of the 1062 was `useCartSalesQuoteZu.addEmail` comparing with `===`
+  (case-sensitive). Both stores must compare case-insensitively; fixing only the UI list is not
+  enough because `addEmail` builds the payload.
+- Normalize with `(x ?? "").trim().toLowerCase()`, not `x?.trim().toLowerCase()` — both are
+  nullish-safe (optional chaining short-circuits the whole chain, it does not throw), but `(x ?? "")`
+  guarantees a string and avoids an `undefined === undefined` match edge.
+- Adding the label to only some `CARTPAGE.ts` files leaves other client/role/language users with a
+  blank message.
+- Do not use a toaster or `setError` (red) for this — product wants the sapphire info style.
+
+## Change history
+- 2026-06-18 — Initial: case-insensitive de-dupe in both cart stores, sapphire `InfoBanner` message in
+  CartForm, `duplicateEmailAddressError` label added to all CARTPAGE.ts variants (bala)
+
+## Related docs
+None yet.

package/knowledge/INDEX.md

@@ -25,6 +25,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos** (TOGa IQ) — 6 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 1 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 
 ## standalone framework
 

package/knowledge/clients/compass-canada/profile.md

@@ -5,14 +5,15 @@ apps:
   - _underscore
   - api2
   - toga2-supply
+  - toga2-commerce
   - worker
   - dbchanges2
 project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-06-08
-owners: [jcardinal]
+updated: 2026-06-18
+owners: [jcardinal, bala]
 files: []
 related:
   - ../compass-usa/profile.md

package/knowledge/clients/compass-usa/profile.md

@@ -5,14 +5,15 @@ apps:
   - _underscore
   - api2
   - toga2-supply
+  - toga2-commerce
   - worker
   - dbchanges2
 project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-06-08
-owners: [jcardinal]
+updated: 2026-06-18
+owners: [jcardinal, bala]
 files: []
 related:
   - features/asn-to-item-fulfillment.md

package/knowledge/registry.json

@@ -152,5 +152,12 @@
     "framework": "standalone",
     "role": "app",
     "dependsOn": []
+  },
+  {
+    "repo": "toga2-commerce",
+    "project": "TOGa Commerce",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": ["api2"]
   }
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.123",
+  "version": "1.0.124",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",