smscode 1.0.0__tar.gz

smscode-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+dist/
+build/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+__pycache__/
+*.pyc

smscode-1.0.0/LICENSE

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

smscode-1.0.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: smscode
+Version: 1.0.0
+Summary: Official Python SDK for the SMSCode virtual number API.
+Project-URL: Homepage, https://smscode.gg
+Project-URL: Documentation, https://smscode.gg/docs/ai.md
+Project-URL: Repository, https://github.com/smscode-gg/sdks
+Project-URL: Issues, https://github.com/smscode-gg/sdks/issues
+Author-email: SMSCode <dev@smscode.gg>
+License: MIT
+License-File: LICENSE
+Keywords: 2fa,api-client,online-sms,otp,phone-verification,python,receive-sms-online,sdk,sms,sms-otp,sms-verification,smscode,temporary-phone-number,virtual-number,virtual-phone-number
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Description-Content-Type: text/markdown
+
+# smscode
+
+Official Python SDK for the SMSCode virtual-number API.
+
+Use it to rent temporary phone numbers, receive SMS OTP verification codes, and
+manage order lifecycle from Python services, bots, and automations.
+
+## Install
+
+```bash
+pip install smscode
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+`SmscodeClient` uses the USD-native `/v2` API by default. Money values are typed
+objects with the exact IDR ledger amount preserved as `canonical_amount`.
+
+```py
+import os
+
+from smscode import OtpTimeoutError, OrderTerminalError, SmscodeClient
+
+client = SmscodeClient(token=os.environ["SMSCODE_TOKEN"])
+
+body = {
+    "catalog_product_id": int(os.environ["SMSCODE_CATALOG_PRODUCT_ID"]),
+    "max_price": "0.50",  # /v2 uses a USD decimal string, never a float
+    "quantity": 1,
+}
+
+with client:
+    created = client.orders.create(body)
+    order = created.orders[0]
+    order_id = int(order["id"])
+
+    try:
+        otp = client.orders.wait_for_otp(order_id, timeout_ms=120_000)
+        print("OTP:", otp.otp_code)
+        # Submit otp.otp_code in your target app here.
+        client.orders.finish(order_id)
+    except (OtpTimeoutError, OrderTerminalError):
+        # No OTP evidence arrived. Cancel remains available only in that case.
+        client.orders.cancel(order_id)
+```
+
+## Async client
+
+The async client has the same surface and uses `httpx.AsyncClient` internally.
+
+```py
+import os
+
+from smscode import AsyncSmscodeClient
+
+
+async def main() -> None:
+    async with AsyncSmscodeClient(token=os.environ["SMSCODE_TOKEN"]) as client:
+        balance = await client.balance.get()
+        print(balance.balance.amount, balance.balance.currency)
+```
+
+## Resend and wait for a new OTP
+
+`finish` does not require a new OTP after resend; the order is finishable once it
+has OTP evidence. If your integration needs to wait for a different post-resend
+code, pass the previous code as `after_code`.
+
+```py
+first = client.orders.wait_for_otp(order_id)
+
+client.orders.resend(order_id)
+
+second = client.orders.wait_for_otp(
+    order_id,
+    after_code=first.otp_code,
+    timeout_ms=120_000,
+)
+
+print("new OTP:", second.otp_code)
+# Submit second.otp_code in your target app here, then finish.
+client.orders.finish(order_id)
+```
+
+If the provider sends the same digits again, code-based polling cannot
+distinguish it from the previous OTP.
+
+## Idempotent order create
+
+Order create is money-sensitive. The SDK resolves an idempotency key before the
+request, sends it as `idempotency-key`, and attaches it to create errors.
+
+```py
+from smscode import SmscodeError
+
+try:
+    created = client.orders.create(body)
+except SmscodeError as err:
+    if err.idempotency_key is None:
+        raise
+    # Retry the exact same body with the same key. Never mint a fresh key for
+    # the same attempted create.
+    created = client.orders.create(body, idempotency_key=err.idempotency_key)
+```
+
+## Webhooks
+
+Verify webhook signatures against the raw request body before parsing JSON.
+
+```py
+from smscode import parse_webhook_event, verify_webhook_signature
+
+
+def handle_webhook(raw_body: bytes, signature_header: str | None, secret: str) -> int:
+    if not verify_webhook_signature(raw_body, signature_header or "", secret):
+        return 401
+
+    event = parse_webhook_event(raw_body)
+    if event["event"] == "order.otp_received":
+        print(event["data"]["otp_code"])
+    return 204
+```
+
+## `/v1` namespace
+
+Use `.v1` only when you intentionally want legacy IDR-only shapes.
+
+```py
+with SmscodeClient(token=os.environ["SMSCODE_TOKEN"]) as client:
+    balance_v2 = client.balance.get()
+    balance_v1 = client.v1.balance.get()
+```
+
+## Error handling
+
+Every API error is a typed `SmscodeError` subclass. Branch on the class or
+`err.code`, not on `err.message`. `RateLimitError` and retryable server errors
+carry `retry_after_seconds` when the API sends `Retry-After`.
+
+## License
+
+MIT

smscode-1.0.0/README.md

@@ -0,0 +1,144 @@
+# smscode
+
+Official Python SDK for the SMSCode virtual-number API.
+
+Use it to rent temporary phone numbers, receive SMS OTP verification codes, and
+manage order lifecycle from Python services, bots, and automations.
+
+## Install
+
+```bash
+pip install smscode
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+`SmscodeClient` uses the USD-native `/v2` API by default. Money values are typed
+objects with the exact IDR ledger amount preserved as `canonical_amount`.
+
+```py
+import os
+
+from smscode import OtpTimeoutError, OrderTerminalError, SmscodeClient
+
+client = SmscodeClient(token=os.environ["SMSCODE_TOKEN"])
+
+body = {
+    "catalog_product_id": int(os.environ["SMSCODE_CATALOG_PRODUCT_ID"]),
+    "max_price": "0.50",  # /v2 uses a USD decimal string, never a float
+    "quantity": 1,
+}
+
+with client:
+    created = client.orders.create(body)
+    order = created.orders[0]
+    order_id = int(order["id"])
+
+    try:
+        otp = client.orders.wait_for_otp(order_id, timeout_ms=120_000)
+        print("OTP:", otp.otp_code)
+        # Submit otp.otp_code in your target app here.
+        client.orders.finish(order_id)
+    except (OtpTimeoutError, OrderTerminalError):
+        # No OTP evidence arrived. Cancel remains available only in that case.
+        client.orders.cancel(order_id)
+```
+
+## Async client
+
+The async client has the same surface and uses `httpx.AsyncClient` internally.
+
+```py
+import os
+
+from smscode import AsyncSmscodeClient
+
+
+async def main() -> None:
+    async with AsyncSmscodeClient(token=os.environ["SMSCODE_TOKEN"]) as client:
+        balance = await client.balance.get()
+        print(balance.balance.amount, balance.balance.currency)
+```
+
+## Resend and wait for a new OTP
+
+`finish` does not require a new OTP after resend; the order is finishable once it
+has OTP evidence. If your integration needs to wait for a different post-resend
+code, pass the previous code as `after_code`.
+
+```py
+first = client.orders.wait_for_otp(order_id)
+
+client.orders.resend(order_id)
+
+second = client.orders.wait_for_otp(
+    order_id,
+    after_code=first.otp_code,
+    timeout_ms=120_000,
+)
+
+print("new OTP:", second.otp_code)
+# Submit second.otp_code in your target app here, then finish.
+client.orders.finish(order_id)
+```
+
+If the provider sends the same digits again, code-based polling cannot
+distinguish it from the previous OTP.
+
+## Idempotent order create
+
+Order create is money-sensitive. The SDK resolves an idempotency key before the
+request, sends it as `idempotency-key`, and attaches it to create errors.
+
+```py
+from smscode import SmscodeError
+
+try:
+    created = client.orders.create(body)
+except SmscodeError as err:
+    if err.idempotency_key is None:
+        raise
+    # Retry the exact same body with the same key. Never mint a fresh key for
+    # the same attempted create.
+    created = client.orders.create(body, idempotency_key=err.idempotency_key)
+```
+
+## Webhooks
+
+Verify webhook signatures against the raw request body before parsing JSON.
+
+```py
+from smscode import parse_webhook_event, verify_webhook_signature
+
+
+def handle_webhook(raw_body: bytes, signature_header: str | None, secret: str) -> int:
+    if not verify_webhook_signature(raw_body, signature_header or "", secret):
+        return 401
+
+    event = parse_webhook_event(raw_body)
+    if event["event"] == "order.otp_received":
+        print(event["data"]["otp_code"])
+    return 204
+```
+
+## `/v1` namespace
+
+Use `.v1` only when you intentionally want legacy IDR-only shapes.
+
+```py
+with SmscodeClient(token=os.environ["SMSCODE_TOKEN"]) as client:
+    balance_v2 = client.balance.get()
+    balance_v1 = client.v1.balance.get()
+```
+
+## Error handling
+
+Every API error is a typed `SmscodeError` subclass. Branch on the class or
+`err.code`, not on `err.message`. `RateLimitError` and retryable server errors
+carry `retry_after_seconds` when the API sends `Retry-After`.
+
+## License
+
+MIT

