smspva-sdk 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

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

package/METHODS.md

@@ -0,0 +1,76 @@
+# SDK method index
+
+All six packages cover these same 56 methods. Both Python clients use the Python names. PHP and Java use the JavaScript camelCase method names, with their own resource access syntax. Go capitalizes the first letter (for example, `GetBalance`); C# also appends `Async` (`GetBalanceAsync`). See each package README for request types and working usage. Parameters retain their API spelling.
+
+## activation
+
+| Python (sync and async) | JavaScript / TypeScript | HTTP |
+| --- | --- | --- |
+| `client.activation.get_balance` | `client.activation.getBalance` | `GET /activation/balance` |
+| `client.activation.get_user_info` | `client.activation.getUserInfo` | `GET /activation/userinfo` |
+| `client.activation.get_operators` | `client.activation.getOperators` | `GET /activation/operators/{country}` |
+| `client.activation.get_conversions` | `client.activation.getConversions` | `GET /activation/conversions/{service}` |
+| `client.activation.get_message_type_settings` | `client.activation.getMessageTypeSettings` | `GET /activation/countryservicesettings` |
+| `client.activation.get_all_number_counts` | `client.activation.getAllNumberCounts` | `GET /activation/countnumbers` |
+| `client.activation.get_country_number_counts` | `client.activation.getCountryNumberCounts` | `GET /activation/countnumbers/{country}` |
+| `client.activation.get_service_price` | `client.activation.getServicePrice` | `GET /activation/serviceprice/{country}/{service}` |
+| `client.activation.get_country_operator_prices` | `client.activation.getCountryOperatorPrices` | `GET /activation/serviceprice/{country}` |
+| `client.activation.get_service_prices` | `client.activation.getServicePrices` | `GET /activation/serviceprices/{service}` |
+| `client.activation.get_all_service_prices` | `client.activation.getAllServicePrices` | `GET /activation/servicesprices` |
+| `client.activation.get_number` | `client.activation.getNumber` | `GET /activation/number/{country}/{service}` |
+| `client.activation.get_number_by_operator` | `client.activation.getNumberByOperator` | `GET /activation/number/{country}/{service}/{operator}` |
+| `client.activation.receive_sms` | `client.activation.receiveSms` | `GET /activation/sms/{orderid}` |
+| `client.activation.get_orders` | `client.activation.getOrders` | `GET /activation/orders` |
+| `client.activation.get_number_status` | `client.activation.getNumberStatus` | `GET /activation/numberstatus/{number}/{service}` |
+| `client.activation.clear_sms` | `client.activation.clearSms` | `PUT /activation/clearsms/{orderid}` |
+| `client.activation.stop_sms` | `client.activation.stopSms` | `PUT /activation/stopsms/{orderid}` |
+| `client.activation.cancel_order` | `client.activation.cancelOrder` | `PUT /activation/cancelorder/{orderid}` |
+| `client.activation.block_number` | `client.activation.blockNumber` | `PUT /activation/blocknumber/{orderid}` |
+
+## rental
+
+| Python (sync and async) | JavaScript / TypeScript | HTTP |
+| --- | --- | --- |
+| `client.rental.get_countries` | `client.rental.getCountries` | `GET /api/rent.php?method=getcountries` |
+| `client.rental.get_default_services` | `client.rental.getDefaultServices` | `GET /api/rent.php?method=get_default_services` |
+| `client.rental.get_countries_by_service` | `client.rental.getCountriesByService` | `GET /api/rent.php?method=get_country_by_service` |
+| `client.rental.get_data` | `client.rental.getData` | `GET /api/rent.php?method=getdata` |
+| `client.rental.get_data_with_providers` | `client.rental.getDataWithProviders` | `GET /api/rent.php?method=getdataWithProviders` |
+| `client.rental.get_count` | `client.rental.getCount` | `GET /api/rent.php?method=getcount` |
+| `client.rental.get_count_with_providers` | `client.rental.getCountWithProviders` | `GET /api/rent.php?method=getCountWithProviders` |
+| `client.rental.get_multi_service_count` | `client.rental.getMultiServiceCount` | `GET /api/rent.php?method=get_count_multi` |
+| `client.rental.get_canada_paypal_days` | `client.rental.getCanadaPaypalDays` | `GET /api/rent.php?method=get_days_canada_paypal` |
+| `client.rental.get_minimum_paypal_days` | `client.rental.getMinimumPaypalDays` | `GET /api/rent.php?method=get_min_paypal_days` |
+| `client.rental.create` | `client.rental.create` | `GET /api/rent.php?method=create` |
+| `client.rental.create_multi` | `client.rental.createMulti` | `GET /api/rent.php?method=create_multi` |
+| `client.rental.add_service_to_order` | `client.rental.addServiceToOrder` | `GET /api/rent.php?method=add_service_to_order` |
+| `client.rental.get_orders` | `client.rental.getOrders` | `GET /api/rent.php?method=orders` |
+| `client.rental.activate` | `client.rental.activate` | `GET /api/rent.php?method=activate` |
+| `client.rental.get_sms` | `client.rental.getSms` | `GET /api/rent.php?method=sms` |
+| `client.rental.prolong` | `client.rental.prolong` | `GET /api/rent.php?method=prolong` |
+| `client.rental.prolong_by_days` | `client.rental.prolongByDays` | `GET /api/rent.php?method=prolong_max` |
+| `client.rental.delete_order` | `client.rental.deleteOrder` | `GET /api/rent.php?method=delete` |
+| `client.rental.get_history` | `client.rental.getHistory` | `GET /api/rent.php?method=get_rent_history` |
+| `client.rental.get_restore_cost` | `client.rental.getRestoreCost` | `GET /api/rent.php?method=restore_user_precalc` |
+| `client.rental.restore` | `client.rental.restore` | `GET /api/rent.php?method=restore_user` |
+
+## email
+
+| Python (sync and async) | JavaScript / TypeScript | HTTP |
+| --- | --- | --- |
+| `client.email.get_providers` | `client.email.getProviders` | `GET /api/rent_email.php?method=get_providers` |
+| `client.email.get_data` | `client.email.getData` | `GET /api/rent_email.php?method=get_data` |
+| `client.email.get_count` | `client.email.getCount` | `GET /api/rent_email.php?method=get_count` |
+| `client.email.create_order` | `client.email.createOrder` | `GET /api/rent_email.php?method=create_order` |
+| `client.email.get_orders` | `client.email.getOrders` | `GET /api/rent_email.php?method=get_orders` |
+| `client.email.get_mails` | `client.email.getMails` | `GET /api/rent_email.php?method=get_mails` |
+| `client.email.get_mail_body` | `client.email.getMailBody` | `GET /api/rent_email.php?method=get_mail_body` |
+| `client.email.buy_alias` | `client.email.buyAlias` | `GET /api/rent_email.php?method=buy_alias` |
+| `client.email.get_mails_by_alias` | `client.email.getMailsByAlias` | `GET /api/rent_email.php?method=get_mails_by_alias` |
+| `client.email.prolong_order` | `client.email.prolongOrder` | `GET /api/rent_email.php?method=prolong_order` |
+| `client.email.cancel_order` | `client.email.cancelOrder` | `GET /api/rent_email.php?method=cancel_order` |
+| `client.email.get_archived_orders` | `client.email.getArchivedOrders` | `GET /api/rent_email.php?method=get_archived_orders` |
+| `client.email.calc_restore_order` | `client.email.calcRestoreOrder` | `GET /api/rent_email.php?method=calc_restore_order` |
+| `client.email.restore_order` | `client.email.restoreOrder` | `GET /api/rent_email.php?method=restore_order` |
+
+Activation also provides `wait_for_sms` / `waitForSms`. It polls an existing order until a caller-supplied expiry, without purchasing or cancelling an order.

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# SMSPVA JavaScript / TypeScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/SMSPVA/smspva-js/actions/workflows/ci.yml/badge.svg)](https://github.com/SMSPVA/smspva-js/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) ![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)
+
+Node.js 22.16+, ESM and CommonJS, with TypeScript declarations. Covers all 56 methods: Activation V2 (20), Rental (22) and Private Email (14). Alternative API is excluded. This is an alpha release. Use the explicit version or the `alpha` tag when installing.
+
+## Installation
+
+```sh
+npm install smspva-sdk@alpha
+# Or pin the first alpha:
+npm install smspva-sdk@0.1.0-alpha.1
+```
+
+Build and install from source:
+
+```sh
+git clone https://github.com/SMSPVA/smspva-js.git
+cd smspva-js
+npm ci
+npm run build
+# In the application that will use the SDK:
+npm install /absolute/path/to/smspva-js
+```
+
+```js
+import { SMSPVA } from 'smspva-sdk';
+
+const client = new SMSPVA({ apiKey: process.env.SMSPVA_API_KEY });
+console.log(await client.activation.getBalance());
+console.log(await client.rental.getCountries());
+console.log(await client.email.getProviders());
+```
+
+CommonJS: `const { SMSPVA } = require('smspva-sdk')`. Use the SDK on your server; keep account keys out of browser code. The package has no runtime dependencies and uses Node's native fetch.
+
+## Requests and results
+
+- Wire methods, parameter names and response values follow the source documentation. Price strings, timestamps and IDs are not converted. Optional source fields remain optional in the generated types.
+- Activation V2 sends the key in the `apikey` header. Rental and Email use query `apikey`. Public methods send no key. Optional-key Rental methods can omit it with a second argument `{ useApiKey: false }`.
+- All documented optional parameters are available, including `partnerkey`, `partner_key`, `provider`, `extend`, pagination and search. Query and path values are encoded. Omitted, undefined or empty Email `pcode` is not sent.
+- `rental.getMultiServiceCount` requires `dtype` and `dcount` explicitly: the docs warn against relying on backend defaults for this method. The wire method stays `get_count_multi`.
+- No request is retried automatically and no redirect is followed. This includes GET operations that create orders, modify state or trigger charges.
+
+```js
+// No key needed for public reference lists.
+const publicClient = new SMSPVA();
+const providers = await publicClient.email.getProviders();
+```
+
+Paid example (run only when you intend to create a rental):
+
+```ts
+import { SMSPVA, isNoStock } from 'smspva-sdk';
+
+const client = new SMSPVA({ apiKey: process.env.SMSPVA_API_KEY });
+const result = await client.email.createOrder({
+  scode: 'CODE_FROM_GET_DATA', dtype: 'week', dcount: 1,
+});
+if (isNoStock(result)) {
+  console.log('No mailbox available; refresh counts before trying again.');
+} else {
+  console.log(result.data);
+}
+```
+
+## Waiting for SMS
+
+`activation.receiveSms({ orderid })` returns the original pending envelope for HTTP 202 / `SMS_NOT_YET_RECEIVED`. Use `isPending(result)` to recognise it. Email creation `status=2` similarly stays an ordinary no-stock result, recognised by `isNoStock`.
+
+For repeated waiting requests, calculate an expiry once when your number is created:
+
+```js
+// numberResult is the successful response from your own getNumber request.
+const expiresAt = Date.now() + numberResult.data.orderExpireIn * 1000;
+const result = await client.activation.waitForSms({
+  orderid: numberResult.data.orderId,
+  expiresAt,
+});
+```
+
+The helper polls only Receive SMS. It uses a five-second interval by default and does not allow a shorter one; this is a helper policy, not an API-wide rate limit. It stops at the saved deadline, on terminal API errors, transport failures or cancellation. It never creates or cancels an order for you. Reading a newly received SMS can trigger payment.
+
+## Errors, timeouts and cancellation
+
+```js
+import { ApiError, TransportError } from 'smspva-sdk';
+
+try {
+  console.log(await client.activation.getBalance());
+} catch (error) {
+  if (error instanceof ApiError) {
+    console.error(error.family, error.httpStatus, error.code);
+  } else if (error instanceof TransportError) {
+    console.error(error.kind, error.outcomeUnknown);
+  } else {
+    throw error;
+  }
+}
+```
+
+`ApiError.response` retains the original API body. `ProtocolError` means invalid JSON or a missing/invalid status envelope. `RequestTimeoutError` extends `TransportError`; for state-changing operations, `outcomeUnknown` reminds you to check orders before trying again. `PollingTimeoutError` means the saved order deadline passed without a result. Exception messages omit request URLs and keys; redact credentials if your own fetch/logging layer logs query URLs.
+
+The default request timeout is 30 seconds, covering fetch and body reading. Set `timeoutMs` in the constructor or a method's second argument. Pass an `AbortSignal` as `{ signal }` to cancel a request or polling. You can inject `fetch` and override `activationBaseUrl`, `rentalBaseUrl`, `emailBaseUrl` for proxies and local testing.
+
+All generated request and response types are exported from the package. The complete method index is in `METHODS.md`. The generated source is committed. `npm run build` compiles it without needing the documentation source.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Development
+
+```sh
+npm ci
+npm run build
+npm test
+npm run test:types
+npm pack
+```
+
+Tests use synthetic fixtures and local HTTP servers; they do not buy numbers or call the production API.
+
+## Documentation
+
+[API documentation](https://docs.smspva.com)
+
+The new documentation is being prepared in English, Spanish and Chinese. Localized links will be added when it is deployed.
+
+The SDK covers Activation V2, Rental and Private Email. Alternative API is not supported.