Resource-based client for the UCD API with well-known discovery or explicit config

Client

The @ucdjs/client package provides a type-safe API client for interacting with the UCD.js API. It provides resource-based helpers for Unicode data files, reports, versions, version manifests, and published server configuration.

Getting Started

Installation

Install the client using your preferred package manager.

npm install @ucdjs/client

Initialization

Create a client instance using createUCDClient(). This fetches /.well-known/ucd-config.json from the provided origin, validates it, and uses the discovered endpoint paths to build the resource wrappers. Unlike resource calls (which return { data, error }), createUCDClient() will throw if discovery or validation fails, so you should wrap it in appropriate error handling.

client.ts

import { createUCDClient } from "@ucdjs/client";

const client = await createUCDClient("https://api.ucdjs.dev");

Usage

The client uses a safe error handling pattern for resource calls. You receive an object containing data and error, and discovery happens only during createUCDClient().

client.ts

// Fetch available Unicode versions
const { data: versions, error } = await client.versions.list();

if (error) {
  console.error("Failed to fetch versions:", error.message);
} else {
  console.log("Available versions:", versions);
}

Discovery vs explicit config

There are two ways to configure the client:

createUCDClient(baseUrl) loads /.well-known/ucd-config.json from the server
createUCDClientWithConfig(baseUrl, config) skips the discovery request and accepts the same config object directly

Both approaches use the same UCDWellKnownConfig shape. The difference is only where that data comes from.

This matters when an installation serves the API from a non-default path. For example, a server can publish:

/.well-known/ucd-config.json on the main origin
/edge/api/files for files
/edge/api/reports for reports
/edge/api/versions for versions

The client types stay the same because the config points the resource wrappers at the correct paths.

client.config.get() still reads the published well-known config from the origin. Version manifest requests follow the configured endpoints.manifest value, so discovery and explicit config both use the same canonical route by default.

client.ts

import { createUCDClientWithConfig } from "@ucdjs/client";

const client = createUCDClientWithConfig("https://example.com", {
  version: "0.1",
  endpoints: {
    files: "/edge/api/files",
    manifest: "/edge/api/versions/{version}/manifest",
    reports: "/edge/api/reports",
    versions: "/edge/api/versions",
  },
});

Client flow

Resources

The client provides four primary resource namespaces. You access them as properties on the instantiated client object.

Prop

Type

Examples

const { data: fileContent, error } = await client.files.get("16.0.0/ucd/UnicodeData.txt");

if (error) {
  console.error("Failed to fetch file:", error.message);
  return;
}

console.log("File content:", fileContent);

// List reports
const { data: reports, error } = await client.reports.list();

if (error) {
  console.error("Failed to fetch reports:", error.message);
  return;
}

// Get latest metadata for a report
const { data: report } = await client.reports.get("tr44");
console.log("Latest report revision:", report?.revision);

// Get a specific revision document
const { data: html } = await client.reports.getHtml("tr44", "36");
console.log("Report HTML:", html);

// List all versions
const { data: versions, error } = await client.versions.list();

if (error) {
  console.error("Failed to fetch versions:", error.message);
  return;
}

// Get file tree for a specific Unicode version
const { data: fileTree } = await client.versions.getFileTree("16.0.0");
console.log("File tree:", fileTree);

// Get the manifest for a specific Unicode version
const { data: manifest } = await client.versions.getManifest("16.0.0");
console.log("Expected files:", manifest?.expectedFiles);

const { data: config, error } = await client.config.get();

if (error) {
  console.error("Failed to fetch config:", error.message);
  return;
}

console.log("API Config:", config);

Client

On this page