toga-ai 1.0.109 → 1.0.110

package/knowledge/2.0/apps/worker2/features/netsuite-opportunity-sync.md

@@ -75,7 +75,24 @@ second, independently-gated concern in the same handler.
    `_Worker::runTask('Netsuite/Opportunity/<verb>', {internalId})`.
 5. **Handle (worker2):** `_Worker_Netsuite_Opportunity` fetches the record from NetSuite by id
    and upserts it into `Forecast.Opportunities` (+ `OpportunityItems`), and — only when a
-   Presales Lead is set — creates the ClickUp opportunity task.
+   Presales Lead is set — creates the ClickUp opportunity task. **Both `POST` (create) and `PUT`
+   (edit) create the task** (since 2026-06-16); `DELETE` only removes from Forecast.
+
+## ClickUp opportunity task
+
+Created by `maybeCreateClickupTask()` → `createTask()` (ported verbatim from the legacy
+`webhook/` handler), gated on a **Presales Lead** (`custbody_ctc_solution_architect` employee →
+email; empty email = skip). Posts to list `901111987449` with `custom_item_id` = `1009`.
+
+- **Task name** = `{opportunityNumber} — {customer} — {title}`, e.g.
+  `60533 — 560 Endeavor Health — Data Center Facility Consolidation Services` (empty parts dropped).
+- **Custom-field value mapping** (the non-obvious part — these were swapped before 2026-06-16):
+  `Opportunity #` (`a5529cdc-…`) ← `tranId`; `Customer #` (`170dc118-…`) ← `entity->refName`
+  (the customer **name**, deliberately — not the NetSuite customer number). Plus `Sales Rep`,
+  `Presales Lead Email`, and `Presales Lead` (users field, resolved via a cached
+  `Client_True.Users.c_clickupUserIdentifier` lookup, falling back to a `GET /team` scan).
+- The ClickUp token comes from `[clickup] token` in the worker2 config (legacy webhook received
+  it on the payload; the new contract drops it).
 
 ## Data model
 
@@ -128,7 +145,26 @@ None — platform-wide Forecast sync.
 - **No WebhookIngestion Lambda locally.** Dev points the enqueuer at an ngrok tunnel to local
   worker2 via the `DEV_OVERRIDE` block, which also wraps the body in worker2's legacy
   `{action,parameters}` envelope (since there's no Lambda to convert `/netsuite` → an action).
-  Set `DEV_OVERRIDE.enabled=false` for prod.
+- **`debugWrap` is the dev/prod body-shape switch — not just the URL.** `debugWrap=true` (dev)
+  nests the raw `{recordType,internalId,…}` contract inside worker2's legacy `{action,parameters}`
+  envelope (`action='Netsuite/Webhook'`); the local `worker()` legacy path needs this because
+  there's no Lambda. `debugWrap=false` (prod) sends the raw contract — the WebhookIngestion Lambda
+  derives the `Netsuite/Webhook` action from the `/netsuite` URL path itself. Changing only the
+  endpoint to prod while leaving `debugWrap` on double-wraps the body and breaks the handler.
+- **Prod cutover: flip `DEV_OVERRIDE.enabled=false` — do NOT comment out the block.** `getConfig()`
+  reads `DEV_OVERRIDE.enabled/.endpoint/.debugWrap`; deleting the `const` throws `ReferenceError`,
+  which `afterSubmit`'s catch swallows as `AMQ enqueue FAILED` → **no row enqueued, sync silently
+  stops.** Flipping `enabled=false` makes `getConfig()` fall through to `DEFAULTS.endpoint`
+  (`https://webhook.togahub.com/netsuite`) with `debugWrap` off. Also flip the enqueuer deployment
+  `Testing → Released` (Testing fires only for the deploying user). Full checklist in
+  `DEPLOY_RUNBOOK.md` §6.
+- **No ClickUp dedup (deferred).** `maybeCreateClickupTask()` only gates on the Presales Lead — it
+  does **not** check whether a task already exists. Since both POST and PUT now create, **every edit
+  of an opportunity with a Presales Lead creates a NEW ClickUp task** (and the NetSuite-side
+  enqueuer fires on every save). Before this hits production traffic, add dedup — recommended:
+  store the created ClickUp task id on the `Forecast.Opportunities` row and skip when present.
+  Until 2026-06-16 PUT skipped ClickUp entirely, which masked this (an edit produced no duplicate
+  only because the edit path didn't create at all).
 - **NetSuite doubled-prefix ids.** The queue record and its fields were created with the full
   custom prefix typed into the ID box, so the real ids are doubled:
   type `customrecordcustomrecord_api_msg_queue`, fields `custrecordcustrecord_amq_*`. The
@@ -142,6 +178,11 @@ None — platform-wide Forecast sync.
   (`Created`,`Pending`,`Retry`,`Sending`) — omitting `Created` silently matches nothing (`candidates:0`).
 
 ## Change history
+- 2026-06-16 — ClickUp parity hardening (TRUE-79182): verified the `Opportunity #`/`Customer #`
+  custom fields exist on list 901111987449 and **fixed their swapped values**; `PUT` now also
+  creates the ClickUp task (was POST-only); task name reformatted to
+  `{opp#} — {customer} — {title}`; `createTask()` made private + generic `Exception` throws
+  narrowed to `RuntimeException`. Dedup still deferred (see gotcha). (dfranks)
 - 2026-06-16 — Trigger correction: the immediate trigger moved INTO the enqueuer (`task.create`
   the drainer) after discovering a UE can't trigger a UE — `ue_amq_drain` retired. `task.create`
   needs a `Not Scheduled` deployment of `ss_amq_drain` (else `NO_DEPLOYMENTS_AVAILABLE`); submit by

package/package.json

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