A snapshot of packages/ in the Weft repository; the official packages are published from these commits. Markup-Kit-Commit: dd1e6eb5270e62e0c8b6c202b3d01f0da6e00ddc
148 lines
5.8 KiB
Markdown
148 lines
5.8 KiB
Markdown
# @weft/stripe
|
|
|
|
A typed client for Stripe's API, written in Weft over `std/http`. It covers customers, Checkout, payment intents,
|
|
subscriptions, prices, products, refunds, the customer portal and webhooks. Its only capability is `http.fetch@api.stripe.com`.
|
|
|
|
```sh
|
|
weft add weft/stripe
|
|
```
|
|
|
|
```weft
|
|
import { client } from "@weft/stripe"
|
|
import * as checkout from "@weft/stripe/checkout"
|
|
import { env } from "std/process"
|
|
|
|
let stripe = client(env("STRIPE_SECRET_KEY")!)
|
|
|
|
let session = try await checkout.create(stripe, {
|
|
mode: "payment",
|
|
success_url: "https://example.com/thanks?s={CHECKOUT_SESSION_ID}",
|
|
cancel_url: "https://example.com/cart",
|
|
line_items: [{ quantity: 1, price_data: { currency: "eur", unit_amount: 1999, product_data: { name: "Ticket" } } }],
|
|
}, { idempotencyKey: `sale-${sale.id}` })
|
|
```
|
|
|
|
## Modules
|
|
|
|
Each resource is its own module, imported as `@weft/stripe/<name>`:
|
|
|
|
| module | functions |
|
|
|---|---|
|
|
| `customers` | `create`, `retrieve`, `update`, `remove`, `list`, `listAll`, `search` |
|
|
| `checkout` | `create`, `retrieve`, `expire`, `list`, `listAll`, `lineItems` |
|
|
| `payment_intents` | `create`, `retrieve`, `update`, `confirm`, `capture`, `cancel`, `list`, `listAll`, `search` |
|
|
| `subscriptions` | `create`, `retrieve`, `update`, `cancel`, `list`, `listAll`, `search` |
|
|
| `prices` | `create`, `retrieve`, `update`, `list`, `listAll` |
|
|
| `products` | `create`, `retrieve`, `update`, `remove`, `list`, `listAll` |
|
|
| `refunds` | `create`, `retrieve`, `list`, `listAll` |
|
|
| `billing` | `createPortalSession`, `retrieveCoupon`, `retrievePromotionCode`, `createAccountSession` |
|
|
| `webhooks` | `verify`, `signature` |
|
|
|
|
Field names are Stripe's own, so its API reference applies as written. Every parameter type has an `extra` field for what the
|
|
type doesn't list, and `request` calls anything else:
|
|
|
|
```weft
|
|
import { request } from "@weft/stripe"
|
|
|
|
type Balance = { livemode: boolean }
|
|
let balance = try await request(stripe, "GET", "/v1/balance", null, {}, j => try j as Balance)
|
|
```
|
|
|
|
## Errors are values
|
|
|
|
Every call fails with a `StripeError`:
|
|
|
|
```weft
|
|
let intent, err = try await paymentIntents.create(stripe, params)
|
|
if err != null {
|
|
return match err {
|
|
CardError { failure } => declined(failure.decline_code),
|
|
RateLimited | ConnectionFailed => retryLater(),
|
|
_ => report(errorMessage(err)),
|
|
}
|
|
}
|
|
```
|
|
|
|
| variant | when |
|
|
|---|---|
|
|
| `CardError` | the card was declined |
|
|
| `InvalidRequest` | the parameters are wrong, or the object doesn't exist |
|
|
| `AuthenticationFailed`, `PermissionDenied` | the API key is wrong or can't do this |
|
|
| `RateLimited` | too many requests |
|
|
| `IdempotencyConflict` | an idempotency key was reused with other parameters |
|
|
| `ApiFailure` | Stripe had a problem |
|
|
| `ConnectionFailed` | Stripe wasn't reached, so the outcome of a `POST` is unknown |
|
|
| `BadResponse` | Stripe's answer isn't what the types say |
|
|
|
|
## Retries and idempotency
|
|
|
|
A request is repeated up to `maxRetries` times (2) after a network error, a conflict or a server error, with exponential
|
|
backoff, as Stripe's own libraries do. It obeys Stripe's `Stripe-Should-Retry` and `Retry-After` headers. Every attempt of a
|
|
`POST` carries one idempotency key, so a request Stripe did receive isn't carried out twice. Pass `idempotencyKey` to make the
|
|
key your own: then a repeat after a crash is safe too.
|
|
|
|
## Paging
|
|
|
|
`list` gives one page, and `listAll` follows the pages up to a limit (10,000 items unless you pass `max`):
|
|
|
|
```weft
|
|
let page = try await customers.list(stripe, { limit: 20, starting_after: lastId })
|
|
let everyone = try await customers.listAll(stripe, { email: "ana@example.com" })
|
|
```
|
|
|
|
## Connect
|
|
|
|
Give `stripeAccount` to the client, or to one call, to act on a connected account:
|
|
|
|
```weft
|
|
let session = try await checkout.create(stripe, params, { stripeAccount: "acct_123" })
|
|
```
|
|
|
|
## Expandable fields and metadata
|
|
|
|
An expandable field is `json`: an id, or the object when you asked for it with `expand`. `idOf` reads either, and `as` gives
|
|
the object its type. `metadata` reads one value of an object's metadata.
|
|
|
|
```weft
|
|
let session = try await checkout.retrieve(stripe, id, { expand: ["subscription"] })
|
|
let subscriptionId = idOf(session.subscription)
|
|
let sub = try session.subscription as Subscription
|
|
let siteId = metadata(sub.metadata, "siteId")
|
|
```
|
|
|
|
## Webhooks
|
|
|
|
`verify` checks the signature in constant time and refuses events older than five minutes. Give it the body exactly as it
|
|
arrived:
|
|
|
|
```weft
|
|
import { verify } from "@weft/stripe/webhooks"
|
|
|
|
async fn webhook(req: Request) {
|
|
let event, err = try verify(req.body, req.headers.get("stripe-signature") ?? "", secret)
|
|
if err != null {
|
|
return status(400)
|
|
}
|
|
if event.type == "checkout.session.completed" {
|
|
let session = try event.data.object as Session else null
|
|
}
|
|
return json({ received: true })
|
|
}
|
|
```
|
|
|
|
`signature(payload, secret, timestamp)` makes the header for a test of your own handler.
|
|
|
|
## What has and hasn't been tested
|
|
|
|
`node packages/stripe/scripts/integration.mjs` runs every function above against [stripe-mock](https://github.com/stripe/stripe-mock), which
|
|
checks each request against Stripe's OpenAPI specification and answers from its fixtures, and runs retries, headers, paging and
|
|
errors against a scripted server. `weft test tests/stripe.test.weft` covers the signature code with FIPS 180-4's and RFC 4231's
|
|
vectors and a signature made by Node's `crypto`. **Nothing here has run against Stripe itself**: try a test-mode key before
|
|
relying on it.
|
|
|
|
## Limits
|
|
|
|
- **It reaches only `api.stripe.com`.** As a dependency, a `baseUrl` on any other host fails with a `CapabilityError`. To point
|
|
it at stripe-mock or a proxy, the app lists that host too: `allow = ["http.fetch@api.stripe.com", "http.fetch@127.0.0.1"]`.
|
|
- `metadata` and expandable fields are `json`: Weft's `as` can't turn a JSON object into a `Map`.
|
|
- Verifying a signature takes about 0.5 ms per KB of event. It is written in Weft until `std/crypto` is available.
|