toga-ai 1.0.101 → 1.0.103

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)_ — 4 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 5 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 6 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 7 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 5 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
@@ -14,7 +14,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 6 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 7 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 6 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 1 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/knowledge/clients/prudential/INDEX.md

@@ -3,5 +3,6 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [Prudential: Dell ASN units PRE/POST interceptor (legacy key + flat tracking)](features/dell-asn-units-interceptor.md) | 2.0 | After the tracking-number bridge migration, the ASN unit route was renamed (`advance-shipping-notice-units` → `advance-shipping-notice-item-units`), so the inhe | _underscore/Model/Prudential/AdvanceShippingNotice.php, dbchanges2/Client_Prudential/2026-06-10 - AsnUnitsInterceptor.sql |
+| [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 |
 | [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. |  |

package/knowledge/clients/prudential/features/service-request-address-validation.md

@@ -0,0 +1,101 @@
+---
+title: "Prudential: Service Request Regional Address Validation"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: prudential
+type: client-feature
+status: active
+updated: 2026-06-16
+owners: ["rgirish"]
+files:
+  - _underscore/Model/Prudential/ServiceRequest.php
+related:
+  - clients/prudential/profile.md
+  - clients/prudential/features/dell-asn-units-interceptor.md
+---
+
+## Summary
+
+The `prePost` interceptor on `_Model_Prudential_ServiceRequest` validates `deliverToAddress`
+fields differently depending on which Prudential regional customer is placing the request.
+The region is determined at runtime by looking up `customer.uuid` (sent in the POST payload)
+against the `Client_Prudential.Customers` table, whose `name` column holds the region label.
+Three regions are supported: **USA**, **India**, **Ireland**. Unknown or absent UUIDs fall
+back to USA rules.
+
+## Key files / entry points
+
+- `_underscore/Model/Prudential/ServiceRequest.php` — `prePost` interceptor; private methods
+  `resolveRegion()`, `validateUsaAddress()`, `validateIndiaAddress()`, `validateIrelandAddress()`
+
+## How it works
+
+1. `prePost` fires before each POST to `/v2/service-requests` for the Prudential client.
+2. `resolveRegion()` reads `payload->customer->uuid`, escapes it, and queries
+   `Client_Prudential.Customers` for the matching `name`. Returns `'India'`, `'Ireland'`, or
+   `'USA'` (default for anything unrecognised or when uuid is null).
+3. A `match` expression dispatches to the correct validator.
+4. On any validation failure, an `Exception` is thrown with a semicolon-delimited list of all
+   errors — the API engine catches it and returns a 4xx to Dell.
+
+## Data model
+
+`Client_Prudential.Customers` — the region lookup table:
+
+| Column | Type      | Notes                                              |
+|--------|-----------|----------------------------------------------------|
+| `id`   | int PK    |                                                    |
+| `uuid` | char(36)  | Sent by Dell in `customer.uuid` on every POST       |
+| `name` | varchar   | Region label: `'USA'`, `'India'`, or `'Ireland'`   |
+
+## Validation rules by region
+
+### USA (default)
+| Field                  | Rule                                      |
+|------------------------|-------------------------------------------|
+| `line1`                | Required, max 35 chars                    |
+| `line2`                | Optional, max 35 chars                    |
+| `city`                 | Required                                  |
+| `zip`                  | Required (any characters)                 |
+| `state.code`           | Required, exactly 2 alphabetic characters |
+
+### India (Dell India primary field spec)
+| Field             | Rule                                                  |
+|-------------------|-------------------------------------------------------|
+| `line1`           | Required, max 30 chars (Customer/Consignee Name)      |
+| `line2`           | Optional, max 30 chars (Address Line 1)               |
+| `line3`           | Optional, max 30 chars (Address Line 2)               |
+| `city`            | Required, max 30 chars (Address Line 3 / city)        |
+| `zip`             | Required, max 6 chars, strictly numeric (0–9)         |
+| `mobileNumber`    | Optional, 10–15 chars, numeric                        |
+| `telephoneNumber` | Optional, 6–15 chars, numeric                         |
+| `customerCode`    | Optional, max 6 chars, alphanumeric                   |
+| `originAreaCode`  | Optional, max 3 chars, alphabetic (A–Z)               |
+
+India optional fields (`mobileNumber`, `telephoneNumber`, `customerCode`, `originAreaCode`)
+are silently skipped when absent — Prudential has not yet started sending them.
+
+### Ireland
+Same as USA except `zip` accepts any characters — Irish Eircode format is alphanumeric
+with a space (e.g. `F92 FP83`). No numeric restriction.
+
+## Gotchas / known issues
+
+- **Null UUID = USA fallback.** All requests sent before Prudential added `customer.uuid` to
+  their payload lacked the field entirely; those are treated as USA and pass through unchanged.
+  This is intentional backward compatibility.
+- **Region check is by `Customers.name` string, not by id.** If the customer name is ever
+  changed in the DB (e.g. `'USA'` → `'United States'`), the validator will silently fall
+  back to USA rules for all regions. The match arms are `'India'` and `'Ireland'` only;
+  everything else maps to USA.
+- **India optional fields are forward-compatible.** The Dell India field spec includes
+  `mobileNumber`, `telephoneNumber`, `customerCode`, and `originAreaCode` but Prudential has
+  not started sending them yet. The validators already handle them — no code change needed
+  when Prudential starts including them.
+- **`line3` is India-only.** USA and Ireland validators do not check `line3` (it is not in
+  their Dell spec). If Dell starts sending it for USA/Ireland it is silently ignored.
+
+## Change history
+- 2026-06-16 — Created: regional address validation (USA/India/Ireland) replacing the single
+  USA-only `validateDeliverToAddress` method; region resolved from `customer.uuid` lookup (rgirish)

package/knowledge/clients/prudential/profile.md

@@ -9,11 +9,12 @@ project: _Underscore
 client: prudential
 type: profile
 status: active
-updated: 2026-06-10
-owners: ["jcardinal"]
+updated: 2026-06-16
+owners: ["jcardinal", "rgirish"]
 files: []
 related:
   - features/dell-asn-units-interceptor.md
+  - features/service-request-address-validation.md
 ---
 
 ## Summary
@@ -24,7 +25,10 @@ return-tracking per unit) into the 2.0 platform (DB `Client_Prudential`); the 1.
 order-status transmissions.
 
 ## Integrations
-- **Inbound:** Dell API → POST `/v2/advance-shipping-notices` (creates ASNs + units + tracking).
+- **Inbound (ASNs):** Dell API → POST `/v2/advance-shipping-notices` (creates ASNs + units + tracking).
+- **Inbound (Service Requests):** Dell API → POST `/v2/service-requests`. Payload includes
+  `customer.uuid` which maps to a regional customer record (`USA`, `India`, or `Ireland`) in
+  `Client_Prudential.Customers` — used to apply region-specific `deliverToAddress` validation.
 - **Outbound (worker crons):** `transmissions_to_netsuite.php`, `transmit_ordershipped_updates_prudential.php`,
   `transmit_closecomplete_updates_prudential.php`, `transmit_order_delivered_updates_from_fedex_toga2.php`,
   `update_tracking_number_from_netsuite_to_toga.php`, `manually_insert_ASN.php`.
@@ -32,6 +36,8 @@ order-status transmissions.
 ## Gotchas
 - Dell will not change their payload shape — see the Dell ASN units interceptor feature doc for the
   PRE/POST translation that keeps their feed working after the tracking-number bridge migration.
+- Service request region is resolved from `Customers.name` string (`'USA'`/`'India'`/`'Ireland'`).
+  Renaming those customer records in the DB would silently break regional validation routing.
 
 ## Related docs
 - Dell ASN units interceptor.

package/knowledge/clients/rate/INDEX.md

@@ -2,5 +2,6 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [Rate Monthly Reconciliation Report](features/monthly-reconciliation-report.md) | 1.0 | A monthly cron that emails an Excel reconciliation report covering all Rate subscription sales orders and their linked PayPal payments for the prior calendar mo | worker/crons/notifications/reports/rate/send_monthly_rate_purchases_report.php, worker/schedules/cron.worker.notification.json |
 | [Rate SAML SSO](features/saml-sso.md) | 2.0 | Rate uses Azure AD as its IdP (`login.rate.com`). | _underscore/Model/Rate/ClientAuthentication.php, saml/Controller/Index.php, toga2-view/src/hooks/useAuthenticationFlow.ts |
 | [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

package/knowledge/clients/rate/features/monthly-reconciliation-report.md

@@ -0,0 +1,85 @@
+---
+title: Rate Monthly Reconciliation Report
+framework: "1.0"
+repo: worker
+project: Worker
+client: rate
+type: client-feature
+status: active
+updated: 2026-06-16
+owners: ["rgirish"]
+files:
+  - worker/crons/notifications/reports/rate/send_monthly_rate_purchases_report.php
+  - worker/schedules/cron.worker.notification.json
+related:
+  - clients/rate/features/saml-sso.md
+  - clients/rate/profile.md
+---
+
+## Summary
+
+A monthly cron that emails an Excel reconciliation report covering all Rate subscription
+sales orders and their linked PayPal payments for the prior calendar month. Used by AIG
+(for contract reconciliation) and the TOGA accounts team (for billing verification).
+
+## How it works
+
+1. Runs on the 1st of each month via `cron.worker.notification.json`.
+2. Queries `Client_Rate` for all `SalesOrders` whose `dateOrder` falls within the prior
+   month, joined through `Entitlements_SalesOrders` → `Entitlements` → `Subscriptions`.
+   Filtered to `Subscriptions.token LIKE 'I-%'` (PayPal recurring subscription tokens only).
+3. Also joins `SalesOrders_Payments` → `Payments` for transaction-level detail.
+4. Builds a 16-column Excel sheet ("Monthly Reconciliation") using PhpSpreadsheet.
+5. Emails the `.xlsx` as an attachment. If no orders found, sends a plain no-data notice.
+
+## Report columns
+
+| # | Column | Source |
+|---|---|---|
+| 1 | Customer Name | `Customers.name` |
+| 2 | Email | `ContactEmailAddresses.emailAddress` |
+| 3 | Address | `Addresses` (line1, line2, city, state, zip via `CONCAT_WS`) |
+| 4 | Entitlement # | `Entitlements.number` |
+| 5 | AIG Contract # | `Entitlements.c_aigContractNumber` |
+| 6 | Sales Order # | `SalesOrders.number` |
+| 7 | Description | `SalesOrders.description` |
+| 8 | Order Date | `SalesOrders.dateOrder` |
+| 9 | Subscription Token | `Subscriptions.token` |
+| 10 | Active | `Subscriptions.isActive` (Yes/No) |
+| 11 | Date Cancelled | `Subscriptions.dateCancelled` |
+| 12 | Date End | `Subscriptions.dateEnd` |
+| 13 | Transaction ID | `Payments.transactionIdentifier` |
+| 14 | Amount | `Payments.amount` |
+| 15 | Payment Date | `Payments.dtStamp` |
+| 16 | Payment Note | `Payments.note` |
+
+## Key design decisions
+
+- **Filtered by `SalesOrders.dateOrder`**, not `Entitlements.dtCreated` — catches recurring
+  monthly payments, not just the original purchase date.
+- **`Subscriptions.token LIKE 'I-%'`** — restricts to PayPal recurring billing agreement
+  tokens; excludes any one-off or non-PayPal orders.
+- **LEFT JOIN on Payments** — a sales order with no payment record still appears in the
+  report (payment columns will be blank). This surfaces orders missing payment data.
+- Ordered by `Subscriptions.id ASC, SalesOrders.dateOrder ASC` — groups all orders per
+  subscriber chronologically.
+
+## Recipients
+
+Currently `$emailTo` in the script. Update there to add AIG or additional recipients.
+
+## Gotchas / known issues
+
+- **`c_aigContractNumber`** is the display string from AIG (e.g. `1000045859462`). The
+  companion `c_aigContractId` (Int32) is used by the AIG cancel API but is not included
+  in this report — add it if AIG requests it for matching.
+- **To run manually for testing**, comment out the `WHERE` date filter. Restore it before
+  leaving the script — the cron runs on the 1st and will pull all-time data otherwise.
+- The script file is named `send_monthly_rate_purchases_report.php` (historical name) but
+  the report it generates is now the reconciliation report — the filename was not renamed.
+
+## Change history
+
+- 2026-06-16 — Rebuilt from a new-purchases report into a full reconciliation report: query
+  now drives off `SalesOrders.dateOrder` (not `Entitlements.dtCreated`), adds Payments join,
+  16-column sheet replacing the old 11-column sheet, filtered to PayPal tokens (rgirish)

package/knowledge/clients/rate/profile.md

@@ -5,15 +5,17 @@ apps:
   - _underscore
   - saml
   - toga2-view
+  - worker
 project: SAML SSO Gateway
 client: rate
 type: profile
 status: active
-updated: 2026-06-11
+updated: 2026-06-16
 owners: ["rgirish"]
 files: []
 related:
   - clients/rate/features/saml-sso.md
+  - clients/rate/features/monthly-reconciliation-report.md
 ---
 
 ## Summary

package/package.json

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