Run 1: API Proxy Publish

Extends @arda-cards/api-proxy with BFF-compatible request context headers, adds the missing processUploadJob endpoint, updates the CHANGELOG, and publishes the package to GitHub Packages. Corresponds to specification.md.

Author: Claude Code for jmpicnic | Date: 2026-04-07 | Status: Planning

User Request

Implement RequestContext + HttpClient header refactoring so that the proxy library can forward user identity headers required by BFF routes (Authorization: Bearer, X-Author, X-Tenant-Id, X-oidc-subject, X-Request-ID). Add processUploadJob() to ItemProxy. Verify all checks, update CHANGELOG, and publish @arda-cards/api-proxy to GitHub Packages.

Entry Criteria

#	Criterion	Verification Command	Expected Output
1	api-proxy worktree on correct branch	git -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/api-proxy branch --show-current	jmpicnic/image-upload-frontend
2	No uncommitted changes in api-proxy worktree	git -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/api-proxy status --porcelain	Empty
3	Existing tests pass	npm --prefix /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/api-proxy run test	Exit 0, 225+ tests passing
4	Prior implemented code present (createImageUploadUrl, deleteDraft, 8 lookup methods)	git -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/api-proxy log --oneline -5	Recent commits from preparation phase visible

Decomposition

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
1.0	Implement RequestContext type, ProxyConfig.generateRequestId, RequestOptions, and refactor HttpClient.request()	typescript-engineer	—	Pending	RequestContext, RequestOptions exported from src/shared/index.ts; HttpClient sends Authorization: Bearer always; sends X-Author/X-Tenant-Id/X-oidc-subject when context provided; falls back to apiKey for X-Author when no context; sends X-Request-ID on every request; all 8 proxy classes accept options?: RequestOptions as last parameter
1.1	Add processUploadJob() method to ItemProxy	typescript-engineer	1.0	Pending	POST /upload-job/{jobId} implemented; unit test verifies method, URL, and UploadJobStatus return type
1.2	Verify all checks	typescript-engineer	1.1	Pending	npm run typecheck, npm run lint, npm run test, npm run build all exit 0
1.3	Update CHANGELOG	typescript-engineer	1.2	Pending	Added + Changed sections per Keep a Changelog format; covers RequestContext, RequestOptions, generateRequestId, processUploadJob, Authorization: Bearer header change, Node >=20.0.0 requirement
1.4	Commit and push	typescript-engineer	1.3	Pending	All changes committed; branch pushed to remote
1.5	Create PR and publish	typescript-engineer	1.4	Pending	PR created to main; /pr-steward run; PR merged; @arda-cards/api-proxy new version confirmed installable from GitHub Packages
1.6	Documentation commit	typescript-engineer	1.5	Pending	Session log / byproducts updated in documentation worktree; make pr-checks passes; documentation changes committed referencing Phase 3.1

Worktree Strategy

Single worktree — all tasks execute sequentially in the api-proxy worktree.

Working directory: /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/api-proxy Branch: jmpicnic/image-upload-frontend

Parallelization

Sequential only — each task builds directly on the previous task’s output.

1.0 (RequestContext + HttpClient) → 1.1 (processUploadJob) → 1.2 (checks) → 1.3 (CHANGELOG) → 1.4 (commit) → 1.5 (PR + publish) → 1.6 (docs)

Idle Agent Strategy

Single agent; no idle time.

Personas Required

Persona	Agent Name	Tasks Assigned	Working Directory	Spawn Order
typescript-engineer	ts-api-proxy	1.0 through 1.6	/Users/jmp/code/arda/projects/image-upload-frontend-worktrees/api-proxy	First

Artifact Specifications

Artifact	Path (relative to worktree)	Format	Description
RequestContext type	src/shared/types.ts	TypeScript	Per-request user identity: author, tenantId, userId
RequestOptions type	src/shared/http-client.ts	TypeScript	Optional per-request options: context?: RequestContext, contentType?: string
ProxyConfig update	src/shared/http-client.ts	TypeScript	Adds generateRequestId?: () => string
Updated HttpClient.request()	src/shared/http-client.ts	TypeScript	Sends Authorization: Bearer, X-Request-ID always; conditional identity headers
Updated proxy methods (8 classes)	src/*/proxy.ts	TypeScript	Each gains options?: RequestOptions as last parameter
processUploadJob()	src/reference/item/proxy.ts	TypeScript	POST /upload-job/{jobId} returning UploadJobStatus
HttpClient unit tests	tests/shared/http-client.test.ts	TypeScript/Vitest	Header behavior verification (6+ new test cases)
ItemProxy unit test	tests/reference/item/proxy.test.ts	TypeScript/Vitest	processUploadJob test case
CHANGELOG	CHANGELOG.md	Markdown	Keep a Changelog format; Added + Changed sections

Internal Dependency Graph

1.0 (RequestContext + HttpClient refactor)
  └──→ 1.1 (processUploadJob)
         └──→ 1.2 (verify checks)
                └──→ 1.3 (CHANGELOG)
                       └──→ 1.4 (commit + push)
                              └──→ 1.5 (PR + publish)
                                     └──→ 1.6 (documentation commit)

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	RequestContext and RequestOptions exported from shared barrel	npm --prefix <worktree> run typecheck	Exit 0, no type errors
2	HttpClient sends Authorization: Bearer on every request	npm --prefix <worktree> run test -- --reporter=verbose 2>&1 | grep "Authorization: Bearer"	Test case PASS
3	HttpClient sends identity headers when context provided	npm --prefix <worktree> run test -- --reporter=verbose 2>&1 | grep "X-Author"	Test case PASS
4	HttpClient sends X-Request-ID on every request	npm --prefix <worktree> run test -- --reporter=verbose 2>&1 | grep "X-Request-ID"	Test case PASS
5	All proxy methods accept options?: RequestOptions	npm --prefix <worktree> run typecheck	Exit 0 (would fail if parameter missing)
6	processUploadJob() present and tested	npm --prefix <worktree> run test -- --reporter=verbose 2>&1 | grep "processUploadJob"	Test case PASS
7	package.json engines.node updated	node -e "const p=require('./package.json'); console.log(p.engines.node)"	>=20.0.0
8	All checks pass	npm --prefix <worktree> run typecheck && npm --prefix <worktree> run lint && npm --prefix <worktree> run test && npm --prefix <worktree> run build	All exit 0
9	CHANGELOG updated with correct entries	head -50 <worktree>/CHANGELOG.md	Added + Changed entries present for this version
10	Package published to GitHub Packages	npm view @arda-cards/api-proxy versions --registry=https://npm.pkg.github.com	New version present
11	PR merged to main	GitHub PR status	Merged
12	Documentation worktree checks pass	make -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation pr-checks	Exit 0

Where <worktree> = /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/api-proxy.

Agent Prompt Templates

typescript-engineer — ts-api-proxy

Working directory: /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/api-proxy Use absolute paths for all tool calls.

Implement Phase 3.1 of the item image upload frontend project: specification.md.

Load skills: general-conventions, release-lifecycle.

The worktree already contains all preparation-phase code (createImageUploadUrl, deleteDraft, 8 lookup methods, bulkCreate, bulkUpdate, etc.) with 225 passing tests. Your tasks are T-0 through T-6 in the specification.

T-0 is the most complex task — read the full specification section before starting. Key points:

• RequestContext goes in src/shared/types.ts
• RequestOptions stays internal to http-client.ts but is exported
• All 8 proxy classes need options?: RequestOptions as last parameter
• The fallback behavior (no context → apiKey as X-Author) is required for backward compatibility
• crypto.randomUUID() for X-Request-ID (Node 20+ only — update engines.node)

Key decisions already resolved: FD-08 (Node 20, crypto.randomUUID()), FD-09 (export RequestOptions from shared only).

For T-5 (PR), use mcp__github-mcp-server__create_pull_request and then run /pr-steward <pr-url>.

For T-6 (documentation), commit the session log or any byproducts to the documentation worktree at: /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation and run make pr-checks there before committing.

Handoff

Artifacts Consumed (from previous runs)

This is the first run. The entry criteria describe the preparation-phase code that already exists in the worktree (implemented prior to this project plan).

Artifacts Produced (for subsequent runs)

Artifact	Consumer Run	Path
@arda-cards/api-proxy published at new version	Run 5 (BFF routes)	GitHub Packages
RequestContext type	Run 5 (BFF wires user identity headers)	src/shared/types.ts
RequestOptions type	Run 5 (BFF calls proxy methods with context)	src/shared/http-client.ts
processUploadJob() method	Run 5 (BFF triggers CSV upload job)	src/reference/item/proxy.ts

STOP before launching Run 2 or Run 5: Confirm the published package is installable:

npm view @arda-cards/api-proxy versions --registry=https://npm.pkg.github.com

Open Questions and Decisions

#	Question	Options	Recommendation	Decision
1	Node version for crypto.randomUUID()	A: Node 20+, B: manual UUID for Node 18 compat	A	Decided (FD-08): crypto.randomUUID(). Update engines.node to >=20.0.0.
2	RequestOptions re-export from domain barrels?	A: shared barrel only, B: all domain barrels	A	Decided (FD-09): Shared barrel only.

Acceptance Criteria

• RequestContext, RequestOptions exported from src/shared/index.ts
• HttpClient.request() sends Authorization: Bearer and X-Request-ID on every request
• HttpClient.request() sends X-Author, X-Tenant-Id, X-oidc-subject when context provided
• All 8 proxy classes accept options?: RequestOptions as last parameter
• processUploadJob() added to ItemProxy with unit test
• package.json engines.node = >=20.0.0
• All checks pass: typecheck, lint, test, build
• CHANGELOG updated with Added + Changed sections
• @arda-cards/api-proxy published to GitHub Packages at new version
• PR merged to main
• Documentation worktree: make pr-checks passes, changes committed

Risks and Blockers

Risk / Blocker	Impact	Mitigation
Proxy method signature change breaks existing API tests	Medium — regression in api-test repo	The options parameter is optional; existing callers compile unchanged
GitHub Packages publish CI step fails	High — blocks Run 5	Monitor CI after merge; re-trigger publish workflow if needed
crypto.randomUUID() not available in test environment	Low — test setup	Node 20+ is the stated requirement; verify test runner uses Node 20

Project Completion Artifacts

Byproducts (byproducts/)

File	Description
changelog.md	Summary of changes made in Run 1
learnings.md	Observations about api-proxy architecture, header conventions
suggestions.md	Improvement suggestions, tech debt, documentation gaps

Task Tracking Protocol

The team’s TaskList is the single source of truth for task status. Follow the protocol at every phase boundary per the team-lead agent definition.

Progress Log

Date	Event	Notes
2026-04-07	Plan created

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved