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.
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
_idto 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
_idreturns200 - 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
connectionIdandcollection - 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/storego 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 buildnpm audit --omit=dev
Expected:
- all required tests pass
- build passes
- audit output reviewed for relevant issues