feat: add Alby NWC payments processor (#323)

[Justxd22]

Add new alby payments processor using NIP-47 NWC (make_invoice, lookup_invoice)

Description

• Wire processor into settings/factory flow
• Add paymentsProcessors.alby config:
  • invoiceExpirySeconds
  • replyTimeoutMs
• Accept both NWC URI schemes for compatibility:
  • nostr+walletconnect://...
  • nostrwalletconnect://...
• Use make_invoice for invoice generation.
• lookup_invoice for polling/status reconciliation.
• State mapping to relay invoice lifecycle (pending/accepted/settled/failed/expired -> internal status).
• Configurable reply-timeout enforcement and expiry propagation.
• Update docs and defaults (README.md, CONFIGURATION.md, .env.example, default-settings.yaml).

Related Issue

#323

How Has This Been Tested?

• Added processor unit tests for:
  • response/state mapping
  • timeout enforcement from config
  • expiry parameter propagation/mapping
  • timer cleanup on successful fast responses
• Added factory tests for:
  • required env/config validation
  • legacy URI compatibility

Screenshots:

Types of changes

• Non-functional change (docs, style, minor refactor)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my code changes.
• I added a changeset, or this is docs-only and I added an empty changeset.
• All new and existing tests passed.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​getalby/​sdk@​5.1.2

View full report

[Copilot]

Pull request overview

Adds a new Alby payments processor implementation using NIP-47 Nostr Wallet Connect (NWC) for invoice creation and status lookup, wired into the existing payments processor selection flow.

Changes:

• Implement AlbyNwcPaymentsProcessor (create via make_invoice, reconcile via lookup_invoice) with configurable reply-timeout and invoice expiry handling.
• Add a factory + switch-case wiring to select alby as payments.processor, including env/config validation and unit tests.
• Update defaults and documentation (default-settings.yaml, .env.example, README.md, CONFIGURATION.md) and add a changeset.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/unit/payments-processors/alby-nwc-payments-processor.spec.ts	Adds unit tests for NWC response/state mapping, timeouts, and expiry propagation.
test/unit/factories/payments-processors/alby-nwc-payments-processor-factory.spec.ts	Adds factory validation tests for env/config and legacy URI scheme support.
src/payments-processors/alby-nwc-payments-processor.ts	New NWC-based payments processor implementation.
src/factories/payments-processors/alby-nwc-payments-processor-factory.ts	New factory to validate config/env and construct the Alby NWC processor.
src/factories/payments-processor-factory.ts	Wires alby into the payments processor selection switch.
src/@types/settings.ts	Adds paymentsProcessors.alby settings type.
resources/default-settings.yaml	Adds default Alby processor settings (expiry + reply timeout).
package.json	Adds @getalby/sdk dependency.
README.md	Documents Alby NWC setup steps and adds alby to the supported processor list.
CONFIGURATION.md	Documents ALBY_NWC_URL and extends payments.processor allowed values.
.env.example	Adds ALBY_NWC_URL example value.
.changeset/seven-lines-heal.md	Adds a minor-version changeset entry for the feature.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Justxd22]

How to test

1. please pull this PR
2. change these in your settings.yaml:

payments:
  enabled: true
  processor: alby
paymentsProcessors:
  alby:
    invoiceExpirySeconds: 900
    replyTimeoutMs: 10000

3. now you need NWC key in your env, use alby facut:

curl -X POST "https://faucet.nwc.dev?balance=10000"

4. paste the key in your .env:

ALBY_NWC_URL=nostr+walletconnect://....

Done run your relay and test invoices

[coveralls]

coverage: 74.883% (+0.3%) from 74.55% — Justxd22:feat/nwc-alby into cameri:main

[Justxd22]

addressing copilot comments

[Justxd22]

@cameri Added @alby-nwc-invoice integration coverage for /invoices with a local in-process NWC wallet service. It verifies three paths: successful invoice creation, timeout-to-500 behavior, and legacy nostrwalletconnect:// URI acceptance, with deterministic setup/teardown for settings, env, and DB cleanup!

Ready

[cameri]

let's please call this logger not debug