@registrystack/client 0.0.0 → 0.26.1

package/README.md

@@ -1,5 +1,27 @@
-# @registrystack/client
+# `@registrystack/client`
 
-This inert `0.0.0` release reserves the package identity for the unified Registry Stack client.
+One versioned Node.js package for the Discovery, Evidence, Relay, and Base
+Registry Engine client APIs in Registry Stack.
 
-Install a real Registry Stack release when version `0.26.1` or later is available. This bootstrap package contains no executable code.
+```sh
+npm install "@registrystack/client@<version>"
+```
+
+```js
+const { discovery, evidence, relay, breg } = require('@registrystack/client');
+
+const registry = new breg.BaseRegistryClient({
+  baseUrl: 'https://registry.example.invalid/',
+});
+```
+
+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.

package/breg/client.d.ts

@@ -0,0 +1,231 @@
+export type JsonScalar = string | number | boolean | null
+export type JsonValue = JsonScalar | ReadonlyArray<JsonValue> | { readonly [key: string]: JsonValue }
+export type JsonObject = { readonly [key: string]: JsonValue }
+/** An integer that satisfies `Number.isSafeInteger` and the option's documented bounds. */
+export type SafeInteger = number
+
+export interface PrivateJwk {
+  readonly kty: string
+  readonly kid: string
+  readonly alg: string
+  readonly [member: string]: JsonValue
+}
+
+export interface PrivateKeyJwtConfig {
+  tokenEndpoint: string
+  clientId: string
+  clientKey: PrivateJwk
+  audience?: string | null
+  assertionLifetimeSeconds?: SafeInteger | null
+  refreshMarginSeconds?: SafeInteger | null
+  requestTimeoutMilliseconds?: SafeInteger | null
+  connectTimeoutMilliseconds?: SafeInteger | null
+  userAgent?: string | null
+  trustedRootCertificates?: string | null
+}
+
+export type BaseRegistryAuthorization =
+  | { static: string }
+  | { privateKeyJwt: PrivateKeyJwtConfig }
+
+export interface BaseRegistryClientConfig {
+  baseUrl: string
+  authorization?: BaseRegistryAuthorization | null
+  requestTimeoutMilliseconds?: SafeInteger | null
+  connectTimeoutMilliseconds?: SafeInteger | null
+  maxResponseBytes?: SafeInteger | null
+  userAgent?: string | null
+  trustedRootCertificates?: string | null
+}
+
+export type RecordFormat = 'json' | 'json-ld'
+
+export interface RecordOptions {
+  select?: ReadonlyArray<string> | null
+  accessProfile?: string | null
+  format?: RecordFormat | null
+}
+
+export interface ListOptions extends RecordOptions {
+  top?: SafeInteger | null
+  filter?: string | null
+  orderby?: string | null
+  count?: boolean | null
+}
+
+export interface ListContinuation {
+  route: string
+  skiptoken: string
+  format: RecordFormat
+  accessProfile?: string | null
+  registryIdentifier: string
+  datasetIdentifier: string
+  entityTypeIdentifier: string
+}
+
+export interface RegistryRecord {
+  recordIdentifier: string
+  revisionIdentifier: string
+  domainData: Readonly<Record<string, JsonValue>>
+  readonly [member: string]: JsonValue | undefined
+}
+
+export interface RecordMetadata {
+  registryIdentifier: string
+  datasetIdentifier: string
+  entityTypeIdentifier: string
+  readonly [member: string]: JsonValue | undefined
+}
+
+export interface RecordEnvelope {
+  data: RegistryRecord
+  meta: RecordMetadata
+  '@context'?: string
+}
+
+export interface RecordPageInfo {
+  nextCursor: string | null
+  readonly [member: string]: JsonValue | undefined
+}
+
+export interface RecordCollection {
+  items: ReadonlyArray<RegistryRecord>
+  pageInfo: RecordPageInfo
+  meta: RecordMetadata
+  count?: SafeInteger
+  '@context'?: string
+}
+
+export interface ProbeStatus { status: string }
+
+export interface CompleteOutcome<T> {
+  kind: 'complete'
+  value: T
+  traceId: string
+  etag?: string
+  location?: string
+}
+
+export interface PageOutcome {
+  kind: 'complete'
+  value: RecordCollection
+  continuation?: ListContinuation
+  traceId: string
+  etag?: string
+}
+
+export interface RawOutcome {
+  kind: 'complete'
+  body: Buffer
+  mediaType: string
+  traceId: string
+  etag?: string
+}
+
+export interface PatchOperation {
+  op: 'add' | 'replace' | 'test'
+  field: string
+  value: JsonValue
+}
+
+export interface RemovePatchOperation {
+  op: 'remove'
+  field: string
+}
+
+export interface LifecycleReviewTarget {
+  entityIdentifier: string
+  recordIdentifier: string
+  operation: 'create' | 'patch'
+  baseRevision?: SafeInteger
+  before?: Readonly<Record<string, JsonValue>>
+  after: Readonly<Record<string, JsonValue>>
+}
+
+export interface LifecycleReview { targets: ReadonlyArray<LifecycleReviewTarget> }
+
+export interface LifecycleReceipt extends JsonObject {
+  id: string
+  revision: SafeInteger
+  snapshot: string
+  request: JsonObject
+}
+
+/** Opaque write authority selected from metadata fetched by this client source. */
+export declare class BRegCreateBinding {
+  private constructor()
+  private readonly __opaque: void
+}
+/** Opaque write authority selected from metadata fetched by this client source. */
+export declare class BRegPatchBinding {
+  private constructor()
+  private readonly __opaque: void
+}
+/** Opaque lifecycle authority selected from metadata fetched by this client source. */
+export declare class BRegLifecycleAuthority {
+  private constructor()
+  private readonly __opaque: void
+}
+
+/** Opaque executable action promoted from a metadata authority and one record. */
+export declare class BRegLifecycleAction {
+  private constructor()
+  private readonly __opaque: void
+  readonly operation: string
+  readonly stage: string | null
+  readonly href: string
+  readonly body: JsonObject
+  readonly review: LifecycleReview | null
+}
+
+/** Caller-filtered metadata bound to the exact client source that fetched it. */
+export declare class BRegMetadata {
+  private constructor()
+  private readonly __opaque: void
+  readonly registryIdentifier: string
+  readonly registryVersion: string
+  readonly registryRevision: string
+  readonly traceId: string
+  readonly etag: string | null
+  selectCreate(operationIdentifier: string, expectedProfile: string): BRegCreateBinding
+  selectPatch(operationIdentifier: string, expectedProfile: string): BRegPatchBinding
+  selectLifecycle(entityIdentifier: string, expectedProfile: string): BRegLifecycleAuthority
+}
+
+export interface BaseRegistryClientFailure extends Error {
+  readonly kind: string
+  readonly code?: string
+  readonly planRefusal?: string
+  readonly status?: number
+  readonly traceId?: string
+  readonly transportKind?: string
+  readonly tokenKind?: string
+}
+
+export declare class BaseRegistryClientError extends Error implements BaseRegistryClientFailure {
+  readonly kind: string
+  readonly code?: string
+  readonly planRefusal?: string
+  readonly status?: number
+  readonly traceId?: string
+  readonly transportKind?: string
+  readonly tokenKind?: string
+}
+
+export declare class BaseRegistryClient {
+  constructor(config: BaseRegistryClientConfig)
+  health(): Promise<CompleteOutcome<ProbeStatus>>
+  ready(): Promise<CompleteOutcome<ProbeStatus>>
+  openapi(accessProfile?: string | null): Promise<RawOutcome>
+  registryMetadata(accessProfile?: string | null): Promise<RawOutcome>
+  registryContract(accessProfile?: string | null): Promise<BRegMetadata>
+  entitySchema(entityIdentifier: string, accessProfile?: string | null): Promise<RawOutcome>
+  getRecord(entityRoute: string, recordIdentifier: string, options?: RecordOptions | null): Promise<CompleteOutcome<RecordEnvelope>>
+  listRecords(entityRoute: string, options?: ListOptions | null): Promise<PageOutcome>
+  continueList(continuation: ListContinuation): Promise<PageOutcome>
+  lookupRecord(entityRoute: string, selector: string, values?: JsonObject | null, options?: RecordOptions | null): Promise<CompleteOutcome<RecordEnvelope>>
+  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>
+  executeLifecycleAction(action: BRegLifecycleAction, idempotencyKey: string): Promise<CompleteOutcome<LifecycleReceipt>>
+}

