lipwa 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ed1d0107830b6fafe1757cc253a820b57fe62c99f38ec78e1d2adde62e10eaa
-  data.tar.gz: 85994d9fe4d49e276892154fc600ae06f420740a55c5580f9bbac6cfbcc3d14b
+  metadata.gz: 184f658687e8cc70f00f9053c7ee5eddf4a3d19679843dd74604abcba4806183
+  data.tar.gz: 7c3d66d4138ceaf01fb053d5cbb11d499321016f0e0078e63fbab24252a9e68a
 SHA512:
-  metadata.gz: 37ebc5f8bff81213d7949b33c984ac4f18bf32b6386b25323665fcf86f8f6a1d838759cbcb4c49fba3f0f4274d1e3a6bdabcd8b78600bf24ad23554e26adc253
-  data.tar.gz: 83d40bb47c71c2fb3f98ba51021b3bcbee44d91610d8407fa44975add4261f894c999f5cb109a370af1bae301fee906ef0f0e89de75993799e3846f7085eec89
+  metadata.gz: 0d6a8dd5390049cc230bca9cfffe383eaa511b112e038e1ae66aec4d87548e77714b210e53e58f29bf4be95ab830c77be8a75fd31236f7fa50018261d482c947
+  data.tar.gz: ce26c22b739fcdc0c27e5c97a8379722db6b8a8ddd87c2d7e744817ab3f2f162b149e5c47734c10a93582fd9aee463b73e2efc0a7aeef774ce7dec1344034eb3

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.1.4] - 2026-09-07
+
+- Use an explicit package allowlist to exclude documentation site sources,
+  development tasks, contributor guidance, and placeholder RBS signatures from
+  the installed gem while retaining runtime files, the license, README, and changelog
+
 ## [0.1.3] - 2026-09-06
 
 - Add Co-op Bank support for bank transfers, balance and statement inquiries,

data/lib/lipwa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lipwa
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lipwa
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Paul Oguda
@@ -147,20 +147,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
-- Rakefile
-- docs/README.md
-- docs/_config.yml
-- docs/_layouts/default.html
-- docs/assets/css/style.css
-- docs/capabilities.md
-- docs/gateways.md
-- docs/getting-started.md
-- docs/index.md
-- docs/reliability.md
-- docs/webhooks.md
 - lib/lipwa.rb
 - lib/lipwa/auth_strategies.rb
 - lib/lipwa/auth_strategies/api_key.rb
@@ -223,7 +211,6 @@ files:
 - lib/lipwa/webhooks/jenga.rb
 - lib/lipwa/webhooks/lnbits.rb
 - lib/lipwa/webhooks/mpesa.rb
-- sig/lipwa.rbs
 homepage: https://github.com/kamalogudah/lipwa
 licenses:
 - MIT

data/CODE_OF_CONDUCT.md

@@ -1,10 +0,0 @@
-# Code of Conduct
-
-"lipwa" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
-
-* Participants will be tolerant of opposing views.
-* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
-* When interpreting the words and actions of others, participants should always assume good intentions.
-* Behaviour which can be reasonably considered harassment will not be tolerated.
-
-If you have any concerns about behaviour within this project, please contact us at ["mcpaul2058@gmail.com"](mailto:"mcpaul2058@gmail.com").

data/Rakefile

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "minitest/test_task"
-
-Minitest::TestTask.create
-
-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

@@ -1,15 +0,0 @@
-# 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

@@ -1,11 +0,0 @@
-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

@@ -1,37 +0,0 @@
-<!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

@@ -1,8 +0,0 @@
-: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}}

data/docs/capabilities.md

