Specification: Phase 5 — API Proxy Update

Update the @arda-cards/api-proxy TypeScript package to match the updated print API contracts from Phases 1-3. This is a small, self-contained change in a separate repository.

Requirements: Phase 5 Requirements Verification: Phase 5 Verification Analysis: Gap Analysis — Gap A-2 Depends on: Phases 1-3 must be complete (API contracts finalized).

Task 1: Update RenderResult types

Files:

api-proxy/src/reference/shared/types.ts

Change: Replace the existing RenderResult interface with the composite types:

export interface CompositeRenderResult {
  job: string;
  asOF: TimeCoordinates;
  results: GroupRenderResult[];
}

export interface GroupRenderResult {
  templateId: string;
  description: string;
  itemCount: number;
  url?: string | null;
  error?: string | null;
  debugPayload?: Record<string, unknown> | null;
}

Keep RenderResult as a deprecated type alias if any external consumers depend on it, or remove it if only used internally.

Tests: T-P5-001, T-P5-002.

Requirement: REQ-P5-001

Task 2: Update print proxy methods

Files:

api-proxy/src/reference/item/proxy.ts
api-proxy/src/resources/kanban/proxy.ts

Change: Update method signatures and return types:

// ItemProxy
async printLabels(entityIds: string[], options?: PrintOptions): Promise<CompositeRenderResult>
async printBreadcrumbs(entityIds: string[], options?: PrintOptions): Promise<CompositeRenderResult>

// KanbanProxy
async printCards(entityIds: string[], options?: PrintOptions): Promise<CompositeRenderResult>

Where PrintOptions is:

export interface PrintOptions {
  livePrint?: boolean;
  debug?: boolean;
  dryRun?: boolean;
}

Pass options as query parameters: ?live-print={livePrint}&debug={debug}&dry-run={dryRun}. Omit parameters that are undefined.

Tests: T-P5-003 through T-P5-007.

Requirements: REQ-P5-002, REQ-P5-003

Task 3: Add unmarkPrinted method

Files:

api-proxy/src/resources/kanban/proxy.ts
api-proxy/src/resources/kanban/types.ts (re-export if needed)

Change: Add method to KanbanProxy:

async unmarkPrinted(cardEId: string, effectiveAsOf?: number): Promise<EntityRecord<KanbanCard, KanbanCardMetadata>>

Calls POST /v1/kanban/kanban-card/{cardEId}/event/unmark?effectiveasof={effectiveAsOf}.

Tests: T-P5-008.

Requirement: REQ-P5-004

Task 4: Update tests and CHANGELOG

Files:

api-proxy/tests/reference/item/proxy.test.ts
api-proxy/tests/resources/kanban/proxy.test.ts
api-proxy/CHANGELOG.md

Change: Update existing print method tests to use CompositeRenderResult mock responses. Add tests for new unmarkPrinted and diagnostic options. Update CHANGELOG.

Tests: T-P5-009, T-P5-010.

Requirements: REQ-P5-005, REQ-P5-006

Open Questions and Decisions

#	Question	Options	Recommendation	Decision
1	Should `RenderResult` be removed or kept as a deprecated alias?	A) Remove B) Deprecate with alias	A — api-proxy is internal; no external consumers need backward compatibility	Option A. Remove.

STOP: Review Gate

Before proceeding to implementation, confirm:

Phases 1-3 complete (API contracts finalized)
Requirements approved