toga-ai 1.0.146 → 1.0.147

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

@@ -2,4 +2,5 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [Grand & Toy ASN Import (Compass Canada)](features/grand-and-toy-asn-import.md) | 2.0 | Imports Grand & Toy (G&T) Advance Shipping Notices for Compass Canada. | worker/crons/toga2/compasscanada/workflow/4_import_grand_and_toy_advance_shipping_notices.php, worker/crons/toga2/compasscanada/workflow/import_grand_and_toy_asn_from_file.php, worker/schedules/cron.worker.sync.json, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Model/Compass/Canada/AdvanceShippingNotice.php, dbchanges2/Client_CompassCanada/ |
 | [Compass Canada](profile.md) | 2.0 | Compass Canada is the Canadian arm of the Compass account — a separate TOGA tenant, related to but distinct from Compass USA. |  |

package/knowledge/clients/compass-canada/features/grand-and-toy-asn-import.md

@@ -0,0 +1,105 @@
+---
+title: Grand & Toy ASN Import (Compass Canada)
+framework: "2.0"
+project: _Underscore
+client: compass-canada
+type: client-feature
+status: active
+updated: 2026-06-19
+owners: ["bala"]
+files:
+  - worker/crons/toga2/compasscanada/workflow/4_import_grand_and_toy_advance_shipping_notices.php
+  - worker/crons/toga2/compasscanada/workflow/import_grand_and_toy_asn_from_file.php
+  - worker/schedules/cron.worker.sync.json
+  - _underscore/Model/Compass/AdvanceShippingNotice.php
+  - _underscore/Model/Compass/Canada/AdvanceShippingNotice.php
+  - dbchanges2/Client_CompassCanada/
+related:
+  - ../profile.md
+---
+
+## Summary
+Imports Grand & Toy (G&T) Advance Shipping Notices for Compass Canada. A 1.0 worker cron reads
+G&T's ASN CSV from a mailbox, posts each shipped line to the 2.0 API as an AdvanceShippingNotice
+(ASN); a Compass interceptor then auto-creates the ItemFulfillment chain, and the customer gets
+an in-transit email in English or French. It mirrors the Compass USA ODP / Strategic-Systems ASN
+flow, adapted for Canadian carriers and bilingual email.
+
+## Key files / entry points
+- `worker/crons/toga2/compasscanada/workflow/4_import_grand_and_toy_advance_shipping_notices.php`
+  — the scheduled cron (1.0 worker tier). Reads mailbox `compasscanada.status@togatech.com`
+  (OAuth2 creds in config `[compasscanada]`), parses the 24-column CSV, posts to api2
+  `/advance-shipping-notices`. Scheduled in `worker/schedules/cron.worker.sync.json` (every 4h).
+- `_underscore/Model/Compass/AdvanceShippingNotice.php` — `postPost` interceptor that builds the
+  ItemFulfillment chain on each ASN POST. Compass Canada inherits it via the empty
+  `_underscore/Model/Compass/Canada/AdvanceShippingNotice.php`.
+- `worker/crons/toga2/compasscanada/workflow/import_grand_and_toy_asn_from_file.php` — one-time
+  backfill variant: reads a CSV from disk (no mailbox/OAuth), creates ASN data only, sends NO
+  user emails/notifications, and stamps `c_dtInTransitEmailSent = NOW()`.
+
+## How it works
+1. Cron gets an O365 OAuth2 token (creds from `App_Registry::get('config')['compasscanada']`),
+   opens the INBOX.
+2. Per attachment: decode CSV, gate on exactly 24 columns (otherwise email the team the file +
+   skip).
+3. Per row: skip electronic-delivery carriers (`Digital` / `E-delivered` / `E-verified`);
+   validate PO / part / tracking; look up SO + contact user + CC addresses; resolve carrier →
+   Ground shipping method; upsert `TrackingNumbers`; resolve the item by
+   `VendorItems.vendorPartNumber`; find-or-create a `Units` row per serial.
+4. POST `/advance-shipping-notices` with the tracking number nested at header + item + unit
+   level (so the interceptor sees it during the POST).
+5. The Compass ASN `postPost` interceptor (when enabled) creates the `ItemFulfillment` (one per
+   SO number, reused if it exists), `ItemFulfillmentItems`, `ItemFulfillmentItemUnits`, and the
+   IF/IFI/IFIU `_TrackingNumbers` bridges.
+6. Only when a tracking number is newly inserted: write Notifications (1.0 `db_store` + 2.0),
+   resolve the user's language, send the EN/FR in-transit email via POST
+   `/email-templates/sendEmail`, then stamp `c_dtInTransitEmailSent = NOW()`.
+
+## Data model
+- ASN: `AdvanceShippingNotices` / `…Items` / `…ItemUnits` + their `…_TrackingNumbers` bridges.
+- IF: `ItemFulfillments` / `…Items` / `…ItemUnits` + their `…_TrackingNumbers` bridges.
+- Vendor: `App_Client_CompassCanada::UUID_VENDOR__GRAND_TOY`.
+- Carriers + methods: `ShippingCarriers` Precision / Purolator / ATSL / Nationex, each with its
+  own Ground `ShippingMethods` row (added 2026-06-18 via dbchanges2; tracking-URL prefixes +
+  carrier logos set on the carrier).
+- Language: `UserGlobalSettings.settingId = 2`, values `en` / `fr-CA`. In-transit `EmailTemplates`
+  uuids — EN `26d2cb67-bdc5-4973-9e39-160c89b0af56`, FR `fb8be211-7c07-4939-9682-08b6c3245f66`.
+- Interceptor wiring: `Core.RecordScripts` + `Core.ApiPayloadInterceptors`, `recordId 55`
+  (AdvanceShippingNotice). The `sendEmail` POST record script is `Core.RecordScripts recordId 202`.
+
+## Client variations
+Compass-Canada-specific; parallels Compass USA's ODP / Strategic-Systems ASN import. Canada sends
+a bilingual EN/FR in-transit email (USA is English only) and uses Canadian carriers.
+
+## Gotchas / known issues
+- **CSV "Part Number" is the VENDOR part number (`VendorItems.vendorPartNumber`), NOT
+  `Items.partNumber`.** Resolve the item through `VendorItems`. (e.g. vendor `IMFP3260` →
+  `Items.partNumber` `C2CY5UC#ABA`.)
+- **G&T's ASN file inconsistently drops the `IM` prefix** (`FP3260` vs `IMFP3260`) on some lines
+  → item-not-found → those lines are skipped and reported in the import-report email. This is a
+  G&T-side export issue; toga transmits the correct `IMFP…` to G&T as the cXML `SupplierPartID`
+  (see `2_transmit_mits_purchase_orders_to_vendors.php`), so it is NOT a MITS bug.
+- **The ASN→IF interceptor must be ENABLED per client.** `Core.ApiPayloadInterceptors` for
+  `recordId 55`, `prePostProcessing=POST`, `httpMethod=POST` must be `isActive=1` (and the client
+  `AclRecordScripts` must grant the caller's roles). It was OFF for Compass Canada; enabling it is
+  required or ASNs post but the IF/IFI/IFIU chain never builds.
+- **Tracking must be nested in the ASN POST payload** (header/item/unit), not linked via SQL
+  after the POST — the interceptor runs during the POST, so post-POST links are invisible to it.
+- **`/email-templates/sendEmail` must be POST** (not GET) so a large `orderItems` HTML payload
+  does not hit the URL-length limit (HTTP 414). POST requires the `sendEmail` record script
+  registered for the POST method (`Core.RecordScripts`), else the engine returns `EV-8`.
+- Each CSV line creates one ASN; the interceptor dedups to **one ItemFulfillment per SO**.
+- A new carrier needs its **own** Ground `ShippingMethod`, or the TrackingNumber ends up with the
+  right carrier but another carrier's Ground method id.
+- `App_Database::fetchOne()` (1.0) throws on a 0-row result — guard item lookups with `numRows()`
+  before `fetchOne()`.
+- The cron reads OAuth2 creds from config `[compasscanada]`; the updated `config.<env>.ini` must
+  be deployed with the code or the token request fails.
+
+## Change history
+- 2026-06-19 — Built the G&T ASN import cron + one-time backfill script; matched items by
+  `VendorItems.vendorPartNumber`; added Canadian carriers + per-carrier Ground methods; EN/FR
+  in-transit email via POST; enabled the Compass ASN→IF interceptor for Compass Canada. (bala)
+
+## Related docs
+- [Compass Canada profile](../profile.md)

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

@@ -12,7 +12,7 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-06-18
+updated: 2026-06-19
 owners: [jcardinal, bala]
 files: []
 related:
@@ -31,10 +31,17 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
 - **1.0:** worker crons under `worker/crons/toga2/compasscanada/`.
 
 ## Vendors & integrations
-- Not yet captured. Confirm vendors / ASN ingestion paths before relying on them.
+- **Grand & Toy (G&T)** — primary hardware vendor. SOs flow toga → MITS → PO to G&T; G&T sends
+  back ASNs. ASN ingestion (email CSV + the auto-created ItemFulfillment chain + bilingual
+  in-transit email) is documented in [Grand & Toy ASN Import](features/grand-and-toy-asn-import.md).
+  Vendor uuid: `App_Client_CompassCanada::UUID_VENDOR__GRAND_TOY`. Canadian carriers in use:
+  UPS, FedEx, Purolator, Precision, Nationex, ATSL (each with a Ground `ShippingMethod`).
+- Worker crons for the G&T flow live under `worker/crons/toga2/compasscanada/workflow/`
+  (`1_…` transmit SOs to MITS, `2_…` transmit POs to vendors, `3_…` status from G&T cXML,
+  `4_…` import G&T ASNs).
 
 ## Notes
-- **Stub** — created alongside the Compass USA profile for disambiguation. The 2026-06-08 ASN
-  → ItemFulfillment work was for **Compass USA**, not Compass Canada. Expand this profile as
-  Compass Canada behavior is investigated.
+- Customer language preference: `UserGlobalSettings.settingId = 2` (`en` / `fr-CA`); customer-
+  facing emails are sent in EN or FR accordingly.
+- The 2026-06-08 ASN → ItemFulfillment work was for **Compass USA**, not Compass Canada.
 - Related: [Compass USA](../compass-usa/profile.md).

package/package.json

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