Requirements: Arda API Proxy

REQ-CORE: Shared Infrastructure

REQ-CORE-001: HttpClient Construction

The HttpClient class accepts a ProxyConfig (host, apiKey) and a basePath string. It uses these to build fully qualified URLs for all requests.

REQ-CORE-002: Request Headers

Every HTTP request sent by HttpClient includes:

• X-Author header set to the configured apiKey
• Content-Type: application/json

REQ-CORE-003: URL Building with Time Coordinates

HttpClient.buildUrl appends optional effectiveasof and recordedasof query parameters when TimeCoordinateParams are provided.

REQ-CORE-004: Error Handling

When a response has a non-OK HTTP status, HttpClient throws an ArdaApiError containing the status code, responseMessage, and details parsed from the response body.

REQ-CORE-005: No Runtime Dependencies

The package has zero runtime (non-dev) dependencies. It relies only on the Node.js 18.18+ native fetch API.

REQ-CORE-006: No MCP Dependency

The package must not import or depend on @modelcontextprotocol/sdk or any MCP-specific code.

REQ-CORE-007: Common Types

The package exports the following shared types, faithful to the Arda API contracts:

• TimeCoordinates — bitemporal effective/recorded pair
• EntityRecord<TPayload, TMetadata> — standard response envelope
• PageResult<TPayload, TMetadata> — paginated response wrapper
• Query, Filter, Sort, SortEntry, SortDirection, Pagination
• HistoryRequestBody
• ErrorResponse
• TimeCoordinateParams
• ProxyConfig

---

REQ-PROXY: Proxy Object Design

REQ-PROXY-001: Independent Instantiation

Each proxy class is independently instantiable with a ProxyConfig object. The caller is responsible for sourcing host and apiKey values.

REQ-PROXY-002: Composition over Inheritance

Proxies hold a reference to an HttpClient instance (composition). They do not extend a base class.

REQ-PROXY-003: Standard CRUD Operations

Every proxy wrapping a standard Arda entity endpoint exposes:

Method	HTTP	Path
create(input, params?)	POST /{entity}	Create entity
get(entityId, params?)	GET /{entity}/{entityId}	Get by entity ID
getByRecordId(recordId)	GET /{entity}/rid/{recordId}	Get by record ID
update(entityId, input, params?)	PUT /{entity}/{entityId}	Update entity
delete(entityId, params?)	DELETE /{entity}/{entityId}	Delete entity
query(query)	POST /{entity}/query	Query with filter/sort/page
queryHistory(entityId, body)	POST /{entity}/{entityId}/history	Audit history

Where params is optional TimeCoordinateParams.

---

REQ-SYS: System Domain

REQ-SYS-001: TenantProxy

Provides standard CRUD operations for /v1/tenant.

REQ-SYS-002: UserAccountProxy

Provides standard CRUD operations for /v1/user-account.

REQ-SYS-003: AgentForProxy

Provides standard CRUD operations for /v1/agent-for.

REQ-SYS-004: InvitationProxy

Provides standard CRUD operations for /v1/invitation.

---

REQ-REF: Reference Data Domain

REQ-REF-001: BusinessAffiliateProxy — Standard Operations

Provides standard CRUD operations for /v1/business-affiliate.

REQ-REF-002: BusinessAffiliateProxy — Detail and Role Operations

Beyond standard CRUD:

Method	HTTP	Path
getWithDetails(entityId, params?)	GET	/business-affiliate/with-details/{entityId}
getRoles(entityId)	GET	/business-affiliate/{entityId}/roles
createRole(entityId, input)	POST	/business-affiliate/{entityId}/roles
updateRole(entityId, roleId, input)	PUT	/business-affiliate/{entityId}/roles/{roleId}

REQ-REF-003: ItemProxy — Standard Operations

Provides standard CRUD operations for /v1/item.

REQ-REF-004: ItemProxy — Draft, Supply, and Utility Operations

Beyond standard CRUD:

Method	HTTP	Path
getDraft(entityId)	GET	/item/{entityId}/draft
updateDraft(entityId, input)	PUT	/item/{entityId}/draft
getSupplies(entityId)	GET	/item/{entityId}/supply
createSupply(entityId, input)	POST	/item/{entityId}/supply
updateSupply(entityId, supplyId, input)	PUT	/item/{entityId}/supply/{supplyId}
deleteSupply(entityId, supplyId)	DELETE	/item/{entityId}/supply/{supplyId}
lookupSuppliers(query)	GET	/lookup-suppliers?q={query}
lookupUnits(query)	GET	/lookup-units?q={query}
printLabels(entityIds)	POST	/item/print-label
printBreadcrumbs(entityIds)	POST	/item/print-breadcrumb
createUploadUrl()	POST	/upload-job/upload-url
getUploadJobStatus(jobId)	GET	/upload-job/{jobId}

