chore: update @smscode/sdk (generated from the SMSCode monorepo)

Author: dzevs

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  build-test:
+  typescript-sdk:
     runs-on: ubuntu-latest
     defaults:
       run:
@@ -34,3 +34,27 @@ jobs:
       - run: bun run test
       - run: bun run lint
       - run: npm pack --dry-run
+
+  python-sdk:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    defaults:
+      run:
+        working-directory: packages/sdk-py
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --all-groups
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run mypy src tests
+      - run: uv run pytest
+      - run: uv run python ../../scripts/check-python-contract-fresh.py
+      - run: uv run python -m build
+      - run: uv run twine check --strict dist/*
+      - run: uv run pytest tests/test_package_install.py -q

README.md

@@ -5,6 +5,7 @@ Official client SDKs for the [SMSCode](https://smscode.gg) virtual-number API 
 ## Packages
 
 - [`@smscode/sdk`](packages/sdk-js) — TypeScript/JavaScript SDK. Install with `bun add @smscode/sdk` (or `npm i @smscode/sdk`).
+- [`smscode`](packages/sdk-py) — Python SDK. Install with `pip install smscode`.
 
 ## Documentation
 

docs/ai.md

@@ -1,6 +1,6 @@
 # SMSCode for AI Agents
 
-Compact integration guidance for coding agents building on the SMSCode virtual-number API. Pair this with the OpenAPI contract and the [`@smscode/sdk`](https://github.com/smscode-gg/sdks) TypeScript/JavaScript client.
+Compact integration guidance for coding agents building on the SMSCode virtual-number API. Pair this with the OpenAPI contract and the official SDKs in [`smscode-gg/sdks`](https://github.com/smscode-gg/sdks): `@smscode/sdk` for TypeScript/JavaScript and `smscode` for Python.
 
 - **OpenAPI contract (source of truth):** [`openapi.yaml`](https://smscode.gg/openapi.yaml) — hand-authored OpenAPI 3.1; every request/response shape lives here. Rendered for humans at <https://smscode.gg/docs>.
 - **Base URL:** `https://api.smscode.gg`
@@ -50,10 +50,18 @@ In the SDK each code maps to a typed subclass of `SmscodeError` (e.g. `RateLimit
 
 ## Install the SDK
 
+TypeScript/JavaScript:
+
 ```bash
 bun add @smscode/sdk    # or: npm i @smscode/sdk
 ```
 
+Python:
+
+```bash
+pip install smscode
+```
+
 ## Recipe: create → waitForOtp → finish (cancel only on no-OTP)
 
 ```ts
@@ -148,3 +156,50 @@ if (event.event === "order.otp_received") {
   console.log(event.data.otp_code);
 }
 ```
+
+## Python SDK recipe
+
+Python uses snake_case names but follows the same lifecycle and idempotency rules:
+
+```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 USD decimal string
+    "quantity": 1,
+}
+
+with client:
+    created = client.orders.create(body)
+    order_id = int(created.orders[0]["id"])
+
+    try:
+        otp = client.orders.wait_for_otp(order_id, timeout_ms=120_000)
+        # Submit otp.otp_code in your target app here.
+        client.orders.finish(order_id)
+    except (OtpTimeoutError, OrderTerminalError):
+        client.orders.cancel(order_id)
+```
+
+For resend flows, preserve the previous 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)
+```
+
+Verify Python webhook signatures with raw bytes:
+
+```py
+from smscode import parse_webhook_event, verify_webhook_signature
+
+if not verify_webhook_signature(raw_body, signature_header or "", secret):
+    return 401
+event = parse_webhook_event(raw_body)
+```

packages/sdk-py/.gitignore

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

packages/sdk-py/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.

packages/sdk-py/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

packages/sdk-py/examples/async_quickstart.py

@@ -0,0 +1,23 @@
+import os
+
+from smscode import AsyncSmscodeClient, OrderTerminalError, OtpTimeoutError
+
+
+async def main() -> None:
+    body = {
+        "catalog_product_id": int(os.environ["SMSCODE_CATALOG_PRODUCT_ID"]),
+        "max_price": "0.50",
+        "quantity": 1,
+    }
+
+    async with AsyncSmscodeClient(token=os.environ["SMSCODE_TOKEN"]) as client:
+        created = await client.orders.create(body)
+        order_id = int(created.orders[0]["id"])
+
+        try:
+            otp = await 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.
+            await client.orders.finish(order_id)
+        except (OtpTimeoutError, OrderTerminalError):
+            await client.orders.cancel(order_id)

packages/sdk-py/examples/quickstart.py

@@ -0,0 +1,27 @@
+import os
+
+from smscode import OrderTerminalError, OtpTimeoutError, SmscodeClient
+
+
+def main() -> None:
+    body = {
+        "catalog_product_id": int(os.environ["SMSCODE_CATALOG_PRODUCT_ID"]),
+        "max_price": "0.50",
+        "quantity": 1,
+    }
+
+    with SmscodeClient(token=os.environ["SMSCODE_TOKEN"]) as client:
+        created = client.orders.create(body)
+        order_id = int(created.orders[0]["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):
+            client.orders.cancel(order_id)
+
+
+if __name__ == "__main__":
+    main()

packages/sdk-py/examples/smoke.py

@@ -0,0 +1,19 @@
+from smscode import (
+    AsyncSmscodeClient,
+    SmscodeClient,
+    is_webhook_event,
+    parse_webhook_event,
+    verify_webhook_signature,
+)
+
+
+def main() -> None:
+    assert SmscodeClient.__name__ == "SmscodeClient"
+    assert AsyncSmscodeClient.__name__ == "AsyncSmscodeClient"
+    assert callable(verify_webhook_signature)
+    event = parse_webhook_event('{"event":"webhook.test","data":{"message":"ok"}}')
+    assert is_webhook_event(event)
+
+
+if __name__ == "__main__":
+    main()

packages/sdk-py/examples/webhook.py

@@ -0,0 +1,12 @@
+from smscode import parse_webhook_event, verify_webhook_signature
+
+
+def handle_webhook(raw_body: bytes, signature_header: str | None, secret: str) -> tuple[int, str]:
+    if not verify_webhook_signature(raw_body, signature_header or "", secret):
+        return 401, "bad signature"
+
+    event = parse_webhook_event(raw_body)
+    if event["event"] == "order.otp_received":
+        otp_code = event["data"].get("otp_code")
+        print("OTP:", otp_code)
+    return 204, "ok"