@@ -1,116 +0,0 @@
----
-title: Capabilities
-description: Reference for Lipwa payment operations.
----
-
-<header class="page-title"><p class="eyebrow">Guide 02</p><h1>Capabilities</h1><p class="lead">A capability describes a payment flow. Gateways include only the modules they support.</p></header>
-
-{% highlight ruby %}gateway = Lipwa.gateway(:jenga)
-gateway.capability?(:bank_transfer) # => true{% endhighlight %}
-
-| Capability | Methods | Gateways |
-| --- | --- | --- |
-| `stk_push` | `stk_push` | M-Pesa |
-| `c2b` | `register_urls`, `simulate` | M-Pesa |
-| `disbursement` | `disburse` | M-Pesa, Jenga |
-| `status_query` | `status` | M-Pesa |
-| `refund` | `refund` | M-Pesa |
-| `bank_transfer` | `transfer`, `balance`, `statement` | Co-op, Jenga |
-| `lightning_invoice` | `create_invoice`, `check_invoice` | LNbits-backed gateways |
-| `lightning_payment` | `pay_invoice`, `check_payment` | LNbits-backed gateways |
-
-Lightning invoice amounts are positive integer satoshis (`amount_sats`), not
-`Lipwa::Money` values. A created invoice's BOLT11 string is stored in
-`response.raw["payment_request"]`; its payment hash is
-`response.provider_reference`. Checking an unpaid invoice still returns
-`Success(Response)`, with `response.success? == false`.
-
-Outbound Lightning payments use the separate `lightning_payment` capability
-and require an explicitly configured wallet admin key. That key can spend the
-wallet balance; it never replaces the receive-only invoice key. A payment may
-remain `pending`, and a transport timeout leaves its outcome unknown. Inspect
-`response.raw["status"]` and call `check_payment` to reconcile it; never retry
-an indeterminate payment automatically.
-
-{% highlight ruby %}lnbits.pay_invoice(bolt11: "lnbc...")
-lnbits.check_payment(payment_hash: "..."){% endhighlight %}
-
-
-## Collection
-
-{% highlight ruby %}mpesa = Lipwa.gateway(:mpesa)
-
-mpesa.stk_push(
-  amount: Lipwa::Money.new(amount: 100, currency: "KES"),
-  phone_number: "254712345678",
-  account_reference: "ORDER-123",
-  callback_url: "https://example.com/webhooks/mpesa"
-)
-
-mpesa.register_urls(
-  validation_url: "https://example.com/mpesa/validation",
-  confirmation_url: "https://example.com/mpesa/confirmation"
-)
-
-mpesa.simulate(
-  amount: Lipwa::Money.new(amount: 100, currency: "KES"),
-  phone_number: "254712345678",
-  bill_ref_number: "ORDER-123"
-){% endhighlight %}
-
-`simulate` is for M-Pesa sandbox testing.
-
-## Disbursement, status, and refund
-
-{% highlight ruby %}mpesa.disburse(
-  command_id: "BusinessPayment",
-  amount: Lipwa::Money.new(amount: 500, currency: "KES"),
-  party_b: "254712345678",
-  remarks: "Supplier payout",
-  result_url: "https://example.com/mpesa/payout/result",
-  queue_timeout_url: "https://example.com/mpesa/payout/timeout"
-)
-
-mpesa.status(
-  transaction_id: "OEI2AK4Q16",
-  remarks: "Reconcile order",
-  result_url: "https://example.com/mpesa/status/result",
-  queue_timeout_url: "https://example.com/mpesa/status/timeout"
-)
-
-mpesa.refund(
-  transaction_id: "OEI2AK4Q16",
-  amount: Lipwa::Money.new(amount: 100, currency: "KES"),
-  remarks: "Customer refund",
-  result_url: "https://example.com/mpesa/refund/result",
-  queue_timeout_url: "https://example.com/mpesa/refund/timeout"
-){% endhighlight %}
-
-M-Pesa B2C command IDs are `SalaryPayment`, `BusinessPayment`, and
-`PromotionPayment`. B2B supports `BusinessPayBill`, `BusinessBuyGoods`, and
-`MerchantToMerchantTransfer` and requires `account_reference`.
-
-## Bank operations
-
-{% highlight ruby %}bank = Lipwa.gateway(:jenga)
-
-bank.transfer(
-  rail: :pesalink,
-  amount: Lipwa::Money.new(amount: "2500.00", currency: "KES"),
-  source_account: "00123456789",
-  destination_account: "00987654321",
-  destination_name: "Amina N.",
-  reference: "INV-1042"
-)
-
-bank.balance(account_number: "00123456789")
-bank.statement(account_number: "00123456789",
-               from_date: Date.new(2026, 8, 1),
-               to_date: Date.new(2026, 8, 31)){% endhighlight %}
-
-Rails are `internal`, `rtgs`, `pesalink`, `swift`, and `bill_payment`,
-subject to provider availability. RTGS/SWIFT require
-`destination_bank_code`; bill payment requires `biller_code`. Jenga also
-exposes `forex_rates`.
-
-<nav class="doc-nav"><a href="{{ '/getting-started/' | relative_url }}">← Getting started</a><a href="{{ '/gateways/' | relative_url }}">Gateways →</a></nav>

