Add swap service

[watersRand]

Description

This PR introduces the SIM Swap Detection Service (/imsi/v2/checkATI) to support checking when a subscriber's SIM card was last swapped. This helps detect and mitigate account takeover and fraud risks prior to completing high-value transactions.

Key changes included:

• Service & Facades: Implemented SwapService and AsyncSwapService with swap_query(customer_number) and swap_request(request) methods.
• Data Validation & Schemas: Added SwapRequest (with MSISDN auto-normalization) and SwapResponse Pydantic models.
• Fraud Detection Helpers: Added is_successful and is_recently_swapped properties to SwapResponse to handle Safaricom's sentinel non-swapped date (01-01-1900).
• Type Stubs & Documentation: Added .pyi type stubs, updated docs/swap.md, and updated landing page status/feature data.

Fixes #160

Type of Change

• New feature (non-breaking change that adds functionality)
• This change requires documentation update

How Has This Been Tested?

• Unit Tests: Added tests covering SwapRequest phone number auto-normalization, SwapResponse.is_recently_swapped sentinel date evaluation (01-01-1900 vs active timestamp), and sync/async service call execution.
• Ruff & Type Linting: Executed ruff check and type assertions with .pyi stub files to verify clean linting across the package.

Checklist

• My code follows the project's coding style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings or errors
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

Screenshots (if applicable)

N/A (Backend API addition & documentation update)

Additional Context

• SIM Swap Detection (checkATI) is a paid API product on Safaricom Daraja. Documentation and docstrings reflect onboarding guidance for sandbox and production.

[RafaelJohn9]

Hello @watersRand , thanks for the awesome PR, a few changes to consider 🤝

[RafaelJohn9]

Apologies for the late review. you can always tag me for a review, no worries 🤝 ,

Thanks for the changes and we have a few things to do before we become ready to merge.

• Remove the environment parameter across the Swap module since this is only used inside http_client module.
• We then update the stubs correctly.
• Then we wire in this service to client and async client see (https://github.com/Byte-Barn/mpesakit/blob/master/mpesakit/mpesa_client.py)

Then we will be good to go 👍

[RafaelJohn9]

We can deprecate the environment parameter that we have across the different swap files, since this is handled by our http client file.

[watersRand]

@RafaelJohn9 ready

[RafaelJohn9]

Thanks for addressing the earlier feedback — the lastSwapDate doc note, using the shared HTTP client, and dropping environment from Swap/AsyncSwap all look good.

One loose end: environment was removed from Swap/AsyncSwap but is still threaded through the SwapService/AsyncSwapService facades, the docs examples, and the E2E tests. Since Swap/AsyncSwap are Pydantic models without extra="forbid", passing environment=... to them is silently dropped rather than erroring, so this isn't caught by tests — but it's dead/misleading code. Left inline comments on where this needs cleanup.

[RafaelJohn9]

SwapService still takes an environment param (default "sandbox") and forwards it here to Swap(...), but Swap no longer has an environment field — it's silently dropped by Pydantic. mpesa_client.py doesn't even pass environment when constructing SwapService, so this is dead state at every call site. Please remove environment from this facade too, matching the cleanup already done on Swap/AsyncSwap.

[RafaelJohn9]

Same issue as SwapService above — environment is forwarded to AsyncSwap(...), which no longer accepts it.

[RafaelJohn9]

This example still passes environment=env to Swap(...), which no longer has that parameter (it's now a no-op field that gets dropped). Please update the example to match the current constructor signature (http_client + token_manager only).

[RafaelJohn9]

Same stale environment=env kwarg here for AsyncSwap(...).

[RafaelJohn9]

This fixture still passes environment=env into Swap(...), which no longer accepts it — worth dropping so the test reflects the real constructor.

[RafaelJohn9]

Same stale environment=env kwarg for AsyncSwap(...) here.

[watersRand]

@RafaelJohn9 Thanks for the thorough review. I didn't realize I had missed these