toga-ai 1.0.60 → 1.0.62

package/knowledge/INDEX.md

@@ -25,4 +25,5 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **New York City Department of Education** (`nycdoe`) → [clients/nycdoe/INDEX.md](clients/nycdoe/INDEX.md)
 - **Prudential Financial** (`prudential`) → [clients/prudential/INDEX.md](clients/prudential/INDEX.md)
 - **Rate** (`rate`) → [clients/rate/INDEX.md](clients/rate/INDEX.md)
+- **Tow Foundation** (`tow-foundation`) → [clients/tow-foundation/INDEX.md](clients/tow-foundation/INDEX.md)
 

package/knowledge/clients/compass-usa/features/mits-po-to-so-item-linking.md

@@ -71,7 +71,28 @@ USA and Canada share the parent handler unchanged.
   number onto the line). Example seen on SA132739: UPS `1Z8696XA0193326215` actually shipped
   `C40QYUC-1` (SO line 4) but was attached to SO line 1 (`1000555`).
 
+- **Over-fulfillment (fulfilled qty > ordered) is the other visible symptom of the same
+  scramble.** When a spuriously-linked PO item ships, its ASN/PO-driven ItemFulfillment walks
+  the bad bridge link and creates a **phantom `ItemFulfillmentItem` on the wrong SO line**, so
+  that line shows more fulfilled than ordered (the same shipment is also fulfilled correctly on
+  its real line). Cleanup per order:
+  - **Spurious bridge rows:** delete where the SO item's part ≠ the PO item's part, scoped to
+    the one `salesOrderId` (`soi.itemId <> vi.itemId` via `VendorItems`). Idempotent.
+  - **Phantom IFI:** the duplicate on the over-fulfilled line is the IFI with **no
+    `ItemFulfillmentItemUnits`, no `ItemFulfillmentItems_TrackingNumbers`, and nothing
+    mirroring it** (`upstreamItemFulfillmentItemId`). The legitimate line fulfillment is the
+    sibling IFI that has a real `Unit` and/or a downstream mirror (often in an auto-numbered
+    `F#####` IF rather than the SO-named IF). Delete the phantom guarded by
+    `id + salesOrderItemId + itemFulfillmentId + quantity`.
+  - These are pre-fix orders only (POs created before the 2026-06-11 guard). Cleanup is
+    one-time data, written as a dated `dbchanges2/Client_Compass/` file per order.
+  - ⚠ Not every over-fulfilled Compass line is this bug — high multipliers (5×–20×) seen on
+    other orders (e.g. SA114091 25→125) do not fit the split-PO 2× pattern and are a separate,
+    uninvestigated cause.
+
 ## Change history
+- 2026-06-11 — Documented the over-fulfillment symptom and the phantom-IFI cleanup predicate;
+  remediated SA132657 and SA132641 (one dated dbchanges2 file each). (jcardinal)
 - 2026-06-11 — Guarded `postPost` SO↔PO item linking to MR orders only; SA links come solely
   from `prePost`'s `createdFromSalesOrderItem` remap. Fixes spurious cross-part links. (jcardinal)
 

package/knowledge/clients/tow-foundation/INDEX.md

@@ -0,0 +1,6 @@
+# Client: Tow Foundation `tow-foundation`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Credit Card Receipt Processing](features/receipt-processing.md) | 2.0 | Automated processing of credit card receipts uploaded to SharePoint. | worker2/Worker/Client/TowFoundation.php, worker2/Worker/Client/TowFoundation/ProcessReceipts.php |
+| [Tow Foundation](profile.md) | 2.0 | Tow Foundation is a nonprofit client. |  |

package/knowledge/clients/tow-foundation/features/receipt-processing.md

