ThePalaceProject / web-patron / 28212759312

89%

push

github

Schema validation for registry and authentication document responses (PP-4583) (#151)

## Description

Add runtime validation for library registry feed and authentication
document responses using ArkType schemas, complementing the existing
compile-time TypeScript types.

- New ArkType schemas in `src/validation/` validate auth document and
registry feed responses at the point they are fetched, catching
malformed upstream data before it enters the application.
- Schema-derived types for leaf shapes (labels, inputs, localized
values, color scheme, features, etc.) replace hand-written interfaces,
making the ArkType schemas the single source of truth for those types.
Compound types that use CPW-specific narrowing (discriminated auth
method union, `AuthDocument` itself) remain hand-written.
- Auth document schema aligned with Palace Manager's
`PalaceAuthenticationDocument` Pydantic model, including Palace
extension fields (e.g., `features`, `public_key`,
`service_description`).
- Registry feed schema aligned with the Library Registry's `OPDSCatalog`
output, including `modified` alongside `updated`, nullable
`adobe_vendor_id`, `numberOfItems` for paginated feeds, `images` on
catalog entries, `properties` on links, and `@type` on facet group
metadata.

## Motivation and Context

CPW has TypeScript types enforcing structure at compile time, but no
runtime validation of responses from the Circulation Manager (auth
documents) or Library Registry (OPDS 2 feeds). A malformed upstream
response would silently propagate through the app, potentially causing
confusing errors far from the source. Runtime validation catches these
at the API boundary and produces clear error messages.

ArkType is already used for config file validation, so this extends the
same approach to external API responses. This is foundational work
toward making ArkType schemas the single source of truth for related
types — deriving TypeScript types directly from the schemas so runtime
validation ... (continued)

225 of 260 branches covered (86.54%)

Branch coverage included in aggregate %.

28 of 28 new or added lines in 4 files covered. (100.0%)

383 of 427 relevant lines covered (89.7%)

29.93 hits per line