Add describe() method to WraithError subclasses (#173)

docs/errors.md

@@ -165,3 +165,31 @@ console.log(JSON.stringify(error, null, 2));
   }
 }
 ```
+
+---
+
+## Actionable Fix Hints with `describe()`
+
+Every `WraithError` instance exposes a `describe(): string` method in addition to `message`, `code`, `context`, and `docsLink`. Where `message` is a compact, log-friendly summary, `describe()` returns a longer, human-readable hint — templated from the error's `context` — that suggests one or two concrete next steps, plus a link to the relevant docs anchor. This means console output and error toasts can surface useful guidance without a round-trip to the docs site.
+
+`WraithError` defines a generic fallback `describe()`, and every concrete subclass overrides it with a hint tailored to that specific failure mode.
+
+### Example
+
+```ts
+import { InsufficientBalanceError } from '@wraith-protocol/sdk';
+
+try {
+  // ... build a transaction
+} catch (err) {
+  if (err instanceof InsufficientBalanceError) {
+    console.error(err.message); // compact summary, e.g. for log lines
+    console.error(err.describe());
+    // "Not enough balance of XLM to build this transaction — need 100, have 50.
+    //  Try: fund the account, reduce the amount, or account for network fees
+    //  separately from the transfer amount. See https://docs.wraith.dev/sdk/errors#insufficient-balance."
+  }
+}
+```
+
+This makes `describe()` well suited for error toasts and CLI output, where a developer (or end user) needs to know what to try next without leaving the app.

etc/sdk.api.md

@@ -90,6 +90,8 @@ export class ContractRevertError extends WraithContractError {
     // (undocumented)
     readonly code = "WRAITH/CONTRACT/CONTRACT_REVERT";
     // (undocumented)
+    describe(): string;
+    // (undocumented)
     readonly reason: string;
 }
 
@@ -110,6 +112,8 @@ export class ECDHFailedError extends WraithCryptoError {
     constructor(reason: string);
     // (undocumented)
     readonly code = "WRAITH/CRYPTO/ECDH_FAILED";
+    // (undocumented)
+    describe(): string;
 }
 
 // @public (undocumented)
@@ -136,41 +140,53 @@ export class InsufficientAuthError extends WraithContractError {
     constructor(required?: string, actual?: string);
     // (undocumented)
     readonly code = "WRAITH/CONTRACT/INSUFFICIENT_AUTH";
+    // (undocumented)
+    describe(): string;
 }
 
 // @public (undocumented)
 export class InsufficientBalanceError extends WraithBuilderError {
     constructor(required: string | bigint, actual: string | bigint, asset?: string);
     // (undocumented)
     readonly code = "WRAITH/BUILDER/INSUFFICIENT_BALANCE";
+    // (undocumented)
+    describe(): string;
 }
 
 // @public (undocumented)
 export class InvalidMetaAddressError extends WraithInputError {
     constructor(metaAddress: string, reason?: string);
     // (undocumented)
     readonly code = "WRAITH/INPUT/INVALID_META_ADDRESS";
+    // (undocumented)
+    describe(): string;
 }
 
 // @public (undocumented)
 export class InvalidNameError extends WraithInputError {
     constructor(name: string, reason?: string);
     // (undocumented)
     readonly code = "WRAITH/INPUT/INVALID_NAME";
+    // (undocumented)
+    describe(): string;
 }
 
 // @public (undocumented)
 export class InvalidScalarError extends WraithInputError {
     constructor(scalar: string | bigint, reason?: string);
     // (undocumented)
     readonly code = "WRAITH/INPUT/INVALID_SCALAR";
+    // (undocumented)
+    describe(): string;
 }
 
 // @public (undocumented)
 export class InvalidSignatureError extends WraithInputError {
     constructor(signature: string | Uint8Array, expectedLength?: number, actualLength?: number);
     // (undocumented)
     readonly code = "WRAITH/INPUT/INVALID_SIGNATURE";
+    // (undocumented)
+    describe(): string;
 }
 
 // @public (undocumented)
@@ -200,6 +216,8 @@ export class KeyDerivationFailedError extends WraithCryptoError {
     constructor(reason: string);
     // (undocumented)
     readonly code = "WRAITH/CRYPTO/KEY_DERIVATION_FAILED";
+    // (undocumented)
+    describe(): string;
 }
 
 // @public (undocumented)
@@ -230,13 +248,17 @@ export class NameAlreadyRegisteredError extends WraithContractError {
     constructor(name: string, owner?: string);
     // (undocumented)
     readonly code = "WRAITH/CONTRACT/NAME_ALREADY_REGISTERED";
+    // (undocumented)
+    describe(): string;
 }
 
 // @public (undocumented)
 export class NameNotFoundError extends WraithContractError {
     constructor(name: string);
     // (undocumented)
     readonly code = "WRAITH/CONTRACT/NAME_NOT_FOUND";
+    // (undocumented)
+    describe(): string;
 }
 
 // @public (undocumented)
@@ -285,6 +307,8 @@ export class RetentionExceededError extends WraithNetworkError {
     constructor(limit: number, actual: number);
     // (undocumented)
     readonly code = "WRAITH/NETWORK/RETENTION_EXCEEDED";
+    // (undocumented)
+    describe(): string;
 }
 
 // @public (undocumented)
@@ -293,6 +317,8 @@ export class RPCRequestError extends WraithNetworkError {
     // (undocumented)
     readonly code = "WRAITH/NETWORK/RPC_REQUEST";
     // (undocumented)
+    describe(): string;
+    // (undocumented)
     readonly statusCode: number;
 }
 
@@ -301,6 +327,8 @@ export class RPCRetryExhaustedError extends WraithNetworkError {
     constructor(url: string, attempts: number, lastError?: string);
     // (undocumented)
     readonly code = "WRAITH/NETWORK/RPC_RETRY_EXHAUSTED";
+    // (undocumented)
+    describe(): string;
 }
 
 // @public (undocumented)
@@ -390,13 +418,17 @@ export class UnsupportedAssetError extends WraithBuilderError {
     constructor(asset: string, chain?: string);
     // (undocumented)
     readonly code = "WRAITH/BUILDER/UNSUPPORTED_ASSET";
+    // (undocumented)
+    describe(): string;
 }
 
 // @public (undocumented)
 export class ViewTagMismatchError extends WraithCryptoError {
     constructor(expectedTag: number, actualTag: number);
     // (undocumented)
     readonly code = "WRAITH/CRYPTO/VIEW_TAG_MISMATCH";
+    // (undocumented)
+    describe(): string;
 }
 
 // @public (undocumented)
@@ -481,6 +513,7 @@ export abstract class WraithError extends Error {
     abstract readonly code: string;
     // (undocumented)
     readonly context?: Record<string, any> | undefined;
+    describe(): string;
     // (undocumented)
     readonly docsLink: string;
     // (undocumented)