npm - @ucdjs/client - Versions diffs - 0.1.1-beta.1 - Mend

@ucdjs/client 0.1.1-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025-PRESENT Lucas Nørgård
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,87 @@
+# @ucdjs/client
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![codecov][codecov-src]][codecov-href]
+A TypeScript-first HTTP client for interacting with the UCD.js API, providing type-safe methods for fetching Unicode character data.
+## Installation
+```bash
+npm install @ucdjs/client
+```
+## Usage
+### Basic Usage
+```typescript
+import { client } from "@ucdjs/client";
+// Get Unicode versions
+const { data: versions, error } = await client.GET("/api/v1/unicode-versions");
+if (error) {
+  console.error("Error:", error.message);
+} else {
+  console.log("Available versions:", versions);
+}
+// Access Unicode data files via proxy
+const { data: fileInfo } = await client.GET("/api/v1/unicode-proxy/{wildcard}", {
+  params: {
+    path: { wildcard: "latest/ucd.all.json" }
+  }
+});
+console.log("File info:", fileInfo);
+```
+### Custom Client Configuration
+```typescript
+import { createClient } from "@ucdjs/client";
+// Create client with custom UCD.js API instance
+const customClient = createClient("https://preview.api.ucdjs.dev");
+// Use the custom client
+const { data, error } = await customClient.GET("/api/v1/unicode-versions");
+if (data) {
+  console.log("Unicode versions from preview API:", data);
+}
+```
+### Working with Binary Data
+```typescript
+import { client } from "@ucdjs/client";
+// Fetch binary Unicode data file
+const { data: binaryData } = await client.GET("/api/v1/unicode-proxy/{wildcard}", {
+  params: {
+    path: { wildcard: "latest/UnicodeData.txt" }
+  },
+  parseAs: "arrayBuffer"
+});
+if (binaryData) {
+  // eslint-disable-next-line node/prefer-global/buffer
+  const text = Buffer.from(binaryData).toString("utf-8");
+  console.log("Unicode data:", `${text.substring(0, 100)}...`);
+}
+```
+## Documentation
+For comprehensive documentation, examples, and API reference, visit the [Client Documentation](https://ucdjs.dev/docs/core/client).
+## 📄 License
+Published under [MIT License](./LICENSE).
+[npm-version-src]: https://img.shields.io/npm/v/@ucdjs/client?style=flat&colorA=18181B&colorB=4169E1
+[npm-version-href]: https://npmjs.com/package/@ucdjs/client
+[npm-downloads-src]: https://img.shields.io/npm/dm/@ucdjs/client?style=flat&colorA=18181B&colorB=4169E1
+[npm-downloads-href]: https://npmjs.com/package/@ucdjs/client
+[codecov-src]: https://img.shields.io/codecov/c/gh/ucdjs/ucd?style=flat&colorA=18181B&colorB=4169E1
+[codecov-href]: https://codecov.io/gh/ucdjs/ucd

package/dist/index.d.mts ADDED Viewed

@@ -0,0 +1,837 @@
+import { SafeFetchResponse } from "@ucdjs-internal/shared";
+import { UCDStoreVersionManifest, UCDWellKnownConfig } from "@ucdjs/schemas";
+//#region src/resources/config.d.ts
+interface ConfigResource {
+  /**
+   * Get the UCD configuration including endpoints and available versions
+   * @returns {Promise<SafeFetchResponse<UCDWellKnownConfig>>} The UCD configuration
+   */
+  get: () => Promise<SafeFetchResponse<UCDWellKnownConfig>>;
+}
+//#endregion
+//#region src/.generated/api.d.ts
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+interface paths {
+  "/api/v1/versions": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    /**
+     * @description ## List All Unicode Versions
+     *
+     *     This endpoint retrieves a comprehensive list of all Unicode versions, including metadata and support status.
+     *
+     *     - Provides **version metadata** such as documentation URLs and public URLs
+     *     - Includes **draft versions** if available
+     *     - Supports **caching** for performance optimization
+     */
+    get: {
+      parameters: {
+        query?: never;
+        header?: never;
+        path?: never;
+        cookie?: never;
+      };
+      requestBody?: never;
+      responses: {
+        /** @description List of Unicode Versions */200: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            "application/json": components["schemas"]["UnicodeVersionList"];
+          };
+        };
+        404: components["responses"]["NotFoundError"];
+        429: components["responses"]["TooManyRequestsError"];
+        500: components["responses"]["InternalServerError"];
+        502: components["responses"]["BadGatewayError"];
+      };
+    };
+    put?: never;
+    post?: never;
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+  "/api/v1/versions/{version}": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    /**
+     * @description ## Get Unicode Version Details
+     *
+     *     This endpoint retrieves detailed information about a specific Unicode version.
+     *
+     *     - Provides **version metadata** such as version name, documentation URL, release date, and type (stable/draft)
+     *     - Includes **location information** (UCD URL and mapped version)
+     *     - Returns **statistics** about characters, blocks, and scripts (if available)
+     *     - Supports **caching** for performance optimization
+     */
+    get: {
+      parameters: {
+        query?: never;
+        header?: never;
+        path: {
+          /** @description A Unicode Version */version: string;
+        };
+        cookie?: never;
+      };
+      requestBody?: never;
+      responses: {
+        /** @description Detailed information about a Unicode version */200: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            "application/json": components["schemas"]["UnicodeVersionDetails"];
+          };
+        };
+        400: components["responses"]["BadRequestError"];
+        404: components["responses"]["NotFoundError"];
+        429: components["responses"]["TooManyRequestsError"];
+        500: components["responses"]["InternalServerError"];
+        502: components["responses"]["BadGatewayError"];
+      };
+    };
+    put?: never;
+    post?: never;
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+  "/api/v1/versions/{version}/file-tree": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    /**
+     * @description This endpoint provides a **structured list of all files** inside the [`ucd folder`](https://unicode.org/Public/UCD/latest/ucd) associated with a specific Unicode version.
+     *
+     *     For older versions, the files are retrieved without the `/ucd` prefix, while for the latest version, the `/ucd` prefix is included.
+     */
+    get: {
+      parameters: {
+        query?: never;
+        header?: never;
+        path: {
+          /** @description A Unicode Version */version: string;
+        };
+        cookie?: never;
+      };
+      requestBody?: never;
+      responses: {
+        /** @description Structured list of files for a Unicode version */200: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            "application/json": components["schemas"]["UnicodeFileTree"];
+          };
+        };
+        400: components["responses"]["BadRequestError"];
+        429: components["responses"]["TooManyRequestsError"];
+        500: components["responses"]["InternalServerError"];
+        502: components["responses"]["BadGatewayError"];
+      };
+    };
+    put?: never;
+    post?: never;
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+  "/api/v1/files/{wildcard}": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    /**
+     * @description This endpoint proxies requests to Unicode.org's Public directory, streaming files directly while transforming directory listings into structured JSON.
+     *
+     *     All paths are relative to `/api/v1/files` — for example, requesting `/api/v1/files/15.1.0/ucd/emoji/emoji-data.txt` fetches the emoji data file from Unicode version 15.1.0.
+     *
+     *     > [!IMPORTANT]
+     *     > The `{wildcard}` parameter accepts any valid path, including deeply nested ones like `15.1.0/ucd/emoji/emoji-data.txt`. In directory listing responses, paths for directories include a trailing slash (e.g., `/15.1.0/ucd/charts/`), while file paths do not.
+     *
+     *     > [!NOTE]
+     *     > To retrieve only metadata without downloading content, use a `HEAD` request instead. See [here](#tag/files/head/api/v1/files/{wildcard})
+     *
+     *     ### Directory Listing Features
+     *
+     *     When accessing a directory, you can filter and sort entries using these query parameters:
+     *
+     *     - `query` - Prefix-based search (case-insensitive) on entry names
+     *     - `pattern` - Glob pattern matching for filtering
+     *     - `type` - Filter by entry type: `all` (default), `files`, or `directories`
+     *     - `sort` - Sort by `name` (default) or `lastModified`
+     *     - `order` - Sort order: `asc` (default) or `desc`
+     *
+     *     ### Modifications
+     *
+     *     Directory responses are automatically transformed into JSON arrays containing file and directory entries. Files are streamed directly from Unicode.org with appropriate content types.
+     */
+    get: {
+      parameters: {
+        query?: {
+          /**
+           * @description A glob pattern to filter directory listing results by filename. Only applies when the response is a directory listing.
+           *     The matching is **case-insensitive**.
+           *
+           *     ## Supported Glob Syntax
+           *
+           *     | Pattern   | Description                                   | Example                                              |
+           *     |-----------|-----------------------------------------------|------------------------------------------------------|
+           *     | `*`     | Match any characters (except path separators) | `*.txt` matches `file.txt`                       |
+           *     | `?`     | Match a single character                      | `file?.txt` matches `file1.txt`                  |
+           *     | `{a,b}` | Match any of the patterns                     | `*.{txt,xml}` matches `file.txt` or `file.xml` |
+           *     | `[abc]` | Match any character in the set                | `file[123].txt` matches `file1.txt`              |
+           *
+           *     ## Examples
+           *
+           *     - `*.txt` - Match all text files
+           *     - `Uni*` - Match files starting with "Uni" (e.g., UnicodeData.txt)
+           *     - `*Data*` - Match files containing "Data"
+           *     - `*.{txt,xml}` - Match text or XML files
+           */
+          pattern?: string;
+          /**
+           * @description A search query to filter directory listing results. Entries are matched if their name **starts with** this value (case-insensitive).
+           *     This is useful for quick prefix-based searching within a directory.
+           *
+           *     ## Examples
+           *
+           *     - `Uni` - Match entries starting with "Uni" (e.g., UnicodeData.txt)
+           *     - `15` - Match version directories starting with "15"
+           */
+          query?: string;
+          /**
+           * @description Filter directory listing results by entry type.
+           *
+           *     - `all` (default) - Return both files and directories
+           *     - `files` - Return only files
+           *     - `directories` - Return only directories
+           */
+          type?: "all" | "files" | "directories";
+          /**
+           * @description The field to sort directory listing results by.
+           *
+           *     - `name` (default) - Sort alphabetically by entry name
+           *     - `lastModified` - Sort by last modification timestamp
+           */
+          sort?: "name" | "lastModified";
+          /**
+           * @description The sort order for directory listing results.
+           *
+           *     - `asc` (default) - Ascending order (A-Z, oldest first)
+           *     - `desc` - Descending order (Z-A, newest first)
+           */
+          order?: "asc" | "desc";
+        };
+        header?: never;
+        path: {
+          /**
+           * @description The path to the Unicode data resource you want to access. This can be any valid path from the official Unicode Public directory structure.
+           *
+           *     ## Path Format Options
+           *
+           *     | Pattern                        | Description                    | Example                             |
+           *     |--------------------------------|--------------------------------|-------------------------------------|
+           *     | `{version}/ucd/{filename}`   | UCD files for specific version | `15.1.0/ucd/UnicodeData.txt`      |
+           *     | `{version}/ucd/{sub}/{file}` | Files in subdirectories        | `15.1.0/ucd/emoji/emoji-data.txt` |
+           *     | `{version}`                  | List files for version         | `15.1.0`                          |
+           *     | `latest/ucd/{filename}`      | Latest version of file         | `latest/ucd/PropList.txt`         |
+           */
+          wildcard: string;
+        };
+        cookie?: never;
+      };
+      requestBody?: never;
+      responses: {
+        /** @description Response from Unicode.org */200: {
+          headers: {
+            /** @description The type of the file or directory */"X-UCD-Stat-Type": "file" | "directory"; /** @description The size of the file in bytes (only for files) */
+            "X-UCD-Stat-Size"?: string; /** @description Number of children (only for directories) */
+            "X-UCD-Stat-Children"?: string; /** @description Number of child files (only for directories) */
+            "X-UCD-Stat-Children-Files"?: string; /** @description Number of child directories (only for directories) */
+            "X-UCD-Stat-Children-Dirs"?: string;
+            [name: string]: unknown;
+          };
+          content: {
+            "application/json": components["schemas"]["FileEntryList"];
+            "application/xml": string;
+            "text/plain": string;
+            "text/html": string;
+            "application/pdf": string;
+            "application/octet-stream": string;
+          };
+        };
+        400: components["responses"]["BadRequestError"];
+        404: components["responses"]["NotFoundError"];
+        500: components["responses"]["InternalServerError"];
+        502: components["responses"]["BadGatewayError"];
+      };
+    };
+    put?: never;
+    post?: never;
+    delete?: never;
+    options?: never;
+    /**
+     * @description Retrieve metadata about a file or directory without downloading the content. Useful for checking existence, file size, and other metadata.
+     *
+     *     All paths are relative to `/api/v1/files`. Directory paths always include a trailing slash (e.g., `/15.1.0/ucd/charts/`), while file paths do not.
+     *
+     *     > [!NOTE]
+     *     > This endpoint returns the same headers as the `GET` request (file size, directory entry counts, last modified timestamps, content type) without the response body.
+     */
+    head: {
+      parameters: {
+        query?: {
+          /**
+           * @description A glob pattern to filter directory listing results by filename. Only applies when the response is a directory listing.
+           *     The matching is **case-insensitive**.
+           *
+           *     ## Supported Glob Syntax
+           *
+           *     | Pattern   | Description                                   | Example                                              |
+           *     |-----------|-----------------------------------------------|------------------------------------------------------|
+           *     | `*`     | Match any characters (except path separators) | `*.txt` matches `file.txt`                       |
+           *     | `?`     | Match a single character                      | `file?.txt` matches `file1.txt`                  |
+           *     | `{a,b}` | Match any of the patterns                     | `*.{txt,xml}` matches `file.txt` or `file.xml` |
+           *     | `[abc]` | Match any character in the set                | `file[123].txt` matches `file1.txt`              |
+           *
+           *     ## Examples
+           *
+           *     - `*.txt` - Match all text files
+           *     - `Uni*` - Match files starting with "Uni" (e.g., UnicodeData.txt)
+           *     - `*Data*` - Match files containing "Data"
+           *     - `*.{txt,xml}` - Match text or XML files
+           */
+          pattern?: string;
+          /**
+           * @description A search query to filter directory listing results. Entries are matched if their name **starts with** this value (case-insensitive).
+           *     This is useful for quick prefix-based searching within a directory.
+           *
+           *     ## Examples
+           *
+           *     - `Uni` - Match entries starting with "Uni" (e.g., UnicodeData.txt)
+           *     - `15` - Match version directories starting with "15"
+           */
+          query?: string;
+          /**
+           * @description Filter directory listing results by entry type.
+           *
+           *     - `all` (default) - Return both files and directories
+           *     - `files` - Return only files
+           *     - `directories` - Return only directories
+           */
+          type?: "all" | "files" | "directories";
+          /**
+           * @description The field to sort directory listing results by.
+           *
+           *     - `name` (default) - Sort alphabetically by entry name
+           *     - `lastModified` - Sort by last modification timestamp
+           */
+          sort?: "name" | "lastModified";
+          /**
+           * @description The sort order for directory listing results.
+           *
+           *     - `asc` (default) - Ascending order (A-Z, oldest first)
+           *     - `desc` - Descending order (Z-A, newest first)
+           */
+          order?: "asc" | "desc";
+        };
+        header?: never;
+        path: {
+          /**
+           * @description The path to the Unicode data resource you want to access. This can be any valid path from the official Unicode Public directory structure.
+           *
+           *     ## Path Format Options
+           *
+           *     | Pattern                        | Description                    | Example                             |
+           *     |--------------------------------|--------------------------------|-------------------------------------|
+           *     | `{version}/ucd/{filename}`   | UCD files for specific version | `15.1.0/ucd/UnicodeData.txt`      |
+           *     | `{version}/ucd/{sub}/{file}` | Files in subdirectories        | `15.1.0/ucd/emoji/emoji-data.txt` |
+           *     | `{version}`                  | List files for version         | `15.1.0`                          |
+           *     | `latest/ucd/{filename}`      | Latest version of file         | `latest/ucd/PropList.txt`         |
+           */
+          wildcard: string;
+        };
+        cookie?: never;
+      };
+      requestBody?: never;
+      responses: {
+        /** @description Response from Unicode.org */200: {
+          headers: {
+            /** @description The type of the file or directory */"X-UCD-Stat-Type": "file" | "directory"; /** @description The size of the file in bytes (only for files) */
+            "X-UCD-Stat-Size": string; /** @description Number of children (only for directories) */
+            "X-UCD-Stat-Children"?: string; /** @description Number of child files (only for directories) */
+            "X-UCD-Stat-Children-Files"?: string; /** @description Number of child directories (only for directories) */
+            "X-UCD-Stat-Children-Dirs"?: string; /** @description The content type of the file */
+            "Content-Type": string; /** @description Last modification time from upstream */
+            "Last-Modified"?: string; /** @description Byte length when applicable */
+            "Content-Length": string;
+            [name: string]: unknown;
+          };
+          content?: never;
+        };
+      };
+    };
+    patch?: never;
+    trace?: never;
+  };
+  "/.well-known/ucd-config.json": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    /**
+     * @description ## UCD Configuration
+     *
+     *     This endpoint retrieves the UCD configuration, including available API endpoints for accessing Unicode data resources.
+     *
+     *     > [!NOTE]
+     *     > The configuration follows the [UCD.js Well-Known Configuration](https://ucdjs.dev/docs/usage/well-known) specification.
+     */
+    get: {
+      parameters: {
+        query?: never;
+        header?: never;
+        path?: never;
+        cookie?: never;
+      };
+      requestBody?: never;
+      responses: {
+        /** @description Retrieves the UCD configuration */200: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            "application/json": components["schemas"]["UCDWellKnownConfig"];
+          };
+        };
+        502: components["responses"]["BadGatewayError"];
+      };
+    };
+    put?: never;
+    post?: never;
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+  "/.well-known/ucd-store/{version}.json": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    /**
+     * @description ## UCD Store Manifest (Per Version)
+     *
+     *     This endpoint retrieves the UCD Store manifest for a specific Unicode version, containing metadata about expected files for that version.
+     *
+     *     This is the recommended endpoint for fetching manifest data, as it provides:
+     *     - Smaller payloads (only the requested version)
+     *     - Better caching (version-specific cache invalidation)
+     *     - Reduced server load
+     *
+     *     Each file entry includes:
+     *     - `name`: The filename only
+     *     - `path`: Path for the /api/v1/files endpoint (includes /ucd/ for versions >= 4.1.0)
+     *     - `storePath`: Path for the store subdomain (ucd-store.ucdjs.dev)
+     *
+     *     > [!NOTE]
+     *     > The monolithic endpoint `/.well-known/ucd-store.json` is deprecated. Use this per-version endpoint instead.
+     */
+    get: {
+      parameters: {
+        query?: never;
+        header?: never;
+        path: {
+          /** @description Unicode version (e.g., '16.0.0') */version: string;
+        };
+        cookie?: never;
+      };
+      requestBody?: never;
+      responses: {
+        /** @description The UCD Store manifest for the specified version */200: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            "application/json": components["schemas"]["UCDStoreVersionManifest"];
+          };
+        };
+        404: components["responses"]["NotFoundError"];
+        429: components["responses"]["TooManyRequestsError"];
+        500: components["responses"]["InternalServerError"];
+        502: components["responses"]["BadGatewayError"];
+      };
+    };
+    put?: never;
+    post?: never;
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+}
+interface components {
+  schemas: {
+    /**
+     * @description Standard error response format used consistently across all API endpoints.
+     *
+     *     Contains essential information for debugging and user feedback. The specific error scenarios and status codes are documented in the individual endpoint response definitions.
+     */
+    ApiError: {
+      /** @description Human-readable error message describing what went wrong */message: string; /** @description HTTP status code matching the response status */
+      status: number; /** @description ISO 8601 timestamp when the error occurred */
+      timestamp: string;
+    }; /** @description A list of Unicode versions with their metadata and support status. */
+    UnicodeVersionList: components["schemas"]["UnicodeVersion"][];
+    /**
+     * @description Represents a Unicode version with its metadata and support status.
+     * @example {
+     *       "version": "17.0.0",
+     *       "documentationUrl": "https://www.unicode.org/versions/Unicode17.0.0/",
+     *       "date": null,
+     *       "url": "https://www.unicode.org/Public/17.0.0",
+     *       "mappedUcdVersion": null,
+     *       "type": "draft"
+     *     }
+     * @example {
+     *       "version": "16.0.0",
+     *       "documentationUrl": "https://www.unicode.org/versions/Unicode16.0.0/",
+     *       "date": "2024",
+     *       "url": "https://www.unicode.org/Public/16.0.0",
+     *       "mappedUcdVersion": null,
+     *       "type": "stable"
+     *     }
+     * @example {
+     *       "version": "15.1.0",
+     *       "documentationUrl": "https://www.unicode.org/versions/Unicode15.1.0/",
+     *       "date": "2023",
+     *       "url": "https://www.unicode.org/Public/15.1.0",
+     *       "mappedUcdVersion": null,
+     *       "type": "stable"
+     *     }
+     */
+    UnicodeVersion: {
+      /** @description The version of the Unicode standard. */version: string;
+      /**
+       * Format: uri
+       * @description The URL to the Unicode version documentation.
+       */
+      documentationUrl: string; /** @description The year of the Unicode version. */
+      date: string | null;
+      /**
+       * Format: uri
+       * @description The URL to the Unicode Character Database (UCD) for this version.
+       */
+      url: string; /** @description The corresponding UCD version mapping for this Unicode version. Null if same as version. */
+      mappedUcdVersion: string | null;
+      /**
+       * @description The status of the Unicode version. 'unsupported' means the version exists but is not yet supported by the API.
+       * @enum {string}
+       */
+      type: "draft" | "stable" | "unsupported";
+    };
+    /**
+     * @description Detailed information about a Unicode version, including metadata and statistics.
+     * @example {
+     *       "version": "16.0.0",
+     *       "documentationUrl": "https://www.unicode.org/versions/Unicode16.0.0/",
+     *       "date": "2024",
+     *       "url": "https://www.unicode.org/Public/16.0.0",
+     *       "mappedUcdVersion": null,
+     *       "type": "stable",
+     *       "statistics": {
+     *         "totalCharacters": 149813,
+     *         "newCharacters": 5185,
+     *         "totalBlocks": 331,
+     *         "newBlocks": 4,
+     *         "totalScripts": 165,
+     *         "newScripts": 2
+     *       }
+     *     }
+     */
+    UnicodeVersionDetails: {
+      /** @description The version of the Unicode standard. */version: string;
+      /**
+       * Format: uri
+       * @description The URL to the Unicode version documentation.
+       */
+      documentationUrl: string; /** @description The year of the Unicode version. */
+      date: string | null;
+      /**
+       * Format: uri
+       * @description The URL to the Unicode Character Database (UCD) for this version.
+       */
+      url: string; /** @description The corresponding UCD version mapping for this Unicode version. Null if same as version. */
+      mappedUcdVersion: string | null;
+      /**
+       * @description The status of the Unicode version. 'unsupported' means the version exists but is not yet supported by the API.
+       * @enum {string}
+       */
+      type: "draft" | "stable" | "unsupported";
+      /**
+       * @description Statistics about this Unicode version. May be null if statistics are not available.
+       * @default {
+       *       "newBlocks": 0,
+       *       "newCharacters": 0,
+       *       "newScripts": 0,
+       *       "totalBlocks": 0,
+       *       "totalCharacters": 0,
+       *       "totalScripts": 0
+       *     }
+       */
+      statistics: {
+        /** @description Total number of characters in this Unicode version. */totalCharacters: number; /** @description Number of new characters added in this version. */
+        newCharacters: number; /** @description Total number of blocks in this Unicode version. */
+        totalBlocks: number; /** @description Number of new blocks added in this version. */
+        newBlocks: number; /** @description Total number of scripts in this Unicode version. */
+        totalScripts: number; /** @description Number of new scripts added in this version. */
+        newScripts: number;
+      };
+    }; /** @description A recursive file tree structure rooted at an array of entries. */
+    UnicodeFileTree: components["schemas"]["UnicodeFileTreeNode"][]; /** @description A recursive file tree node; directories include children, files do not. */
+    UnicodeFileTreeNode: components["schemas"]["UnicodeFileTreeDirectory"] | components["schemas"]["UnicodeFileTreeFile"]; /** @description A directory node in the Unicode file tree, containing child nodes. */
+    UnicodeFileTreeDirectory: {
+      name: string;
+      path: string;
+      lastModified: number | null; /** @enum {string} */
+      type: "directory";
+      children: components["schemas"]["UnicodeFileTreeNode"][];
+    }; /** @description A file node in the Unicode file tree. */
+    UnicodeFileTreeFile: {
+      name: string;
+      path: string;
+      lastModified: number | null; /** @enum {string} */
+      type: "file";
+    }; /** @description An array of file entries, each representing either a file or a directory. */
+    FileEntryList: ({
+      name: string;
+      path: string;
+      lastModified: number | null; /** @enum {string} */
+      type: "directory";
+    } | {
+      name: string;
+      path: string;
+      lastModified: number | null; /** @enum {string} */
+      type: "file";
+    })[];
+    /**
+     * @description Configuration schema for the .well-known/ucd-config.json endpoint.
+     *
+     *     This configuration provides clients with the necessary information to interact with the UCD API server, including endpoint paths and optional metadata about the server itself.
+     *
+     *     The `manifest` endpoint is deprecated. Use the per-version endpoint `/.well-known/ucd-store/{version}.json` instead for better performance and caching.
+     */
+    UCDWellKnownConfig: {
+      /** @default 1.0 */version: string;
+      endpoints: {
+        files: string;
+        manifest: string;
+        versions: string;
+      }; /** @default [] */
+      versions: string[];
+    };
+    /**
+     * @description Response schema for per-version manifest endpoint.
+     *     Matches the schema from /.well-known/ucd-store/{version}.json
+     */
+    UCDStoreVersionManifest: {
+      /** @description List of expected files for this version with their paths */expectedFiles: components["schemas"]["ExpectedFile"][];
+    }; /** @description A file expected to be present in a UCD version */
+    ExpectedFile: {
+      /** @description Filename only */name: string; /** @description Path relative to /api/v1/files endpoint (includes /ucd/ for versions >= 4.1.0) */
+      path: string; /** @description Path for store subdomain (without /ucd/ prefix) */
+      storePath: string;
+    };
+  };
+  responses: {
+    /** @description Bad request error */BadRequestError: {
+      headers: {
+        [name: string]: unknown;
+      };
+      content: {
+        "application/json": components["schemas"]["ApiError"];
+      };
+    }; /** @description Resource not found */
+    NotFoundError: {
+      headers: {
+        [name: string]: unknown;
+      };
+      content: {
+        "application/json": components["schemas"]["ApiError"];
+      };
+    }; /** @description Rate limit exceeded */
+    TooManyRequestsError: {
+      headers: {
+        [name: string]: unknown;
+      };
+      content: {
+        "application/json": components["schemas"]["ApiError"];
+      };
+    }; /** @description Internal server error */
+    InternalServerError: {
+      headers: {
+        [name: string]: unknown;
+      };
+      content: {
+        "application/json": components["schemas"]["ApiError"];
+      };
+    }; /** @description Bad gateway - upstream service failed */
+    BadGatewayError: {
+      headers: {
+        [name: string]: unknown;
+      };
+      content: {
+        "application/json": components["schemas"]["ApiError"];
+      };
+    };
+  };
+  parameters: never;
+  requestBodies: never;
+  headers: never;
+  pathItems: never;
+}
+//#endregion
+//#region src/resources/files.d.ts
+type FileResponse = paths["/api/v1/files/{wildcard}"]["get"]["responses"][200]["content"];
+interface FilesResource {
+  /**
+   * Get a file or directory listing from the Unicode data
+   *
+   * @param {string} path - The path to the file (e.g., "16.0.0/ucd/UnicodeData.txt")
+   * @returns {Promise<SafeFetchResponse<FileResponse[keyof FileResponse]>>} File content as text, JSON, or other format depending on the file type
+   */
+  get: (path: string) => Promise<SafeFetchResponse<FileResponse[keyof FileResponse]>>;
+}
+//#endregion
+//#region src/resources/manifest.d.ts
+interface ManifestResource {
+  /**
+   * Get the manifest for a specific Unicode version
+   * @param {string} version - The Unicode version (e.g., "16.0.0")
+   * @returns {Promise<SafeFetchResponse<UCDStoreVersionManifest>>} The manifest containing expectedFiles
+   */
+  get: (version: string) => Promise<SafeFetchResponse<UCDStoreVersionManifest>>;
+}
+//#endregion
+//#region src/resources/versions.d.ts
+type VersionsListResponse = paths["/api/v1/versions"]["get"]["responses"][200]["content"]["application/json"];
+type FileTreeResponse = paths["/api/v1/versions/{version}/file-tree"]["get"]["responses"][200]["content"]["application/json"];
+interface VersionsResource {
+  /**
+   * List all available Unicode versions
+   * @return {Promise<SafeFetchResponse<VersionsListResponse>>} An array of available Unicode version strings
+   */
+  list: () => Promise<SafeFetchResponse<VersionsListResponse>>;
+  /**
+   * Get the file tree for a specific Unicode version
+   *
+   * @param {string} version - The Unicode version (e.g., "16.0.0")
+   * @returns {Promise<SafeFetchResponse<FileTreeResponse>>} The file tree structure for the specified version
+   */
+  getFileTree: (version: string) => Promise<SafeFetchResponse<FileTreeResponse>>;
+}
+//#endregion
+//#region src/index.d.ts
+interface UCDClient {
+  /**
+   * Access file-related endpoints
+   */
+  files: FilesResource;
+  /**
+   * Access version-related endpoints
+   */
+  versions: VersionsResource;
+  /**
+   * Access configuration endpoints
+   */
+  config: ConfigResource;
+  /**
+   * Access manifest endpoints
+   */
+  manifest: ManifestResource;
+}
+/**
+ * Creates a UCD client that automatically discovers endpoint paths
+ * via the well-known configuration endpoint
+ *
+ * @param {string} baseUrl - The base URL of the UCD API server (e.g., "https://api.ucdjs.dev")
+ * @returns {Promise<UCDClient>} A configured UCD client with resource namespaces
+ *
+ * @example
+ * ```ts
+ * const client = await createUCDClient('https://api.ucdjs.dev');
+ *
+ * // List all versions
+ * const versions = await client.versions.list();
+ *
+ * // Get a file
+ * const file = await client.files.get('16.0.0/ucd/UnicodeData.txt');
+ *
+ * // Get configuration
+ * const config = await client.config.get();
+ *
+ * // Get manifest for a version
+ * const manifest = await client.manifest.get('16.0.0');
+ * ```
+ */
+declare function createUCDClient(baseUrl: string): Promise<UCDClient>;
+/**
+ * Creates a UCD client with a synchronous configuration
+ *
+ * @param {string} baseUrl - The base URL of the UCD API server (e.g., "https://api.ucdjs.dev")
+ * @param {UCDWellKnownConfig} endpointConfig - The well-known configuration for endpoints
+ * @returns {UCDClient} A configured UCD client with resource namespaces
+ *
+ * @example
+ * ```ts
+ * const client = createUCDClientWithConfig('https://api.ucdjs.dev', {
+ *   version: '1.0',
+ *   endpoints: {
+ *     files: '/files',
+ *     manifest: '/files/.ucd-store.json',
+ *     versions: '/versions',
+ *   },
+ * });
+ *
+ * // List all versions
+ * const versions = await client.versions.list();
+ *
+ * // Get a file
+ * const file = await client.files.get('16.0.0/ucd/UnicodeData.txt');
+ * ```
+ */
+declare function createUCDClientWithConfig(baseUrl: string, endpointConfig: UCDWellKnownConfig): UCDClient;
+//#endregion
+export { UCDClient, createUCDClient, createUCDClientWithConfig };

