toga-ai 1.0.685 → 1.0.686

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 20 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 29 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 30 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 13 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)

package/knowledge/clients/prudential/INDEX.md

@@ -6,10 +6,11 @@
 | [Prudential: Dell LCH IOP transmissions (LCHRequestV2)](features/dell-lch-iop-transmissions.md) | 1.0 | Outbound order transmissions from the 1.0 worker tier to Dell's Lifecycle Hub (LCH) ITSM integration. | library/app/api/delllch.php, library/app/apitransaction.php, worker/crons/toga2/prudential/transmissions_to_dell_usa.php, worker/crons/toga2/prudential/transmissions_to_dell_ireland.php, worker/crons/toga2/prudential/transmissions_to_dell_india.php, worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php |
 | [Prudential: Device information import + unit→contact linking (import_device_information.php)](features/device-information-import-and-contact-linking.md) | 1.0 | Prudential's **device-sync** cron (`worker/crons/toga2/prudential/import_device_information.php`) pulls device/asset records (from ServiceNow / the Dell CMDB fe | worker/crons/toga2/prudential/import_device_information.php, worker/crons/toga2/prudential/backfill_unit_contacts.php, dbchanges2/Client_Prudential/2026-07-07 - Contact Dedup Merge.sql |
 | [Prudential: OneUptime order-pipeline backlog monitors (Monitor/Prudential/*)](features/oneuptime-order-pipeline-monitors.md) | 2.0 | Three worker2 OneUptime push monitors (TRUE-80587) that watch the Prudential/Dell order pipeline for **stalls**, which were previously invisible — a stuck pipel | worker2/Worker/Monitor/Prudential.php, worker2/Config/production.ini, dbchanges2/Core/2026-08-07a - Prudential AIG ServiceNow OneUptime monitor crons.sql, dbchanges2/Client_Prudential/2026-04-08 - Insert Customers.sql |
+| [Prudential: order email PDF attachments (which guide goes on which email)](features/order-email-pdf-attachments.md) | 1.0 | Every customer-facing Prudential order email carries S3-hosted PDF guides, and **which** guide is attached is decided by the service request type. | worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/toga2/prudential/transmissions_to_netsuite.php, worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php, worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php, worker/crons/toga2/prudential/test_new_hire_email.php |
 | [Prudential: Service Request Regional Address Validation](features/service-request-address-validation.md) | 2.0 | The `prePost` interceptor on `_Model_Prudential_ServiceRequest` validates `deliverToAddress` fields differently depending on which Prudential regional customer | _underscore/Model/Prudential/ServiceRequest.php, _underscore/Test/Prudential/ServiceRequestTest.php |
 | [Prudential: Service Request rejection alert email](features/service-request-rejection-alert-email.md) | 2.0 | When a Prudential ServiceNow→TOGa service-request submission (`POST /v2/service-requests`) is **rejected by validation**, TOGa now sends a real-time internal al | worker2/Worker/Client/Prudential/reports/ReqRejectionEmail.php, _underscore/Model/Prudential/ServiceRequest.php |
 | [Prudential: Sales Orders CSV export (TOGa 2.5 Supply)](features/supply-orders-csv-export.md) | 2.0 | The **Export** button on the TOGa 2.5 Supply *Sales Orders* page is **Prudential-only**: it downloads a 22-column CSV (`prudential-orders-<YYYY-MM-DD>.csv`) cov | toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/PRUDENTIAL/exportApiFields.json, toga25-supply/src/pages/SalesOrders/api/prudentialExportApi.ts, toga25-supply/src/pages/SalesOrders/hooks/usePrudentialOrdersExport.ts, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx |
-| [Prudential Order Shipped Email — transmit_ordershipped_updates_prudential.php](features/transmit-ordershipped-email.md) | 1.0 | Cron script that transmits "Order Shipped" updates to ServiceNow (RITM) and sends a shipped notification email to the end user. | worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php, worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php, worker/crons/toga2/prudential/transmit_rejected_cancelled_updates_prudential.php, worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/notifications/reports/prudential_exception_report.php |
+| [Prudential Order Shipped Email — transmit_ordershipped_updates_prudential.php](features/transmit-ordershipped-email.md) | 1.0 | Cron script that transmits "Order Shipped" updates to ServiceNow (RITM) and sends a shipped notification email to the end user. | worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php, worker/crons/toga2/prudential/transmissions_to_netsuite.php, worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php, worker/crons/toga2/prudential/transmit_rejected_cancelled_updates_prudential.php, worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/notifications/reports/prudential_exception_report.php |
 | [Prudential Financial](profile.md) | 2.0 | Prudential is a TOGA client whose device-fulfillment flow is driven by **Dell** via the Dell API (`Client_Prudential.Apis.id = 2`). |  |
 | [Prudential: Dell ASN failed POST backfill replay](workflows/dell-asn-backfill-replay.md) | 2.0 | When Dell ASN POSTs fail in bulk (e.g. |  |
 | [Prudential — HTTP/2 disabled on the Commerce ALB (proxy workaround) + open re-enable action](workflows/http2-alb-workaround.md) | 2.0 | Prudential users hit **`ERR_HTTP2_PROTOCOL_ERROR`** in Chrome and Edge (both Chromium) loading `https://prudential.togacommerce.com`, while the site worked fine |  |

package/knowledge/clients/prudential/features/order-email-pdf-attachments.md

@@ -0,0 +1,141 @@
+---
+title: "Prudential: order email PDF attachments (which guide goes on which email)"
+framework: "1.0"
+repo: worker
+project: Worker
+client: prudential
+type: client-feature
+status: active
+updated: 2026-08-28
+owners: ["bala"]
+files:
+  - worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php
+  - worker/crons/toga2/prudential/transmissions_to_netsuite.php
+  - worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php
+  - worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php
+  - worker/crons/toga2/prudential/test_new_hire_email.php
+related:
+  - transmit-ordershipped-email.md
+  - ../profile.md
+---
+
+## Summary
+Every customer-facing Prudential order email carries S3-hosted PDF guides, and **which** guide is
+attached is decided by the service request type. The rule was inconsistent between stages — the
+same request type received different documents depending on whether the email came from
+order-created, shipped, or delivered — and a new hire was being sent the *return* instructions
+instead of a setup guide. As of 2026-08-27 one rule applies at **every** stage:
+
+> **New hire → getting-started guides only (Windows 11 + Mac).
+> Reclaim, Breakfix, Swap, Label, Refresh → the return-instructions guide.**
+
+Reported by the client (Gary Yerman) against the new-hire order-created email; the fix for that
+specific branch shipped as **TRUE-81393**, and the consistency pass across the other stages
+followed in the same session.
+
+## The rule, by stage
+
+| Service request type | Order created | Shipped | Delivered |
+|---|---|---|---|
+| New (1) | Win11 + Mac | Win11 + Mac | Win11 + Mac |
+| Reclaim (5) | Return | Return | Return |
+| Breakfix (2) | Win11 + Return | Win11 + Mac + Return | Win11 + Mac + Return |
+| Swap (4) | Win11 + Return | Win11 + Mac + Return | Win11 + Mac + Return |
+| Label (6) | Win11 + Return | Win11 + Mac + Return | Win11 + Mac + Return |
+| Refresh (3) | Win11 + Mac + Return | Win11 + Mac + Return | Win11 + Mac + Return |
+
+The load-bearing part is the **Return** column: no non-New type may go out without the return
+guide, and New must never carry it.
+
+## Which cron sends which email
+
+All four are `active: 1` in `worker/schedules/cron.worker.sync.json`:
+
+| Stage | Cron | Branches on |
+|---|---|---|
+| Order created | `generate_sales_and_purchase_orders_from_service_requests.php` | `serviceRequestTypeId` (`1`, `5`, `3`, `else`) |
+| Shipped | `transmissions_to_netsuite.php` | type **name** (`$reqType == "New"`, `else`) |
+| Shipped | `transmit_ordershipped_updates_prudential.php` | type **name** (`$reqType == "New"`, `else`) |
+| Delivered | `transmit_closecomplete_updates_prudential.php` | type **name** (`$reqType == "New"`, `else`) |
+
+**Two different crons send the shipped email** (`transmissions_to_netsuite.php` and
+`transmit_ordershipped_updates_prudential.php` — both also stamp
+`c_dtTransmittedOrderShippedUpdateToPrudential`). Any attachment change to the shipped email must
+be made in **both**, or the two senders drift apart.
+
+The order-created cron switches on the numeric `serviceRequestTypeId`, while the shipped and
+delivered crons switch on the type **name string** read from
+`serviceRequest.serviceRequestType.name` in the TOGa API response. The names match the enum
+exactly (`New`, `Reclaim`), so the string comparisons are safe — but the two styles mean a newly
+added request type lands in the `else` branch everywhere and is never matched by name.
+
+## The PDF assets
+
+All three live under `https://external-client-files.s3.us-west-2.amazonaws.com/prudential/` and
+all three returned HTTP 200 (verified 2026-08-27). Two of them are **renamed on attach**:
+
+| S3 object | Attached to the email as | Size |
+|---|---|---|
+| `EquipMe-Win11-v1.pdf` | `Getting_Started_Guide_Windows11.pdf` | 773,591 B |
+| `2026_Aug_PrudentialMacSetupGuide_ZCC.pdf` | `PrudentialMacSetupGuide.pdf` | 7,543,154 B |
+| `Prudential_Instruction-2Page-V1.pdf` | (unchanged) | 100,224 B |
+
+The Mac guide dominates: a new-hire email is roughly **11 MB** once base64-encoded. Grepping for
+the attached-as filename will not find the S3 object — search the S3 basename.
+
+## How to change an attachment safely
+
+1. Every fetch goes through the file-scope `safeFetchPdf()` helper, never bare
+   `file_get_contents()`. Under the 1.0 framework's `E_ALL` + `App_Error::handleError`, a failed
+   S3 pull is converted to an `ErrorException` and **throws at the call site**, killing the cron
+   mid-batch before any `!== false` guard can run. Full root cause in
+   `transmit-ordershipped-email.md`. `transmissions_to_netsuite.php` was the last file still
+   fetching directly and calling `addAttachment()` unconditionally (which would also mail a
+   0-byte file under a real guide's name); it was converted 2026-08-27.
+2. Each PDF gets its **own** `if ($pdfX !== false)` guard around the `file_put_contents` +
+   `addAttachment` pair — never a joint `&&`. One failed PDF must drop only itself; the email
+   always sends.
+3. **Put the return-guide fetch *before* the `if ($reqType != 'Reclaim')` guard** in the shipped
+   and delivered crons. Everything inside that guard is skipped for Reclaim — and Reclaim is
+   precisely the type that most needs the return instructions. That guard is how Reclaim ended up
+   receiving zero attachments.
+
+## Testing
+
+`crons/toga2/prudential/test_new_hire_email.php` (local, untracked) rebuilds the new-hire email
+verbatim — same subject, same HTML template, same S3 fetches — mails it to a hardcoded
+`$testRecipients` list, and prints each PDF's attached/missing state and byte size before
+sending. It **writes nothing**: no sales order, no purchase order, no api2 call, no SQL. It
+deliberately calls only `App_Framework_Worker::initialize()` and **not**
+`App_Framework::cronInitialization()`, because that INSERTs a `CronJobExecutions` row.
+
+Run it from the worker repo's `crons/` directory with the `library` and `_underscore` repos on
+the include path:
+
+```
+php -d include_path=".;<library>;<_underscore>" toga2/prudential/test_new_hire_email.php
+```
+
+## Gotchas / known gaps
+
+- **`prudential_beta/` does not match prod.**
+  `crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php` is
+  `active: 1` on the same schedule but points at the beta DB and still references the retired
+  `Prudential_Return_Instructions.pdf` (and the old `PrudentialMacSetupGuide.pdf`). **A beta test
+  will not reproduce prod attachment behavior.** Left as-is deliberately; the developer is aware.
+- **Breakfix / Swap / Label get no Mac guide on the order-created email** (they do get it on
+  shipped and delivered). Known, and left alone on purpose — not a bug to "fix" unasked.
+- The delivered cron (`transmit_closecomplete_updates_prudential.php`) already followed the rule
+  and was deliberately **not** touched.
+
+## Change history
+- 2026-08-27 — Client-reported: the new-hire order-created email attached the return-instructions
+  PDF and carried no Mac guide. Swapped it to Win11 + Mac
+  (`2026_Aug_PrudentialMacSetupGuide_ZCC.pdf` attached as `PrudentialMacSetupGuide.pdf`) and
+  dropped the return doc (TRUE-81393). Then made the rule consistent across every stage: added the
+  return guide to the order-created Reclaim branch (previously zero attachments) and to the
+  Breakfix/Swap/Label catch-all; added it for every non-New type in **both** shipped crons, placed
+  ahead of the `!= 'Reclaim'` guard so Reclaim actually receives it; and removed it from the
+  New-hire shipped email in both. Converted the last direct `file_get_contents` PDF fetches in
+  `transmissions_to_netsuite.php` to `safeFetchPdf()` with guarded write+attach. Added
+  `test_new_hire_email.php` as a write-free manual harness (bala)

package/knowledge/clients/prudential/features/transmit-ordershipped-email.md

@@ -6,16 +6,18 @@ project: Worker
 client: prudential
 type: client-feature
 status: active
-updated: 2026-07-10
-owners: ["rgirish"]
+updated: 2026-08-28
+owners: ["rgirish", "bala"]
 files:
   - worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php
+  - worker/crons/toga2/prudential/transmissions_to_netsuite.php
   - worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php
   - worker/crons/toga2/prudential/transmit_rejected_cancelled_updates_prudential.php
   - worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php
   - worker/crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php
   - worker/crons/notifications/reports/prudential_exception_report.php
 related:
+  - order-email-pdf-attachments.md
   - ../profile.md
 ---
 
@@ -39,9 +41,13 @@ Iterates the same POs collected in Phase 1. For each:
 1. Fetches PO details via TOGa API (`GET /purchase-orders/<uuid>`).
 2. Fetches tracking number via TOGa API (`GET /tracking-numbers`).
 3. Builds and sends the shipped email based on `serviceRequestType`:
-   - **New** — "Your new hire equipment has shipped" with 3 PDF attachments (Win11 guide, return instructions, Mac setup guide).
-   - **Breakfix / Refresh** — "Your equipment has been shipped" with 2 PDF attachments (Win11 + Mac setup guide), skipped for Reclaim.
-   - **Reclaim** — "Your equipment has been shipped" with no PDF attachments.
+   - **New** — "Your new hire equipment has shipped", Win11 + Mac setup guides.
+   - **Everything else** — "Your equipment has been shipped", return-instructions guide for
+     every type (including Reclaim), plus Win11 + Mac for the non-Reclaim types.
+
+   **The attachment set changed on 2026-08-27** — which guide goes on which email, at every
+   stage of the order, is now owned by `order-email-pdf-attachments.md`. Read that before
+   changing any attachment here.
 4. Stamps `c_dtEmailSentOrderShipped = NOW()` on the PO.
 
 ## Data model
@@ -80,6 +86,18 @@ TrackingNumbers WHERE purchaseOrderId = PurchaseOrders.id AND TrackingNumbers.st
 orders that genuinely qualified for a delivery email. Over 2026-07-01..07-09 this dropped 6 false
 positives (25 → 19 flagged) while retaining all 19 genuine discrepancies.
 
+## A second cron sends the same shipped email
+
+`transmissions_to_netsuite.php` (also `active: 1`) builds and sends the **same** shipped email —
+same subjects, same branch shape — and also stamps `c_dtTransmittedOrderShippedUpdateToPrudential`.
+It is easy to miss: it is not named like the other `transmit_*` crons. Any change to the shipped
+email's content or attachments must be applied to **both** files or the two senders drift.
+
+It was also the last Prudential cron still calling `file_get_contents()` directly for its PDFs and
+calling `addAttachment()` unconditionally — so a failed S3 pull threw and killed the batch, and a
+false return would have mailed a 0-byte file under a real guide's name. Converted to
+`safeFetchPdf()` with per-PDF guards on 2026-08-27.
+
 ## Sibling scripts sharing this pattern
 The same two-phase (transmit-then-email) shape and the same PDF-fetch fragility exist in three
 sibling crons, all fixed the same way this session (2026-07-06):
@@ -175,6 +193,13 @@ stamp (crash hits the next iteration). With multiple New-type POs, a crash on PO
 all subsequent POs in the same run.
 
 ## Change history
+- 2026-08-27 — Extended the `safeFetchPdf()` + per-PDF-guard pattern to
+  `transmissions_to_netsuite.php`, the last cron still fetching PDFs with bare
+  `file_get_contents()` and attaching unconditionally. Also recorded that this cron is a **second
+  sender of the shipped email** alongside `transmit_ordershipped_updates_prudential.php`. The
+  shipped email's attachment set was reworked the same day to match the new client-agreed rule
+  (New = setup guides only; every other type gets the return guide, Reclaim included) — see
+  order-email-pdf-attachments.md (bala)
 - 2026-07-10 — Third regression of the "Order Shipped / Order Delivered Email Not Sent" symptom.
   True trigger: `createAssetAndRetryPut()` called the nonexistent `App_Database::escapeString()`
   (~line 158 in `transmit_ordershipped` + `transmit_closecomplete`) — a fatal `Error` under E_ALL

package/knowledge/clients/prudential/profile.md

@@ -27,6 +27,7 @@ related:
   - features/device-information-import-and-contact-linking.md
   - workflows/http2-alb-workaround.md
   - features/supply-orders-csv-export.md
+  - features/order-email-pdf-attachments.md
 ---
 
 ## Summary
@@ -63,7 +64,11 @@ order-status transmissions.
 - PO lifecycle is tracked by `purchaseOrderStageId`. The `dtAcknowledged` column is **unused
   (always NULL)** — do not key logic on it.
 
-`ServiceRequests.serviceRequestTypeId`: **1 = New Hire, 2 = Breakfix, 3 = Refresh, 5 = Reclaim**.
+`ServiceRequests.serviceRequestTypeId` (full set, verified against prod `Client_Prudential`
+2026-08-27): **1 = New, 2 = Breakfix, 3 = Refresh, 4 = Swap, 5 = Reclaim, 6 = Label**.
+The order-created cron branches on this id; the shipped/delivered crons branch on the type
+**name** string (`serviceRequest.serviceRequestType.name`), so 4 and 6 only ever reach an
+`else` branch.
 
 ## Gotchas
 - **Commerce (`prudential.togacommerce.com`):** Prudential's corporate TLS-inspection proxy
@@ -98,6 +103,8 @@ order-status transmissions.
 - features/transmit-ordershipped-email.md
 - features/device-information-import-and-contact-linking.md — device-sync cron, unit→contact
   linking, the "null null" contact-export incident + dedup/backfill remediation.
+- features/order-email-pdf-attachments.md — which PDF guide is attached to which customer
+  order email at which stage, the S3 asset list, and the four crons that send them.
 - features/supply-orders-csv-export.md — the Prudential-only Sales Orders CSV export in TOGa 2.5
   Supply (`toga25-supply`): its two queries, why contacts join `SalesOrders.contactId` (not
   `Units.contactId`, NULL until Dell assigns the asset), and the `ServiceRequests_Units` fan-out.

package/package.json

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