Live API only. Purchases spend real balance.
No keys are included. Purchases require explicit confirmation. Never automatically create a replacement order after a timeout.
Download sim7.mjs ↓1. Download the client and configure the environment
Use Node.js 22.13 or later with node:sqlite. Download sim7.mjs; no third-party packages are required. Create a live Sim7 key with account:read, catalog:read, orders:read and orders:write. webhooks:write is needed only to configure notifications. Keep the key out of browsers, URLs, repositories and logs.
Set SIM7_API_KEY through your protected process environment and SIM7_STATE_FILE to a private SQLite file on persistent storage. Never place it under public, in a temporary directory or in an ephemeral container layer. It holds original intents, purchase receipts and webhook events. Restrict access to the database and backups.
The commands below use sh/bash. Configure the variables in your environment first; use PowerShell's $env:NAME syntax on Windows. SIM7_BUSINESS_ID must come from your order system and stay unchanged on retries. Start with read-only balance and catalog requests, which do not create purchases.
node sim7.mjs balance
node sim7.mjs prices --service openai --country usa2. Purchase once with persistent idempotency
Use service, country and operator IDs from the API catalog. max_price is in US dollars at your API key's applicable price, not rubles. It is a purchase ceiling, not a guaranteed price. Review stock and price before committing. The command requires --confirm because it spends real balance.
Before POST, the client durably records business_id and the exact payload in SQLite. A restart after a network error reuses the same Idempotency-Key. If the receipt is already stored, no purchase request is sent. Changing the payload for an existing business_id is blocked locally. Never delete state or invent a replacement ID to check an uncertain result.
The client obtains stable account_id from /account and binds the intent to a key fingerprint. Changing keys while an old purchase is unresolved blocks resubmission. Unresolved intents older than six days also require reconciliation: server idempotency retention is not indefinite.
node sim7.mjs buy --business-id "$SIM7_BUSINESS_ID" --service openai --country usa --operator any --max-price 0.50 --confirm3. Observe the first and subsequent SMS
A purchase returns order_id, the number, price and expiry. Store order_id on your customer order; neither the phone number nor your own business ID replaces it. Pass it to watch: messages[] is read every five seconds and status=code_received remains active.
Console output defaults to status and new-message counts, without SMS text. --show-messages explicitly prints content and should only be used in a private console, never public CI logs. The library watch interface yields order and new_messages so your application can show them to the authenticated owner.
Request a second code in the target service while the order is active. There is no universal Sim7 method to make another platform send an SMS. A local observation timeout does not finish or cancel the order. Receiving a code also never triggers finish; that is a separate deliberate action that may end further delivery.
node sim7.mjs watch --order-id "$SIM7_ORDER_ID" --seconds 1200
# Private console only:
node sim7.mjs watch --order-id "$SIM7_ORDER_ID" --seconds 1200 --show-messages
# Explicitly finish only when the user is done:
node sim7.mjs finish --order-id "$SIM7_ORDER_ID" --confirmUsing the Node.js library
The ES module exports Client, State, verifyWebhook and webhookServer. Client uses fetch with AbortSignal and redirects disabled; watch is an async iterator. node:sqlite performs short synchronous local operations, not heavy public-server analytics. Use a shared business journal instead of per-container SQLite when scaling across instances.
The following snippet performs a real-balance purchase. Run it only after reviewing the price and setting persistent SIM7_BUSINESS_ID. Replace the count output with owner-authorized delivery of new_messages. Keep codes out of shared logs and never call finish inside the first-message loop.
import { Client, State } from './sim7.mjs';
const state = new State(process.env.SIM7_STATE_FILE);
try {
const client = new Client(process.env.SIM7_API_KEY, state);
const order = await client.purchase(process.env.SIM7_BUSINESS_ID, {
service: 'openai', country: 'usa', max_price: 0.50,
});
for await (const update of client.watch(order.order_id)) {
console.log(update.order.status, update.new_messages.length);
}
} finally {
state.close();
}4. Receive a signed webhook
The same file includes a POST /webhooks/sim7 receiver bound only to 127.0.0.1. Place your own HTTPS reverse proxy in front and block external access to the private port. Register your public HTTPS URL using PUT /api/v1/webhook with a separate Idempotency-Key or dashboard tools. Securely retain the one-time signing secret.
SIM7_WEBHOOK_SECRETS is a JSON map of version numbers to issued whsec secrets. Retain required previous versions for queued deliveries during rotation. The receiver checks the secret version, timestamp within five minutes, and HMAC-SHA256 over timestamp, a dot and the raw body bytes. Never reserialize parsed JSON before verification.
It then checks signed event identity and type, and inserts into the SQLite inbox with a unique delivery ID. Duplicate delivery returns 200 without inserting again. A failed database write returns 503 so delivery may be retried. Never acknowledge an event before it is durably recorded.
node sim7.mjs webhook --port 80805. Connect fulfillment and accounting
The receiver persists events but never credits money or fulfills goods automatically. Your worker reads inbox WHERE processed=0. Updating your order, deduplicating fulfillment and setting processed=1 must share one business transaction. For external delivery use a transactional outbox and a stable operation ID. Never mark an event processed before attempting an irreversible side effect.
Authorize order_id against the customer mapping in your database, not a visitor's URL parameter. Webhooks may repeat or arrive out of order; fetch GET /orders/{id} for authoritative current state when needed. Keep transition history and prevent old events from reopening terminal orders. completed, cancelled, banned and expired are terminal; code_received is not.
The receiver does not magically provide exactly-once external side effects: your transaction and destination idempotency determine that. Safe purchases also require retained state and the original key. For multiple servers replace local SQLite with a shared transactional database using equivalent uniqueness constraints; never create independent histories per instance.
Errors: when to stop
Network failures, 5xx, idempotency_in_progress and 429 use bounded retries with the same key. Retry-After is respected; an excessive or unsupported delay stops retries. idempotency_conflict, price_changed, insufficient_funds and validation errors must never trigger an automatic replacement purchase. Resolve the original outcome first.
Unknown does not mean unpurchased. Preserve business_id, any available order_id and timestamps, then reconcile your account history or contact support. Rotating keys, deleting SQLite or raising max_price is not a way to inspect an old outcome. A separate new purchase must be a separate customer-confirmed decision.

