pesa-cli 1.0.0__tar.gz → 1.0.2__tar.gz

{pesa_cli-1.0.0 → pesa_cli-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pesa-cli
-Version: 1.0.0
+Version: 1.0.2
 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
@@ -22,6 +22,7 @@ Requires-Dist: rich>=13
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
+Requires-Dist: daraja-mock>=1.0.0; extra == "dev"
 Dynamic: license-file
 
 # pesa-cli
@@ -182,3 +183,7 @@ 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.*
+
+## Getting sandbox credentials
+
+New to Daraja, or on a new machine? Follow [the sandbox setup guide](https://github.com/gabrielmahia/mpesa-python/blob/main/docs/SANDBOX_SETUP.md): it creates a free sandbox app and runs OAuth, an STK Push and a status query, with exact portal labels. Set `DARAJA_CALLBACK_URL` to a public HTTPS address you can watch (for example a webhook.site URL); without it the CLI uses a placeholder and tells you so.

{pesa_cli-1.0.0 → pesa_cli-1.0.2}/README.md

@@ -156,3 +156,7 @@ 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.*
+
+## Getting sandbox credentials
+
+New to Daraja, or on a new machine? Follow [the sandbox setup guide](https://github.com/gabrielmahia/mpesa-python/blob/main/docs/SANDBOX_SETUP.md): it creates a free sandbox app and runs OAuth, an STK Push and a status query, with exact portal labels. Set `DARAJA_CALLBACK_URL` to a public HTTPS address you can watch (for example a webhook.site URL); without it the CLI uses a placeholder and tells you so.

{pesa_cli-1.0.0 → pesa_cli-1.0.2}/pesa_cli/cli.py

@@ -26,9 +26,7 @@ from __future__ import annotations
 
 import json
 import os
-import sys
 import time
-import hashlib
 import base64
 import urllib.request
 import urllib.error
@@ -42,7 +40,6 @@ 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",
@@ -107,6 +104,10 @@ def require_credential(key: str, label: str) -> str:
 # ── Daraja HTTP layer ──────────────────────────────────────────────────────────
 
 def _base_url() -> str:
+    # Documented in the README ("Use with daraja-mock"): point the CLI at a local test server instead of Safaricom.
+    override = os.environ.get("PESA_BASE_URL")
+    if override:
+        return override.rstrip("/")
     env = get_credential("environment") or "sandbox"
     if env == "production":
         return "https://api.safaricom.co.ke"
@@ -186,8 +187,7 @@ def config_show():
         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]")
+    rprint(f"\n[dim]Config file: {_config_path()}[/dim]")
 
 
 @config_app.command("set")
@@ -219,12 +219,9 @@ def auth():
             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"[green]✓ Authenticated[/green]\n"
+        f"Environment: [cyan]{env}[/cyan]\n"
+        f"Token: [dim]{token[:12]}...{token[-4:]}[/dim]\n"
         f"Expires in: [cyan]~60 minutes[/cyan]",
         title="pesa auth", border_style="green",
     ))
@@ -243,7 +240,8 @@ def stk_push(
     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"
+    callback_given  = get_credential("callback_url")
+    callback_url    = callback_given or "https://example.com/mpesa/callback"
     ref = ref[:12]  # Daraja hard limit
 
     timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
@@ -271,27 +269,24 @@ def stk_push(
 
     if response.get("ResponseCode") == "0":
         checkout_id = response.get("CheckoutRequestID", "")
+        # Without a callback URL Safaricom posts the result to a placeholder you cannot see; say so instead of failing silently.
+        notice = "" if callback_given else (
+            "\n\n[yellow]No callback URL set (DARAJA_CALLBACK_URL). Safaricom will post the result to "
+            f"{callback_url}, which you cannot see. Use 'pesa stk query' to check the outcome.[/yellow]"
+        )
         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]",
+            f"[green]✓ STK Push sent[/green]\n"
+            f"Phone:       [cyan]+{phone}[/cyan]\n"
+            f"Amount:      [cyan]KES {amount:,}[/cyan]\n"
+            f"Reference:   [cyan]{ref}[/cyan]\n"
+            f"Checkout ID: [dim]{checkout_id}[/dim]\n\n"
+            f"[dim]The customer will receive a PIN prompt on their phone.[/dim]\n"
+            f"[dim]Run: pesa stk query {checkout_id}[/dim]{notice}",
             title="STK Push", border_style="green",
         ))
     else:
         rprint(Panel(
-            f"[red]✗ Request rejected[/red]
-{json.dumps(response, indent=2)}",
+            f"[red]✗ Request rejected[/red]\n{json.dumps(response, indent=2)}",
             title="STK Push", border_style="red",
         ))
         raise typer.Exit(1)
