droboticflow/docs/plans/2026-04-14-business-db-write-api-implementation.md
eust-w 43326d6a5e feat(platform): land workflow, data tooling, and docs updates
Include the accumulated workflow scheduling, run history, subtree rerun, operator UI, deployment, data asset, object storage, database browser, and documentation changes currently in the worktree.
2026-04-24 12:29:46 +08:00

5.3 KiB

Business DB External Write API Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add a dedicated authenticated REST API for third-party writes into preconfigured business Mongo connections, with collection-scoped API keys and support for create, patch-by-id, and business-key upsert.

Architecture: Extend the singleton settings document to persist hashed external write tokens and their scopes, add dedicated internal token-management endpoints plus dedicated external write endpoints under /api/external/business-db, and extend the Mongo/memory database store adapters with patch and upsert helpers. Keep the external API separate from the internal database browser routes so permissions stay narrow.

Tech Stack: Go, chi, MongoDB Go driver, Go test, existing in-memory store test harness


Task 1: Save token configuration in domain and settings

Files:

  • Modify: internal/domain/types.go
  • Modify: internal/store/helpers.go

Step 1: Write the failing test

Add an API test that creates an external write token and verifies the returned payload includes a one-time plaintext API key while the stored settings only keep a hash and preview.

Step 2: Run test to verify it fails

Run: go test ./internal/api -run TestExternalBusinessWriteTokenCRUD -v Expected: FAIL because the token types and endpoints do not exist yet.

Step 3: Write minimal implementation

Add token and scope structs to SettingsRecord, plus helper defaults and sanitization-ready fields needed by the API.

Step 4: Run test to verify it passes

Run: go test ./internal/api -run TestExternalBusinessWriteTokenCRUD -v Expected: still failing later in the request path, but no longer on missing types.

Task 2: Extend the store with patch and upsert support

Files:

  • Modify: internal/store/store.go
  • Modify: internal/store/mongo.go
  • Modify: internal/store/memory.go

Step 1: Write the failing test

Add store or API tests that expect:

  • patch by _id to update selected fields without changing _id
  • business-key upsert to create when no match exists
  • business-key upsert to update when a match exists

Step 2: Run test to verify it fails

Run: go test ./internal/api -run 'TestExternalBusinessWrite(DocumentPatch|Upsert)' -v Expected: FAIL because the store interface does not expose patch or upsert methods.

Step 3: Write minimal implementation

Add PatchDatabaseDocument and UpsertDatabaseDocument to the store interface and implement them in Mongo and memory stores.

Step 4: Run test to verify it passes

Run: go test ./internal/api -run 'TestExternalBusinessWrite(DocumentPatch|Upsert)' -v Expected: still failing later in the API layer, but store calls now resolve.

Task 3: Add internal token management endpoints

Files:

  • Modify: internal/api/server.go
  • Create or modify: internal/api/database_external_write.go
  • Test: internal/api/server_test.go

Step 1: Write the failing test

Add tests for:

  • create token
  • list tokens
  • rotate token
  • reject unknown connectionId

Step 2: Run test to verify it fails

Run: go test ./internal/api -run TestExternalBusinessWriteTokenCRUD -v Expected: FAIL with 404 or validation gaps.

Step 3: Write minimal implementation

Register token management routes and implement create/list/update/rotate/delete handlers against SettingsRecord.

Step 4: Run test to verify it passes

Run: go test ./internal/api -run TestExternalBusinessWriteTokenCRUD -v Expected: PASS.

Task 4: Add authenticated external write endpoints

Files:

  • Modify: internal/api/server.go
  • Create or modify: internal/api/database_external_write.go
  • Test: internal/api/server_test.go

Step 1: Write the failing test

Add tests for:

  • missing API key returns 401
  • invalid API key returns 401
  • disabled token returns 401
  • unauthorized collection returns 403
  • create document returns 201
  • patch by _id returns 200
  • business-key upsert returns created and updated outcomes

Step 2: Run test to verify it fails

Run: go test ./internal/api -run 'TestExternalBusinessWrite(Auth|Create|DocumentPatch|Upsert)' -v Expected: FAIL because the middleware and routes do not exist.

Step 3: Write minimal implementation

Add:

  • token hash generation and constant-time validation
  • scope checks for connectionId and collection
  • request validation for plain JSON objects only
  • three external write handlers

Step 4: Run test to verify it passes

Run: go test ./internal/api -run 'TestExternalBusinessWrite(Auth|Create|DocumentPatch|Upsert)' -v Expected: PASS.

Task 5: Update docs and verify end-to-end

Files:

  • Modify: docs/api.md

Step 1: Write the failing test

No code test needed; use verification commands.

Step 2: Run verification

Run:

  • go test ./internal/api ./internal/store
  • go test ./...
  • npm run build

Expected:

  • backend tests pass
  • repo build stays green

Step 3: Write minimal implementation

Document token-management and external write API payloads, headers, and sample requests.

Step 4: Re-run verification

Run:

  • go test ./...
  • npm run build
  • npm audit --omit=dev

Expected:

  • all required tests pass
  • build passes
  • audit output reviewed for relevant issues