bila 0.1.0__tar.gz

bila-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+.env.local
+.env*.local
+
+# Playwright MCP — local screenshots & dev logs
+/.playwright-mcp/
+/bila-*.png

bila-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: bila
+Version: 0.1.0
+Summary: Official Bila Python SDK — Stripe-style payment aggregator for Somalia.
+Project-URL: Homepage, https://bila.so
+Project-URL: Documentation, https://bila.so/docs/sdks
+Project-URL: Source, https://github.com/Saakuut/bila
+Author-email: Tabsamo Group <info@tabsamo.com>
+License: MIT
+Keywords: bila,edahab,payments,somalia,stripe,waafipay
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.31
+Description-Content-Type: text/markdown
+
+# bila — Python SDK
+
+Official Python SDK for [Bila](https://bila.so), the Stripe-style payment aggregator for Somalia.
+
+```bash
+pip install bila
+```
+
+```python
+from bila import Bila
+
+bila = Bila(api_key="sk_live_...")
+
+charge = bila.charges.create(
+    amount=10000,
+    currency="USD",
+    rail="auto",
+    identifier="+252611234567",
+    description="Order #1234",
+)
+
+if charge["status"] == "requires_action":
+    redirect_url = charge["requires_action_payload"]["redirect_to"]
+    # send the payer to redirect_url
+```
+
+Webhook verification:
+
+```python
+from bila import verify_webhook_signature
+
+signature = request.headers["Bila-Signature"]
+body = request.get_data().decode()
+if not verify_webhook_signature(body, signature, secret="whsec_..."):
+    return "invalid signature", 400
+```
+
+Full docs at <https://bila.so/docs/sdks>.

bila-0.1.0/README.md

@@ -0,0 +1,38 @@
+# bila — Python SDK
+
+Official Python SDK for [Bila](https://bila.so), the Stripe-style payment aggregator for Somalia.
+
+```bash
+pip install bila
+```
+
+```python
+from bila import Bila
+
+bila = Bila(api_key="sk_live_...")
+
+charge = bila.charges.create(
+    amount=10000,
+    currency="USD",
+    rail="auto",
+    identifier="+252611234567",
+    description="Order #1234",
+)
+
+if charge["status"] == "requires_action":
+    redirect_url = charge["requires_action_payload"]["redirect_to"]
+    # send the payer to redirect_url
+```
+
+Webhook verification:
+
+```python
+from bila import verify_webhook_signature
+
+signature = request.headers["Bila-Signature"]
+body = request.get_data().decode()
+if not verify_webhook_signature(body, signature, secret="whsec_..."):
+    return "invalid signature", 400
+```
+
+Full docs at <https://bila.so/docs/sdks>.

bila-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bila"
+version = "0.1.0"
+description = "Official Bila Python SDK — Stripe-style payment aggregator for Somalia."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Tabsamo Group", email = "info@tabsamo.com" }]
+requires-python = ">=3.9"
+keywords = ["bila", "payments", "somalia", "waafipay", "edahab", "stripe"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Office/Business :: Financial",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "requests>=2.31",
+]
+
+[project.urls]
+Homepage = "https://bila.so"
+Documentation = "https://bila.so/docs/sdks"
+Source = "https://github.com/Saakuut/bila"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bila"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/bila", "README.md", "pyproject.toml"]

bila-0.1.0/src/bila/__init__.py

@@ -0,0 +1,229 @@
+"""Official Bila Python SDK.
+
+Stripe-style: one client, resources hanging off the client, every method
+returns a dict with the API response shape.
+
+Usage:
+    from bila import Bila
+    bila = Bila(api_key="sk_live_...")
+    charge = bila.charges.create(amount=10000, currency="USD", rail="auto",
+                                  identifier="+252611234567")
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+import uuid
+from typing import Any, Dict, Optional
+
+import requests
+
+__version__ = "0.1.0"
+__all__ = ["Bila", "BilaError", "verify_webhook_signature"]
+
+DEFAULT_BASE_URL = "https://api.bila.so"
+DEFAULT_VERSION = "2026-05-17"
+DEFAULT_TIMEOUT = 60
+
+
+class BilaError(Exception):
+    """Raised when the Bila API returns a non-2xx response."""
+
+    def __init__(self, status: int, body: Dict[str, Any]):
+        super().__init__(body.get("message") or f"Bila {status}")
+        self.status = status
+        self.type = body.get("type")
+        self.code = body.get("code")
+        self.param = body.get("param")
+        self.request_id = body.get("request_id")
+
+
+class Bila:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        bila_version: str = DEFAULT_VERSION,
+        timeout: int = DEFAULT_TIMEOUT,
+    ) -> None:
+        if not api_key:
+            raise ValueError("Bila: api_key is required.")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._bila_version = bila_version
+        self._timeout = timeout
+        self._session = requests.Session()
+
+        # Resources
+        self.charges = _Charges(self)
+        self.refunds = _Refunds(self)
+        self.customers = _Customers(self)
+        self.payment_methods = _PaymentMethods(self)
+        self.webhook_endpoints = _WebhookEndpoints(self)
+        self.balance = _Balance(self)
+        self.events = _Events(self)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        json_body: Optional[Dict[str, Any]] = None,
+        *,
+        idempotency_key: Optional[str] = None,
+        bila_version: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        basic = base64.b64encode(f"{self._api_key}:".encode()).decode()
+        headers = {
+            "Authorization": f"Basic {basic}",
+            "Bila-Version": bila_version or self._bila_version,
+            "Accept": "application/json",
+        }
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+        if method.upper() not in ("GET", "HEAD"):
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+        if request_id:
+            headers["X-Request-Id"] = request_id
+
+        res = self._session.request(
+            method,
+            url,
+            data=json.dumps(json_body) if json_body is not None else None,
+            headers=headers,
+            timeout=self._timeout,
+        )
+        try:
+            data = res.json()
+        except ValueError:
+            data = {}
+        if not res.ok:
+            err = (data or {}).get("error") or {"type": "api_error", "message": f"HTTP {res.status_code}"}
+            raise BilaError(res.status_code, err)
+        return data
+
+
+class _Resource:
+    def __init__(self, client: Bila) -> None:
+        self._client = client
+
+
+def _qs(params: Dict[str, Any]) -> str:
+    items = [(k, str(v)) for k, v in params.items() if v is not None]
+    if not items:
+        return ""
+    from urllib.parse import urlencode
+    return "?" + urlencode(items)
+
+
+class _Charges(_Resource):
+    def create(self, *, amount: int, currency: str, rail: str, **kw: Any) -> Dict[str, Any]:
+        body = {"amount": amount, "currency": currency, "rail": rail, **kw}
+        opts = {k: body.pop(k) for k in ("idempotency_key", "bila_version", "request_id") if k in body}
+        return self._client.request("POST", "/v1/charges", body, **opts)
+
+    def retrieve(self, charge_id: str, **opts: Any) -> Dict[str, Any]:
+        return self._client.request("GET", f"/v1/charges/{charge_id}", **opts)
+
+    def list(self, *, limit: Optional[int] = None, starting_after: Optional[str] = None, **opts: Any) -> Dict[str, Any]:
+        q = _qs({"limit": limit, "starting_after": starting_after})
+        return self._client.request("GET", f"/v1/charges{q}", **opts)
+
+    def cancel(self, charge_id: str, **opts: Any) -> Dict[str, Any]:
+        return self._client.request("POST", f"/v1/charges/{charge_id}/cancel", {}, **opts)
+
+    def confirm(self, charge_id: str, **opts: Any) -> Dict[str, Any]:
+        return self._client.request("POST", f"/v1/charges/{charge_id}/confirm", {}, **opts)
+
+
+class _Refunds(_Resource):
+    def create(self, *, charge: str, amount: Optional[int] = None, reason: Optional[str] = None, **opts: Any) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"charge": charge}
+        if amount is not None:
+            body["amount"] = amount
+        if reason is not None:
+            body["reason"] = reason
+        return self._client.request("POST", "/v1/refunds", body, **opts)
+
+    def retrieve(self, refund_id: str, **opts: Any) -> Dict[str, Any]:
+        return self._client.request("GET", f"/v1/refunds/{refund_id}", **opts)
+
+    def list(self, *, limit: Optional[int] = None, starting_after: Optional[str] = None, charge: Optional[str] = None, **opts: Any) -> Dict[str, Any]:
+        q = _qs({"limit": limit, "starting_after": starting_after, "charge": charge})
+        return self._client.request("GET", f"/v1/refunds{q}", **opts)
+
+
+class _Customers(_Resource):
+    def create(self, **params: Any) -> Dict[str, Any]:
+        opts = {k: params.pop(k) for k in ("idempotency_key", "bila_version", "request_id") if k in params}
+        return self._client.request("POST", "/v1/customers", params, **opts)
+
+    def retrieve(self, customer_id: str, **opts: Any) -> Dict[str, Any]:
+        return self._client.request("GET", f"/v1/customers/{customer_id}", **opts)
+
+
+class _PaymentMethods(_Resource):
+    def create(self, *, rail: str, kind: str, **params: Any) -> Dict[str, Any]:
+        body = {"rail": rail, "kind": kind, **params}
+        opts = {k: body.pop(k) for k in ("idempotency_key", "bila_version", "request_id") if k in body}
+        return self._client.request("POST", "/v1/payment_methods", body, **opts)
+
+    def retrieve(self, pm_id: str, **opts: Any) -> Dict[str, Any]:
+        return self._client.request("GET", f"/v1/payment_methods/{pm_id}", **opts)
+
+
+class _WebhookEndpoints(_Resource):
+    def create(self, *, url: str, **params: Any) -> Dict[str, Any]:
+        body = {"url": url, **params}
+        opts = {k: body.pop(k) for k in ("idempotency_key", "bila_version", "request_id") if k in body}
+        return self._client.request("POST", "/v1/webhook_endpoints", body, **opts)
+
+    def retrieve(self, endpoint_id: str, **opts: Any) -> Dict[str, Any]:
+        return self._client.request("GET", f"/v1/webhook_endpoints/{endpoint_id}", **opts)
+
+    def list(self, **opts: Any) -> Dict[str, Any]:
+        return self._client.request("GET", "/v1/webhook_endpoints", **opts)
+
+
+class _Balance(_Resource):
+    def retrieve(self, **opts: Any) -> Dict[str, Any]:
+        return self._client.request("GET", "/v1/balance", **opts)
+
+
+class _Events(_Resource):
+    def list(self, *, limit: Optional[int] = None, starting_after: Optional[str] = None, type: Optional[str] = None, **opts: Any) -> Dict[str, Any]:
+        q = _qs({"limit": limit, "starting_after": starting_after, "type": type})
+        return self._client.request("GET", f"/v1/events{q}", **opts)
+
+
+def verify_webhook_signature(
+    body: str,
+    header: str,
+    secret: str,
+    tolerance_seconds: int = 300,
+) -> bool:
+    """Verify a Bila-Signature header against the raw request body.
+
+    Header format: 't=<unix-timestamp>,v1=<hex-hmac-sha256>'
+    """
+    parts: Dict[str, str] = {}
+    for piece in header.split(","):
+        if "=" in piece:
+            k, v = piece.split("=", 1)
+            parts[k.strip()] = v.strip()
+    try:
+        t = int(parts.get("t", ""))
+    except ValueError:
+        return False
+    sig = parts.get("v1", "")
+    if not sig:
+        return False
+    if abs(int(time.time()) - t) > tolerance_seconds:
+        return False
+    expected = hmac.new(secret.encode(), f"{t}.{body}".encode(), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, sig)