toga-ai 1.0.569 → 1.0.571

package/knowledge/1.0/apps/library/INDEX.md

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Library (1.0 Framework) Architecture](architecture.md) | `library` is the shared library repository for **all 1.0 (legacy) applications** — the `App_` framework. | library/_.php, library/app/, library/browser/ |
+| [Address Validation Gateway (App_Api_OfficeDepot::validateAddress + USPS fallback)](features/address-validation-gateway.md) | `App_Api_OfficeDepot::validateAddress()` is the shared 1.0 (`App_`) address-validation gateway. | library/app/api/officedepot.php, library/app/api/usps.php |
 | [Where a new App_ class goes — the app/ folder IS a behavioral contract](features/app-class-placement-base-contracts.md) | In `library/app/`, choosing a folder is **not** a filing decision — the autoloader maps `App_<Folder>_<File>` to `app/<folder>/<file>.php`, and each folder's ba | library/app/model.php, library/app/client.php, library/app/api.php, library/app/api/servicerequest.php, library/app/api/volt.php, library/app/api/carrier/fedex.php |
 | [App_Sso — Reusable 1.0 SSO Initiation (SP-initiated SAML via saml.togahub.com)](features/app-sso-initiation.md) | `App_Sso` (`library/app/sso.php`) is the **1.0 port of the 2.0 SAML gateway's SP-initiated SSO initiation**, packaged as a reusable, framework-level capability | library/app/sso.php, library/sso/togahub_private_key.key |
 | [Cron Execution Monitoring (App_Framework check-in/out → CronJobExecutions)](features/cron-execution-monitoring.md) | `App_Framework::cronInitialization()` / `App_Framework::cronFinished()` (in `library/app/framework.php`) give every 1.0 (`App_`) cron job a check-in/check-out l | library/app/framework.php |

package/knowledge/1.0/apps/library/features/address-validation-gateway.md

@@ -0,0 +1,77 @@
+---
+title: Address Validation Gateway (App_Api_OfficeDepot::validateAddress + USPS fallback)
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-08-13
+owners: [jcardinal]
+files:
+  - library/app/api/officedepot.php
+  - library/app/api/usps.php
+related:
+  - ../../toga/features/odp-customer-search-loyalty-persistence.md
+---
+
+## Summary
+`App_Api_OfficeDepot::validateAddress()` is the shared 1.0 (`App_`) address-validation gateway.
+It is the entry point every TOGa 1.0 flow calls (via classic AJAX
+`ajaxAction('App_Api_OfficeDepot','validateAddress')`) to standardize/verify a typed address
+before it is saved. It wraps ODP's address-validation service and falls back to
+`App_Api_USPS::validateAddress()` (USPS REST API v3, OAuth `client_credentials`, in
+`library/app/api/usps.php`). It returns a standardized address (corrected city/casing/zip) that
+callers are expected to write back before saving.
+
+## Key files / entry points
+- `library/app/api/officedepot.php` — `App_Api_OfficeDepot::validateAddress()`, the gateway.
+- `library/app/api/usps.php` — `App_Api_USPS::validateAddress()`, the fallback carrier.
+
+## How it works
+1. **Endpoint selection.** The gateway calls the ODP **sandbox** endpoint when
+   `App_Registry::inTestMode()` is true (`inTestMode` = `config['internal']['test_mode'] > 0`),
+   and the **live** ODP endpoint otherwise. Production is effectively hard-pinned to live
+   (comment "2024-01-22 JC - Always using production...").
+2. **On a real ODP answer** (HTTP 200, whether it accepts or rejects the address) the gateway
+   returns ODP's standardized result.
+3. **On any non-200 ODP response** (sandbox down/expired, etc.) it falls back to
+   `App_Api_USPS::validateAddress()` and returns the USPS result — a genuine standardization
+   **or** a genuine bad-address rejection both count as a real answer and are returned.
+4. **Only when BOTH ODP and USPS are unavailable** does it return `array('success' => true)`
+   with no standardized fields (fail-open, so associates are never hard-blocked by an outage).
+
+## Gotchas / known issues
+- **Beta-bypass class of bug (fixed 2026-08-13).** Previously the ODP-failure `else` branch
+  returned `array('success' => true)` with **no** standardized address fields and the USPS
+  fallback was commented out. Beta/test uses the ODP **sandbox**; when the sandbox was
+  down/expired, callers saw `success:true` and saved the **raw typed address** (wrong city,
+  wrong casing) with no validation. Production was unaffected because it hits the working live
+  ODP endpoint. The fix restores the USPS fallback so a validation only truly fails open when
+  **both** carriers are down.
+- **"Both unavailable" must check BOTH USPS service-down strings.** USPS signals unavailability
+  two ways: `'Address validation service is temporarily unavailable'` **and**
+  `'USPS OAuth authentication failed'`. The fail-open condition must match either. Checking only
+  the first string wrongly blocks associates when ODP is down *and* USPS OAuth also fails
+  (a php-reviewer pass caught this).
+- **Front-end write-back anti-pattern (widespread, mostly UNFIXED).** Many 1.0 front-end
+  callbacks use the gateway response only as a pass/fail **gate**, then rebuild the save payload
+  from the raw DOM inputs — discarding the standardized `address1`/`city`/`state`/`zipCode` the
+  gateway returned. So even a successful validation never persists the corrected address. Known
+  flows with this anti-pattern still present:
+  `toga/app/togarefresh2026/servicerequests/finalizequote.php`,
+  `toga/app/togarefresh2026/appointment/select.php`,
+  `toga/app/servicerequests/builder.php`, `toga/app/loaners/checkout.php`,
+  `toga/app/jobjackets/view.php`, and the `togarefresh2023` variants. The 2026-08-13 gateway fix
+  protects all of them from the beta bypass, but the write-back was only corrected in the
+  `togarefresh2026` customersearch flow (see related doc). When touching any of these, write the
+  standardized address back into the inputs before building the save payload.
+
+## Related docs
+- `../../toga/features/odp-customer-search-loyalty-persistence.md` — the customersearch save
+  flow, where the write-back fix was applied.
+
+## Change history
+- 2026-08-13 — Fix: restored the USPS fallback in `App_Api_OfficeDepot::validateAddress` so the
+  beta/sandbox path no longer fakes `success:true` and saves unvalidated addresses; fail-open now
+  requires BOTH ODP and USPS down, checking both USPS service-down strings. (jcardinal)