@@ -329,10 +324,8 @@ def stk_query(
     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"[{color}]{symbol} {result_desc}[/{color}]\n"
+        f"Result Code: [cyan]{result_code}[/cyan]\n"
         f"Checkout ID: [dim]{checkout_id}[/dim]",
         title="STK Query", border_style=color,
     ))
@@ -377,22 +370,16 @@ def b2c(
 
     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"[green]✓ B2C request accepted[/green]\n"
+            f"Phone:           [cyan]+{phone}[/cyan]\n"
+            f"Amount:          [cyan]KES {amount:,}[/cyan]\n"
+            f"Conversation ID: [dim]{response.get('ConversationID', '')}[/dim]\n\n"
             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)}",
+            f"[red]✗ B2C rejected[/red]\n{json.dumps(response, indent=2)}",
             title="B2C", border_style="red",
         ))
         raise typer.Exit(1)
@@ -428,20 +415,15 @@ def balance():
 
     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"[green]✓ Balance request accepted[/green]\n"
+            f"Shortcode:       [cyan]{shortcode}[/cyan]\n"
+            f"Conversation ID: [dim]{response.get('ConversationID', '')}[/dim]\n\n"
             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)}",
+            f"[red]✗ Request rejected[/red]\n{json.dumps(response, indent=2)}",
             title="Account Balance", border_style="red",
         ))
         raise typer.Exit(1)

{pesa_cli-1.0.0 → pesa_cli-1.0.2}/pesa_cli/main.py

@@ -25,10 +25,8 @@ from __future__ import annotations
 
 import base64
 import os
-import sys
 import time
 from datetime import datetime
-from typing import Optional
 
 import requests
 import typer

{pesa_cli-1.0.0 → pesa_cli-1.0.2}/pesa_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pesa-cli
-Version: 1.0.0
+Version: 1.0.2
 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
@@ -22,6 +22,7 @@ Requires-Dist: rich>=13
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
+Requires-Dist: daraja-mock>=1.0.0; extra == "dev"
 Dynamic: license-file
 
 # pesa-cli
