toga-ai 1.0.215 → 1.0.216

package/knowledge/2.0/apps/worker2/INDEX.md

@@ -8,6 +8,8 @@
 | [ClickUp Work Type Automation (Committed / Conditional / Stretch)](features/clickup-work-type-automation.md) | The ClickUp webhook handler (`_Worker_Clickup`) automatically maintains each task's **Work Type** custom field — `Committed`, `Conditional`, or `Stretch` — base | worker2/Worker/Clickup.php, worker2/Tests/Worker/ClickupWorkTypeTest.php |
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |
+| [Etilize Catalog Item Import & Refresh](features/etilize-catalog-item-import.md) | Client-generic catalog onboarding from an S3 CSV plus an Etilize re-pull. | worker2/Worker/Etilize/Items.php |
+| [Etilize Item Translation Import](features/etilize-item-translation-import.md) | The abstract worker class `_Worker_Etilize_ItemTranslations` imports **non-English** item text from Etilize into the client's `ItemTranslations` table. | worker2/Worker/Etilize/ItemTranslations.php |
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Notification/Email.php, dbchanges2/Core/2026-05-21 - Monitors.sql |
 | [NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, test/@dave/test_model_load_behavior.php, dbchanges2/Forecast/2026-06-25a - Add unique index on Opportunities netsuiteOpportunityInternalId.sql, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_open_order_gating.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |

package/knowledge/2.0/apps/worker2/features/etilize-catalog-item-import.md

@@ -0,0 +1,105 @@
+---
+title: Etilize Catalog Item Import & Refresh
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-26
+owners: [bala]
+files:
+  - worker2/Worker/Etilize/Items.php
+related:
+  - ./creating-worker-actions.md
+  - ./etilize-item-translation-import.md
+---
+
+## Summary
+
+Client-generic catalog onboarding from an S3 CSV plus an Etilize re-pull. The
+abstract worker class `_Worker_Etilize_Items` ingests an item catalog (items, vendor
+items, costs, prices, personas) and enriches each item with features and images from
+the Etilize datasheet. All three actions write **directly to `DB_CLIENT`** via raw
+`_Query` — there is **no api2 round-trip**. Used today by **Compass Canada** (single
+price) and **Quad** (multi-currency), but nothing in the code is client-specific.
+
+## Public actions
+
+Routes are `Etilize/Items/<Method>` (see [creating-worker-actions](./creating-worker-actions.md)).
+
+1. `ImportItemsFromCsvFile(string $client, string $s3Url, string $catalogUuid)`
+   — **normal import**: one `ItemPrice` + `VendorItemCost` per item with **NULL
+   currency**, using the Cost / Lease Price columns (e.g. Compass).
+2. `ImportItemsWithCurrencyPricesFromCsvFile(string $client, string $s3Url, string $catalogUuid)`
+   — **per-currency import**: each currency-coded column becomes its own
+   `ItemPrice` + `VendorItemCost` (e.g. Quad).
+3. `RefreshItemsFromEtilize(string $client, array $items, ?string $catalog = null)`
+   where `items = [{partNumber, etilizeId}]` — looks each item up by `partNumber`
+   and, only if its stored `c_etilizeProductId` differs from the supplied `etilizeId`,
+   updates it and re-pulls the item's features + images from the Etilize datasheet.
+   Returns a per-item changed/unchanged summary.
+
+## How the import works
+
+Both import actions delegate to the shared private
+`runItemCsvImport(..., bool $useCurrencyPrices)` — `useCurrencyPrices` is the only
+difference between the two public entry points.
+
+1. **Setup** — resolve `clientId` from `Core.Clients` by `clientIdentifier`, register
+   the client DB, and resolve `catalogId` from `catalogUuid` against the `Catalogs` table.
+2. **Download & parse CSV** — pulled from S3 with `_Cloud::getFileFromS3`. **Row 1 =
+   headers, row 2 = a field-description row that is skipped, data starts at row 3.**
+   Columns are mapped **by header name** via case-insensitive regex patterns, so clients
+   whose columns are in a **different order** both work (Compass vs. Quad) — order is never
+   assumed.
+3. **Per data row, find-or-create:**
+   - the **Item** — resolving `manufacturerId` / `itemCategoryId` / `itemTypeId` /
+     `assetTypeId` by name via a generic find-or-create over `Manufacturers`,
+     `ItemCategories`, `ItemTypes`, `AssetTypes`; set in the catalog with flags.
+   - the **VendorItem** — vendor resolved by name; `overridePoSubmissionIntegrationId`
+     left NULL.
+   - **pricing** — either a single NULL-currency row, or one row per currency column
+     (see Multi-currency below).
+   - **personas** — each CSV persona token resolved by numeric id **or** by name against
+     `Personas`, linked through the `Personas_Items` bridge table.
+4. **Etilize enrichment** (from the `getProduct` datasheet):
+   - **features** → `Features` (find-or-create by name, Text measure) + `ItemFeatures` +
+     `ItemCategoryFeatureGroups` + `ItemCategoryFeatures`.
+   - **images** → `Images` (find-or-create by `sourceUrl`) + a single `ItemImages` row
+     holding the four size-slot FKs: thumbnail / low / medium / high mapped to Etilize
+     sizes **160 / 225 / 650 / 900**.
+
+## Multi-currency
+
+- The set of **valid currency codes is read per-client at runtime** from that client's own
+  `Currencies` table via `loadClientCurrencyCodes()` — **never hardcoded** — so each client
+  only uses the currencies it actually has configured.
+- A small **alias map** normalizes CSV header spellings to the real `Currencies.code`
+  (e.g. a `PER` header → `PEN`).
+- A CSV currency column is used **only if** its normalized code matches one of the client's
+  configured currencies. For each match the import creates an `ItemPrice` + `VendorItemCost`
+  with that `currencyId` (`priceType` `each`).
+
+## Etilize re-pull (`RefreshItemsFromEtilize`)
+
+- Item located by `partNumber`. The Etilize id is updated **only when** the supplied
+  `etilizeId` differs from the stored `c_etilizeProductId`.
+- The feature/image re-pull is **find-or-create** and **does not delete stale features**
+  — this is intentional.
+
+## Gotchas
+
+- CSV layout is fixed at the top: header row, a **skipped** description row, then data
+  from row 3. Feeding a two-row (header+data) file would treat the first data row as the
+  description row.
+- Columns are matched by header regex, not position — a renamed/missing header silently
+  drops that column rather than mis-mapping by index.
+- Currency columns not present in the client's `Currencies` table are ignored, so a
+  catalog that ships an unconfigured currency simply won't price it.
+
+## Change history
+- 2026-06-26 — Documented `_Worker_Etilize_Items`: header-mapped S3 CSV import with
+  shared `runItemCsvImport`, normal (NULL-currency) vs. per-currency pricing, per-client
+  runtime currency resolution, persona linking, Etilize feature/image enrichment, and the
+  id-diff-only `RefreshItemsFromEtilize` re-pull. (bala)

package/knowledge/2.0/apps/worker2/features/etilize-item-translation-import.md

@@ -0,0 +1,69 @@
+---
+title: Etilize Item Translation Import
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-26
+owners: [bala]
+files:
+  - worker2/Worker/Etilize/ItemTranslations.php
+related:
+  - ./creating-worker-actions.md
+  - ./etilize-catalog-item-import.md
+---
+
+## Summary
+
+The abstract worker class `_Worker_Etilize_ItemTranslations` imports **non-English**
+item text from Etilize into the client's `ItemTranslations` table. English is never
+written — it stays in the `Items` table. The class writes **directly to `DB_CLIENT`**
+via raw `_Query` (**no api2**). Used today to give **Compass Canada** French (fr-CA)
+catalog text without duplicating English, but the code is client-generic.
+
+`ItemTranslations` columns: `itemId`, `languageId`, `title`, `description`,
+`longDescription`, with `UNIQUE(itemId, languageId)`.
+
+## Public actions
+
+Routes are `Etilize/ItemTranslations/<Method>` (see
+[creating-worker-actions](./creating-worker-actions.md)).
+
+1. `ImportAllItemsForLanguage(string $client, string $languageCode, ?string $languageName = null, ?string $catalog = null)`
+   — translates **all** items that have a `c_etilizeProductId`.
+2. `ImportItemsLanguageByPartNumbers(string $client, string $languageCode, array $partNumbers, ?string $languageName = null, ?string $catalog = null)`
+   — translates only the given part numbers (uses a `partNumber IN (...)` filter).
+
+## How it works
+
+1. Resolve `clientId` from `Core.Clients` by `clientIdentifier` and register the client DB.
+2. **Find-or-create the Language** by `code` (e.g. `fr-CA`).
+3. **Derive the Etilize locale** from the language code: `fr-CA` → `fr_ca` (lowercased,
+   hyphen → underscore).
+4. Load the client's `Items` that have a **non-empty `c_etilizeProductId`** (scoped to the
+   given part numbers for the by-part-numbers action).
+5. For each item, call the Etilize **Spex Live `getProduct`** API (`appId` 231136, catalog
+   default `na`) for that locale.
+6. Extract the translated **`title`** (Etilize description **type 2**) and
+   **`longDescription`** (Etilize description **type 1**).
+7. **Upsert** into `ItemTranslations` via `INSERT ... ON DUPLICATE KEY UPDATE` using
+   `COALESCE(VALUES(col), col)` so a blank new value never overwrites existing text.
+
+Items **not published in the requested locale are skipped**.
+
+## Gotchas
+
+- The unique key is `(itemId, languageId)`; re-running an import upserts rather than
+  duplicating, and the `COALESCE` guard means a blank Etilize value will not clear an
+  existing translation.
+- Only items with a `c_etilizeProductId` are translatable — items without an Etilize id
+  are silently skipped.
+- English is intentionally never written here; it lives in the `Items` table.
+
+## Change history
+- 2026-06-26 — Documented `_Worker_Etilize_ItemTranslations`: per-language Etilize
+  `getProduct` import into `ItemTranslations` (title=desc type 2, longDescription=type 1),
+  locale derived from language code, COALESCE upsert that never overwrites with blanks,
+  all-items vs. by-part-numbers actions. (bala)

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 16 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 15 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 17 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 7 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

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

@@ -7,12 +7,13 @@ apps:
   - toga2-supply
   - toga2-commerce
   - worker
+  - worker2
   - dbchanges2
 project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-06-19
+updated: 2026-06-26
 owners: [jcardinal, bala]
 files: []
 related:

package/knowledge/clients/quad/profile.md

@@ -6,13 +6,14 @@ apps:
   - api2
   - toga2-supply
   - toga2-commerce
+  - worker2
   - dbchanges2
 project: _Underscore
 client: quad
 type: profile
 status: active
-updated: 2026-06-19
-owners: ["jcardinal"]
+updated: 2026-06-26
+owners: ["jcardinal", "bala"]
 files: []
 related:
   - ../../2.0/apps/_underscore/features/tracking-number-bridges.md

package/package.json

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