@did-btcr2/api 0.2.2 → 0.3.0

package/dist/types/method.d.ts

@@ -0,0 +1,117 @@
+import { BitcoinConnection } from '@did-btcr2/bitcoin';
+import type { DocumentBytes, HexString, KeyBytes, PatchOperation } from '@did-btcr2/common';
+import { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import type { Btcr2DidDocument, DidCreateOptions, ResolutionOptions } from '@did-btcr2/method';
+import type { DidResolutionResult, DidVerificationMethod } from '@web5/dids';
+import { BitcoinApi } from './bitcoin.js';
+import { CasApi } from './cas.js';
+import type { Logger } from './types.js';
+/**
+ * DID method operations sub-facade: create, resolve, update, deactivate.
+ *
+ * Lazily initialized by {@link DidBtcr2Api} because it depends on
+ * {@link BitcoinApi} which requires network configuration.
+ * @public
+ */
+export declare class DidMethodApi {
+    #private;
+    constructor(btc?: BitcoinApi, cas?: CasApi, logger?: Logger);
+    /**
+     * Create a deterministic (k1) DID from a public key.
+     * Sets idType to KEY automatically.
+     * @param genesisBytes The compressed public key bytes (33 bytes).
+     * @param options Creation options (idType is set for you).
+     * @returns The created DID identifier string.
+     */
+    createDeterministic(genesisBytes: KeyBytes, options?: Omit<DidCreateOptions, 'idType'>): string;
+    /**
+     * Create a non-deterministic (x1) DID from external genesis document bytes.
+     * Sets idType to EXTERNAL automatically.
+     * @param genesisBytes The genesis document bytes.
+     * @param options Creation options (idType is set for you).
+     * @returns The created DID identifier string.
+     */
+    createExternal(genesisBytes: DocumentBytes, options?: Omit<DidCreateOptions, 'idType'>): string;
+    /**
+     * Resolve a DID by driving the sans-I/O {@link Resolver} state machine.
+     * If a Bitcoin connection is configured on the API, it is used automatically
+     * to fetch beacon signals. Sidecar data flows through `options.sidecar`.
+     * @param did The DID to resolve.
+     * @param options Resolution options.
+     * @returns The resolution result.
+     */
+    resolve(did: string, options?: ResolutionOptions): Promise<DidResolutionResult>;
+    /**
+     * Update an existing DID document. If a Bitcoin connection is configured on
+     * the API, it is injected automatically.
+     * @param params The update parameters.
+     * @returns The signed update.
+     */
+    update({ sourceDocument, patches, sourceVersionId, verificationMethodId, beaconId, signingMaterial, bitcoin, }: {
+        sourceDocument: Btcr2DidDocument;
+        patches: PatchOperation[];
+        sourceVersionId: number;
+        verificationMethodId: string;
+        beaconId: string;
+        signingMaterial?: KeyBytes | HexString;
+        bitcoin?: BitcoinConnection;
+    }): Promise<SignedBTCR2Update>;
+    /**
+     * Get the signing method from a DID document by method ID.
+     * @param didDocument The DID document.
+     * @param methodId The method ID (if omitted, the first signing method is returned).
+     * @returns The found signing method.
+     */
+    getSigningMethod(didDocument: Btcr2DidDocument, methodId?: string): DidVerificationMethod;
+    /**
+     * Create a fluent builder for a DID update operation.
+     * @param sourceDocument The current DID document to update.
+     * @returns An {@link UpdateBuilder} for chaining update parameters.
+     *
+     * @example
+     * ```ts
+     * const signed = await api.btcr2
+     *   .buildUpdate(currentDoc)
+     *   .patch({ op: 'add', path: '/service/1', value: newService })
+     *   .version(2)
+     *   .signer('#initialKey')
+     *   .beacon('#beacon-0')
+     *   .execute();
+     * ```
+     */
+    buildUpdate(sourceDocument: Btcr2DidDocument): UpdateBuilder;
+    /** Deactivate a DID (not yet implemented in the core method). */
+    deactivate(): Promise<SignedBTCR2Update>;
+}
+/**
+ * Fluent builder for DID update operations. Reduces the cognitive load of
+ * the 7-parameter `update()` call by letting callers chain named steps.
+ *
+ * Created via {@link DidMethodApi.buildUpdate}.
+ * @public
+ */
+export declare class UpdateBuilder {
+    #private;
+    /** @internal */
+    constructor(methodApi: DidMethodApi, sourceDocument: Btcr2DidDocument);
+    /** Add a single JSON Patch operation. Can be called multiple times. */
+    patch(op: PatchOperation): this;
+    /** Set all patches at once (replaces any previously added). */
+    patches(ops: PatchOperation[]): this;
+    /** Set the source version ID. */
+    version(id: number): this;
+    /** Set the verification method ID used for signing. */
+    signer(methodId: string): this;
+    /** Set the beacon ID for the update announcement. */
+    beacon(beaconId: string): this;
+    /** Set the signing material (secret key bytes or hex). */
+    signingMaterial(material: KeyBytes | HexString): this;
+    /** Override the Bitcoin connection for this update. */
+    withBitcoin(connection: BitcoinConnection): this;
+    /**
+     * Execute the update.
+     * @throws {Error} If required fields (version, signer, beacon) are missing.
+     */
+    execute(): Promise<SignedBTCR2Update>;
+}
+//# sourceMappingURL=method.d.ts.map

package/dist/types/method.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../../src/method.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAmB,gBAAgB,EAA8D,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE5K,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;;GAMG;AACH,qBAAa,YAAY;;gBAKX,GAAG,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAM3D;;;;;;OAMG;IACH,mBAAmB,CAAC,YAAY,EAAE,QAAQ,EAAE,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAM,GAAG,MAAM;IAKnG;;;;;;OAMG;IACH,cAAc,CAAC,YAAY,EAAE,aAAa,EAAE,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAM,GAAG,MAAM;IAKnG;;;;;;;OAOG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAqGrF;;;;;OAKG;IACG,MAAM,CAAC,EACX,cAAc,EACd,OAAO,EACP,eAAe,EACf,oBAAoB,EACpB,QAAQ,EACR,eAAe,EACf,OAAO,GACR,EAAE;QACD,cAAc,EAAE,gBAAgB,CAAC;QACjC,OAAO,EAAE,cAAc,EAAE,CAAC;QAC1B,eAAe,EAAE,MAAM,CAAC;QACxB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;QACvC,OAAO,CAAC,EAAE,iBAAiB,CAAC;KAC7B,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAa9B;;;;;OAKG;IACH,gBAAgB,CAAC,WAAW,EAAE,gBAAgB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,qBAAqB;IAIzF;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,cAAc,EAAE,gBAAgB,GAAG,aAAa;IAI5D,iEAAiE;IAC3D,UAAU,IAAI,OAAO,CAAC,iBAAiB,CAAC;CAS/C;AAED;;;;;;GAMG;AACH,qBAAa,aAAa;;IAUxB,gBAAgB;gBACJ,SAAS,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB;IAKrE,uEAAuE;IACvE,KAAK,CAAC,EAAE,EAAE,cAAc,GAAG,IAAI;IAK/B,+DAA+D;IAC/D,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,IAAI;IAKpC,iCAAiC;IACjC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKzB,uDAAuD;IACvD,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAK9B,qDAAqD;IACrD,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAK9B,0DAA0D;IAC1D,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI;IAKrD,uDAAuD;IACvD,WAAW,CAAC,UAAU,EAAE,iBAAiB,GAAG,IAAI;IAKhD;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC;CAqB5C"}

package/dist/types/types.d.ts

@@ -0,0 +1,128 @@
+import type { HttpExecutor, NetworkName, RestConfig, RpcConfig } from '@did-btcr2/bitcoin';
+import type { KeyManager } from '@did-btcr2/kms';
+import type { Btcr2DidDocument } from '@did-btcr2/method';
+import type { DidResolutionResult } from '@web5/dids';
+import type { CasConfig } from './cas.js';
+/**
+ * Pluggable logger interface. All methods are optional-call; the default
+ * implementation is a silent no-op.
+ * @public
+ */
+export type Logger = {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+};
+/**
+ * The two supported DID identifier types.
+ *
+ * Note: the upstream `DidCreateOptions.idType` is typed as `string` rather
+ * than a union. This local alias provides compile-time safety at the API
+ * facade level. Upstream runtime validation in `Identifier.encode()` still
+ * catches invalid values.
+ * @public
+ */
+export type IdType = 'KEY' | 'EXTERNAL';
+/**
+ * A branded string representing a DID identifier (e.g. `did:btcr2:k1q...`).
+ * Use branded types to prevent accidentally passing a txid where a DID is
+ * expected, or vice versa, at compile time.
+ *
+ * @example
+ * ```ts
+ * const did = api.generateDid().did as DidString;
+ * api.resolveDid(did); // OK
+ * api.btc.getTransaction(did); // Type error — DidString is not TxId
+ * ```
+ * @public
+ */
+export type DidString = string & {
+    readonly __brand: 'DidString';
+};
+/**
+ * A branded string representing a Bitcoin transaction ID (64-char hex).
+ * @public
+ */
+export type TxId = string & {
+    readonly __brand: 'TxId';
+};
+/**
+ * Result of a DID resolution attempt. Wraps the standard
+ * {@link DidResolutionResult} with a discriminated `ok` flag for ergonomic
+ * pattern matching without exception handling.
+ *
+ * @example
+ * ```ts
+ * const result = await api.tryResolveDid(did);
+ * if (result.ok) {
+ *   console.log(result.document);
+ * } else {
+ *   console.log(result.error, result.errorMessage);
+ * }
+ * ```
+ * @public
+ */
+export type ResolutionResult = {
+    ok: true;
+    document: Btcr2DidDocument;
+    metadata: DidResolutionResult['didDocumentMetadata'];
+    raw: DidResolutionResult;
+} | {
+    ok: false;
+    error: string;
+    errorMessage?: string;
+    raw: DidResolutionResult;
+};
+/**
+ * Bitcoin API configuration options.
+ * The `network` field is required and determines default REST/RPC endpoints.
+ * Optional `rest` and `rpc` fields override individual endpoints on top of
+ * the network defaults.
+ *
+ * @example
+ * ```ts
+ * // Use regtest defaults (localhost Polar + Esplora)
+ * { network: 'regtest' }
+ *
+ * // Use testnet4 with a custom REST endpoint
+ * { network: 'testnet4', rest: { host: 'https://my-mempool.example/api' } }
+ *
+ * // Use regtest with custom RPC credentials, default REST
+ * { network: 'regtest', rpc: { host: 'http://mynode:18443', username: 'u', password: 'p' } }
+ * ```
+ * @public
+ */
+export type BitcoinApiConfig = {
+    /** Bitcoin network name (e.g., 'regtest', 'testnet4', 'bitcoin'). */
+    network: NetworkName;
+    /** Override REST client settings on top of network defaults. */
+    rest?: Partial<RestConfig>;
+    /** Override RPC client settings on top of network defaults. */
+    rpc?: RpcConfig;
+    /**
+     * Optional HTTP executor for sans-I/O usage. Defaults to global `fetch`.
+     * Inject a custom executor to intercept requests in tests or route through
+     * a proxy without monkey-patching globals.
+     */
+    executor?: HttpExecutor;
+    /**
+     * Optional request timeout in milliseconds for REST calls.
+     * When set, wraps the HTTP executor with an `AbortSignal.timeout()`.
+     * Has no effect when a custom `executor` is provided (the custom
+     * executor is responsible for its own timeouts).
+     */
+    timeoutMs?: number;
+};
+/**
+ * Top-level API configuration options.
+ * @public
+ */
+export type ApiConfig = {
+    btc?: BitcoinApiConfig;
+    cas?: CasConfig;
+    kms?: KeyManager;
+    /** Optional logger. Defaults to a silent no-op logger. */
+    logger?: Logger;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClD,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnE;;;GAGG;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAE,QAAQ,EAAE,gBAAgB,CAAC;IAAC,QAAQ,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;IAAC,GAAG,EAAE,mBAAmB,CAAA;CAAE,GACzH;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAElF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qEAAqE;IACrE,OAAO,EAAE,WAAW,CAAC;IACrB,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3B,+DAA+D;IAC/D,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/api",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "SDK for accessing the did:btcr2 method functionality.",
   "main": "./dist/cjs/index.js",
@@ -85,11 +85,11 @@
     "nostr-tools": "^2.15.0",
     "tiny-secp256k1": "^2.2.3",
     "@did-btcr2/bitcoin": "0.5.0",
-    "@did-btcr2/common": "7.0.0",
-    "@did-btcr2/keypair": "0.11.0",
-    "@did-btcr2/kms": "0.4.0",
+    "@did-btcr2/common": "8.0.0",
     "@did-btcr2/cryptosuite": "6.0.2",
-    "@did-btcr2/method": "0.24.1"
+    "@did-btcr2/keypair": "0.11.0",
+    "@did-btcr2/method": "0.25.0",
+    "@did-btcr2/kms": "0.4.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.22.0",