data/docs/gateways.md

@@ -1,158 +0,0 @@
----
-title: Gateways
-description: Configure M-Pesa, Co-op Bank, and Jenga HQ.
----
-
-<header class="page-title"><p class="eyebrow">Guide 03</p><h1>Gateways</h1><p class="lead">Configure process-wide defaults or isolate each tenant's credentials and HTTP settings in a context.</p></header>
-
-## Process-wide defaults
-
-`Lipwa.configure` sets shared `logger`, `default_timeout`, and Faraday `adapter`
-defaults. Gateway-class `.configure` sets provider credentials, environment, and
-HTTP overrides, as shown below. These APIs and `Lipwa.gateway(:mpesa)` remain
-supported and backward compatible; existing single-tenant applications do not
-need to adopt contexts.
-
-Configure defaults at boot before resolving gateways or constructing contexts.
-`Lipwa.gateway(:mpesa)` lazily constructs and memoizes one process-wide gateway.
-Its provider and shared settings are captured on the first lookup; later
-configuration changes do not update that instance. Direct construction with
-`Lipwa::Gateways::Mpesa.new` captures defaults at construction time instead.
-
-## M-Pesa
-
-{% highlight ruby %}Lipwa::Gateways::Mpesa.configure do |c|
-  c.env = :sandbox
-  c.consumer_key = ENV.fetch("MPESA_CONSUMER_KEY")
-  c.consumer_secret = ENV.fetch("MPESA_CONSUMER_SECRET")
-  c.shortcode = ENV.fetch("MPESA_SHORTCODE")
-  c.passkey = ENV.fetch("MPESA_PASSKEY")
-end{% endhighlight %}
-
-Lipwa chooses the Daraja host and manages OAuth tokens.
-
-## Co-op Bank
-
-{% highlight ruby %}Lipwa::Gateways::CoopBank.configure do |c|
-  c.env = :sandbox
-  c.api_key = ENV.fetch("COOP_API_KEY")
-  c.api_secret = ENV.fetch("COOP_API_SECRET")
-  c.base_url = ENV["COOP_BASE_URL"]   # optional override
-  c.token_url = ENV["COOP_TOKEN_URL"] # optional override
-end{% endhighlight %}
-
-`client_id` and `client_secret` are aliases for `api_key` and `api_secret`.
-
-## Jenga HQ
-
-{% highlight ruby %}Lipwa::Gateways::Jenga.configure do |c|
-  c.env = :sandbox
-  c.api_key = ENV.fetch("JENGA_API_KEY")
-  c.merchant_code = ENV.fetch("JENGA_MERCHANT_CODE")
-  c.consumer_secret = ENV.fetch("JENGA_CONSUMER_SECRET")
-  c.private_key = File.read(ENV.fetch("JENGA_PRIVATE_KEY_PATH"))
-  c.source_account = ENV.fetch("JENGA_SOURCE_ACCOUNT")
-  c.source_name = ENV.fetch("JENGA_SOURCE_NAME")
-  c.country_code = "KE"
-  c.partner_id = ENV["JENGA_PARTNER_ID"]
-end{% endhighlight %}
-
-Lipwa obtains bearer tokens and signs provider requests.
-
-## Per-gateway HTTP settings
-
-{% highlight ruby %}Lipwa::Gateways::Jenga.configure do |c|
-  c.timeout = 20
-  c.open_timeout = 5
-  c.logger = MyStructuredLogger.new
-end{% endhighlight %}
-
-Logs recursively redact authorization, credentials, cookies, passwords,
-tokens, and secret-like fields.
-
-## Contexts
-
-`Lipwa.context { |config| ... }` (or `Lipwa::Context.new` with the same block)
-captures `Lipwa.config` and every currently registered gateway class's settings
-before running the builder block. Unspecified settings inherit those captured
-defaults. `config.gateway(:mpesa) { |mpesa| ... }` overrides only that context's
-M-Pesa settings. Provider `timeout` and `logger` take precedence over shared
-`default_timeout` and `logger`; otherwise the shared defaults apply.
-
-The snapshot happens when the context is constructed, even if its first gateway
-lookup is much later. Subsequent global changes and registrations do not alter
-an existing context. Overrides do not change process-wide defaults or other
-contexts. Typed overrides are validated during construction.
-
-When the block finishes, configuration is immutable: configuration strings,
-arrays, and hashes are copied and frozen. Logger and other service objects retain
-their identity rather than being deeply copied or frozen. Gateway runtime state,
-such as HTTP clients and OAuth token caches, can still change.
-
-Each context lazily constructs and memoizes its own gateway instances. Repeated
-`tenant_context.gateway(:mpesa)` calls return the same instance, distinct from
-another context's gateway and from `Lipwa.gateway(:mpesa)`. Built-in provider HTTP
-clients, authentication, and token caches belong to those gateway instances.
-Pass contexts explicitly; there is no thread-local current tenant.
-
-### Retain one context per tenant
-
-Construct one service object per tenant and retain it across payment calls. Here
-`secrets_for` is an application-supplied callable that loads that tenant's secrets
-from your credential store during context construction:
-
-{% highlight ruby %}class TenantPayments
-  attr_reader :context
-
-  def initialize(tenant_id:, secrets_for:)
-    @context = Lipwa.context do |config|
-      secrets = secrets_for.call(tenant_id)
-      config.default_timeout = 20
-      config.gateway(:mpesa) do |mpesa|
-        mpesa.env = :production
-        mpesa.consumer_key = secrets.fetch(:consumer_key)
-        mpesa.consumer_secret = secrets.fetch(:consumer_secret)
-        mpesa.shortcode = secrets.fetch(:shortcode)
-        mpesa.passkey = secrets.fetch(:passkey)
-      end
-    end
-  end
-
-  def stk_push(**params)
-    context.gateway(:mpesa).stk_push(**params)
-  end
-end
-
-# Retain these services in your application's tenant service registry.
-payments_by_tenant = tenant_ids.to_h do |tenant_id|
-  [tenant_id, TenantPayments.new(tenant_id: tenant_id, secrets_for: secrets_for)]
-end
-
-tenant_context = payments_by_tenant.fetch(tenant_id).context
-tenant_context.gateway(:mpesa) # This tenant's memoized gateway
-Lipwa.gateway(:mpesa)          # Separate process-wide gateway using boot defaults
-{% endhighlight %}
-
-Do not repeatedly mutate `Lipwa::Gateways::Mpesa.configure` per request to switch
-tenants: those defaults are shared across requests, and memoized gateways retain
-their earlier snapshots. For credential rotation, construct a replacement service
-and context with fresh secrets and use it for subsequent calls. Existing contexts
-continue using their captured credentials.
-
-Tenant secrets loaded during construction remain covered by Lipwa's HTTP log
-redaction for authorization, credentials, tokens, and secret-like fields. This
-does not sanitize arbitrary application logs: do not log raw secret hashes or
-inspect configuration objects containing credentials.
-
-### Explicit gateway construction and custom authentication
-
-Explicit `config:` and `global_config:` gateway constructor snapshots replace
-their respective defaults and are copied and finalized by the gateway.
-
-Custom `auth_strategy` objects are duplicated for each gateway. Stateful custom
-strategies should implement `initialize_copy` to isolate nested mutable state,
-or supply a zero-argument factory that creates a fresh strategy and token source.
-Callable token providers and clocks must not close over shared mutable token
-caches. Built-in OAuth clients reset their caches when copied.
-
-<nav class="doc-nav"><a href="{{ '/capabilities/' | relative_url }}">← Capabilities</a><a href="{{ '/webhooks/' | relative_url }}">Webhooks →</a></nav>