@@ -0,0 +1,130 @@
+---
+title: "Credit Card Receipt Processing"
+framework: "2.0"
+project: Worker
+client: tow-foundation
+type: client-feature
+status: active
+updated: 2026-06-11
+owners: ["rgirish"]
+files:
+  - worker2/Worker/Client/TowFoundation.php
+  - worker2/Worker/Client/TowFoundation/ProcessReceipts.php
+related:
+  - clients/tow-foundation/profile.md
+---
+
+## Summary
+
+Automated processing of credit card receipts uploaded to SharePoint. Downloads each
+receipt, extracts structured data via Talos AI, cross-verifies against billing-cycle
+statements, renames the file, archives it per cardholder, generates a QuickBooks-ready
+Excel file per person, uploads it to SharePoint, and sends a summary email.
+
+Invocation: `{"action": "Client/TowFoundation/ProcessReceipts/Run", "parameters": {}}`
+
+Optional filter parameters: `limit` (int), `year` (string e.g. `"2026"`), `person` (string e.g. `"Brent Peterkin"`).
+
+## Key files / entry points
+
+- `TowFoundation.php` — base class; holds all email constants and `initialize()` (empty — no client DB)
+- `ProcessReceipts.php` — all logic; abstract class extending `_Worker_Client_TowFoundation`
+
+## How it works
+
+### SharePoint folder structure
+```
+Credit Card Receipts/
+  {Person}/
+    {Year}/
+      {BillingCycleFolder}/   ← receipt files live here (e.g. "Amex ending in 06-03-2026")
+      {Person} reports/        ← .xlsx billing statements for cross-verification
+      Archive/
+        {Person}/              ← successfully processed receipts land here (renamed)
+        exception/
+          {Person}/            ← failed receipts land here (original name preserved)
+      3. QB Excel/             ← generated Excel files uploaded here after each run
+```
+
+### Processing flow
+
+1. **Auth** — OAuth2 client-credentials token from Microsoft Graph
+2. **Walk** — `walkReceiptsFolder()` enumerates all receipt files and statement Excels
+3. **Filter** — optional `$year` / `$person` / `$limit` applied to the receipt list
+4. **Pre-load statements** — all billing-cycle `.xlsx` files under `reports/` are downloaded
+   and parsed upfront via PhpSpreadsheet (auto-detect header row by scanning for
+   description/amount keywords)
+5. **Pass 1 — Extract** — for each receipt:
+   - Enforce size limit (4 MB images, 10 MB documents)
+   - Download file bytes from SharePoint
+   - POST to Talos AI `/api/ai/generate` → structured `{vendor_name, invoice_date, total, payment_memo, category, ...}`
+   - Cross-verify amount ± $0.01 against parsed statement; if matched, override `payment_memo` with statement description
+   - Build base filename (no suffix yet) and store in `$pendingRenames`
+   - On extract failure → move to `Archive/exception/{Person}/` immediately
+6. **Collision detection** — count base name occurrences across all pending renames
+7. **Pass 2 — Move** — for each pending rename:
+   - If base name appears more than once, assign `_a`, `_b`, `_c`... suffix to **all** colliding files (including the first)
+   - PATCH SharePoint to rename + move to `Archive/{Person}/`
+8. **Excel generation** — one `.xlsx` per person (PhpSpreadsheet); columns: Row #, Account Name, QB Vendor, Payment Amount, Date, Payment Method, Payment Memo, QB Description, Class, Category, Payment Account, Ref No.
+9. **SharePoint upload** — each Excel uploaded to `{Person}/{Year}/3. QB Excel/` via Graph API PUT
+10. **Summary email** — sent with Excel files attached; To: Jheanelle, CC: Magdalena, BCC: devteam@togatech.com
+
+### Renamed file format
+```
+YYYY.MM.DD Name of Cardholder_VendorName_Amount[_a].ext
+```
+- Vendor name: special chars stripped, spaces → underscores
+- Amount: two decimal places (e.g. `42.50`)
+- Suffix `_a`, `_b`... added when date + person + vendor + amount are all identical (e.g. multiple train tickets same day)
+
+### Ref No. (QuickBooks)
+Amex billing cycle runs 3rd-to-3rd. `computeRefNo()` returns the cycle-end date as `MMDDYYYY`.
+- Charge on or before the 3rd → cycle ends on the 3rd of the same month
+- Charge after the 3rd → cycle ends on the 3rd of the next month
+
+### Per-person constants
+`CLASS_MAP` and `PAYMENT_ACCOUNT_MAP` in `ProcessReceipts.php` map each cardholder's name
+to their QuickBooks Class and Payment Account strings. Ryan Farrell uses Bank of America
+Mastercard; all others use AMEX Open Credit Card.
+
+## Email routing
+
+Defined as constants in `TowFoundation.php`:
+
+| Constant | Value | Role |
+|---|---|---|
+| `NOTIFY_EMAIL_CLIENT` | `Jheanelle@towfoundation.org` | To |
+| `NOTIFY_EMAIL_CC` | `['Magdalena@towfoundation.org']` | CC |
+| `NOTIFY_EMAIL_BCC` | `['devteam@togatech.com']` | BCC |
+| `NOTIFY_EMAIL_DEV` | `devteam@goagilant.com` | To (always) |
+| `NOTIFY_EMAIL_EXTRA` | jcardinal, ajean, bmorton @goagilant.com | To |
+
+Fatal errors send only to `NOTIFY_EMAIL_DEV` (no CC/BCC).
+
+## Gotchas / known issues
+
+- **`$year` variable shadowing** — `Run()` uses `$year` as both a filter parameter and a
+  loop variable (line ~159: `$year = $receipt['year']`). After the loop `$year` holds the
+  last receipt's year, not the original filter value. Harmless now but fragile if the loop
+  is restructured.
+- **Two-pass rename is required** — collision detection must see ALL base names before any
+  file is moved. A single-pass approach would retroactively need to rename the first file
+  after discovering a duplicate, which is not possible once it's already on SharePoint.
+- **`_Loader::setThrowExceptionInAutoloaderIfClassNotFound(false)`** — must wrap all
+  PhpSpreadsheet calls. ZipStream is a Composer dependency that triggers the autoloader;
+  without this flag, it throws on missing class and aborts Excel generation.
+- **Graph API item-ID move** — `renameAndMoveToArchive()` resolves the target folder to an
+  item ID before PATCHing. Using path-based `parentReference` causes HTTP 400 on folder
+  names with special characters (spaces, dots). Always resolve to ID first.
+- **`ensureFolderPath()` for "3. QB Excel"** — the folder name contains a dot and space;
+  `ensureFolderPath` handles this correctly via `rawurlencode` on each path segment.
+- **Statement matching tolerance** — `matchStatementRow()` uses `abs($row['amount'] - $amount) < 0.01`
+  for amount matching, then date tie-break for multiple same-amount rows. Returns first
+  candidate if date tie-break also ambiguous.
+- **No client DB** — there is no audit trail in MySQL. All state lives in SharePoint folder
+  structure and email. If a run is interrupted mid-way, some receipts may be archived
+  without a corresponding Excel row.
+
+## Change history
+
+- 2026-06-11 — Added CC (Magdalena), BCC (devteam@togatech.com), per-cardholder Archive subfolders, Excel upload to "3. QB Excel" SharePoint folder, two-pass rename with alphabetical duplicate suffix, rename format changed to `YYYY.MM.DD Full Name_Vendor_Amount` (rgirish)

