toga-ai 1.0.313 → 1.0.314

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

@@ -5,7 +5,7 @@ project: TOGa
 client: pcmaticb2b
 type: client-feature
 status: active
-updated: 2026-07-09
+updated: 2026-07-10
 owners: [snaredla]
 files:
   - _underscore/Trait/Startech/Entitlement.php
@@ -31,10 +31,11 @@ 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; }`.
+  activates the subscription (`isActive = true`), calls the trait, then links the returned
+  customerId onto the contact (see "Contact linkage" below).
 - `_Trait_Startech_Entitlement::postPost` (`_underscore/Trait/Startech/Entitlement.php`)
-  does the two OptimumDesk calls.
+  does the two OptimumDesk calls and **returns the resolved `customerId`**. It is
+  **client-agnostic** — no client-specific model references (that was moved to the model).
 
 ## How it works
 
@@ -47,6 +48,22 @@ it fires on entitlement create, not on update.
    - `customerID` is **capital-D** (lowercase `customerId` fails customer resolution).
    - `sku` `140102` = `_Model_Pcmaticb2b_Entitlement::STARTECH_ENTITLEMENT_SKU`.
 
+## Contact linkage (customerId → c_startechUserId)
+
+After the trait resolves the `customerId`, `_Model_Pcmaticb2b_Entitlement::postPost` writes it
+onto the entitlement's contact as **`c_startechUserId`** (loads the contact by
+`payload->contact->uuid`, saves via direct model — wrapped in its own try/catch so a linkage
+failure never blocks provisioning).
+
+Why: OptimumDesk uses this **same id** as the ticket `creator`/`affected_user` and as the
+`owner_id` for the subscriptions endpoint. Pre-linking it means inbound Startech webhooks match
+the existing contact (webhook matches on `affected_user` = `c_startechUserId`) instead of
+creating a duplicate. Confirmed: **provisioning `customerId` = ticketing owner id = `c_startechUserId`**
+(same id-space).
+
+Design note: the trait returns the id and stays client-agnostic; the pcmatic-specific write
+lives in the client model. Do **not** put client model refs back in the trait.
+
 ## Endpoint & credentials
 
 - Unified endpoint `https://scuses.optimumdesk.com`, **HTTP Basic auth**, account
@@ -71,11 +88,18 @@ Provisioning is pcmaticb2b-only; the trait is applied solely to `_Model_Pcmaticb
 
 ## 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**:
+**Read-back endpoint (added by StarTech 2026-07-10):**
+```
+GET /api/v3/easeedesk/owner/{owner_id}/activated_subscriptions      (JWT auth)
+```
+Returns the active subscriptions for an owner — `sku`, `sku_name`, `devices_left`,
+`workorder_id`, `workorder_sku_id`, `ticket_id`. **`owner_id` = the provisioning `customerId`
+= the contact's `c_startechUserId`**, so no extra lookup is needed to call it. Verified live
+returning SKU `140102` "24/7 Unlimited Tech Support B2B" for our provisioned customers.
+(The provisioning API itself still has no GET-SKU route — only `GET /customer/{id}`, which does
+not list SKUs; the ticketing/JWT API above is where subscriptions are read back.)
+
+The other authoritative check is the **outbound API log**:
 ```sql
 SELECT direction, method, route, responseCode, responsePayload
 FROM Logs_Pcmaticb2b.Api