data/docs/getting-started.md

@@ -1,64 +0,0 @@
----
-title: Getting started
-description: Install Lipwa, configure a gateway, and make your first request.
----
-
-<header class="page-title"><p class="eyebrow">Guide 01</p><h1>Getting started</h1><p class="lead">Install the gem, configure one gateway, and handle the result explicitly.</p></header>
-
-## Install and configure
-
-{% highlight bash %}bundle add lipwa{% endhighlight %}
-
-{% highlight 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{% endhighlight %}
-
-## Make a request
-
-{% highlight ruby %}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) { Payment.update!(provider_reference: response.provider_reference) },
-  ->(error) { logger.error(error.message) }
-){% endhighlight %}
-
-<div class="callout"><strong>Acceptance is not settlement.</strong> STK Push, disbursement, refund, and status calls are asynchronous. Process the later verified callback for the final result.</div>
-
-## Initiator credentials
-
-Disbursement, status, and refund also require:
-
-{% highlight ruby %}Lipwa::Gateways::Mpesa.configure do |config|
-  config.initiator_name = ENV.fetch("MPESA_INITIATOR_NAME")
-  config.initiator_password = ENV.fetch("MPESA_INITIATOR_PASSWORD")
-  config.security_credential_cert =
-    File.read(ENV.fetch("MPESA_CERTIFICATE_PATH"))
-end{% endhighlight %}
-
-Sandbox and production certificates differ. Keep certificate content outside
-source control.
-
-## Idempotency
-
-Reuse one stable `idempotency_key` when retrying one logical write. Lipwa
-retries safe reads automatically, but writes only when this key is present.
-The provider controls key retention and duplicate detection.
-
-<nav class="doc-nav"><a href="{{ '/' | relative_url }}">← Home</a><a href="{{ '/capabilities/' | relative_url }}">Capabilities →</a></nav>

