lipwa 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afc2872c6fa2654eb15ce20c62a1a6027e93f9d7a3b4aceaa0c6420ac96b29d3
-  data.tar.gz: a58735e4ccecf1e745d8287db798b9b6993b0da08cff0511c7927d182c239a42
+  metadata.gz: 5ed1d0107830b6fafe1757cc253a820b57fe62c99f38ec78e1d2adde62e10eaa
+  data.tar.gz: 85994d9fe4d49e276892154fc600ae06f420740a55c5580f9bbac6cfbcc3d14b
 SHA512:
-  metadata.gz: e6abf4adc039b3930c73663e1dfb6888b2a3b13846a3637fd17a13ff6909776b28e0ac340ab6bc9f8db78f56b2a3eea5d41bd9f9ec5fb5a466282480c849c044
-  data.tar.gz: 57b7f247579e9d6c810f29fe0998b2bac9c1d027c9cd39780ae64d567a9813b0b34cd7020a7fd0e5f558559600563becdebfcb3cd7f77fc43c6694e9384e861e
+  metadata.gz: 37ebc5f8bff81213d7949b33c984ac4f18bf32b6386b25323665fcf86f8f6a1d838759cbcb4c49fba3f0f4274d1e3a6bdabcd8b78600bf24ad23554e26adc253
+  data.tar.gz: 83d40bb47c71c2fb3f98ba51021b3bcbee44d91610d8407fa44975add4261f894c999f5cb109a370af1bae301fee906ef0f0e89de75993799e3846f7085eec89

data/CHANGELOG.md

@@ -1,3 +1,28 @@
+## [0.1.3] - 2026-09-06
+
+- Add Co-op Bank support for bank transfers, balance and statement inquiries,
+  transaction status queries, OAuth authentication, and normalized callbacks
+- Add Jenga HQ support for bank transfers, mobile-money disbursements, account
+  inquiries, forex rates, OAuth/RSA request signing, and verified payment IPNs
+- Add card-payment capabilities for purchase, authorization, capture, and void,
+  with Flutterwave, Paystack, and Pesapal gateway implementations
+- Add Lightning Network support through LNbits, including separate invoice and
+  admin API keys, invoice creation/status checks, outbound payments and
+  reconciliation, and verified webhook parsing
+- Add immutable `Lipwa::Context` configuration snapshots with isolated,
+  memoized gateway instances for multi-tenant and concurrent applications
+- Add a capability-focused documentation site and rewrite the project README
+- Add constrained decimal amounts and currency-safe arithmetic to `Lipwa::Money`
+- Formalize transient HTTP retries with bounded exponential backoff and idempotency-safe writes
+- Add structured HTTP logging with recursive credential and secret redaction
+- Add `idempotency_key:` support across gateway calls via the `Idempotency-Key` header
+
+## [0.1.2] - 2026-08-29
+
+- Add a Rails API example covering M-Pesa collection, disbursement, refunds,
+  and webhook handling
+- Refresh gem metadata and exclude the internal project plan from packaged gems
+
 ## [0.1.1]
 
 - Add `Lipwa::HttpAdapter`, a Faraday-based HTTP wrapper

data/README.md

@@ -1,262 +1,290 @@
 # Lipwa
 