package/breg/client.js

@@ -0,0 +1,185 @@
+'use strict';
+
+const { types: { isProxy } } = require('node:util');
+const native = require('./index');
+
+const MAX_JSON_DEPTH = 128;
+const MAX_JSON_NODES = 100_000;
+const MAX_JSON_STRING_BYTES = 4 * 1024 * 1024;
+
+class BaseRegistryClientError extends Error {
+  constructor(envelope) {
+    super(envelope.message);
+    this.name = 'BaseRegistryClientError';
+    this.kind = envelope.kind;
+    for (const field of ['code', 'planRefusal', 'status', 'traceId', 'transportKind', 'tokenKind']) {
+      if (envelope[field] !== undefined && envelope[field] !== null) this[field] = envelope[field];
+    }
+  }
+}
+
+function normalize(error, fallbackKind) {
+  if (error instanceof BaseRegistryClientError) return error;
+  if (error instanceof Error && typeof error.message === 'string') {
+    try {
+      const envelope = JSON.parse(error.message);
+      if (envelope && typeof envelope === 'object' && typeof envelope.kind === 'string') {
+        return new BaseRegistryClientError(envelope);
+      }
+    } catch {
+      // napi argument conversion errors are not mapped Rust error envelopes.
+    }
+  }
+  if (fallbackKind) {
+    return new BaseRegistryClientError({
+      kind: fallbackKind,
+      message: fallbackKind === 'configuration'
+        ? 'Base Registry client configuration is invalid'
+        : 'Base Registry client arguments are invalid',
+    });
+  }
+  return error;
+}
+
+function inputError(kind) {
+  return new BaseRegistryClientError({
+    kind,
+    message: kind === 'configuration'
+      ? 'Base Registry client configuration is invalid'
+      : 'Base Registry client arguments are invalid',
+  });
+}
+
+function chargeString(value, budget, kind) {
+  budget.stringBytes += Buffer.byteLength(value, 'utf8');
+  if (budget.stringBytes > MAX_JSON_STRING_BYTES) throw inputError(kind);
+}
+
+function cloneJson(value, budget, depth, kind) {
+  if (depth > MAX_JSON_DEPTH) throw inputError(kind);
+  budget.nodes += 1;
+  if (budget.nodes > MAX_JSON_NODES) throw inputError(kind);
+  if (value === null || typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    chargeString(value, budget, kind);
+    return value;
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw inputError(kind);
+    return value;
+  }
+  if (value === undefined || typeof value !== 'object' || isProxy(value)) throw inputError(kind);
+
+  const prototype = Object.getPrototypeOf(value);
+  const array = Array.isArray(value);
+  if (array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) {
+    throw inputError(kind);
+  }
+  if (budget.active.has(value)) throw inputError(kind);
+  budget.active.add(value);
+  try {
+    const keys = Reflect.ownKeys(value);
+    if (keys.some((key) => typeof key === 'symbol')) throw inputError(kind);
+    if (array) {
+      if (value.length + budget.nodes > MAX_JSON_NODES) throw inputError(kind);
+      const clone = new Array(value.length);
+      let count = 0;
+      for (const key of keys) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !Object.hasOwn(descriptor, 'value')) throw inputError(kind);
+        if (key === 'length') continue;
+        chargeString(key, budget, kind);
+        const index = Number(key);
+        if (!descriptor.enumerable || !Number.isInteger(index) || index < 0
+          || index >= value.length || String(index) !== key) throw inputError(kind);
+        clone[index] = cloneJson(descriptor.value, budget, depth + 1, kind);
+        count += 1;
+      }
+      if (count !== value.length) throw inputError(kind);
+      return clone;
+    }
+    const clone = Object.create(null);
+    for (const key of keys) {
+      chargeString(key, budget, kind);
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor || !Object.hasOwn(descriptor, 'value')) throw inputError(kind);
+      if (!descriptor.enumerable) continue;
+      clone[key] = cloneJson(descriptor.value, budget, depth + 1, kind);
+    }
+    return clone;
+  } finally {
+    budget.active.delete(value);
+  }
+}
+
+function sanitizeArguments(args, jsonIndexes, requiredIndexes) {
+  const budget = { nodes: 0, stringBytes: 0, active: new WeakSet() };
+  return args.map((value, index) => {
+    if (!jsonIndexes.has(index)) return value;
+    if (value === undefined || value === null) {
+      if (requiredIndexes.has(index)) throw inputError('invalid_request');
+      return value;
+    }
+    return cloneJson(value, budget, 0, 'invalid_request');
+  });
+}
+
+function wrapAsync(name, jsonIndexes = [], requiredIndexes = []) {
+  const original = native.BaseRegistryClient.prototype[name];
+  native.BaseRegistryClient.prototype[name] = function (...args) {
+    try {
+      const sanitized = sanitizeArguments(args, new Set(jsonIndexes), new Set(requiredIndexes));
+      return original.apply(this, sanitized).catch((error) => { throw normalize(error); });
+    } catch (error) {
+      throw normalize(error, 'invalid_request');
+    }
+  };
+}
+
+for (const [method, jsonIndexes, requiredIndexes] of [
+  ['health'], ['ready'], ['openapi'], ['registryMetadata'], ['registryContract'], ['entitySchema'],
+  ['getRecord', [2]], ['listRecords', [1]], ['continueList', [0], [0]],
+  ['lookupRecord', [2, 3]], ['createRecord', [1], [1]],
+  ['patchRecord', [3], [3]], ['executeLifecycleAction'],
+]) wrapAsync(method, jsonIndexes, requiredIndexes);
+
+const lifecycleActions = native.BaseRegistryClient.prototype.lifecycleActions;
+native.BaseRegistryClient.prototype.lifecycleActions = function (...args) {
+  try {
+    const sanitized = sanitizeArguments(args, new Set([1]), new Set([1]));
+    return lifecycleActions.apply(this, sanitized);
+  } catch (error) {
+    throw normalize(error, 'invalid_request');
+  }
+};
+
+for (const name of ['selectCreate', 'selectPatch', 'selectLifecycle']) {
+  const original = native.BRegMetadata.prototype[name];
+  native.BRegMetadata.prototype[name] = function (...args) {
+    try {
+      return original.apply(this, args);
+    } catch (error) {
+      throw normalize(error, 'invalid_request');
+    }
+  };
+}
+
+class BaseRegistryClient extends native.BaseRegistryClient {
+  constructor(config) {
+    try {
+      super(cloneJson(config, { nodes: 0, stringBytes: 0, active: new WeakSet() }, 0, 'configuration'));
+    } catch (error) {
+      throw normalize(error, 'configuration');
+    }
+  }
+}
+
+module.exports = {
+  BaseRegistryClient,
+  BaseRegistryClientError,
+  BRegMetadata: native.BRegMetadata,
+  BRegCreateBinding: native.BRegCreateBinding,
+  BRegPatchBinding: native.BRegPatchBinding,
+  BRegLifecycleAuthority: native.BRegLifecycleAuthority,
+  BRegLifecycleAction: native.BRegLifecycleAction,
+};