data/docs/index.md

@@ -1,46 +0,0 @@
----
-title: Home
-description: Unified, capability-based African payment APIs for Ruby.
----
-
-<section class="hero"><div>
-<p class="eyebrow">Payment flows, honestly modeled</p>
-<h1>One Ruby API. Only the capabilities you need.</h1>
-<p class="lead">Lipwa unifies mobile money, bank transfers, payouts, and asynchronous callbacks without pretending every provider behaves like a card gateway.</p>
-<div class="actions"><a class="button" href="{{ '/getting-started/' | relative_url }}">Get started</a><a class="button secondary" href="{{ '/capabilities/' | relative_url }}">Explore capabilities</a></div>
-</div><div class="terminal"><div class="terminal-bar"><span class="terminal-dot"></span><span class="terminal-dot"></span><span class="terminal-dot"></span></div>
-{% highlight ruby %}gateway = Lipwa.gateway(:mpesa)
-
-result = gateway.stk_push(
-  amount: Lipwa::Money.new(
-    amount: "100.00",
-    currency: "KES"
-  ),
-  phone_number: "254712345678",
-  account_reference: "ORDER-123",
-  callback_url: callback_url,
-  idempotency_key: "stk-order-123"
-)
-
-result.fmap(&:provider_reference){% endhighlight %}
-</div></section>
-
-## Designed around real payment flows
-
-<div class="grid">
-<article class="card"><span class="number">01</span><h3>Capability first</h3><p>Gateways expose operations they truly implement. Inspect support with <code>capability?</code> and route deliberately.</p></article>
-<article class="card"><span class="number">02</span><h3>Failure explicit</h3><p>Validation and provider failures travel through <code>Dry::Monads::Result</code>.</p></article>
-<article class="card"><span class="number">03</span><h3>Async aware</h3><p>Request acknowledgement and final outcome stay distinct. Normalized webhook events complete the flow.</p></article>
-</div>
-
-## Supported gateways
-
-| Gateway | What it can do |
-| --- | --- |
-| M-Pesa | STK Push, C2B, B2C/B2B, status, refunds |
-| Co-op Bank | Transfers, balances, and statements |
-| Jenga HQ | Bank/mobile transfers, account queries, forex |
-
-<div class="callout"><strong>Start with a flow, not a provider.</strong> Choose the capability your product needs, then select a gateway that advertises it.</div>
-
-<nav class="doc-nav"><span></span><a href="{{ '/getting-started/' | relative_url }}">Getting started →</a></nav>

data/docs/reliability.md

