toga-ai 1.0.314 → 1.0.316

package/knowledge/1.0/apps/library/features/elite-freshservice-sync.md

@@ -6,7 +6,7 @@ project: Library
 client: elite
 type: client-feature
 status: active
-updated: 2026-06-15
+updated: 2026-07-10
 owners: ["snaredla"]
 files:
   - library/app/api/toga2.php
@@ -165,5 +165,49 @@ Pass `true` for the dedup GET — errors must not silently empty the dedup array
 Each ticket sync is wrapped in `try/catch` — exceptions are sent to Sentry and the run
 continues with the next ticket. A single bad ticket does not abort the whole sync.
 
+## Elite-specific sync behaviour
+
+### Department assignment (TOGaDesk → TOGA 2)
+Elite tickets use `c_togadeskDepartmentId` on `Client_Elite.TicketTeams` to reverse-lookup the correct Toga2 team from TOGaDesk's actual `departmentid`. CF84 (custom field storing team name) is **never** updated when an agent manually transfers a ticket between TOGaDesk departments via the UI — so it cannot be used as the sync source for team.
+
+Lookup in `syncTogaDesk1TicketIntoToga2Ticket`:
+```php
+$eliteTeamLookupOptions = [
+    'where' => ['and' => [['c_togadeskDepartmentId' => ['=' => (int) $togadeskTicket->departmentid]]]]
+];
+$eliteTeamResult = App_Api_Toga2::send(..., 'GET', '/ticket-teams', null, $eliteTeamLookupOptions, ...);
+if ($eliteTeamResult->meta->totalRecordCount == 1) {
+    $payload['ticketTeam'] = ['uuid' => $eliteTeamResult->data->ticketTeams[0]->uuid];
+}
+```
+
+**Pending DB migration** — `c_togadeskDepartmentId INT NULL` must be added to `Client_Elite.TicketTeams` with team→dept mappings before this lookup works.
+
+### Timestamp guard (prevents overwriting Freshservice changes)
+Before pushing any field update (priority, status, category, group, type) to Freshservice, the sync compares timestamps:
+```php
+$eliteOriginalUpdatedAt = ... strtotime($eliteTicket->updated_at) ...;  // captured BEFORE reply POSTs
+$togadeskUpdatedAt = strtotime($togadeskLastModified);
+$togadeskUpdateIsMoreRecent = ($togadeskUpdatedAt > $eliteOriginalUpdatedAt);
+```
+Nothing is written to Freshservice unless TOGaDesk is strictly newer. Safe to reset `TOGA_LAST_TICKET_INTEGRATION_DATETIME` for re-sync — Freshservice changes are protected.
+
+### Reply status badge mapping
+`tickets_replies.newStatus` is set from `$ticketNote->ticketStage->code` when a reply is synced in. Elite code → TOGaDesk status:
+
+| Freshservice code | TOGaDesk status |
+|---|---|
+| 2 | Open |
+| 3 | Awaiting User |
+| 6 | In Progress |
+| 4 | Resolved |
+| 5 | Closed |
+
+**Gotcha:** `case 2` was previously mapped to `STATUS__NEW_TICKET` (wrong) — fixed 2026-07-10. Replies from Freshservice with status "Open" were showing "New Ticket" badge in TOGaDesk.
+
+### Variable name pollution gotcha
+The Elite team lookup block inside `syncTogaDesk1TicketIntoToga2Ticket` must use its own dedicated options variable (`$eliteTeamLookupOptions`) — never reuse `$method`, `$route`, `$payload`, or `$options`. Those shared variables are consumed by the `send()` call immediately after the block. Reusing them causes the wrong endpoint to be called, resulting in a Sentry crash: `Undefined property: stdClass::$tickets`.
+
 ## Change history
 - 2026-06-10 — Documented `App_Api_Toga2::syncWithTogadesk` orchestration (bidirectional TOGA 2 ↔ TOGaDesk ticket/note/file sync, watermarks, `ticketNoteFiles` gotcha). (snaredla)
