toga-ai 1.0.102 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.102",
+  "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",