registrystack / registrystack/registry-stack
Client docs: Node change-request example, immediate-action metadata, envelope shapes, caching, compatibility
- Dominant language
- Rust
- Stars
- 2
- Forks
- 0
- Avg merge
- 2h 57m
- Merged PRs (30d)
- 128
Description
## What Happened
Verified gaps in the public client documentation (`reference/client-api`, the client READMEs) after reading three real consumers of `@registrystack/client`:
1. **No worked Node example for a change request.** The lifecycle section is prose plus a method table. The only end-to-end walkthrough (`tutorials/review-registry-changes`) is curl. Consumers wanting create, submit, review, apply from Node have nothing to copy.
2. **Immediate-action metadata contract undocumented.** `BRegImmediateActionDescriptor.inputs[].apiName`, `referenceInputs`, `targetConditionsPath` and when to call `actionTargetConditions` appear in the types and nowhere in the docs.
3. **Envelope shapes not stated as a contract.** Single reads nest under `data`, list items are bare, receipts are minimal; Casework has a bare `WorkItem`, `MutationResponse { item, attempt }`, and `HostedTerminalResult`. A short shape table per product would stop consumers guessing.
4. **No caching guidance for `registryContract`.** The call is an unconditional GET every time and the OpenFn adaptor calls it per operation. `BRegMetadata.etag` is exposed but nothing says how to use it. One paragraph recommending a caller-side cache keyed by profile and ETag is enough until conditional GET is confirmed on the server.
5. **No client-versus-server compatibility statement.** `security/support-window` covers binaries. Nothing maps an `@registrystack/client` version to the server versions it is tested against.
## Expected Behavior
One docs change covering the five items, following `docs/site/AGENTS.md` and the style guide, with the Node example replayed against a `bregctl dev` session so it can join the reader gate.
## Environment
Docs at 0.30.0.
Triage: later, documentation only.
Contributor guide
Research direction
Start with docs/site/AGENTS.md and the style guide, then review reference/client-api, the client READMEs, tutorials/review-registry-changes, and security/support-window. Use the client types and a bregctl dev session to shape the Node example and document the five requested contracts; done means the example is replayed and joins the reader gate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100