feat: custom error types for better error handling (#19)

satoshai-dev · claude · web-flow · commit e3277ee8cc4f · 2026-02-26T15:18:47.000Z
* feat: add custom error types for better error handling Replace generic Error throws with typed error classes (NetworkError, FeeEstimationError, BroadcastError, ConfirmationError, ConfigurationError, UserRejectionError) so users can catch specific failure modes programmatically. Closes #13 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * chore: add changeset for custom error types Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: forward ErrorOptions for cause chaining in all error subclasses All custom error subclasses now accept an optional ErrorOptions parameter and forward it to the base class, enabling error cause chaining via `new NetworkError('msg', 500, url, body, { cause })`. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
diff --git a/.changeset/custom-error-types.md b/.changeset/custom-error-types.md
@@ -0,0 +1,7 @@
+---
+'@satoshai/playstacks': minor
+---
+
+Add custom error types for programmatic error handling
+
+Introduces a typed error hierarchy (`PlaystacksError`, `NetworkError`, `BroadcastError`, `ConfirmationError`, `UserRejectionError`, `ConfigurationError`, `FeeEstimationError`) so consumers can catch specific errors with `instanceof` checks instead of parsing error message strings.
diff --git a/packages/playstacks/src/config.ts b/packages/playstacks/src/config.ts
@@ -1,3 +1,5 @@
+import { ConfigurationError } from './errors.js';
+
 export type NetworkName = 'mainnet' | 'testnet' | 'devnet';
 
 export interface CustomNetwork {
@@ -71,7 +73,7 @@ export function resolveConfig(config: PlaystacksConfig, derivedPrivateKey?: stri
     : derivedPrivateKey;
 
   if (!privateKey) {
-    throw new Error('No private key available. Provide privateKey or mnemonic.');
+    throw new ConfigurationError('No private key available. Provide privateKey or mnemonic.');
   }
 
   return {
diff --git a/packages/playstacks/src/errors.ts b/packages/playstacks/src/errors.ts
@@ -0,0 +1,89 @@
+/** Base error class for all Playstacks errors. */
+export class PlaystacksError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'PlaystacksError';
+  }
+}
+
+/** Thrown when the Stacks API is unreachable or returns an HTTP error. */
+export class NetworkError extends PlaystacksError {
+  readonly statusCode: number;
+  readonly url: string;
+  readonly responseBody?: string;
+
+  constructor(
+    message: string,
+    statusCode: number,
+    url: string,
+    responseBody?: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = 'NetworkError';
+    this.statusCode = statusCode;
+    this.url = url;
+    this.responseBody = responseBody;
+  }
+}
+
+/** Thrown when fee estimation fails. */
+export class FeeEstimationError extends PlaystacksError {
+  readonly statusCode?: number;
+  readonly responseBody?: string;
+
+  constructor(
+    message: string,
+    statusCode?: number,
+    responseBody?: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = 'FeeEstimationError';
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+  }
+}
+
+/** Thrown when a signed transaction is rejected during broadcast. */
+export class BroadcastError extends PlaystacksError {
+  readonly reason?: string;
+
+  constructor(message: string, reason?: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'BroadcastError';
+    this.reason = reason;
+  }
+}
+
+/** Thrown when a transaction does not confirm within the configured timeout. */
+export class ConfirmationError extends PlaystacksError {
+  readonly txid: string;
+  readonly timeoutMs: number;
+
+  constructor(message: string, txid: string, timeoutMs: number, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'ConfirmationError';
+    this.txid = txid;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+/** Thrown when the mock wallet rejects a request (code 4001). */
+export class UserRejectionError extends PlaystacksError {
+  readonly code: number;
+
+  constructor(message = 'User rejected the request', code = 4001, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'UserRejectionError';
+    this.code = code;
+  }
+}
+
+/** Thrown when configuration is invalid (missing key, unknown network, bad key length). */
+export class ConfigurationError extends PlaystacksError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'ConfigurationError';
+  }
+}
diff --git a/packages/playstacks/src/index.ts b/packages/playstacks/src/index.ts
@@ -1,5 +1,14 @@
 // Public API
 export { testWithStacks, type StacksFixture, type StacksFixtures } from './fixtures.js';
+export {
+  PlaystacksError,
+  NetworkError,
+  FeeEstimationError,
+  BroadcastError,
+  ConfirmationError,
+  UserRejectionError,
+  ConfigurationError,
+} from './errors.js';
 export {
   type PlaystacksConfig,
   type PrivateKeyConfig,
diff --git a/packages/playstacks/src/network/api-client.ts b/packages/playstacks/src/network/api-client.ts
@@ -1,4 +1,5 @@
 import type { ResolvedNetwork } from './network-config.js';
+import { NetworkError, FeeEstimationError } from '../errors.js';
 
 export interface AccountInfo {
   balance: string;
@@ -16,7 +17,12 @@ async function fetchJson<T>(url: string): Promise<T> {
   const response = await fetch(url);
   if (!response.ok) {
     const body = await response.text().catch(() => '');
-    throw new Error(`Stacks API error ${response.status}: ${url}\n${body}`);
+    throw new NetworkError(
+      `Stacks API error ${response.status}: ${url}`,
+      response.status,
+      url,
+      body || undefined,
+    );
   }
   return response.json() as Promise<T>;
 }
@@ -85,7 +91,11 @@ export async function fetchTransactionFeeEstimate(
 
   if (!response.ok) {
     const body = await response.text().catch(() => '');
-    throw new Error(`Fee estimation failed ${response.status}: ${body}`);
+    throw new FeeEstimationError(
+      `Fee estimation failed ${response.status}`,
+      response.status,
+      body || undefined,
+    );
   }
 
   return response.json() as Promise<FeeEstimation>;
diff --git a/packages/playstacks/src/network/network-config.ts b/packages/playstacks/src/network/network-config.ts
@@ -1,4 +1,5 @@
 import type { NetworkOption } from '../config.js';
+import { ConfigurationError } from '../errors.js';
 
 export interface ResolvedNetwork {
   /** Human-readable name */
@@ -31,7 +32,7 @@ export function resolveNetwork(option: NetworkOption): ResolvedNetwork {
   if (typeof option === 'string') {
     const network = NETWORK_MAP[option];
     if (!network) {
-      throw new Error(
+      throw new ConfigurationError(
         `Unknown network "${option}". Use "mainnet", "testnet", "devnet", or { url: "..." }.`
       );
     }
diff --git a/packages/playstacks/src/tx/broadcaster.ts b/packages/playstacks/src/tx/broadcaster.ts
@@ -3,6 +3,7 @@ import {
   type StacksTransactionWire,
 } from '@stacks/transactions';
 import type { ResolvedNetwork } from '../network/network-config.js';
+import { BroadcastError } from '../errors.js';
 
 export interface BroadcastResult {
   txid: string;
@@ -31,5 +32,5 @@ export async function broadcast(
   }
 
   const errorStr = JSON.stringify(result);
-  throw new Error(`Transaction broadcast failed: ${errorStr}`);
+  throw new BroadcastError(`Transaction broadcast failed: ${errorStr}`, errorStr);
 }
diff --git a/packages/playstacks/src/tx/confirmation.ts b/packages/playstacks/src/tx/confirmation.ts
@@ -1,6 +1,7 @@
 import type { ResolvedConfig } from '../config.js';
 import type { ResolvedNetwork } from '../network/network-config.js';
 import { fetchTransactionStatus } from '../network/api-client.js';
+import { ConfirmationError } from '../errors.js';
 
 /** Terminal transaction status on the Stacks network */
 export type TxStatus = 'success' | 'abort_by_response' | 'abort_by_post_condition';
@@ -41,8 +42,10 @@ export async function waitForConfirmation(
     await sleep(config.pollInterval);
   }
 
-  throw new Error(
-    `Transaction ${normalizedTxid} did not confirm within ${config.timeout}ms`
+  throw new ConfirmationError(
+    `Transaction ${normalizedTxid} did not confirm within ${config.timeout}ms`,
+    normalizedTxid,
+    config.timeout,
   );
 }
 
diff --git a/packages/playstacks/src/wallet/key-manager.ts b/packages/playstacks/src/wallet/key-manager.ts
@@ -6,6 +6,7 @@ import {
 } from '@stacks/transactions';
 import { generateWallet, generateNewAccount } from '@stacks/wallet-sdk';
 import type { WalletIdentity } from './types.js';
+import { ConfigurationError } from '../errors.js';
 
 /**
  * Normalize a private key hex string.
@@ -16,7 +17,7 @@ function normalizePrivateKey(key: string): string {
   const hex = key.startsWith('0x') ? key.slice(2) : key;
   // Validate length: 64 chars (32 bytes) or 66 chars (32 bytes + 01 suffix)
   if (hex.length !== 64 && hex.length !== 66) {
-    throw new Error(
+    throw new ConfigurationError(
       `Invalid private key length: expected 64 or 66 hex chars, got ${hex.length}`
     );
   }
diff --git a/packages/playstacks/tests/unit/errors.test.ts b/packages/playstacks/tests/unit/errors.test.ts
@@ -0,0 +1,92 @@
+import { describe, it, expect } from 'vitest';
+import {
+  PlaystacksError,
+  NetworkError,
+  FeeEstimationError,
+  BroadcastError,
+  ConfirmationError,
+  UserRejectionError,
+  ConfigurationError,
+} from '../../src/errors.js';
+
+describe('custom error types', () => {
+  it('PlaystacksError is instanceof Error', () => {
+    const err = new PlaystacksError('base error');
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(PlaystacksError);
+    expect(err.name).toBe('PlaystacksError');
+    expect(err.message).toBe('base error');
+  });
+
+  it('NetworkError includes status, url, and body', () => {
+    const err = new NetworkError('API error 500', 500, 'https://api.hiro.so/v2/info', 'Internal Server Error');
+    expect(err).toBeInstanceOf(PlaystacksError);
+    expect(err).toBeInstanceOf(NetworkError);
+    expect(err.name).toBe('NetworkError');
+    expect(err.statusCode).toBe(500);
+    expect(err.url).toBe('https://api.hiro.so/v2/info');
+    expect(err.responseBody).toBe('Internal Server Error');
+  });
+
+  it('FeeEstimationError includes status and body', () => {
+    const err = new FeeEstimationError('Fee estimation failed 400', 400, 'bad request');
+    expect(err).toBeInstanceOf(PlaystacksError);
+    expect(err.name).toBe('FeeEstimationError');
+    expect(err.statusCode).toBe(400);
+    expect(err.responseBody).toBe('bad request');
+  });
+
+  it('BroadcastError includes reason', () => {
+    const err = new BroadcastError('Transaction broadcast failed', '{"error":"ConflictingNonceInMempool"}');
+    expect(err).toBeInstanceOf(PlaystacksError);
+    expect(err.name).toBe('BroadcastError');
+    expect(err.reason).toBe('{"error":"ConflictingNonceInMempool"}');
+  });
+
+  it('ConfirmationError includes txid and timeout', () => {
+    const err = new ConfirmationError('did not confirm', '0xabc', 120_000);
+    expect(err).toBeInstanceOf(PlaystacksError);
+    expect(err.name).toBe('ConfirmationError');
+    expect(err.txid).toBe('0xabc');
+    expect(err.timeoutMs).toBe(120_000);
+  });
+
+  it('UserRejectionError has defaults', () => {
+    const err = new UserRejectionError();
+    expect(err).toBeInstanceOf(PlaystacksError);
+    expect(err.name).toBe('UserRejectionError');
+    expect(err.message).toBe('User rejected the request');
+    expect(err.code).toBe(4001);
+  });
+
+  it('ConfigurationError for invalid config', () => {
+    const err = new ConfigurationError('Unknown network "foo"');
+    expect(err).toBeInstanceOf(PlaystacksError);
+    expect(err.name).toBe('ConfigurationError');
+    expect(err.message).toBe('Unknown network "foo"');
+  });
+
+  it('errors support cause chaining via ErrorOptions', () => {
+    const cause = new Error('original fetch error');
+    const err = new NetworkError('API error', 500, '/v2/info', undefined, { cause });
+    expect(err.cause).toBe(cause);
+
+    const configErr = new ConfigurationError('bad key', { cause });
+    expect(configErr.cause).toBe(cause);
+  });
+
+  it('errors can be caught by base class', () => {
+    const errors = [
+      new NetworkError('net', 500, '/'),
+      new FeeEstimationError('fee'),
+      new BroadcastError('broadcast'),
+      new ConfirmationError('confirm', '0x1', 1000),
+      new UserRejectionError(),
+      new ConfigurationError('config'),
+    ];
+    for (const err of errors) {
+      expect(err).toBeInstanceOf(PlaystacksError);
+      expect(err).toBeInstanceOf(Error);
+    }
+  });
+});

Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,7 @@ import {`
`3`	`3`	`type StacksTransactionWire,`
`4`	`4`	`} from '@stacks/transactions';`
`5`	`5`	`import type { ResolvedNetwork } from '../network/network-config.js';`
	`6`	`+import { BroadcastError } from '../errors.js';`
`6`	`7`
`7`	`8`	`export interface BroadcastResult {`
`8`	`9`	`txid: string;`
`@@ -31,5 +32,5 @@ export async function broadcast(`
`31`	`32`	`}`
`32`	`33`
`33`	`34`	`const errorStr = JSON.stringify(result);`
`34`		- throw new Error(`Transaction broadcast failed: ${errorStr}`);
	`35`	+ throw new BroadcastError(`Transaction broadcast failed: ${errorStr}`, errorStr);
`35`	`36`	`}`