onlinesim-swift-api

Swift client for the OnlineSim API — SMS numbers, rent, account and free numbers. async/await, Sendable, zero dependencies.

Install

Swift 5.9 or newer; macOS 12, iOS 15, tvOS 15, watchOS 8 or Linux. The client uses URLSession and has no dependencies. Add the package with Swift Package Manager:

// Package.swift
dependencies: [
    .package(url: "https://github.com/s00d/onlinesim-swift-api.git", from: "1.0.0"),
],
targets: [
    .target(name: "MyApp", dependencies: [.product(name: "OnlineSim", package: "onlinesim-swift-api")]),
]

In Xcode: File → Add Package Dependencies…, enter https://github.com/s00d/onlinesim-swift-api.git, add the OnlineSim library.

Quick start

Check the balance, order a number, wait for the SMS code.

import OnlineSim

let client = OnlineSimClient(apiKey: "your-api-key")

let balance = try await client.user.balance()
print("available: \(balance.balance - max(balance.zbalance, 0)) USD")

let order = try await client.numbers.getWithNumber("google", country: 44)
print("enter \(order.number) in the app")

// Polls every 5 s for up to 10 min, then closes the operation.
let code = try await client.numbers.waitCode(order.tzid)
print("code: \(code)")

Client options

import OnlineSim

let client = OnlineSimClient(
    apiKey: "your-api-key",
    lang: "en",
    timeout: 15
)
ParameterTypeDefaultDescription
apiKeyString?nilSent as Authorization: Bearer <apiKey>, never in the URL. Not needed for tariffs and free numbers.
baseURLURLhttps://onlinesim.host/api/API base; trailing slash optional.
langString"en"Language of server texts (lang query parameter).
devIDString?nilPartner developer id (dev_id), sent only when set.
timeoutTimeInterval30Per-request timeout, seconds.
transportany TransportURLSessionTransport()Sends the HTTP requests: your own URLSession (proxy, custom TLS), or a fake in tests.

OnlineSimClient is an immutable Sendable struct: create it once and share it between tasks. Sections: client.numbers, client.rent, client.user, client.free. Webhook bodies are parsed by the standalone parseWebhook.

Models are Codable, Sendable and Hashable structs with Swift names (webhookURL, guardIntervalRemainingSeconds). Server quirks are normalised: money that arrives as a decimal string (balance, rent sum in rent.state) becomes a Double, maps that arrive as an empty PHP array [] become empty dictionaries (paymentHistory().paylist sent as a JSON array keeps its items under the keys "0", "1"…), and country codes and rent days are Int keys.

Transport

Implement Transport to send the requests yourself:

public protocol Transport: Sendable {
    func send(_ request: TransportRequest) async throws -> TransportResponse
}

TransportRequest carries method, url, headers, body and timeout; return every HTTP status as a TransportResponse(status:body:) and throw only when no response arrived (URLError(.timedOut) is reported as a request timeout).

import Foundation
import OnlineSim

let configuration = URLSessionConfiguration.ephemeral
configuration.connectionProxyDictionary = [:] // your proxy settings
let client = OnlineSimClient(
    apiKey: "your-api-key",
    transport: URLSessionTransport(session: URLSession(configuration: configuration))
)

Error handling

Every error is an OnlineSimError:

CaseWhen
.api(code:message:)The API answered with an error code (also a wrong key, HTTP 456, and the rate limit, HTTP 429 TRY_AGAIN_LATER).
.noNumber(code:message:)NO_NUMBER: no number right now. An API error too.
.transport(message:status:body:)Network error, request timeout, or a body that is not the expected JSON. status is nil without a response, body holds the first 500 characters.
.waitTimeout(tzid:timeout:)waitCode got no code within its timeout.
.invalidPayload(message:)parseWebhook got input that is not a JSON object.

error.code is the API code for .api and .noNumber (nil otherwise); error.message is readable text for every case.

import OnlineSim

do {
    _ = try await client.numbers.get("google", country: 44)
} catch OnlineSimError.noNumber {
    // try another country or later
} catch let error as OnlineSimError {
    switch error {
    case .api(let code, let message): print(code, message) // e.g. WARNING_LOW_BALANCE
    case .transport(_, let status, let body): print("network", status ?? 0, body)
    default: throw error
    }
}

message is the server's text when it sends one, otherwise a short English description of the code (OnlineSimError.messages), otherwise the code itself. Profile validation failures become .api with code VALIDATION_ERROR.