Goal: Arda API Proxy — Typed TypeScript Client

Objective

Extract and extend the shared HTTP client layer currently embedded in api-mcp/packages/shared into a standalone, published TypeScript package (@arda-cards/api-proxy) in the api-proxy repository. The package provides a type-safe client for every Arda REST API endpoint, usable from any TypeScript project — not just MCP servers.

Current State

The api-mcp repository contains a shared package (@arda-cards/arda-api-client) that provides:

• ArdaApiClient — base HTTP class wrapping fetch with authentication, bitemporal query parameters, and error handling.
• Common types — EntityRecord, PageResult, Query, Filter, TimeCoordinates, etc.
• Auth utilities — reads ARDA_API_HOST and ARDA_API_KEY from the environment; sets X-Author header.
• Error handling — ArdaApiError class with status, message, and details.

Each MCP server package (e.g., tenant-mcp) extends ArdaApiClient with a module-specific subclass that exposes typed CRUD + query + history methods, plus module-specific types generated from the OpenAPI specs.

The limitation is that this client is only available as an internal dependency of the api-mcp monorepo. Conventional TypeScript code (scripts, backends, test harnesses, CLI tools) cannot consume it without pulling in the full MCP workspace.

Target State

A single published npm package — @arda-cards/api-proxy — that provides:

1. Core client — the base HTTP client, auth, error handling, and common types extracted from api-mcp/packages/shared.
2. Per-module proxy objects — typed proxy classes for every API endpoint across all in-scope modules (tenant, user-account, agent-for, invitation, business-affiliate, item, kanban, order). Each proxy is independently instantiable and directly callable from any TypeScript code — no MCP tool wrapper required.
3. Per-module types — request/response types for each module, faithful to the OpenAPI specs.

Package Identity

Property	Value
Package name	@arda-cards/api-proxy
Repository	Arda-cards/api-proxy
Registry	GitHub Packages (npm.pkg.github.com)
Runtime	Node.js 18.18+ (native fetch)

Constraints

1. No MCP dependency — the package must not import or depend on @modelcontextprotocol/sdk or any MCP-specific code.
2. No breaking changes to api-mcp — changes to api-mcp are out of scope. The extraction is a copy-and-extend, not a move. api-mcp may later be refactored to depend on api-proxy, but that is a separate project.
3. Type fidelity — types must match the Arda API OpenAPI specs. Reuse the type definitions already created in api-mcp where they exist.
   • Where the OpenApi type is ambiguous due to deficiencies in the tool, inspect the code in operations, common-module or accounts (alias accounts-component) for details using the Kotlin types directly.
4. Independent Proxy Objects Each API Endpoint should have its own separately instatiatable proxy object configured with the host and the api key (see below). Shared utilities should be in a separate directory and imported from each endpoint.
5. Caller-supplied configuration — each proxy is constructed with explicit host and apiKey parameters. The caller is responsible for sourcing these values (e.g., from environment variables like ARDA_API_HOST and ARDA_API_KEY, a secrets manager, or any other mechanism). The package itself does not read from the environment.
6. Published to GitHub Packages — CI publishes on merge to main, matching the pattern used by api-mcp.

API Endpoints in Scope

Module	API Base Path	Category	Status
tenant	/v1/tenant	System
user-account	/v1/user-account	System
agent-for	/v1/agent-for	System
invitation	/v1/invitation	System
business-affiliate	/v1/business-affiliate	Reference Data
item	/v1/item	Reference Data
kanban	/v1/kanban	Resources
order	/v1/order	Procurement
pdf-render	/v1/pdf-render	Print	Out of scope

Repositories Affected

Repository	Changes
api-proxy	New package: core client, per-module functions/types, tests, CI/CD
documentation	Project plan and goal documents
api-mcp	No changes (out of scope)

Source Material

• api-mcp/packages/shared/src/ — base client, types, auth, errors
• api-mcp/packages/tenant-mcp/src/ — reference implementation of a module-specific client and types
• api-mcp/development-docs/goal.md — original MCP project goal
• Arda API OpenAPI specs at {host}/v1/{module}/docs/openApi.json