forked from coracle/caravel
Jon Staab
99 lines
5.2 KiB
Markdown
99 lines
5.2 KiB
Markdown
# `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 small typed results. The domain logic that drives it lives in `spec/billing.md`, and the webhook dispatch lives in `spec/api.md`.
|
|
|
|
Members:
|
|
|
|
- `env: Env` - configuration; supplies the Stripe secret key (bearer token + idempotency HMAC key) and the webhook signing secret
|
|
- `http: reqwest::Client`
|
|
|
|
All requests authenticate with `env.stripe_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 the secret key. Reconcile-to-desired-state writes (e.g. setting an item quantity, deleting/canceling) 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 new(env: &Env) -> Self`
|
|
|
|
Constructs the client with a fresh `reqwest::Client`, holding a clone of `env`. This is what `Billing::new` and `main` call.
|
|
|
|
## `pub async fn create_customer(&self, tenant_pubkey: &str, name: &str) -> Result<String>`
|
|
|
|
- `POST /v1/customers` with `name` and `metadata[tenant_pubkey]`
|
|
- Idempotent on `tenant_pubkey`
|
|
- Returns the new customer id
|
|
|
|
## `pub async fn get_subscription(&self, subscription_id: &str) -> Result<Option<StripeSubscription>>`
|
|
|
|
- `GET /v1/subscriptions/:id`
|
|
- Returns `None` if Stripe responds `404` (so callers can recover from a stale subscription id), otherwise the parsed `StripeSubscription`
|
|
|
|
## `pub async fn create_subscription(&self, customer_id: &str, items: &BTreeMap<String, i64>) -> Result<StripeSubscription>`
|
|
|
|
- `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 created `StripeSubscription` (including its items)
|
|
|
|
## `pub async fn create_subscription_item(&self, subscription_id: &str, price_id: &str, quantity: i64) -> Result<()>`
|
|
|
|
- `POST /v1/subscription_items`
|
|
- Idempotent on `(subscription_id, price_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<Vec<StripeInvoice>>`
|
|
|
|
- `GET /v1/invoices?customer=…`
|
|
- Returns the parsed `data` array
|
|
|
|
## `pub async fn get_invoice(&self, invoice_id: &str) -> Result<Option<StripeInvoice>>`
|
|
|
|
- `GET /v1/invoices/:id`
|
|
- Returns `None` if Stripe responds `404`, otherwise the parsed `StripeInvoice`
|
|
|
|
## `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` (under a distinct key from `pay_invoice`)
|
|
|
|
## `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 Customer Portal session URL
|
|
|
|
## `pub fn get_webhook_event(&self, payload: &str, signature: &str) -> Result<StripeWebhookEvent>`
|
|
|
|
Verifies the `Stripe-Signature` header against `env.stripe_webhook_secret` and parses the body.
|
|
|
|
- Parse `t=` (timestamp) and `v1=` (signature) from the header
|
|
- Compute `HMAC-SHA256(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 `StripeWebhookEvent`
|
|
|
|
# Typed results
|
|
|
|
- `StripeWebhookEvent { event_type: String, data: StripeWebhookEventData }`, `StripeWebhookEventData { object: serde_json::Value }` — the verified, parsed webhook event (`event_type` deserializes from the JSON `type` field)
|
|
- `StripeSubscription { id, status, items: Vec<StripeSubscriptionItem> }` (`items` flattened from Stripe's `{ data: [...] }` list)
|
|
- `StripeSubscriptionItem { id, price: StripePrice, quantity }` (`quantity` defaults to 1 when absent)
|
|
- `StripePrice { id }`
|
|
- `StripeInvoice { id, customer, status, amount_due, currency }` (the subset of invoice fields the API surfaces; `Serialize` + `Clone`)
|