@registrystack/client 0.28.0 → 0.30.0

package/breg/client.js

@@ -12,7 +12,7 @@ class BaseRegistryClientError extends Error {
     super(envelope.message);
     this.name = 'BaseRegistryClientError';
     this.kind = envelope.kind;
-    for (const field of ['code', 'planRefusal', 'status', 'traceId', 'transportKind', 'tokenKind']) {
+    for (const field of ['code', 'planRefusal', 'refusalCode', 'status', 'traceId', 'transportKind', 'tokenKind']) {
       if (envelope[field] !== undefined && envelope[field] !== null) this[field] = envelope[field];
     }
   }
@@ -65,7 +65,8 @@ function cloneJson(value, budget, depth, kind) {
     return value;
   }
   if (typeof value === 'number') {
-    if (!Number.isFinite(value)) throw inputError(kind);
+    if (!Number.isFinite(value)
+      || (Number.isInteger(value) && !Number.isSafeInteger(value))) throw inputError(kind);
     return value;
   }
   if (value === undefined || typeof value !== 'object' || isProxy(value)) throw inputError(kind);
@@ -138,13 +139,95 @@ function wrapAsync(name, jsonIndexes = [], requiredIndexes = []) {
 
 for (const [method, jsonIndexes, requiredIndexes] of [
   ['health'], ['ready'], ['openapi'], ['registryMetadata'], ['registryContract'], ['entitySchema'],
+  ['recordRevisions'], ['getRecordRevision', [3]],
   ['getRecord', [2]], ['listRecords', [1]], ['continueList', [0], [0]],
+  ['getGeoJsonRecord', [2]], ['listGeoJsonRecords', [1]], ['continueGeoJsonList', [0], [0]],
+  ['listCurrentRecords', [1]], ['continueCurrentList', [0], [0]],
+  ['listRecordsAsOf', [1], [1]], ['continueAsOfList', [0], [0]],
+  ['listSnapshotRecords', [1]], ['continueSnapshotList', [0], [0]],
+  ['listRelationshipRecords', [3]], ['continueRelationshipList', [0], [0]],
   ['lookupRecord', [2, 3]], ['createRecord', [1], [1]],
-  ['patchRecord', [3], [3]], ['executeLifecycleAction'],
+  ['actionTargetConditions', [1], [1]], ['invokeAction', [1], [1]],
+  ['executeRecoveredCreate'],
+  ['patchRecord', [3], [3]], ['batchRecords', [1], [1]], ['tombstoneRecord'],
+  ['executeLifecycleAction'],
+  ['executeRecoveredLifecycleAction'],
+  ['uploadAttachment'], ['downloadAttachment'], ['deleteAttachment'],
   ['getRecordJson', [2]], ['listRecordsJson', [1]], ['continueListJson', [0], [0]],
+  ['getGeoJsonRecordJson', [2]], ['listGeoJsonRecordsJson', [1]],
+  ['continueGeoJsonListJson', [0], [0]],
+  ['listCurrentRecordsJson', [1]], ['continueCurrentListJson', [0], [0]],
+  ['listRecordsAsOfJson', [1], [1]], ['continueAsOfListJson', [0], [0]],
+  ['listSnapshotRecordsJson', [1]], ['continueSnapshotListJson', [0], [0]],
+  ['listRelationshipRecordsJson', [3]], ['continueRelationshipListJson', [0], [0]],
   ['lookupRecordJson', [3]], ['createRecordJson'], ['patchRecordJson'], ['executeLifecycleActionJson'],
+  ['actionTargetConditionsJson'], ['invokeActionJson'], ['batchRecordsJson'], ['tombstoneRecordJson'],
+  ['executeRecoveredCreateJson'], ['executeRecoveredLifecycleActionJson'],
+  ['uploadAttachmentJson'], ['deleteAttachmentJson'],
 ]) wrapAsync(method, jsonIndexes, requiredIndexes);
 
+for (const [method, jsonIndexes, requiredIndexes] of [
+  ['prepareCreate', [1], [1]], ['prepareCreateJson'], ['recoverCreate'],
+  ['prepareLifecycleAction', [1], [1]], ['prepareLifecycleActionJson'],
+  ['recoverLifecycleAction'],
+]) {
+  const original = native.BaseRegistryClient.prototype[method];
+  native.BaseRegistryClient.prototype[method] = function (...args) {
+    try {
+      return original.apply(this, sanitizeArguments(
+        args, new Set(jsonIndexes), new Set(requiredIndexes),
+      ));
+    } catch (error) {
+      throw normalize(error, 'invalid_request');
+    }
+  };
+}
+
+function preparedClass(Class, label) {
+  Object.defineProperty(Class.prototype, Symbol.for('nodejs.util.inspect.custom'), {
+    value() { return `${label}(<redacted>)`; },
+  });
+  Object.defineProperty(Class.prototype, 'toString', {
+    value() { return `${label}(<redacted>)`; },
+  });
+  const Facade = function () {
+    throw new TypeError(`${label} has no public constructor`);
+  };
+  Object.defineProperties(Facade, {
+    name: { value: label },
+    fromBytes: {
+      value(bytes) {
+        try {
+          if (!Buffer.isBuffer(bytes)) throw inputError('invalid_request');
+          return Class.fromBytes(bytes);
+        } catch (error) {
+          throw normalize(error, 'invalid_request');
+        }
+      },
+    },
+    [Symbol.hasInstance]: {
+      value(value) { return value instanceof Class; },
+    },
+  });
+  Facade.prototype = Class.prototype;
+  return Facade;
+}
+
+const BRegPreparedCreate = preparedClass(native.BRegPreparedCreate, 'BRegPreparedCreate');
+const BRegPreparedLifecycle = preparedClass(
+  native.BRegPreparedLifecycle, 'BRegPreparedLifecycle',
+);
+
+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 +244,30 @@ 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',
+  'selectImmediateAction', 'selectTombstone', 'selectBatch', 'changeRequestCapability',
+]) {
   const original = native.BRegMetadata.prototype[name];
   native.BRegMetadata.prototype[name] = function (...args) {
     try {
@@ -190,4 +296,14 @@ module.exports = {
   BRegPatchBinding: native.BRegPatchBinding,
   BRegLifecycleAuthority: native.BRegLifecycleAuthority,
   BRegLifecycleAction: native.BRegLifecycleAction,
+  BRegAttachmentSlot: native.BRegAttachmentSlot,
+  BRegAttachmentUpload: native.BRegAttachmentUpload,
+  BRegImmediateActionBinding: native.BRegImmediateActionBinding,
+  BRegActionTargetConditions: native.BRegActionTargetConditions,
+  BRegTombstoneBinding: native.BRegTombstoneBinding,
+  BRegBatchBinding: native.BRegBatchBinding,
+  BRegPreparedCreate,
+  BRegPreparedLifecycle,
+  BRegRecoveredCreate: native.BRegRecoveredCreate,
+  BRegRecoveredLifecycle: native.BRegRecoveredLifecycle,
 };

package/breg/index.d.ts

@@ -8,30 +8,151 @@ export declare class BaseRegistryClient {
   registryMetadata(accessProfile?: string | undefined | null): Promise<RawOutcome>
   registryContract(accessProfile?: string | undefined | null): Promise<BRegMetadata>
   entitySchema(entityIdentifier: string, accessProfile?: string | undefined | null): Promise<RawOutcome>
+  /** Retrieve one bounded first page of record revisions as inert JSON. */
+  recordRevisions(entityRoute: string, recordIdentifier: string, accessProfile?: string | undefined | null): Promise<RawOutcome>
+  /** Retrieve one exact retained revision as validated inert record JSON. */
+  getRecordRevision(entityRoute: string, recordIdentifier: string, revision: number, options?: any | 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>
+  getGeoJsonRecord(entityRoute: string, recordIdentifier: string, options?: any | undefined | null): Promise<CompleteOutcome>
+  listGeoJsonRecords(entityRoute: string, options?: any | undefined | null): Promise<PageOutcome>
+  continueGeoJsonList(value: any): Promise<PageOutcome>
+  listCurrentRecords(entityRoute: string, options?: any | undefined | null): Promise<PageOutcome>
+  continueCurrentList(value: any): Promise<PageOutcome>
+  listRecordsAsOf(entityRoute: string, options?: any | undefined | null): Promise<PageOutcome>
+  continueAsOfList(value: any): Promise<PageOutcome>
+  listSnapshotRecords(entityRoute: string, options?: any | undefined | null): Promise<PageOutcome>
+  continueSnapshotList(value: any): Promise<PageOutcome>
+  listRelationshipRecords(entityRoute: string, recordIdentifier: string, pathRoute: string, options?: any | undefined | null): Promise<PageOutcome>
+  continueRelationshipList(value: any): Promise<PageOutcome>
   lookupRecord(entityRoute: string, selector: string, values?: any | undefined | null, options?: any | undefined | null): Promise<CompleteOutcome>
+  /** Fetch opaque target conditions for one metadata-selected action. */
+  actionTargetConditions(binding: BRegImmediateActionBinding, inputs: any): Promise<BRegActionTargetConditions>
+  /** Invoke one metadata-selected immediate action without automatic retry. */
+  invokeAction(binding: BRegImmediateActionBinding, inputs: any, idempotencyKey: string, conditions?: BRegActionTargetConditions | undefined | null): Promise<CompleteOutcome>
   createRecord(binding: BRegCreateBinding, data: any, idempotencyKey: string, formatValue?: string | undefined | null): Promise<CompleteOutcome>
+  /** Prepare inert Create evidence before any token acquisition or I/O. */
+  prepareCreate(binding: BRegCreateBinding, data: any, idempotencyKey: string, formatValue?: string | undefined | null): BRegPreparedCreate
+  /** Revalidate saved Create evidence against freshly selected authority. */
+  recoverCreate(binding: BRegCreateBinding, prepared: BRegPreparedCreate): BRegRecoveredCreate
+  /** Explicitly send a recovered Create request with fresh authority. */
+  executeRecoveredCreate(binding: BRegCreateBinding, recovered: BRegRecoveredCreate): Promise<CompleteOutcome>
   patchRecord(binding: BRegPatchBinding, recordIdentifier: string, etag: string, operations: any, idempotencyKey: string, formatValue?: string | undefined | null): Promise<CompleteOutcome>
+  /** Execute one metadata-selected atomic batch without automatic retry. */
+  batchRecords(binding: BRegBatchBinding, request: any, idempotencyKey: string): Promise<CompleteOutcome>
+  /** Tombstone one record against its current strong ETag. */
+  tombstoneRecord(binding: BRegTombstoneBinding, recordIdentifier: string, etag: string, 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>
+  /** Prepare inert lifecycle evidence before any token acquisition or I/O. */
+  prepareLifecycleAction(authority: BRegLifecycleAuthority, record: any, action: BRegLifecycleAction, idempotencyKey: string, formatValue?: string | undefined | null): BRegPreparedLifecycle
+  /** Revalidate saved lifecycle evidence against freshly selected authority. */
+  recoverLifecycleAction(authority: BRegLifecycleAuthority, prepared: BRegPreparedLifecycle): BRegRecoveredLifecycle
+  /** Explicitly send a recovered lifecycle action. */
+  executeRecoveredLifecycleAction(recovered: BRegRecoveredLifecycle): 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>
+  getGeoJsonRecordJson(entityRoute: string, recordIdentifier: string, options?: any | undefined | null): Promise<JsonOutcome>
+  listGeoJsonRecordsJson(entityRoute: string, options?: any | undefined | null): Promise<JsonOutcome>
+  continueGeoJsonListJson(value: any): Promise<JsonOutcome>
+  listCurrentRecordsJson(entityRoute: string, options?: any | undefined | null): Promise<JsonOutcome>
+  continueCurrentListJson(value: any): Promise<JsonOutcome>
+  listRecordsAsOfJson(entityRoute: string, options?: any | undefined | null): Promise<JsonOutcome>
+  continueAsOfListJson(value: any): Promise<JsonOutcome>
+  listSnapshotRecordsJson(entityRoute: string, options?: any | undefined | null): Promise<JsonOutcome>
+  continueSnapshotListJson(value: any): Promise<JsonOutcome>
+  listRelationshipRecordsJson(entityRoute: string, recordIdentifier: string, pathRoute: string, options?: any | undefined | null): Promise<JsonOutcome>
+  continueRelationshipListJson(value: any): Promise<JsonOutcome>
   lookupRecordJson(entityRoute: string, selector: string, valuesJson?: string | undefined | null, options?: any | undefined | null): Promise<JsonOutcome>
+  /** Fetch opaque target conditions from exact action-input JSON. */
+  actionTargetConditionsJson(binding: BRegImmediateActionBinding, inputsJson: string): Promise<BRegActionTargetConditions>
+  /** Invoke an action from exact JSON and preserve exact receipt values. */
+  invokeActionJson(binding: BRegImmediateActionBinding, inputsJson: string, idempotencyKey: string, conditions?: BRegActionTargetConditions | undefined | null): Promise<JsonOutcome>
   createRecordJson(binding: BRegCreateBinding, dataJson: string, idempotencyKey: string, formatValue?: string | undefined | null): Promise<JsonOutcome>
+  /** Prepare inert Create evidence from exact JSON text. */
+  prepareCreateJson(binding: BRegCreateBinding, dataJson: string, idempotencyKey: string, formatValue?: string | undefined | null): BRegPreparedCreate
+  /** Explicitly send a recovered Create request and preserve exact values. */
+  executeRecoveredCreateJson(binding: BRegCreateBinding, recovered: BRegRecoveredCreate): Promise<JsonOutcome>
   patchRecordJson(binding: BRegPatchBinding, recordIdentifier: string, etag: string, operationsJson: string, idempotencyKey: string, formatValue?: string | undefined | null): Promise<JsonOutcome>
+  /** Execute one metadata-selected atomic batch from exact JSON. */
+  batchRecordsJson(binding: BRegBatchBinding, requestJson: string, idempotencyKey: string): Promise<JsonOutcome>
+  /** Tombstone one record and preserve exact response values. */
+  tombstoneRecordJson(binding: BRegTombstoneBinding, recordIdentifier: string, etag: 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>
+  /** Prepare inert lifecycle evidence from an exact Registry Record response. */
+  prepareLifecycleActionJson(authority: BRegLifecycleAuthority, recordJson: string, action: BRegLifecycleAction, idempotencyKey: string, formatValue?: string | undefined | null): BRegPreparedLifecycle
   executeLifecycleActionJson(action: BRegLifecycleAction, idempotencyKey: string): Promise<JsonOutcome>
+  /** Explicitly send a recovered lifecycle action and preserve exact values. */
+  executeRecoveredLifecycleActionJson(recovered: BRegRecoveredLifecycle): Promise<JsonOutcome>
 }
 
+/** Opaque server-validated target conditions for one immediate action. */
+export declare class BRegActionTargetConditions {
+  get preconditionKeys(): Array<string>
+  get valueJson(): string
+  get traceId(): string
+}
+export type ActionTargetConditions = BRegActionTargetConditions
+
+/** 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 BRegBatchBinding {
+
+}
+export type BatchBinding = BRegBatchBinding
+
 export declare class BRegCreateBinding {
 
 }
 export type CreateBinding = BRegCreateBinding
 
+export declare class BRegImmediateActionBinding {
+
+}
+export type ImmediateActionBinding = BRegImmediateActionBinding
+
 export declare class BRegLifecycleAction {
+  withReason(reason: string): BRegLifecycleAction
   get bodyJson(): string
   get reviewJson(): string | null
   get operation(): string
@@ -50,6 +171,12 @@ export type LifecycleAuthority = BRegLifecycleAuthority
 export declare class BRegMetadata {
   /** Caller-filtered inert descriptors. Selectors below remain the only authority constructors. */
   get operations(): any
+  /** Complete typed caller-filtered immediate-action descriptors. */
+  get immediateActions(): any
+  /** Original caller-filtered action metadata as exact JSON text. */
+  get actionsJson(): string | null
+  /** Descriptive change-request capability for one entity, when advertised. */
+  changeRequestCapability(entityIdentifier: string): any | null
   get registryIdentifier(): string
   get registryVersion(): string
   get registryRevision(): string
@@ -58,6 +185,10 @@ 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>
+  selectImmediateAction(actionIdentifier: string, expectedProfile: string): BRegImmediateActionBinding
+  selectTombstone(entityIdentifier: string, expectedProfile: string): BRegTombstoneBinding
+  selectBatch(entityIdentifier: string, expectedProfile: string): BRegBatchBinding
 }
 export type Metadata = BRegMetadata
 
@@ -66,6 +197,53 @@ export declare class BRegPatchBinding {
 }
 export type PatchBinding = BRegPatchBinding
 
+/**
+ * Inert original Create request evidence. The bytes carry values and an
+ * idempotency key, but no token or executable metadata authority.
+ */
+export declare class BRegPreparedCreate {
+  /** Restore bounded inert evidence previously returned by `toBytes`. */
+  static fromBytes(bytes: Buffer): BRegPreparedCreate
+  /** Copy the exact evidence bytes for owner-protected persistence. */
+  toBytes(): Buffer
+}
+export type PreparedCreate = BRegPreparedCreate
+
+/**
+ * Inert original lifecycle request evidence. The bytes carry record values
+ * and an idempotency key, but no token or executable metadata authority.
+ */
+export declare class BRegPreparedLifecycle {
+  /** Restore bounded inert evidence previously returned by `toBytes`. */
+  static fromBytes(bytes: Buffer): BRegPreparedLifecycle
+  /** Copy the exact evidence bytes for owner-protected persistence. */
+  toBytes(): Buffer
+}
+export type PreparedLifecycle = BRegPreparedLifecycle
+
+/**
+ * A recovered Create request, key, and representation. This remains inert
+ * until `executeRecoveredCreate` is explicitly called with fresh authority.
+ */
+export declare class BRegRecoveredCreate {
+
+}
+export type RecoveredCreate = BRegRecoveredCreate
+
+/**
+ * A recovered lifecycle action and key. This remains inert until
+ * `executeRecoveredLifecycleAction` is explicitly called.
+ */
+export declare class BRegRecoveredLifecycle {
+
+}
+export type RecoveredLifecycle = BRegRecoveredLifecycle
+
+export declare class BRegTombstoneBinding {
+
+}
+export type TombstoneBinding = BRegTombstoneBinding
+
 export interface CompleteOutcome {
   kind: string
   value: any
@@ -82,6 +260,8 @@ export interface JsonOutcome {
   traceId: string
   etag?: string
   location?: string
+  snapshot?: string
+  validAt?: string
 }
 
 export interface PageOutcome {
@@ -90,6 +270,8 @@ export interface PageOutcome {
   continuation?: any
   traceId: string
   etag?: string
+  snapshot?: string
+  validAt?: string
 }
 
 export interface RawOutcome {