packages/ at markup-kit dd1e6eb5270e
A snapshot of packages/ in the Weft repository; the official packages are published from these commits. Markup-Kit-Commit: dd1e6eb5270e62e0c8b6c202b3d01f0da6e00ddc
This commit is contained in:
commit
306b143104
72 changed files with 10915 additions and 0 deletions
148
stripe/README.md
Normal file
148
stripe/README.md
Normal file
|
|
@ -0,0 +1,148 @@
|
|||
# @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.
|
||||
Loading…
Reference in a new issue