registrystack / registrystack/registry-stack

Client docs: Node change-request example, immediate-action metadata, envelope shapes, caching, compatibility

Open
#1,022 0 comments 0 reactions 0 assignees View on GitHub
agent-ready area:breg area:casework area:docs criticality:p3 documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.