welshman/docs/util/zaps.md

# Zaps

The Zaps module provides utilities for working with Lightning Network payments (zaps) in Nostr, including LNURL handling, invoice amount parsing, and zap validation.

## Zapper Interface
The Zapper interface represents a Lightning Network payment provider that can process zaps:

```typescript
interface Zapper {
  // LNURL for payment processing
  lnurl: string

  // User's pubkey on the payment service
  pubkey?: string

  // LNURL callback endpoint
  callback?: string

  // Minimum payment amount in millisatoshis
  minSendable?: number

  // Maximum payment amount in millisatoshis
  maxSendable?: number

  // Pubkey used to sign zap receipts
  nostrPubkey?: string

  // Whether provider supports Nostr zaps
  allowsNostr?: boolean
}
```

### Finding Nostr Zappers

#### Getting Lightning Info

First, check the user's profile for Lightning addresses:

```typescript
function getLightningInfo(profile: Profile) {
  // Check for Lightning Address (NIP-57)
  if (profile.lud16) {
    return {
      type: 'lud16',
      address: profile.lud16
    }
  }

  // Check for LNURL
  if (profile.lud06) {
    return {
      type: 'lud06',
      url: profile.lud06
    }
  }

  return null
}
```

#### Fetching LNURL Metadata

Once you have the Lightning address or LNURL, fetch the metadata:

```typescript
async function fetchZapper(address: string): Promise<Zapper | null> {
  // Convert Lightning address to LNURL if needed
  const lnurl = getLnUrl(address)
  if (!lnurl) return null

  try {
    // Decode and fetch LNURL metadata
    const url = new URL(bech32.decode(lnurl).data)
    const response = await fetch(url.toString())
    const metadata = await response.json()

    // Extract zapper details
    return {
      lnurl,
      callback: metadata.callback,
      minSendable: metadata.minSendable,
      maxSendable: metadata.maxSendable,
      nostrPubkey: metadata.nostrPubkey,
      allowsNostr: Boolean(metadata.allowsNostr),
    }
  } catch (error) {
    console.error('Failed to fetch zapper:', error)
    return null
  }
}
```

```typescript
// Example Alby zapper configuration
const albyZapper: Zapper = {
  lnurl: "lnurl1...",
  pubkey: "alby_user_pubkey",
  nostrPubkey: "alby_signing_key",
  allowsNostr: true,
  minSendable: 1000,    // 1 sat minimum
  maxSendable: 100000000 // 100k sats maximum
}

// Example LNbits zapper
const lnbitsZapper: Zapper = {
  lnurl: "lnurl1...",
  callback: "https://lnbits.com/callback",
  nostrPubkey: "lnbits_signing_key",
  allowsNostr: true
}
```

### Zap Structure
```typescript
interface Zap {
  request: TrustedEvent    // Zap request event kind 9734
  response: TrustedEvent   // Zap receipt/response event kind 9735 sent by the zapper
  invoiceAmount: number    // Amount in millisats
}
```

## Core Functions

### Lightning Address Handling
```typescript
// Convert address to LNURL
function getLnUrl(address: string): string | null

// Examples:
getLnUrl("user@domain.com")  // => lnurl1...
getLnUrl("https://domain.com/.well-known/lnurlp/user")  // => lnurl1...
getLnUrl("lnurl1...")  // => returns unchanged
```

### Invoice Processing
```typescript
// Parse amount from BOLT11 invoice
function getInvoiceAmount(bolt11: string): number

// Convert human readable amount to millisats
function hrpToMillisat(hrpString: string): bigint
```

### Zap Validation

The `zapFromEvent` function validates a zap receipt event, against an expected zapper.

It returns a `Zap` object if the zap is valid, or `null` if not.

```typescript
function zapFromEvent(
  response: TrustedEvent,
  zapper: Zapper | undefined
): Zap | null
```

## Usage Examples

### Processing Lightning Addresses
```typescript
// Get LNURL from various formats
const lnurl1 = getLnUrl("user@getalby.com")
const lnurl2 = getLnUrl("https://getalby.com/.well-known/lnurlp/user")
const lnurl3 = getLnUrl("lnurl1...")

// Check if conversion was successful
if (lnurl1) {
  // Process LNURL
  processLnurl(lnurl1)
}
```

### Invoice Amount Handling
```typescript
// Get invoice amount in millisats
const amount = getInvoiceAmount(bolt11Invoice)

// Convert string amount to millisats
const millisats = hrpToMillisat("1000")  // 1000 sats
const millisats = hrpToMillisat("1m")    // 1 million sats
```

### Zap Validation
```typescript
// Validate zap event
const zap = zapFromEvent(zapResponse, albyZapper)

if (zap) {
  // Process valid zap
  processZap(zap)
}
```