decode_invoice

Instructions

Implementation Reference

• src/lightning-faucet.ts:898-936 (handler)

  The `decodeInvoice` method on `LightningFaucetClient` that executes the 'decode_invoice' tool logic. It sends a request with the bolt11 invoice to the API, then normalizes the response fields (amount, expiry, payment hash, etc.) into a consistent format.

  async decodeInvoice(bolt11: string): Promise<{
    amountSats: number;
    description: string;
    paymentHash: string;
    destination: string;
    expiresAt: string;
    isExpired: boolean;
    createdAt?: string;
    rawResponse: ApiResponse;
  }> {
    const result = await this.request<ApiResponse & {
      amount_sats?: number;
      num_satoshis?: string;
      description?: string;
      payment_hash?: string;
      destination?: string;
      timestamp?: string;
      expiry?: string;
      expires_at?: string;
      is_expired?: boolean;
    }>('decode_invoice', { invoice: bolt11 });
  
    const amountSats = result.amount_sats || parseInt(result.num_satoshis || '0', 10);
    const timestamp = result.timestamp ? parseInt(result.timestamp, 10) : 0;
    const expiry = result.expiry ? parseInt(result.expiry, 10) : 3600;
    const expiresAt = result.expires_at || new Date((timestamp + expiry) * 1000).toISOString();
    const isExpired = result.is_expired ?? (timestamp + expiry < Date.now() / 1000);
  
    return {
      amountSats,
      description: result.description || '',
      paymentHash: result.payment_hash || '',
      destination: result.destination || '',
      expiresAt,
      isExpired,
      createdAt: timestamp ? new Date(timestamp * 1000).toISOString() : undefined,
      rawResponse: result,
    };
  }

• src/lightning-faucet.ts:158-188 (helper)

  The private `request()` helper method used by `decodeInvoice` to make the actual HTTP API call. It sends the action name ('decode_invoice') along with the api_key and data payload.

  private async request<T extends ApiResponse>(
    action: string,
    data: Record<string, unknown> = {}
  ): Promise<T> {
    const payload = {
      action,
      api_key: this.apiKey,
      ...data,
    };
  
    const response = await fetch(API_BASE_URL, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(payload),
    });
  
    if (!response.ok) {
      // Don't include statusText in error — it may expose server internals
      throw new Error(`Request failed (HTTP ${response.status})`);
    }
  
    const result = await response.json() as T;
  
    if (!result.success) {
      throw new Error(result.error || 'Unknown API error');
    }
  
    return result;
  }

• src/lightning-faucet.ts:918-918 (registration)

  The string 'decode_invoice' is passed as the action parameter to `this.request()`, which is how the tool is effectively registered with the remote API.

  }>('decode_invoice', { invoice: bolt11 });

• src/lightning-faucet.ts:908-918 (schema)

  Type definition for the response from the 'decode_invoice' API call, including fields like amount_sats, num_satoshis, description, payment_hash, etc.

  const result = await this.request<ApiResponse & {
    amount_sats?: number;
    num_satoshis?: string;
    description?: string;
    payment_hash?: string;
    destination?: string;
    timestamp?: string;
    expiry?: string;
    expires_at?: string;
    is_expired?: boolean;
  }>('decode_invoice', { invoice: bolt11 });

• src/lightning-faucet.ts:898-907 (schema)

  Return type definition for the `decodeInvoice` method, mapping API response fields (snake_case) to camelCase properties.

  async decodeInvoice(bolt11: string): Promise<{
    amountSats: number;
    description: string;
    paymentHash: string;
    destination: string;
    expiresAt: string;
    isExpired: boolean;
    createdAt?: string;
    rawResponse: ApiResponse;
  }> {