Add L402 paywall support, remove keys.List(), add by-hash lookups

- Add L402Service with CreateChallenge(), Verify(), Pay() methods
- Add L402 types: CreateL402ChallengeParams, L402Challenge,
  VerifyL402Params, VerifyL402Response, PayL402Params, L402PayResponse
- Remove Keys.List() — server endpoint removed
- Remove APIKey type
- Add GetByHash() and WatchByHash() to InvoicesService and PaymentsService
- Bump version to 0.5.0

Made-with: Cursor

Author: realbub

README.md

@@ -95,6 +95,27 @@ fmt.Printf("%d sats available\n", wallet.Available)
 
 ---
 
+## L402 paywalls
+
+```go
+// Create a challenge (server side)
+challenge, _ := client.L402.CreateChallenge(ctx, &lnbot.CreateL402ChallengeParams{
+    Amount:      100,
+    Description: lnbot.Ptr("API access"),
+})
+
+// Pay the challenge (client side)
+result, _ := client.L402.Pay(ctx, &lnbot.PayL402Params{
+    WwwAuthenticate: challenge.WwwAuthenticate,
+})
+
+// Verify a token (server side, stateless)
+v, _ := client.L402.Verify(ctx, &lnbot.VerifyL402Params{
+    Authorization: *result.Authorization,
+})
+fmt.Println(v.Valid)
+```
+
 ## Error handling
 
 ```go

invoices.go

@@ -64,6 +64,15 @@ func (s *InvoicesService) CreateForAddress(ctx context.Context, params *CreateIn
 	return &v, nil
 }
 
+// GetByHash returns a single invoice by its payment hash.
+func (s *InvoicesService) GetByHash(ctx context.Context, paymentHash string) (*Invoice, error) {
+	var v Invoice
+	if err := s.c.get(ctx, fmt.Sprintf("/v1/invoices/%s", paymentHash), &v); err != nil {
+		return nil, err
+	}
+	return &v, nil
+}
+
 // Watch opens an SSE stream and sends events to the returned channel.
 // The channel is closed when the stream ends. Cancel the context to abort.
 func (s *InvoicesService) Watch(ctx context.Context, number int, timeout *int) (<-chan InvoiceEvent, <-chan error) {
@@ -141,3 +150,81 @@ func (s *InvoicesService) Watch(ctx context.Context, number int, timeout *int) (
 
 	return events, errs
 }
+
+// WatchByHash opens an SSE stream for an invoice identified by payment hash.
+// The channel is closed when the stream ends. Cancel the context to abort.
+func (s *InvoicesService) WatchByHash(ctx context.Context, paymentHash string, timeout *int) (<-chan InvoiceEvent, <-chan error) {
+	events := make(chan InvoiceEvent, 1)
+	errs := make(chan error, 1)
+
+	go func() {
+		defer close(events)
+		defer close(errs)
+
+		path := fmt.Sprintf("%s/v1/invoices/%s/events", s.c.baseURL, paymentHash)
+		if timeout != nil {
+			path = fmt.Sprintf("%s?timeout=%d", path, *timeout)
+		}
+
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, path, nil)
+		if err != nil {
+			errs <- err
+			return
+		}
+		req.Header.Set("Accept", "text/event-stream")
+		req.Header.Set("User-Agent", "lnbot-go/"+Version)
+		if s.c.apiKey != "" {
+			req.Header.Set("Authorization", "Bearer "+s.c.apiKey)
+		}
+
+		resp, err := s.c.http.Do(req)
+		if err != nil {
+			errs <- err
+			return
+		}
+		defer resp.Body.Close()
+
+		if resp.StatusCode >= 400 {
+			body, _ := io.ReadAll(resp.Body)
+			errs <- parseAPIError(resp.StatusCode, body)
+			return
+		}
+
+		scanner := bufio.NewScanner(resp.Body)
+		var (
+			eventType string
+			dataLines []string
+		)
+		dispatch := func() {
+			if eventType == "" || len(dataLines) == 0 {
+				return
+			}
+			raw := strings.Join(dataLines, "\n")
+			var data Invoice
+			if json.Unmarshal([]byte(raw), &data) == nil {
+				events <- InvoiceEvent{Event: eventType, Data: data}
+			}
+		}
+
+		for scanner.Scan() {
+			line := scanner.Text()
+			switch {
+			case line == "":
+				dispatch()
+				eventType = ""
+				dataLines = nil
+			case strings.HasPrefix(line, "event:"):
+				eventType = strings.TrimSpace(line[6:])
+			case strings.HasPrefix(line, "data:"):
+				dataLines = append(dataLines, strings.TrimSpace(line[5:]))
+			}
+		}
+		dispatch()
+
+		if err := scanner.Err(); err != nil {
+			errs <- err
+		}
+	}()
+
+	return events, errs
+}

keys.go

@@ -8,15 +8,6 @@ import (
 // KeysService handles API key operations.
 type KeysService struct{ c *Client }
 
-// List returns all API keys for the current wallet.
-func (s *KeysService) List(ctx context.Context) ([]APIKey, error) {
-	var v []APIKey
-	if err := s.c.get(ctx, "/v1/keys", &v); err != nil {
-		return nil, err
-	}
-	return v, nil
-}
-
 // Rotate rotates the API key at the given slot (0 = primary, 1 = secondary).
 func (s *KeysService) Rotate(ctx context.Context, slot int) (*RotatedAPIKey, error) {
 	var v RotatedAPIKey

l402.go

@@ -0,0 +1,33 @@
+package lnbot
+
+import "context"
+
+// L402Service handles L402 paywall authentication operations.
+type L402Service struct{ c *Client }
+
+// CreateChallenge creates an L402 challenge (invoice + macaroon) for paywall authentication.
+func (s *L402Service) CreateChallenge(ctx context.Context, params *CreateL402ChallengeParams) (*L402Challenge, error) {
+	var v L402Challenge
+	if err := s.c.post(ctx, "/v1/l402/challenges", params, &v); err != nil {
+		return nil, err
+	}
+	return &v, nil
+}
+
+// Verify verifies an L402 authorization token. Stateless — checks signature, preimage, and caveats.
+func (s *L402Service) Verify(ctx context.Context, params *VerifyL402Params) (*VerifyL402Response, error) {
+	var v VerifyL402Response
+	if err := s.c.post(ctx, "/v1/l402/verify", params, &v); err != nil {
+		return nil, err
+	}
+	return &v, nil
+}
+
+// Pay pays an L402 challenge and returns a ready-to-use Authorization header.
+func (s *L402Service) Pay(ctx context.Context, params *PayL402Params) (*L402PayResponse, error) {
+	var v L402PayResponse
+	if err := s.c.post(ctx, "/v1/l402/pay", params, &v); err != nil {
+		return nil, err
+	}
+	return &v, nil
+}

lnbot.go

@@ -18,7 +18,7 @@ const (
 	defaultTimeout = 30 * time.Second
 
 	// Version is the SDK version sent in the User-Agent header.
-	Version = "0.4.0"
+	Version = "0.5.0"
 )
 
 // Option configures the Client.
@@ -50,6 +50,7 @@ type Client struct {
 	Events       *EventsService
 	Backup       *BackupService
 	Restore      *RestoreService
+	L402         *L402Service
 }
 
 // New creates a new LnBot client.
@@ -73,6 +74,7 @@ func New(apiKey string, opts ...Option) *Client {
 	c.Events = &EventsService{c: c}
 	c.Backup = &BackupService{c: c}
 	c.Restore = &RestoreService{c: c}
+	c.L402 = &L402Service{c: c}
 	return c
 }
 

payments.go

@@ -45,6 +45,15 @@ func (s *PaymentsService) Get(ctx context.Context, number int) (*Payment, error)
 	return &v, nil
 }
 
+// GetByHash returns a single payment by its payment hash.
+func (s *PaymentsService) GetByHash(ctx context.Context, paymentHash string) (*Payment, error) {
+	var v Payment
+	if err := s.c.get(ctx, fmt.Sprintf("/v1/payments/%s", paymentHash), &v); err != nil {
+		return nil, err
+	}
+	return &v, nil
+}
+
 // Watch opens an SSE stream and sends events to the returned channel.
 // The channel is closed when the stream ends. Cancel the context to abort.
 func (s *PaymentsService) Watch(ctx context.Context, number int, timeout *int) (<-chan PaymentEvent, <-chan error) {
@@ -122,3 +131,81 @@ func (s *PaymentsService) Watch(ctx context.Context, number int, timeout *int) (
 
 	return events, errs
 }
+
+// WatchByHash opens an SSE stream for a payment identified by payment hash.
+// The channel is closed when the stream ends. Cancel the context to abort.
+func (s *PaymentsService) WatchByHash(ctx context.Context, paymentHash string, timeout *int) (<-chan PaymentEvent, <-chan error) {
+	events := make(chan PaymentEvent, 1)
+	errs := make(chan error, 1)
+
+	go func() {
+		defer close(events)
+		defer close(errs)
+
+		path := fmt.Sprintf("%s/v1/payments/%s/events", s.c.baseURL, paymentHash)
+		if timeout != nil {
+			path = fmt.Sprintf("%s?timeout=%d", path, *timeout)
+		}
+
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, path, nil)
+		if err != nil {
+			errs <- err
+			return
+		}
+		req.Header.Set("Accept", "text/event-stream")
+		req.Header.Set("User-Agent", "lnbot-go/"+Version)
+		if s.c.apiKey != "" {
+			req.Header.Set("Authorization", "Bearer "+s.c.apiKey)
+		}
+
+		resp, err := s.c.http.Do(req)
+		if err != nil {
+			errs <- err
+			return
+		}
+		defer resp.Body.Close()
+
+		if resp.StatusCode >= 400 {
+			body, _ := io.ReadAll(resp.Body)
+			errs <- parseAPIError(resp.StatusCode, body)
+			return
+		}
+
+		scanner := bufio.NewScanner(resp.Body)
+		var (
+			eventType string
+			dataLines []string
+		)
+		dispatch := func() {
+			if eventType == "" || len(dataLines) == 0 {
+				return
+			}
+			raw := strings.Join(dataLines, "\n")
+			var data Payment
+			if json.Unmarshal([]byte(raw), &data) == nil {
+				events <- PaymentEvent{Event: eventType, Data: data}
+			}
+		}
+
+		for scanner.Scan() {
+			line := scanner.Text()
+			switch {
+			case line == "":
+				dispatch()
+				eventType = ""
+				dataLines = nil
+			case strings.HasPrefix(line, "event:"):
+				eventType = strings.TrimSpace(line[6:])
+			case strings.HasPrefix(line, "data:"):
+				dataLines = append(dataLines, strings.TrimSpace(line[5:]))
+			}
+		}
+		dispatch()
+
+		if err := scanner.Err(); err != nil {
+			errs <- err
+		}
+	}()
+
+	return events, errs
+}

types.go

@@ -46,15 +46,6 @@ type UpdateWalletParams struct {
 // API Keys
 // ---------------------------------------------------------------------------
 
-// APIKey represents an API key's metadata.
-type APIKey struct {
-	ID         string     `json:"id"`
-	Name       string     `json:"name"`
-	Hint       string     `json:"hint"`
-	CreatedAt  *time.Time `json:"createdAt"`
-	LastUsedAt *time.Time `json:"lastUsedAt"`
-}
-
 // RotatedAPIKey is returned after rotating an API key.
 type RotatedAPIKey struct {
 	Key  string `json:"key"`
@@ -298,3 +289,57 @@ type PasskeyAssertionParams struct {
 	SessionID string         `json:"sessionId"`
 	Assertion map[string]any `json:"assertion"`
 }
+
+// ---------------------------------------------------------------------------
+// L402
+// ---------------------------------------------------------------------------
+
+// CreateL402ChallengeParams are the parameters for creating an L402 challenge.
+type CreateL402ChallengeParams struct {
+	Amount        int64    `json:"amount"`
+	Description   *string  `json:"description,omitempty"`
+	ExpirySeconds *int     `json:"expirySeconds,omitempty"`
+	Caveats       []string `json:"caveats,omitempty"`
+}
+
+// L402Challenge is returned when an L402 challenge is created.
+type L402Challenge struct {
+	Macaroon        string    `json:"macaroon"`
+	Invoice         string    `json:"invoice"`
+	PaymentHash     string    `json:"paymentHash"`
+	ExpiresAt       time.Time `json:"expiresAt"`
+	WwwAuthenticate string    `json:"wwwAuthenticate"`
+}
+
+// VerifyL402Params are the parameters for verifying an L402 token.
+type VerifyL402Params struct {
+	Authorization string `json:"authorization"`
+}
+
+// VerifyL402Response is returned when verifying an L402 token.
+type VerifyL402Response struct {
+	Valid       bool     `json:"valid"`
+	PaymentHash *string  `json:"paymentHash"`
+	Caveats     []string `json:"caveats"`
+	Error       *string  `json:"error"`
+}
+
+// PayL402Params are the parameters for paying an L402 challenge.
+type PayL402Params struct {
+	WwwAuthenticate string  `json:"wwwAuthenticate"`
+	MaxFee          *int64  `json:"maxFee,omitempty"`
+	Reference       *string `json:"reference,omitempty"`
+	Wait            *bool   `json:"wait,omitempty"`
+	Timeout         *int    `json:"timeout,omitempty"`
+}
+
+// L402PayResponse is returned after paying an L402 challenge.
+type L402PayResponse struct {
+	Authorization *string `json:"authorization"`
+	PaymentHash   string  `json:"paymentHash"`
+	Preimage      *string `json:"preimage"`
+	Amount        int64   `json:"amount"`
+	Fee           *int64  `json:"fee"`
+	PaymentNumber int     `json:"paymentNumber"`
+	Status        string  `json:"status"`
+}