@did-btcr2/api 0.2.1 → 0.3.0

package/src/api.ts

@@ -1,313 +1,297 @@
-import {
-  BitcoinCoreRpcClient,
-  BitcoinNetworkConnection,
-  BitcoinRestClient,
-  BlockV3,
-  RawTransactionV2,
-  RestClientConfigParams,
-  RpcClientConfig
-} from '@did-btcr2/bitcoin';
-import type {
-  Bytes,
-  CryptosuiteName,
-  DocumentBytes,
-  Entropy,
-  HashBytes,
-  Hex,
-  HexString,
-  JSONObject,
-  KeyBytes,
-  PatchOperation,
-  ProofBytes,
-  SchnorrKeyPairObject,
-  SignatureBytes
-} from '@did-btcr2/common';
-import { DEFAULT_BLOCK_CONFIRMATIONS, DEFAULT_REST_CONFIG, DEFAULT_RPC_CONFIG, IdentifierTypes, NotImplementedError } from '@did-btcr2/common';
-import type { MultikeyObject, SignedBTCR2Update } from '@did-btcr2/cryptosuite';
-import { SchnorrMultikey } from '@did-btcr2/cryptosuite';
-import { SchnorrKeyPair, Secp256k1SecretKey } from '@did-btcr2/keypair';
-import type { Btcr2DidDocument, DidCreateOptions, ResolutionOptions, SidecarData } from '@did-btcr2/method';
-import { DidBtcr2, DidDocument, DidDocumentBuilder, Identifier } from '@did-btcr2/method';
-import type { DidResolutionResult, DidService, DidVerificationMethod } from '@web5/dids';
-
-export { DidDocument, DidDocumentBuilder, Identifier, IdentifierTypes };
-export type {
-  BlockV3,
-  Bytes,
-  CryptosuiteName,
-  DidResolutionResult,
-  DidService,
-  DidVerificationMethod,
-  DocumentBytes,
-  HashBytes,
-  Hex,
-  JSONObject,
-  KeyBytes,
-  MultikeyObject,
-  PatchOperation,
-  ProofBytes,
-  RawTransactionV2,
-  RestClientConfigParams,
-  RpcClientConfig,
-  SchnorrKeyPairObject,
-  SignatureBytes
-};
-
-/* =========================
- * Configuration Interfaces
- * ========================= */
-
-export type NetworkName = 'mainnet' | 'testnet4' | 'signet' | 'regtest';
-
-export type BitcoinApiConfig = {
-  /** Shortcut to compute base URLs and params via @did-btcr2/bitcoin getNetwork */
-  network?: NetworkName;
-  /** Override REST client settings */
-  rest?: RestClientConfigParams;
-  /** Override RPC client settings */
-  rpc?: RpcClientConfig;
-  /** Default number of confirmations to consider "final" */
-  defaultConfirmations?: number;
-};
-
-export type ApiConfig = {
-  bitcoin?: BitcoinApiConfig;
-};
-
-/* =========================
- * Sub-facade: KeyPair
- * ========================= */
+import type { NetworkName } from '@did-btcr2/bitcoin';
+import type { DocumentBytes, KeyBytes, PatchOperation } from '@did-btcr2/common';
+import { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { KeyIdentifier } from '@did-btcr2/kms';
+import type { Btcr2DidDocument, DidCreateOptions, ResolutionOptions } from '@did-btcr2/method';
+import type { DidResolutionResult } from '@web5/dids';
+import { BitcoinApi } from './bitcoin.js';
+import { CasApi, type CasConfig } from './cas.js';
+import { CryptoApi } from './crypto.js';
+import { DidApi } from './did.js';
+import { assertString, NOOP_LOGGER } from './helpers.js';
+import { KeyManagerApi } from './kms.js';
+import { DidMethodApi } from './method.js';
+import type { ApiConfig, BitcoinApiConfig, Logger, ResolutionResult } from './types.js';
+
+/**
+ * Main DidBtcr2Api facade — the primary entry point for the SDK.
+ *
+ * Exposes sub-facades for Bitcoin, DID Method, KeyPair, Crypto, and
+ * KeyManager operations. Created via the {@link createApi} factory.
+ * @public
+ */
+export class DidBtcr2Api {
+  /** Cryptographic operations (keypair, multikey, cryptosuite, proof). */
+  readonly crypto: CryptoApi;
+  /** DID identifier operations (encode, decode, generate, parse). */
+  readonly did: DidApi;
+  /** Key management operations. */
+  readonly kms: KeyManagerApi;
 
-export class KeyPairApi {
-  /** Generate a new Schnorr keypair (secp256k1). */
-  static generate(): SchnorrKeyPair {
-    return new SchnorrKeyPair();
-  }
+  #btcConfig?: BitcoinApiConfig;
+  #btc?: BitcoinApi;
+  #casConfig?: CasConfig;
+  #cas?: CasApi;
+  #btcr2?: DidMethodApi;
+  #log: Logger;
+  #disposed = false;
 
-  /** Import from secret key bytes or bigint. */
-  static fromSecret(ent: Entropy): SchnorrKeyPair {
-    const sk = new Secp256k1SecretKey(ent);
-    return new SchnorrKeyPair({ secretKey: sk });
+  constructor(config?: ApiConfig) {
+    this.#btcConfig = config?.btc;
+    this.#casConfig = config?.cas;
+    this.#log = config?.logger ?? NOOP_LOGGER;
+    this.kms = new KeyManagerApi(config?.kms);
+    this.did = new DidApi();
+    this.crypto = new CryptoApi();
   }
-}
 
-export class MultikeyApi {
   /**
-   * Create a Schnorr Multikey wrapper (includes verificationMethod, sign/verify).
-   * If secret is present, the multikey can sign.
+   * Bitcoin API sub-facade (lazily initialized).
+   * Only available when `btc` config was provided to the constructor.
+   * @throws {Error} If the instance has been disposed or no Bitcoin config was provided.
    */
-  static create(params: {
-    id: string;
-    controller: string;
-    keys: SchnorrKeyPair
-  }): SchnorrMultikey {
-    return new SchnorrMultikey(params);
-  }
-
-  /** Produce a DID Verification Method JSON from a multikey. */
-  static toVerificationMethod(mk: SchnorrMultikey): DidVerificationMethod {
-    return mk.toVerificationMethod();
-  }
-
-  /** Sign bytes via the multikey (requires secret). */
-  static async sign(mk: SchnorrMultikey, data: Bytes): Promise<SignatureBytes> {
-    return mk.sign(data);
-  }
-
-  /** Verify signature via multikey. */
-  static async verify(mk: SchnorrMultikey, data: Bytes, signature: SignatureBytes): Promise<boolean> {
-    return mk.verify(data, signature);
-  }
-}
-
-/* =========================
- * Sub-facade: Crypto
- * ========================= */
-
-export class CryptoApi {
-  public static keyPairApi = new KeyPairApi();
-  public static multikeyApi = new MultikeyApi();
-}
-
-/* =========================
- * Sub-facade: Bitcoin
- * ========================= */
-
-export class BitcoinApi {
-  readonly rest: BitcoinRestClient;
-  readonly rpc: BitcoinCoreRpcClient;
-  readonly defaultConfirmations: number;
-
-  constructor(cfg?: BitcoinApiConfig) {
-    const restCfg = {
-      host : cfg?.rest?.host ?? DEFAULT_REST_CONFIG.host,
-      ...cfg?.rest
-    };
-
-    const rpcCfg = {
-      ...DEFAULT_RPC_CONFIG,
-      ...cfg?.rpc
-    };
-
-    this.rest = new BitcoinRestClient(restCfg);
-    this.rpc = new BitcoinCoreRpcClient(rpcCfg);
-    this.defaultConfirmations = cfg?.defaultConfirmations ?? DEFAULT_BLOCK_CONFIRMATIONS;
+  get btc(): BitcoinApi {
+    this.#assertNotDisposed();
+    if (!this.#btc) {
+      if (!this.#btcConfig) {
+        throw new Error(
+          'Bitcoin not configured. Pass a btc config to createApi(), e.g.: '
+          + 'createApi({ btc: { network: \'regtest\' } })'
+        );
+      }
+      this.#btc = new BitcoinApi(this.#btcConfig);
+    }
+    return this.#btc;
   }
 
-  /** Fetch a transaction by txid via REST. */
-  async getTransaction(txid: string) {
-    return await this.rest.transaction.get(txid);
+  /**
+   * CAS API sub-facade (lazily initialized).
+   * Only available when `cas` config was provided to the constructor.
+   * @throws {Error} If the instance has been disposed or no CAS config was provided.
+   */
+  get cas(): CasApi {
+    this.#assertNotDisposed();
+    if (!this.#cas) {
+      if (!this.#casConfig) {
+        throw new Error(
+          'CAS not configured. Pass a cas config to createApi(), e.g.: '
+          + 'createApi({ cas: { helia: await createHelia() } })'
+        );
+      }
+      this.#cas = new CasApi(this.#casConfig);
+    }
+    return this.#cas;
   }
 
-  /** Broadcast a raw tx (hex) via REST. */
-  async send(rawTxHex: string) {
-    return await this.rest.transaction.send(rawTxHex);
+  /**
+   * DID Method API sub-facade (lazily initialized with bitcoin + CAS wiring).
+   * @throws {Error} If the instance has been disposed.
+   */
+  get btcr2(): DidMethodApi {
+    this.#assertNotDisposed();
+    if (!this.#btcr2) {
+      this.#btcr2 = new DidMethodApi(
+        this.#btcConfig ? this.btc : undefined,
+        this.#casConfig ? this.cas : undefined,
+        this.#log
+      );
+    }
+    return this.#btcr2;
   }
 
-  /** Get UTXOs for an address via REST. */
-  async getUtxos(address: string) {
-    return await this.rest.address.getUtxos(address);
+  /**
+   * Whether this API instance has been disposed.
+   */
+  get disposed(): boolean {
+    return this.#disposed;
   }
 
-  /** Get a block by hash or height via REST. */
-  async getBlock(params: { hash?: string; height?: number }) {
-    return await this.rest.block.get({ blockhash: params.hash, height: params.height });
+  /**
+   * Create a DID using either deterministic (KEY) or external (EXTERNAL) mode.
+   * @param type The creation mode.
+   * @param genesisBytes Public key bytes (deterministic) or document bytes (external).
+   * @param options Creation options (idType is set for you).
+   * @returns The created DID identifier string.
+   */
+  createDid(
+    type: 'deterministic' | 'external',
+    genesisBytes: KeyBytes | DocumentBytes,
+    options?: Omit<DidCreateOptions, 'idType'>
+  ): string {
+    this.#assertNotDisposed();
+    return type === 'deterministic'
+      ? this.btcr2.createDeterministic(genesisBytes as KeyBytes, options)
+      : this.btcr2.createExternal(genesisBytes as DocumentBytes, options);
   }
-}
-
-/* =========================
- * Sub-facade: KeyManager
- * ========================= */
-
-// export class KeyManagerApi {
-//   readonly impl: IMethodKeyManager;
-
-//   constructor(params?: ApiKeyManagerConfig) {
-//     this.impl = new MethodKeyManager(params);
-//   }
 
-//   setActive(keyUri: string) {
-//     this.impl.activeKeyUri = keyUri;
-//   }
-
-//   export(keyUri: string) {
-//     return this.impl.export(keyUri);
-//   }
-
-//   import(mk: SchnorrMultikey, opts?: { importKey?: boolean; active?: boolean }) {
-//     return this.impl.import(mk, opts);
-//   }
-
-//   sign(keyUri: string, hash: HashBytes): Promise<SignatureBytes> {
-//     return this.impl.sign(keyUri, hash);
-//   }
-// }
-
-/* =========================
- * Sub-facade: DID / CRUD
- * ========================= */
-
-export class DidApi {
   /**
-   * Create a deterministic DID from a public key (bytes).
+   * Generate a new DID, create the keypair, and import it into the KMS.
+   * @param options Optional settings.
+   * @param options.setActive Whether to set the imported key as active in the KMS (default `true`).
+   * @param options.network Network for the generated DID (default `'regtest'`).
+   * @returns The generated DID string and KMS key identifier.
    */
-  async createDeterministic({ genesisBytes, options }: {
-    genesisBytes: KeyBytes;
-    options: DidCreateOptions;
-  }) {
-    return DidBtcr2.create(genesisBytes, options);
+  generateDid(options?: { setActive?: boolean; network?: NetworkName }): { did: string; keyId: KeyIdentifier } {
+    this.#assertNotDisposed();
+    const { keyPair, did } = this.did.generate(options?.network);
+    const kp = SchnorrKeyPair.fromJSON(keyPair);
+    const keyId = this.kms.import(kp, { setActive: options?.setActive ?? true });
+    return { did, keyId };
   }
 
   /**
-   * Create from an intermediate DID document (external genesis).
+   * Resolve a DID, automatically injecting the configured Bitcoin connection.
+   * @param did The DID to resolve.
+   * @param options Optional resolution options.
+   * @returns The resolution result.
    */
-  async createExternal({ genesisBytes, options }: {
-    genesisBytes: DocumentBytes;
-    options: DidCreateOptions;
-  }) {
-    return DidBtcr2.create(genesisBytes, options);
+  async resolveDid(did: string, options?: ResolutionOptions): Promise<DidResolutionResult> {
+    this.#assertNotDisposed();
+    return await this.btcr2.resolve(did, options);
   }
 
   /**
-   * Resolve DID document from DID (did:btcr2:...).
+   * Resolve a DID and return a discriminated result instead of throwing.
+   * Useful when resolution failure is an expected outcome (e.g. checking
+   * whether a DID exists before creating it).
+   * @param did The DID to resolve.
+   * @param options Optional resolution options.
+   * @returns A {@link ResolutionResult} with `ok: true` on success or
+   *          `ok: false` with error details on failure.
    */
-  async resolve(did: string, options: ResolutionOptions): Promise<DidResolutionResult> {
-    return await DidBtcr2.resolve(did, options);
+  async tryResolveDid(did: string, options?: ResolutionOptions): Promise<ResolutionResult> {
+    this.#assertNotDisposed();
+    assertString(did, 'did');
+    try {
+      const raw = await this.btcr2.resolve(did, options);
+      if (raw.didDocument) {
+        return {
+          ok       : true,
+          document : raw.didDocument as Btcr2DidDocument,
+          metadata : raw.didDocumentMetadata,
+          raw,
+        };
+      }
+      return {
+        ok           : false,
+        error        : raw.didResolutionMetadata?.error ?? 'unknown',
+        errorMessage : raw.didResolutionMetadata?.errorMessage as string | undefined,
+        raw,
+      };
+    } catch (err: any) {
+      return {
+        ok           : false,
+        error        : 'internalError',
+        errorMessage : err.message,
+        raw          : {
+          didDocument            : null,
+          didDocumentMetadata    : {},
+          didResolutionMetadata  : { error: 'internalError', errorMessage: err.message },
+        } as unknown as DidResolutionResult,
+      };
+    }
   }
 
   /**
-   * Update a DID Document using a JSON Patch, signed as capabilityInvocation.
-   * You provide the prior DID Document (to pick VM), a JSON Patch, and a signer multikey.
-   * This delegates to MethodUpdate (which follows the cryptosuite rules internally).
+   * Update a DID document: resolve the current state, apply patches, sign, and announce.
+   * Automatically injects the configured Bitcoin connection.
+   *
+   * If `sourceDocument` and `sourceVersionId` are both provided, resolution
+   * is skipped. Otherwise the DID is resolved first to obtain them.
+   * @param params The update parameters.
+   * @returns The signed update.
    */
-  async update({
-    sourceDocument,
+  async updateDid({
+    did,
     patches,
-    sourceVersionId,
     verificationMethodId,
     beaconId,
-    signingMaterial,
-    bitcoin,
+    sourceDocument,
+    sourceVersionId,
   }: {
-    sourceDocument: Btcr2DidDocument;
+    did: string;
     patches: PatchOperation[];
-    sourceVersionId: number;
     verificationMethodId: string;
     beaconId: string;
-    signingMaterial?: KeyBytes | HexString;
-    bitcoin?: BitcoinNetworkConnection;
+    sourceDocument?: Btcr2DidDocument;
+    sourceVersionId?: number;
   }): Promise<SignedBTCR2Update> {
-    // The Update class exposes the algorithm that creates a DID Update Payload and proof;
-    // keep this wrapper narrow so testing can mock MethodUpdate directly.
-    return await DidBtcr2.update({
-      sourceDocument,
+    this.#assertNotDisposed();
+    assertString(did, 'did');
+
+    let doc = sourceDocument;
+    let versionId = sourceVersionId;
+
+    if (!doc || versionId === undefined) {
+      const resolution = await this.resolveDid(did);
+      if (!resolution.didDocument) {
+        const meta = resolution.didResolutionMetadata;
+        const detail = meta?.error ? `: ${meta.error}` : '.';
+        const extra = meta?.errorMessage ? ` ${meta.errorMessage}` : '';
+        throw new Error(
+          `Failed to resolve DID ${did} for update${detail}${extra}`,
+          { cause: meta }
+        );
+      }
+      doc = doc ?? resolution.didDocument as Btcr2DidDocument;
+
+      if (versionId === undefined) {
+        const rawVersionId = resolution.didDocumentMetadata?.versionId;
+        if (rawVersionId === undefined || rawVersionId === null) {
+          throw new Error(
+            `Resolution of DID ${did} succeeded but returned no versionId in metadata. `
+            + 'Provide sourceVersionId explicitly.'
+          );
+        }
+        const parsed = Number(rawVersionId);
+        if (!Number.isFinite(parsed)) {
+          throw new Error(
+            `Resolution of DID ${did} returned a non-numeric versionId: ${String(rawVersionId)}.`
+          );
+        }
+        versionId = parsed;
+      }
+    }
+
+    return await this.btcr2.update({
+      sourceDocument    : doc,
       patches,
-      sourceVersionId,
+      sourceVersionId   : versionId,
       verificationMethodId,
       beaconId,
-      signingMaterial,
-      bitcoin,
     });
   }
 
-  /** Deactivate convenience: applies the standard `deactivated: true` patch. */
-  async deactivate(): Promise<SidecarData> {
-    // This class is a stub in method right now; expose a narrow wrapper for future expansion.
-    // return DidBtcr2.deactivate({ identifier, patch }); // No-op holder; implement when core adds behavior.
-    throw new NotImplementedError(
-      'DidApi.deactivate is not implemented yet.',
-      {
-        type : 'DID_API_METHOD_NOT_IMPLEMENTED',
-        name : 'NOT_IMPLEMENTED_ERROR'
-      }
-    );
+  /**
+   * Release internal references. After disposal, accessing `btc`, `btcr2`,
+   * or calling top-level methods will throw.
+   *
+   * Note: the underlying {@link BitcoinConnection} does not hold persistent
+   * connections, so this is primarily a guard against accidental reuse.
+   */
+  dispose(): void {
+    this.#btc = undefined;
+    this.#cas = undefined;
+    this.#btcr2 = undefined;
+    this.#btcConfig = undefined;
+    this.#casConfig = undefined;
+    this.#disposed = true;
   }
-}
-
-/* =========================
- * Root facade
- * ========================= */
 
-export class DidBtcr2Api {
-  readonly bitcoin: BitcoinApi;
-  readonly did: DidApi;
-  readonly keys: KeyPairApi;
-  readonly crypto: CryptoApi;
-  // readonly keyManager: KeyManagerApi;
-
-  constructor(config?: ApiConfig) {
-    this.bitcoin = new BitcoinApi(config?.bitcoin);
-    this.did = new DidApi();
-    this.keys = new KeyPairApi();
-    this.crypto = new CryptoApi();
-    // this.keyManager = new KeyManagerApi(config?.keyManager);
+  #assertNotDisposed(): void {
+    if (this.#disposed) {
+      throw new Error('This DidBtcr2Api instance has been disposed and can no longer be used.');
+    }
   }
 }
 
-/* =========================
- * Factory
- * ========================= */
-
-export function createApi(config?: ApiConfig) {
+/**
+ * Create a new {@link DidBtcr2Api} instance with the given configuration.
+ * @param config Optional configuration for the API.
+ * @returns The created DidBtcr2Api instance.
+ * @public
+ */
+export function createApi(config?: ApiConfig): DidBtcr2Api {
   return new DidBtcr2Api(config);
 }