@registrystack/client 0.28.0 → 0.30.0

package/README.md

@@ -1,20 +1,48 @@
-# `@registrystack/client`
+# @registrystack/client
 
-One versioned Node.js package for the Discovery, Evidence, Relay, and Base
-Registry Engine client APIs in Registry Stack.
+One versioned Node.js package for the Discovery, Evidence, Relay, Base Registry
+Engine, and Casework client APIs in Registry Stack.
+
+## Install
 
 ```sh
 npm install "@registrystack/client@<version>"
 ```
 
+Requires Node.js 22.12 or newer. Supported targets are macOS arm64, Linux
+arm64 with glibc, and Linux x64 with glibc; installing the package pulls in
+one platform-specific optional dependency containing all five native
+bindings.
+
+## Usage
+
 ```js
-const { discovery, evidence, relay, breg } = require('@registrystack/client');
+const { discovery, evidence, relay, breg, casework } = require('@registrystack/client');
 
 const registry = new breg.BaseRegistryClient({
   baseUrl: 'https://registry.example.invalid/',
 });
+const work = new casework.CaseworkClient({
+  baseUrl: 'https://casework.example.invalid/',
+});
 ```
 
+## Products
+
+- `discovery`: Registry Discovery, bounded search and resolution over a
+  curated index.
+- `evidence`: Evidence Gateway, request and verify signed minimum-disclosure
+  assertions.
+- `relay`: Registry Relay, scoped read-only APIs over existing sources.
+- `breg`: Base Registry Engine, records, contracts, writes, and lifecycle.
+- `casework`: Registry Casework, staff inbox, claims, drafts, decisions,
+  recovery, history, holdings, and directory bootstrap.
+
+Each product remains in its own namespace because its routing,
+authentication, errors, and verification rules are different.
+
+## TypeScript
+
 A TypeScript consumer also needs the Node type definitions, and must name
 them. The published declarations use `Buffer`, a Node.js global, and
 TypeScript 6 does not load installed `@types` packages on its own, so a
@@ -37,29 +65,49 @@ npm install --save-dev "@types/node"
 The package does not declare that dependency itself, because a JavaScript
 consumer does not need it.
 
-Each product remains in its own namespace because its routing,
-authentication, errors, and verification rules are different. The package
-uses one platform-specific native dependency containing all four bindings.
-Supported targets are macOS arm64, Linux arm64 with glibc, and Linux x64 with
-glibc. Install the exact client version that matches the deployment.
-
-The unified package is published beginning with Registry Stack v0.26.1.
-Existing standalone client packages remain available for earlier versions,
-but the release process does not publish new standalone versions once this
-package is active.
-
-For server-side BReg applications, `breg.BaseRegistryClient.registryContract()`
-returns caller-filtered `operations` with typed field, request, and list-query
-descriptors. Descriptions do not grant authority: select opaque create, patch,
-and lifecycle authorities from that same contract before executing mutations.
-
-Use BReg methods ending in `Json` when values must cross Node without numeric
-coercion. They accept domain JSON text and return `valueJson` plus the usual
-trace, ETag, location, and opaque continuation. `lifecycleActionsJson` accepts a
-record envelope; opaque actions expose `bodyJson` and `reviewJson`. Decode these
-strings with a lossless JSON library when displaying wide numbers. Decimal
-fields remain fixed-scale strings, and null remains distinct from absence.
-Duplicate members and silently rounded literals are refused. Existing BReg
-integer restrictions still apply: `9007199254740992` is a supported write,
-whereas `9007199254740993` is refused before I/O. Do not round refused values.
-The client never retries a mutation automatically.
+## Base Registry Engine notes
+
+`breg.BaseRegistryClient.registryContract()` returns caller-filtered
+`operations` with typed field, readable request field, request, and list-query
+descriptors; those
+descriptions grant no authority, so select the opaque create, patch, and
+lifecycle authorities from that same contract before executing a mutation.
+Methods ending in `Json` keep values exact across the Node number boundary:
+they accept domain JSON text and return `valueJson` alongside the usual
+trace, ETag, location, and opaque continuation. The client never retries a
+mutation automatically. See
+[Exact JSON in Node](https://docs.registrystack.org/reference/client-api/#exact-json-in-node)
+for the full rules.
+
+## Versioning
+
+Install the exact client version that matches the deployment. The unified
+package is published beginning with Registry Stack v0.26.1. Existing
+standalone client packages remain available for earlier versions, but the
+release process does not publish new standalone versions once this package
+is active.
+
+The `casework` namespace is part of the unified package beginning with
+Registry Stack v0.30.0.
+
+## Casework notes
+
+The Casework module is for a trusted server host. Each call takes that request's
+bearer token and selected Casework profile; source-reading calls also take the
+selected source profile. The client does not retain them. Browsers should send
+only the host's session cookie. Claim, release, and decide consume the
+caller-filtered action returned on the item, including its exact route and
+`ifMatch` revision. Mutations require a caller-controlled idempotency key and
+are never retried automatically. After a lost response, use
+`recoverDecisionByKey` with the original key so recovery does not depend on the
+attempt identifier being received.
+
+## Documentation
+
+- [Client API reference](https://docs.registrystack.org/reference/client-api/)
+- [Repository](https://github.com/registrystack/registry-stack)
+- [Issue tracker](https://github.com/registrystack/registry-stack/issues)
+
+## License
+
+Apache-2.0