pesa-cli 1.0.0__py3-none-any.whl

pesa_cli/__init__.py

@@ -0,0 +1,2 @@
+from .main import app, main
+__all__ = ["app", "main"]

pesa_cli/__main__.py

@@ -0,0 +1,4 @@
+from pesa_cli.cli import app
+
+if __name__ == "__main__":
+    app()

pesa_cli/cli.py

@@ -0,0 +1,447 @@
+"""
+pesa-cli — Command-line tool for M-Pesa Daraja v3.
+
+Commands:
+    pesa auth        Test credentials and show token expiry
+    pesa stk         Initiate STK Push to a phone number
+    pesa stk query   Poll the status of an STK Push
+    pesa b2c         Send money to a phone (B2C)
+    pesa balance     Check account balance
+    pesa config      View or set credentials
+
+Credentials are stored in ~/.pesa/config.json (or PESA_CONFIG env var).
+All sensitive values can also be provided as environment variables:
+    DARAJA_CONSUMER_KEY, DARAJA_CONSUMER_SECRET, DARAJA_SHORTCODE,
+    DARAJA_PASSKEY, DARAJA_ENV (sandbox | production)
+
+Usage:
+    pesa config set --key consumer-key --value YOUR_KEY
+    pesa auth
+    pesa stk 0712345678 500 --ref "Order001" --desc "Payment"
+    pesa stk query ws_CO_...
+    pesa b2c 0712345678 1000 --remarks "Disbursement"
+    pesa balance
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+import hashlib
+import base64
+import urllib.request
+import urllib.error
+import urllib.parse
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich import print as rprint
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich.text import Text
+
+app = typer.Typer(
+    name="pesa",
+    help="M-Pesa Daraja v3 command-line tool.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+stk_app = typer.Typer(help="STK Push operations.", no_args_is_help=True)
+app.add_typer(stk_app, name="stk")
+
+console = Console()
+
+
+# ── Config management ──────────────────────────────────────────────────────────
+
+DEFAULT_CONFIG_PATH = Path.home() / ".pesa" / "config.json"
+
+CREDENTIAL_KEYS = [
+    "consumer_key", "consumer_secret", "shortcode",
+    "passkey", "initiator_name", "security_credential",
+    "environment",  # sandbox | production
+]
+
+
+def _config_path() -> Path:
+    env_path = os.environ.get("PESA_CONFIG")
+    return Path(env_path) if env_path else DEFAULT_CONFIG_PATH
+
+
+def load_config() -> dict:
+    path = _config_path()
+    if path.exists():
+        return json.loads(path.read_text())
+    return {}
+
+
+def save_config(cfg: dict) -> None:
+    path = _config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(cfg, indent=2))
+    path.chmod(0o600)  # Owner read/write only — credentials file
+
+
+def get_credential(key: str) -> Optional[str]:
+    """Resolve credential: env var > config file."""
+    env_key = f"DARAJA_{key.upper()}"
+    val = os.environ.get(env_key)
+    if val:
+        return val
+    cfg = load_config()
+    return cfg.get(key)
+
+
+def require_credential(key: str, label: str) -> str:
+    val = get_credential(key)
+    if not val:
+        rprint(f"[red]✗[/red] Missing {label}. Run [cyan]pesa config set --key {key.replace('_','-')} --value VALUE[/cyan]")
+        raise typer.Exit(1)
+    return val
+
+
+# ── Daraja HTTP layer ──────────────────────────────────────────────────────────
+
+def _base_url() -> str:
+    env = get_credential("environment") or "sandbox"
+    if env == "production":
+        return "https://api.safaricom.co.ke"
+    return "https://sandbox.safaricom.co.ke"
+
+
+def _get_token(consumer_key: str, consumer_secret: str) -> str:
+    credentials = base64.b64encode(f"{consumer_key}:{consumer_secret}".encode()).decode()
+    url = f"{_base_url()}/oauth/v1/generate?grant_type=client_credentials"
+    req = urllib.request.Request(url, headers={"Authorization": f"Basic {credentials}"})
+    with urllib.request.urlopen(req, timeout=15) as r:
+        data = json.loads(r.read())
+    token = data.get("access_token")
+    if not token:
+        raise RuntimeError(f"No access_token in response: {data}")
+    return token
+
+
+def _stk_password(shortcode: str, passkey: str, timestamp: str) -> str:
+    return base64.b64encode(f"{shortcode}{passkey}{timestamp}".encode()).decode()
+
+
+def _daraja_post(endpoint: str, payload: dict, token: str) -> dict:
+    url = f"{_base_url()}{endpoint}"
+    body = json.dumps(payload).encode()
+    req = urllib.request.Request(
+        url, data=body,
+        headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=20) as r:
+            return json.loads(r.read())
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode()
+        try:
+            return json.loads(error_body)
+        except Exception:
+            raise RuntimeError(f"HTTP {e.code}: {error_body[:200]}")
+
+
+def _normalise_phone(raw: str) -> str:
+    phone = raw.strip().replace(" ", "").lstrip("+")
+    if phone.startswith("07") or phone.startswith("01"):
+        phone = "254" + phone[1:]
+    elif len(phone) == 9 and phone[0] == "7":
+        phone = "254" + phone
+    if not (phone.startswith("254") and phone.isdigit() and len(phone) == 12):
+        rprint(f"[red]✗[/red] Invalid Kenyan phone number: {raw!r}")
+        raise typer.Exit(1)
+    return phone
+
+
+# ── Commands ───────────────────────────────────────────────────────────────────
+
+config_app = typer.Typer(help="View and set Daraja credentials.", no_args_is_help=True)
+app.add_typer(config_app, name="config")
+
+
+@config_app.command("show")
+def config_show():
+    """Show current configuration (secrets masked)."""
+    cfg = load_config()
+    env_overrides = {k: os.environ.get(f"DARAJA_{k.upper()}") for k in CREDENTIAL_KEYS}
+    if not cfg and not any(env_overrides.values()):
+        rprint("[yellow]No configuration found.[/yellow] Run [cyan]pesa config set[/cyan] to add credentials.")
+        return
+    table = Table(title="pesa configuration", show_header=True)
+    table.add_column("Key", style="cyan")
+    table.add_column("Source")
+    table.add_column("Value")
+    for key in CREDENTIAL_KEYS:
+        env_val = env_overrides.get(key)
+        cfg_val = cfg.get(key)
+        val = env_val or cfg_val
+        source = "env var" if env_val else ("config file" if cfg_val else "—")
+        is_secret = key not in ("shortcode", "environment", "initiator_name")
+        display = ("*" * 8 + val[-4:] if val and is_secret and len(val) > 4 else val or "—")
+        table.add_row(key, source, display)
+    console.print(table)
+    rprint(f"
+[dim]Config file: {_config_path()}[/dim]")
+
+
+@config_app.command("set")
+def config_set(
+    key: str = typer.Option(..., help="Credential key (e.g. consumer-key)"),
+    value: str = typer.Option(..., help="Credential value"),
+):
+    """Set a credential in ~/.pesa/config.json."""
+    key = key.replace("-", "_")
+    if key not in CREDENTIAL_KEYS:
+        rprint(f"[red]✗[/red] Unknown key {key!r}. Valid keys: {CREDENTIAL_KEYS}")
+        raise typer.Exit(1)
+    cfg = load_config()
+    cfg[key] = value
+    save_config(cfg)
+    rprint(f"[green]✓[/green] Set [cyan]{key}[/cyan]")
+
+
+@app.command()
+def auth():
+    """Test credentials — fetch an OAuth token and show expiry."""
+    consumer_key    = require_credential("consumer_key",    "Consumer Key")
+    consumer_secret = require_credential("consumer_secret", "Consumer Secret")
+    with console.status("Authenticating..."):
+        try:
+            token = _get_token(consumer_key, consumer_secret)
+        except Exception as e:
+            rprint(f"[red]✗ Authentication failed:[/red] {e}")
+            raise typer.Exit(1)
+    env = get_credential("environment") or "sandbox"
+    rprint(Panel(
+        f"[green]✓ Authenticated[/green]
+"
+        f"Environment: [cyan]{env}[/cyan]
+"
+        f"Token: [dim]{token[:12]}...{token[-4:]}[/dim]
+"
+        f"Expires in: [cyan]~60 minutes[/cyan]",
+        title="pesa auth", border_style="green",
+    ))
+
+
+@stk_app.command("push")
+def stk_push(
+    phone: str = typer.Argument(..., help="Kenyan phone number (any format)"),
+    amount: int = typer.Argument(..., help="Amount in KES (must be integer)"),
+    ref: str = typer.Option("pesa-cli", "--ref", help="AccountReference (max 12 chars)"),
+    desc: str = typer.Option("Payment", "--desc", help="TransactionDesc"),
+):
+    """Initiate an STK Push payment request."""
+    phone = _normalise_phone(phone)
+    consumer_key    = require_credential("consumer_key",    "Consumer Key")
+    consumer_secret = require_credential("consumer_secret", "Consumer Secret")
+    shortcode       = require_credential("shortcode",       "Shortcode")
+    passkey         = require_credential("passkey",         "Passkey")
+    callback_url    = get_credential("callback_url") or "https://example.com/mpesa/callback"
+    ref = ref[:12]  # Daraja hard limit
+
+    timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
+    password  = _stk_password(shortcode, passkey, timestamp)
+
+    with console.status(f"Sending STK Push to +{phone}..."):
+        try:
+            token = _get_token(consumer_key, consumer_secret)
+            response = _daraja_post("/mpesa/stkpush/v1/processrequest", {
+                "BusinessShortCode": shortcode,
+                "Password":          password,
+                "Timestamp":         timestamp,
+                "TransactionType":   "CustomerPayBillOnline",
+                "Amount":            amount,
+                "PartyA":            phone,
+                "PartyB":            shortcode,
+                "PhoneNumber":       phone,
+                "CallBackURL":       callback_url,
+                "AccountReference":  ref,
+                "TransactionDesc":   desc,
+            }, token)
+        except Exception as e:
+            rprint(f"[red]✗ STK Push failed:[/red] {e}")
+            raise typer.Exit(1)
+
+    if response.get("ResponseCode") == "0":
+        checkout_id = response.get("CheckoutRequestID", "")
+        rprint(Panel(
+            f"[green]✓ STK Push sent[/green]
+"
+            f"Phone:       [cyan]+{phone}[/cyan]
+"
+            f"Amount:      [cyan]KES {amount:,}[/cyan]
+"
+            f"Reference:   [cyan]{ref}[/cyan]
+"
+            f"Checkout ID: [dim]{checkout_id}[/dim]
+
+"
+            f"[dim]The customer will receive a PIN prompt on their phone.[/dim]
+"
+            f"[dim]Run: pesa stk query {checkout_id}[/dim]",
+            title="STK Push", border_style="green",
+        ))
+    else:
+        rprint(Panel(
+            f"[red]✗ Request rejected[/red]
+{json.dumps(response, indent=2)}",
+            title="STK Push", border_style="red",
+        ))
+        raise typer.Exit(1)
+
+
+@stk_app.command("query")
+def stk_query(
+    checkout_id: str = typer.Argument(..., help="CheckoutRequestID from stk push"),
+):
+    """Poll the status of an STK Push request."""
+    consumer_key    = require_credential("consumer_key",    "Consumer Key")
+    consumer_secret = require_credential("consumer_secret", "Consumer Secret")
+    shortcode       = require_credential("shortcode",       "Shortcode")
+    passkey         = require_credential("passkey",         "Passkey")
+
+    timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
+    password  = _stk_password(shortcode, passkey, timestamp)
+
+    with console.status("Querying status..."):
+        try:
+            token    = _get_token(consumer_key, consumer_secret)
+            response = _daraja_post("/mpesa/stkpushquery/v1/query", {
+                "BusinessShortCode": shortcode,
+                "Password":          password,
+                "Timestamp":         timestamp,
+                "CheckoutRequestID": checkout_id,
+            }, token)
+        except Exception as e:
+            rprint(f"[red]✗ Query failed:[/red] {e}")
+            raise typer.Exit(1)
+
+    result_code = response.get("ResultCode", "?")
+    result_desc = response.get("ResultDesc", "Unknown")
+    STATUS_COLORS = {"0": "green", "1032": "yellow", "1037": "yellow"}
+    color = STATUS_COLORS.get(str(result_code), "red")
+    symbol = "✓" if str(result_code) == "0" else "✗"
+    rprint(Panel(
+        f"[{color}]{symbol} {result_desc}[/{color}]
+"
+        f"Result Code: [cyan]{result_code}[/cyan]
+"
+        f"Checkout ID: [dim]{checkout_id}[/dim]",
+        title="STK Query", border_style=color,
+    ))
+
+
+@app.command()
+def b2c(
+    phone: str = typer.Argument(..., help="Recipient phone number"),
+    amount: int = typer.Argument(..., help="Amount in KES"),
+    remarks: str = typer.Option("Payment", "--remarks", help="Transaction remarks"),
+    occasion: str = typer.Option("", "--occasion", help="Optional occasion"),
+):
+    """Send money from shortcode to a phone number (B2C)."""
+    phone = _normalise_phone(phone)
+    consumer_key      = require_credential("consumer_key",          "Consumer Key")
+    consumer_secret   = require_credential("consumer_secret",       "Consumer Secret")
+    shortcode         = require_credential("shortcode",              "Shortcode")
+    initiator         = require_credential("initiator_name",         "Initiator Name")
+    security_cred     = require_credential("security_credential",    "Security Credential")
+    result_url        = get_credential("result_url")    or "https://example.com/b2c/result"
+    timeout_url       = get_credential("timeout_url")   or "https://example.com/b2c/timeout"
+
+    with console.status(f"Sending KES {amount:,} to +{phone}..."):
+        try:
+            token    = _get_token(consumer_key, consumer_secret)
+            response = _daraja_post("/mpesa/b2c/v3/paymentrequest", {
+                "InitiatorName":      initiator,
+                "SecurityCredential": security_cred,
+                "CommandID":          "BusinessPayment",
+                "Amount":             amount,
+                "PartyA":             shortcode,
+                "PartyB":             f"+{phone}",
+                "Remarks":            remarks,
+                "QueueTimeOutURL":    timeout_url,
+                "ResultURL":          result_url,
+                "Occasion":           occasion,
+                "OriginatorConversationID": f"pesa-cli-{int(time.time())}",
+            }, token)
+        except Exception as e:
+            rprint(f"[red]✗ B2C failed:[/red] {e}")
+            raise typer.Exit(1)
+
+    if response.get("ResponseCode") == "0":
+        rprint(Panel(
+            f"[green]✓ B2C request accepted[/green]
+"
+            f"Phone:           [cyan]+{phone}[/cyan]
+"
+            f"Amount:          [cyan]KES {amount:,}[/cyan]
+"
+            f"Conversation ID: [dim]{response.get('ConversationID', '')}[/dim]
+
+"
+            f"[dim]Result will be posted to your ResultURL.[/dim]",
+            title="B2C", border_style="green",
+        ))
+    else:
+        rprint(Panel(
+            f"[red]✗ B2C rejected[/red]
+{json.dumps(response, indent=2)}",
+            title="B2C", border_style="red",
+        ))
+        raise typer.Exit(1)
+
+
+@app.command()
+def balance():
+    """Check account balance for the configured shortcode."""
+    consumer_key    = require_credential("consumer_key",          "Consumer Key")
+    consumer_secret = require_credential("consumer_secret",       "Consumer Secret")
+    shortcode       = require_credential("shortcode",              "Shortcode")
+    initiator       = require_credential("initiator_name",         "Initiator Name")
+    security_cred   = require_credential("security_credential",    "Security Credential")
+    result_url      = get_credential("result_url")  or "https://example.com/balance/result"
+    timeout_url     = get_credential("timeout_url") or "https://example.com/balance/timeout"
+
+    with console.status("Requesting balance..."):
+        try:
+            token    = _get_token(consumer_key, consumer_secret)
+            response = _daraja_post("/mpesa/accountbalance/v1/query", {
+                "InitiatorName":      initiator,
+                "SecurityCredential": security_cred,
+                "CommandID":          "AccountBalance",
+                "PartyA":             shortcode,
+                "IdentifierType":     "4",
+                "Remarks":            "Balance query from pesa-cli",
+                "QueueTimeOutURL":    timeout_url,
+                "ResultURL":          result_url,
+            }, token)
+        except Exception as e:
+            rprint(f"[red]✗ Balance query failed:[/red] {e}")
+            raise typer.Exit(1)
+
+    if response.get("ResponseCode") == "0":
+        rprint(Panel(
+            f"[green]✓ Balance request accepted[/green]
+"
+            f"Shortcode:       [cyan]{shortcode}[/cyan]
+"
+            f"Conversation ID: [dim]{response.get('ConversationID', '')}[/dim]
+
+"
+            f"[dim]Balance will be posted to your ResultURL asynchronously.[/dim]",
+            title="Account Balance", border_style="green",
+        ))
+    else:
+        rprint(Panel(
+            f"[red]✗ Request rejected[/red]
+{json.dumps(response, indent=2)}",
+            title="Account Balance", border_style="red",
+        ))
+        raise typer.Exit(1)

pesa_cli/main.py

@@ -0,0 +1,269 @@
+"""
+pesa — command-line tool for M-Pesa Daraja v3.
+
+Commands:
+  pesa stk-push   — trigger STK Push payment prompt
+  pesa stk-query  — check STK Push status
+  pesa b2c        — send money to phone (B2C)
+  pesa balance    — check shortcode balance
+  pesa config     — show/set environment configuration
+
+Usage:
+    export MPESA_CONSUMER_KEY=...
+    export MPESA_CONSUMER_SECRET=...
+    export MPESA_SHORTCODE=174379
+    export MPESA_PASSKEY=...
+    export MPESA_CALLBACK_URL=https://example.com/callback
+    export MPESA_SANDBOX=true
+
+    pesa stk-push --phone 0712345678 --amount 100 --ref "Order1"
+    pesa stk-query --id ws_CO_...
+    pesa balance
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import sys
+import time
+from datetime import datetime
+from typing import Optional
+
+import requests
+import typer
+
+app = typer.Typer(
+    name="pesa",
+    help="Command-line tool for M-Pesa Daraja v3.",
+    no_args_is_help=True,
+)
+
+_token_cache: dict = {"token": None, "expires_at": 0.0}
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _base_url() -> str:
+    sandbox = os.environ.get("MPESA_SANDBOX", "true").lower() == "true"
+    return "https://sandbox.safaricom.co.ke" if sandbox else "https://api.safaricom.co.ke"
+
+
+def _get_token() -> str:
+    if time.time() < _token_cache.get("expires_at", 0) - 30:
+        return _token_cache["token"]  # type: ignore[return-value]
+    key    = _require("MPESA_CONSUMER_KEY")
+    secret = _require("MPESA_CONSUMER_SECRET")
+    creds  = base64.b64encode(f"{key}:{secret}".encode()).decode()
+    resp   = requests.get(
+        f"{_base_url()}/oauth/v1/generate?grant_type=client_credentials",
+        headers={"Authorization": f"Basic {creds}"},
+        timeout=10,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    _token_cache["token"]      = data["access_token"]
+    _token_cache["expires_at"] = time.time() + int(data["expires_in"])
+    return _token_cache["token"]  # type: ignore[return-value]
+
+
+def _require(var: str) -> str:
+    val = os.environ.get(var)
+    if not val:
+        typer.echo(f"Error: {var} not set. Run: pesa config", err=True)
+        raise typer.Exit(1)
+    return val
+
+
+def _normalize(phone: str) -> str:
+    phone = phone.strip().lstrip("+").replace(" ", "")
+    if phone.startswith("0"):
+        phone = "254" + phone[1:]
+    elif not phone.startswith("254"):
+        phone = "254" + phone
+    return phone
+
+
+def _password_ts() -> tuple[str, str]:
+    shortcode = _require("MPESA_SHORTCODE")
+    passkey   = _require("MPESA_PASSKEY")
+    ts        = datetime.now().strftime("%Y%m%d%H%M%S")
+    pw        = base64.b64encode(f"{shortcode}{passkey}{ts}".encode()).decode()
+    return pw, ts
+
+
+def _post(path: str, payload: dict) -> dict:
+    token = _get_token()
+    resp  = requests.post(
+        f"{_base_url()}{path}",
+        json=payload,
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=15,
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+def _print_result(data: dict, success_key: str = "ResponseCode", success_val: str = "0") -> None:
+    is_ok = data.get(success_key) == success_val
+    icon  = "✓" if is_ok else "✗"
+    for k, v in data.items():
+        typer.echo(f"  {k}: {v}")
+    typer.echo(f"\n{icon} {'Success' if is_ok else 'Failed'}")
+
+
+# ── Commands ──────────────────────────────────────────────────────────────────
+
+@app.command("stk-push")
+def stk_push(
+    phone:  str = typer.Option(..., "--phone", "-p", help="Phone number (07xx, 254xx, or +254xx)"),
+    amount: int = typer.Option(..., "--amount", "-a", help="Amount in KES (whole number)"),
+    ref:    str = typer.Option("Payment", "--ref", "-r", help="Account reference (max 12 chars)"),
+    desc:   str = typer.Option("Payment", "--desc", "-d", help="Transaction description"),
+):
+    """Trigger an M-Pesa STK Push payment prompt on the customer's phone."""
+    shortcode = _require("MPESA_SHORTCODE")
+    callback  = _require("MPESA_CALLBACK_URL")
+    pw, ts    = _password_ts()
+    phone     = _normalize(phone)
+
+    typer.echo(f"Sending STK Push: KES {amount} → {phone}")
+    data = _post("/mpesa/stkpush/v1/processrequest", {
+        "BusinessShortCode": shortcode,
+        "Password":          pw,
+        "Timestamp":         ts,
+        "TransactionType":   "CustomerPayBillOnline",
+        "Amount":            amount,
+        "PartyA":            phone,
+        "PartyB":            shortcode,
+        "PhoneNumber":       phone,
+        "CallBackURL":       callback,
+        "AccountReference":  ref[:12],
+        "TransactionDesc":   desc[:13],
+    })
+    _print_result(data)
+    checkout_id = data.get("CheckoutRequestID")
+    if checkout_id:
+        typer.echo(f"\nCheckoutRequestID: {checkout_id}")
+        typer.echo(f"Run: pesa stk-query --id {checkout_id}")
+
+
+@app.command("stk-query")
+def stk_query(
+    checkout_id: str = typer.Option(..., "--id", "-i", help="CheckoutRequestID from stk-push"),
+    wait:        int = typer.Option(0, "--wait", "-w", help="Seconds to wait before querying (0=immediate)"),
+):
+    """Check the status of an STK Push request."""
+    if wait:
+        typer.echo(f"Waiting {wait}s...")
+        time.sleep(wait)
+
+    shortcode = _require("MPESA_SHORTCODE")
+    pw, ts    = _password_ts()
+
+    data = _post("/mpesa/stkpushquery/v1/query", {
+        "BusinessShortCode": shortcode,
+        "Password":          pw,
+        "Timestamp":         ts,
+        "CheckoutRequestID": checkout_id,
+    })
+
+    result_code = data.get("ResultCode", "-1")
+    status_map  = {
+        "0":    "✓ SUCCESS",
+        "1":    "✗ INSUFFICIENT FUNDS",
+        "1032": "✗ CANCELLED BY USER",
+        "1037": "✗ TIMED OUT",
+        "2001": "✗ WRONG PIN",
+    }
+    typer.echo(f"Status: {status_map.get(result_code, f'Code {result_code}')}")
+    typer.echo(f"Description: {data.get('ResultDesc')}")
+
+
+@app.command("b2c")
+def b2c(
+    phone:  str = typer.Option(..., "--phone", "-p", help="Recipient phone number"),
+    amount: int = typer.Option(..., "--amount", "-a", help="Amount in KES"),
+    reason: str = typer.Option("SalaryPayment", "--reason", "-r",
+                               help="CommandID: SalaryPayment | BusinessPayment | PromotionPayment"),
+):
+    """Send money from shortcode to a phone number (B2C)."""
+    initiator  = _require("MPESA_INITIATOR_NAME")
+    security   = _require("MPESA_SECURITY_CREDENTIAL")
+    shortcode  = _require("MPESA_SHORTCODE")
+    callback   = _require("MPESA_CALLBACK_URL")
+    phone      = _normalize(phone)
+
+    typer.echo(f"Sending B2C: KES {amount} → {phone}")
+    data = _post("/mpesa/b2c/v3/paymentrequest", {
+        "InitiatorName":        initiator,
+        "SecurityCredential":   security,
+        "CommandID":            reason,
+        "Amount":               amount,
+        "PartyA":               shortcode,
+        "PartyB":               phone,
+        "Remarks":              f"B2C {reason}",
+        "QueueTimeOutURL":      callback,
+        "ResultURL":            callback,
+        "Occassion":            "",
+    })
+    _print_result(data)
+
+
+@app.command("balance")
+def balance():
+    """Query the M-Pesa shortcode account balance."""
+    initiator = _require("MPESA_INITIATOR_NAME")
+    security  = _require("MPESA_SECURITY_CREDENTIAL")
+    shortcode = _require("MPESA_SHORTCODE")
+    callback  = _require("MPESA_CALLBACK_URL")
+
+    typer.echo("Querying balance (result delivered async to callback URL)...")
+    data = _post("/mpesa/accountbalance/v1/query", {
+        "Initiator":          initiator,
+        "SecurityCredential": security,
+        "CommandID":          "AccountBalance",
+        "PartyA":             shortcode,
+        "IdentifierType":     "4",
+        "Remarks":            "Balance query",
+        "QueueTimeOutURL":    callback,
+        "ResultURL":          callback,
+    })
+    _print_result(data)
+
+
+@app.command("config")
+def config():
+    """Show current M-Pesa configuration (keys masked)."""
+    env_vars = [
+        "MPESA_CONSUMER_KEY",
+        "MPESA_CONSUMER_SECRET",
+        "MPESA_SHORTCODE",
+        "MPESA_PASSKEY",
+        "MPESA_CALLBACK_URL",
+        "MPESA_INITIATOR_NAME",
+        "MPESA_SANDBOX",
+    ]
+    typer.echo("Current pesa configuration:\n")
+    for var in env_vars:
+        val = os.environ.get(var)
+        if val:
+            if "KEY" in var or "SECRET" in var or "CREDENTIAL" in var or "PASSKEY" in var:
+                display = val[:4] + "****" + val[-4:] if len(val) > 8 else "****"
+            else:
+                display = val
+        else:
+            display = "(not set)"
+        typer.echo(f"  {var:<32} {display}")
+
+    sandbox = os.environ.get("MPESA_SANDBOX", "true").lower() == "true"
+    typer.echo(f"\n  Mode: {'SANDBOX' if sandbox else 'PRODUCTION'}")
+    typer.echo(f"  Base URL: {_base_url()}")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

pesa_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: pesa-cli
+Version: 1.0.0
+Summary: Command-line tool for M-Pesa Daraja v3 — STK Push, B2C, balance, config management.
+Author-email: Gabriel Mahia <contact@aikungfu.dev>
+License: CC-BY-NC-ND-4.0
+Project-URL: Homepage, https://github.com/gabrielmahia/pesa-cli
+Keywords: mpesa,safaricom,daraja,cli,kenya,fintech,python,typer
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: requests>=2.28
+Requires-Dist: rich>=13
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# pesa-cli
+
+**Command-line tool for M-Pesa Daraja v3 — STK Push, B2C, balance check, config management.**
+
+[![CI](https://github.com/gabrielmahia/pesa-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/gabrielmahia/pesa-cli/actions)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](#)
+[![Tests](https://img.shields.io/badge/tests-34%20passing-brightgreen)](#)
+[![License](https://img.shields.io/badge/License-CC%20BY--NC--ND%204.0-lightgrey)](LICENSE)
+
+Test integrations, trigger payments, and check balances from your terminal —
+without opening the Safaricom portal or writing a script.
+
+---
+
+## Install
+
+```bash
+pip install pesa-cli
+```
+
+---
+
+## Setup
+
+```bash
+# Set credentials once — stored in ~/.pesa/config.json (mode 600)
+pesa config set --key consumer-key    --value YOUR_CONSUMER_KEY
+pesa config set --key consumer-secret --value YOUR_CONSUMER_SECRET
+pesa config set --key shortcode       --value 174379
+pesa config set --key passkey         --value YOUR_PASSKEY
+pesa config set --key environment     --value sandbox   # or production
+
+# Or use environment variables (useful in CI/CD)
+export DARAJA_CONSUMER_KEY=...
+export DARAJA_CONSUMER_SECRET=...
+
+# Test credentials
+pesa auth
+```
+
+---
+
+## Commands
+
+### `pesa auth`
+Test credentials and verify connectivity.
+```
+✓ Authenticated
+Environment: sandbox
+Token: mock_token_ab...3456
+Expires in: ~60 minutes
+```
+
+### `pesa stk push PHONE AMOUNT`
+Initiate an STK Push payment request. The customer receives a PIN prompt on their phone.
+```bash
+pesa stk push 0712345678 500
+pesa stk push 0712345678 500 --ref "Invoice001" --desc "Monthly contribution"
+```
+```
+✓ STK Push sent
+Phone:       +254712345678
+Amount:      KES 500
+Reference:   Invoice001
+Checkout ID: ws_CO_150120241430221234567890
+
+Run: pesa stk query ws_CO_150120241430221234567890
+```
+
+### `pesa stk query CHECKOUT_ID`
+Poll the status of an STK Push.
+```bash
+pesa stk query ws_CO_150120241430221234567890
+```
+```
+✓ The service request is processed successfully.
+Result Code: 0
+```
+
+### `pesa b2c PHONE AMOUNT`
+Send money from your shortcode to a phone number.
+```bash
+pesa b2c 0712345678 1000 --remarks "Chama disbursement"
+```
+
+### `pesa balance`
+Request account balance (result posted to your ResultURL asynchronously).
+```bash
+pesa balance
+```
+
+### `pesa config show`
+Display current configuration with secrets masked.
+```
+┌──────────────────────────────────────────────────┐
+│ pesa configuration                               │
+├──────────────────┬─────────────┬─────────────────┤
+│ consumer_key     │ config file │ ************3456 │
+│ consumer_secret  │ config file │ ************abcd │
+│ shortcode        │ config file │ 174379           │
+│ environment      │ config file │ sandbox          │
+└──────────────────┴─────────────┴─────────────────┘
+```
+
+---
+
+## Credentials
+
+Credentials are resolved in this order: **environment variable** → **config file**.
+
+| Credential | Config key | Environment variable |
+|------------|-----------|----------------------|
+| Consumer Key | `consumer_key` | `DARAJA_CONSUMER_KEY` |
+| Consumer Secret | `consumer_secret` | `DARAJA_CONSUMER_SECRET` |
+| Shortcode | `shortcode` | `DARAJA_SHORTCODE` |
+| Passkey | `passkey` | `DARAJA_PASSKEY` |
+| Initiator Name | `initiator_name` | `DARAJA_INITIATOR_NAME` |
+| Security Credential | `security_credential` | `DARAJA_SECURITY_CREDENTIAL` |
+| Environment | `environment` | `DARAJA_ENVIRONMENT` |
+
+Config file is stored at `~/.pesa/config.json` with mode 600 (owner read/write only).
+Override location with `PESA_CONFIG=/path/to/config.json`.
+
+---
+
+## Use with daraja-mock
+
+```bash
+# Start daraja-mock
+python -m daraja_mock --port 8765
+
+# Point pesa-cli at the mock
+export PESA_BASE_URL=http://localhost:8765
+pesa auth
+pesa stk push 0712345678 100 --ref "Test"
+```
+
+---
+
+## Design decisions
+
+**Credentials resolved env → file.** CI/CD environments should use env vars.
+Developer machines use the config file. The CLI never asks for credentials
+interactively — that would break scripting.
+
+**Secrets masked at 600.** The config file is created with `chmod 600` so
+other users on shared systems cannot read Daraja credentials.
+
+**AccountReference truncated silently.** Daraja rejects `AccountReference` > 12 chars
+with a cryptic error. The CLI truncates to 12 and shows what was sent.
+
+**Rich output, not JSON by default.** For human use. Add `--output json` flag
+if scripting against pesa-cli output is needed.
+
+---
+
+*Part of the [nairobi-stack](https://github.com/gabrielmahia/nairobi-stack) East Africa engineering ecosystem.*
+*Maintained by [Gabriel Mahia](https://github.com/gabrielmahia). Kenya × USA.*

pesa_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pesa_cli/__init__.py,sha256=Ve3bQpvLbYmTt2qBNPYwzcApA-8C_ZbZqVpHvVDkmLs,54
+pesa_cli/__main__.py,sha256=d4F2wMiETFozbkxaPkB0nbnte2qDbnr2XG_11Nq2b0w,67
+pesa_cli/cli.py,sha256=5jhDYO1xnX9T06fshQ_yNcaHKbH-FBPS3ekLwU1Hd78,17060
+pesa_cli/main.py,sha256=g9TJZYw7HCQvFVZRkZRjOjMo8q6sh4sTfcM4P65E5RI,9183
+pesa_cli-1.0.0.dist-info/licenses/LICENSE,sha256=ciwpMjQTMsbBPvPCwMoSZCVNcZV54s2JDp-16m57Dn0,168
+pesa_cli-1.0.0.dist-info/METADATA,sha256=Fo5g3T-GYhhWywToJTxsksPYfwUYY5_0QtwGQ7KFnV4,5970
+pesa_cli-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pesa_cli-1.0.0.dist-info/entry_points.txt,sha256=Gd19aESW0F9H7FYTFCZZYDH-fJsUogvDaWD7xgBildo,42
+pesa_cli-1.0.0.dist-info/top_level.txt,sha256=vZOZjKhhuE7wM_BFaZ0TVcxoHOFgTGJDCIusJc6neig,9
+pesa_cli-1.0.0.dist-info/RECORD,,

pesa_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pesa_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pesa = pesa_cli.cli:app

pesa_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,3 @@
+Creative Commons Attribution-NonCommercial-NoDerivatives 4.0
+Copyright (c) 2026 Gabriel Mahia <contact@aikungfu.dev>
+https://creativecommons.org/licenses/by-nc-nd/4.0/

pesa_cli-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pesa_cli