toga-ai 1.0.84 → 1.0.85

package/knowledge/1.0/apps/webhook/INDEX.md

@@ -0,0 +1,5 @@
+# webhook (Webhook) — 1.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [NetSuite → ClickUp Opportunity Sync](features/netsuite-clickup-opportunity-sync.md) | NetSuite Opportunities are pushed into the ClickUp **Opportunities** list (list id `901111987449`, in the Opportunity/RFP Hub space `90113928591`) as tasks name | webhook/_/webhook/netsuite.php, webhook/api.php, api2/Webhook/Netsuite.php, worker2/Worker/Netsuite.php, api2/Controller/Index.php |

package/knowledge/1.0/apps/webhook/features/netsuite-clickup-opportunity-sync.md

@@ -0,0 +1,93 @@
+---
+title: NetSuite → ClickUp Opportunity Sync
+framework: "1.0"
+repo: webhook
+project: Webhook
+client: shared
+type: feature
+status: active
+updated: 2026-06-15
+owners: ["dfranks"]
+files:
+  - webhook/_/webhook/netsuite.php
+  - webhook/api.php
+  - api2/Webhook/Netsuite.php
+  - worker2/Worker/Netsuite.php
+  - api2/Controller/Index.php
+related: []
+---
+
+## Summary
+NetSuite Opportunities are pushed into the ClickUp **Opportunities** list (list id `901111987449`,
+in the Opportunity/RFP Hub space `90113928591`) as tasks named `<oppNumber> — <customerNumber>
+<customer> — <title>` (e.g. `60533 — 560 Endeavor Health — Data Center Facility Consolidation
+Services`). The trigger and the entire task payload are **built on the NetSuite side**; TOGA only
+relays the payload to the ClickUp API verbatim.
+
+## Key files / entry points
+- **Live receiver:** `webhook/_/webhook/netsuite.php` → `Webhook_NetSuite::post()` → `createTask()`,
+  reached at `https://webhook.togahub.com/netsuite` and routed by `webhook/api.php` (the legacy
+  PHP 7.2 / `App_` webhook project). This is the path NetSuite actually hits.
+- **Inactive copies (triplicated, identical relay logic):** `api2/Webhook/Netsuite.php`
+  (`_Webhook_NetSuite::post`) and `worker2/Worker/Netsuite.php` (`_Worker_NetSuite::Webhook`).
+  The api2 webhook route (`Controller/Index.php`, `case 'webhook'`) logs inbound payloads to
+  `Logs.Api`; the worker2 Lambda path logs to `Logs.Webhook`. **Neither shows any `/netsuite`
+  traffic** — confirming the legacy `webhook/` project is the live receiver, not api2/worker2.
+- The ClickUp call uses a token carried in the inbound payload (`$body->token`); in production
+  that token belongs to `dfranks@togatech.com`, so all integration-created tasks show that creator.
+
+## How it works
+1. A NetSuite event/process POSTs a JSON body to `webhook.togahub.com/netsuite`.
+2. `createTask()` resolves the ClickUp user id for `$body->presalesLead` (cached in the client DB
+   `Users.c_clickupUserIdentifier`, else fetched from the ClickUp `/team` members list).
+3. It POSTs a new task to `list/901111987449/task` with `name => $body->name` **verbatim**,
+   `description => $body->description`, and custom fields for sales rep / presales email / presales
+   user id / opportunity number / customer number.
+
+There are (at least) two NetSuite-side triggers feeding this one webhook:
+- **Real-time** UserEventScript on the Opportunity "Presales Lead" field
+  (`custbody_ctc_solution_architect`, employee ref) — fires on empty→set and posts a fully-populated
+  payload. Produces correctly-named tasks. Verified 2026-06-15: touching one opp via REST PATCH
+  (an `xedit`) produced the correct `60533 — 560 Endeavor Health — …` task.
+- **A scheduled/batch process** (runs ~:01 past the hour) — source of the degenerate tasks below.
+
+## Data model
+- ClickUp Opportunities list `901111987449`; custom-item id `1009`.
+- Custom field UUIDs: SALES_REP `f2bf421f-e24c-4e1c-bea4-98a227abe087`, PRESALES_EMAIL
+  `440e2f9c-07bc-482b-9bf1-39b0e673b989`, PRESALES_USER_ID `b755ca44-7d7f-4e4b-9b93-6ee95d0ea8da`,
+  OPPORTUNITY_NUMBER `a5529cdc-8dbb-4165-8bc5-9f5cc691796a`, CUSTOMER_NUMBER `170dc118-b3fa-413b-826b-2753e9405851`.
+- Client DB `Users` table caches `c_clickupUserIdentifier` by email.
+
+## Client variations
+None — single internal Agilant/True integration.
+
+## Gotchas / known issues
+- **`OPP <internalId>` degenerate tasks (root cause).** Occasionally a task is named just
+  `OPP 7147699` with no description/fields. The name is built entirely by NetSuite; TOGA relays it.
+  The opportunities involved are **fully populated in NetSuite** (verified via SuiteQL — `OPP 7147699`
+  is internal id 7147699 = tranid 74197, "7904 Froedtert South", "Seal Shield Opportunity Assessment"),
+  so this is **not** missing data and **not** a TOGA bug — a NetSuite-side process sent a fallback
+  payload (`name = "OPP " + record.id`, descriptive fields empty) without loading `tranid`/`entity`/
+  `title`. The four observed (Jun 2026) all created at ~:01 past the hour by the dfranks token →
+  a NetSuite **scheduled** script, distinct from the working real-time presales-lead trigger
+  (~3% failure: 4 degenerate vs 122 correct from the same token). Fix is NetSuite-side
+  (load the record / saved-search columns before building the name); the offending script lives in
+  the NetSuite File Cabinet, not this repo. Optional TOGA backstop: in `createTask()`, if `name` is
+  empty or matches `^OPP \d+$`, look the opp up by internal id and rebuild the name before POSTing.
+- **No inbound logging.** `Webhook_NetSuite::post()` has a `// Log payload to file` comment but does
+  **nothing** — the raw NetSuite payload is persisted nowhere, which is why this was hard to trace.
+  Adding real request logging here would make recurrences diagnosable immediately.
+- **Opp#/Cust# fields swapped (separate bug, all copies).** `OPPORTUNITY_NUMBER` custom field is set
+  from `$body->customerNumber` and `CUSTOMER_NUMBER` from `$body->opportunityNumber`
+  (e.g. api2 `Netsuite.php` lines 116–122).
+- Handler is triplicated; a fix must be applied to the live `webhook/` copy (and ideally the others
+  to avoid drift).
+
+## Change history
+- 2026-06-15 — Documented integration + root-caused `OPP <internalId>` degenerate tasks to a NetSuite
+  scheduled (~:01 hourly) fallback payload; confirmed live receiver is `webhook/`, not api2/worker2;
+  noted no-op inbound logging and the Opp#/Cust# swap. (dfranks)
+
+## Related docs
+- `test/@dave/touch_opportunity_presales_lead.php` re-fires the real-time presales-lead trigger
+  (blank→restore `custbody_ctc_solution_architect`).

package/knowledge/INDEX.md

@@ -8,6 +8,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **worker** (Worker) — 4 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 7 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 5 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
+- **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
 
 ## 2.0 framework
 

package/knowledge/registry.json

@@ -11,6 +11,6 @@
   { "repo": "togadesk",    "project": "TOGa Desk",   "framework": "1.0", "role": "app",  "dependsOn": [] },
   { "repo": "togaview",    "project": "TOGa View",   "framework": "1.0", "role": "app",  "dependsOn": [] },
   { "repo": "toga2-hub",   "project": "TOGa Hub",    "framework": "2.0", "role": "app",  "dependsOn": ["api2"] },
-  { "repo": "togatech",    "project": "TOGA Technology Website", "framework": "standalone", "role": "app", "dependsOn": [] }
-
+  { "repo": "togatech",    "project": "TOGA Technology Website", "framework": "standalone", "role": "app", "dependsOn": [] },
+  { "repo": "webhook",     "project": "Webhook",     "framework": "1.0", "role": "app",  "dependsOn": ["library"] }
 ]

package/package.json

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