lipay-sdk 1.0.0__tar.gz

lipay_sdk-1.0.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Lipay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lipay_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: lipay-sdk
+Version: 1.0.0
+Summary: Official Python SDK for Lipay Messaging Platform
+Author-email: Evans Musamia <evans@lipay.store>
+Maintainer-email: Lipay Platform <dev@lipay.store>
+License: MIT
+Project-URL: Homepage, https://message.lipay.store
+Project-URL: Documentation, https://github.com/Evans-musamia/LipayMessagingPlatform#readme
+Project-URL: Repository, https://github.com/Evans-musamia/LipayMessagingPlatform
+Project-URL: Issues, https://github.com/Evans-musamia/LipayMessagingPlatform/issues
+Project-URL: Changelog, https://github.com/Evans-musamia/LipayMessagingPlatform/releases
+Keywords: lipay,whatsapp,messaging,africa,customer-service-window,api-sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Web Environment
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Telephony
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.9.0
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115.0; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# Lipay Python SDK
+
+Official Python client for [Lipay](https://message.lipay.store) — the developer platform for WhatsApp messaging, routing, and Customer Service Window (CSW) management across Africa.
+
+Use this library in your application (BrandFlow, Teacher, custom backends) to check whether the Meta **24-hour customer service window** is open before sending free-text WhatsApp messages.
+
+---
+
+## Installation
+
+**From PyPI (recommended):**
+
+```bash
+pip install lipay-sdk
+pip install "lipay-sdk[fastapi]"
+```
+
+Pin in `requirements.txt`:
+
+```text
+lipay-sdk==1.0.0
+```
+
+**From Git (tagged release):**
+
+```bash
+pip install git+https://github.com/Evans-musamia/LipayMessagingPlatform.git@v1.0.0
+```
+
+**TestPyPI (maintainers — sandbox):**
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ lipay-sdk
+```
+
+**Editable (local development):**
+
+```bash
+git clone https://github.com/Evans-musamia/LipayMessagingPlatform.git
+cd LipayMessagingPlatform
+pip install -e ".[dev]"
+```
+
+Publishing guide: [PYPI.md](PYPI.md)
+
+---
+
+## Quick start
+
+```python
+import asyncio
+
+from lipay_sdk import LipayCswSessionGuard
+
+
+async def main() -> None:
+    guard = LipayCswSessionGuard("https://message.lipay.store")
+
+    active = await guard.is_window_active(
+        customer_phone="+254700000000",
+        business_phone="+254711111111",
+    )
+
+    if active:
+        print("CSW open — safe to send free-text via Lipay /v1/whatsapp/send")
+    else:
+        print("CSW closed — send an approved template first")
+
+    await guard.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Configuration object (Pydantic)
+
+For explicit control over timeouts, cache TTL, and API paths:
+
+```python
+from lipay_sdk.csw_session_guard import LipayCswSessionGuard, LipaySdkConfig
+
+config = LipaySdkConfig(
+    gateway_url="https://message.lipay.store",
+    local_active_ttl_seconds=180,
+    http_timeout_seconds=10.0,
+)
+guard = LipayCswSessionGuard(config)
+```
+
+### Full status payload
+
+```python
+status = await guard.get_session_status(
+    customer_phone="254700000000",
+    business_phone="254711111111",
+)
+print(status.is_communication_window_active, status.window_expires_at)
+```
+
+---
+
+## Caching behavior
+
+The SDK implements an **in-process memory guard** in front of Lipay's Redis-backed `GET /api/v1/switchboard/session-status` endpoint.
+
+| Event | Behavior |
+|--------|----------|
+| Lipay returns `active=true` | Response cached in your app process RAM for **180 seconds** (configurable via `LipaySdkConfig.local_active_ttl_seconds`) |
+| Repeat lookup within TTL | Served from local memory — **no HTTP call** to Lipay |
+| Lipay returns `active=false` | **Never cached** — every lookup hits Lipay |
+| Local TTL expires | Cache entry dropped; next lookup syncs from Lipay |
+
+This mirrors how Twilio-style SDKs reduce read amplification: your container avoids redundant session-status traffic while the gateway remains the source of truth on Redis.
+
+---
+
+## FastAPI integration
+
+Install the optional extra:
+
+```bash
+pip install "lipay-sdk[fastapi] @ git+https://github.com/Evans-musamia/LipayMessagingPlatform.git@v1.0.0"
+```
+
+Wire the guard on application startup:
+
+```python
+from contextlib import asynccontextmanager
+
+import httpx
+from fastapi import Depends, FastAPI, Request
+
+from lipay_sdk import LipayCswSessionGuard
+from lipay_sdk.csw_session_guard import LipaySdkConfig
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    http = httpx.AsyncClient(timeout=10.0)
+    config = LipaySdkConfig(gateway_url="https://message.lipay.store")
+    app.state.lipay_guard = LipayCswSessionGuard(config, http_client=http)
+    yield
+    await app.state.lipay_guard.close()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+def get_guard(request: Request) -> LipayCswSessionGuard:
+    return request.app.state.lipay_guard
+
+
+@app.get("/check-window")
+async def check_window(
+    customer_phone: str,
+    business_phone: str,
+    guard: LipayCswSessionGuard = Depends(get_guard),
+):
+    return await guard.get_session_status(
+        customer_phone=customer_phone,
+        business_phone=business_phone,
+    )
+```
+
+---
+
+## API reference
+
+### `LipayCswSessionGuard`
+
+| Method | Description |
+|--------|-------------|
+| `is_window_active(customer_phone, business_phone)` | `bool` — CSW open for pair |
+| `get_session_status(...)` | `SessionStatus` — full gateway payload |
+| `fetch_from_lipay(...)` | Always calls Lipay (bypasses local cache) |
+| `close()` | Close owned `httpx` client |
+
+### `LipaySdkConfig` (Pydantic)
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `gateway_url` | required | Lipay gateway base URL |
+| `local_active_ttl_seconds` | `180` | Local RAM cache TTL |
+| `http_timeout_seconds` | `5.0` | HTTP client timeout |
+| `session_status_path` | `/api/v1/switchboard/session-status` | Status endpoint path |
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

lipay_sdk-1.0.0/README.md

@@ -0,0 +1,192 @@
+# Lipay Python SDK
+
+Official Python client for [Lipay](https://message.lipay.store) — the developer platform for WhatsApp messaging, routing, and Customer Service Window (CSW) management across Africa.
+
+Use this library in your application (BrandFlow, Teacher, custom backends) to check whether the Meta **24-hour customer service window** is open before sending free-text WhatsApp messages.
+
+---
+
+## Installation
+
+**From PyPI (recommended):**
+
+```bash
+pip install lipay-sdk
+pip install "lipay-sdk[fastapi]"
+```
+
+Pin in `requirements.txt`:
+
+```text
+lipay-sdk==1.0.0
+```
+
+**From Git (tagged release):**
+
+```bash
+pip install git+https://github.com/Evans-musamia/LipayMessagingPlatform.git@v1.0.0
+```
+
+**TestPyPI (maintainers — sandbox):**
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ lipay-sdk
+```
+
+**Editable (local development):**
+
+```bash
+git clone https://github.com/Evans-musamia/LipayMessagingPlatform.git
+cd LipayMessagingPlatform
+pip install -e ".[dev]"
+```
+
+Publishing guide: [PYPI.md](PYPI.md)
+
+---
+
+## Quick start
+
+```python
+import asyncio
+
+from lipay_sdk import LipayCswSessionGuard
+
+
+async def main() -> None:
+    guard = LipayCswSessionGuard("https://message.lipay.store")
+
+    active = await guard.is_window_active(
+        customer_phone="+254700000000",
+        business_phone="+254711111111",
+    )
+
+    if active:
+        print("CSW open — safe to send free-text via Lipay /v1/whatsapp/send")
+    else:
+        print("CSW closed — send an approved template first")
+
+    await guard.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Configuration object (Pydantic)
+
+For explicit control over timeouts, cache TTL, and API paths:
+
+```python
+from lipay_sdk.csw_session_guard import LipayCswSessionGuard, LipaySdkConfig
+
+config = LipaySdkConfig(
+    gateway_url="https://message.lipay.store",
+    local_active_ttl_seconds=180,
+    http_timeout_seconds=10.0,
+)
+guard = LipayCswSessionGuard(config)
+```
+
+### Full status payload
+
+```python
+status = await guard.get_session_status(
+    customer_phone="254700000000",
+    business_phone="254711111111",
+)
+print(status.is_communication_window_active, status.window_expires_at)
+```
+
+---
+
+## Caching behavior
+
+The SDK implements an **in-process memory guard** in front of Lipay's Redis-backed `GET /api/v1/switchboard/session-status` endpoint.
+
+| Event | Behavior |
+|--------|----------|
+| Lipay returns `active=true` | Response cached in your app process RAM for **180 seconds** (configurable via `LipaySdkConfig.local_active_ttl_seconds`) |
+| Repeat lookup within TTL | Served from local memory — **no HTTP call** to Lipay |
+| Lipay returns `active=false` | **Never cached** — every lookup hits Lipay |
+| Local TTL expires | Cache entry dropped; next lookup syncs from Lipay |
+
+This mirrors how Twilio-style SDKs reduce read amplification: your container avoids redundant session-status traffic while the gateway remains the source of truth on Redis.
+
+---
+
+## FastAPI integration
+
+Install the optional extra:
+
+```bash
+pip install "lipay-sdk[fastapi] @ git+https://github.com/Evans-musamia/LipayMessagingPlatform.git@v1.0.0"
+```
+
+Wire the guard on application startup:
+
+```python
+from contextlib import asynccontextmanager
+
+import httpx
+from fastapi import Depends, FastAPI, Request
+
+from lipay_sdk import LipayCswSessionGuard
+from lipay_sdk.csw_session_guard import LipaySdkConfig
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    http = httpx.AsyncClient(timeout=10.0)
+    config = LipaySdkConfig(gateway_url="https://message.lipay.store")
+    app.state.lipay_guard = LipayCswSessionGuard(config, http_client=http)
+    yield
+    await app.state.lipay_guard.close()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+def get_guard(request: Request) -> LipayCswSessionGuard:
+    return request.app.state.lipay_guard
+
+
+@app.get("/check-window")
+async def check_window(
+    customer_phone: str,
+    business_phone: str,
+    guard: LipayCswSessionGuard = Depends(get_guard),
+):
+    return await guard.get_session_status(
+        customer_phone=customer_phone,
+        business_phone=business_phone,
+    )
+```
+
+---
+
+## API reference
+
+### `LipayCswSessionGuard`
+
+| Method | Description |
+|--------|-------------|
+| `is_window_active(customer_phone, business_phone)` | `bool` — CSW open for pair |
+| `get_session_status(...)` | `SessionStatus` — full gateway payload |
+| `fetch_from_lipay(...)` | Always calls Lipay (bypasses local cache) |
+| `close()` | Close owned `httpx` client |
+
+### `LipaySdkConfig` (Pydantic)
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `gateway_url` | required | Lipay gateway base URL |
+| `local_active_ttl_seconds` | `180` | Local RAM cache TTL |
+| `http_timeout_seconds` | `5.0` | HTTP client timeout |
+| `session_status_path` | `/api/v1/switchboard/session-status` | Status endpoint path |
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

lipay_sdk-1.0.0/lipay_sdk/__init__.py

@@ -0,0 +1,5 @@
+"""Official Lipay Python SDK — public tenant integration surface."""
+
+from lipay_sdk.csw_session_guard import LipayCswSessionGuard
+
+__all__ = ["LipayCswSessionGuard"]

lipay_sdk-1.0.0/lipay_sdk/csw_session_guard.py

@@ -0,0 +1,196 @@
+"""
+Customer Service Window (CSW) session guard for Lipay tenant applications.
+
+Queries Lipay's Redis-backed session-status API with an in-process TTL cache
+so active-window lookups avoid redundant network round-trips.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+from pydantic import BaseModel, Field, field_validator
+
+
+def _normalize_phone(phone: str) -> str:
+    cleaned = phone.strip().replace(" ", "").replace("-", "")
+    if not cleaned:
+        return cleaned
+    if not cleaned.startswith("+"):
+        return f"+{cleaned.lstrip('+')}"
+    return cleaned
+
+
+class LipaySdkConfig(BaseModel):
+    """Runtime configuration for the Lipay HTTP client and local cache."""
+
+    gateway_url: str = Field(
+        ...,
+        description="Lipay gateway base URL, e.g. https://message.lipay.store",
+        min_length=8,
+    )
+    local_active_ttl_seconds: int = Field(
+        default=180,
+        ge=0,
+        description="In-process cache TTL after a successful active=true response",
+    )
+    http_timeout_seconds: float = Field(default=5.0, gt=0)
+    session_status_path: str = Field(
+        default="/api/v1/switchboard/session-status",
+        description="Path appended to gateway_url for CSW lookups",
+    )
+
+    @field_validator("gateway_url", "session_status_path")
+    @classmethod
+    def strip_slashes(cls, value: str) -> str:
+        return value.strip()
+
+
+class SessionStatus(BaseModel):
+    """Normalized response from Lipay session-status."""
+
+    customer_phone_number: str
+    business_phone_number: str
+    is_communication_window_active: bool
+    window_expires_at: str | None = None
+
+    @classmethod
+    def from_api_payload(cls, payload: dict[str, Any]) -> SessionStatus:
+        return cls.model_validate(payload)
+
+
+class LipayCswSessionGuard:
+    """
+    In-process TTL cache + Lipay ``GET /api/v1/switchboard/session-status`` client.
+
+    Use before outbound free-text WhatsApp sends to confirm the 24-hour CSW is open.
+    """
+
+    def __init__(
+        self,
+        config: LipaySdkConfig | str,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        if isinstance(config, str):
+            config = LipaySdkConfig(gateway_url=config)
+        self._config = config
+        self._base_url = config.gateway_url.rstrip("/")
+        self._status_path = (
+            config.session_status_path
+            if config.session_status_path.startswith("/")
+            else f"/{config.session_status_path}"
+        )
+        self._http = http_client
+        self._owns_client = http_client is None
+        self._local: dict[str, tuple[SessionStatus, float]] = {}
+
+    @property
+    def config(self) -> LipaySdkConfig:
+        return self._config
+
+    def _pair_key(self, business_phone: str, customer_phone: str) -> str:
+        return f"{_normalize_phone(business_phone)}:{_normalize_phone(customer_phone)}"
+
+    def _read_local(self, pair_key: str) -> SessionStatus | None:
+        entry = self._local.get(pair_key)
+        if not entry:
+            return None
+        payload, expires_at = entry
+        if time.monotonic() >= expires_at:
+            self._local.pop(pair_key, None)
+            return None
+        return payload
+
+    def _write_local_active(self, pair_key: str, status: SessionStatus) -> None:
+        ttl = self._config.local_active_ttl_seconds
+        self._local[pair_key] = (status, time.monotonic() + ttl)
+
+    def _clear_local(self, pair_key: str) -> None:
+        self._local.pop(pair_key, None)
+
+    async def _client(self) -> httpx.AsyncClient:
+        if self._http is None:
+            self._http = httpx.AsyncClient(timeout=self._config.http_timeout_seconds)
+        return self._http
+
+    async def close(self) -> None:
+        if self._owns_client and self._http is not None:
+            await self._http.aclose()
+            self._http = None
+
+    async def fetch_from_lipay(
+        self,
+        *,
+        customer_phone: str,
+        business_phone: str,
+    ) -> SessionStatus:
+        params = urlencode(
+            {
+                "customer_phone": customer_phone.lstrip("+"),
+                "business_phone": business_phone.lstrip("+"),
+            }
+        )
+        url = f"{self._base_url}{self._status_path}?{params}"
+        client = await self._client()
+        response = await client.get(url)
+        response.raise_for_status()
+        return SessionStatus.from_api_payload(response.json())
+
+    async def get_session_status(
+        self,
+        *,
+        customer_phone: str,
+        business_phone: str,
+    ) -> SessionStatus:
+        """Return CSW status — local memory first, then Lipay gateway."""
+        pair_key = self._pair_key(business_phone, customer_phone)
+
+        cached = self._read_local(pair_key)
+        if cached is not None:
+            return cached
+
+        status = await self.fetch_from_lipay(
+            customer_phone=customer_phone,
+            business_phone=business_phone,
+        )
+
+        if status.is_communication_window_active:
+            self._write_local_active(pair_key, status)
+        else:
+            self._clear_local(pair_key)
+
+        return status
+
+    async def is_window_active(
+        self,
+        *,
+        customer_phone: str,
+        business_phone: str,
+    ) -> bool:
+        """
+        Convenience API: ``True`` when the Meta 24-hour CSW is open for this pair.
+
+        Example::
+
+            guard = LipayCswSessionGuard("https://message.lipay.store")
+            if await guard.is_window_active(
+                customer_phone="+254700000000",
+                business_phone="+254711111111",
+            ):
+                ...
+        """
+        status = await self.get_session_status(
+            customer_phone=customer_phone,
+            business_phone=business_phone,
+        )
+        return status.is_communication_window_active
+
+    def is_communication_window_active(self, status: SessionStatus | dict[str, Any]) -> bool:
+        """Evaluate a status object returned by :meth:`get_session_status`."""
+        if isinstance(status, SessionStatus):
+            return status.is_communication_window_active
+        return bool(status.get("is_communication_window_active"))

lipay_sdk-1.0.0/lipay_sdk.egg-info/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: lipay-sdk
+Version: 1.0.0
+Summary: Official Python SDK for Lipay Messaging Platform
+Author-email: Evans Musamia <evans@lipay.store>
+Maintainer-email: Lipay Platform <dev@lipay.store>
+License: MIT
+Project-URL: Homepage, https://message.lipay.store
+Project-URL: Documentation, https://github.com/Evans-musamia/LipayMessagingPlatform#readme
+Project-URL: Repository, https://github.com/Evans-musamia/LipayMessagingPlatform
+Project-URL: Issues, https://github.com/Evans-musamia/LipayMessagingPlatform/issues
+Project-URL: Changelog, https://github.com/Evans-musamia/LipayMessagingPlatform/releases
+Keywords: lipay,whatsapp,messaging,africa,customer-service-window,api-sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Web Environment
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Telephony
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.9.0
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115.0; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# Lipay Python SDK
+
+Official Python client for [Lipay](https://message.lipay.store) — the developer platform for WhatsApp messaging, routing, and Customer Service Window (CSW) management across Africa.
+
+Use this library in your application (BrandFlow, Teacher, custom backends) to check whether the Meta **24-hour customer service window** is open before sending free-text WhatsApp messages.
+
+---
+
+## Installation
+
+**From PyPI (recommended):**
+
+```bash
+pip install lipay-sdk
+pip install "lipay-sdk[fastapi]"
+```
+
+Pin in `requirements.txt`:
+
+```text
+lipay-sdk==1.0.0
+```
+
+**From Git (tagged release):**
+
+```bash
+pip install git+https://github.com/Evans-musamia/LipayMessagingPlatform.git@v1.0.0
+```
+
+**TestPyPI (maintainers — sandbox):**
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ lipay-sdk
+```
+
+**Editable (local development):**
+
+```bash
+git clone https://github.com/Evans-musamia/LipayMessagingPlatform.git
+cd LipayMessagingPlatform
+pip install -e ".[dev]"
+```
+
+Publishing guide: [PYPI.md](PYPI.md)
+
+---
+
+## Quick start
+
+```python
+import asyncio
+
+from lipay_sdk import LipayCswSessionGuard
+
+
+async def main() -> None:
+    guard = LipayCswSessionGuard("https://message.lipay.store")
+
+    active = await guard.is_window_active(
+        customer_phone="+254700000000",
+        business_phone="+254711111111",
+    )
+
+    if active:
+        print("CSW open — safe to send free-text via Lipay /v1/whatsapp/send")
+    else:
+        print("CSW closed — send an approved template first")
+
+    await guard.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Configuration object (Pydantic)
+
+For explicit control over timeouts, cache TTL, and API paths:
+
+```python
+from lipay_sdk.csw_session_guard import LipayCswSessionGuard, LipaySdkConfig
+
+config = LipaySdkConfig(
+    gateway_url="https://message.lipay.store",
+    local_active_ttl_seconds=180,
+    http_timeout_seconds=10.0,
+)
+guard = LipayCswSessionGuard(config)
+```
+
+### Full status payload
+
+```python
+status = await guard.get_session_status(
+    customer_phone="254700000000",
+    business_phone="254711111111",
+)
+print(status.is_communication_window_active, status.window_expires_at)
+```
+
+---
+
+## Caching behavior
+
+The SDK implements an **in-process memory guard** in front of Lipay's Redis-backed `GET /api/v1/switchboard/session-status` endpoint.
+
+| Event | Behavior |
+|--------|----------|
+| Lipay returns `active=true` | Response cached in your app process RAM for **180 seconds** (configurable via `LipaySdkConfig.local_active_ttl_seconds`) |
+| Repeat lookup within TTL | Served from local memory — **no HTTP call** to Lipay |
+| Lipay returns `active=false` | **Never cached** — every lookup hits Lipay |
+| Local TTL expires | Cache entry dropped; next lookup syncs from Lipay |
+
+This mirrors how Twilio-style SDKs reduce read amplification: your container avoids redundant session-status traffic while the gateway remains the source of truth on Redis.
+
+---
+
+## FastAPI integration
+
+Install the optional extra:
+
+```bash
+pip install "lipay-sdk[fastapi] @ git+https://github.com/Evans-musamia/LipayMessagingPlatform.git@v1.0.0"
+```
+
+Wire the guard on application startup:
+
+```python
+from contextlib import asynccontextmanager
+
+import httpx
+from fastapi import Depends, FastAPI, Request
+
+from lipay_sdk import LipayCswSessionGuard
+from lipay_sdk.csw_session_guard import LipaySdkConfig
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    http = httpx.AsyncClient(timeout=10.0)
+    config = LipaySdkConfig(gateway_url="https://message.lipay.store")
+    app.state.lipay_guard = LipayCswSessionGuard(config, http_client=http)
+    yield
+    await app.state.lipay_guard.close()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+def get_guard(request: Request) -> LipayCswSessionGuard:
+    return request.app.state.lipay_guard
+
+
+@app.get("/check-window")
+async def check_window(
+    customer_phone: str,
+    business_phone: str,
+    guard: LipayCswSessionGuard = Depends(get_guard),
+):
+    return await guard.get_session_status(
+        customer_phone=customer_phone,
+        business_phone=business_phone,
+    )
+```
+
+---
+
+## API reference
+
+### `LipayCswSessionGuard`
+
+| Method | Description |
+|--------|-------------|
+| `is_window_active(customer_phone, business_phone)` | `bool` — CSW open for pair |
+| `get_session_status(...)` | `SessionStatus` — full gateway payload |
+| `fetch_from_lipay(...)` | Always calls Lipay (bypasses local cache) |
+| `close()` | Close owned `httpx` client |
+
+### `LipaySdkConfig` (Pydantic)
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `gateway_url` | required | Lipay gateway base URL |
+| `local_active_ttl_seconds` | `180` | Local RAM cache TTL |
+| `http_timeout_seconds` | `5.0` | HTTP client timeout |
+| `session_status_path` | `/api/v1/switchboard/session-status` | Status endpoint path |
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

lipay_sdk-1.0.0/lipay_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+lipay_sdk/__init__.py
+lipay_sdk/csw_session_guard.py
+lipay_sdk.egg-info/PKG-INFO
+lipay_sdk.egg-info/SOURCES.txt
+lipay_sdk.egg-info/dependency_links.txt
+lipay_sdk.egg-info/requires.txt
+lipay_sdk.egg-info/top_level.txt
+tests/test_csw_session_guard.py

lipay_sdk-1.0.0/lipay_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lipay_sdk-1.0.0/lipay_sdk.egg-info/requires.txt

@@ -0,0 +1,11 @@
+httpx>=0.27.0
+pydantic>=2.9.0
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.24
+build>=1.0
+twine>=5.0
+
+[fastapi]
+fastapi>=0.115.0

lipay_sdk-1.0.0/lipay_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+lipay_sdk

lipay_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lipay-sdk"
+version = "1.0.0"
+description = "Official Python SDK for Lipay Messaging Platform"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Evans Musamia", email = "evans@lipay.store" }]
+maintainers = [{ name = "Lipay Platform", email = "dev@lipay.store" }]
+keywords = ["lipay", "whatsapp", "messaging", "africa", "customer-service-window", "api-sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Environment :: Web Environment",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Telephony",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.9.0",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.115.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "build>=1.0", "twine>=5.0"]
+
+[project.urls]
+Homepage = "https://message.lipay.store"
+Documentation = "https://github.com/Evans-musamia/LipayMessagingPlatform#readme"
+Repository = "https://github.com/Evans-musamia/LipayMessagingPlatform"
+Issues = "https://github.com/Evans-musamia/LipayMessagingPlatform/issues"
+Changelog = "https://github.com/Evans-musamia/LipayMessagingPlatform/releases"
+
+[tool.setuptools.packages.find]
+include = ["lipay_sdk*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

lipay_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lipay_sdk-1.0.0/tests/test_csw_session_guard.py

@@ -0,0 +1,105 @@
+"""Unit tests for lipay_sdk.csw_session_guard."""
+
+import time
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from lipay_sdk import LipayCswSessionGuard
+from lipay_sdk.csw_session_guard import LipaySdkConfig, SessionStatus
+
+
+ACTIVE = SessionStatus(
+    customer_phone_number="+254700000000",
+    business_phone_number="+254711111111",
+    is_communication_window_active=True,
+    window_expires_at="2026-06-01T15:30:22Z",
+)
+
+INACTIVE = SessionStatus(
+    customer_phone_number="+254700000000",
+    business_phone_number="+254711111111",
+    is_communication_window_active=False,
+    window_expires_at=None,
+)
+
+
+def test_config_from_string_gateway_url():
+    guard = LipayCswSessionGuard("https://message.lipay.store")
+    assert guard.config.gateway_url == "https://message.lipay.store"
+
+
+def test_config_pydantic_overrides():
+    config = LipaySdkConfig(
+        gateway_url="https://message.lipay.store",
+        local_active_ttl_seconds=60,
+        session_status_path="/api/v1/switchboard/session-status",
+    )
+    guard = LipayCswSessionGuard(config)
+    assert guard.config.local_active_ttl_seconds == 60
+
+
+@pytest.mark.asyncio
+async def test_is_window_active_true():
+    guard = LipayCswSessionGuard("https://message.lipay.store")
+    with patch.object(
+        guard, "fetch_from_lipay", new_callable=AsyncMock, return_value=ACTIVE
+    ):
+        assert await guard.is_window_active(
+            customer_phone="254700000000",
+            business_phone="254711111111",
+        )
+
+
+@pytest.mark.asyncio
+async def test_local_cache_skips_second_fetch():
+    guard = LipayCswSessionGuard("https://message.lipay.store")
+    with patch.object(
+        guard, "fetch_from_lipay", new_callable=AsyncMock, return_value=ACTIVE
+    ) as mock_fetch:
+        await guard.get_session_status(
+            customer_phone="254700000000",
+            business_phone="254711111111",
+        )
+        await guard.get_session_status(
+            customer_phone="254700000000",
+            business_phone="254711111111",
+        )
+    mock_fetch.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_inactive_never_cached():
+    guard = LipayCswSessionGuard("https://message.lipay.store")
+    with patch.object(
+        guard, "fetch_from_lipay", new_callable=AsyncMock, return_value=INACTIVE
+    ) as mock_fetch:
+        await guard.get_session_status(
+            customer_phone="254700000000",
+            business_phone="254711111111",
+        )
+        await guard.get_session_status(
+            customer_phone="254700000000",
+            business_phone="254711111111",
+        )
+    assert mock_fetch.await_count == 2
+
+
+@pytest.mark.asyncio
+async def test_expired_local_cache_refetches():
+    config = LipaySdkConfig(
+        gateway_url="https://message.lipay.store",
+        local_active_ttl_seconds=1,
+    )
+    guard = LipayCswSessionGuard(config)
+    pair_key = guard._pair_key("254711111111", "254700000000")
+    guard._local[pair_key] = (ACTIVE, time.monotonic() - 1)
+
+    with patch.object(
+        guard, "fetch_from_lipay", new_callable=AsyncMock, return_value=ACTIVE
+    ) as mock_fetch:
+        await guard.get_session_status(
+            customer_phone="254700000000",
+            business_phone="254711111111",
+        )
+    mock_fetch.assert_awaited_once()