vak-sms-client 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 api-kit contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# vak-sms-client
 
-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.
+TypeScript and Node.js client for the [VAK-SMS API](https://vak-sms.com/en/api/).
+
+## Features
+
+- Virtual phone numbers and SMS OTP reception across international countries and operators
+- Complete activation lifecycle management (`send`, `end`, `bad`, and automatic polling)
+- Real-time stock counts and prices per service
+- Written in TypeScript with full type declarations and TSDoc
+
+## Installation
+
+```bash
+npm install vak-sms-client
+```
+
+## Quick Start
+
+```typescript
+import { VakSmsClient } from 'vak-sms-client';
+
+const client = new VakSmsClient({
+  apiKey: process.env.VAK_SMS_API_KEY!,
+});
+
+async function main() {
+  // Check account balance
+  const balance = await client.getBalance();
+  console.log(`Account balance: ${balance} RUB`);
+
+  // List supported countries and network operators
+  const countries = await client.getCountryList();
+  console.log(`Supported countries count: ${countries.length}`);
+}
+
+main().catch(console.error);
+```
+
+## Ordering a Virtual Number and Receiving SMS
+
+```typescript
+import { VakSmsClient } from 'vak-sms-client';
+
+const client = new VakSmsClient({ apiKey: 'YOUR_API_KEY' });
+
+async function activateNumber() {
+  // Order a number for Telegram in Russia
+  const order = await client.getNumber({
+    service: 'tg',
+    country: 'ru',
+  });
+
+  console.log(`Phone: ${order.tel}`);
+  console.log(`Operation ID: ${order.idNum}`);
+
+  // Wait for incoming SMS code (polls every 3 seconds up to 2 minutes)
+  const code = await client.waitForCode(order.idNum, { timeoutMs: 120000 });
+  if (code) {
+    console.log(`Received SMS code: ${code}`);
+    // Complete activation
+    await client.setStatus(order.idNum, 'end');
+  } else {
+    // If no code arrived, cancel/release the number
+    await client.setStatus(order.idNum, 'bad');
+  }
+}
+```
+
+## API Methods
+
+- `getBalance(): Promise<number>` — Returns the current balance in RUB.
+- `getNumber(options: GetNumberOptions): Promise<VakNumber>` — Orders a virtual phone number.
+- `prolongNumber(service, tel, softId?): Promise<VakNumber>` — Extends the duration of an existing number.
+- `getSmsCode(idNum, all?): Promise<string | string[] | null>` — Retrieves received SMS code(s).
+- `waitForCode(idNum, options?): Promise<string | null>` — Polls until SMS code arrives or times out.
+- `setStatus(idNum, status): Promise<string>` — Updates activation status (`send`, `end`, `bad`).
+- `getCountNumber(service, country?, operator?): Promise<CountNumber>` — Returns quantity and price for a service.
+- `getCountryList(): Promise<CountryOperator[]>` — Retrieves all supported countries and operators.
+- `getCountNumbersList(country?, operator?, rent?): Promise<Record<string, unknown>>` — Retrieves inventory catalog.
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,285 @@
+/**
+ * Default software/affiliate identifier (empty if none assigned).
+ */
+export declare const DEFAULT_SOFT_ID = "";
+/**
+ * Configuration options for the VakSmsClient.
+ */
+export interface VakSmsClientOptions {
+    /**
+     * API key obtained from VAK-SMS dashboard.
+     */
+    apiKey: string;
+    /**
+     * Base URL for the VAK-SMS API. Defaults to https://vak-sms.com.
+     */
+    baseURL?: string;
+    /**
+     * Request timeout in milliseconds. Defaults to 30000 ms.
+     */
+    timeout?: number;
+    /**
+     * Optional partner/software identifier.
+     */
+    softId?: string;
+}
+/**
+ * Options for requesting a virtual phone number.
+ */
+export interface GetNumberOptions {
+    /**
+     * Service code (e.g. 'tg' for Telegram, 'wa' for WhatsApp) or an array of two codes.
+     */
+    service: string | string[];
+    /**
+     * Country code (e.g. 'ru', 'kz', 'ua').
+     */
+    country?: string;
+    /**
+     * Mobile operator name (e.g. 'megafon', 'beeline', 'tele2').
+     */
+    operator?: string;
+    /**
+     * Whether to order a prolonged rental number (e.g. 4 hours).
+     */
+    rent?: boolean;
+    /**
+     * Optional partner/software ID override.
+     */
+    softId?: string;
+}
+/**
+ * Acquired virtual phone number details.
+ */
+export interface VakNumber {
+    /**
+     * Full phone number with country dial code.
+     */
+    tel: string | number;
+    /**
+     * Unique operation/order identifier.
+     */
+    idNum: string;
+    /**
+     * Service code requested.
+     */
+    service?: string;
+    /**
+     * Whether the number was leased under a prolonged rental.
+     */
+    rent?: boolean;
+}
+/**
+ * Available number count and unit price for a service.
+ */
+export interface CountNumber {
+    /**
+     * Service short code.
+     */
+    service: string;
+    /**
+     * Number of available phone numbers currently in stock.
+     */
+    count: number;
+    /**
+     * Unit cost per activation.
+     */
+    price?: number;
+}
+/**
+ * Supported country metadata and available operators.
+ */
+export interface CountryOperator {
+    /**
+     * Human-readable country name.
+     */
+    countryName: string;
+    /**
+     * Country 2-letter ISO code.
+     */
+    countryCode: string;
+    /**
+     * List of supported mobile network operators.
+     */
+    operatorList: string[];
+}
+/**
+ * Error dictionary for known VAK-SMS error codes.
+ */
+export declare const VAK_SMS_ERROR_DESCRIPTIONS: Record<string, string>;
+/**
+ * Error thrown by the VAK-SMS client when API calls fail.
+ */
+export declare class VakSmsError extends Error {
+    /**
+     * Error code identifier returned by VAK-SMS.
+     */
+    readonly code?: string;
+    /**
+     * Raw response payload from the server.
+     */
+    readonly responseBody?: unknown;
+    constructor(message: string, code?: string, responseBody?: unknown);
+}
+/**
+ * Client for the VAK-SMS temporary number and SMS OTP receiving service.
+ */
+export declare class VakSmsClient {
+    private readonly apiKey;
+    private readonly softId;
+    private readonly http;
+    /**
+     * Creates a new VakSmsClient.
+     *
+     * @param options - API key string or configuration object.
+     *
+     * @example
+     * ```typescript
+     * import { VakSmsClient } from 'vak-sms-client';
+     *
+     * const client = new VakSmsClient({ apiKey: 'YOUR_API_KEY' });
+     * const balance = await client.getBalance();
+     * console.log(`Balance: ${balance} RUB`);
+     * ```
+     */
+    constructor(options: VakSmsClientOptions | string);
+    /**
+     * Retrieves the current account balance.
+     *
+     * @returns Current balance in RUB.
+     *
+     * @example
+     * ```typescript
+     * const balance = await client.getBalance();
+     * console.log(`Current balance: ${balance}`);
+     * ```
+     */
+    getBalance(): Promise<number>;
+    /**
+     * Requests a temporary virtual phone number.
+     *
+     * @param options - Order parameters including service, country, operator, and rental status.
+     * @returns Number details with idNum and phone number.
+     *
+     * @example
+     * ```typescript
+     * const order = await client.getNumber({
+     *   service: 'tg',
+     *   country: 'ru',
+     * });
+     * console.log(`Phone: ${order.tel}, ID: ${order.idNum}`);
+     * ```
+     */
+    getNumber(options: GetNumberOptions): Promise<VakNumber>;
+    /**
+     * Extends the rental duration for an existing number.
+     *
+     * @param service - Service code.
+     * @param tel - Phone number without plus sign (e.g. 79991234567).
+     * @param softId - Optional software referral ID.
+     * @returns Prolonged number details.
+     *
+     * @example
+     * ```typescript
+     * const res = await client.prolongNumber('tg', '79991234567');
+     * console.log(`Prolonged ID: ${res.idNum}`);
+     * ```
+     */
+    prolongNumber(service: string, tel: string | number, softId?: string): Promise<VakNumber>;
+    /**
+     * Retrieves incoming SMS code(s) for an active order.
+     *
+     * @param idNum - Activation ID returned by getNumber.
+     * @param all - Whether to return an array of all received codes.
+     * @returns Code string, array of codes, or null if code not yet arrived.
+     *
+     * @example
+     * ```typescript
+     * const code = await client.getSmsCode('abcd1234ef');
+     * if (code) {
+     *   console.log('Received SMS code:', code);
+     * }
+     * ```
+     */
+    getSmsCode(idNum: string, all?: boolean): Promise<string | string[] | null>;
+    /**
+     * Polls until an SMS code arrives or timeout occurs.
+     *
+     * @param idNum - Activation identifier.
+     * @param options - Polling options with timeoutMs (default 120s) and intervalMs (default 3s).
+     * @returns Code string or null on timeout.
+     *
+     * @example
+     * ```typescript
+     * const code = await client.waitForCode('abcd1234ef', { timeoutMs: 60000 });
+     * console.log('Code:', code);
+     * ```
+     */
+    waitForCode(idNum: string, options?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<string | null>;
+    /**
+     * Updates activation status.
+     *
+     * Status actions:
+     * - 'send': Ready to receive another SMS code
+     * - 'end': Successfully complete the activation
+     * - 'bad': Ban/report number as defective to release it
+     *
+     * @param idNum - Activation identifier.
+     * @param status - Action name ('send', 'end', 'bad').
+     * @returns Status response string.
+     *
+     * @example
+     * ```typescript
+     * await client.setStatus('abcd1234ef', 'end');
+     * console.log('Activation completed');
+     * ```
+     */
+    setStatus(idNum: string, status: 'send' | 'end' | 'bad'): Promise<string>;
+    /**
+     * Checks available phone number quantity and price for a service.
+     *
+     * @param service - Service code.
+     * @param country - Country code (default: 'ru').
+     * @param operator - Optional mobile operator filter.
+     * @returns Quantity and unit price.
+     *
+     * @example
+     * ```typescript
+     * const count = await client.getCountNumber('tg', 'ru');
+     * console.log(`Available: ${count.count}, Price: ${count.price} RUB`);
+     * ```
+     */
+    getCountNumber(service: string, country?: string, operator?: string): Promise<CountNumber>;
+    /**
+     * Retrieves the catalog of supported countries and operators.
+     *
+     * @returns List of country and operator listings.
+     *
+     * @example
+     * ```typescript
+     * const countries = await client.getCountryList();
+     * console.log(`Supported countries: ${countries.length}`);
+     * ```
+     */
+    getCountryList(): Promise<CountryOperator[]>;
+    /**
+     * Retrieves full catalog of available services and stock for a country.
+     *
+     * @param country - Country code (default 'ru').
+     * @param operator - Optional mobile operator filter.
+     * @param rent - Whether to query prolonged rental service stock.
+     * @returns Map of services and stock.
+     *
+     * @example
+     * ```typescript
+     * const catalog = await client.getCountNumbersList('ru');
+     * console.log(catalog);
+     * ```
+     */
+    getCountNumbersList(country?: string, operator?: string, rent?: boolean): Promise<Record<string, unknown>>;
+    private request;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,370 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VakSmsClient = exports.VakSmsError = exports.VAK_SMS_ERROR_DESCRIPTIONS = exports.DEFAULT_SOFT_ID = void 0;
+const axios_1 = __importDefault(require("axios"));
+/**
+ * Default software/affiliate identifier (empty if none assigned).
+ */
+exports.DEFAULT_SOFT_ID = '';
+/**
+ * Error dictionary for known VAK-SMS error codes.
+ */
+exports.VAK_SMS_ERROR_DESCRIPTIONS = {
+    apiKeyNotFound: 'API key not found',
+    noService: 'Service not found or invalid',
+    noNumber: 'No numbers available, try again later',
+    noMoney: 'Insufficient funds, please top up balance',
+    noCountry: 'Country not found',
+    noOperator: 'No operator was found for the requested country',
+    badStatus: 'Status not correct',
+    idNumNotFound: 'idNum not found',
+    badService: 'Incorrect website or service code',
+    badData: 'Invalid request data sent',
+};
+/**
+ * Error thrown by the VAK-SMS client when API calls fail.
+ */
+class VakSmsError extends Error {
+    /**
+     * Error code identifier returned by VAK-SMS.
+     */
+    code;
+    /**
+     * Raw response payload from the server.
+     */
+    responseBody;
+    constructor(message, code, responseBody) {
+        super(message);
+        this.name = 'VakSmsError';
+        this.code = code;
+        this.responseBody = responseBody;
+        Object.setPrototypeOf(this, VakSmsError.prototype);
+    }
+}
+exports.VakSmsError = VakSmsError;
+/**
+ * Client for the VAK-SMS temporary number and SMS OTP receiving service.
+ */
+class VakSmsClient {
+    apiKey;
+    softId;
+    http;
+    /**
+     * Creates a new VakSmsClient.
+     *
+     * @param options - API key string or configuration object.
+     *
+     * @example
+     * ```typescript
+     * import { VakSmsClient } from 'vak-sms-client';
+     *
+     * const client = new VakSmsClient({ apiKey: 'YOUR_API_KEY' });
+     * const balance = await client.getBalance();
+     * console.log(`Balance: ${balance} RUB`);
+     * ```
+     */
+    constructor(options) {
+        if (typeof options === 'string') {
+            this.apiKey = options.trim();
+            this.softId = exports.DEFAULT_SOFT_ID;
+            this.http = axios_1.default.create({
+                baseURL: 'https://vak-sms.com',
+                timeout: 30000,
+            });
+        }
+        else {
+            if (!options || !options.apiKey || !options.apiKey.trim()) {
+                throw new VakSmsError('API key is required to initialize VakSmsClient', 'apiKeyNotFound');
+            }
+            this.apiKey = options.apiKey.trim();
+            this.softId = options.softId ?? exports.DEFAULT_SOFT_ID;
+            this.http = axios_1.default.create({
+                baseURL: options.baseURL || 'https://vak-sms.com',
+                timeout: options.timeout || 30000,
+            });
+        }
+    }
+    /**
+     * Retrieves the current account balance.
+     *
+     * @returns Current balance in RUB.
+     *
+     * @example
+     * ```typescript
+     * const balance = await client.getBalance();
+     * console.log(`Current balance: ${balance}`);
+     * ```
+     */
+    async getBalance() {
+        const data = (await this.request('/api/getBalance/'));
+        if (typeof data === 'object' && data !== null && typeof data.balance === 'number') {
+            return data.balance;
+        }
+        throw new VakSmsError('Invalid getBalance response', 'INVALID_RESPONSE', data);
+    }
+    /**
+     * Requests a temporary virtual phone number.
+     *
+     * @param options - Order parameters including service, country, operator, and rental status.
+     * @returns Number details with idNum and phone number.
+     *
+     * @example
+     * ```typescript
+     * const order = await client.getNumber({
+     *   service: 'tg',
+     *   country: 'ru',
+     * });
+     * console.log(`Phone: ${order.tel}, ID: ${order.idNum}`);
+     * ```
+     */
+    async getNumber(options) {
+        const service = Array.isArray(options.service) ? options.service.join(',') : options.service;
+        const params = {
+            service,
+        };
+        if (options.country)
+            params.country = options.country;
+        if (options.operator)
+            params.operator = options.operator;
+        if (options.rent)
+            params.rent = 'true';
+        const softId = options.softId ?? this.softId;
+        if (softId)
+            params.softId = softId;
+        const data = (await this.request('/api/getNumber/', params));
+        if (data && data.idNum && data.tel) {
+            return {
+                idNum: String(data.idNum),
+                tel: data.tel,
+                service,
+                rent: options.rent,
+            };
+        }
+        throw new VakSmsError('Invalid getNumber response', 'INVALID_RESPONSE', data);
+    }
+    /**
+     * Extends the rental duration for an existing number.
+     *
+     * @param service - Service code.
+     * @param tel - Phone number without plus sign (e.g. 79991234567).
+     * @param softId - Optional software referral ID.
+     * @returns Prolonged number details.
+     *
+     * @example
+     * ```typescript
+     * const res = await client.prolongNumber('tg', '79991234567');
+     * console.log(`Prolonged ID: ${res.idNum}`);
+     * ```
+     */
+    async prolongNumber(service, tel, softId) {
+        const params = {
+            service,
+            tel,
+        };
+        const effectiveSoftId = softId ?? this.softId;
+        if (effectiveSoftId)
+            params.softId = effectiveSoftId;
+        const data = (await this.request('/api/prolongNumber/', params));
+        if (data && data.idNum && data.tel) {
+            return {
+                idNum: String(data.idNum),
+                tel: data.tel,
+                service,
+            };
+        }
+        throw new VakSmsError('Invalid prolongNumber response', 'INVALID_RESPONSE', data);
+    }
+    /**
+     * Retrieves incoming SMS code(s) for an active order.
+     *
+     * @param idNum - Activation ID returned by getNumber.
+     * @param all - Whether to return an array of all received codes.
+     * @returns Code string, array of codes, or null if code not yet arrived.
+     *
+     * @example
+     * ```typescript
+     * const code = await client.getSmsCode('abcd1234ef');
+     * if (code) {
+     *   console.log('Received SMS code:', code);
+     * }
+     * ```
+     */
+    async getSmsCode(idNum, all) {
+        const params = { idNum };
+        if (all)
+            params.all = 'true';
+        const data = (await this.request('/api/getSmsCode/', params));
+        if (data && 'smsCode' in data) {
+            return data.smsCode ?? null;
+        }
+        return null;
+    }
+    /**
+     * Polls until an SMS code arrives or timeout occurs.
+     *
+     * @param idNum - Activation identifier.
+     * @param options - Polling options with timeoutMs (default 120s) and intervalMs (default 3s).
+     * @returns Code string or null on timeout.
+     *
+     * @example
+     * ```typescript
+     * const code = await client.waitForCode('abcd1234ef', { timeoutMs: 60000 });
+     * console.log('Code:', code);
+     * ```
+     */
+    async waitForCode(idNum, options) {
+        const timeoutMs = options?.timeoutMs ?? 120000;
+        const intervalMs = options?.intervalMs ?? 3000;
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            const res = await this.getSmsCode(idNum);
+            if (res) {
+                if (Array.isArray(res)) {
+                    return res[res.length - 1] ?? null;
+                }
+                return res;
+            }
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+        return null;
+    }
+    /**
+     * Updates activation status.
+     *
+     * Status actions:
+     * - 'send': Ready to receive another SMS code
+     * - 'end': Successfully complete the activation
+     * - 'bad': Ban/report number as defective to release it
+     *
+     * @param idNum - Activation identifier.
+     * @param status - Action name ('send', 'end', 'bad').
+     * @returns Status response string.
+     *
+     * @example
+     * ```typescript
+     * await client.setStatus('abcd1234ef', 'end');
+     * console.log('Activation completed');
+     * ```
+     */
+    async setStatus(idNum, status) {
+        const data = (await this.request('/api/setStatus/', {
+            idNum,
+            status,
+        }));
+        if (data && typeof data.status === 'string') {
+            return data.status;
+        }
+        return 'ok';
+    }
+    /**
+     * Checks available phone number quantity and price for a service.
+     *
+     * @param service - Service code.
+     * @param country - Country code (default: 'ru').
+     * @param operator - Optional mobile operator filter.
+     * @returns Quantity and unit price.
+     *
+     * @example
+     * ```typescript
+     * const count = await client.getCountNumber('tg', 'ru');
+     * console.log(`Available: ${count.count}, Price: ${count.price} RUB`);
+     * ```
+     */
+    async getCountNumber(service, country = 'ru', operator) {
+        const params = {
+            service,
+            country,
+            price: 1,
+        };
+        if (operator)
+            params.operator = operator;
+        const data = (await this.request('/api/getCountNumber/', params));
+        if (data && typeof data === 'object') {
+            const countVal = data[service];
+            const count = typeof countVal === 'number' ? countVal : 0;
+            const price = typeof data.price === 'number' ? data.price : undefined;
+            return {
+                service,
+                count,
+                price,
+            };
+        }
+        throw new VakSmsError('Invalid getCountNumber response', 'INVALID_RESPONSE', data);
+    }
+    /**
+     * Retrieves the catalog of supported countries and operators.
+     *
+     * @returns List of country and operator listings.
+     *
+     * @example
+     * ```typescript
+     * const countries = await client.getCountryList();
+     * console.log(`Supported countries: ${countries.length}`);
+     * ```
+     */
+    async getCountryList() {
+        const data = await this.request('/api/getCountryList/');
+        if (Array.isArray(data)) {
+            return data;
+        }
+        throw new VakSmsError('Invalid getCountryList response', 'INVALID_RESPONSE', data);
+    }
+    /**
+     * Retrieves full catalog of available services and stock for a country.
+     *
+     * @param country - Country code (default 'ru').
+     * @param operator - Optional mobile operator filter.
+     * @param rent - Whether to query prolonged rental service stock.
+     * @returns Map of services and stock.
+     *
+     * @example
+     * ```typescript
+     * const catalog = await client.getCountNumbersList('ru');
+     * console.log(catalog);
+     * ```
+     */
+    async getCountNumbersList(country = 'ru', operator, rent) {
+        const params = {
+            country,
+        };
+        if (operator)
+            params.operator = operator;
+        if (rent)
+            params.rent = 'true';
+        const data = (await this.request('/api/getCountNumbersList/', params));
+        return data && typeof data === 'object' ? data : {};
+    }
+    async request(endpoint, params = {}) {
+        try {
+            const response = await this.http.get(endpoint, {
+                params: {
+                    apiKey: this.apiKey,
+                    ...params,
+                },
+            });
+            const data = response.data;
+            if (data && typeof data === 'object') {
+                if ('error' in data && data.error) {
+                    const errCode = String(data.error);
+                    const desc = exports.VAK_SMS_ERROR_DESCRIPTIONS[errCode] || `VAK-SMS API error: ${errCode}`;
+                    throw new VakSmsError(desc, errCode, data);
+                }
+                if ('code' in data && data.code && 'message' in data) {
+                    throw new VakSmsError(String(data.message), String(data.code), data);
+                }
+            }
+            return data;
+        }
+        catch (err) {
+            if (err instanceof VakSmsError) {
+                throw err;
+            }
+            throw new VakSmsError(`VAK-SMS request failed: ${err instanceof Error ? err.message : String(err)}`, 'NETWORK_ERROR');
+        }
+    }
+}
+exports.VakSmsClient = VakSmsClient;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "vak-sms-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "TypeScript client for the VAK-SMS virtual number and SMS activation API",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "jest",
+    "test:live": "jest --testPathPattern=test/live --testPathIgnorePatterns=/node_modules/",
+    "docs": "typedoc --options typedoc.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TysikGG/api-kit.git",
+    "directory": "vak-sms/js"
+  },
+  "keywords": [
+    "vak-sms",
+    "vaksms",
+    "sms-activation",
+    "virtual-numbers",
+    "sms-verification",
+    "otp"
+  ],
+  "license": "ISC",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "axios": "^1.20.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.2",
+    "axios-mock-adapter": "^2.1.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typedoc": "^0.28.1",
+    "typedoc-plugin-markdown": "^4.6.0",
+    "typescript": "^5.7.2"
+  }
+}