+- 2026-07-10 — Added Elite-specific section: department reverse-lookup via `c_togadeskDepartmentId`, timestamp guard, reply status badge mapping fix (`case 2` → Open), variable pollution gotcha. (snaredla)

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

@@ -6,7 +6,7 @@
 | [Cart Bundle Submission & the bundleUuid Identity Contract](features/cart-bundle-submission-and-identity.md) | How cart **bundles** (kits) are turned into `SalesOrderItems` when a cart is submitted or an existing order is edited, and the **identity-field contract** every | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts, src/utils/formatSalesOrderBundlesFromApi.ts, src/stores/useCartStoreZu.ts, src/pages/OrderDetails/helpers/formatSalesOrderDataFromLocalStorage.ts, src/pages/OrderDetails/view/components/OrderItems.tsx |
 | [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 |
 | [Cart Page — config-driven form architecture (current state + planned refactor)](features/cart-page-config-architecture.md) | The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/pages/Cart/view/cartForm/CartFormSection.tsx, src/pages/Cart/view/cartForm/CartFormRenderer.tsx, src/pages/Cart/view/EditCart.tsx, src/pages/Cart/view/EditOrder.tsx, src/pages/Cart/viewModel/useEditOrderOrEditCartViewModel.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts, src/hooks/useAssignClientFields.ts |
-| [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx |
+| [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/pages/Cart/api/CartApi.ts, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx |
 | [Config-Driven Expedited Shipping Gating (Cart)](features/expedited-shipping-gating.md) | On the toga2-commerce **Cart** page, expedited shipping options (**"2nd Day EOB"** and **"Next Day Air"**) are only offered in the *Shipping Method* dropdown wh | toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/CartPage.tsx |
 | [Multi-Tenant Resolution & Theming](features/multi-tenant-theming.md) | `toga2-commerce` serves multiple clients from one codebase. | src/themeConfig/themes.json, src/themeConfig/ThemeContext.tsx, src/themeConfig/types.ts, src/components/ThemeSwitcher/ThemeSwitcher.tsx, src/components/AuthLayout/AuthLayout.tsx, src/api/axiosInstance.ts, src/contexts/AuthContext.tsx, tailwind.config.js |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-commerce` (React + Vite, "commerce2-react") builds and deploys on **AWS Amplify**. | toga2-commerce/amplify.yml, toga2-commerce/.gitattributes, toga2-commerce/package.json, toga2-commerce/.github/workflows/sync-stage-environments.yml |

package/knowledge/2.0/apps/toga2-commerce/features/client-fields.md

@@ -6,14 +6,15 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
-owners: ["apeterson"]
+updated: 2026-07-10
+owners: ["apeterson", "tcox"]
 files:
   - src/fieldsConfig/index.ts
   - src/fieldsConfig/getClientLoginFields.ts
   - src/fieldsConfig/clientFields/COMPASS.json
   - src/fieldsConfig/clientFields/COMPASSCANADA.json
   - src/fieldsConfig/clientFields/QUAD.json
+  - src/pages/Cart/api/CartApi.ts
   - src/hooks/useAssignClientFields.ts
   - src/hooks/useDynamicConditionalFieldOptions.ts
   - src/stores/useFieldsStore.ts
@@ -43,7 +44,8 @@ resolved per tenant, per language, and per role**. There are **two layers**:
 ```json
 {
   "languageSwitcher": { "uuid": "1", "isEnabled": true|false },
-  "userApiFields": ["firstName", "lastName", "email", "uuid", "_isAdmin", ...]
+  "userApiFields": ["firstName", "lastName", "email", "uuid", "_isAdmin", ...],
+  "fetchUsersApiFields": ["firstName", "lastName", "email", "uuid", ...]
 }
 ```
 
@@ -52,11 +54,31 @@ resolved per tenant, per language, and per role**. There are **two layers**:
 - `userApiFields` — the allow-list of user columns fetched at login; importantly it includes the
   tenant's **role flags**: COMPASS/COMPASSCANADA carry `_isAdmin`, `_isSupervisor`, `_isSuperAdmin`;
   QUAD carries `_isGlobalAdmin`, `_isItShopper`, `_isBuyer`. All include `_personaIds`.
+- `fetchUsersApiFields` — the allow-list of user columns fetched by the **view-as user search**
+  (`fetchUsers()` in `src/pages/Cart/api/CartApi.ts`, driven from `NavIconList.tsx`). Distinct from
+  `userApiFields` (which is the login fetch). COMPASS/COMPASSCANADA use the 14-field default list;
+  **QUAD uses an 8-field list that intentionally omits `supervisorUser.*`** (see gotcha).
 
 Resolved by **`src/fieldsConfig/getClientLoginFields.ts`** — a `switch(client)` returning the JSON;
 **default is `COMPASS`** (not DEFAULT). Called from `AuthContext` as `getClientLoginFields(host)`.
 The `languageSwitcher.isEnabled` value feeds the login-settings branch in `getLoginSettings.ts`.
 
+### `fetchUsersApiFields` and the config-driven view-as search (C6)
+
+`fetchUsers()` in `src/pages/Cart/api/CartApi.ts` no longer hardcodes its field list. It resolves it
+via `getClientLoginFields(fieldKey ?? "").fetchUsersApiFields`, replacing a former
+`if (fieldKey === "QUAD")` client-name branch — this honors the Cart "no `if (client === ...)`,
+drive client behavior from config" rule (**C6** in
+[cart-page-config-architecture](cart-page-config-architecture.md)). An unknown/missing `fieldKey`
+falls back to COMPASS inside `getClientLoginFields` (same as the old `else` branch). Because the
+tenant JSONs are **statically imported**, a tenant missing `fetchUsersApiFields` is a TypeScript
+compile error — not a silent empty fetch — so the list is client-editable via config without
+touching Cart code.
+
+**Follow-up candidate (not yet done):** `fetchUser()` (singular, same `CartApi.ts`) still holds the
+same hardcoded QUAD-vs-default field-list pattern and is a candidate for the identical config
+treatment in a future ticket.
+
 ## Layer B — the per-page FIELDS registry
 
 `src/fieldsConfig/index.ts` (~1100 lines) imports every page's per-tenant field constants (which
@@ -179,10 +201,22 @@ Common field attributes: `uuid`, `label`, `valueKey` (path into the data object)
 - Role is derived from string `"1"` flags on the user (`user?._isAdmin === "1"`), not booleans.
 - `getClientLoginFields` defaults to **COMPASS** for an unknown host, which can mask a
   misconfigured tenant in local dev.
+- **QUAD's `fetchUsersApiFields` omits `supervisorUser.*` on purpose — do not "fix" it to match
+  COMPASS.** A code-review bot flagged the mismatch, but it is correct: the original hardcoded QUAD
+  `fetchUsers` branch never requested supervisor fields; only `fetchUser()` (the detail fetch) does,
+  and the sole `fetchUsers` caller (view-as search in `NavIconList.tsx`) gets full detail from
+  `fetchUser()` after selection. QUAD also uses the `_isGlobalAdmin`/`_isBuyer`/`_isItShopper` role
+  model, not the supervisor hierarchy. Aligning the two lists would smuggle a behavior change into a
+  refactor.
 
 ## Change history
 - 2026-06-23 — Initial: documented the two-layer field system (global `clientFields/<TENANT>.json`
   + the per-page `FIELDS` registry), the `tenant→language→role` resolution in `useAssignClientFields`,
   the `en`/`fr` vs `ENGLISH`/`FRENCH` distinction, role derivation per tenant, and field JSON shapes
   (apeterson)
+- 2026-07-10 — Added the Layer A `fetchUsersApiFields` key: moved the hardcoded `fetchUsers()`
+  field lists out of `CartApi.ts` into each tenant JSON (COMPASS/COMPASSCANADA = 14-field default,
+  QUAD = 8-field), replacing the `if (fieldKey === "QUAD")` branch with a config lookup (C6). Noted
+  the deliberate QUAD `supervisorUser.*` omission and the `fetchUser()` follow-up candidate. Refactor
+  only, no behavior change; `tsc --noEmit` clean. (tcox)
 </content>

package/package.json

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