@registrystack/client 0.27.0 → 0.29.0

package/README.md

@@ -1,12 +1,21 @@
-# `@registrystack/client`
+# @registrystack/client
 
 One versioned Node.js package for the Discovery, Evidence, Relay, and Base
 Registry Engine 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 four native
+bindings.
+
+## Usage
+
 ```js
 const { discovery, evidence, relay, breg } = require('@registrystack/client');
 
@@ -15,6 +24,20 @@ const registry = new breg.BaseRegistryClient({
 });
 ```
 
+## 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.
+
+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,13 +60,33 @@ 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.
+## Base Registry Engine notes
+
+`breg.BaseRegistryClient.registryContract()` returns caller-filtered
+`operations` with typed 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.
+
+## 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

package/breg/client.d.ts

@@ -151,6 +151,129 @@ export interface LifecycleReceipt extends JsonObject {
   request: JsonObject
 }
 
+/** Exact validated JSON text, serialized before conversion to JavaScript numbers.
+ * Decode with a lossless JSON library if inspecting values outside the safe integer range.
+ * Decimal fields remain fixed-scale JSON strings. */
+export interface JsonOutcome {
+  kind: 'complete'
+  valueJson: string
+  continuation?: ListContinuation
+  traceId: string
+  etag?: string
+  location?: string
+}
+
+export interface BRegFieldDescriptor {
+  readonly id: string
+  readonly apiName: string
+  readonly label: string
+  readonly schemaJson: string
+  readonly required: boolean
+  readonly nullable: boolean
+  readonly readOnly: boolean
+  readonly removable: boolean
+  readonly referenceTargetEntity: string | null
+}
+export interface BRegQueryField {
+  readonly id: string
+  readonly apiName: string
+  readonly operators?: ReadonlyArray<string>
+  readonly directions?: ReadonlyArray<string>
+}
+export interface BRegQueryDescriptor {
+  readonly kind: string
+  readonly selectableFields: ReadonlyArray<BRegQueryField>
+  readonly filterableFields: ReadonlyArray<BRegQueryField>
+  readonly sortableFields: ReadonlyArray<BRegQueryField>
+  readonly allowCount: boolean
+  readonly defaultPageSize: number
+  readonly maxPageSize: number
+  readonly maxFilterClauses: number
+  readonly maxInValues: number
+  readonly pagination: { readonly parameter: string; readonly responsePath: string; readonly exclusive: boolean }
+  readonly temporal: JsonObject | null
+}
+export interface BRegOperationDescriptor {
+  readonly id: string
+  readonly method: string
+  readonly path: string
+  readonly kind: string
+  readonly sourceEntity: string
+  readonly responseEntity: string
+  readonly accessProfile: string
+  readonly entityLabel: string
+  readonly titleFields: ReadonlyArray<string>
+  readonly requiredCapabilities: ReadonlyArray<string>
+  readonly fields: ReadonlyArray<BRegFieldDescriptor>
+  readonly readableFields: ReadonlyArray<string>
+  readonly createWritableFields: ReadonlyArray<string>
+  readonly patchWritableFields: ReadonlyArray<string>
+  readonly query: BRegQueryDescriptor | null
+  readonly request: {
+    readonly fieldNames: string | null
+    readonly queryParameters: ReadonlyArray<string>
+    readonly body: string | null
+    readonly contentType: string | null
+    readonly schemaJson: string | null
+    readonly idempotencyKeyRequired: boolean | null
+    readonly ifMatchRequired: boolean | null
+    readonly mutationSemantics: string | null
+    readonly patchPathPrefix: string | null
+    readonly patchOperations: ReadonlyArray<string>
+    readonly removeSemantics: string | null
+  }
+}
+
+export type BRegAttachmentVerificationStatus = 'notRequired' | 'pending' | 'approved' | 'rejected'
+
+export type BRegAttachmentClassification = 'public' | 'internal' | 'restricted'
+
+/** Engine-owned state of one filled slot, read from a record's domain data. */
+export interface BRegAttachmentState {
+  readonly slotIdentifier: string
+  readonly proposalVersion: SafeInteger
+  readonly erased: boolean
+  readonly byteSize: SafeInteger
+  readonly sha256: string
+  readonly contentType: string | null
+  readonly uploadedAt: string | null
+  readonly uploadedBy: string | null
+  readonly verificationStatus: BRegAttachmentVerificationStatus | null
+}
+
+/** What one record projection says about one slot. */
+export type BRegAttachmentSlotValue =
+  | { readonly kind: 'not_selected'; readonly value: null }
+  | { readonly kind: 'empty'; readonly value: null }
+  | { readonly kind: 'filled'; readonly value: BRegAttachmentState }
+
+/** Opaque bytes already accepted by one slot's served upload policy. */
+export declare class BRegAttachmentUpload {
+  private constructor()
+  private readonly __opaque: void
+  readonly contentType: string
+  readonly byteSize: SafeInteger
+}
+
+/** Opaque governed attachment slot selected from metadata fetched by this client source. */
+export declare class BRegAttachmentSlot {
+  private constructor()
+  private readonly __opaque: void
+  readonly slotIdentifier: string
+  readonly entityIdentifier: string
+  readonly accessProfile: string
+  readonly requiredForSubmit: boolean
+  readonly maximumBytes: SafeInteger
+  readonly contentTypes: ReadonlyArray<string>
+  readonly classification: BRegAttachmentClassification
+  readonly canDownload: boolean
+  readonly canUpload: boolean
+  readonly canRemove: boolean
+  acceptsContentType(contentType: string): boolean
+  prepareUpload(contentType: string, body: Buffer): BRegAttachmentUpload
+  valueIn(record: RecordEnvelope, format?: RecordFormat | null): BRegAttachmentSlotValue
+}
+
 /** Opaque write authority selected from metadata fetched by this client source. */
 export declare class BRegCreateBinding {
   private constructor()
@@ -169,11 +292,14 @@ export declare class BRegLifecycleAuthority {
 
 /** Opaque executable action promoted from a metadata authority and one record. */
 export declare class BRegLifecycleAction {
+  withReason(reason: string): BRegLifecycleAction
   private constructor()
   private readonly __opaque: void
   readonly operation: string
   readonly stage: string | null
   readonly href: string
+  readonly bodyJson: string
+  readonly reviewJson: string | null
   readonly body: JsonObject
   readonly review: LifecycleReview | null
 }
@@ -182,6 +308,7 @@ export declare class BRegLifecycleAction {
 export declare class BRegMetadata {
   private constructor()
   private readonly __opaque: void
+  readonly operations: ReadonlyArray<BRegOperationDescriptor>
   readonly registryIdentifier: string
   readonly registryVersion: string
   readonly registryRevision: string
@@ -190,6 +317,7 @@ export declare class BRegMetadata {
   selectCreate(operationIdentifier: string, expectedProfile: string): BRegCreateBinding
   selectPatch(operationIdentifier: string, expectedProfile: string): BRegPatchBinding
   selectLifecycle(entityIdentifier: string, expectedProfile: string): BRegLifecycleAuthority
+  selectAttachments(entityIdentifier: string, expectedProfile: string): ReadonlyArray<BRegAttachmentSlot>
 }
 
 export interface BaseRegistryClientFailure extends Error {
@@ -227,5 +355,18 @@ export declare class BaseRegistryClient {
   createRecord(binding: BRegCreateBinding, data: JsonObject, idempotencyKey: string, format?: RecordFormat | null): Promise<CompleteOutcome<RecordEnvelope>>
   patchRecord(binding: BRegPatchBinding, recordIdentifier: string, etag: string, operations: ReadonlyArray<PatchOperation | RemovePatchOperation>, idempotencyKey: string, format?: RecordFormat | null): Promise<CompleteOutcome<RecordEnvelope>>
   lifecycleActions(authority: BRegLifecycleAuthority, record: RecordEnvelope, format?: RecordFormat | null): ReadonlyArray<BRegLifecycleAction>
+  uploadAttachment(slot: BRegAttachmentSlot, recordIdentifier: string, etag: string, upload: BRegAttachmentUpload, idempotencyKey: string, format?: RecordFormat | null): Promise<CompleteOutcome<RecordEnvelope>>
+  downloadAttachment(slot: BRegAttachmentSlot, recordIdentifier: string, proposalVersion: SafeInteger): Promise<RawOutcome>
+  deleteAttachment(slot: BRegAttachmentSlot, recordIdentifier: string, etag: string, idempotencyKey: string, format?: RecordFormat | null): Promise<CompleteOutcome<RecordEnvelope>>
+  getRecordJson(entityRoute: string, recordIdentifier: string, options?: RecordOptions | null): Promise<JsonOutcome>
+  listRecordsJson(entityRoute: string, options?: ListOptions | null): Promise<JsonOutcome>
+  continueListJson(continuation: ListContinuation): Promise<JsonOutcome>
+  lookupRecordJson(entityRoute: string, selector: string, valuesJson?: string | null, options?: RecordOptions | null): Promise<JsonOutcome>
+  createRecordJson(binding: BRegCreateBinding, dataJson: string, idempotencyKey: string, format?: RecordFormat | null): Promise<JsonOutcome>
+  patchRecordJson(binding: BRegPatchBinding, recordIdentifier: string, etag: string, operationsJson: string, idempotencyKey: string, format?: RecordFormat | null): Promise<JsonOutcome>
+  uploadAttachmentJson(slot: BRegAttachmentSlot, recordIdentifier: string, etag: string, upload: BRegAttachmentUpload, idempotencyKey: string, format?: RecordFormat | null): Promise<JsonOutcome>
+  deleteAttachmentJson(slot: BRegAttachmentSlot, recordIdentifier: string, etag: string, idempotencyKey: string, format?: RecordFormat | null): Promise<JsonOutcome>
+  lifecycleActionsJson(authority: BRegLifecycleAuthority, recordJson: string, format?: RecordFormat | null): ReadonlyArray<BRegLifecycleAction>
+  executeLifecycleActionJson(action: BRegLifecycleAction, idempotencyKey: string): Promise<JsonOutcome>
   executeLifecycleAction(action: BRegLifecycleAction, idempotencyKey: string): Promise<CompleteOutcome<LifecycleReceipt>>
 }

package/breg/client.js

@@ -141,8 +141,28 @@ for (const [method, jsonIndexes, requiredIndexes] of [
   ['getRecord', [2]], ['listRecords', [1]], ['continueList', [0], [0]],
   ['lookupRecord', [2, 3]], ['createRecord', [1], [1]],
   ['patchRecord', [3], [3]], ['executeLifecycleAction'],
+  ['uploadAttachment'], ['downloadAttachment'], ['deleteAttachment'],
+  ['getRecordJson', [2]], ['listRecordsJson', [1]], ['continueListJson', [0], [0]],
+  ['lookupRecordJson', [3]], ['createRecordJson'], ['patchRecordJson'], ['executeLifecycleActionJson'],
+  ['uploadAttachmentJson'], ['deleteAttachmentJson'],
 ]) wrapAsync(method, jsonIndexes, requiredIndexes);
 
+const withReason = native.BRegLifecycleAction.prototype.withReason;
+native.BRegLifecycleAction.prototype.withReason = function (reason) {
+  try {
+    if (typeof reason !== 'string' || !reason.isWellFormed()) throw inputError('invalid_request');
+    return withReason.call(this, reason);
+  } catch (error) {
+    throw normalize(error, 'invalid_request');
+  }
+};
+
+const lifecycleActionsJson = native.BaseRegistryClient.prototype.lifecycleActionsJson;
+native.BaseRegistryClient.prototype.lifecycleActionsJson = function (...args) {
+  try { return lifecycleActionsJson.apply(this, args); }
+  catch (error) { throw normalize(error, 'invalid_request'); }
+};
+
 const lifecycleActions = native.BaseRegistryClient.prototype.lifecycleActions;
 native.BaseRegistryClient.prototype.lifecycleActions = function (...args) {
   try {
@@ -153,7 +173,27 @@ native.BaseRegistryClient.prototype.lifecycleActions = function (...args) {
   }
 };
 
-for (const name of ['selectCreate', 'selectPatch', 'selectLifecycle']) {
+const valueIn = native.BRegAttachmentSlot.prototype.valueIn;
+native.BRegAttachmentSlot.prototype.valueIn = function (...args) {
+  try {
+    return valueIn.apply(this, sanitizeArguments(args, new Set([0]), new Set([0])));
+  } catch (error) {
+    throw normalize(error, 'invalid_request');
+  }
+};
+
+for (const name of ['prepareUpload', 'acceptsContentType']) {
+  const original = native.BRegAttachmentSlot.prototype[name];
+  native.BRegAttachmentSlot.prototype[name] = function (...args) {
+    try {
+      return original.apply(this, args);
+    } catch (error) {
+      throw normalize(error, 'invalid_request');
+    }
+  };
+}
+
+for (const name of ['selectCreate', 'selectPatch', 'selectLifecycle', 'selectAttachments']) {
   const original = native.BRegMetadata.prototype[name];
   native.BRegMetadata.prototype[name] = function (...args) {
     try {
@@ -182,4 +222,6 @@ module.exports = {
   BRegPatchBinding: native.BRegPatchBinding,
   BRegLifecycleAuthority: native.BRegLifecycleAuthority,
   BRegLifecycleAction: native.BRegLifecycleAction,
+  BRegAttachmentSlot: native.BRegAttachmentSlot,
+  BRegAttachmentUpload: native.BRegAttachmentUpload,
 };

package/breg/index.d.ts

@@ -14,16 +14,67 @@ export declare class BaseRegistryClient {
   lookupRecord(entityRoute: string, selector: string, values?: any | undefined | null, options?: any | undefined | null): Promise<CompleteOutcome>
   createRecord(binding: BRegCreateBinding, data: any, idempotencyKey: string, formatValue?: string | undefined | null): Promise<CompleteOutcome>
   patchRecord(binding: BRegPatchBinding, recordIdentifier: string, etag: string, operations: any, idempotencyKey: string, formatValue?: string | undefined | null): Promise<CompleteOutcome>
+  /**
+   * Replace one governed attachment slot with exact bytes. The prepared
+   * upload already satisfies the slot's served size and content-type policy.
+   */
+  uploadAttachment(slot: BRegAttachmentSlot, recordIdentifier: string, etag: string, upload: BRegAttachmentUpload, idempotencyKey: string, formatValue?: string | undefined | null): Promise<CompleteOutcome>
+  /** Read the exact bytes one governed slot holds for one proposal version. */
+  downloadAttachment(slot: BRegAttachmentSlot, recordIdentifier: string, proposalVersion: number): Promise<RawOutcome>
+  /** Empty one governed attachment slot. */
+  deleteAttachment(slot: BRegAttachmentSlot, recordIdentifier: string, etag: string, idempotencyKey: string, formatValue?: string | undefined | null): Promise<CompleteOutcome>
   lifecycleActions(authority: BRegLifecycleAuthority, record: any, formatValue?: string | undefined | null): Array<BRegLifecycleAction>
   executeLifecycleAction(action: BRegLifecycleAction, idempotencyKey: string): Promise<CompleteOutcome>
+  getRecordJson(entityRoute: string, recordIdentifier: string, options?: any | undefined | null): Promise<JsonOutcome>
+  listRecordsJson(entityRoute: string, options?: any | undefined | null): Promise<JsonOutcome>
+  continueListJson(value: any): Promise<JsonOutcome>
+  lookupRecordJson(entityRoute: string, selector: string, valuesJson?: string | undefined | null, options?: any | undefined | null): Promise<JsonOutcome>
+  createRecordJson(binding: BRegCreateBinding, dataJson: string, idempotencyKey: string, formatValue?: string | undefined | null): Promise<JsonOutcome>
+  patchRecordJson(binding: BRegPatchBinding, recordIdentifier: string, etag: string, operationsJson: string, idempotencyKey: string, formatValue?: string | undefined | null): Promise<JsonOutcome>
+  uploadAttachmentJson(slot: BRegAttachmentSlot, recordIdentifier: string, etag: string, upload: BRegAttachmentUpload, idempotencyKey: string, formatValue?: string | undefined | null): Promise<JsonOutcome>
+  deleteAttachmentJson(slot: BRegAttachmentSlot, recordIdentifier: string, etag: string, idempotencyKey: string, formatValue?: string | undefined | null): Promise<JsonOutcome>
+  lifecycleActionsJson(authority: BRegLifecycleAuthority, recordJson: string, formatValue?: string | undefined | null): Array<BRegLifecycleAction>
+  executeLifecycleActionJson(action: BRegLifecycleAction, idempotencyKey: string): Promise<JsonOutcome>
 }
 
+/** Opaque governed attachment slot selected from metadata fetched by this client source. */
+export declare class BRegAttachmentSlot {
+  get slotIdentifier(): string
+  get entityIdentifier(): string
+  get accessProfile(): string
+  get requiredForSubmit(): boolean
+  /** Largest body the served slot policy accepts, in bytes. */
+  get maximumBytes(): number
+  get contentTypes(): Array<string>
+  /** Authored sensitivity of this slot's content. */
+  get classification(): string
+  get canDownload(): boolean
+  get canUpload(): boolean
+  get canRemove(): boolean
+  acceptsContentType(contentType: string): boolean
+  /** Bind exact bytes to this slot. Refusals happen here, before any request. */
+  prepareUpload(contentType: string, body: Buffer): BRegAttachmentUpload
+  /** Read this slot's engine-owned state out of one Registry Record envelope. */
+  valueIn(record: any, formatValue?: string | undefined | null): any
+}
+export type AttachmentSlot = BRegAttachmentSlot
+
+/** Opaque bytes already accepted by one slot's served upload policy. */
+export declare class BRegAttachmentUpload {
+  get contentType(): string
+  get byteSize(): number
+}
+export type AttachmentUpload = BRegAttachmentUpload
+
 export declare class BRegCreateBinding {
 
 }
 export type CreateBinding = BRegCreateBinding
 
 export declare class BRegLifecycleAction {
+  withReason(reason: string): BRegLifecycleAction
+  get bodyJson(): string
+  get reviewJson(): string | null
   get operation(): string
   get stage(): string | null
   get href(): string
@@ -38,6 +89,8 @@ export declare class BRegLifecycleAuthority {
 export type LifecycleAuthority = BRegLifecycleAuthority
 
 export declare class BRegMetadata {
+  /** Caller-filtered inert descriptors. Selectors below remain the only authority constructors. */
+  get operations(): any
   get registryIdentifier(): string
   get registryVersion(): string
   get registryRevision(): string
@@ -46,6 +99,7 @@ export declare class BRegMetadata {
   selectCreate(operationIdentifier: string, expectedProfile: string): BRegCreateBinding
   selectPatch(operationIdentifier: string, expectedProfile: string): BRegPatchBinding
   selectLifecycle(entityIdentifier: string, expectedProfile: string): BRegLifecycleAuthority
+  selectAttachments(entityIdentifier: string, expectedProfile: string): Array<BRegAttachmentSlot>
 }
 export type Metadata = BRegMetadata
 
@@ -62,6 +116,16 @@ export interface CompleteOutcome {
   location?: string
 }
 
+/** Validated product result serialized before the JavaScript number boundary. */
+export interface JsonOutcome {
+  kind: string
+  valueJson: string
+  continuation?: any
+  traceId: string
+  etag?: string
+  location?: string
+}
+
 export interface PageOutcome {
   kind: string
   value: any

package/native.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const PACKAGE_VERSION = '0.27.0';
+const PACKAGE_VERSION = '0.29.0';
 const PRODUCTS = new Set(['discovery', 'evidence', 'relay', 'breg']);
 
 function target() {

package/package.json

@@ -1,15 +1,28 @@
 {
   "name": "@registrystack/client",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Unified Node.js client for Registry Stack products.",
   "license": "Apache-2.0",
+  "homepage": "https://docs.registrystack.org/reference/client-api/",
+  "bugs": {
+    "url": "https://github.com/registrystack/registry-stack/issues"
+  },
+  "keywords": [
+    "registry",
+    "registrystack",
+    "discovery",
+    "evidence",
+    "relay",
+    "breg"
+  ],
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/registrystack/registry-stack"
+    "url": "https://github.com/registrystack/registry-stack",
+    "directory": "crates/registry-stack-client-node"
   },
   "main": "index.js",
   "types": "index.d.ts",
@@ -42,8 +55,8 @@
     "typescript": "6.0.3"
   },
   "optionalDependencies": {
-    "@registrystack/client-darwin-arm64": "0.27.0",
-    "@registrystack/client-linux-arm64-gnu": "0.27.0",
-    "@registrystack/client-linux-x64-gnu": "0.27.0"
+    "@registrystack/client-darwin-arm64": "0.29.0",
+    "@registrystack/client-linux-arm64-gnu": "0.29.0",
+    "@registrystack/client-linux-x64-gnu": "0.29.0"
   }
 }