package/breg/index.d.ts

@@ -0,0 +1,79 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+export declare class BaseRegistryClient {
+  constructor(config: any)
+  health(): Promise<CompleteOutcome>
+  ready(): Promise<CompleteOutcome>
+  openapi(accessProfile?: string | undefined | null): Promise<RawOutcome>
+  registryMetadata(accessProfile?: string | undefined | null): Promise<RawOutcome>
+  registryContract(accessProfile?: string | undefined | null): Promise<BRegMetadata>
+  entitySchema(entityIdentifier: string, accessProfile?: string | undefined | null): Promise<RawOutcome>
+  getRecord(entityRoute: string, recordIdentifier: string, options?: any | undefined | null): Promise<CompleteOutcome>
+  listRecords(entityRoute: string, options?: any | undefined | null): Promise<PageOutcome>
+  continueList(value: any): Promise<PageOutcome>
+  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>
+  lifecycleActions(authority: BRegLifecycleAuthority, record: any, formatValue?: string | undefined | null): Array<BRegLifecycleAction>
+  executeLifecycleAction(action: BRegLifecycleAction, idempotencyKey: string): Promise<CompleteOutcome>
+}
+
+export declare class BRegCreateBinding {
+
+}
+export type CreateBinding = BRegCreateBinding
+
+export declare class BRegLifecycleAction {
+  get operation(): string
+  get stage(): string | null
+  get href(): string
+  get body(): any
+  get review(): any | null
+}
+export type LifecycleAction = BRegLifecycleAction
+
+export declare class BRegLifecycleAuthority {
+
+}
+export type LifecycleAuthority = BRegLifecycleAuthority
+
+export declare class BRegMetadata {
+  get registryIdentifier(): string
+  get registryVersion(): string
+  get registryRevision(): string
+  get traceId(): string
+  get etag(): string | null
+  selectCreate(operationIdentifier: string, expectedProfile: string): BRegCreateBinding
+  selectPatch(operationIdentifier: string, expectedProfile: string): BRegPatchBinding
+  selectLifecycle(entityIdentifier: string, expectedProfile: string): BRegLifecycleAuthority
+}
+export type Metadata = BRegMetadata
+
+export declare class BRegPatchBinding {
+
+}
+export type PatchBinding = BRegPatchBinding
+
+export interface CompleteOutcome {
+  kind: string
+  value: any
+  traceId: string
+  etag?: string
+  location?: string
+}
+
+export interface PageOutcome {
+  kind: string
+  value: any
+  continuation?: any
+  traceId: string
+  etag?: string
+}
+
+export interface RawOutcome {
+  kind: string
+  body: Buffer
+  mediaType: string
+  traceId: string
+  etag?: string
+}

package/breg/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('../native').load('breg');