PSA/docs/plans/2026-06-12-integration-workflow-modules/SCRATCHPAD.md

# Scratchpad — Integration Workflow Modules

Working notes for the implementation. Design authority:
`../2026-06-12-integration-workflow-modules-design.md`. PRD + feature/test
tracking live alongside this file.

## Verify-during-implementation list (from design)

- NinjaOne scripting-options discovery endpoint exact path (expected
  `GET /v2/device/{id}/scripting/options`).
- Tactical endpoint paths: `/scripts/`, `/agents/{agent_id}/runscript/`,
  `/agents/{agent_id}/cmd/`, `/agents/{agent_id}/reboot/` (and response
  shapes — run_script output retrieval may be task/poll based).
- Huntress incident-resolve write endpoint + payload (changelog announced;
  confirm at api.huntress.io/docs).
- Level `automations.list` response includes webhook tokens, or whether the
  separate "list automation webhooks" endpoint is needed for discovery.

## Implementation order (suggested)

1. Framework (F001–F005) + parity tests — everything else stacks on it.
2. Tactical (marquee actions; mock server exists for smoke).
3. Level, Huntress (thin clients, mostly reads + one write each).
4. Teams (createConversation is the heavy item — do last among modules).
5. scheduling.create_entry + icons/polish.

## Findings

### 2026-06-12 — implementation complete (F001–F032, automated T001–T013)

**Build-boundary constraint shaped all module clients.** The workflows
package's tsup config externalizes every `@alga-psa/*` import, and both
`@alga-psa/integrations/runtime` and `@alga-psa/ee-microsoft-teams` map
their exports to TS *source* — so the workflows dist (loaded by the
tsc-built Temporal worker) cannot import them at runtime. The Teams package
additionally depends on `@alga-psa/workflows` (circular). Consequence:
Tactical, Level, Huntress, and Teams all got self-contained fetch clients
in `ee/packages/workflows/src/runtime/actions/*RuntimeSupport.ts`,
following the pre-existing NinjaOne precedent (which exists for exactly
this reason). PRD 6.2's "reuse TacticalRmmClient" and 6.5's
"createConversation in ee/packages/microsoft-teams" were adjusted
accordingly (noted in features.json F008/F009/F025/F027).

**Vendor verifications completed:**
- NinjaOne: `POST /v2/device/{id}/script/run` confirmed; discovery is the
  `requestScriptingOptions` operation ("Device scripting options get") —
  implemented as `GET /v2/device/{id}/scripting/options`; confirm payload
  shape during T015-style live smoke.
- Tactical: `POST /agents/{id}/runscript/` payload confirmed against
  docs.tacticalrmm.com (output: 'wait' returns script output); cmd/reboot
  paths follow the same agent-route convention — confirm on the mock
  server during smoke.
- Level: all four automation endpooints confirmed against
  levelapi.readme.io (`GET /v2/automations`, `GET /v2/automations/webhooks`
  with full URL + requires_authorization_header, `POST
  /v2/automations/webhooks/{token}` body `{device_ids}`, `GET
  /v2/automation-runs/{id}?include_steps`). The trigger response body is
  undocumented — surfaced as `vendor_response` passthrough.
- Huntress: full OpenAPI fetched from `api.huntress.io/v1/swagger_doc.json`.
  `POST /v1/incident_reports/{id}/resolution` takes NO body; fails 403 when
  the (default, read-only) account API key is used — needs a user-based
  key with resolve permission; 409/422 unless all remediations approved and
  status is 'sent'. All three mapped to actionable errors.

**Teams notify_user** uses the five manifest-declared activity types via a
`category` input (default escalation) rather than free-form
`systemDefault` (would need a manifest change). Deep link is the generic
entity link to the personal tab. `post_to_channel` resolves the regional
Bot Framework serviceUrl from any stored `teams_conversation_references`
row (or explicit `service_url` input) — a tenant with the app installed
but zero stored references gets an actionable error.

**scheduling.assign_user overlap:** it already creates entries but demands
a work-item link and exactly one user; `scheduling.create_entry` is the
superset (optional link → `work_item_type: 'ad_hoc'`, multi-assignee),
reusing the family's eligibility/conflict/audit helpers.

**Pre-existing test failures (verified identical on origin/main, not
ours):** `Schedules.test.tsx`, `payloadSchemaConventions.test.ts`,
`payloadSchemaExamples.test.ts`, `workflowEventFormModeBuilder.test.ts`
(29 tests, env-related), plus `actionCallSchedulingSaveAsRuntime.test.ts`
in shared (module resolution) and the ee/server designer contract tests
failing to *load* here ("No such built-in module: node:" — they should run
in CI; our icon contract test follows the same pattern).

**Test tallies:** workflows package 128 passed / 29 pre-existing failures;
shared scheduling db suite 12/12 against local-test postgres (DB_HOST=
localhost DB_PORT=5472 + admin password from alga-psa secrets); package
tsc clean throughout.

**Remaining: manual smokes T014–T018** need a dev stack running this
branch (palette gating on connect/disconnect, Tactical mock run_script
round-trip, Teams live tenant, dispatch-board + calendar sync check,
icon render).

### 2026-06-12 — editor disconnected-state (F033–F035) + dep tidy-up

The "circular dependency" first cited for Teams was actually a **stale,
unused** `@alga-psa/workflows` entry in ee-microsoft-teams's package.json
(left behind when payload builders moved to `@alga-psa/workflow-streams`);
removed. The real reuse blocker (source-mapped exports vs dist-external
workflows runtime) stands and is documented above.

Disconnected-integration editor behavior, decided with Robert:
availability gates ADDING, not VIEWING. First-party app catalog records
are now annotated `available: boolean` instead of removed; the palette
filters client-side; existing steps get a Disconnected badge on the step
card and an amber banner in the grouped config section (which previously
disappeared silently because the catalog record was filtered out). Input
mapping always kept working (it resolves from the unfiltered registry
list). Publish-time and disconnect-time warnings considered and
deferred (PRD §11).

Local test-env caveats: ee/server component tests cannot run here
(pre-existing `React.act is not a function` in @testing-library setup,
and contract tests fail to load on `node:` builtins) — T019 and the icon
contract test follow existing patterns and run in CI. ee/server tsc needs
`NODE_OPTIONS=--max-old-space-size=8192`; its remaining errors are
pre-existing (chat registry / agent-tooling / msp-composition, absent
generated packages on a fresh copy) — none in workflow-designer.