@@ -1,50 +0,0 @@
----
-title: Reliability
-description: Results, retries, idempotency, and money safety.
----
-
-<header class="page-title"><p class="eyebrow">Guide 05</p><h1>Reliability</h1><p class="lead">Expected failures are explicit, and automatic recovery is limited to operations safe to repeat.</p></header>
-
-## Results and errors
-
-| Type | Delivery | Meaning |
-| --- | --- | --- |
-| `ValidationError` | `Failure` | Input failed a capability contract |
-| `GatewayError` | `Failure` | Network or provider HTTP failure |
-| `WebhookParseError` | `Failure` | Invalid inbound JSON |
-| `ConfigurationError` | raised | Missing or invalid setup |
-| `UnsupportedProviderError` | raised | No webhook parser registered |
-
-`Lipwa::Response` exposes `success?`, `provider_reference`, `message`,
-`code`, and `raw`.
-
-## Retry policy
-
-Lipwa retries transient network exceptions and HTTP 429, 500, 502, 503, and
-504 at most twice. Backoff begins at 0.5 seconds, doubles with up to 50%
-jitter, and caps waits at 5 seconds. Server `Retry-After` and
-`RateLimit-Reset` values are honored within that cap.
-
-Safe reads retry automatically. Writes retry only with `Idempotency-Key`.
-
-## Decimal money
-
-{% highlight ruby %}subtotal = Lipwa::Money.new(amount: "199.95", currency: "KES")
-fee = Lipwa::Money.new(amount: "5.05", currency: "KES")
-
-total = subtotal + fee
-total.to_s       # => "205.0 KES"
-total > subtotal # => true{% endhighlight %}
-
-Amounts and results are non-negative. Addition, subtraction, and comparison
-across currencies raise `ArgumentError`. Currency conversion is never hidden.
-
-## Async reconciliation
-
-1. Persist a pending operation and idempotency key before calling the API.
-2. Store the synchronous provider reference.
-3. Verify and process callbacks idempotently.
-4. Use status query where supported to reconcile missing callbacks.
-5. Treat acknowledgements and callbacks as repeatable messages.
-
-<nav class="doc-nav"><a href="{{ '/webhooks/' | relative_url }}">← Webhooks</a><a href="{{ '/' | relative_url }}">Home →</a></nav>

data/docs/webhooks.md

@@ -1,72 +0,0 @@
----
-title: Webhooks
-description: Parse and verify M-Pesa, Jenga, and LNbits callbacks.
----
-
-<header class="page-title"><p class="eyebrow">Guide 04</p><h1>Webhooks</h1><p class="lead">Normalize provider payloads, then perform the provider-specific trust check before changing financial state.</p></header>
-
-## Parse
-
-{% highlight ruby %}result = Lipwa::Webhook.parse_webhook(
-  provider: :mpesa,
-  body: request.body.read,
-  headers: request.headers.to_h
-)
-
-result.either(
-  ->(event) { process_event(event) },
-  ->(error) { head :bad_request }
-){% endhighlight %}
-
-`WebhookEvent` exposes `provider`, `event_type`, `success?`,
-`provider_reference`, `message`, `raw`, and `verify_signature`.
-
-## Verify M-Pesa
-
-Daraja does not cryptographically sign callbacks. Lipwa checks the remote
-address against Safaricom's published callback IP list:
-
-{% highlight ruby %}return head :forbidden unless event.verify_signature(
-  source_ip: request.remote_ip
-){% endhighlight %}
-
-Configure trusted proxies carefully so clients cannot spoof forwarded IPs.
-Event types are `stk_callback`, `c2b`, `transaction_status`,
-`disbursement`, and `refund`.
-
-## Verify Jenga
-
-Jenga receive-payment IPNs normalize to `receive_payment`:
-
-{% highlight ruby %}return head :forbidden unless event.verify_signature(
-  username: ENV.fetch("JENGA_WEBHOOK_USERNAME"),
-  password: ENV.fetch("JENGA_WEBHOOK_PASSWORD")
-){% endhighlight %}
-
-## Verify LNbits
-
-LNbits does not HMAC-sign webhooks by default. Give each invoice a strong,
-random token in its webhook URL, persist that token alongside the payment hash,
-and compare the URL parameter when the callback arrives:
-
-{% highlight ruby %}return head :forbidden unless event.verify_signature(
-  expected_token: invoice.webhook_token,
-  provided_token: params[:token]
-){% endhighlight %}
-
-This is a shared-secret URL check, not proof that the webhook body came from
-LNbits. Anyone who learns the token can forge a payload. Always call
-`check_invoice(payment_hash: event.provider_reference)` and confirm its status
-before crediting funds; use the webhook only as a low-latency trigger.
-
-## Processing checklist
-
-1. Retain the raw body and parse it through Lipwa.
-2. Verify using provider-specific options.
-3. Correlate by `provider_reference`.
-4. Apply the transition idempotently inside a transaction.
-5. Return quickly and defer slow work to a job.
-
-<div class="callout"><strong>Never credit from an unverified callback.</strong> Parsing normalizes data; verification determines trust.</div>
-
-<nav class="doc-nav"><a href="{{ '/gateways/' | relative_url }}">← Gateways</a><a href="{{ '/reliability/' | relative_url }}">Reliability →</a></nav>

data/sig/lipwa.rbs

@@ -1,4 +0,0 @@
-module Lipwa
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end