package/dist/index.mjs ADDED Viewed

@@ -0,0 +1,155 @@
+import { customFetch, discoverEndpointsFromConfig, tryOr } from "@ucdjs-internal/shared";
+import { UCDStoreVersionManifestSchema, UCDWellKnownConfigSchema, UnicodeFileTreeSchema, UnicodeVersionListSchema } from "@ucdjs/schemas";
+import { PathTraversalError, resolveSafePath } from "@ucdjs/path-utils";
+//#region src/resources/config.ts
+function createConfigResource(options) {
+	const { baseUrl } = options;
+	return { async get() {
+		const url = new URL("/.well-known/ucd-config.json", baseUrl);
+		return customFetch.safe(url.toString(), {
+			parseAs: "json",
+			schema: UCDWellKnownConfigSchema
+		});
+	} };
+}
+//#endregion
+//#region src/resources/files.ts
+function createFilesResource(options) {
+	const { baseUrl, endpoints } = options;
+	return { async get(path) {
+		const resolvedPathOrError = tryOr({
+			try: () => resolveSafePath(endpoints.files, path),
+			err: (err) => {
+				if (err instanceof PathTraversalError) return {
+					data: null,
+					error: err
+				};
+				throw err;
+			}
+		});
+		if (typeof resolvedPathOrError !== "string") return resolvedPathOrError;
+		const url = new URL(resolvedPathOrError, baseUrl);
+		return customFetch.safe(url.toString());
+	} };
+}
+//#endregion
+//#region src/resources/manifest.ts
+/**
+* Regex pattern for validating Unicode version format (X.Y.Z)
+* Compiled once at module load for better performance
+*/
+const VERSION_FORMAT_REGEX = /^\d+\.\d+\.\d+$/;
+function createManifestResource(options) {
+	const { baseUrl } = options;
+	return { async get(version) {
+		if (!VERSION_FORMAT_REGEX.test(version)) return {
+			error: /* @__PURE__ */ new Error(`Invalid version format: ${version}. Expected X.Y.Z format.`),
+			data: null
+		};
+		const url = new URL(`/.well-known/ucd-store/${version}.json`, baseUrl);
+		return customFetch.safe(url.toString(), {
+			parseAs: "json",
+			schema: UCDStoreVersionManifestSchema
+		});
+	} };
+}
+//#endregion
+//#region src/resources/versions.ts
+function createVersionsResource(options) {
+	const { baseUrl, endpoints } = options;
+	return {
+		async list() {
+			const url = new URL(endpoints.versions, baseUrl);
+			return customFetch.safe(url.toString(), {
+				parseAs: "json",
+				schema: UnicodeVersionListSchema
+			});
+		},
+		async getFileTree(version) {
+			const url = new URL(`${endpoints.versions}/${version}/file-tree`, baseUrl);
+			return customFetch.safe(url.toString(), {
+				parseAs: "json",
+				schema: UnicodeFileTreeSchema
+			});
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+function createResources(baseUrl, endpointConfig) {
+	return {
+		files: createFilesResource({
+			baseUrl,
+			endpoints: endpointConfig
+		}),
+		versions: createVersionsResource({
+			baseUrl,
+			endpoints: endpointConfig
+		}),
+		config: createConfigResource({ baseUrl }),
+		manifest: createManifestResource({ baseUrl })
+	};
+}
+/**
+* Creates a UCD client that automatically discovers endpoint paths
+* via the well-known configuration endpoint
+*
+* @param {string} baseUrl - The base URL of the UCD API server (e.g., "https://api.ucdjs.dev")
+* @returns {Promise<UCDClient>} A configured UCD client with resource namespaces
+*
+* @example
+* ```ts
+* const client = await createUCDClient('https://api.ucdjs.dev');
+*
+* // List all versions
+* const versions = await client.versions.list();
+*
+* // Get a file
+* const file = await client.files.get('16.0.0/ucd/UnicodeData.txt');
+*
+* // Get configuration
+* const config = await client.config.get();
+*
+* // Get manifest for a version
+* const manifest = await client.manifest.get('16.0.0');
+* ```
+*/
+async function createUCDClient(baseUrl) {
+	return createResources(baseUrl, (await discoverEndpointsFromConfig(baseUrl)).endpoints);
+}
+/**
+* Creates a UCD client with a synchronous configuration
+*
+* @param {string} baseUrl - The base URL of the UCD API server (e.g., "https://api.ucdjs.dev")
+* @param {UCDWellKnownConfig} endpointConfig - The well-known configuration for endpoints
+* @returns {UCDClient} A configured UCD client with resource namespaces
+*
+* @example
+* ```ts
+* const client = createUCDClientWithConfig('https://api.ucdjs.dev', {
+*   version: '1.0',
+*   endpoints: {
+*     files: '/files',
+*     manifest: '/files/.ucd-store.json',
+*     versions: '/versions',
+*   },
+* });
+*
+* // List all versions
+* const versions = await client.versions.list();
+*
+* // Get a file
+* const file = await client.files.get('16.0.0/ucd/UnicodeData.txt');
+* ```
+*/
+function createUCDClientWithConfig(baseUrl, endpointConfig) {
+	return createResources(baseUrl, endpointConfig.endpoints);
+}
+//#endregion
+export { createUCDClient, createUCDClientWithConfig };

package/package.json ADDED Viewed

@@ -0,0 +1,62 @@
+{
+  "name": "@ucdjs/client",
+  "version": "0.1.1-beta.1",
+  "type": "module",
+  "author": {
+    "name": "Lucas Nørgård",
+    "email": "lucasnrgaard@gmail.com",
+    "url": "https://luxass.dev"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/ucdjs/ucd",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ucdjs/ucd.git",
+    "directory": "packages/client"
+  },
+  "bugs": {
+    "url": "https://github.com/ucdjs/ucd/issues"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "@ucdjs/schemas": "0.1.1-beta.1",
+    "@ucdjs/path-utils": "0.1.1-beta.1",
+    "@ucdjs-internal/shared": "0.1.1-beta.1",
+    "@ucdjs/env": "0.1.1-beta.1"
+  },
+  "devDependencies": {
+    "@luxass/eslint-config": "7.2.0",
+    "@types/picomatch": "4.0.2",
+    "eslint": "10.0.0",
+    "openapi-typescript": "7.13.0",
+    "publint": "0.3.17",
+    "tsdown": "0.20.3",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "vitest-testdirs": "4.4.2",
+    "@ucdjs-tooling/tsdown-config": "1.0.0",
+    "@ucdjs-tooling/tsconfig": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown --tsconfig=./tsconfig.build.json",
+    "dev": "tsdown --watch",
+    "clean": "git clean -xdf dist node_modules",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit -p tsconfig.build.json",
+    "generate:client": "openapi-typescript ../../ucd-generated/api/openapi.json -o ./src/.generated/api.d.ts",
+    "generate:client:local": "openapi-typescript http://localhost:8787/openapi.json -o ./src/.generated/api.d.ts"
+  }
+}