toga-ai 1.0.108 → 1.0.110

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

@@ -40,10 +40,13 @@ second, independently-gated concern in the same handler.
 `test/@dave/NetSuite/api-message-queue/` — upload all four `.js` to one File Cabinet folder):
 - `lib_amq_queue.js` — shared module: record-type/field ids, `transmit()`, `findSendableIds()`.
 - `ue_api_msg_queue_enqueue.js` — User Event on the synced source records (Opportunity, …):
-  writes one queue row per create/edit/delete.
-- `ue_amq_drain.js` — User Event on the **API Message Queue** record: async trigger — kicks the
-  scheduled drainer via `N/task` (no inline HTTP, so it never blocks the source save).
-- `ss_amq_drain.js` — Scheduled Script: catch-up drainer (retries + anything the UE missed).
+  writes one queue row per create/edit/delete, then **kicks the scheduled drainer via `N/task`**
+  (async, non-blocking). The immediate trigger lives here — see gotchas for why.
+- `ss_amq_drain.js` — Scheduled Script: drains rows (the on-demand kick *and* a cron safety-net).
+  Needs **two deployments**: one `Scheduled` (cron) + one `Not Scheduled` (the on-demand slot
+  `task.create` submits into).
+- `ue_amq_drain.js` — **RETIRED.** A UE on the queue record can't fire on enqueuer-created rows
+  (UE-can't-trigger-UE); undeploy it.
 - The custom record itself: **"API Message Queue"**, internal id **1185**.
 
 **worker2 side:**
@@ -59,12 +62,12 @@ second, independently-gated concern in the same handler.
    (`{recordType, internalId, eventType, action}`), `headers`. It maps `record.Type`
    (lowercase) → the camelCase `recordType` worker2 expects (explicit map; e.g.
    `salesorder`→`salesOrder`), and `context.type` → CRUD verb (`create`→POST, `edit`/`xedit`→PUT,
-   `delete`→DELETE).
-2. **Trigger + drain (NetSuite):** the queue record's `ue_amq_drain` UE fires the scheduled
-   `ss_amq_drain` via `N/task` (async); `ss_amq_drain` also runs on its own schedule.
-   `transmit()` claims a row (`Created`→`Sending`) before the HTTP call, POSTs to the row's
-   endpoint, then **deletes on 2xx** / sets `Retry` (+exponential backoff) / `Failed`
-   (terminal — never auto-deleted; Jeff's data-loss rule).
+   `delete`→DELETE). It then **kicks the drainer**:
+   `task.create({taskType:SCHEDULED_SCRIPT, scriptId:'customscript_ss_amq_drain'})` — scriptId only,
+   no deployment id. If no on-demand slot is free the kick is skipped and the cron backs it up.
+2. **Drain (NetSuite):** `ss_amq_drain` runs (from the kick or its cron). `transmit()` claims a row
+   (`Created`→`Sending`) before the HTTP call, POSTs to the row's endpoint, then **deletes on 2xx** /
+   sets `Retry` (+exponential backoff) / `Failed` (terminal — never auto-deleted; Jeff's data-loss rule).
 3. **Ingest (prod):** `webhook.togahub.com/netsuite` → WebhookIngestion **Python Lambda** →
    INSERT `Core.WorkerJobs` + SQS → returns 200 immediately. Fully async; outcome lives in
    `WorkerJobs.isSuccess`/`failureReason`.
@@ -72,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
 
@@ -97,6 +117,16 @@ None — platform-wide Forecast sync.
 
 ## Gotchas / known issues
 
+- **A User Event can't trigger another User Event → the immediate trigger lives in the enqueuer.**
+  The enqueuer (a UE) creating the queue row does NOT fire any UE on the queue record (only the
+  *scheduled* drainer's `submitFields` does). So a drain-UE on the queue record never runs for
+  enqueued rows — the enqueuer kicks the drainer itself via `task.create`. (`ue_amq_drain.js` is
+  retired for exactly this reason. Evidence: its log only ever showed `xedit`/`Sending`, never `create`.)
+- **`task.create(SCHEDULED_SCRIPT)` needs a `Not Scheduled` deployment.** A `Scheduled` deployment is
+  reserved for its recurrence → `NO_DEPLOYMENTS_AVAILABLE`; a `Testing` deployment can't be submitted
+  at all. Give `ss_amq_drain` a dedicated `Not Scheduled` deployment as the on-demand slot (add more
+  for concurrency) and keep a `Scheduled` one for the cron. Submit by **scriptId only** — the
+  deployment id is prefix-doubled (`customdeploycustomdeploy_ss_amq_drain`).
 - **worker2 routes EVERY request to `_Controller_Index::worker()`** — `worker2/_.php` sets
   `DEFAULT_CONTROLLER_METHOD = ['_Controller_Index','worker']`, which short-circuits `_Route`'s
   URI matching. There is no per-URL routing, and `.htaccess` denies direct `.php` files, so you
@@ -115,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
@@ -124,13 +173,21 @@ None — platform-wide Forecast sync.
   string throws `Object of class stdClass could not be converted to string`. Normalize before
   matching.
 - **Drain dedup** uses a `Sending` claim status: `transmit()` flips `Created`→`Sending` before the
-  HTTP call so a concurrent pass skips it; the immediate UE trigger only fires for `Created`/
-  `Pending`, so the drainer's own `Sending`/`Retry`/`Failed` writes don't re-trigger it (a
-  `skip (status not triggerable)` debug line on those is expected). `findSendableIds` must list
-  every sendable status (`Created`,`Pending`,`Retry`,`Sending`) — omitting `Created` silently
-  matches nothing (`candidates:0`).
+  HTTP call so a concurrent drainer pass skips it (`Sending` ∉ sendable), narrowing the double-send
+  window to the load→claim gap. `findSendableIds` must list every sendable status
+  (`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
+  scriptId only (deployment id is prefix-doubled). Fixed an `itemType`-as-object crash in the
+  importer. POST/DELETE coded but only PUT (edit) verified live. (dfranks)
 - 2026-06-16 — Built the queue enqueuer/drainer SuiteScripts, the worker2 `/netsuite` router, and
   the `_Worker_Netsuite_Opportunity` Forecast importer (header + items + status), with ClickUp
   parity. Verified opportunity 5483750 imports end-to-end in dev via ngrok. (dfranks)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.108",
+  "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",