toga-ai 1.0.199 → 1.0.200

package/knowledge/INDEX.md

@@ -15,7 +15,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 14 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 15 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 15 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 6 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 2 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/knowledge/clients/rate/INDEX.md

@@ -3,6 +3,7 @@
 | 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 SalesOrder → NetSuite CashSale Export (postPost)](features/netsuite-cashsale-export.md) | 2.0 | Rate sells home-warranty / home-tech-support products. | _underscore/Model/Rate/SalesOrder.php, _underscore/Model/Rate/Item.php |
 | [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 |
 | [Service Card Entitlement Display](features/service-card-entitlements.md) | 2.0 | Rate's home and services pages display one service card per purchased entitlement. | src/components/ServiceCard/ServiceCard.tsx, src/components/ServiceCard/index.ts, src/hooks/useBundleServices.ts, src/pages/Home/api/homeApi.ts, src/pages/Home/view/HomePage.tsx, src/pages/Home/viewModels/useHomePageViewModel.ts, src/pages/Services/view/ServicesPage.tsx, src/pages/Services/viewModels/useServicePageViewModel.ts |
 | [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

package/knowledge/clients/rate/features/netsuite-cashsale-export.md

@@ -0,0 +1,92 @@
+---
+title: "Rate SalesOrder → NetSuite CashSale Export (postPost)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: rate
+type: client-feature
+status: active
+updated: 2026-06-25
+owners: ["rgirish"]
+files:
+  - _underscore/Model/Rate/SalesOrder.php
+  - _underscore/Model/Rate/Item.php
+related:
+  - 2.0/apps/_underscore/features/netsuite-rest-client.md
+  - clients/rate/profile.md
+---
+
+## Summary
+
+Rate sells home-warranty / home-tech-support products. When a Rate SalesOrder is created,
+the `_Model_Rate_SalesOrder::postPost` interceptor builds and writes a NetSuite **CashSale**
+(not a SalesOrder). This doc covers two pieces of that export added 2026-06-25: passing the
+order's ship-to (property) address onto the CashSale, and resolving each line item's NetSuite
+item internalId from a dedicated column with a partNumber fallback.
+
+This is Rate's override of the shared NetSuite write path documented in
+`2.0/apps/_underscore/features/netsuite-rest-client.md`.
+
+## Key files / entry points
+
+| File | Role |
+|---|---|
+| `_underscore/Model/Rate/SalesOrder.php` | `postPost` interceptor — builds the NetSuite CashSale (address + line items) |
+| `_underscore/Model/Rate/Item.php` | `_Model_Rate_Item` — declares `c_netsuiteInternalItemId` so the column is API-exposed and UI-settable |
+
+## How it works
+
+### Ship-to address → CashSale `shippingAddress`
+The `postPost` SQL query was expanded to `LEFT JOIN Addresses` (via
+`SalesOrders.shipToAddressId`) and `States`, selecting `line1`, `line2`, `city`, the
+state code, and `zip`. The address is captured from the first result row and set as a
+top-level `shippingAddress` on the CashSale — an `Address` object with `override=true`
+and `country='_unitedStates'`.
+
+This fires for **every** order that has a `shipToAddressId` set — it is **not** restricted
+to the Whole Home Warranty SKU (1429124), because `shippingAddress` is a top-level field on
+the CashSale, not a per-line concern. (The business driver was Whole Home Warranty orders
+needing the property address in NetSuite so ops / account teams can determine regional
+pricing, but the field applies to all orders.)
+
+### Line item NetSuite internalId resolution
+Each line item's NetSuite `RecordRef` internalId is now resolved as:
+
+1. `Items.c_netsuiteInternalItemId` when populated, else
+2. the hard-coded `partNumber` integer (1429122 / 1429123 / 1429124) as a fallback.
+
+The query was updated to `SELECT Items.c_netsuiteInternalItemId` alongside `partNumber`.
+The fallback exists because ops has not yet populated `c_netsuiteInternalItemId`.
+
+### `c_netsuiteInternalItemId` field declaration
+`Client_Rate.Items` has a `c_netsuiteInternalItemId INT` column that was not declared in the
+ORM. It is now declared as `FIELD_INTEGER` on `_Model_Rate_Item`, so the column is exposed
+through the API and can be set via the UI.
+
+## Production data state (as of 2026-06-25)
+
+- **All 39 Rate SalesOrders in `Client_Rate.SalesOrders` have `shipToAddressId = NULL`.**
+  The new code path only populates `shippingAddress` once the frontend starts setting
+  `shipToAddressId` on order creation. For the historical backfill export, the address was
+  pulled from the contact's `primaryContactAddressId → ContactAddresses → Addresses` join
+  instead — a one-off, not the going-forward path.
+- **`Items.c_netsuiteInternalItemId` is NULL for all three Rate SKUs** (partNumbers
+  1429122, 1429123, 1429124). Until ops populates it, the partNumber-integer fallback is the
+  active internalId path.
+
+## Gotchas / known issues
+
+- **`shippingAddress` only flows when `shipToAddressId` is set.** No live order has it set
+  yet (all 39 are NULL), so the new address path is effectively dormant until the frontend
+  populates the field on creation. Don't assume the CashSale carries an address from current
+  prod data.
+- **internalId fallback is partNumber, not the NS internalId.** Until ops backfills
+  `c_netsuiteInternalItemId`, CashSale lines reference the partNumber integer as the NS item
+  internalId. These happen to coincide for Rate today, but the clean path is the column.
+- **Historical backfill used a different address source** (contact primary address), not
+  `shipToAddressId` — do not confuse the one-off backfill join with the going-forward order
+  path.
+
+## Change history
+
+- 2026-06-25 — Added ship-to address (`LEFT JOIN Addresses`/`States`) to the CashSale as a top-level `shippingAddress` (override=true, US); resolved line-item NS internalId from `c_netsuiteInternalItemId` with partNumber fallback; declared `c_netsuiteInternalItemId` on `_Model_Rate_Item`. Confirmed all 39 prod orders have NULL `shipToAddressId` and all 3 SKUs have NULL `c_netsuiteInternalItemId` (rgirish)

package/knowledge/clients/rate/profile.md

@@ -10,12 +10,13 @@ project: SAML SSO Gateway
 client: rate
 type: profile
 status: active
-updated: 2026-06-24
+updated: 2026-06-25
 owners: ["rgirish", "bala"]
 files: []
 related:
   - clients/rate/features/saml-sso.md
   - clients/rate/features/monthly-reconciliation-report.md
+  - clients/rate/features/netsuite-cashsale-export.md
 ---
 
 ## Summary

package/package.json

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