@@ -182,3 +183,7 @@ 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.*
+
+## Getting sandbox credentials
+
+New to Daraja, or on a new machine? Follow [the sandbox setup guide](https://github.com/gabrielmahia/mpesa-python/blob/main/docs/SANDBOX_SETUP.md): it creates a free sandbox app and runs OAuth, an STK Push and a status query, with exact portal labels. Set `DARAJA_CALLBACK_URL` to a public HTTPS address you can watch (for example a webhook.site URL); without it the CLI uses a placeholder and tells you so.

{pesa_cli-1.0.0 → pesa_cli-1.0.2}/pesa_cli.egg-info/SOURCES.txt

@@ -11,4 +11,5 @@ pesa_cli.egg-info/dependency_links.txt
 pesa_cli.egg-info/entry_points.txt
 pesa_cli.egg-info/requires.txt
 pesa_cli.egg-info/top_level.txt
-tests/test_cli.py
+tests/test_cli.py
+tests/test_cli_e2e.py

{pesa_cli-1.0.0 → pesa_cli-1.0.2}/pesa_cli.egg-info/requires.txt

@@ -5,3 +5,4 @@ rich>=13
 [dev]
 pytest>=7
 ruff
+daraja-mock>=1.0.0

{pesa_cli-1.0.0 → pesa_cli-1.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pesa-cli"
-version = "1.0.0"
+version = "1.0.2"
 description = "Command-line tool for M-Pesa Daraja v3 — STK Push, B2C, balance, config management."
 readme = "README.md"
 license = {text = "CC-BY-NC-ND-4.0"}
@@ -30,7 +30,7 @@ dependencies = [
 pesa = "pesa_cli.cli:app"
 
 [project.optional-dependencies]
-dev = ["pytest>=7", "ruff"]
+dev = ["pytest>=7", "ruff", "daraja-mock>=1.0.0"]
 
 [project.urls]
 Homepage = "https://github.com/gabrielmahia/pesa-cli"

{pesa_cli-1.0.0 → pesa_cli-1.0.2}/tests/test_cli.py

@@ -1,6 +1,5 @@
 """Tests for pesa-cli — config and normalize logic without live calls."""
 import os
-import pytest
 from typer.testing import CliRunner
 from pesa_cli import app
 from pesa_cli.main import _normalize

pesa_cli-1.0.2/tests/test_cli_e2e.py

@@ -0,0 +1,128 @@
+"""End-to-end tests of the CLI that actually ships (`pesa = "pesa_cli.cli:app"`), driven against the daraja-mock test server.
+
+Why this exists: pesa_cli/cli.py had a SyntaxError from its first commit, so the published `pesa` command could not start, while the old tests passed because
+they imported a sibling module (pesa_cli.main). These tests exercise the real entry point, every command, and the documented PESA_BASE_URL override."""
+import importlib
+import py_compile
+import re
+import socket
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+from daraja_mock import DarajaMock
+
+ROOT = Path(__file__).resolve().parents[1]
+runner = CliRunner()
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+@pytest.fixture(scope="module")
+def mock():
+    m = DarajaMock(consumer_key="testkey", consumer_secret="testsecret")
+    m.base_url = m.run_thread(port=_free_port())
+    return m
+
+
+@pytest.fixture
+def env(mock, tmp_path):
+    mock.reset()
+    return {
+        "PESA_BASE_URL": mock.base_url, "PESA_CONFIG": str(tmp_path / "cfg.json"),
+        "DARAJA_CONSUMER_KEY": "testkey", "DARAJA_CONSUMER_SECRET": "testsecret", "DARAJA_SHORTCODE": "174379", "DARAJA_PASSKEY": "testpasskey",
+        "DARAJA_INITIATOR_NAME": "testapi", "DARAJA_SECURITY_CREDENTIAL": "testcred",
+    }
+
+
+def _app():
+    return importlib.import_module("pesa_cli.cli").app
+
+
+def _posts(mock, path):
+    return [e for e in mock.request_log() if e["path"] == path]
+
+
+# ── guards against shipping something that cannot start ────────────────────────────────────────────────────────────────
+def test_every_module_in_the_package_compiles():
+    for f in sorted((ROOT / "pesa_cli").glob("*.py")):
+        py_compile.compile(str(f), doraise=True)
+
+
+def test_the_declared_entry_point_resolves():
+    target = re.search(r'^\s*pesa\s*=\s*"([\w.]+):(\w+)"', (ROOT / "pyproject.toml").read_text(encoding="utf-8"), re.M)
+    assert target, "no `pesa` entry point in pyproject.toml"
+    assert getattr(importlib.import_module(target.group(1)), target.group(2)) is _app()
+
+
+def test_help_lists_every_command():
+    out = runner.invoke(_app(), ["--help"]).output
+    for cmd in ("auth", "b2c", "balance", "stk", "config"):
+        assert cmd in out
+
+
+# ── every command against the mock ────────────────────────────────────────────────────────────────────────────────────
+def test_auth(mock, env):
+    r = runner.invoke(_app(), ["auth"], env=env)
+    assert r.exit_code == 0 and "Authenticated" in r.output
+    assert _posts(mock, "/oauth/v1/generate")
+
+
+def test_stk_push_sends_the_normalised_payload(mock, env):
+    r = runner.invoke(_app(), ["stk", "push", "0712345678", "100", "--ref", "E2E"], env=env)
+    assert r.exit_code == 0 and "STK Push sent" in r.output
+    body = _posts(mock, "/mpesa/stkpush/v1/processrequest")[-1]["body"]
+    assert str(body["PhoneNumber"]) == "254712345678" and str(body["Amount"]) == "100" and body["AccountReference"] == "E2E"
+
+
+def test_stk_query_reports_success_and_cancellation(mock, env):
+    ok = runner.invoke(_app(), ["stk", "query", "ws_CO_TEST"], env=env)
+    assert ok.exit_code == 0 and "Result Code: 0" in ok.output
+    mock.set_stk_result(1032)
+    cancelled = runner.invoke(_app(), ["stk", "query", "ws_CO_TEST"], env=env)
+    assert "Result Code: 1032" in cancelled.output
+
+
+def test_b2c_and_balance_are_accepted(mock, env):
+    assert "B2C request accepted" in runner.invoke(_app(), ["b2c", "0712345678", "50"], env=env).output
+    assert "Balance request accepted" in runner.invoke(_app(), ["balance"], env=env).output
+    assert _posts(mock, "/mpesa/b2c/v3/paymentrequest") and _posts(mock, "/mpesa/accountbalance/v1/query")
+
+
+def test_missing_credentials_fail_cleanly(env):
+    bare = {k: "" for k in env if k.startswith("DARAJA_")}
+    bare.update(PESA_BASE_URL=env["PESA_BASE_URL"], PESA_CONFIG=env["PESA_CONFIG"])
+    r = runner.invoke(_app(), ["stk", "push", "0712345678", "100"], env=bare)
+    assert r.exit_code == 1 and "Traceback" not in r.output
+
+
+@pytest.mark.parametrize("raw,expected", [("0712345678", "254712345678"), ("+254712345678", "254712345678"), ("712345678", "254712345678"),
+                                          ("0112345678", "254112345678"), ("+254110123456", "254110123456")])
+def test_phone_normalisation(raw, expected):
+    assert importlib.import_module("pesa_cli.cli")._normalise_phone(raw) == expected
+
+
+def test_invalid_phone_is_rejected():
+    import typer
+
+    with pytest.raises(typer.Exit):
+        importlib.import_module("pesa_cli.cli")._normalise_phone("12345")
+
+
+def test_a_missing_callback_url_is_announced_not_silent(mock, env):
+    """Without DARAJA_CALLBACK_URL the CLI substitutes https://example.com/mpesa/callback, so the user never sees the result and had no hint why."""
+    r = runner.invoke(_app(), ["stk", "push", "0712345678", "10", "--ref", "NOCB"], env=env)
+    assert r.exit_code == 0 and "No callback URL" in r.output
+    body = _posts(mock, "/mpesa/stkpush/v1/processrequest")[-1]["body"]
+    assert body["CallBackURL"] == "https://example.com/mpesa/callback"
+
+
+def test_a_configured_callback_url_is_used_and_not_warned_about(mock, env):
+    r = runner.invoke(_app(), ["stk", "push", "0712345678", "10", "--ref", "WITHCB"], env={**env, "DARAJA_CALLBACK_URL": "https://webhook.site/abc"})
+    assert r.exit_code == 0 and "No callback URL" not in r.output
+    assert _posts(mock, "/mpesa/stkpush/v1/processrequest")[-1]["body"]["CallBackURL"] == "https://webhook.site/abc"