saman-api 0.1.0__tar.gz

saman_api-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+.verify-venv/
+.mypy_cache/
+.ruff_cache/
+runtime-audit.txt
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.coverage
+.pytest_cache/
+.env
+.pypirc
+session*.json
+*.har

saman_api-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Initial typed Python HTTP SDK for Saman Mobillet API 0.3+.
+- Explicit sync and async methods for all 67 documented API operations.
+- Interactive credential/SMS login, pending-session resume, and English CLI.
+- Structured errors with preserved server payloads and no secret-bearing repr.
+- Bounded transaction iteration, exact identifier preservation, no SDK retries.
+- CLI commands for every operation, with explicit confirmation for money movement.

saman_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 APIBANK contributors
+
+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.

saman_api-0.1.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.5
+Name: saman-api
+Version: 0.1.0
+Summary: Typed sync and async Python clients for the Saman Mobillet HTTP API
+Project-URL: Documentation, https://apibank.heydari.workers.dev/saman/
+Project-URL: Repository, https://github.com/DevURANIUM/saman-api
+Project-URL: Issues, https://github.com/DevURANIUM/saman-api/issues
+Author: APIBANK contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,banking,client,iran,mobillet,saman
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28.1
+Description-Content-Type: text/markdown
+
+# saman-api
+
+A typed, synchronous and asynchronous Python client for the **Saman Mobillet HTTP API**.
+
+This package talks to your running Saman API service. It **does not connect directly
+to the bank**, replace the Node.js server, or execute requests through the documentation
+website. The service manages bank encryption, cookies and the bank session.
+
+Requires Python 3.10+ and API service 0.3+. All SDK prompts and messages are English.
+
+## Installation
+
+```sh
+pip install saman-api
+```
+
+Until the first PyPI release, install from the source package directory:
+
+```sh
+pip install .
+```
+
+Start the accompanying Node.js API server with `npm install` and `npm start`.
+Configure `SAMAN_API_KEY` on the server and provide the same key to this client.
+The default API URL is `http://127.0.0.1:8089/v1`; a supplied URL without `/v1`
+has that suffix appended. Production connections should use HTTPS.
+
+```python
+from samanapi import Client
+
+with Client(base_url="http://127.0.0.1:8089/v1", api_key="YOUR_SERVICE_API_KEY") as client:
+    result = client.sign_in()  # Username, hidden password, then hidden SMS code if needed
+    print(result["bankVerified"])
+    print(client.deposits())
+    print(client.cards())
+    print(client.balance())
+```
+
+The constructor also reads `SAMAN_API_URL` and `SAMAN_API_KEY`. Bank credentials
+are not stored by this Python package. One API server owns one bank session:
+creating another Python client does **not** create an independent bank login.
+`close()` closes HTTP connections; `logout()` clears the shared server session.
+
+## Login in a web application
+
+Use explicit stages rather than an interactive prompt:
+
+```python
+from samanapi import Client
+
+with Client() as client:
+    result = client.login("YOUR_USERNAME", "YOUR_PASSWORD")
+    if result.get("otpRequired"):
+        if result.get("otpSent"):
+            # Collect the code in your application's UI, then call:
+            result = client.verify_otp("123456")  # synthetic example code
+        else:
+            print(result.get("otpError"))
+```
+
+The service requests the device SMS automatically. Do not call `request_otp()`
+after every login: it is an explicit resend. `sign_in()` accepts `otp_callback`
+for integration, and resumes a pending code step when called without credentials.
+Return `resend` from the callback to request another code. Wrong codes leave the
+pending server session available for another attempt. Use `login(..., request_otp=False)`
+only when you deliberately want the service's legacy manual-SMS workflow.
+
+`ok=True` can mean that the initial credential step succeeded. A completed login
+has `loggedIn=True` and `bankVerified=True`. Password-change requirements must be
+completed in the bank app. Device-verification, card PIN2 and digital-rial activation
+codes belong to different workflows.
+
+## Async client
+
+```python
+import asyncio
+from samanapi import AsyncClient
+
+async def main():
+    async with AsyncClient() as client:
+        print(await client.check_session())
+        print(await client.latest_transactions("123-456-0000001-2", limit=10))
+
+asyncio.run(main())
+```
+
+Every endpoint has the same name and parameters in `Client` and `AsyncClient`.
+`AsyncClient.sign_in` accepts synchronous or asynchronous callbacks. Default
+interactive callbacks run in a worker thread. Transaction iteration uses
+`for row in client.iter_transactions(...)` or `async for` with the async client.
+
+## History, details and exact search
+
+```python
+with Client() as client:
+    history = client.transactions(
+        "123-456-0000001-2", page=0, size=20,
+        details=True, is_withdrawal=False,
+        from_date=1700000000, to_date=1700086400,
+    )
+    result = client.find_transaction(
+        "000000000001", "123-456-0000001-2",
+        match_by="reference", pages=10, max_transactions=200,
+    )
+    if not result["found"]:
+        print(result["searchComplete"], result["stopReason"])
+```
+
+Pages start at **0**. Transaction dates are Unix **seconds**; merchant summary
+`from_date` is Unix **milliseconds**. Identifiers, tracking/reference numbers,
+cards, deposit numbers and IBANs stay strings, preserving leading zeros.
+Transaction IDs are encoded as one URL segment, including embedded slashes.
+
+`details=True` lets the server include full bank detail/receipt objects in each
+row's `detail`. Unknown fields are preserved. The SDK does not infer a sender's
+name or card number from free text. JSON null balances remain `None`, and absent
+fields remain absent; neither is converted to zero. Card and deposit balances
+are not added together.
+
+`iter_transactions(..., size=100, max_pages=10, details=False)` is bounded. It raises
+`PaginationError` when a page repeats or the budget runs out before the end of
+history. It does not silently claim that a bounded search covered the whole account.
+
+## Transfers and digital rial
+
+```python
+with Client() as client:
+    reasons = client.transfer_reasons()
+    owner = client.iban_owner("IR000000000000000000000000")  # synthetic, replace it
+    # Programmatic money movement is explicit; no confirmation dialog is inserted:
+    # receipt = client.transfer_iban(source, destination, amount_irr, reason_code)
+```
+
+Transfer amounts are positive integer **IRR**, capped at JavaScript's safe integer
+range. Card expiry is Jalali `YYYYMM`. `transfer_card` needs `cvv2`, `pin2`, and
+`expire_date`. The server encrypts these fields. PAYA takes a deposit as source
+and an IBAN as destination. Select `reason_code` from `transfer_reasons()`.
+The current service implements CARD, DEPOSIT and PAYA, not SATNA/POL submission.
+
+Digital rial has separate eligibility, SMS, activation, balance, transaction,
+charge, discharge, deactivation and contact methods. Wallet history IDs differ
+from deposit-history IDs. Activation currently supports CUSTOMER wallets.
+
+The SDK never retries or follows redirects automatically. On a timeout or a
+cancelled payment request, the operation may already have succeeded: inspect
+history before submitting another instruction. API-server renewal behavior is
+separate from the SDK; the companion server never automatically replays transfers.
+
+## Errors and response preservation
+
+```python
+from samanapi import Client, ApiError, TransportError
+
+try:
+    with Client() as client:
+        print(client.cards())
+except ApiError as exc:
+    print(exc.status_code, exc.code, exc.next_action)
+    # exc.payload contains the full response; inspect it only where appropriate.
+except TransportError as exc:
+    print(exc.request_may_have_succeeded)
+```
+
+Exception types include `AuthenticationError`, `DeviceVerificationRequired`,
+`PasswordChangeRequired`, `ValidationError`, `BankError`, `SmsDeliveryError`,
+`TransportError`, `ProtocolError` and `PaginationError`. HTTP errors preserve
+`payload`, `bank_status`, `auth`, `next_action`, `method` and `path`. Error string
+representations do not print server payloads or credentials. An HTTP 200 body
+containing an application `error` is not silently accepted.
+
+The default response limit is 20 MiB; larger responses raise `ProtocolError`
+rather than being truncated. Configure `max_response_bytes` explicitly if needed.
+`timeout` defaults to 120 seconds. Longer bounded searches may need a larger value.
+Custom HTTPX transports are supported for tests and advanced use; their own retry
+or security behavior is the caller's responsibility. `trust_env` defaults to false.
+
+## CLI
+
+```sh
+saman-api login
+saman-api status
+saman-api deposits
+saman-api balance
+saman-api transactions --deposit-number 123-456-0000001-2 --page 0 --size 20 --details false
+saman-api find-transaction 000000000001 --deposit-number 123-456-0000001-2 --match-by reference
+saman-api --help
+```
+
+The API key is read from `SAMAN_API_KEY`. `SAMAN_USER` and `SAMAN_PASS` may supply
+credentials to CLI login. All endpoint methods have hyphenated CLI commands;
+`--help` lists their arguments. Boolean arguments take `true` or `false`.
+Wallet filter lists are comma-separated. Use `python -m samanapi` as an
+alternative entry point. The CLI writes JSON results to stdout and errors to
+stderr; `--json-errors` gives structured errors and exit code 1. Cancellation
+uses exit code 130. Financial commands require `TRANSFER`, wallet activation
+`ACTIVATE`, and deactivation `DEACTIVATE`; noninteractive callers must pass the
+matching `--confirm` value. Required card secrets are prompted without echo
+when omitted. Use `import-har FILE` for a local private capture, never a public example.
+
+## API reference and development
+
+See [the complete method reference](docs/reference.md) and the
+[HTTP service documentation](https://apibank.heydari.workers.dev/saman/).
+`request("GET", "cards", query={...})` is available for future relative routes;
+absolute/cross-origin paths and traversal are rejected before any I/O.
+
+```sh
+pip install -e .
+python -m unittest discover -s tests -v
+python tools/generate_async.py
+python -m build
+python -m twine check dist/*
+```
+
+Tests use mock transports and a fake bank behind the real Node server. They do
+not send money or verify a current live bank session. The source distribution
+and wheel use explicit include rules and contain no sessions, captures or API keys.

saman_api-0.1.0/README.md

@@ -0,0 +1,217 @@
+# saman-api
+
+A typed, synchronous and asynchronous Python client for the **Saman Mobillet HTTP API**.
+
+This package talks to your running Saman API service. It **does not connect directly
+to the bank**, replace the Node.js server, or execute requests through the documentation
+website. The service manages bank encryption, cookies and the bank session.
+
+Requires Python 3.10+ and API service 0.3+. All SDK prompts and messages are English.
+
+## Installation
+
+```sh
+pip install saman-api
+```
+
+Until the first PyPI release, install from the source package directory:
+
+```sh
+pip install .
+```
+
+Start the accompanying Node.js API server with `npm install` and `npm start`.
+Configure `SAMAN_API_KEY` on the server and provide the same key to this client.
+The default API URL is `http://127.0.0.1:8089/v1`; a supplied URL without `/v1`
+has that suffix appended. Production connections should use HTTPS.
+
+```python
+from samanapi import Client
+
+with Client(base_url="http://127.0.0.1:8089/v1", api_key="YOUR_SERVICE_API_KEY") as client:
+    result = client.sign_in()  # Username, hidden password, then hidden SMS code if needed
+    print(result["bankVerified"])
+    print(client.deposits())
+    print(client.cards())
+    print(client.balance())
+```
+
+The constructor also reads `SAMAN_API_URL` and `SAMAN_API_KEY`. Bank credentials
+are not stored by this Python package. One API server owns one bank session:
+creating another Python client does **not** create an independent bank login.
+`close()` closes HTTP connections; `logout()` clears the shared server session.
+
+## Login in a web application
+
+Use explicit stages rather than an interactive prompt:
+
+```python
+from samanapi import Client
+
+with Client() as client:
+    result = client.login("YOUR_USERNAME", "YOUR_PASSWORD")
+    if result.get("otpRequired"):
+        if result.get("otpSent"):
+            # Collect the code in your application's UI, then call:
+            result = client.verify_otp("123456")  # synthetic example code
+        else:
+            print(result.get("otpError"))
+```
+
+The service requests the device SMS automatically. Do not call `request_otp()`
+after every login: it is an explicit resend. `sign_in()` accepts `otp_callback`
+for integration, and resumes a pending code step when called without credentials.
+Return `resend` from the callback to request another code. Wrong codes leave the
+pending server session available for another attempt. Use `login(..., request_otp=False)`
+only when you deliberately want the service's legacy manual-SMS workflow.
+
+`ok=True` can mean that the initial credential step succeeded. A completed login
+has `loggedIn=True` and `bankVerified=True`. Password-change requirements must be
+completed in the bank app. Device-verification, card PIN2 and digital-rial activation
+codes belong to different workflows.
+
+## Async client
+
+```python
+import asyncio
+from samanapi import AsyncClient
+
+async def main():
+    async with AsyncClient() as client:
+        print(await client.check_session())
+        print(await client.latest_transactions("123-456-0000001-2", limit=10))
+
+asyncio.run(main())
+```
+
+Every endpoint has the same name and parameters in `Client` and `AsyncClient`.
+`AsyncClient.sign_in` accepts synchronous or asynchronous callbacks. Default
+interactive callbacks run in a worker thread. Transaction iteration uses
+`for row in client.iter_transactions(...)` or `async for` with the async client.
+
+## History, details and exact search
+
+```python
+with Client() as client:
+    history = client.transactions(
+        "123-456-0000001-2", page=0, size=20,
+        details=True, is_withdrawal=False,
+        from_date=1700000000, to_date=1700086400,
+    )
+    result = client.find_transaction(
+        "000000000001", "123-456-0000001-2",
+        match_by="reference", pages=10, max_transactions=200,
+    )
+    if not result["found"]:
+        print(result["searchComplete"], result["stopReason"])
+```
+
+Pages start at **0**. Transaction dates are Unix **seconds**; merchant summary
+`from_date` is Unix **milliseconds**. Identifiers, tracking/reference numbers,
+cards, deposit numbers and IBANs stay strings, preserving leading zeros.
+Transaction IDs are encoded as one URL segment, including embedded slashes.
+
+`details=True` lets the server include full bank detail/receipt objects in each
+row's `detail`. Unknown fields are preserved. The SDK does not infer a sender's
+name or card number from free text. JSON null balances remain `None`, and absent
+fields remain absent; neither is converted to zero. Card and deposit balances
+are not added together.
+
+`iter_transactions(..., size=100, max_pages=10, details=False)` is bounded. It raises
+`PaginationError` when a page repeats or the budget runs out before the end of
+history. It does not silently claim that a bounded search covered the whole account.
+
+## Transfers and digital rial
+
+```python
+with Client() as client:
+    reasons = client.transfer_reasons()
+    owner = client.iban_owner("IR000000000000000000000000")  # synthetic, replace it
+    # Programmatic money movement is explicit; no confirmation dialog is inserted:
+    # receipt = client.transfer_iban(source, destination, amount_irr, reason_code)
+```
+
+Transfer amounts are positive integer **IRR**, capped at JavaScript's safe integer
+range. Card expiry is Jalali `YYYYMM`. `transfer_card` needs `cvv2`, `pin2`, and
+`expire_date`. The server encrypts these fields. PAYA takes a deposit as source
+and an IBAN as destination. Select `reason_code` from `transfer_reasons()`.
+The current service implements CARD, DEPOSIT and PAYA, not SATNA/POL submission.
+
+Digital rial has separate eligibility, SMS, activation, balance, transaction,
+charge, discharge, deactivation and contact methods. Wallet history IDs differ
+from deposit-history IDs. Activation currently supports CUSTOMER wallets.
+
+The SDK never retries or follows redirects automatically. On a timeout or a
+cancelled payment request, the operation may already have succeeded: inspect
+history before submitting another instruction. API-server renewal behavior is
+separate from the SDK; the companion server never automatically replays transfers.
+
+## Errors and response preservation
+
+```python
+from samanapi import Client, ApiError, TransportError
+
+try:
+    with Client() as client:
+        print(client.cards())
+except ApiError as exc:
+    print(exc.status_code, exc.code, exc.next_action)
+    # exc.payload contains the full response; inspect it only where appropriate.
+except TransportError as exc:
+    print(exc.request_may_have_succeeded)
+```
+
+Exception types include `AuthenticationError`, `DeviceVerificationRequired`,
+`PasswordChangeRequired`, `ValidationError`, `BankError`, `SmsDeliveryError`,
+`TransportError`, `ProtocolError` and `PaginationError`. HTTP errors preserve
+`payload`, `bank_status`, `auth`, `next_action`, `method` and `path`. Error string
+representations do not print server payloads or credentials. An HTTP 200 body
+containing an application `error` is not silently accepted.
+
+The default response limit is 20 MiB; larger responses raise `ProtocolError`
+rather than being truncated. Configure `max_response_bytes` explicitly if needed.
+`timeout` defaults to 120 seconds. Longer bounded searches may need a larger value.
+Custom HTTPX transports are supported for tests and advanced use; their own retry
+or security behavior is the caller's responsibility. `trust_env` defaults to false.
+
+## CLI
+
+```sh
+saman-api login
+saman-api status
+saman-api deposits
+saman-api balance
+saman-api transactions --deposit-number 123-456-0000001-2 --page 0 --size 20 --details false
+saman-api find-transaction 000000000001 --deposit-number 123-456-0000001-2 --match-by reference
+saman-api --help
+```
+
+The API key is read from `SAMAN_API_KEY`. `SAMAN_USER` and `SAMAN_PASS` may supply
+credentials to CLI login. All endpoint methods have hyphenated CLI commands;
+`--help` lists their arguments. Boolean arguments take `true` or `false`.
+Wallet filter lists are comma-separated. Use `python -m samanapi` as an
+alternative entry point. The CLI writes JSON results to stdout and errors to
+stderr; `--json-errors` gives structured errors and exit code 1. Cancellation
+uses exit code 130. Financial commands require `TRANSFER`, wallet activation
+`ACTIVATE`, and deactivation `DEACTIVATE`; noninteractive callers must pass the
+matching `--confirm` value. Required card secrets are prompted without echo
+when omitted. Use `import-har FILE` for a local private capture, never a public example.
+
+## API reference and development
+
+See [the complete method reference](docs/reference.md) and the
+[HTTP service documentation](https://apibank.heydari.workers.dev/saman/).
+`request("GET", "cards", query={...})` is available for future relative routes;
+absolute/cross-origin paths and traversal are rejected before any I/O.
+
+```sh
+pip install -e .
+python -m unittest discover -s tests -v
+python tools/generate_async.py
+python -m build
+python -m twine check dist/*
+```
+
+Tests use mock transports and a fake bank behind the real Node server. They do
+not send money or verify a current live bank session. The source distribution
+and wheel use explicit include rules and contain no sessions, captures or API keys.

saman_api-0.1.0/docs/publishing.md

@@ -0,0 +1,66 @@
+# Release guide
+
+Distribution: `saman-api`. Import: `samanapi`. Initial version: `0.1.0`.
+The package requires Python 3.10+ and a running Saman HTTP service 0.3+.
+The Node service itself is not shipped inside the wheel.
+
+## Verify locally
+
+From the Python package directory:
+
+```sh
+python -m pip install -e . build twine pip-audit ruff mypy
+python -m unittest discover -s tests -v
+ruff check src --select E9,F63,F7,F82
+mypy src/samanapi tests/typing_contract.py --check-untyped-defs --warn-unused-ignores
+python tools/generate_async.py
+python -m build
+python -m twine check dist/*
+```
+
+The build produces a wheel and source archive in `dist/`. Install the wheel in
+a fresh environment and run `saman-api --help`. The integration test requires
+the Node source and its dependencies; install them from the repository root first.
+Standalone SDK distributions skip that repository-only test, while mock transport
+tests remain runnable. Audit the runtime environment with `pip-audit` before release.
+
+Keep the version in `pyproject.toml`, `__init__.py` and the client's user-agent
+aligned; regenerate the async client after editing the sync implementation.
+Update CHANGELOG.md and docs/reference.md when changing public methods.
+Use a new version for every PyPI release; PyPI files cannot be overwritten.
+
+## Trusted Publishing
+
+The repository includes `.github/workflows/publish.yml`, triggered manually from
+the main branch. It tests the server and SDK, builds and checks distributions,
+then publishes with PyPI's short-lived OIDC identity. No PyPI password or token
+is stored in source. It does not run automatically on push.
+
+Before the first publication, replace the GitHub owner and repository placeholders
+with the repository you upload this source to. Then sign into your PyPI account, enable its required
+account security and create a pending Trusted Publisher:
+
+| Setting | Value |
+| --- | --- |
+| PyPI project | `saman-api` |
+| GitHub owner | `DevURANIUM` |
+| Repository | `saman-api` |
+| Workflow filename | `publish.yml` |
+| Environment | `pypi` |
+
+Create the `pypi` GitHub environment, restrict deployment to main, and configure
+required reviewers if desired. Then run the publish workflow for the reviewed
+commit. Name availability is not a reservation and must be checked again at release.
+
+For a first rehearsal, configure a separate publisher/environment on TestPyPI
+and set the publish action's repository-url to `https://test.pypi.org/legacy/`.
+
+See [PyPI's official Trusted Publishing guide](https://docs.pypi.org/trusted-publishers/using-a-publisher/).
+
+## Contents and privacy
+
+The wheel contains only the SDK, typing marker, package metadata and license.
+The source archive additionally includes tests, examples, documentation and the
+async generator. All examples use synthetic identifiers. Session directories,
+bank captures, environment files, local paths, credentials and private keys must
+never be added to either archive or the GitHub release.