package/knowledge/1.0/apps/toga/features/odp-customer-search-loyalty-persistence.md

@@ -6,13 +6,14 @@ project: TOGa
 client: office-depot
 type: client-feature
 status: active
-updated: 2026-08-10
+updated: 2026-08-13
 owners: [jcardinal]
 files:
   - toga/app/togarefresh2026/customersearch/view.php
   - library/app/model/customer.php
 related:
   - ./bundleconfirmation-cart-preservation.md
+  - ../../library/features/address-validation-gateway.md
 ---
 
 ## Summary
@@ -47,6 +48,18 @@ field.
 ## Data model
 - `Customers.merchantId` (TOGA_ODP legacy DB) — stores the ODP loyalty/rewards `memberId`.
 
+## Standardized-address write-back (Next button flow)
+The "Existing PC Services" flow — `content=togarefresh2026_customersearch`, Next button
+(`#nextSubmit`) → `validateAddress()` → JS callback `validateAddressResponse(resp)` — used the
+gateway response only as a pass/fail gate, then rebuilt the save `formData` from the raw DOM
+inputs and called `App_Model_Customer::saveNewCustomer` — discarding `resp['address1']`/`city`/
+`state`/`zipCode`, so the validated casing/city/zip never persisted. Fixed 2026-08-13: before
+building `formData`, the callback now writes the standardized address from `resp` back into the
+`streetAddress`/`line2`/`city`/`state`/`zip` inputs (guarded on `resp['address1']` present), so
+the corrected address is what gets saved. The gateway itself lives in `library` — see
+`../../library/features/address-validation-gateway.md`, which lists the many other 1.0 flows
+that still have this write-back anti-pattern.
+
 ## Gotchas / known issues
 - **`saveNewCustomer` has two callers.** `togarefresh2026` now sends `merchantId`;
   `togarefresh2023` does **not**. The `!empty()` guard is what keeps the 2023 flow safe — it
@@ -64,6 +77,9 @@ field.
 - `./bundleconfirmation-cart-preservation.md`
 
 ## Change history
+- 2026-08-13 — Fix: `validateAddressResponse` now writes the standardized address from the
+  validation gateway back into the form inputs before saving, so validated city/casing/zip
+  persist (previously the response was used only as a pass/fail gate). (jcardinal)
 - 2026-08-10 — Fix: ODP loyalty number now persists to Customers.merchantId across the
   togarefresh2026 customer-search save flow (front end + saveNewCustomer), guarded by !empty().
   Flagged a pre-existing SQL-injection risk in the same method for follow-up. (jcardinal)

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 17 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 18 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 23 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)

package/knowledge/clients/compass-usa/features/odp-edi-855-acknowledgement-and-overquantity-guard.md

@@ -94,6 +94,31 @@ The 850 carries the identifiers the 855 echoes back:
 full 850 → TOGa identifier map, incl. `BEG` = ODP PO number and `REF*QC` = the value to
 search on for the ODP SalesOrder.)
 
+## Rejections raise a business alert (Logs.Issue)
+A reject used to be **silent** — the PO was skipped and no human was notified. Cron `3a` now
+surfaces every over-quantity/duplicate rejection as a curated **Logs.Issue** alert by throwing
+`App_Exception_Business` (issue key **`COMPASS_OFFICE_DEPOT_PO_IMPORT_REJECTED_OVER_QUANTITY`**,
+`URGENCY_HIGH`, message listing the rejected PO numbers). The reject 855 is still built and
+acknowledged back to Office Depot first; the alert is purely additional notification. The issue
+key follows the sibling cron `1_transmit_compass_sales_orders_to_mits.php` naming convention.
+
+### ⚠ Gotcha — the throw is DEFERRED to end-of-run, never inline
+The exception is **not** thrown in the reject branch. It is deferred to the very end of the run:
+after the full `$ediFiles['Contents']` loop, after each S3 850 file is logged + deleted, and
+after `App_Framework::cronFinished()`. A single collector array
+(`$rejectedPurchaseOrderNumbers`) accumulates rejected PO numbers across all files/POs, and one
+exception is thrown at end-of-run.
+
+**Why it must be deferred:** an inline throw unwinds the loop *before* the per-file S3 delete, so
+the same 850 is re-fetched next run and a **duplicate reject 855 is re-sent to Office Depot every
+run — an "855 storm."** Deferring guarantees each 850 is deleted first, and the stable issue key
+collapses multiple rejects into one Logs.Issue.
+
+Throwing **after** `cronFinished()` is safe: the overlap guard
+(`App_Framework::exitIfProcessRunning`, a `ps -ef` process-table scan) has no dependency on
+cronFinished's `CronJobExecutions` checkout row, and on CLI an uncaught `App_Exception_Business`
+just echoes `ERROR [ref]:` and exits.
+
 ## ⚠ Open item — reject codes vs ODP's 855 companion guide
 The reject codes used (`BAK02 = RD`, `ACK01 = IR`) are the **standards-correct** X12 values.
 They have **not** yet been confirmed against Office Depot's 855 companion guide. If ODP
@@ -102,6 +127,13 @@ A legacy, abandoned sketch (`compass/edi/3_send_edi_855(reject).php`) used **non
 codes `BAK01 = A1` / `BAK02 = RE` — that path was **deliberately NOT followed**.
 
 ## Change history
+- 2026-08-13 — Rejections now raise a business alert: cron `3a` throws
+  `App_Exception_Business` (`COMPASS_OFFICE_DEPOT_PO_IMPORT_REJECTED_OVER_QUANTITY`,
+  `URGENCY_HIGH`) so every over-quantity/duplicate reject surfaces as a Logs.Issue instead of
+  being silent. The throw is **deferred to end-of-run** (after the file loop, per-file S3
+  delete, and `cronFinished()`) via a `$rejectedPurchaseOrderNumbers` collector — an inline
+  throw would skip the S3 delete and cause an "855 storm" (same 850 re-fetched, duplicate reject
+  855 re-sent every run). `php -l` clean; php-reviewer 0/0. (jcardinal)
 - 2026-08-13 — Built the over-quantity guard on the ODP 850 importer (cron 3a): ODP
   re-sending an already-processed Compass SO line under a new PO number now rejects the whole
   PO (new helper `officeDepotPurchaseOrderExceedsCompassDemand()`, "first occurrence passes",

package/package.json

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