@did-btcr2/cli 0.20.0 → 0.21.0

package/src/resolution-options.ts

@@ -0,0 +1,67 @@
+import { DEFAULT_MIN_CONF } from '@did-btcr2/api';
+import type { ResolutionOptions } from '@did-btcr2/method';
+import { readFile } from 'node:fs/promises';
+import { CLIError } from './error.js';
+
+/** The flags that select the resolution options of a command. */
+export type ResolutionOptionFlags = {
+  resolutionOptions?     : string;
+  resolutionOptionsPath? : string;
+  minConf?               : number;
+};
+
+/** The help text of `--min-conf`. `resolve`, `update`, and `deactivate` share it. */
+export const MIN_CONF_HELP =
+  'Minimum block confirmations a beacon signal needs before resolution applies it '
+  + `(positive integer, default: ${DEFAULT_MIN_CONF}). Overrides a minConf inside the JSON resolution options`;
+
+/**
+ * Builds the resolution options from the flags. The inline JSON wins over
+ * the file. The `--min-conf` flag wins over a `minConf` inside the JSON.
+ * Returns `undefined` if no flag is set.
+ */
+export async function readResolutionOptions(flags: ResolutionOptionFlags): Promise<ResolutionOptions | undefined> {
+  let resolutionOptions: ResolutionOptions | undefined;
+  if (flags.resolutionOptions) {
+    try {
+      resolutionOptions = JSON.parse(flags.resolutionOptions);
+    } catch {
+      throw new CLIError(
+        'Invalid resolution options. Must be a valid JSON string.',
+        'INVALID_ARGUMENT_ERROR',
+        { resolutionOptions: flags.resolutionOptions }
+      );
+    }
+  } else if (flags.resolutionOptionsPath) {
+    try {
+      const content = await readFile(flags.resolutionOptionsPath, 'utf-8');
+      resolutionOptions = JSON.parse(content);
+    } catch {
+      throw new CLIError(
+        'Invalid resolution options path. Must be a valid path to a JSON file.',
+        'INVALID_ARGUMENT_ERROR',
+        { resolutionOptionsPath: flags.resolutionOptionsPath }
+      );
+    }
+  }
+  // The flag wins over a minConf inside the JSON options.
+  if (flags.minConf !== undefined) {
+    resolutionOptions = { ...(resolutionOptions ?? {}), minConf: flags.minConf };
+  }
+  return resolutionOptions;
+}
+
+/**
+ * Commander argParser for `--min-conf`. Accepts a positive integer (minimum 1),
+ * the domain the specification gives `minConf`. Errors at parse time otherwise.
+ */
+export function parseMinConf(value: string): number {
+  if (!/^[1-9]\d*$/.test(value)) {
+    throw new CLIError(
+      '--min-conf must be a positive integer (minimum 1).',
+      'INVALID_ARGUMENT_ERROR',
+      { value },
+    );
+  }
+  return Number(value);
+}

package/src/types.ts

@@ -1,5 +1,4 @@
-import type { DidUpdateResult } from '@did-btcr2/api';
-import type { PatchOperation } from '@did-btcr2/common';
+import type { BroadcastOptions, DidUpdateResult, PublishToCasMode, Signer } from '@did-btcr2/api';
 import type { Btcr2DidDocument, ResolutionOptions } from '@did-btcr2/method';
 import type { DidResolutionResult } from '@web5/dids';
 import type { DoctorReport, EffectiveConfig } from './config.js';
@@ -36,12 +35,23 @@ export interface ResolveCommandOptions {
   options?   : ResolutionOptions;
 }
 
+/**
+ * The parameters that `update` and `deactivate` hand to the api's `updateDid`
+ * and `deactivateDid`. `update` adds `patches`. An absent source pair lets the
+ * api resolve the current document with `resolutionOptions` (ADR 098, ADR
+ * 101). An absent `verificationMethodId` or `beaconId` lets the api derive it
+ * (ADR 104).
+ */
 export interface UpdateCommandOptions {
-  sourceDocument       : Btcr2DidDocument;
-  patches              : PatchOperation[];
-  sourceVersionId      : number;
-  verificationMethodId : string;
-  beaconId             : string;
+  did                   : string;
+  signer                : Signer;
+  sourceDocument?       : Btcr2DidDocument;
+  sourceVersionId?      : number;
+  verificationMethodId? : string;
+  beaconId?             : string;
+  resolutionOptions?    : ResolutionOptions;
+  publishToCas          : PublishToCasMode;
+  broadcastOptions?     : BroadcastOptions;
 }
 
 export type CommandResult =