toga-ai 1.0.101 → 1.0.102

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.102",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",