toga-ai 1.0.305 → 1.0.307

package/knowledge/1.0/apps/library/features/startech-pcmaticb2b-sync.md

@@ -6,7 +6,7 @@ project: Library
 client: pcmaticb2b
 type: client-feature
 status: active
-updated: 2026-07-06
+updated: 2026-07-09
 owners: [snaredla]
 files:
   - library/app/api/toga2.php
@@ -75,11 +75,12 @@ Ruled out while debugging "nothing syncs to V1" (0/77 contacts + 0/37 entitlemen
 
 Imports Startech (Easeedesk V3) config into TOGA 2.0 — users, groups, devices, categories, ticket types.
 
-- **Groups** must come from `GET /groups_dispatching` (`data.dispatch[]`, keys `group_id`/`group_name`). The company-scoped `dynamic_field_options->data->groups` returns empty here — groups are provider-level, not per-company.
-- **Categories** — `App_Api_StarTechTicket::getCategories($companyId, $ticketTypeIds)` forwards a `ticket_type` filter alongside `company`. ⚠ The param name `ticket_type` is **unverified** against the Easeedesk API (not documented for `/tickets/categories`) — confirm in Postman before relying on type filtering; if it's ignored, categories come back unfiltered.
+- **Groups** come from `dynamic_field_options->data->groups` (keys `ID`/`group_name`) — verified 2026-07-09 returning **16 groups** for company 24412. The earlier claim that this returns empty and groups must come from `/groups_dispatching` was **wrong**: the empty result was caused by **incorrect credentials** in `startechticket.php` (`agilant.api`), not the endpoint. Fixed by using the `pcmaticb2b@startechteam.ro` account. `/groups_dispatching` returned 0 and is not used.
+- **Categories** — `App_Api_StarTechTicket::getCategories($companyId, $ticketTypeIds)` forwards a `ticket_type` filter alongside `company`. **Verified 2026-07-09**: `company=24412&ticket_type=50,54` returns 15 categories (the scoped set); the `ticket_type` param works as intended.
 - Any single upsert failing aborts the run (all `send()` calls throw on API error); the block order is users → groups → devices → categories → ticket types.
 
 ## Change history
 
 - 2026-06-23: Initial doc — ticket type maps (both directions), NULL sync behavior, TOGADESK_PCS type added
 - 2026-07-06: Added syncWithToga V1 leg (cross-ref gating, cron-abort ordering, debugging findings) and supporting-records import notes (groups via groups_dispatching, getCategories ticket-type filter)
+- 2026-07-09: Corrected the groups note — groups come from `dynamic_field_options->data->groups` (16 groups); the empty result was a credentials bug (`agilant.api`), not the endpoint. Confirmed `getCategories` `ticket_type` filter works (`50,54` → 15 categories).

package/knowledge/clients/pcmaticb2b/INDEX.md

@@ -2,5 +2,6 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [PC Matic B2B — Startech Entitlement Provisioning (customer + SKU)](features/startech-entitlement-provisioning.md) | 2.0 | When a PC Matic B2B entitlement is created in TOGA 2.0 (`POST /entitlements`), the client registers the customer on StarTech's OptimumDesk platform and assigns | _underscore/Trait/Startech/Entitlement.php, _underscore/Model/Pcmaticb2b/Entitlement.php, _underscore/Config.php, api2/Config/production.ini, api2/Config/beta.ini, api2/Config/sandbox-client.ini, test/@srija/Startech Testing/PC Matic B2B/test_e2e_pcmaticb2b.sh |
 | [PC Matic B2B — Startech Ticket Sync](features/startech-ticket-sync.md) | 1.0 | Bidirectional ticket sync between TOGaDesk 1.0 (client 177), TOGA 2.0 (client 21), and Startech (Easeedesk). | worker/crons/toga2/startech/sync_togadesk_startech_pcmaticb2b.php, worker/crons/toga2/startech/common_import_supporting_records.php, library/app/api/toga2.php, library/app/api/startechticket.php, togadesk/desk/includes/controllers/quickactions.php, togadesk/desk/template/pages/tickets/manage.php, togadesk/desk/includes/functions.php, worker2/Worker/Startech.php, _underscore/Trait/Startech/Ticket.php, dbchanges2/Client_Pcmaticb2b/2026-06-22-pcmaticb2b-enhancements.sql |
 | [PC Matic B2B Client Profile](profile.md) | 1.0 | PC Matic B2B is a client using TOGaDesk 1.0 for ticket management, with TOGA 2.0 as the data layer and Startech (Easeedesk) as an external ticketing system for | worker/crons/toga2/startech/sync_togadesk_startech_pcmaticb2b.php, togadesk/desk/includes/functions.php |

package/knowledge/clients/pcmaticb2b/features/startech-entitlement-provisioning.md

@@ -0,0 +1,118 @@
+---
+title: PC Matic B2B — Startech Entitlement Provisioning (customer + SKU)
+framework: "2.0"
+project: TOGa
+client: pcmaticb2b
+type: client-feature
+status: active
+updated: 2026-07-09
+owners: [snaredla]
+files:
+  - _underscore/Trait/Startech/Entitlement.php
+  - _underscore/Model/Pcmaticb2b/Entitlement.php
+  - _underscore/Config.php
+  - api2/Config/production.ini
+  - api2/Config/beta.ini
+  - api2/Config/sandbox-client.ini
+  - test/@srija/Startech Testing/PC Matic B2B/test_e2e_pcmaticb2b.sh
+related:
+  - clients/pcmaticb2b/features/startech-ticket-sync.md
+  - clients/pcmaticb2b/profile.md
+  - 1.0/apps/library/features/startech-pcmaticb2b-sync.md
+---
+
+## Summary
+
+When a PC Matic B2B entitlement is created in TOGA 2.0 (`POST /entitlements`), the client
+registers the customer on StarTech's OptimumDesk platform and assigns the entitlement SKU.
+This is the "provisioning" leg — distinct from the ticket sync. It is **one-way, POST-only**:
+it fires on entitlement create, not on update.
+
+## Key files / entry points
+
+- `_Model_Pcmaticb2b_Entitlement::postPost` (`_underscore/Model/Pcmaticb2b/Entitlement.php`)
+  activates the subscription (`isActive = true`) then calls the trait via
+  `use _Trait_Startech_Entitlement { postPost as traitEntitlementPostPost; }`.
+- `_Trait_Startech_Entitlement::postPost` (`_underscore/Trait/Startech/Entitlement.php`)
+  does the two OptimumDesk calls.
+
+## How it works
+
+1. `POST /customer` — body `{ firstName, lastName, emailAddress }` →
+   `{"status":"OK","customerId":"<id>"}`. If already present, the response message contains
+   `Already Registered` + `customerId=<id>` (regex-extracted).
+2. `POST /sku` — body is a **JSON array** of assignment objects:
+   `[{ "customerID": "<id>", "sku": "140102", "purchaseDate": "YYYY-MM-DD", "quantity": "1" }]`
+   → `{"status":"OK","service_id":<id>,"sku":140102}`.
+   - `customerID` is **capital-D** (lowercase `customerId` fails customer resolution).
+   - `sku` `140102` = `_Model_Pcmaticb2b_Entitlement::STARTECH_ENTITLEMENT_SKU`.
+
+## Endpoint & credentials
+
+- Unified endpoint `https://scuses.optimumdesk.com`, **HTTP Basic auth**, account
+  `pcmaticb2b@startechteam.ro`.
+- Credentials come from config section **`[startechPcmaticb2b]`**, read via
+  `_Config::startechPcmaticb2b('opDeskEndpoint' | 'opDeskUsername' | 'opDeskPassword')`.
+  `_Config` has **no explicit method** — `__callStatic` maps the method name directly to the
+  ini section name, so the section name and the call must match exactly.
+- The section exists in `production.ini`, `beta.ini`, and `sandbox-client.ini`
+  (key order: endpoint, username, password). It was previously named `[asiIntegration]`
+  (account `asi.integration`) — renamed because that account's catalog lacked SKU 140102.
+
+## Data model
+
+- `_Model_Pcmaticb2b_Entitlement` adds `c_togaServiceRequestId` (INTEGER). The trait does
+  **not** write it — it is set later by the `syncWithToga` V1 write-back leg.
+- `prePost` rejects a cancelled subscription (`dateCancelled !== null` → "Subscription not valid").
+
+## Client variations
+
+Provisioning is pcmaticb2b-only; the trait is applied solely to `_Model_Pcmaticb2b_Entitlement`.
+
+## Verifying it worked
+
+There is **no GET-SKU / list-services endpoint** on the provisioning API — probing
+`/sku?customerID=`, `/customer/{id}/services`, `/skus/{id}` all return the OptimumDesk
+"machine-to-machine" 404 page. Only `GET /customer/{id}` works, and it does **not** list SKUs.
+
+The authoritative check is the **outbound API log**:
+```sql
+SELECT direction, method, route, responseCode, responsePayload
+FROM Logs_Pcmaticb2b.Api
+WHERE direction = 'OUT' AND route IN ('/customer', '/sku')
+ORDER BY id DESC LIMIT 4;
+```
+Look for `OUT POST /sku` → `service_id` + `sku:140102`, `responseCode 200`. The framework
+logs the trait's outbound calls here with `direction='OUT'`.
+
+## End-to-end verification (2026-07-09, post-deploy)
+
+Confirmed live against production `api.togahub.com`:
+- `POST /entitlements` → 201; subscription flipped `isActive=1`.
+- Trait fired → OUT log showed `POST /customer` OK (`customerId 1864974`) and
+  `POST /sku` OK (`service_id 623917`, `sku 140102`).
+
+Runnable harness: `test/@srija/Startech Testing/PC Matic B2B/test_e2e_pcmaticb2b.sh` (bash +
+curl + python). Covers entitlement flow, provisioning direct, ticketing, and import read-side
+with PASS/FAIL assertions. TOGA2 curl auth = `POST /auth/api {client,api,secret}` →
+`data.tokens.access`, then `Authorization: Bearer`.
+
+## Gotchas / known issues
+
+- **Silent failure.** On any error the trait `error_log`s and returns — no exception. If creds
+  or endpoint are wrong, provisioning fails invisibly. Check `error_log` / the OUT log.
+- **`/sku` must be an array**, and `customerID` must be capital-D.
+- **One-way, POST-only.** No `postPut` — an entitlement created/updated through any non-POST
+  path (or the `syncWithToga` PUT write-back) does not (re)register the SKU.
+- **Config drift across envs.** All three env inis must carry `[startechPcmaticb2b]`; a missing
+  section means `_Config::startechPcmaticb2b()` returns falsy and the trait bails.
+
+## Related docs
+
+- Ticket sync: `clients/pcmaticb2b/features/startech-ticket-sync.md`
+- Library sync engine + import: `1.0/apps/library/features/startech-pcmaticb2b-sync.md`
+
+## Change history
+
+- 2026-07-09: Initial doc — entitlement→OptimumDesk customer+SKU provisioning, unified
+  endpoint, `[startechPcmaticb2b]` config rename, no-GET-SKU / OUT-log verification, E2E test.

package/knowledge/clients/pcmaticb2b/features/startech-ticket-sync.md

@@ -5,7 +5,7 @@ project: TOGa
 client: pcmaticb2b
 type: client-feature
 status: active
-updated: 2026-07-06
+updated: 2026-07-09
 owners: [snaredla]
 files:
   - worker/crons/toga2/startech/sync_togadesk_startech_pcmaticb2b.php
@@ -22,6 +22,7 @@ related:
   - clients/pcmaticb2b/profile.md
   - 2.0/apps/worker2/features/startech-webhook-handler.md
   - 1.0/apps/library/features/startech-pcmaticb2b-sync.md
+  - clients/pcmaticb2b/features/startech-entitlement-provisioning.md
 ---
 
 ## Summary
@@ -72,6 +73,8 @@ Column: `TINYINT(1) UNSIGNED NULL DEFAULT NULL`
 
 The `ticketType` on Startech-originated tickets is resolved dynamically via `c_startechTicketTypeId` on `TicketTypes` — not hardcoded.
 
+**Verified 2026-07-09 (company 24412):** `getTicketTypes(24412)` returns exactly two active types — **50 = Support Request**, **54 = Phone Call Support**. The import cron uses `STARTECH_TICKET_TYPE_IDS='50,54'` and maps them to TOGaDesk departments `50→336` (Support Request), `54→337` (Phone Call/PCS). The older `SUPPORT REQUEST=6 / API=201` values above are stale for this company — treat 50/54 as authoritative.
+
 ## Sync Direction 1: Startech to TOGA 2.0 (Webhook)
 
 `worker2/Worker/Startech.php` — `_Worker_Startech::Webhook()`
@@ -162,7 +165,34 @@ const TOGADESK_TICKET_TYPE__TOGADESK_PCS   = 'TOGaDesk-PCS';
 - **Staff-email collision.** `App_Api_Toga2::syncToga2ContactIntoTogadesk1People` matches `people` by email OR referenceId and **updates in place**. If the email already exists as a staff/admin account (clientid ≠ 177), it links `referenceId` onto that staff row and never creates a client-177 `type='user'` customer. Use a fresh, non-staff email for customer test tickets.
 - **The escalate button applies desk changes unconditionally.** The handler sets dept→337, `escalateToStartech=1`, Ticket Type→"Phone Call Support", and adds history **regardless of 2.0 linkage**. The `c_escalateToStartech=1` PUT (which triggers Startech) fires **only when `referenceId` is already set**; unlinked tickets are left for the sync cron to link — the button does not create the 2.0 ticket on-demand.
 
+## Sync Risks (2026-07-09, from full-path trace)
+
+These are latent issues in the current loop-guard design — flagged for a follow-up fix,
+not yet resolved:
+
+1. **`c_escalateToStartech` is never reset after escalation.** Once an analyst escalates,
+   the 2.0 record keeps `=1` permanently. Every subsequent togadesk→2.0 sync PUT (every 2 min
+   on any ticket/note change) delivers `$outData` with `escalate=1` + `c_startechTicketId` set,
+   so `postPut` passes the `!== 1` guard and re-pushes a `change_ticket_status`/category update
+   to StarTech each cycle. Not an infinite loop, but repeated echo updates.
+2. **Webhook flips `1→0`, silencing later analyst-side updates.** Once StarTech's webhook writes
+   `c_escalateToStartech=0` on an escalated ticket, later Togadesk edits (synced up without
+   setting escalate) leave the stored value at 0, so `postPut`'s `!==1` guard blocks them —
+   legitimate analyst changes to an escalated ticket may stop propagating to StarTech.
+3. **Interceptor firing is DB-gated.** `postPost`/`postPut` only run if an active
+   `ApiPayloadInterceptor` row exists for `_Model_Pcmaticb2b_Ticket` POST/PUT
+   (`api2/Component/Api/V2/V2.php`). Correct trait code is insufficient — verify the rows in
+   the live client DB or escalation silently never fires.
+
+## Verification
+
+- **Entitlement provisioning** (customer + SKU) — see
+  `clients/pcmaticb2b/features/startech-entitlement-provisioning.md`. Confirm via
+  `Logs_Pcmaticb2b.Api` `direction='OUT'` rows for `/customer` + `/sku`.
+- **Runnable E2E harness:** `test/@srija/Startech Testing/PC Matic B2B/test_e2e_pcmaticb2b.sh`.
+
 ## Change history
 
 - 2026-06-23: Initial doc — full bidirectional sync, c_escalateToStartech semantics, ticket type maps, escalate button, DB migration, constants, gotchas
 - 2026-07-06: Added sync prerequisites/gotchas (entitlement gate, staff-email collision) and clarified the escalate button's actual behavior (desk changes always; 2.0 PUT only when linked)
+- 2026-07-09: Corrected Startech ticket-type IDs (50 Support Request, 54 Phone Call Support for company 24412); added Sync Risks (escalate flag never reset, webhook 1→0 silencing, interceptor DB-gating) and Verification (OUT-log + E2E test); cross-linked entitlement provisioning.

package/knowledge/sessions/2026-07-09-surface-local-db-replay-apeterson.md

@@ -0,0 +1,66 @@
+---
+type: session
+slug: surface-local-db-replay
+title: Reset local DB from beta, then replay Surface-feature DB changes to LOCAL
+author: apeterson
+repos: [toga25-supply, api2, _underscore, dbchanges2]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-07-09
+updated: 2026-07-09
+---
+
+# Session: surface-local-db-replay
+**Date:** 2026-07-09
+**Project/Repo:** toga25-supply (2.0)
+**Task:** Reset the local dev database from beta (dev-sandbox), fix the resulting breakage, then manually replay the Surface UI feature's DB changes to LOCAL one SQL step at a time, logging every command.
+
+---
+
+## What WORKED
+<!-- Include specific file paths and evidence -->
+- **Local DB refresh from beta.** Per-schema `mysqldump` from `dev.sandbox.database.togahub.com` → local `DROP DATABASE`/`CREATE DATABASE` → re-import. Refreshed `Core`, `Client_Compass`, `Client_CompassCanada`, `Client_Nychh`, `Client_Quad`. Verified: local `Core` = 48 tables matched beta's 48; beta reachability proven via `SELECT @@hostname` = `ip-172-17-3-190`. Local backups taken first to `/tmp/LOCAL_BACKUP_<DB>.sql`.
+- **Non-locking dump flags** for the RELOAD-less sandbox `admin` user: `mysqldump --skip-lock-tables --no-tablespaces --set-gtid-purged=OFF --routines --triggers` (NO `--single-transaction`). Dump completed (`-- Dump completed on …` marker present).
+- **Fixed the whole-API 500** (`_Model_Client_BundleTranslation` not found) by bringing `Model/Client/BundleTranslation.php` into local `_underscore` from feature branch `TRUE-80065` (commit `ef6ebd80`). Login worked afterward. No server restart needed (models autoload per-request).
+- **Fixed CompassCanada 1146** (`advanceshippingnoticeitemunits doesn't exist`) by running `toga25-supply/sync_compasscanada_schema.sql` against `Client_CompassCanada` — but only after selecting the DB in the client UI (see failures). SO record loads now.
+- **Surface Core replay to LOCAL (all done):** `ALTER Core.SurfaceElements ADD iconWeightToken` + set weights on ids 17/18/19/21; `sales-order-listing-actions` BUTTON_BAR seed; slug renames (`sales-order-actions`→`sales-order-record-actions`, `sales-order-row-actions`→`sales-order-listing-row-actions`); `sales-order-record-approvals` gate (Core off + enable Compass/CompassCanada/Quad); `sales-order-record-header` surface.
+- **Per-client data (all done):** F1 client feature tables across all 32 `Client_*`; Gina (user 4273) role fix in Compass; Compass Manager (role 8) hides approval-workflow (surf 8/el 19) + admin-notes (surf 20/el 37); Approvals-filter hides — Compass role 8, CompassCanada role 9, Quad + NYCHH all-users.
+- **Execution log** written to `toga25-supply/db-migrations/DB-CHANGE-LOG.md` (SQL-only, per user preference), one entry per step run.
+
+## What did NOT work — DO NOT RETRY THESE
+<!-- Exact failure reasons — do not vague-ify -->
+- `mysqldump --single-transaction …` against beta → `mysqldump: Couldn't execute 'FLUSH TABLES WITH READ LOCK': Access denied for user 'admin'@'%' (using password: YES) (1045)`. The sandbox `admin` lacks RELOAD. `--single-transaction` still issues FTWRL on MySQL 8; adding `--skip-lock-tables` did NOT suppress it. Fix = remove `--single-transaction` entirely.
+- Direct `mysql -h dev.sandbox.database.togahub.com` off-VPN → `ERROR 2003 (HY000): Can't connect … (60)` (timeout). Host is firewalled; requires company VPN.
+- Running `sync_compasscanada_schema.sql` with a standalone `USE Client_CompassCanada;` line executed separately from the `CREATE` block → tables landed in the wrong DB; verify `SELECT` returned 0 rows in `Client_CompassCanada` and the SO record kept 1146-ing (identical error). The `USE` did not carry across separate executions in the client. Fix = select `Client_CompassCanada` as the active DB in the client UI, then run the whole file in one execution.
+- Initial assumption that the "still 500s" CompassCanada error was caching — it was not; the tables genuinely weren't in the DB (0-row verify). Don't assume cache before verifying table existence.
+
+## Not tried yet (candidates for next session)
+- **F2 ACL-grant verify** (paused by user). Multi-client read-only check drafted: for Compass/CompassCanada/Quad/NYCHH/Prudential, confirm `AclRecordScripts` has both `surfaces/meta` and `surfaces/meta-group` granted. Expectation: already present (Step 1's Section 2 applied it since Core had `meta-group` from the reset). Full 32-client coverage would need a 32-way UNION or a loop.
+- **In-app UI verification** across Compass, Compass Canada, Quad, NYCHH: status badge, record header, approvals gate visibility, and the role-gated hidden buttons.
+- Cleanup of stray empty tables if `sync_compasscanada_schema.sql` first landed in the wrong DB (identify which DB was selected, drop the 17 empties there).
+- Remove the ~3.4 GB of `/tmp/*_beta.sql` dumps and `/tmp/LOCAL_BACKUP_*.sql` backups once confident.
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| toga25-supply/db-migrations/DB-CHANGE-LOG.md | created | Full SQL-only execution log of the LOCAL replay (steps 1–8 + L2). |
+| _underscore/Model/Client/BundleTranslation.php | added (from branch TRUE-80065) | Fixes the autoload 500; committed source, brought in via git. |
+| Local MySQL (localhost) | modified | Core + 4 clients reset from beta; Surface changes replayed; CompassCanada drift synced. LOCAL only. |
+| toga25-supply/sync_compasscanada_schema.sql | unchanged | Existing file; run against Client_CompassCanada this session. |
+
+## Decisions made
+- **Beta reset target scope = Core + Compass/CompassCanada/NYCHH/Quad only** (not all 32), per user. Rationale: those are the clients in play; other locals left as-is.
+- **Use hardcoded element ids 17/18/19/21 (icon weights) and 8/19, 20/37 (Manager hides)** per user preference, after verifying they matched local Core. Rejected: slug-resolved lookups (user wanted the literal ids); but #7/#8 were converted to `NOT EXISTS`-guarded to be idempotent.
+- **DB-CHANGE-LOG entries are SQL-only, added only after the user confirms a step ran** (two explicit user preferences). Large 16 KB DDL (`sync_compasscanada_schema.sql`) referenced rather than inlined to avoid drift.
+- **CompassCanada drift sync classified LOCAL-ONLY** — do NOT replay to beta/prod (prod already has the 17 tables).
+- **NEVER merge the beta branch into a feature branch** (user rule; distinct from resetting the local DB from beta). Missing code (BundleTranslation.php) pulled from the specific feature branch, not a beta merge.
+
+## Blockers
+none
+
+## Exact next step
+> Run the paused F2 ACL-grant verify (multi-client `SELECT` over `Client_Compass`/`CompassCanada`/`Quad`/`Nychh`/`Prudential` `AclRecordScripts` joined to `Core.RecordScripts`, checking both `meta` and `meta-group` are granted). If any client is missing `meta-group`, run the guarded grant re-run for that client; otherwise mark F2 done and proceed to in-app UI verification.
+
+---
+_Saved by /session-save on 2026-07-09_

package/package.json

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