Skip to content

feat!: Python SDK 3.0.0 on the OnlineSim API v2 contract - #19

Merged
s00d merged 2 commits into
masterfrom
feat/sdk-v2
Nov 19, 2026
Merged

s00d merged 2 commits into
masterfrom
feat/sdk-v2

Conversation

@s00d

@s00d s00d commented Nov 19, 2026

Copy link
Copy Markdown
Owner

Rewrite to the OnlineSim API v2 contract (OpenAPI generated from the backend, s00d/OnlineSIM-Backend#362). The JS SDK is the reference; all SDKs share one surface: numbers, rent, user (webhooks), free.list, waitCode, parseWebhook.

Changes (3.0.0)

A rewrite. The public API changed; see the docs.

Removed

  • The proxy API (ProxyService, Driver.proxy(), deprecated by the backend).
  • numbers.repeat (getNumRepeat), numbers.service (getService), numbers.service_number (getServiceNumber): no backend route.
  • rent.port_reload: deprecated no-op on the backend.
  • user.create_empty (pay/createEmpty).
  • The old free-number methods (getFreeCountryList / getFreePhoneList / getFreeMessageList): the backend returns empty data; use free.list.
  • Driver, API and the per-service classes (NumbersService, RentNumbersService, UserService, FreeNumbersService), RequestException.
  • Runtime dependencies httpx, pydantic, dacite; requirements.txt, pytest.ini, deploy.sh, DEPLOYMENT.md, example/, the live-API tests.

Changed

  • One client: OnlineSim(api_key, *, base_url, lang, dev_id, timeout, transport); sections are attributes (client.numbers, client.rent, client.user, client.free).
  • The API key is sent as Authorization: Bearer <key>, never in the query string. base_url is the full API base (https://onlinesim.host/api/).
  • Errors: OnlineSimError → ApiError (code, message), NoNumberError (subclass of ApiError), TransportError (status, body), TimeoutError (also a built-in TimeoutError).
  • numbers.wait_code(tzid, *, interval, timeout, keep_open, full_message, since, sleep, clock), times in seconds.
  • numbers.get / get_with_number take reject= as a keyword; get_with_number returns {tzid, number, country, time, service}.
  • numbers.state(*, message_to_code, order_by, msg_list) / state_one(tzid, ...) take booleans; order_by is lowercase.
  • rent.get(country, days, extension): extension defaults to True (the server default; False makes the rent non-extendable for good).
  • Results are plain dicts typed as TypedDicts; money parsed to numbers (user.balance()["balance"], rent sum).
  • Python ≥ 3.9, zero runtime dependencies (stdlib urllib), py.typed, hatchling build, __version__ from the installed metadata.

Fixed

  • lang was also sent as dev_id; dev_id is sent only when set.
  • getService was requested as /apigetService; old URL building is gone.
  • NO_NUMBER / NO_NUMBER_FOR_FORWARD are mapped to NoNumberError; error messages come from the server or a fallback table.
  • response is stripped from successful results.
  • getNum was sent as POST; every call except the profile webhook update is a GET with query parameters.
  • Booleans were sent as true/false; now 1/0. reject is a comma list; unset parameters are omitted.
  • wait_code polled with a broken counter; it now uses a deadline with an injectable clock.
  • An HTTP 456 wrong-key answer is an ApiError; non-JSON answers and network errors raise TransportError.
  • state() returns [] instead of raising when there are no operations.
  • Empty maps sent by PHP as [] (rent extend, paylist, free numbers, country services) are returned as {}.
  • Rent requests always send pagination=0, so messages is a flat list.
  • pytest.ini used the [tool:pytest] header and was ignored; .venv was not git-ignored; py.typed was declared but missing.

Added

  • user.set_webhook_url(url), user.clear_webhook_url(), user.webhook_logs(page).
  • parse_webhook(payload) for inbound receiving_sms / rent_sms webhooks.
  • Injectable transport (HttpRequest → HttpResponse) and per-request timeout.
  • Offline test suite (fake transport, fake clock), docs examples type-checked with mypy, opt-in integration test, CI on Python 3.9–3.13 with ruff and mypy.
  • New documentation site (Nuxt Content).

Checked locally

  • lint/format, offline unit tests (fake transport), package build, Nuxt docs build (docs/)
  • integration on the local backend (on.test): read-only calls and the number lifecycle on the provider-free test driver

Not published, no tag. Release steps: tag after merge, publish, gh release create, enable GitHub Pages (gh-pages) for the docs.

🤖 Generated with Claude Code

s00d and others added 2 commits November 19, 2026 21:09
Rewrite against the OpenAPI spec generated from the backend and the shared
SDK conventions (the JS SDK is the reference):
- one request function: body checked before status (456 wrong key → ApiError),
  NO_NUMBER → NoNumber error, validation objects → VALIDATION_ERROR
- numbers, rent, user (webhook URL set/clear/logs), free.list, waitCode with
  injectable clock/sleep, standalone webhook parser
- removed: proxy API, onlineProxy, repeat/service/serviceNumber, createEmpty,
  portReload, old free-number endpoints
- offline tests with a fake transport, opt-in integration test (on.test)
- Nuxt docs site in docs/, CI and docs workflows, CHANGELOG entry

BREAKING CHANGE: new major version, see CHANGELOG.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
setup-python has no 3.9 build for the newest ubuntu-latest image.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@s00d
s00d merged commit 5ff7540 into master Nov 19, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant