toga-ai 1.0.569 → 1.0.570

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/package.json

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