feat: finished docs and added GitHub deploy yml

Author: RafaelJohn9

.github/workflows/deploy-docs.yml

@@ -0,0 +1,56 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches: [main, master]
+    paths:
+        - 'docs/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+          cache-dependency-path: './docs/package-lock.json'
+
+      - name: Install dependencies
+        run: |
+          cd docs
+          npm ci
+
+      - name: Build website
+        run: |
+          cd docs
+          npm run build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './docs/build'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/docs/account-balance.mdx

@@ -0,0 +1,316 @@
+---
+title: Account Balance
+description: Query organization account balances and handle result and timeout callbacks from the M-Pesa Account Balance API.
+---
+
+import SectionHeader from '@site/docs/components/SectionHeader';
+import CodeBlock from '@site/docs/components/CodeBlock';
+import Alert from '@site/docs/components/Alert';
+import ParametersTable from '@site/docs/components/ParametersTable';
+import Tabs from '@site/docs/components/Tabs';
+
+<SectionHeader
+    subtitle="Request account balances, receive asynchronous result notifications, and handle timeout callbacks from Safaricom's Account Balance API."
+    gradient={true}
+    size="large"
+/>
+
+<Alert type="info" title="What this page covers">
+    This guide documents the Account Balance flow: how to construct queries, expected acknowledgement responses, how to parse ResultURL callbacks (final balances) and QueueTimeOutURL notifications, and important validation/safety checks to implement on your side.
+</Alert>
+
+<SectionHeader title="Parameters Definition" size="small" />
+
+<ParametersTable
+parameters={[
+    {
+        name: "Initiator",
+        type: "str",
+        dataType: "String",
+        required: true,
+        description: "Username used to initiate the request (API initiator identity)."
+    },
+    {
+        name: "SecurityCredential",
+        type: "str",
+        dataType: "String",
+        required: true,
+        description: "Encrypted security credential (as required by Safaricom)."
+    },
+    {
+        name: "CommandID",
+        type: "str",
+        dataType: "String",
+        required: true,
+        description: "Transaction type. Default: 'AccountBalance'."
+    },
+    {
+        name: "PartyA",
+        type: "int",
+        dataType: "Integer",
+        required: true,
+        description: "Organization shortcode, till number or MSISDN depending on IdentifierType."
+    },
+    {
+        name: "IdentifierType",
+        type: "int",
+        dataType: "Integer",
+        required: true,
+        description: "Type of PartyA. Allowed values: 1 (MSISDN), 2 (Till number), 4 (Short code)."
+    },
+    {
+        name: "Remarks",
+        type: "str",
+        dataType: "String",
+        required: true,
+        description: "Freeform comments for the transaction (must not exceed 100 characters)."
+    },
+    {
+        name: "QueueTimeOutURL",
+        type: "str",
+        dataType: "String",
+        required: true,
+        description: "Callback URL for timeout notifications (QueueTimeOutURL)."
+    },
+    {
+        name: "ResultURL",
+        type: "str",
+        dataType: "String",
+        required: true,
+        description: "Callback URL where final account balance result will be posted."
+    }
+]}
+/>
+
+<SectionHeader title="Responses & Result Notifications" size="small" />
+
+<ParametersTable
+parameters={[
+    {
+        name: "OriginatorConversationID",
+        type: "str",
+        dataType: "String",
+        required: false,
+        description: "Unique identifier for the original request acknowledgement."
+    },
+    {
+        name: "ConversationID",
+        type: "str",
+        dataType: "String",
+        required: false,
+        description: "Unique transaction identifier returned by M-Pesa."
+    },
+    {
+        name: "ResponseCode",
+        type: "str|int",
+        dataType: "String/Integer",
+        required: true,
+        description: "Acknowledgement status code. '0' indicates acceptance of the request."
+    },
+    {
+        name: "ResponseDescription",
+        type: "str",
+        dataType: "String",
+        required: true,
+        description: "Human readable acknowledgement message."
+    },
+    {
+        name: "Result.ResultType / Result.ResultCode / Result.ResultDesc",
+        type: "int|int|str",
+        dataType: "Integer/Integer/String",
+        required: true,
+        description: "Result metadata posted to ResultURL. ResultType=0 => success; ResultCode=0 => success."
+    },
+    {
+        name: "Result.ResultParameter.ResultParameters",
+        type: "list",
+        dataType: "Array",
+        required: false,
+        description: "List of key/value result parameters. 'AccountBalance' key contains pipe- and ampersand-delimited balance blobs for accounts."
+    },
+    {
+        name: "ReferenceData.ReferenceItem",
+        type: "object",
+        dataType: "Object",
+        required: false,
+        description: "Reference item included in callbacks (e.g., original QueueTimeoutURL)."
+    }
+]}
+/>
+
+<SectionHeader title="Overview" size="small" subtitle="Query lifecycle: send AccountBalance request → receive immediate ack → process asynchronous result or timeout." />
+
+<Alert type="info" title="Implementation Options">
+    - Use the high-level MpesaClient/BalanceService facade for token management, header injection and typed Pydantic models.  
+    - Use the lower-level AccountBalance class with a TokenManager and HttpClient if you need full control over request construction, middleware and error handling.
+</Alert>
+
+<Tabs defaultValue={0}>
+    <Tabs.TabPane label="MpesaClient (Recommended)" icon="🚀">
+        <Alert type="info" title="Why use the facade">
+            The facade handles authentication and returns typed models (acknowledgement and parsed callbacks). Use it for concise integration in most applications.
+        </Alert>
+
+        <SectionHeader title="Quick Setup" size="small" />
+
+        <CodeBlock language="python" title="Python (example)">
+{`
+# Requires: mpesakit, fastapi (for webhook example)
+from mpesakit import MpesaClient
+from mpesakit.account_balance import (
+    AccountBalanceResultCallback,
+    AccountBalanceTimeoutCallback,
+    AccountBalanceIdentifierType,
+)
+from mpesakit.security.ip_whitelist import is_mpesa_ip_allowed
+
+# ---- Client / Request (synchronous example) ----
+client = MpesaClient(consumer_key="YOUR_KEY", consumer_secret="YOUR_SECRET", environment="sandbox")
+
+resp = client.balance.query(
+    initiator="apiuser",
+    security_credential="ENCRYPTED_SECURITY_CREDENTIAL",
+    party_a=600000,
+    identifier_type=AccountBalanceIdentifierType.SHORT_CODE,
+    remarks="Balance inquiry",
+    result_url="https://your.service/webhook/account-balance/result",
+    queue_timeout_url="https://your.service/webhook/account-balance/timeout",
+)
+
+if resp.is_successful():
+    print("Acknowledgement accepted:", resp.ConversationID or resp.OriginatorConversationID)
+else:
+    print("Acknowledgement failed:", resp.ResponseDescription)
+
+`}
+        </CodeBlock>
+    </Tabs.TabPane>
+
+    <Tabs.TabPane label="Direct API" icon="⚡">
+        <Alert type="warning" title="Advanced Usage">
+            Use the direct AccountBalance service with explicit TokenManager and HttpClient if you need custom request shaping, retry policies or observability hooks.
+        </Alert>
+
+        <SectionHeader title="Direct Implementation" size="small" />
+
+        <CodeBlock language="python" title="Python (example)">
+{`
+# Build an AccountBalanceRequest and call the low-level service.
+# The service posts to /mpesa/accountbalance/v1/query and returns an acknowledgement.
+request = AccountBalanceRequest(...)
+response = account_balance.query(request)
+# response is an AccountBalanceResponse model.
+`}
+        </CodeBlock>
+    </Tabs.TabPane>
+</Tabs>
+
+<SectionHeader title="Webhook Handling (Result & Timeout)" size="small" />
+
+<CodeBlock language="python" title="Webhook Example (FastAPI)">
+{`
+# Example: FastAPI endpoints for Account Balance Result & Timeout callbacks
+from fastapi import FastAPI, Request, HTTPException
+from mpesakit.account_balance import (
+    AccountBalanceResultCallback,
+    AccountBalanceTimeoutCallback,
+    AccountBalanceResultCallbackResponse,
+    AccountBalanceTimeoutCallbackResponse,
+)
+from mpesakit.security.ip_whitelist import is_mpesa_ip_allowed
+import logging
+
+app = FastAPI()
+logger = logging.getLogger("mpesa.account_balance")
+
+
+async def _caller_ip(request: Request) -> str:
+    return (request.headers.get("x-forwarded-for") or request.client.host).split(",")[0].strip()
+
+
+@app.post("/webhook/account-balance/result")
+async def account_balance_result(request: Request):
+    payload = await request.json()
+    caller_ip = await _caller_ip(request)
+    if not is_mpesa_ip_allowed(caller_ip):
+        raise HTTPException(status_code=403, detail="forbidden")
+
+    # Validate and parse incoming payload into project models
+    try:
+        callback = AccountBalanceResultCallback(**payload)
+    except Exception as exc:
+        logger.exception("Invalid AccountBalance result payload")
+        return AccountBalanceResultCallbackResponse(ResultCode=1, ResultDesc=f"Invalid payload: {exc}")
+
+    response = callback.model_dump(mode="json")
+    logger.info("AccountBalance result received: %s", response)
+
+    return AccountBalanceResultCallbackResponse()  # defaults to ResultCode=0, ResultDesc="Result received and processed successfully."
+
+
+@app.post("/webhook/account-balance/timeout")
+async def account_balance_timeout(request: Request):
+    payload = await request.json()
+    caller_ip = await _caller_ip(request)
+    if not is_mpesa_ip_allowed(caller_ip):
+        raise HTTPException(status_code=403, detail="forbidden")
+
+    try:
+        callback = AccountBalanceTimeoutCallback(**payload)
+    except Exception as exc:
+        logger.exception("Invalid AccountBalance timeout payload")
+        return AccountBalanceTimeoutCallbackResponse(ResultCode=1, ResultDesc=f"Invalid payload: {exc}")
+
+    response = callback.model_dump(mode="json")
+    logger.warning("AccountBalance timeout received: %s", response)
+
+    # Quick typed acknowledgement to stop retries
+    return AccountBalanceTimeoutCallbackResponse()  # defaults to ResultCode=0, ResultDesc="Timeout notification received and processed successfully."
+`}
+</CodeBlock>
+
+<SectionHeader title="Important behaviors & validations" size="small" />
+
+<Alert type="warning" title="IdentifierType & Remarks validation">
+    - IdentifierType must be one of the supported enum values (1=MSISDN, 2=Till number, 4=Short code). Invalid values should be rejected before sending requests.  
+    - Remarks must not exceed 100 characters; the client/model will raise validation errors if this rule is violated.
+</Alert>
+
+<Alert type="info" title="Acknowledgement semantics">
+    - The initial /query call returns an acknowledgement (ResponseCode/ResponseDescription). This does not contain the final balance.  
+    - Final account balances are delivered asynchronously to your ResultURL (ResultType/ResultCode = 0 indicates success).
+</Alert>
+
+<SectionHeader title="Response helpers" size="small" />
+
+- A returned AccountBalanceResponse model exposes:
+- is_successful() helper that treats any all-zero ResponseCode string (e.g., "0" or "000") as success.
+- Result callbacks are parsed into AccountBalanceResultCallback with:
+- ResultParameter.ResultParameters list containing an 'AccountBalance' entry holding a delimited balance string.
+
+
+<SectionHeader title="Testing & Expected Behaviors" size="small" />
+
+- Query:
+    - Should return an AccountBalanceResponse acknowledgement. Confirm `is_successful()` for `ResponseCode == 0`.
+    - HTTP client must receive the correct path and headers (`Authorization Bearer token + JSON content-type`).
+
+- Result Callback:
+    - Parse Result.ResultParameter.ResultParameters and extract the AccountBalance key. Persist parsed balances for reconciliation.
+    - Ensure your handler returns the expected acknowledgement payload quickly so provider retries are avoided.
+
+- Timeout Callback:
+    - QueueTimeOutURL receives a Result with ResultType=1; handle accordingly (mark request as timed out, alert operations).
+
+<SectionHeader title="Next Steps" size="small" />
+
+<Alert type="info" title="Go-live checklist">
+    - Implement secure callback endpoints (IP restrictions, TLS).  
+    - Persist both acknowledgements and final result notifications for audit and reconciliation.  
+    - Add observability & alerting for timeout notifications and unexpected result codes.
+</Alert>
+
+## Related Documentation
+
+- [📡 Webhook Setup Guide](/webhooks-best-practices) - Best practices for building reliable endpoints  
+- [🏗️ Production Setup](/production) - Go-live checklist, security and monitoring