---

REQ-RES: Resources Domain

REQ-RES-001: KanbanProxy — Standard Operations

Provides standard CRUD operations for /v1/kanban.

REQ-RES-002: KanbanProxy — Detail, Summary, and Event Operations

Beyond standard CRUD:

Method	HTTP	Path
getDetails(entityId, params?)	GET	/kanban-card/details/{entityId}
queryDetails(query)	POST	/kanban-card/details
queryDetailsByStatus(status, query)	POST	/kanban-card/details/{status}
getCardsForItem(itemEntityId)	GET	/kanban-card/for-item/{itemEntityId}
getSummary()	GET	/kanban-card/summary
getSummaryRequested()	GET	/kanban-card/summary/requested
getSummaryInProcess()	GET	/kanban-card/summary/in-process
updateNotes(entityId, input)	PUT	/kanban-card/{entityId}/notes
postEvent(entityId, event, body?)	POST	/kanban-card/{entityId}/event/{event}
printCards(entityIds)	POST	/kanban-card/print-card

REQ-RES-003: KanbanProxy — Event Type Safety

The postEvent method accepts an event parameter constrained to the union type: "request" | "accept" | "start-processing" | "complete-processing" | "fulfill" | "receive" | "use" | "deplete" | "withdraw".

---

REQ-PROC: Procurement Domain

REQ-PROC-001: OrderProxy — Standard Operations

Provides standard CRUD operations for /v1/order.

REQ-PROC-002: OrderProxy — Full View and Creation Operations

Beyond standard CRUD:

Method	HTTP	Path
getFull(entityId, params?)	GET	/order/full/{entityId}
createFromItems(input)	POST	/order/from-items
addItemsToOrder(entityId, input)	POST	/order/from-items/{entityId}
createFromKanbanCards(input)	POST	/order/from-kanban-cards
addKanbanCardsToOrder(entityId, input)	POST	/order/from-kanban-cards/{entityId}

REQ-PROC-003: OrderProxy — Line Item Operations

Method	HTTP	Path
addLine(entityId, input)	POST	/order/{entityId}/lines
updateLine(entityId, lineId, input)	PUT	/order/{entityId}/lines/{lineId}
deleteLine(entityId, lineId)	DELETE	/order/{entityId}/lines/{lineId}
moveLine(entityId, lineId, input)	PUT	/order/{entityId}/lines/move-line/{lineId}

REQ-PROC-004: OrderProxy — Lifecycle and Annotation Operations

Method	HTTP	Path
submit(entityId)	POST	/order/{entityId}/submit
accept(entityId)	POST	/order/{entityId}/accepted
receive(entityId, input)	POST	/order/{entityId}/receive
archive(entityId)	POST	/order/{entityId}/archive
annotate(entityId, input)	PUT	/order/{entityId}/annotate
annotateLine(entityId, lineId, input)	PUT	/order/{entityId}/annotate-line/{lineId}

---

REQ-PKG: Package and Distribution

REQ-PKG-001: Package Exports

The package exposes both barrel and deep imports via package.json exports map:

Import Path	Content
@arda-cards/api-proxy	All proxies and shared types
@arda-cards/api-proxy/shared	Shared types and utilities only
@arda-cards/api-proxy/system	System domain proxies
@arda-cards/api-proxy/reference	Reference Data domain proxies
@arda-cards/api-proxy/resources	Resources domain proxies
@arda-cards/api-proxy/procurement	Procurement domain proxies

REQ-PKG-002: Type Fidelity

All request/response types match the Arda API OpenAPI specifications. Where OpenAPI types are ambiguous, Kotlin source in operations or accounts-component is authoritative.

REQ-PKG-003: TypeScript Strict Mode

The package compiles under strict: true with verbatimModuleSyntax enabled.

REQ-PKG-004: Publishing

The package is published to GitHub Packages (npm.pkg.github.com) as @arda-cards/api-proxy on merge to main.

REQ-PKG-005: CI Checks

Pull requests and pushes to main run: format check, typecheck, lint, and tests with coverage enforcement (80% lines, 80% branches).