@@ -112,7 +136,19 @@ with PASS/FAIL assertions. TOGA2 curl auth = `POST /auth/api {client,api,secret}
 - Ticket sync: `clients/pcmaticb2b/features/startech-ticket-sync.md`
 - Library sync engine + import: `1.0/apps/library/features/startech-pcmaticb2b-sync.md`
 
+## PC Matic integration note
+
+PC Matic does **not** integrate with StarTech directly and needs no StarTech creds/API. Every
+sale → PC Matic creates an **entitlement in TOGA 2.0** → this trait provisions the customer +
+SKU to StarTech → an **active subscription** appears on StarTech. Customers/agents verify
+subscriptions via the PC Matic Agent, the OptimumDesk portal (Customers → customer → subscriptions),
+or the `activated_subscriptions` endpoint above.
+
 ## 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.
+- 2026-07-10: Refactor — trait returns customerId (client-agnostic); model writes
+  `c_startechUserId` on the contact. Added `activated_subscriptions` read-back endpoint
+  (owner_id = customerId = c_startechUserId). Noted PC Matic does not integrate with StarTech.
+  E2E confirmed in prod (17/17).

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-09
+updated: 2026-07-10
 owners: [snaredla]
 files:
   - worker/crons/toga2/startech/sync_togadesk_startech_pcmaticb2b.php
@@ -75,6 +75,37 @@ The `ticketType` on Startech-originated tickets is resolved dynamically via `c_s
 
 **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.
 
+## Ticket Statuses & Workflows (verified 2026-07-10, company 24412)
+
+Statuses are **per workflow**, and the workflow is keyed by its **workflow_id — NOT the ticket-type id**:
+
+- Support Request (type 50) → **workflow_id 56**
+- Phone Call Support (type 54) → **workflow_id 59**
+
+```
+GET /api/v3/easeedesk/tickets/workflows
+GET /api/v3/easeedesk/tickets/statuses?workflow_id=56   # Support Request
+GET /api/v3/easeedesk/tickets/statuses?workflow_id=59   # Phone Call Support
+```
+⚠ Do **not** pass the type id (50/54) as `workflow_id` — that queries a different workflow and returns unrelated statuses (this caused an earlier mis-read that reported "subscription statuses" on 54).
+
+### Our `TicketStages.c_startechStageId` vs the workflows
+| TOGA stage | c_startechStageId | in 56 (SR) | in 59 (PCS) |
+|---|---|---|---|
+| New Ticket | 1 | ✓ | ✓ |
+| In Progress | 2 | ✓ | ✓ |
+| Resolved | 5 | ✓ | ✓ |
+| Reopened | 6 | ✓ | ✓ |
+| Closed | 7 | ✓ | ✓ |
+| Awaiting User | 210 | ✗ disabled by StarTech | ✗ |
+| Open | 72 | ✗ not in workflow | ✗ |
+| On Hold | 209 | ✗ disabled by StarTech | ✗ |
+
+StarTech (Razvan) enabled Resolved(5)/Reopened(6)/Closed(7) in both workflows and **disabled Awaiting User(210) & On Hold(209)**; `Open(72)` is not present in either. So **those three stage mappings are currently invalid** and would be rejected on sync.
+
+### Pending enhancement — per-ticket-type statuses
+Each workflow also exposes many operational statuses we don't handle (Connected, Transferred, User Offline, Cancelled, Remote Control, Customer Confirmation, Lost, Dispatched, Automate Check, Live, Rework), and the two ticket types have **different** status sets. We have **never** supported statuses that differ by ticket type — Razvan is asking us to map his workflow-specific statuses like the PC Matic / Tech Services setup, which we have **not** integrated with TOGaDesk. This is a **separate enhancement on both the sync and TOGaDesk** sides; raised with Jake/JT for a decision — **not yet implemented**.
+
 ## Sync Direction 1: Startech to TOGA 2.0 (Webhook)
 
 `worker2/Worker/Startech.php` — `_Worker_Startech::Webhook()`
@@ -196,3 +227,4 @@ not yet resolved:
 - 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.
+- 2026-07-10: Added Ticket Statuses & Workflows section — workflow IDs 56 (Support Request) / 59 (Phone Call Support), statuses queried by workflow_id (not type id); TicketStages.c_startechStageId check (Awaiting User 210 / On Hold 209 disabled, Open 72 absent → invalid); flagged per-ticket-type statuses as a pending enhancement (sync + TOGaDesk).

package/package.json

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