smscode-1.0.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "smscode"
+version = "1.0.0"
+description = "Official Python SDK for the SMSCode virtual number API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "SMSCode", email = "dev@smscode.gg" }]
+keywords = [
+  "smscode",
+  "sms",
+  "otp",
+  "virtual-number",
+  "phone-verification",
+  "2fa",
+  "sms-verification",
+  "api-client",
+  "sdk",
+  "python",
+  "receive-sms-online",
+  "sms-otp",
+  "temporary-phone-number",
+  "virtual-phone-number",
+  "online-sms",
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.urls]
+Homepage = "https://smscode.gg"
+Documentation = "https://smscode.gg/docs/ai.md"
+Repository = "https://github.com/smscode-gg/sdks"
+Issues = "https://github.com/smscode-gg/sdks/issues"
+
+[dependency-groups]
+test = ["pytest>=8", "pytest-asyncio>=0.23", "respx>=0.21", "pyyaml>=6"]
+lint = ["ruff>=0.8"]
+type = ["mypy>=1.11"]
+build = ["build>=1.2", "twine>=5"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/smscode"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src/smscode",
+  "/tests",
+  "/LICENSE",
+  "/README.md",
+  "/pyproject.toml",
+  "/uv.lock",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["smscode"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

smscode-1.0.0/src/smscode/__init__.py

@@ -0,0 +1,153 @@
+from importlib import metadata
+
+from smscode.async_client import AsyncSmscodeClient
+from smscode.client import SmscodeClient
+from smscode.errors import (
+    CancelTooEarlyError,
+    ConflictError,
+    ForbiddenError,
+    FxRateUnavailableError,
+    IdempotencyKeyReuseError,
+    InsufficientBalanceError,
+    InternalError,
+    InvalidMoneyError,
+    InvalidResponseError,
+    NetworkError,
+    NoOfferAvailableError,
+    NotFoundError,
+    OrderTerminalError,
+    OtpTimeoutError,
+    PayloadTooLargeError,
+    ProviderError,
+    RateLimitError,
+    RequestCancelledError,
+    RequestInProgressError,
+    ServiceUnavailableError,
+    SmscodeError,
+    TempBannedError,
+    TimeoutError,
+    UnauthorizedError,
+    ValidationError,
+    map_error,
+)
+from smscode.idempotency import (
+    IDEMPOTENCY_KEY_PATTERN,
+    is_valid_idempotency_key,
+    resolve_idempotency_key,
+)
+from smscode.models import (
+    BalanceV1,
+    BalanceV2,
+    CancelResult,
+    CancelResultV2,
+    Country,
+    CreatedOrder,
+    CreateOrderResult,
+    CreateOrderResultV1,
+    CreateOrderResultV2,
+    ExchangeRate,
+    FinishResult,
+    Order,
+    OrderCapabilities,
+    OrdersList,
+    OrdersListV2,
+    Product,
+    ProductsPage,
+    ProductsPageV1,
+    ProductsPageV2,
+    ProductV2,
+    ResendResult,
+    Service,
+    V2Fx,
+    WebhookConfig,
+    WebhookTestResult,
+)
+from smscode.money import Money, parse_money
+from smscode.retry import RetryPolicy, async_with_retry, with_retry
+from smscode.types import ApiResult, RequestOptions
+from smscode.wait import OtpResult, async_wait_for_otp, wait_for_otp
+from smscode.webhook import (
+    WebhookEvent,
+    is_webhook_event,
+    parse_webhook_event,
+    verify_webhook_signature,
+)
+
+VERSION = metadata.version("smscode")
+__version__ = VERSION
+
+
+__all__ = [
+    "IDEMPOTENCY_KEY_PATTERN",
+    "VERSION",
+    "ApiResult",
+    "AsyncSmscodeClient",
+    "BalanceV1",
+    "BalanceV2",
+    "CancelResult",
+    "CancelResultV2",
+    "CancelTooEarlyError",
+    "ConflictError",
+    "Country",
+    "CreateOrderResult",
+    "CreateOrderResultV1",
+    "CreateOrderResultV2",
+    "CreatedOrder",
+    "ExchangeRate",
+    "FinishResult",
+    "ForbiddenError",
+    "FxRateUnavailableError",
+    "IdempotencyKeyReuseError",
+    "InsufficientBalanceError",
+    "InternalError",
+    "InvalidMoneyError",
+    "InvalidResponseError",
+    "Money",
+    "NetworkError",
+    "NoOfferAvailableError",
+    "NotFoundError",
+    "Order",
+    "OrderCapabilities",
+    "OrderTerminalError",
+    "OrdersList",
+    "OrdersListV2",
+    "OtpResult",
+    "OtpTimeoutError",
+    "PayloadTooLargeError",
+    "Product",
+    "ProductV2",
+    "ProductsPage",
+    "ProductsPageV1",
+    "ProductsPageV2",
+    "ProviderError",
+    "RateLimitError",
+    "RequestCancelledError",
+    "RequestInProgressError",
+    "RequestOptions",
+    "ResendResult",
+    "RetryPolicy",
+    "Service",
+    "ServiceUnavailableError",
+    "SmscodeClient",
+    "SmscodeError",
+    "TempBannedError",
+    "TimeoutError",
+    "UnauthorizedError",
+    "V2Fx",
+    "ValidationError",
+    "WebhookConfig",
+    "WebhookEvent",
+    "WebhookTestResult",
+    "__version__",
+    "async_wait_for_otp",
+    "async_with_retry",
+    "is_valid_idempotency_key",
+    "is_webhook_event",
+    "map_error",
+    "parse_money",
+    "parse_webhook_event",
+    "resolve_idempotency_key",
+    "verify_webhook_signature",
+    "wait_for_otp",
+    "with_retry",
+]

smscode-1.0.0/src/smscode/_async_transport.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from smscode._decode import decode_response, retry_after_from_error
+from smscode._transport import DEFAULT_BASE_URL, build_url, clean_params, is_retryable
+from smscode.errors import NetworkError, TimeoutError
+from smscode.retry import RetryPolicy, async_with_retry
+from smscode.types import ApiResult, HttpMethod, QueryValue
+
+
+class AsyncTransport:
+    def __init__(
+        self,
+        *,
+        token: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_ms: int = 0,
+        max_retries: int = 0,
+        client: httpx.AsyncClient | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not token:
+            raise TypeError("AsyncSmscodeClient requires a token.")
+        if client is not None and transport is not None:
+            raise TypeError("Pass either client or transport, not both.")
+        self._token = token
+        self._base_url = base_url
+        self._max_retries = max(0, max_retries)
+        self._owns_client = client is None
+        timeout = None if timeout_ms <= 0 else timeout_ms / 1000
+        self._client = client or httpx.AsyncClient(timeout=timeout, transport=transport)
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def request(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        params: Mapping[str, QueryValue] | None = None,
+        json: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+        retry: int | None = None,
+    ) -> ApiResult[Any]:
+        max_retries = self._max_retries if retry is None else max(0, retry)
+        policy = RetryPolicy(
+            max_retries=max_retries,
+            retry_on=is_retryable,
+            retry_after=retry_after_from_error,
+        )
+        return await async_with_retry(
+            lambda: self._attempt(method, path, params=params, json=json, headers=headers),
+            policy,
+        )
+
+    async def _attempt(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        params: Mapping[str, QueryValue] | None,
+        json: Any | None,
+        headers: Mapping[str, str] | None,
+    ) -> ApiResult[Any]:
+        request_headers = {
+            "Authorization": f"Bearer {self._token}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        if headers is not None:
+            request_headers.update(headers)
+        try:
+            response = await self._client.request(
+                method,
+                build_url(self._base_url, path),
+                params=clean_params(params),
+                json=json,
+                headers=request_headers,
+            )
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(str(exc) or "SMSCode request timed out") from exc
+        except httpx.RequestError as exc:
+            raise NetworkError(str(exc) or "SMSCode network request failed") from exc
+        return decode_response(response)