package/knowledge/clients/tow-foundation/profile.md

@@ -0,0 +1,35 @@
+---
+title: "Tow Foundation"
+framework: "2.0"
+project: Worker
+client: tow-foundation
+type: profile
+status: active
+updated: 2026-06-11
+owners: ["rgirish"]
+files: []
+related:
+  - clients/tow-foundation/features/receipt-processing.md
+---
+
+## Summary
+
+Tow Foundation is a nonprofit client. Their integration automates credit card receipt
+processing: receipts uploaded to SharePoint by cardholders are downloaded, extracted via
+Talos AI, cross-verified against Amex/Mastercard billing statements, renamed, archived,
+and exported as QuickBooks-ready Excel files.
+
+No client database is used (no persistence beyond SharePoint and email).
+
+## Contacts
+
+- **Jheanelle Gordon** — primary contact; receives the processing completion email
+- **Magdalena Minta** — CC on completion email
+- devteam@togatech.com — BCC on all emails
+
+## Key integration points
+
+- Microsoft SharePoint (Microsoft Graph API) — receipt file storage
+- Talos AI (`/api/ai/generate`) — structured receipt data extraction
+- PhpSpreadsheet — Excel generation and statement parsing
+- `_Email` — completion summary + fatal error notifications

package/package.json

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