Client
Architecture notes for @ucdjs/client
@ucdjs/client is the typed HTTP client for UCD.js services.
Role
- Discovers endpoints from the
.well-knownconfig. - Exposes typed resource wrappers for files, versions, and config.
- Defines the consumer-facing request and error contract used by higher-level packages.
Related Docs
Public Package Docs
User-facing client overview and examples.
Data Flow
See where client discovery and API consumption fit in the system.
Package Layers
Understand how the client relates to schemas, env, and consumers.
UCD Store
See how ucd-store uses the client for discovery, manifests, trees, and file fetches.
Mental Model
The client has two construction modes:
createUCDClient(baseUrl)performs.well-knowndiscovery firstcreateUCDClientWithConfig(baseUrl, config)skips discovery and builds resources directly
Once constructed, the client exposes three resource namespaces:
configfilesversions
Each resource returns { data, error } style results instead of throwing for normal request failures.
The main exception is endpoint discovery, where createUCDClient() throws if the .well-known
document cannot be fetched or validated.
Method Flows
createUCDClient(baseUrl)
createUCDClientWithConfig(baseUrl, config)
client.files.get(path)
client.versions.list() and client.versions.getFileTree(version)
client.versions.getManifest(version)
client.config.get()
Testing Use
These diagrams also define the most useful client test buckets:
- discovery success, fetch failure, and invalid
.well-knownconfig - safe-path validation for
files.get() - successful resource fetches with schema validation
- invalid version format for
getManifest() - normalization of request failures into
{ data, error }