-Lipwa is a unified Ruby gem for accepting and disbursing payments across
-African payment providers — mobile money, bank APIs, and (eventually) card
-rails — behind one consistent, capability-based interface. It currently
-ships a full integration with Safaricom's **M-Pesa Daraja API**: STK Push,
-C2B, B2C/B2B disbursements, and inbound webhook handling.
-
-Every gateway call returns a `Dry::Monads::Result`
-(`Success(Lipwa::Response)` / `Failure(Lipwa::Error)`) instead of raising —
-see [Error handling](#error-handling) below. Only genuine programmer
-mistakes (bad config, calling a capability the gateway doesn't support) are
-raised as exceptions.
+Lipwa is a capability-based Ruby toolkit for African payment APIs. Mobile
+money, bank transfers, payouts, and callbacks do not share one card-shaped
+interface; each gateway exposes only the flows it supports.
 
-## Installation
+```ruby
+gateway = Lipwa.gateway(:mpesa)
+gateway.capability?(:stk_push)      # => true
+gateway.capability?(:bank_transfer) # => false
+```
 
-Install the gem and add it to the application's Gemfile by executing:
+## What it provides
 
-```bash
-bundle add lipwa
-```
+- Explicit, composable gateway capabilities
+- Validated inputs and immutable decimal money values
+- `Dry::Monads::Result` for expected validation and network failures
+- Normalized responses and webhook events
+- OAuth/signing strategies, timeouts, safe retries, and redacted logs
 
-If bundler is not being used to manage dependencies, install the gem by
-executing:
+## Installation
 
 ```bash
-gem install lipwa
+bundle add lipwa
 ```
 
-## Configuration
+Lipwa supports Ruby 3.2 and newer.
 
-Set gem-wide defaults once (logger, default timeout, Faraday adapter — all
-optional):
+## Quick start
 
 ```ruby
+require "lipwa"
+
 Lipwa.configure do |config|
   config.logger = Rails.logger
   config.default_timeout = 10
 end
+
+Lipwa::Gateways::Mpesa.configure do |config|
+  config.env = :sandbox
+  config.consumer_key = ENV.fetch("MPESA_CONSUMER_KEY")
+  config.consumer_secret = ENV.fetch("MPESA_CONSUMER_SECRET")
+  config.shortcode = ENV.fetch("MPESA_SHORTCODE")
+  config.passkey = ENV.fetch("MPESA_PASSKEY")
+end
+
+result = Lipwa.gateway(:mpesa).stk_push(
+  amount: Lipwa::Money.new(amount: "100.00", currency: "KES"),
+  phone_number: "254712345678",
+  account_reference: "ORDER-123",
+  callback_url: "https://payments.example.com/webhooks/mpesa",
+  idempotency_key: "stk-order-123"
+)
+
+result.either(
+  ->(response) { puts response.provider_reference },
+  ->(error) { warn error.message }
+)
 ```
 
-Then configure each gateway you use. For M-Pesa:
+A successful STK response means M-Pesa accepted the request. The final payment
+outcome arrives asynchronously at `callback_url`.
+
+## Isolated configuration contexts
+
+Use an explicit context for each merchant or tenant. It snapshots the current
+`Lipwa.config` and all registered gateway configurations before applying overrides.
 
 ```ruby
-Lipwa::Gateways::Mpesa.configure do |c|
-  c.env = :sandbox # or :production
-  c.consumer_key = ENV["MPESA_CONSUMER_KEY"]
-  c.consumer_secret = ENV["MPESA_CONSUMER_SECRET"]
-  c.shortcode = ENV["MPESA_SHORTCODE"]
-  c.passkey = ENV["MPESA_PASSKEY"] # STK Push only
-
-  # B2C/B2B disbursements only:
-  c.initiator_name = ENV["MPESA_INITIATOR_NAME"]
-  c.initiator_password = ENV["MPESA_INITIATOR_PASSWORD"]
-  c.security_credential_cert = File.read(ENV["MPESA_CERT_PATH"])
+tenant_context = Lipwa.context do |config|
+  config.default_timeout = 20
+
+  config.gateway(:mpesa) do |mpesa|
+    mpesa.consumer_key = tenant.mpesa_consumer_key
+    mpesa.consumer_secret = tenant.mpesa_consumer_secret
+    mpesa.shortcode = tenant.mpesa_shortcode
+    mpesa.passkey = tenant.mpesa_passkey
+  end
 end
+
+gateway = tenant_context.gateway(:mpesa)
+gateway.equal?(tenant_context.gateway(:mpesa)) # => true (memoized per context)
+gateway.equal?(Lipwa.gateway(:mpesa))          # => false (process-wide gateway)
 ```
 
-`consumer_key`/`consumer_secret` authenticate every Daraja call (OAuth2
-client-credentials, cached and auto-refreshed). `shortcode`/`passkey` are
-only needed for STK Push and C2B. `initiator_name`/`initiator_password`/
-`security_credential_cert` are only needed if you call `#disburse` — see
-[Disbursement](#disbursement-b2c--b2b) for what the cert is and where to
-get it. Configuring only what you actually use is fine; each capability
-raises `Lipwa::ConfigurationError` at call time if something it needs is
-missing, not at load time.
+`Lipwa::Context.new` accepts the same block. Settings are frozen when the block
+finishes, and typed overrides are validated during construction. Later global
+reconfiguration does not affect an existing context. Each context owns its gateway
+instances; pass the context explicitly to your application code. There is no
+thread-local tenant state. Logger and other service objects retain their identity;
+configuration strings, arrays, and hashes are copied and frozen.
 
-Fetch a configured gateway by name instead of referencing the class
-directly:
+`Lipwa.configure`, gateway-class `.configure`, and `Lipwa.gateway(:mpesa)`
+remain supported and backward compatible for process-wide configuration.
+Configure defaults at boot; do not repeatedly mutate gateway-class configuration
+per request to switch tenants. Load tenant secrets when constructing the context,
+then retain one context per tenant. Lipwa's HTTP log redaction also applies to
+context gateways; avoid logging raw credentials or configuration.
+See [contexts and the tenant service example](docs/gateways.md#contexts) for
+inheritance, snapshot timing, and credential rotation.
 
-```ruby
-Lipwa.gateway(:mpesa).stk_push(...)
-```
+## Lightning Network (LNbits)
 
-## Usage
+LNbits is the only Lightning backend supported today. The authentication
+strategy and capability-based gateway shape allow other REST-based Lightning
+backends to register their own gateway class later without changing this API.
 
-### STK Push (Lipa Na M-Pesa Online)
+### Configuration
 
-Pushes a payment prompt to the payer's phone. The actual result of the
-payment arrives later at `callback_url` — a successful call here only
-confirms Daraja *accepted* the request, not that the customer paid.
+Configure the URL of your hosted or self-hosted LNbits instance and its scoped
+invoice/read key. Receiving payments only requires this less-privileged key.
+Configure the separate admin key only when the application sends payments.
 
 ```ruby
-result = Lipwa.gateway(:mpesa).stk_push(
-  amount: Lipwa::Money.new(amount: 100, currency: "KES"), # 100 = 1.00 KES, minor units
-  phone_number: "254712345678",
-  account_reference: "ORDER-123",
-  callback_url: "https://example.com/webhooks/mpesa/stk"
-)
-
-result.either(
-  ->(response) { response.provider_reference }, # CheckoutRequestID
-  ->(error) { logger.error(error.message) }
-)
+Lipwa::Gateways::Lnbits.configure do |config|
+  config.base_url = ENV.fetch("LNBITS_BASE_URL")
+  config.invoice_key = ENV.fetch("LNBITS_INVOICE_KEY")
+  # Optional and deliberately separate: only configure this when sending.
+  config.admin_key = ENV["LNBITS_ADMIN_KEY"]
+end
 ```
 
-### C2B (Customer to Business)
+### Usage
 
-Registers the validation/confirmation webhook URLs Daraja calls when a
-customer pays your paybill/till directly (outside STK Push), and — sandbox
-only — simulates such a payment so you can exercise those URLs without a
-real transaction.
+Lightning invoice amounts are positive integer satoshi amounts, rather than
+`Lipwa::Money` values:
 
 ```ruby
-Lipwa.gateway(:mpesa).register_urls(
-  validation_url: "https://example.com/webhooks/mpesa/validate",
-  confirmation_url: "https://example.com/webhooks/mpesa/confirm"
-)
+lnbits = Lipwa.gateway(:lnbits)
 
-# Sandbox only:
-Lipwa.gateway(:mpesa).simulate(
-  amount: Lipwa::Money.new(amount: 100, currency: "KES"),
-  phone_number: "254712345678",
-  bill_ref_number: "ORDER-123"
+invoice_result = lnbits.create_invoice(
+  amount_sats: 2_100,
+  memo: "Order ORDER-123",
+  expiry: 900
 )
-```
-
-### Disbursement (B2C / B2B)
 
-`#disburse` sends money out from your shortcode — to a customer's phone
-(B2C: salaries, promotions, business payments) or to another business
-(B2B: paybill/till settlement) — driven by `command_id` rather than two
-separate methods:
+invoice = invoice_result.value!
+invoice.provider_reference       # payment_hash, used by #check_invoice
+invoice.raw["payment_request"]   # BOLT11 string; render this as a QR code
 
-```ruby
-# B2C — pay out to a customer's phone
-result = Lipwa.gateway(:mpesa).disburse(
-  command_id: "SalaryPayment", # or "BusinessPayment" / "PromotionPayment"
-  amount: Lipwa::Money.new(amount: 5_000_00, currency: "KES"),
-  party_b: "254712345678", # payee MSISDN
-  remarks: "August salary",
-  result_url: "https://example.com/webhooks/mpesa/b2c/result",
-  queue_timeout_url: "https://example.com/webhooks/mpesa/b2c/timeout",
-  occasion: "August payroll"
+status_result = lnbits.check_invoice(
+  payment_hash: invoice.provider_reference
 )
 
-# B2B — settle with another business shortcode
-result = Lipwa.gateway(:mpesa).disburse(
-  command_id: "BusinessPayBill", # or "BusinessBuyGoods" / "MerchantToMerchantTransfer"
-  amount: Lipwa::Money.new(amount: 10_000_00, currency: "KES"),
-  party_b: "600000", # payee business shortcode
-  remarks: "Supplier settlement",
-  result_url: "https://example.com/webhooks/mpesa/b2b/result",
-  queue_timeout_url: "https://example.com/webhooks/mpesa/b2b/timeout",
-  account_reference: "INV-2026-08-001" # required for B2B command IDs
-)
+status = status_result.value!
+status.success?       # true only when LNbits reports paid == true
+status.raw["paid"]   # the provider's raw payment status
 ```
 
-Like STK Push, `#disburse` only confirms Daraja *accepted* the request
-(`ConversationID`) — the outcome (success or failure of the actual
-payout) arrives later at `result_url`.
+An unpaid invoice check is still a successful `Dry::Monads::Result`; inspect
+`Lipwa::Response#success?` to distinguish paid from unpaid. `Failure` is
+reserved for validation and transport errors.
 
-**About `security_credential_cert`**: Daraja requires every B2C/B2B
-request to carry a `SecurityCredential` — your initiator password,
-RSA-encrypted with Safaricom's public certificate. Lipwa does this
-encryption for you (see `Lipwa::Gateways::Mpesa::SecurityCredential`); you
-just need to supply the certificate itself as PEM/DER content via
-`security_credential_cert`. Download it from the Daraja developer
-portal — the **Test Credentials** page for sandbox, or your app's
-production certificate for production — since sandbox and production use
-different certificates and mixing them up causes every B2C/B2B request to
-fail. Don't hardcode certificate content in source; load it from a file or
-secret store, e.g. `c.security_credential_cert = File.read("certs/mpesa_production.cer")`.
+### Outbound payments
 
-### Refund
-
-`#refund` reverses a completed M-Pesa transaction by its `TransactionID`
-(Daraja's Transaction Reversal API):
+Paying a BOLT11 invoice requires the LNbits wallet admin key. This credential
+can spend the wallet balance and is never used as a fallback for `invoice_key`:
 
 ```ruby
-result = Lipwa.gateway(:mpesa).refund(
-  transaction_id: "OEI2AK4Q16",
-  amount: Lipwa::Money.new(amount: 100_00, currency: "KES"),
-  remarks: "Missing item",
-  result_url: "https://example.com/webhooks/mpesa/reversal/result",
-  queue_timeout_url: "https://example.com/webhooks/mpesa/reversal/timeout",
-  occasion: "Customer complaint"
-)
+payment_result = lnbits.pay_invoice(bolt11: "lnbc...")
+payment = payment_result.value!
+
+if payment.success?
+  puts "settled: #{payment.provider_reference}"
+elsif payment.raw["status"] == "pending"
+  # Reconcile later; do not submit the invoice again.
+  payment = lnbits.check_payment(
+    payment_hash: payment.provider_reference
+  ).value!
+end
 ```
 
-Like `#disburse`, `#refund` only confirms Daraja *accepted* the reversal
-request — the outcome arrives later at `result_url`. It requires the same
-`security_credential_cert` as `#disburse` — see
-[Disbursement](#disbursement-b2c--b2b) for what the cert is and where to
-get it.
+`pay_invoice` is a synchronous submission, but settlement can remain pending
+or become indeterminate if the request times out. A timeout is not proof of
+failure and must not trigger an automatic retry. Reconcile the original
+payment with `check_payment` before taking further action.
 
-### Webhook handling
+### Webhooks
 
-Daraja delivers STK Push results and C2B validation/confirmation as
-inbound HTTP callbacks. Parse and (for M-Pesa) verify them with
-`Lipwa::Webhook`:
+LNbits does not sign payment webhooks. Mint a strong per-invoice token, embed
+it in the HTTPS webhook URL, and store it with the returned payment hash. A
+valid token makes the callback a useful low-latency notification, but it is
+not proof of payment: always call `check_invoice` before crediting the payer.
 
 ```ruby
-# in your webhook controller
-result = Lipwa::Webhook.parse_webhook(provider: :mpesa, body: request.body.read, headers: request.headers)
+require "securerandom"
+require "uri"
+
+# When creating the invoice:
+webhook_token = SecureRandom.hex(32)
+webhook_url = "https://payments.example.com/webhooks/lnbits?#{
+  URI.encode_www_form(token: webhook_token)
+}"
+
+invoice_result = lnbits.create_invoice(
+  amount_sats: 2_100,
+  memo: "Order ORDER-123",
+  webhook_url: webhook_url
+)
+invoice = invoice_result.value!
 
-result.either(
-  lambda do |event|
-    if event.verify_signature(source_ip: request.remote_ip)
-      # event.event_type   => :stk_callback or :c2b
-      # event.success?     => whether the STK push succeeded (always true for C2B —
-      #                       C2B callbacks only fire for an already-completed payment)
-      # event.provider_reference => CheckoutRequestID (STK) or TransID (C2B)
-      handle(event)
-    else
-      head :forbidden
-    end
-  end,
-  ->(error) { logger.error(error.message) }
+# Persist both values against the order. Never put an LNbits API key in the URL.
+order.update!(
+  lightning_payment_hash: invoice.provider_reference,
+  lightning_webhook_token: webhook_token
+)
+
+# In the webhook controller/handler:
+event_result = Lipwa::Webhook.parse_webhook(
+  provider: :lnbits,
+  body: request.body.read,
+  headers: request.headers
 )
+event = event_result.value!
+order = Order.find_by!(lightning_payment_hash: event.provider_reference)
+
+verified = event.verify_signature(
+  expected_token: order.lightning_webhook_token,
+  provided_token: request.params["token"]
+)
+head :unauthorized and return unless verified
+
+# Token verification alone is insufficient: ask LNbits for authoritative state.
+status_result = lnbits.check_invoice(payment_hash: event.provider_reference)
+status = status_result.value!
+head :unprocessable_entity and return unless status.success?
+
+order.credit_once!
+head :ok
 ```
 
-M-Pesa doesn't cryptographically sign callbacks, so `verify_signature`
-checks the request's source IP against Safaricom's published callback IP
-ranges instead — always call it before trusting a callback's contents.
+## Capability matrix
 
-### `Lipwa::Money`
+| Gateway | Capabilities |
+| --- | --- |
+| `:mpesa` | `stk_push`, `c2b`, `disbursement`, `status_query`, `refund` |
+| `:coop_bank` | `bank_transfer`: transfer, balance, statement |
+| `:jenga` | `bank_transfer`, `disbursement`, plus `forex_rates` |
+| `:lnbits` | `lightning_invoice`: receive; `lightning_payment`: pay and reconcile |
 
-Amounts are always a `Lipwa::Money` — an immutable value object storing
-minor currency units (e.g. `100` = KES 1.00) plus an ISO 4217 currency
-code (defaults to `"KES"`):
+## Money
+
+`Lipwa::Money` stores non-negative amounts as constrained `BigDecimal` values.
+Addition, subtraction, and comparison require matching currencies;
+multiplication and division accept numeric scalars.
 
 ```ruby
-Lipwa::Money.new(amount: 100, currency: "KES")
+price = Lipwa::Money.new(amount: "100.25", currency: "KES")
+tax = Lipwa::Money.new(amount: "16.04", currency: "KES")
+
+(price + tax).to_s # => "116.29 KES"
+(price * 2).to_s   # => "200.5 KES"
 ```
 
-## Error handling
+Currency conversion is never implicit.
+
+## Results and errors
+
+Operations return `Success(Lipwa::Response)`, `Failure(Lipwa::ValidationError)`,
+or `Failure(Lipwa::GatewayError)`. Configuration and unsupported-provider
+errors are raised because they are programmer or deployment mistakes.
 
-Gateway methods (`#stk_push`, `#register_urls`, `#simulate`, `#disburse`)
-never raise for expected failure modes — they return a
-`Dry::Monads::Result`:
+For asynchronous operations, persist `response.provider_reference` and
+correlate it with a verified webhook. Never treat request acknowledgement as
+the final transaction outcome.
 
-- `Success(Lipwa::Response)` — `#success?`, `#provider_reference`,
-  `#message`, `#code`, `#raw` (the parsed provider response). Note a
-  `Success` can still wrap `response.success? == false` — Daraja
-  synchronous validation errors (bad shortcode, malformed request) come
-  back as a normal 200 response with a non-zero `ResponseCode`.
-- `Failure(Lipwa::ValidationError)` — your params failed contract
-  validation before any network call was made.
-- `Failure(Lipwa::GatewayError)` — the HTTP call itself failed (timeout,
-  connection error) or the provider returned an HTTP error status.
+## Documentation
 
-`Lipwa::ConfigurationError` and `Lipwa::UnsupportedCapabilityError` are
-raised, not wrapped — they represent programmer/ops mistakes (missing
-credentials, calling a capability a gateway doesn't include) that should
-fail loudly at call time rather than be routed through error-handling
-code.
+- [Documentation home](docs/index.md)
+- [Getting started](docs/getting-started.md)
+- [Capabilities](docs/capabilities.md)
+- [Gateway configuration](docs/gateways.md)
+- [Webhooks](docs/webhooks.md)
+- [Reliability and errors](docs/reliability.md)
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies.
-Then, run `rake test` to run the tests. You can also run `bin/console` for
-an interactive prompt that will allow you to experiment.
+```bash
+bin/setup
+bundle exec rake
+bin/console
+```
 
-Tests run against hand-authored VCR cassettes
-(`test/fixtures/vcr_cassettes/mpesa/`) with fake sandbox credentials —
-they never hit Safaricom's real sandbox, so no network access or real
-credentials are needed to run the suite.
+Tests use WebMock and sanitized VCR fixtures; they do not contact live provider
+sandboxes.
 
+## Contributing and license
 `examples/rails_api` is a small Rails API app that exercises every
 capability against a real (sandbox) Daraja account — STK Push, C2B,
 disbursement, refund, and inbound webhooks — useful both for evaluating
@@ -269,20 +297,7 @@ install`. To release a new version, update the version number in
 git tag for the version, push git commits and the created tag, and push
 the `.gem` file to [rubygems.org](https://rubygems.org).
 
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at
-https://github.com/kamalogudah/lipwa. This project is intended to be a
-safe, welcoming space for collaboration, and contributors are expected to
-adhere to the [code of conduct](https://github.com/kamalogudah/lipwa/blob/master/CODE_OF_CONDUCT.md).
-
-## License
-
-The gem is available as open source under the terms of the
-[MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the Lipwa project's codebases, issue trackers,
-chat rooms and mailing lists is expected to follow the
-[code of conduct](https://github.com/kamalogudah/lipwa/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/kamalogudah/lipwa). Please follow the
+[code of conduct](CODE_OF_CONDUCT.md). Lipwa is available under the
+[MIT License](LICENSE.txt).

data/Rakefile

@@ -9,4 +9,15 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
+namespace :docs do
+  desc "Build the documentation site"
+  task :build do
+    require "jekyll"
+    Jekyll::Commands::Build.process(
+      source: File.expand_path("docs", __dir__),
+      destination: File.expand_path("_site", __dir__)
+    )
+  end
+end
+
 task default: %i[test rubocop]

data/docs/README.md

@@ -0,0 +1,15 @@
+# Lipwa documentation site
+
+This directory is the source for the Lipwa documentation site. It uses Jekyll
+with a custom layout and has no theme or plugin dependency.
+
+From the repository root:
+
+```bash
+bundle install
+bundle exec rake docs:build
+```
+
+The generated site is written to `_site/`. GitHub Pages can publish directly
+from the `docs/` directory on the main branch; `baseurl` in `_config.yml` is
+already set for the `/lipwa` project path.

data/docs/_config.yml

@@ -0,0 +1,11 @@
+title: Lipwa
+description: Capability-based payment APIs for Ruby
+url: https://kamalogudah.github.io
+baseurl: /lipwa
+permalink: pretty
+markdown: kramdown
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: default

data/docs/_layouts/default.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="theme-color" content="#102a25">
+    <meta name="description" content="{{ page.description | default: site.description }}">
+    <title>{% if page.title %}{{ page.title }} · {% endif %}{{ site.title }}</title>
+    <link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">
+  </head>
+  <body>
+    <a class="skip-link" href="#content">Skip to content</a>
+    <header class="site-header">
+      <a class="brand" href="{{ '/' | relative_url }}"><span class="brand-mark">L</span> Lipwa</a>
+      <button class="nav-toggle" type="button" aria-expanded="false" aria-controls="site-nav">Menu</button>
+      <nav id="site-nav" class="site-nav" aria-label="Primary">
+        <a href="{{ '/getting-started/' | relative_url }}">Start</a>
+        <a href="{{ '/capabilities/' | relative_url }}">Capabilities</a>
+        <a href="{{ '/gateways/' | relative_url }}">Gateways</a>
+        <a href="{{ '/webhooks/' | relative_url }}">Webhooks</a>
+        <a href="{{ '/reliability/' | relative_url }}">Reliability</a>
+        <a href="https://github.com/kamalogudah/lipwa">GitHub ↗</a>
+      </nav>
+    </header>
+    <main id="content" class="page-shell">{{ content }}</main>
+    <footer class="site-footer"><span>Lipwa · payment flows, honestly modeled</span><a href="https://github.com/kamalogudah/lipwa/blob/master/LICENSE.txt">MIT licensed</a></footer>
+    <script>
+      const button = document.querySelector(".nav-toggle");
+      const nav = document.querySelector(".site-nav");
+      button.addEventListener("click", () => {
+        const open = button.getAttribute("aria-expanded") === "true";
+        button.setAttribute("aria-expanded", String(!open));
+        nav.classList.toggle("is-open", !open);
+      });
+    </script>
+  </body>
+</html>

data/docs/assets/css/style.css

@@ -0,0 +1,8 @@
+:root{--ink:#15231f;--muted:#586b65;--paper:#fbfaf5;--panel:#f0f4ed;--line:#d7dfd7;--green:#16735d;--dark:#102a25;--lime:#d8f06d;--code:#11231f;--max:1120px}
+*{box-sizing:border-box}html{scroll-behavior:smooth;scroll-padding-top:6rem}body{margin:0;color:var(--ink);background:radial-gradient(circle at 88% 2%,rgba(216,240,109,.24),transparent 24rem),var(--paper);font:17px/1.7 Inter,ui-sans-serif,system-ui,-apple-system,sans-serif}a{color:var(--green);text-underline-offset:.2em}.skip-link{position:fixed;top:-4rem;left:1rem;z-index:10;padding:.65rem 1rem;color:white;background:var(--dark)}.skip-link:focus{top:1rem}
+.site-header{position:sticky;top:0;z-index:5;display:flex;align-items:center;justify-content:space-between;min-height:72px;padding:0 max(24px,calc((100vw - var(--max))/2));border-bottom:1px solid rgba(21,35,31,.12);background:rgba(251,250,245,.94);backdrop-filter:blur(16px)}.brand{display:flex;align-items:center;gap:.65rem;color:var(--dark);font-weight:800;text-decoration:none}.brand-mark{display:grid;width:34px;height:34px;place-items:center;border-radius:9px;background:var(--lime);font-family:ui-monospace,monospace}.site-nav{display:flex;gap:1.35rem}.site-nav a{color:var(--ink);font-size:.9rem;font-weight:650;text-decoration:none}.site-nav a:hover{color:var(--green)}.nav-toggle{display:none}
+.page-shell{width:min(calc(100% - 48px),var(--max));min-height:calc(100vh - 160px);margin:auto;padding:4.5rem 0 6rem}.hero{display:grid;grid-template-columns:1.15fr .85fr;gap:clamp(2rem,6vw,6rem);align-items:center;min-height:560px;padding:2rem 0 5rem}.eyebrow{margin:0 0 .7rem;color:var(--green);font-size:.78rem;font-weight:800;letter-spacing:.13em;text-transform:uppercase}h1,h2,h3{color:var(--dark);font-weight:800;line-height:1.12;letter-spacing:-.035em}h1{max-width:850px;margin:0 0 1.25rem;font-size:clamp(2.65rem,7vw,5.6rem)}h2{margin:3.5rem 0 1rem;font-size:clamp(1.65rem,4vw,2.6rem)}h3{margin:2.2rem 0 .5rem;font-size:1.25rem}p,ul,ol{max-width:780px}.lead{color:var(--muted);font-size:clamp(1.08rem,2vw,1.35rem)}
+.actions{display:flex;gap:.75rem;margin-top:2rem}.button{padding:.72rem 1.05rem;border:1px solid var(--dark);border-radius:8px;color:white;background:var(--dark);font-weight:750;text-decoration:none}.button.secondary{color:var(--dark);background:transparent}.terminal{overflow:hidden;border:1px solid #29443c;border-radius:14px;box-shadow:0 24px 80px rgba(16,42,37,.18);background:var(--code)}.terminal-bar{display:flex;gap:6px;padding:14px 16px;border-bottom:1px solid #29443c}.terminal-dot{width:9px;height:9px;border-radius:50%;background:#547269}.terminal-dot:last-child{background:var(--lime)}
+pre{overflow-x:auto;padding:1.25rem 1.35rem;border-radius:10px;color:#e7f1ec;background:var(--code);font:.87rem/1.65 ui-monospace,monospace}.terminal pre{margin:0;border-radius:0}code{padding:.12em .35em;border-radius:4px;color:#165b4c;background:#e7eee7;font-size:.88em}pre code{padding:0;color:inherit;background:transparent;font-size:inherit}.grid{display:grid;grid-template-columns:repeat(3,1fr);gap:1rem;margin:2rem 0}.card{padding:1.5rem;border:1px solid var(--line);border-radius:12px;background:rgba(255,255,255,.6)}.card h3{margin-top:0}.card p{margin-bottom:0;color:var(--muted);font-size:.95rem}.number{color:var(--green);font:700 .8rem ui-monospace,monospace}.callout{margin:2rem 0;padding:1rem 1.25rem;border-left:4px solid var(--green);background:var(--panel)}
+table{width:100%;margin:1.5rem 0 2.5rem;border-collapse:collapse;font-size:.94rem}th,td{padding:.8rem .9rem;border-bottom:1px solid var(--line);text-align:left;vertical-align:top}th{color:var(--dark);background:var(--panel);font-size:.78rem;text-transform:uppercase}.page-title{padding-bottom:2rem;border-bottom:1px solid var(--line)}.page-title h1{font-size:clamp(2.5rem,6vw,4.5rem)}.doc-nav{display:flex;justify-content:space-between;margin-top:4rem;padding-top:1.5rem;border-top:1px solid var(--line)}.site-footer{display:flex;justify-content:space-between;padding:2rem max(24px,calc((100vw - var(--max))/2));color:var(--muted);border-top:1px solid var(--line);font-size:.82rem}
+@media(max-width:800px){.hero{grid-template-columns:1fr;min-height:auto}.grid{grid-template-columns:1fr}.nav-toggle{display:block;padding:.45rem .7rem;border:1px solid var(--line);border-radius:6px;background:transparent}.site-nav{position:absolute;top:71px;right:0;left:0;display:none;flex-direction:column;padding:.5rem 24px 1rem;background:var(--paper)}.site-nav.is-open{display:flex}.site-nav a{padding:.6rem 0}.page-shell{width:min(calc(100% - 32px),var(--max));padding-top:3rem}.site-footer{flex-direction:column}table{display:block;overflow-x:auto}}