Compare commits

..

1 Commits

27 changed files with 833 additions and 1435 deletions
-59
View File
@@ -1,59 +0,0 @@
name: Docker
on:
push:
branches: [master]
env:
REGISTRY: gitea.coracle.social
jobs:
build-and-push-image:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
strategy:
matrix:
include:
- component: frontend
image: coracle/caravel-frontend
context: frontend
- component: backend
image: coracle/caravel-backend
context: backend
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Log in to the Container registry
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: hodlbod
password: ${{ secrets.PACKAGE_TOKEN }}
- name: Extract metadata (tags, labels) for Docker
id: meta
uses: docker/metadata-action@v5
with:
images: ${{ env.REGISTRY }}/${{ matrix.image }}
tags: |
type=raw,value=latest,enable=${{ github.ref == 'refs/heads/master' }}
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
with:
driver: docker-container
- name: Build and push Docker image
id: push
uses: docker/build-push-action@v5
with:
context: ${{ matrix.context }}
push: true
platforms: linux/amd64,linux/arm64
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
+1 -1
View File
@@ -26,7 +26,7 @@ docker run -it \
-v ./config:/app/config \
-v ./media:/app/media \
-v ./data:/app/data \
gitea.coracle.social/coracle/zooid
ghcr.io/coracle-social/zooid
```
### 2. Configure the backend
-9
View File
@@ -26,17 +26,8 @@ LIVEKIT_URL=
LIVEKIT_API_KEY=
LIVEKIT_API_SECRET=
# Blossom S3 (optional; when region, bucket, access key, and secret are all set, relays with blossom enabled sync with adapter s3 and key_prefix = relay schema)
BLOSSOM_S3_ENDPOINT=
BLOSSOM_S3_REGION=
BLOSSOM_S3_BUCKET=
BLOSSOM_S3_ACCESS_KEY=
BLOSSOM_S3_SECRET_KEY=
# Billing
NWC_URL= # Nostr Wallet Connect URL for generating Lightning invoices
ENCRYPTION_SECRET= # Nostr secret key (hex or nsec) used to encrypt tenant NWC URLs at rest
STRIPE_SECRET_KEY= # Required Stripe API secret key (sk_...)
STRIPE_WEBHOOK_SECRET=whsec_test_00000000000000000000000000 # Webhook signing secret (use real value in production)
STRIPE_PRICE_BASIC= # Stripe price ID (price_...) for the Basic plan; required for paid plans
STRIPE_PRICE_GROWTH= # Stripe price ID (price_...) for the Growth plan; required for paid plans
-7
View File
@@ -43,17 +43,10 @@ Environment variables:
| `LIVEKIT_URL` | LiveKit URL sent to zooid when relay livekit is enabled | _optional_ |
| `LIVEKIT_API_KEY` | LiveKit API key sent to zooid | _optional_ |
| `LIVEKIT_API_SECRET` | LiveKit API secret sent to zooid | _optional_ |
| `BLOSSOM_S3_ENDPOINT` | S3-compatible endpoint URL for Blossom; omit for AWS S3 | _optional_ |
| `BLOSSOM_S3_REGION` | S3 region; with bucket, access key, and secret enables S3 for Blossom | _optional_ |
| `BLOSSOM_S3_BUCKET` | S3 bucket name | _optional_ |
| `BLOSSOM_S3_ACCESS_KEY` | S3 access key ID | _optional_ |
| `BLOSSOM_S3_SECRET_KEY` | S3 secret access key | _optional_ |
| `NWC_URL` | Platform NWC URL used to generate BOLT11 invoices | _required for invoice generation_ |
| `ENCRYPTION_SECRET` | Nostr secret key (hex or nsec) used to encrypt tenant NWC URLs at rest | _required_ |
| `STRIPE_SECRET_KEY` | Stripe API secret key used for billing API operations | _required_ |
| `STRIPE_WEBHOOK_SECRET` | Stripe webhook signing secret used to verify `Stripe-Signature` headers | _required_ |
| `STRIPE_PRICE_BASIC` | Stripe price ID (`price_...`) backing the Basic plan | _required for paid plans_ |
| `STRIPE_PRICE_GROWTH` | Stripe price ID (`price_...`) backing the Growth plan | _required for paid plans_ |
| `ROBOT_SECRET` | Robot Nostr secret key | _required_ |
| `ROBOT_NAME` | Robot display name (kind `0`) | _optional_ |
| `ROBOT_DESCRIPTION` | Robot description (kind `0`) | _optional_ |
+41 -56
View File
@@ -2,47 +2,45 @@
Billing encapsulates logic related to synchronizing state with Stripe, processing payments via NWC, and managing subscription lifecycle.
It owns the domain logic only: every raw Stripe REST call goes through the `Stripe` wrapper (see `spec/stripe.md`), and every Lightning (NWC) wallet operation and the fiat-minor-units → millisatoshi conversion go through the helpers in `spec/bitcoin.md`.
Members:
- `stripe: Stripe` - thin wrapper around the Stripe REST API (see `spec/stripe.md`), built from `STRIPE_SECRET_KEY` / `STRIPE_WEBHOOK_SECRET`
- `bitcoin: Bitcoin` - the Bitcoin-facing config: system NWC wallet (`NWC_URL`) plus the BTC price-feed HTTP client (see `spec/bitcoin.md`)
- `nwc_url: String` - a nostr wallet connect URL used to **create** bolt11 invoices (i.e. receive payments), from `NWC_URL`
- `stripe_secret_key: String` - Stripe API key used for billing API operations, from `STRIPE_SECRET_KEY`
- `stripe_webhook_secret: String` - secret for verifying Stripe webhook signatures, from `STRIPE_WEBHOOK_SECRET`
- `query: Query`
- `command: Command`
- `robot: Robot`
## `pub fn new(query: Query, command: Command, robot: Robot) -> Self`
- Builds `stripe` via `Stripe::from_env()` and `bitcoin` via `Bitcoin::from_env()`
- Panics if `STRIPE_SECRET_KEY` or `STRIPE_WEBHOOK_SECRET` is missing/empty (`NWC_URL` is optional)
- Reads environment and populates members
- Panics if `STRIPE_SECRET_KEY` is missing/empty
- Panics if `STRIPE_WEBHOOK_SECRET` is missing/empty
## `pub fn start(&self)`
- Subscribes to `command.notify.subscribe()`
- On `create_relay`, `update_relay`, `activate_relay`, `deactivate_relay`, `fail_relay_sync`, and `complete_relay_sync`: resolve the relay named by the activity (skip if it no longer exists) and reconcile its tenant via `sync_tenant_subscription`.
- The startup/lagged reconcile loop calls `sync_tenant_subscription` for every tenant.
- On `create_relay`, `update_relay`, `activate_relay`, `deactivate_relay`, `fail_relay_sync`, and `complete_relay_sync`, call `self.sync_relay_subscription`.
## `fn sync_tenant_subscription(&self, tenant_pubkey: &str)`
## `pub fn sync_relay_subscription(&self, activity: &Activity)`
Reconciles a tenant's single Stripe subscription with the set of relays that should be billed. Only paid (non-free) relays interact with Stripe. Free-only tenants have no subscription. Must be idempotent.
Stripe forbids two subscription items on the same subscription from sharing a price, so billing is modeled as **one subscription item per plan (price), with `quantity` equal to the number of the tenant's `active` relays on that plan**. Every such relay's `stripe_subscription_item_id` points at the shared item for its plan; relays that aren't billed (free, inactive, delinquent) have it cleared.
Manages the Stripe subscription and subscription items for a relay's tenant. Only paid (non-free) relays interact with Stripe. Free-only tenants have no subscription. Must be idempotent.
Stripe uses **pay-in-advance** by default: when a subscription is first created, Stripe immediately generates an open invoice for the current period. The `invoice.created` webhook fires shortly after and `handle_invoice_created` attempts payment.
- Fetch the tenant and its relays. Build the desired state: for each `active` relay on a paid plan with a non-empty `stripe_price_id`, count relays per price.
- **Resolve the live subscription**: if the tenant has a `stripe_subscription_id`, fetch it. If Stripe no longer knows about it, or its status is `canceled`/`incomplete_expired`, call `command.clear_tenant_subscription` and treat the tenant as having no subscription.
- **No relays to bill** (desired state empty): if the tenant still has a `stripe_subscription_id`, cancel the Stripe subscription and call `command.clear_tenant_subscription`. Clear `stripe_subscription_item_id` on every relay that has one. Return.
- **No subscription yet**: create a Stripe subscription for the customer with `collection_method: "charge_automatically"` and one item per `(price, quantity)`. Save the subscription ID via `command.set_tenant_subscription`.
- **Existing subscription**: fetch its current items. For each desired `(price, quantity)`: update the matching item's quantity if it differs, otherwise create the item. Delete any item whose price no longer appears in the desired state.
- **Point relays at items**: for each relay, set `stripe_subscription_item_id` (via `command.set_relay_subscription_item`) to the shared item for its plan, or clear it (via `command.delete_relay_subscription_item`) if the relay is not billed.
- **Downgrade validation**: if any quantity decreased or any item was removed, preview the upcoming Stripe invoice and log proration line/amount details to validate expected credit/proration behavior.
- Fetch the relay and tenant associated with the `activity`
- **If relay plan is `free`**: if the relay has a `stripe_subscription_item_id`, delete it via the Stripe API and call `command.delete_relay_subscription_item`. Then run downgrade proration validation by previewing the upcoming invoice and logging proration lines/amounts. Then check cleanup (below). Return early.
- **If relay is `inactive` or `delinquent`**: if the relay has a `stripe_subscription_item_id`, delete it via the Stripe API and call `command.delete_relay_subscription_item`. Then check cleanup (below). Return early.
- **If relay is `active` and on a paid plan**:
- **Ensure subscription exists**: If the tenant has no `stripe_subscription_id`, create a Stripe subscription for the customer with `collection_method: "charge_automatically"` and the relay's price as the first item. Save the subscription ID via `command.set_tenant_subscription` and the item ID via `command.set_relay_subscription_item`. Return early.
- **Sync the subscription item**: If the tenant already has a subscription, create or update the relay's Stripe subscription item to the plan's `stripe_price_id` via the Stripe API, then call `command.set_relay_subscription_item`.
- **Downgrade validation**: when changing an existing subscription item, detect if the new plan amount is lower than the current one. If yes, preview the upcoming Stripe invoice and log proration line/amount details to validate expected credit/proration behavior.
- **Clean up empty subscription**: After any item deletion, check if the tenant has any remaining active paid relays. If none and the tenant has a `stripe_subscription_id`, cancel the Stripe subscription immediately and call `command.clear_tenant_subscription`.
## `pub fn handle_webhook(&self, payload: &str, signature: &str) -> Result<()>`
- Verify and parse the event via `self.stripe.construct_event(payload, signature)` (checks the `Stripe-Signature` HMAC and timestamp tolerance — see `spec/stripe.md`)
- Dispatch by type:
- Verify the webhook signature using `self.stripe_webhook_secret`
- Parse the event and dispatch by type:
- `invoice.created` -> `self.handle_invoice_created`
- `invoice.paid` -> `self.handle_invoice_paid`
- `invoice.payment_failed` -> `self.handle_invoice_payment_failed`
@@ -52,69 +50,56 @@ Stripe uses **pay-in-advance** by default: when a subscription is first created,
- `payment_method.attached` -> `self.handle_payment_method_attached`
- Unknown event types are ignored (return Ok)
## `pub async fn stripe_create_customer(&self, tenant_pubkey: &str) -> Result<String>`
- Resolves a display name via `robot.fetch_nostr_name(tenant_pubkey)`, falling back to the first 8 chars of the pubkey
- Creates the Stripe customer via `stripe.create_customer(display_name, tenant_pubkey)` and returns its id
## `pub async fn stripe_list_invoices(&self, customer_id: &str) -> Result<Value>`
- Delegates to `stripe.list_invoices` — returns the `data` array of the customer's invoices
- Fetches invoices from Stripe API for the given customer
- Returns the `data` array from the Stripe response
## `pub async fn stripe_create_portal_session(&self, customer_id: &str, return_url: Option<&str>) -> Result<String>`
## `pub async fn stripe_get_invoice(&self, invoice_id: &str) -> Result<Value>`
- Delegates to `stripe.create_portal_session` — returns the Customer Portal session URL
- Fetches a single invoice from Stripe API by ID
- Returns the full Stripe invoice object
## `pub async fn get_invoice_with_tenant(&self, invoice_id: &str) -> Result<(Value, Tenant), InvoiceLookupError>`
## `pub async fn create_bolt11(&self, amount_due_cents: i64) -> Result<String>`
- Fetches the invoice via `stripe.get_invoice` (a Stripe 4xx surfaces as `InvoiceLookupError::StripeClient`)
- Looks up the tenant by the invoice's `customer` field; errors if the invoice has no customer or no tenant matches
## `pub async fn reconcile_manual_lightning_invoice(&self, invoice_id: &str, invoice: &Value) -> Result<Value, InvoiceLookupError>`
If `invoice.status == "open"` and a manual-Lightning bolt11 was previously issued for it (`query.get_invoice_manual_lightning_bolt11`), check whether that bolt11 has settled (`bitcoin.system_wallet().invoice_settled(...)`). If it has, mark the Stripe invoice paid out of band (`stripe.pay_invoice_out_of_band`) and return the refreshed invoice. On any lookup/settlement failure, log and return the invoice unchanged.
## `pub async fn get_or_create_manual_lightning_bolt11(&self, invoice_id: &str, tenant_pubkey: &str, amount_due_minor: i64, currency: &str) -> Result<String>`
- Returns the existing bolt11 if one is already recorded for the invoice
- Otherwise creates one via `create_bolt11`, records it with `command.insert_manual_lightning_invoice_payment`, and returns it (re-reading the stored row if the insert lost a race)
## `pub async fn create_bolt11(&self, amount_due_minor: i64, currency: &str) -> Result<String>`
- Converts the fiat amount to msats via `bitcoin.fiat_minor_to_msats` (fetches the live BTC spot price — see `spec/bitcoin.md`)
- Issues a bolt11 invoice for that amount on the system NWC wallet (`bitcoin.system_wallet().make_invoice(...)`)
- Creates a bolt11 Lightning invoice for the given amount using the system NWC wallet (`self.nwc_url`)
- Returns the bolt11 invoice string
## `pub async fn stripe_create_portal_session(&self, customer_id: &str) -> Result<String>`
- Creates a Stripe Customer Portal session for the given customer
- Returns the portal session URL
## `pub async fn pay_outstanding_nwc_invoices(&self, tenant: &Tenant) -> Result<()>`
Called when a tenant first sets their NWC URL (via `PUT /tenants/:pubkey`). Attempts to pay any currently open invoices for the tenant using their NWC wallet, so that invoices created before NWC was configured are not left unpaid.
- If `tenant.nwc_url` is empty, return early.
- List all Stripe invoices for `tenant.stripe_customer_id` via `stripe.list_invoices`.
- List all Stripe invoices for `tenant.stripe_customer_id` via `stripe_list_invoices`.
- For each invoice with `status == "open"` and `amount_due > 0`:
- Attempt NWC payment via `nwc_pay_invoice`.
- On success: mark the Stripe invoice paid out of band (`stripe.pay_invoice_out_of_band`) and call `command.clear_tenant_nwc_error`.
- On success: call `stripe_pay_invoice_out_of_band` and `command.clear_tenant_nwc_error`.
- On failure: call `command.set_tenant_nwc_error` and log the error; continue to the next invoice.
## `pub async fn pay_outstanding_card_invoices(&self, tenant: &Tenant) -> Result<()>`
Attempts Stripe-side collection for open invoices when the tenant has a card on file.
- If tenant has no card payment method (`stripe.has_payment_method`), return early.
- List all Stripe invoices for `tenant.stripe_customer_id` via `stripe.list_invoices`.
- If tenant has no card payment method, return early.
- List all Stripe invoices for `tenant.stripe_customer_id`.
- For each invoice with `status == "open"` and `amount_due > 0`:
- Call `stripe.pay_invoice` to retry collection using the card on file.
- Call Stripe `POST /v1/invoices/:id/pay` to retry collection using the card on file.
- Log and continue on failures.
## `fn handle_invoice_created(&self, invoice: &Invoice)`
Attempts to pay a new subscription invoice. Because Stripe defaults to pay-in-advance, this webhook fires immediately when a subscription is created (i.e. when a paid relay is added or a plan is upgraded). Payment priority:
1. **NWC auto-pay**: If the tenant has a `nwc_url`, run `nwc_pay_invoice` (decrypting the tenant's stored `nwc_url` first):
- The system wallet (`bitcoin.system_wallet()`) issues a bolt11 invoice for the fiat amount; the tenant's wallet (`Wallet::parse` of the decrypted URL) pays it. A `pending` row in `invoice_nwc_payment` guards against double-charging across retries.
- If payment succeeds: mark the Stripe invoice paid out of band (`stripe.pay_invoice_out_of_band`) and clear `nwc_error` via `command.clear_tenant_nwc_error`. Done.
- If it fails before any charge could have gone out: set `nwc_error` on the tenant via `command.set_tenant_nwc_error`, and fall through to the next option (carrying a short summary of the error into the eventual DM).
- If it fails after a charge may have gone out (needs reconciliation): set `nwc_error` and return the error without falling through — a human must reconcile before any retry.
1. **NWC auto-pay**: If the tenant has a `nwc_url`:
- Create a bolt11 Lightning invoice for the invoice amount using `self.nwc_url` (the receiving/system wallet)
- Pay the bolt11 invoice using the tenant's `nwc_url` (the spending/tenant wallet)
- If payment succeeds: call Stripe `POST /v1/invoices/:id/pay` with `paid_out_of_band: true`. Clear `nwc_error` via `command.clear_tenant_nwc_error`.
- If payment fails: set `nwc_error` on tenant via `command.set_tenant_nwc_error`. Fall through to next option.
2. **Card on file**: If the tenant has a payment method on the Stripe customer, do nothing here — Stripe will charge automatically for this invoice attempt.
3. **Manual payment**: If neither NWC nor card is available, send a DM via `robot.send_dm` notifying the tenant that payment is due with a link to the application for manual Lightning payment.
-62
View File
@@ -1,62 +0,0 @@
# `bitcoin` — Bitcoin / Lightning helpers
Small wrappers around the Bitcoin-facing services the app talks to: Nostr Wallet Connect (NWC) wallets for Lightning invoices/payments, and a fiat↔BTC spot price feed, plus the fiat-minor-units → millisatoshi conversion that ties them together. The billing-specific orchestration (which wallet pays which invoice, double-charge guards, DMs, etc.) lives in `spec/billing.md`.
## `pub struct Bitcoin`
Owns the app's Bitcoin-facing configuration: the system NWC wallet URL (the wallet used to *receive* payments — issue and look up bolt11 invoices) and the HTTP client used for the fiat↔BTC spot price feed.
Members:
- `system_nwc_url: String` - from `NWC_URL`
- `http: reqwest::Client`
### `pub fn from_env() -> Self`
Reads `NWC_URL` (the system / receiving wallet) and constructs a fresh `reqwest::Client`. Unlike the Stripe keys, `NWC_URL` is **optional**: if it's unset, Lightning operations fail at use time with a clear error rather than panicking at startup. This is what `Billing::new` calls.
### `pub fn system_wallet(&self) -> Result<Wallet>`
Returns the system `Wallet` (parsed from `system_nwc_url` with label `"system"`). Errors if `NWC_URL` is unset or malformed.
### `pub async fn fiat_minor_to_msats(&self, amount_due_minor: i64, currency: &str) -> Result<u64>`
Fetches the live BTC spot price (via `btc_spot_price_from_base` against Coinbase) for `currency` and converts `amount_due_minor` to millisatoshis via `fiat_minor_to_msats_from_quote`. `currency` is upper-cased before use.
## `pub struct Wallet`
A handle to a single NWC wallet. Each operation opens a fresh NWC connection and tears it down (`shutdown`) afterwards.
Member:
- `uri: NostrWalletConnectURI` - the parsed `nostr+walletconnect://…` URI
### `pub fn parse(uri: &str, label: &str) -> Result<Self>`
Parses an `nostr+walletconnect://` URI. `label` (e.g. `"system"` / `"tenant"`) only flavours the error message — `invalid {label} NWC URL` — so callers can tell which wallet was misconfigured.
### `pub async fn make_invoice(&self, amount_msats: u64, description: &str) -> Result<String>`
Issues a bolt11 invoice for `amount_msats` with the given description. Returns the bolt11 string.
### `pub async fn pay_invoice(&self, bolt11: String) -> Result<()>`
Pays a bolt11 invoice.
### `pub async fn invoice_settled(&self, bolt11: &str) -> Result<bool>`
Looks up a bolt11 invoice (previously issued by this wallet) and returns whether it has settled — true if the transaction state is `Settled` or `settled_at` is present.
## `pub async fn btc_spot_price_from_base(http: &reqwest::Client, api_base: &str, currency: &str) -> Result<f64>`
Fetches the BTC spot price denominated in `currency` (an ISO-4217 code) from a Coinbase-shaped API at `api_base` (`{api_base}/BTC-{currency}/spot`); production callers reach it via `Bitcoin::fiat_minor_to_msats` with the real Coinbase base, while tests can point it at a stub. Errors if the quote is missing, unparseable, or non-positive.
## `pub fn fiat_minor_to_msats_from_quote(amount_due_minor: i64, currency: &str, btc_price_in_fiat: f64) -> Result<u64>`
Converts a fiat amount expressed in minor units (cents, etc.) to millisatoshis, given a BTC price quote in that currency.
- Errors if `amount_due_minor <= 0` or `btc_price_in_fiat <= 0`
- Converts minor units to a major-unit amount using the currency's decimal exponent (most currencies 2; `JPY`/`KRW`/… 0; `BHD`/`KWD`/… 3 — following Stripe's currency conventions; an unrecognized or malformed code is an error)
- `msats = (amount_fiat / btc_price_in_fiat) * 100_000_000_000`
- Rounds **up** so we never under-charge, but snaps to the nearest integer when within `1e-6` of one to avoid floating-point artifacts at integer boundaries
- Errors if the result is non-finite, non-positive, or exceeds `u64::MAX`
-2
View File
@@ -5,7 +5,6 @@ Infra is a service which listens for activity and synchronizes relay updates to
Members:
- `api_url: String` - the URL of the zooid instance to be managed, from `ZOOID_API_URL`
- `blossom_s3: Option<BlossomS3Sync>` - shared Blossom S3 settings from `BLOSSOM_S3_*` when region, bucket, access key, and secret are all non-empty after trim
- `query: Query`
- `command: Command`
@@ -37,4 +36,3 @@ Members:
- Otherwise, sends `PATCH /relay/:id` to update it.
- Includes `secret` only for relay creation (`POST`) so updates do not rotate relay identity.
- Passes relay configuration in the body including host, schema, inactive flag, info, policy, groups, management, blossom, livekit, push, and roles.
- When `blossom_s3` is configured and the relay has blossom enabled, the blossom section includes `adapter: "s3"`, S3 fields from the environment, and `s3.key_prefix` set to the relay's `schema`. Otherwise blossom omits S3 (zooid defaults to local storage) or sends `{ "enabled": false }` when blossom is disabled.
+2 -2
View File
@@ -63,9 +63,9 @@ Tenants are customers of the service, identified by a nostr `pubkey`. Public met
A relay is a nostr relay owned by a `tenant` and hosted by the attached zooid instance. Relay subdomains MUST be unique.
- `id` - calculated based on `subdomain` + 8 random hex chars
- `id` - a random ID identifying the relay
- `tenant` - the tenant's pubkey
- `schema` - the relay's db schema (read only, same as `id`)
- `schema` - the relay's db schema (read_only, calculated based on `subdomain` + `id`)
- `subdomain` - the relay's subdomain
- `plan` - the relay's plan
- `stripe_subscription_item_id` (nullable) - the Stripe subscription item id. Only set for relays on paid plans.
+4
View File
@@ -39,6 +39,10 @@ Members:
- Returns the tenant matching the given `stripe_customer_id`
## `pub fn has_active_paid_relays(&self, tenant_id: &str) -> Result<bool>`
- Returns true if the tenant has any relays where `status = 'active'` and `plan != 'free'`
## `pub fn list_activity_for_relay(&self, relay_id: &str) -> Result<Vec<Activity>>`
- Returns all activity where `resource_type = 'relay'` and `resource_id = relay_id`
-113
View File
@@ -1,113 +0,0 @@
# `pub struct Stripe`
A thin async wrapper around the subset of the Stripe REST API this service uses. It knows nothing about relays, tenants, or the database — it just speaks HTTP to Stripe and returns `serde_json::Value` (or small typed results). The domain logic that drives it lives in `spec/billing.md`.
Members:
- `secret_key: String` - Stripe API key, used as the bearer token and as the HMAC key for idempotency keys
- `webhook_secret: String` - secret for verifying Stripe webhook signatures
- `http: reqwest::Client`
All requests authenticate with `secret_key` via `Authorization: Bearer`. Write requests that must not be retried twice (customer/subscription/item creation, invoice payment) send a deterministic `Idempotency-Key` derived by HMAC-ing the operation name and its arguments with `secret_key`. Reconcile-to-desired-state writes (e.g. setting an item quantity) intentionally omit the idempotency key, since re-applying the same target is a no-op.
On any 4xx/5xx response, the wrapper reads the body and folds Stripe's JSON error payload (`error.message` / `error.type` / `error.code` / `error.param`) into the returned error so callers get an actionable message instead of a bare status line.
## `pub fn from_env() -> Self`
Reads `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` (both required) and constructs the client. Panics if either is missing or blank. This is what `Billing::new` calls.
## `pub fn new(secret_key: String, webhook_secret: String) -> Self`
Constructs the client with a fresh `reqwest::Client` from explicit keys (does not touch the environment).
## `pub async fn create_customer(&self, name: &str, tenant_pubkey: &str) -> Result<String>`
- `POST /v1/customers` with `name` and `metadata[tenant_pubkey]`
- Idempotent on `tenant_pubkey`
- Returns the new customer id; errors if it isn't a `cus_…` id
## `pub async fn get_subscription(&self, subscription_id: &str) -> Result<Option<Value>>`
- `GET /v1/subscriptions/:id`
- Returns `None` if Stripe responds `404` (so callers can recover from a stale subscription id), otherwise the subscription object
## `pub async fn create_subscription(&self, customer_id: &str, items: &BTreeMap<String, i64>) -> Result<(String, BTreeMap<String, String>)>`
- `POST /v1/subscriptions` with `collection_method: charge_automatically` and one `items[n][price]` / `items[n][quantity]` pair per entry
- Idempotent on the customer and the `(price, quantity)` set
- Returns the subscription id and a map from price id to the created subscription item id
## `pub async fn create_subscription_item(&self, subscription_id: &str, price_id: &str, quantity: i64) -> Result<String>`
- `POST /v1/subscription_items`
- Idempotent on `(subscription_id, price_id)`
- Returns the new subscription item id
## `pub async fn set_subscription_item_quantity(&self, item_id: &str, quantity: i64) -> Result<()>`
- `POST /v1/subscription_items/:id` with `quantity`
- No idempotency key (reconcile-to-target write)
## `pub async fn delete_subscription_item(&self, item_id: &str) -> Result<()>`
- `DELETE /v1/subscription_items/:id`
## `pub async fn cancel_subscription(&self, subscription_id: &str) -> Result<()>`
- `DELETE /v1/subscriptions/:id`
## `pub async fn list_invoices(&self, customer_id: &str) -> Result<Value>`
- `GET /v1/invoices?customer=…`
- Returns the `data` array
## `pub async fn get_invoice(&self, invoice_id: &str) -> Result<Value, InvoiceLookupError>`
- `GET /v1/invoices/:id`
- On a 4xx response, returns `InvoiceLookupError::StripeClient { status }` (callers usually surface this as a client error, e.g. `404` "no such invoice"); other failures are `InvoiceLookupError::Internal`
- Returns the full invoice object
## `pub async fn pay_invoice(&self, invoice_id: &str) -> Result<()>`
- `POST /v1/invoices/:id/pay` (retries collection using the customer's default payment method)
- Idempotent on `invoice_id`
## `pub async fn pay_invoice_out_of_band(&self, invoice_id: &str) -> Result<()>`
- `POST /v1/invoices/:id/pay` with `paid_out_of_band: true` — used when payment was collected over Lightning rather than through Stripe
- Idempotent on `invoice_id`
## `pub async fn preview_upcoming_invoice(&self, customer_id: &str, subscription_id: Option<&str>) -> Result<Value>`
- `GET /v1/invoices/upcoming?customer=…[&subscription=…]`
- Used to validate proration when a subscription is downgraded
## `pub async fn has_payment_method(&self, customer_id: &str) -> Result<bool>`
- `GET /v1/payment_methods?customer=…&type=card`
- Returns whether the customer has at least one card on file
## `pub async fn create_portal_session(&self, customer_id: &str, return_url: Option<&str>) -> Result<String>`
- `POST /v1/billing_portal/sessions` with `customer` and optional `return_url`
- Returns the portal session URL
## `pub fn construct_event(&self, payload: &str, sig_header: &str) -> Result<Event>`
Verifies the `Stripe-Signature` header against `webhook_secret` and parses the body.
- Parse `t=` (timestamp) and `v1=` (signature) from the header
- Compute `HMAC-SHA256(webhook_secret, "{t}.{payload}")`, hex-encode it, and compare to `v1=`; error on mismatch
- Error if the timestamp is more than 300 seconds from now
- Returns the deserialized `Event` (`{ event_type, data: { object } }`)
# `pub enum InvoiceLookupError`
- `StripeClient { status: reqwest::StatusCode }` - Stripe returned a 4xx for an invoice lookup
- `Internal(anyhow::Error)` - any other failure
Implements `Display`/`Error` and `From<anyhow::Error>` / `From<reqwest::Error>` (both mapping to `Internal`).
# `pub struct Event` / `pub struct EventData`
The verified, parsed webhook event: `Event { event_type: String, data: EventData }`, `EventData { object: serde_json::Value }`.
+8 -18
View File
@@ -3,7 +3,7 @@ use std::sync::Arc;
use anyhow::{Result, anyhow};
use axum::{
Json, Router,
extract::{Path, Query as QueryParams, State},
extract::{Path, State},
http::{HeaderMap, StatusCode},
response::{IntoResponse, Response},
routing::{get, post},
@@ -12,14 +12,13 @@ use base64::Engine;
use nostr_sdk::{Event, JsonUtil, Kind};
use serde::{Deserialize, Serialize};
use crate::billing::Billing;
use crate::billing::{Billing, InvoiceLookupError};
use crate::command::Command;
use crate::infra::Infra;
use crate::models::{
RELAY_STATUS_ACTIVE, RELAY_STATUS_DELINQUENT, RELAY_STATUS_INACTIVE, Relay, Tenant,
};
use crate::query::Query;
use crate::stripe::InvoiceLookupError;
use axum::body::Bytes;
#[derive(Clone)]
@@ -276,6 +275,9 @@ impl Api {
return Err(RelayValidationError::PremiumFeature);
}
if relay.schema.is_empty() {
relay.schema = format!("{}_{}", relay.subdomain.replace('-', "_"), relay.id);
}
if relay.status.is_empty() {
relay.status = RELAY_STATUS_ACTIVE.to_string();
}
@@ -752,16 +754,10 @@ async fn create_relay(
let auth = state.api.extract_auth_pubkey(&headers)?;
state.api.require_admin_or_tenant(&auth, &payload.tenant)?;
let relay_id = format!(
"{}_{}",
payload.subdomain.replace('-', "_"),
&uuid::Uuid::new_v4().simple().to_string()[..8]
);
let mut relay = Relay {
id: relay_id.clone(),
id: uuid::Uuid::new_v4().to_string(),
tenant: payload.tenant,
schema: relay_id.clone(),
schema: String::new(),
subdomain: payload.subdomain,
plan: payload.plan,
stripe_subscription_item_id: None,
@@ -1102,16 +1098,10 @@ async fn get_invoice_bolt11(
}
}
#[derive(serde::Deserialize)]
struct StripeSessionParams {
return_url: Option<String>,
}
async fn create_stripe_session(
State(state): State<AppState>,
headers: HeaderMap,
Path(pubkey): Path<String>,
QueryParams(params): QueryParams<StripeSessionParams>,
) -> std::result::Result<Response, ApiError> {
let auth = state.api.extract_auth_pubkey(&headers)?;
state.api.require_admin_or_tenant(&auth, &pubkey)?;
@@ -1120,7 +1110,7 @@ async fn create_stripe_session(
match state
.api
.billing
.stripe_create_portal_session(&tenant.stripe_customer_id, params.return_url.as_deref())
.stripe_create_portal_session(&tenant.stripe_customer_id)
.await
{
Ok(url) => Ok(ok(StatusCode::OK, serde_json::json!({ "url": url }))),
+717 -238
View File
File diff suppressed because it is too large Load Diff
-220
View File
@@ -1,220 +0,0 @@
//! Small wrappers around the Bitcoin-facing services this app talks to: Nostr
//! Wallet Connect wallets (for Lightning invoices/payments) and a fiat↔BTC spot
//! price feed, plus the fiat-minor-units → millisatoshi conversion that ties them
//! together. The billing-specific orchestration lives in [`crate::billing`].
use anyhow::{Result, anyhow};
use nwc::prelude::{
LookupInvoiceRequest, LookupInvoiceResponse, MakeInvoiceRequest, NWC, NostrWalletConnectURI,
PayInvoiceRequest, TransactionState,
};
const COINBASE_SPOT_API: &str = "https://api.coinbase.com/v2/prices";
/// Millisatoshis per bitcoin.
const MSATS_PER_BTC: f64 = 100_000_000_000.0;
/// Owns the app's Bitcoin-facing configuration: the system NWC wallet URL (the
/// wallet used to *receive* payments — issue and look up bolt11 invoices) and the
/// HTTP client used for the fiat↔BTC spot price feed.
#[derive(Clone)]
pub struct Bitcoin {
system_nwc_url: String,
http: reqwest::Client,
}
impl Bitcoin {
/// Reads `NWC_URL` (the system / receiving wallet). Unlike the Stripe keys this
/// is optional: if it's unset, Lightning operations fail at use time with a
/// clear error rather than at startup.
pub fn from_env() -> Self {
Self {
system_nwc_url: std::env::var("NWC_URL").unwrap_or_default(),
http: reqwest::Client::new(),
}
}
/// The system wallet — issues and looks up the bolt11 invoices we want paid to
/// us. Errors if `NWC_URL` is unset or malformed.
pub fn system_wallet(&self) -> Result<Wallet> {
Wallet::parse(&self.system_nwc_url, "system")
}
/// Fetches the live BTC spot price and converts a fiat amount in minor units
/// (cents, etc.) to millisatoshis.
pub async fn fiat_minor_to_msats(&self, amount_due_minor: i64, currency: &str) -> Result<u64> {
let currency = currency.to_uppercase();
let btc_price = btc_spot_price_from_base(&self.http, COINBASE_SPOT_API, &currency).await?;
fiat_minor_to_msats_from_quote(amount_due_minor, &currency, btc_price)
}
}
#[derive(serde::Deserialize)]
struct CoinbaseSpotPriceResponse {
data: CoinbaseSpotPriceData,
}
#[derive(serde::Deserialize)]
struct CoinbaseSpotPriceData {
amount: String,
}
/// A handle to a single Nostr Wallet Connect wallet. Each operation opens a fresh
/// connection and tears it down afterwards.
pub struct Wallet {
uri: NostrWalletConnectURI,
}
impl Wallet {
/// Parses an `nostr+walletconnect://` URI. `label` only flavours the error
/// message so callers can tell which wallet was misconfigured.
pub fn parse(uri: &str, label: &str) -> Result<Self> {
let uri = uri
.parse::<NostrWalletConnectURI>()
.map_err(|_| anyhow!("invalid {label} NWC URL"))?;
Ok(Self { uri })
}
/// Issues a bolt11 invoice for `amount_msats`.
pub async fn make_invoice(&self, amount_msats: u64, description: &str) -> Result<String> {
let nwc = NWC::new(self.uri.clone());
let result = nwc
.make_invoice(MakeInvoiceRequest {
amount: amount_msats,
description: Some(description.to_string()),
description_hash: None,
expiry: None,
})
.await;
nwc.shutdown().await;
Ok(result
.map_err(|e| anyhow!("failed to create invoice: {e}"))?
.invoice)
}
/// Pays a bolt11 invoice.
pub async fn pay_invoice(&self, bolt11: String) -> Result<()> {
let nwc = NWC::new(self.uri.clone());
let result = nwc.pay_invoice(PayInvoiceRequest::new(bolt11)).await;
nwc.shutdown().await;
result.map(|_| ()).map_err(|e| anyhow!("{e}"))
}
/// Returns whether a bolt11 invoice (previously issued by this wallet) has been
/// settled.
pub async fn invoice_settled(&self, bolt11: &str) -> Result<bool> {
let nwc = NWC::new(self.uri.clone());
let result = nwc
.lookup_invoice(LookupInvoiceRequest {
payment_hash: None,
invoice: Some(bolt11.to_string()),
})
.await;
nwc.shutdown().await;
let response = result.map_err(|e| anyhow!("failed to lookup invoice: {e}"))?;
Ok(lookup_invoice_response_is_settled(&response))
}
}
fn lookup_invoice_response_is_settled(response: &LookupInvoiceResponse) -> bool {
response.state == Some(TransactionState::Settled) || response.settled_at.is_some()
}
/// Fetches the BTC spot price denominated in `currency` (an ISO-4217 code) from a
/// Coinbase-shaped API at `api_base`. Exposed so tests can stub the price feed;
/// production callers go through [`Bitcoin::fiat_minor_to_msats`].
pub async fn btc_spot_price_from_base(
http: &reqwest::Client,
api_base: &str,
currency: &str,
) -> Result<f64> {
let pair = format!("BTC-{currency}");
let url = format!("{}/{pair}/spot", api_base.trim_end_matches('/'));
let resp = http.get(url).send().await?;
let body: CoinbaseSpotPriceResponse = resp.error_for_status()?.json().await?;
let amount = body
.data
.amount
.parse::<f64>()
.map_err(|e| anyhow!("invalid BTC spot quote for {currency}: {e}"))?;
if amount <= 0.0 {
return Err(anyhow!(
"invalid non-positive BTC spot quote for {currency}"
));
}
Ok(amount)
}
/// Converts a fiat amount expressed in minor units (cents, etc.) to millisatoshis,
/// given a BTC price quote in that currency. Rounds up so we never under-charge,
/// but snaps to the nearest integer when within a hair of one to avoid floating
/// point artifacts at integer boundaries.
pub fn fiat_minor_to_msats_from_quote(
amount_due_minor: i64,
currency: &str,
btc_price_in_fiat: f64,
) -> Result<u64> {
if amount_due_minor <= 0 {
return Err(anyhow!("amount_due must be positive"));
}
if btc_price_in_fiat <= 0.0 {
return Err(anyhow!("btc_price_in_fiat must be positive"));
}
let divisor = 10_f64.powi(currency_minor_exponent(currency)? as i32);
let amount_fiat = (amount_due_minor as f64) / divisor;
let amount_btc = amount_fiat / btc_price_in_fiat;
let raw_msats = amount_btc * MSATS_PER_BTC;
let amount_msats = if (raw_msats - raw_msats.round()).abs() < 1e-6 {
raw_msats.round()
} else {
raw_msats.ceil()
};
if !amount_msats.is_finite() || amount_msats <= 0.0 || amount_msats > u64::MAX as f64 {
return Err(anyhow!("calculated msat amount is out of bounds"));
}
Ok(amount_msats as u64)
}
/// Number of decimal places in `currency`'s minor unit, following Stripe's
/// currency conventions (most are 2, JPY/KRW/… are 0, BHD/KWD/… are 3).
fn currency_minor_exponent(currency: &str) -> Result<u8> {
let normalized = currency.to_uppercase();
let exponent = match normalized.as_str() {
// Zero-decimal currencies in Stripe.
"BIF" | "CLP" | "DJF" | "GNF" | "JPY" | "KMF" | "KRW" | "MGA" | "PYG" | "RWF" | "UGX"
| "VND" | "VUV" | "XAF" | "XOF" | "XPF" => 0,
// Three-decimal currencies in Stripe.
"BHD" | "JOD" | "KWD" | "OMR" | "TND" => 3,
_ if normalized.chars().all(|c| c.is_ascii_alphabetic()) && normalized.len() == 3 => 2,
_ => return Err(anyhow!("invalid currency code: {currency}")),
};
Ok(exponent)
}
#[cfg(test)]
mod tests {
use super::fiat_minor_to_msats_from_quote;
#[test]
fn converts_usd_minor_units_with_quote() {
let msats = fiat_minor_to_msats_from_quote(100, "usd", 100_000.0)
.expect("conversion should succeed");
assert_eq!(msats, 1_000_000);
}
#[test]
fn converts_zero_decimal_currency_with_quote() {
let msats = fiat_minor_to_msats_from_quote(100, "jpy", 10_000_000.0)
.expect("conversion should succeed");
assert_eq!(msats, 1_000_000);
}
#[test]
fn rejects_malformed_currency_code() {
// Not three ASCII letters: rejected outright.
assert!(fiat_minor_to_msats_from_quote(100, "usdd", 100_000.0).is_err());
assert!(fiat_minor_to_msats_from_quote(100, "us1", 100_000.0).is_err());
}
}
+1 -94
View File
@@ -10,47 +10,6 @@ const RELAY_SYNC_RETRY_BASE_DELAY_SECS: u64 = 30;
const RELAY_SYNC_RETRY_MAX_DELAY_SECS: u64 = 15 * 60;
const RELAY_SYNC_RETRY_MAX_ATTEMPTS: usize = 6;
/// Blossom S3 settings from env; relay sync sets `key_prefix` to the relay schema.
#[derive(Clone)]
struct BlossomS3Sync {
endpoint: String,
region: String,
bucket: String,
access_key: String,
secret_key: String,
}
impl BlossomS3Sync {
fn from_env() -> Option<Self> {
let region = std::env::var("BLOSSOM_S3_REGION").unwrap_or_default();
let bucket = std::env::var("BLOSSOM_S3_BUCKET").unwrap_or_default();
let access_key = std::env::var("BLOSSOM_S3_ACCESS_KEY").unwrap_or_default();
let secret_key = std::env::var("BLOSSOM_S3_SECRET_KEY").unwrap_or_default();
let region = region.trim().to_string();
let bucket = bucket.trim().to_string();
let access_key = access_key.trim().to_string();
let secret_key = secret_key.trim().to_string();
if region.is_empty() || bucket.is_empty() || access_key.is_empty() || secret_key.is_empty() {
return None;
}
let endpoint = std::env::var("BLOSSOM_S3_ENDPOINT")
.unwrap_or_default()
.trim()
.to_string();
Some(Self {
endpoint,
region,
bucket,
access_key,
secret_key,
})
}
}
#[derive(Clone)]
pub struct Infra {
api_url: String,
@@ -59,7 +18,6 @@ pub struct Infra {
livekit_api_key: String,
livekit_api_secret: String,
api_secret: String,
blossom_s3: Option<BlossomS3Sync>,
query: Query,
command: Command,
}
@@ -72,7 +30,6 @@ impl Infra {
let livekit_api_key = std::env::var("LIVEKIT_API_KEY").unwrap_or_default();
let livekit_api_secret = std::env::var("LIVEKIT_API_SECRET").unwrap_or_default();
let api_secret = std::env::var("ZOOID_API_SECRET").unwrap_or_default();
let blossom_s3 = BlossomS3Sync::from_env();
if api_url.trim().is_empty() {
anyhow::bail!("missing ZOOID_API_URL");
@@ -88,7 +45,6 @@ impl Infra {
livekit_api_key,
livekit_api_secret,
api_secret,
blossom_s3,
query,
command,
})
@@ -298,7 +254,6 @@ impl Infra {
host,
livekit,
is_new.then(|| Keys::generate().secret_key().to_secret_hex()),
self.blossom_s3.as_ref(),
);
let url = format!("{}/relay/{}", base, relay.id);
@@ -368,10 +323,7 @@ fn relay_sync_body(
host: String,
livekit: serde_json::Value,
secret: Option<String>,
blossom_s3: Option<&BlossomS3Sync>,
) -> serde_json::Value {
let blossom = blossom_sync_json(relay, blossom_s3);
let mut body = serde_json::json!({
"host": host,
"schema": relay.schema,
@@ -389,7 +341,7 @@ fn relay_sync_body(
},
"groups": { "enabled": relay.groups_enabled == 1 },
"management": { "enabled": relay.management_enabled == 1 },
"blossom": blossom,
"blossom": { "enabled": relay.blossom_enabled == 1 },
"livekit": livekit,
"push": { "enabled": relay.push_enabled == 1 },
"roles": {
@@ -405,51 +357,6 @@ fn relay_sync_body(
body
}
fn blossom_sync_json(relay: &Relay, blossom_s3: Option<&BlossomS3Sync>) -> serde_json::Value {
let enabled = relay.blossom_enabled == 1;
if !enabled {
return serde_json::json!({ "enabled": false });
}
let Some(s3) = blossom_s3 else {
return serde_json::json!({ "enabled": true });
};
let mut s3_obj = serde_json::Map::new();
if !s3.endpoint.trim().is_empty() {
s3_obj.insert(
"endpoint".to_string(),
serde_json::Value::String(s3.endpoint.clone()),
);
}
s3_obj.insert(
"region".to_string(),
serde_json::Value::String(s3.region.clone()),
);
s3_obj.insert(
"bucket".to_string(),
serde_json::Value::String(s3.bucket.clone()),
);
s3_obj.insert(
"access_key".to_string(),
serde_json::Value::String(s3.access_key.clone()),
);
s3_obj.insert(
"secret_key".to_string(),
serde_json::Value::String(s3.secret_key.clone()),
);
s3_obj.insert(
"key_prefix".to_string(),
serde_json::Value::String(relay.schema.clone()),
);
serde_json::json!({
"enabled": true,
"adapter": "s3",
"s3": serde_json::Value::Object(s3_obj),
})
}
fn should_sync_relay_activity(activity_type: &str) -> bool {
matches!(
activity_type,
-2
View File
@@ -1,6 +1,5 @@
pub mod api;
pub mod billing;
pub mod bitcoin;
pub mod cipher;
pub mod command;
pub mod infra;
@@ -8,4 +7,3 @@ pub mod models;
pub mod pool;
pub mod query;
pub mod robot;
pub mod stripe;
-2
View File
@@ -1,6 +1,5 @@
mod api;
mod billing;
mod bitcoin;
mod cipher;
mod command;
mod infra;
@@ -8,7 +7,6 @@ mod models;
mod pool;
mod query;
mod robot;
mod stripe;
use anyhow::Result;
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
+11
View File
@@ -184,6 +184,17 @@ impl Query {
Ok(bolt11)
}
pub async fn has_active_paid_relays(&self, tenant_id: &str) -> Result<bool> {
let plans = sqlx::query_scalar::<_, String>(
"SELECT plan FROM relay WHERE tenant = ? AND status = 'active'",
)
.bind(tenant_id)
.fetch_all(&self.pool)
.await?;
Ok(plans.into_iter().any(|plan| Self::is_paid_plan(&plan)))
}
pub async fn list_activity_for_relay(&self, relay_id: &str) -> Result<Vec<Activity>> {
let rows = sqlx::query_as::<_, Activity>(
"SELECT id, tenant, created_at, activity_type, resource_type, resource_id
-19
View File
@@ -160,25 +160,6 @@ impl Robot {
Ok(relays)
}
pub async fn fetch_nostr_name(&self, pubkey: &str) -> Option<String> {
let pubkey = PublicKey::parse(pubkey).ok()?;
let filter = Filter::new().author(pubkey).kind(Kind::Metadata).limit(1);
let events = self
.indexer_client
.fetch_events(filter, Duration::from_secs(5))
.await
.ok()?;
let event = events.into_iter().max_by_key(|e| e.created_at)?;
let content: serde_json::Value = serde_json::from_str(&event.content).ok()?;
let name = content
.get("display_name")
.or_else(|| content.get("name"))
.and_then(|v| v.as_str())
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())?;
Some(name)
}
async fn fetch_messaging_relays_from_outbox(
&self,
recipient: &str,
-482
View File
@@ -1,482 +0,0 @@
//! A thin async wrapper around the subset of the Stripe REST API this service uses.
//!
//! Nothing here knows about relays, tenants, or our database — it just speaks HTTP
//! to Stripe and hands back `serde_json::Value` (or small typed results). The
//! domain logic lives in [`crate::billing`].
use anyhow::{Result, anyhow};
use hmac::{Hmac, Mac};
use sha2::Sha256;
use std::collections::BTreeMap;
type HmacSha256 = Hmac<Sha256>;
const STRIPE_API: &str = "https://api.stripe.com/v1";
const WEBHOOK_TOLERANCE_SECS: i64 = 300;
/// Error returned by invoice lookups, distinguishing a Stripe 4xx (e.g. "no such
/// invoice") — which callers usually want to surface as a client error — from an
/// internal failure.
#[derive(Debug)]
pub enum InvoiceLookupError {
StripeClient { status: reqwest::StatusCode },
Internal(anyhow::Error),
}
impl std::fmt::Display for InvoiceLookupError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::StripeClient { status } => {
write!(
f,
"stripe invoice lookup failed with status {}",
status.as_u16()
)
}
Self::Internal(error) => write!(f, "{error}"),
}
}
}
impl std::error::Error for InvoiceLookupError {}
impl From<anyhow::Error> for InvoiceLookupError {
fn from(value: anyhow::Error) -> Self {
Self::Internal(value)
}
}
impl From<reqwest::Error> for InvoiceLookupError {
fn from(value: reqwest::Error) -> Self {
Self::Internal(value.into())
}
}
/// A Stripe webhook event with its signature already verified.
#[derive(serde::Deserialize)]
pub struct Event {
#[serde(rename = "type")]
pub event_type: String,
pub data: EventData,
}
#[derive(serde::Deserialize)]
pub struct EventData {
pub object: serde_json::Value,
}
#[derive(Clone)]
pub struct Stripe {
pub(crate) secret_key: String,
pub(crate) webhook_secret: String,
http: reqwest::Client,
}
impl Stripe {
/// Builds the client from the environment: `STRIPE_SECRET_KEY` and
/// `STRIPE_WEBHOOK_SECRET`, both required. Panics if either is missing or blank.
pub fn from_env() -> Self {
let secret_key = std::env::var("STRIPE_SECRET_KEY").unwrap_or_default();
if secret_key.trim().is_empty() {
panic!("missing STRIPE_SECRET_KEY environment variable");
}
let webhook_secret = std::env::var("STRIPE_WEBHOOK_SECRET").unwrap_or_default();
if webhook_secret.trim().is_empty() {
panic!("missing STRIPE_WEBHOOK_SECRET environment variable");
}
Self::new(secret_key, webhook_secret)
}
pub fn new(secret_key: String, webhook_secret: String) -> Self {
Self {
secret_key,
webhook_secret,
http: reqwest::Client::new(),
}
}
// --- Customers ---
/// Creates a customer with the given display name, tagging it with the tenant
/// pubkey in metadata. Idempotent on the tenant pubkey.
pub async fn create_customer(&self, name: &str, tenant_pubkey: &str) -> Result<String> {
let resp = self
.http
.post(format!("{STRIPE_API}/customers"))
.bearer_auth(&self.secret_key)
.header(
"Idempotency-Key",
self.idempotency_key(&["create_customer", tenant_pubkey]),
)
.form(&[("name", name), ("metadata[tenant_pubkey]", tenant_pubkey)])
.send()
.await?;
let body: serde_json::Value = error_for_status(resp).await?.json().await?;
let customer_id = body["id"]
.as_str()
.ok_or_else(|| anyhow!("missing customer id"))?;
if !customer_id.starts_with("cus_") {
return Err(anyhow!("unexpected customer id format"));
}
Ok(customer_id.to_string())
}
// --- Subscriptions ---
/// Fetches a subscription, returning `None` if Stripe no longer knows about it
/// (so callers can recover from a stale subscription id).
pub async fn get_subscription(
&self,
subscription_id: &str,
) -> Result<Option<serde_json::Value>> {
let resp = self
.http
.get(format!("{STRIPE_API}/subscriptions/{subscription_id}"))
.bearer_auth(&self.secret_key)
.send()
.await?;
if resp.status() == reqwest::StatusCode::NOT_FOUND {
return Ok(None);
}
let body: serde_json::Value = error_for_status(resp).await?.json().await?;
Ok(Some(body))
}
/// Creates a subscription with one item per `(price_id, quantity)` entry, billed
/// automatically. Returns the subscription id and a map from price id to the
/// created subscription item id. Idempotent on the customer and the item set.
pub async fn create_subscription(
&self,
customer_id: &str,
items: &BTreeMap<String, i64>,
) -> Result<(String, BTreeMap<String, String>)> {
let mut form: Vec<(String, String)> = vec![
("customer".to_string(), customer_id.to_string()),
(
"collection_method".to_string(),
"charge_automatically".to_string(),
),
];
let mut key_parts: Vec<String> =
vec!["create_subscription".to_string(), customer_id.to_string()];
for (index, (price_id, quantity)) in items.iter().enumerate() {
form.push((format!("items[{index}][price]"), price_id.clone()));
form.push((format!("items[{index}][quantity]"), quantity.to_string()));
key_parts.push(format!("{price_id}={quantity}"));
}
let key_refs: Vec<&str> = key_parts.iter().map(String::as_str).collect();
let resp = self
.http
.post(format!("{STRIPE_API}/subscriptions"))
.bearer_auth(&self.secret_key)
.header("Idempotency-Key", self.idempotency_key(&key_refs))
.form(&form)
.send()
.await?;
let body: serde_json::Value = error_for_status(resp).await?.json().await?;
let subscription_id = body["id"]
.as_str()
.ok_or_else(|| anyhow!("missing subscription id"))?
.to_string();
let mut price_to_item = BTreeMap::new();
for item in body["items"]["data"]
.as_array()
.ok_or_else(|| anyhow!("missing subscription items"))?
{
let item_id = item["id"]
.as_str()
.ok_or_else(|| anyhow!("missing subscription item id"))?;
let price_id = item["price"]["id"]
.as_str()
.ok_or_else(|| anyhow!("missing subscription item price id"))?;
price_to_item.insert(price_id.to_string(), item_id.to_string());
}
Ok((subscription_id, price_to_item))
}
pub async fn create_subscription_item(
&self,
subscription_id: &str,
price_id: &str,
quantity: i64,
) -> Result<String> {
let quantity = quantity.to_string();
let resp = self
.http
.post(format!("{STRIPE_API}/subscription_items"))
.bearer_auth(&self.secret_key)
.header(
"Idempotency-Key",
self.idempotency_key(&["create_subscription_item", subscription_id, price_id]),
)
.form(&[
("subscription", subscription_id),
("price", price_id),
("quantity", quantity.as_str()),
])
.send()
.await?;
let body: serde_json::Value = error_for_status(resp).await?.json().await?;
body["id"]
.as_str()
.map(str::to_string)
.ok_or_else(|| anyhow!("missing subscription item id"))
}
/// Sets a subscription item's quantity. No idempotency key: this is a
/// reconcile-to-desired-state write, and re-applying the same target is a no-op.
pub async fn set_subscription_item_quantity(&self, item_id: &str, quantity: i64) -> Result<()> {
let resp = self
.http
.post(format!("{STRIPE_API}/subscription_items/{item_id}"))
.bearer_auth(&self.secret_key)
.form(&[("quantity", quantity.to_string())])
.send()
.await?;
error_for_status(resp).await?;
Ok(())
}
pub async fn delete_subscription_item(&self, item_id: &str) -> Result<()> {
let resp = self
.http
.delete(format!("{STRIPE_API}/subscription_items/{item_id}"))
.bearer_auth(&self.secret_key)
.send()
.await?;
error_for_status(resp).await?;
Ok(())
}
pub async fn cancel_subscription(&self, subscription_id: &str) -> Result<()> {
let resp = self
.http
.delete(format!("{STRIPE_API}/subscriptions/{subscription_id}"))
.bearer_auth(&self.secret_key)
.send()
.await?;
error_for_status(resp).await?;
Ok(())
}
// --- Invoices ---
/// Returns the `data` array of the customer's invoices.
pub async fn list_invoices(&self, customer_id: &str) -> Result<serde_json::Value> {
let resp = self
.http
.get(format!("{STRIPE_API}/invoices"))
.bearer_auth(&self.secret_key)
.query(&[("customer", customer_id)])
.send()
.await?;
let body: serde_json::Value = error_for_status(resp).await?.json().await?;
Ok(body["data"].clone())
}
pub async fn get_invoice(
&self,
invoice_id: &str,
) -> std::result::Result<serde_json::Value, InvoiceLookupError> {
let resp = self
.http
.get(format!("{STRIPE_API}/invoices/{invoice_id}"))
.bearer_auth(&self.secret_key)
.send()
.await?;
if resp.status().is_client_error() {
return Err(InvoiceLookupError::StripeClient {
status: resp.status(),
});
}
let body: serde_json::Value = error_for_status(resp).await?.json().await?;
Ok(body)
}
pub async fn pay_invoice(&self, invoice_id: &str) -> Result<()> {
let resp = self
.http
.post(format!("{STRIPE_API}/invoices/{invoice_id}/pay"))
.bearer_auth(&self.secret_key)
.header(
"Idempotency-Key",
self.idempotency_key(&["pay_invoice", invoice_id]),
)
.send()
.await?;
error_for_status(resp).await?;
Ok(())
}
/// Marks an invoice paid out of band — used when we've collected payment over
/// Lightning rather than through Stripe.
pub async fn pay_invoice_out_of_band(&self, invoice_id: &str) -> Result<()> {
let resp = self
.http
.post(format!("{STRIPE_API}/invoices/{invoice_id}/pay"))
.bearer_auth(&self.secret_key)
.header(
"Idempotency-Key",
self.idempotency_key(&["pay_invoice_oob", invoice_id]),
)
.form(&[("paid_out_of_band", "true")])
.send()
.await?;
error_for_status(resp).await?;
Ok(())
}
pub async fn preview_upcoming_invoice(
&self,
customer_id: &str,
subscription_id: Option<&str>,
) -> Result<serde_json::Value> {
let mut req = self
.http
.get(format!("{STRIPE_API}/invoices/upcoming"))
.bearer_auth(&self.secret_key)
.query(&[("customer", customer_id)]);
if let Some(subscription_id) = subscription_id {
req = req.query(&[("subscription", subscription_id)]);
}
let body: serde_json::Value = error_for_status(req.send().await?).await?.json().await?;
Ok(body)
}
// --- Payment methods ---
pub async fn has_payment_method(&self, customer_id: &str) -> Result<bool> {
let resp = self
.http
.get(format!("{STRIPE_API}/payment_methods"))
.bearer_auth(&self.secret_key)
.query(&[("customer", customer_id), ("type", "card")])
.send()
.await?;
let body: serde_json::Value = error_for_status(resp).await?.json().await?;
Ok(body["data"].as_array().is_some_and(|a| !a.is_empty()))
}
// --- Billing portal ---
pub async fn create_portal_session(
&self,
customer_id: &str,
return_url: Option<&str>,
) -> Result<String> {
let mut params = vec![("customer", customer_id.to_string())];
if let Some(url) = return_url {
params.push(("return_url", url.to_string()));
}
let resp = self
.http
.post(format!("{STRIPE_API}/billing_portal/sessions"))
.bearer_auth(&self.secret_key)
.form(&params)
.send()
.await?;
let body: serde_json::Value = error_for_status(resp).await?.json().await?;
body["url"]
.as_str()
.map(str::to_string)
.ok_or_else(|| anyhow!("missing portal session url"))
}
// --- Webhooks ---
/// Verifies the `Stripe-Signature` header against the configured webhook secret
/// (including the timestamp tolerance check) and parses the event body.
pub fn construct_event(&self, payload: &str, sig_header: &str) -> Result<Event> {
self.verify_webhook_signature(payload, sig_header)?;
Ok(serde_json::from_str(payload)?)
}
fn verify_webhook_signature(&self, payload: &str, sig_header: &str) -> Result<()> {
let mut timestamp = None;
let mut signature = None;
for part in sig_header.split(',') {
if let Some(t) = part.strip_prefix("t=") {
timestamp = Some(t);
} else if let Some(v) = part.strip_prefix("v1=") {
signature = Some(v);
}
}
let timestamp = timestamp.ok_or_else(|| anyhow!("missing webhook timestamp"))?;
let signature = signature.ok_or_else(|| anyhow!("missing webhook signature"))?;
let signed_payload = format!("{timestamp}.{payload}");
let mut mac = HmacSha256::new_from_slice(self.webhook_secret.as_bytes())
.map_err(|e| anyhow!("invalid webhook secret: {e}"))?;
mac.update(signed_payload.as_bytes());
let expected = hex::encode(mac.finalize().into_bytes());
if expected != signature {
return Err(anyhow!("webhook signature mismatch"));
}
let ts: i64 = timestamp
.parse()
.map_err(|_| anyhow!("bad webhook timestamp"))?;
let now = chrono::Utc::now().timestamp();
if (now - ts).abs() > WEBHOOK_TOLERANCE_SECS {
return Err(anyhow!("webhook timestamp outside tolerance"));
}
Ok(())
}
// --- Internals ---
/// Derives a stable idempotency key by HMAC-ing `parts` with the secret key.
fn idempotency_key(&self, parts: &[&str]) -> String {
let mut mac = HmacSha256::new_from_slice(self.secret_key.as_bytes())
.expect("HMAC accepts any key length");
for (i, part) in parts.iter().enumerate() {
if i > 0 {
mac.update(b":");
}
mac.update(part.as_bytes());
}
hex::encode(mac.finalize().into_bytes())
}
}
/// Like [`reqwest::Response::error_for_status`], but on a 4xx/5xx response it reads
/// the body and folds Stripe's JSON error payload (`error.message`/`code`/`param`)
/// into the returned error, so callers get an actionable message instead of a bare
/// "400 Bad Request" with only the URL.
async fn error_for_status(resp: reqwest::Response) -> Result<reqwest::Response> {
let status = resp.status();
if !status.is_client_error() && !status.is_server_error() {
return Ok(resp);
}
let url = resp.url().clone();
let body = resp.text().await.unwrap_or_default();
let detail = serde_json::from_str::<serde_json::Value>(&body)
.ok()
.and_then(|json| {
let error = &json["error"];
let message = error["message"].as_str()?.to_string();
let mut detail = message;
if let Some(code) = error["type"].as_str().or_else(|| error["code"].as_str()) {
detail.push_str(&format!(" [{code}]"));
}
if let Some(param) = error["param"].as_str() {
detail.push_str(&format!(" (param: {param})"));
}
Some(detail)
})
.unwrap_or_else(|| {
if body.trim().is_empty() {
"<empty response body>".to_string()
} else {
body
}
});
Err(anyhow!(
"Stripe API request to {url} failed with status {status}: {detail}"
))
}
+31
View File
@@ -0,0 +1,31 @@
use axum::{Json, Router, routing::get};
use backend::billing::{fetch_btc_spot_price_from_base, fiat_minor_to_msats_from_quote};
#[tokio::test]
async fn quote_endpoint_can_be_stubbed_deterministically() {
async fn spot() -> Json<serde_json::Value> {
Json(serde_json::json!({ "data": { "amount": "50000.00" } }))
}
let app = Router::new().route("/v2/prices/BTC-USD/spot", get(spot));
let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
.await
.expect("bind test server");
let addr = listener.local_addr().expect("get local addr");
tokio::spawn(async move {
axum::serve(listener, app).await.expect("serve quote stub");
});
let client = reqwest::Client::new();
let base = format!("http://{addr}/v2/prices");
let btc_price = fetch_btc_spot_price_from_base(&client, &base, "USD")
.await
.expect("fetch stubbed quote");
assert_eq!(btc_price, 50_000.0);
let msats =
fiat_minor_to_msats_from_quote(100, "USD", btc_price).expect("convert quoted fiat amount");
assert_eq!(msats, 2_000_000);
}
+1 -1
View File
@@ -40,7 +40,7 @@ export default function PaymentSetup(props: PaymentSetupProps) {
setRedirecting(true)
setError("")
try {
const { url } = await createPortalSession(account()!.pubkey, window.location.href)
const { url } = await createPortalSession(account()!.pubkey)
window.location.href = url
} catch (e) {
setError(e instanceof Error ? e.message : "Failed to open billing portal")
+2 -3
View File
@@ -253,9 +253,8 @@ export function reactivateRelay(id: string) {
return callApi<undefined, void>("POST", `/relays/${id}/reactivate`)
}
export function createPortalSession(pubkey: string, returnUrl?: string) {
const query = returnUrl ? `?return_url=${encodeURIComponent(returnUrl)}` : ""
return callApi<undefined, { url: string }>("GET", `/tenants/${pubkey}/stripe/session${query}`)
export function createPortalSession(pubkey: string) {
return callApi<undefined, { url: string }>("GET", `/tenants/${pubkey}/stripe/session`)
}
export function getInvoiceBolt11(invoiceId: string) {
+4 -9
View File
@@ -1,5 +1,5 @@
import { createSignal } from "solid-js"
import { updateRelayById, deactivateRelayById, reactivateRelayById, getLatestOpenInvoice, tenantNeedsPaymentSetup, type Relay } from "@/lib/hooks"
import { updateRelayById, deactivateRelayById, reactivateRelayById, getLatestOpenInvoice, type Relay } from "@/lib/hooks"
import { setToastMessage } from "@/components/Toast"
import type { Invoice, PlanId } from "@/lib/api"
@@ -31,7 +31,6 @@ export default function useRelayToggles(
) {
const [busy, setBusy] = createSignal(false)
const [pendingInvoice, setPendingInvoice] = createSignal<Invoice | undefined>()
const [pendingPaymentSetup, setPendingPaymentSetup] = createSignal(false)
async function updateRelay(next: Relay, previous: Relay) {
mutate(next)
@@ -102,12 +101,8 @@ export default function useRelayToggles(
}
if (plan !== "free") {
const needsSetup = await tenantNeedsPaymentSetup()
if (needsSetup) {
const invoice = await getLatestOpenInvoice()
if (invoice) setPendingInvoice(invoice)
setPendingPaymentSetup(true)
}
const invoice = await getLatestOpenInvoice()
if (invoice) setPendingInvoice(invoice)
}
}
@@ -121,5 +116,5 @@ export default function useRelayToggles(
onToggleLivekitSupport: () => toggle("livekit_enabled", relay()?.plan !== "free"),
}
return { busy, handleDeactivate, handleReactivate, handleUpdatePlan, pendingInvoice, clearPendingInvoice: () => setPendingInvoice(undefined), pendingPaymentSetup, clearPendingPaymentSetup: () => setPendingPaymentSetup(false), toggles }
return { busy, handleDeactivate, handleReactivate, handleUpdatePlan, pendingInvoice, clearPendingInvoice: () => setPendingInvoice(undefined), toggles }
}
+1 -1
View File
@@ -49,7 +49,7 @@ export default function Account() {
async function openPortal() {
setPortalLoading(true)
try {
const { url } = await createPortalSession(account()!.pubkey, window.location.href)
const { url } = await createPortalSession(account()!.pubkey)
window.location.href = url
} catch (e) {
setError(e instanceof Error ? e.message : "Failed to open billing portal")
+2 -9
View File
@@ -1,5 +1,5 @@
import { useParams } from "@solidjs/router"
import { createEffect, createMemo, createResource, createSignal, Show } from "solid-js"
import { createMemo, createResource, createSignal, Show } from "solid-js"
import BackLink from "@/components/BackLink"
import PageContainer from "@/components/PageContainer"
import PaymentDialog from "@/components/PaymentDialog"
@@ -28,20 +28,13 @@ export default function RelayDetail() {
})
const loading = useMinLoading(() => relay.loading && !relay())
const [activity] = useRelayActivity(relayId)
const { busy, handleDeactivate, handleReactivate, handleUpdatePlan, pendingInvoice, clearPendingInvoice, pendingPaymentSetup, clearPendingPaymentSetup, toggles } = useRelayToggles(relayId, relay, { refetch, mutate })
const { busy, handleDeactivate, handleReactivate, handleUpdatePlan, pendingInvoice, clearPendingInvoice, toggles } = useRelayToggles(relayId, relay, { refetch, mutate })
const [tenant, { refetch: refetchTenant }] = useTenant()
const [paymentSetupOpen, setPaymentSetupOpen] = createSignal(false)
const [invoiceDialogOpen, setInvoiceDialogOpen] = createSignal(false)
const [paymentBannerDismissed, setPaymentBannerDismissed] = createSignal(false)
createEffect(() => {
if (pendingPaymentSetup() && !pendingInvoice()) {
setPaymentSetupOpen(true)
clearPendingPaymentSetup()
}
})
const isPaidRelay = createMemo(() => {
const r = relay()
if (!r) return false
+6 -22
View File
@@ -3,15 +3,13 @@ import { useNavigate } from "@solidjs/router"
import BackLink from "@/components/BackLink"
import PageContainer from "@/components/PageContainer"
import PaymentDialog from "@/components/PaymentDialog"
import PaymentSetup from "@/components/PaymentSetup"
import RelayForm, { type RelayFormValues } from "@/components/RelayForm"
import { createRelayForActiveTenant, getLatestOpenInvoice, tenantNeedsPaymentSetup } from "@/lib/hooks"
import { createRelayForActiveTenant, getLatestOpenInvoice } from "@/lib/hooks"
import type { Invoice } from "@/lib/api"
export default function RelayNew() {
const navigate = useNavigate()
const [pendingInvoice, setPendingInvoice] = createSignal<Invoice | undefined>()
const [paymentSetupOpen, setPaymentSetupOpen] = createSignal(false)
let createdRelayId = ""
async function handleSubmit(values: RelayFormValues) {
@@ -19,14 +17,9 @@ export default function RelayNew() {
createdRelayId = relay.id
if (values.plan !== "free") {
const needsSetup = await tenantNeedsPaymentSetup()
if (needsSetup) {
const invoice = await getLatestOpenInvoice()
if (invoice) {
setPendingInvoice(invoice)
return
}
setPaymentSetupOpen(true)
const invoice = await getLatestOpenInvoice()
if (invoice) {
setPendingInvoice(invoice)
return
}
}
@@ -34,13 +27,8 @@ export default function RelayNew() {
navigate(`/relays/${relay.id}`)
}
function handleInvoiceClose() {
function handleDialogClose() {
setPendingInvoice(undefined)
setPaymentSetupOpen(true)
}
function handleSetupClose() {
setPaymentSetupOpen(false)
navigate(`/relays/${createdRelayId}`)
}
@@ -59,14 +47,10 @@ export default function RelayNew() {
<PaymentDialog
invoice={inv()}
open={true}
onClose={handleInvoiceClose}
onClose={handleDialogClose}
/>
)}
</Show>
<PaymentSetup
open={paymentSetupOpen()}
onClose={handleSetupClose}
/>
</PageContainer>
)
}
+1 -4
View File
@@ -5,9 +5,6 @@ dev:
cd frontend && bun dev &
wait
dev-backend:
cd backend && onchange src -ik -- bash -c 'RUST_LOG=backend=info cargo run'
dev-frontend:
cd frontend && bun run dev
@@ -30,7 +27,7 @@ build-backend:
cd backend && cargo build
build-frontend:
cd frontend && bun i && bun run build
cd frontend && bun run build
fmt: fmt-backend