@registrystack/client 0.28.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,29 +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.
-
-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, 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

@@ -224,6 +224,56 @@ export interface BRegOperationDescriptor {
   }
 }
 
+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()
@@ -242,6 +292,7 @@ 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
@@ -266,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 {
@@ -303,12 +355,17 @@ 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,10 +141,22 @@ 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); }
@@ -161,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 {
@@ -190,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,6 +14,15 @@ 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>
@@ -22,16 +31,48 @@ export declare class BaseRegistryClient {
   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
@@ -58,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
 

package/native.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const PACKAGE_VERSION = '0.28.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.28.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.28.0",
-    "@registrystack/client-linux-arm64-gnu": "0.28.0",
-    "@registrystack/client-linux-x64-gnu": "0.28.0"
+    "@registrystack/client-darwin-arm64": "0.29.0",
+    "@registrystack/client-linux-arm64-gnu": "0.29.0",
+    "@registrystack/client-linux-x64-gnu": "0.29.0"
   }
 }