airalo-sdk-type 0.0.7 → 0.0.9

package/README.md

@@ -1,59 +1,352 @@
-# CloudHub
-
-CloudHub is an API wrapper for managing authentication, products, and orders seamlessly. It is built with TypeScript and designed for flexibility and scalability.
-
-## Installation
-
-Install the package using npm or yarn:
-
-```bash
-npm install cloudhub.mn
-```
-
-## Usage
-
-Import CloudHub and configure it for your application:
-
-```ts
-import CloudHub from "cloudhub";
-
-// Set host and logger
-await CloudHub.setHost("https://api.example.com");
-await CloudHub.setLogger(true);
-
-// Authenticate
-const authResult = await CloudHub.auth.LOGIN({
-  email: "user@example.com",
-  password: "password123",
-});
-console.log(authResult);
-```
-
-## Features
-
-- **Authentication**: Login and manage tokens.
-- **Item Management**: Retrieve and manage items.
-- **Product Management**: Retrieve products and details.
-- **Order Verification**: Verify orders by ID.
-
-## API
-
-### `CloudHub.setHost(url: string)`
-
-Set the API host URL.
-
-### `CloudHub.setLogger(status: boolean)`
-
-Enable or disable logging.
-
-### `CloudHub.auth.LOGIN(body: { email: string; password: string })`
-
-Authenticate a user and retrieve an access token.
-
-### `CloudHub.auth.getToken()`
-
-Retrieve a new authentication token using stored credentials.
-
-## License
-
-MIT License
+# airalo-sdk-type
+
+> Unofficial TypeScript/JavaScript SDK for the [Airalo Partner API](https://partners-api.airalo.com)
+
+[![npm version](https://img.shields.io/npm/v/airalo-sdk-type)](https://www.npmjs.com/package/airalo-sdk-type)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
+
+---
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Environments](#environments)
+- [API reference](#api-reference)
+  - [Auth](#auth)
+  - [Packages](#packages)
+  - [Orders](#orders)
+  - [eSIMs](#esims)
+  - [Balance](#balance)
+  - [Notifications](#notifications)
+  - [Misc](#misc)
+- [Response format](#response-format)
+- [All methods](#all-methods)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Installation
+
+```bash
+npm install airalo-sdk-type
+# or
+yarn add airalo-sdk-type
+```
+
+---
+
+## Quick start
+
+```typescript
+import Airalo from "airalo-sdk-type";
+
+// 1. Point to sandbox or production
+Airalo.setHost("https://sandbox-partners-api.airalo.com");
+
+// 2. Authenticate — token is stored automatically
+await Airalo.auth.TOKEN({
+  client_id: "YOUR_CLIENT_ID",
+  client_secret: "YOUR_CLIENT_SECRET"
+});
+
+// 3. Fetch available packages
+const { data } = await Airalo.Package.Packages();
+console.log(data);
+
+// 4. Place an order
+const order = await Airalo.Order.SubmitOrder({
+  quantity: "1",
+  package_id: "chinacom-7days-1gb"
+});
+console.log(order.data?.sims[0].qrcode);
+```
+
+---
+
+## Environments
+
+| Environment | Base URL                                  |
+| ----------- | ----------------------------------------- |
+| Sandbox     | `https://sandbox-partners-api.airalo.com` |
+| Production  | `https://partners-api.airalo.com`         |
+
+```typescript
+// Sandbox (default)
+Airalo.setHost("https://sandbox-partners-api.airalo.com");
+
+// Production
+Airalo.setHost("https://partners-api.airalo.com");
+
+// Enable request/response logging
+Airalo.setLogger(true);
+```
+
+---
+
+## API reference
+
+### Auth
+
+```typescript
+// Fetch and store an access token
+await Airalo.auth.TOKEN({
+  client_id: "YOUR_CLIENT_ID",
+  client_secret: "YOUR_CLIENT_SECRET"
+});
+```
+
+---
+
+### Packages
+
+```typescript
+// List all available packages
+const all = await Airalo.Package.Packages();
+
+// Filter by country, page, and limit
+const jp = await Airalo.Package.Packages({
+  "filter[country]": "JP",
+  limit: 10,
+  page: 1
+});
+```
+
+---
+
+### Orders
+
+```typescript
+// Place a synchronous order — response includes SIM + QR code immediately
+const order = await Airalo.Order.SubmitOrder({
+  quantity: "1",
+  package_id: "chinacom-7days-1gb",
+  type: "sim", // optional, defaults to "sim"
+  description: "My order", // optional
+  brand_settings_name: "MyBrand" // optional, null = unbranded
+});
+
+// Place an asynchronous order — result is delivered via webhook
+await Airalo.Order.SubmitOrderAsync({
+  quantity: "1",
+  package_id: "chinacom-7days-1gb",
+  webhook_url: "https://myapp.com/webhook",
+  to_email: "user@example.com", // optional
+  sharing_option: ["link", "pdf"], // optional, required if to_email is set
+  copy_address: ["cc@example.com"] // optional
+});
+
+// Place a top-up order for an existing eSIM
+await Airalo.Order.SubmitTopUpOrder({
+  package_id: "bonbon-mobile-30days-3gb-topup",
+  iccid: "8934000000000087299",
+  description: "Top-up" // optional
+});
+
+// List orders with filters
+const orders = await Airalo.Order.GetOrderList({
+  "filter[order_status]": "completed", // completed | failed | refunded
+  "filter[iccid]": "89343",
+  "filter[code]": "20221021-003188",
+  "filter[created_at]": "2024-01-01 - 2024-12-31",
+  include: "sims,status",
+  limit: 20,
+  page: 1
+});
+
+// Get a single order by ID
+const single = await Airalo.Order.GetOrder(731579);
+
+// List all order statuses
+const statuses = await Airalo.Order.GetOrderStatuses();
+
+// Get a specific status by slug
+const status = await Airalo.Order.GetOrderStatusBySlug("completed");
+```
+
+---
+
+### eSIMs
+
+```typescript
+// List eSIMs with optional filters
+const sims = await Airalo.Sims.GetSimList({
+  "filter[iccid]": "8910300000",
+  "filter[created_at]": "2024-01-01 - 2024-12-31",
+  include: "order,order.status,share",
+  limit: 10,
+  page: 1
+});
+
+// Get a single eSIM by ICCID
+const sim = await Airalo.Sims.GetSim("8910300000033289733");
+
+// Get installation instructions (QR + manual)
+const instructions = await Airalo.Sims.GetSimInstructions(
+  "8910300000033289733"
+);
+
+// Get current data usage
+const usage = await Airalo.Sims.GetDataUsage("8910300000033289733");
+// usage.data.remaining  — bytes remaining
+// usage.data.total      — total bytes
+// usage.data.status     — NOT_ACTIVE | ACTIVE | FINISHED | EXPIRED
+
+// List available top-up packages for an eSIM
+const topups = await Airalo.Sims.GetTopUpPackageList("8910300000033289733");
+
+// Get package history for an eSIM
+const history = await Airalo.Sims.GetSimPackageHistory("8910300000033289733");
+
+// Update the brand name shown on an eSIM
+await Airalo.Sims.UpdateSimBrand("8910300000033289733", "MyBrand");
+```
+
+---
+
+### Balance
+
+```typescript
+const balance = await Airalo.Balance.GetBalance();
+console.log(balance.data?.balances.availableBalance.amount);
+console.log(balance.data?.balances.availableBalance.currency);
+```
+
+---
+
+### Notifications
+
+```typescript
+// Opt in to low-data webhook notifications
+await Airalo.Notification.NotificationOptIn({
+  type: "webhook_low_data",
+  webhook_url: "https://myapp.com/webhook"
+});
+
+// Opt in to credit-limit notifications with threshold levels (%)
+await Airalo.Notification.NotificationOptIn({
+  type: "webhook_credit_limit",
+  webhook_url: "https://myapp.com/webhook",
+  levels: [50, 70, 80, 90]
+});
+
+// Opt out
+await Airalo.Notification.NotificationOptOut({
+  type: "webhook_low_data" // email_low_data | email_credit_limit | webhook_low_data | webhook_credit_limit
+});
+
+// Get current notification settings
+const settings = await Airalo.Notification.GetNotification();
+
+// Simulate a webhook event (sandbox only)
+await Airalo.Notification.SimulateWebhook({
+  event: "low_data_notification",
+  type: "expire_1",
+  iccid: "8997212330099025334"
+});
+```
+
+---
+
+### Misc
+
+```typescript
+// List eSIM-compatible devices
+const devices = await Airalo.Misc.GetCompatibleDevices();
+
+// Create an eSIM voucher
+const voucher = await Airalo.Misc.CreateEsimVoucher({
+  package_id: "chinacom-7days-1gb",
+  quantity: 1
+});
+```
+
+---
+
+## Response format
+
+Every method returns an `ApiResult<T>` object:
+
+```typescript
+// Success
+{
+  success: true,
+  data: T,
+  message: "Амжилттай."
+}
+
+// Error
+{
+  success: false,
+  data: null,
+  message: "Error message from API"
+}
+```
+
+Check `result.success` before accessing `result.data`:
+
+```typescript
+const result = await Airalo.Order.SubmitOrder({
+  quantity: "1",
+  package_id: "chinacom-7days-1gb"
+});
+
+if (result.success) {
+  console.log(result.data.sims[0].qrcode_url);
+} else {
+  console.error(result.message);
+}
+```
+
+---
+
+## All methods
+
+| Module         | Method                 | Description                             |
+| -------------- | ---------------------- | --------------------------------------- |
+| `auth`         | `TOKEN`                | Fetch and store access token            |
+| `Package`      | `Packages`             | List packages (filterable by country)   |
+| `Order`        | `SubmitOrder`          | Place a synchronous order               |
+| `Order`        | `SubmitOrderAsync`     | Place an asynchronous order via webhook |
+| `Order`        | `SubmitTopUpOrder`     | Top up an existing eSIM                 |
+| `Order`        | `GetOrderList`         | List orders with filters                |
+| `Order`        | `GetOrder`             | Get a single order by ID                |
+| `Order`        | `GetOrderStatuses`     | List all order statuses                 |
+| `Order`        | `GetOrderStatusBySlug` | Get a single status by slug             |
+| `Sims`         | `GetSimList`           | List eSIMs with filters                 |
+| `Sims`         | `GetSim`               | Get a single eSIM by ICCID              |
+| `Sims`         | `GetSimInstructions`   | Get installation instructions           |
+| `Sims`         | `GetDataUsage`         | Get current data usage                  |
+| `Sims`         | `GetTopUpPackageList`  | List available top-up packages          |
+| `Sims`         | `GetSimPackageHistory` | Get package history                     |
+| `Sims`         | `UpdateSimBrand`       | Update eSIM brand name                  |
+| `Balance`      | `GetBalance`           | Get account balance                     |
+| `Notification` | `NotificationOptIn`    | Enable a notification type              |
+| `Notification` | `NotificationOptOut`   | Disable a notification type             |
+| `Notification` | `GetNotification`      | Get current notification settings       |
+| `Notification` | `SimulateWebhook`      | Simulate a webhook event (sandbox)      |
+| `Misc`         | `GetCompatibleDevices` | List eSIM-compatible devices            |
+| `Misc`         | `CreateEsimVoucher`    | Create an eSIM voucher                  |
+
+---
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first.
+
+```bash
+git clone https://github.com/togtokh-dev/airalo.git
+cd airalo
+npm install
+npm test
+```
+
+---
+
+## License
+
+[ISC](https://opensource.org/licenses/ISC) © Buyantogtokh
+
+> This is an **unofficial** SDK and is not affiliated with or endorsed by Airalo.

package/dist/api/auth.d.ts

@@ -0,0 +1,17 @@
+import { ApiResult } from "../utils/helpers";
+export declare const TOKEN: (auth: {
+    client_id: string;
+    client_secret: string;
+}) => Promise<ApiResult<{
+    access_token: string;
+}>>;
+export declare const getToken: () => Promise<string>;
+declare const _default: {
+    TOKEN: (auth: {
+        client_id: string;
+        client_secret: string;
+    }) => Promise<ApiResult<{
+        access_token: string;
+    }>>;
+};
+export default _default;

package/dist/api/auth.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getToken = exports.TOKEN = void 0;
+const config_1 = require("../config");
+const axios_master_1 = require("axios-master");
+const form_data_1 = __importDefault(require("form-data"));
+// Token авах дотоод функц
+async function fetchToken(client_id, client_secret) {
+    const formData = new form_data_1.default();
+    formData.append("client_id", client_id);
+    formData.append("client_secret", client_secret);
+    formData.append("grant_type", "client_credentials");
+    const response = await (0, axios_master_1.axiosMasterLogger)({
+        method: "POST",
+        url: `${config_1.config.host}/v2/token`,
+        headers: {
+            Accept: "application/json",
+            ...formData.getHeaders()
+        },
+        data: formData
+    }, {
+        name: "Token",
+        timeout: 20000,
+        logger: (data) => config_1.config.logger && console.log("Token:", data.json)
+    });
+    return response?.data?.access_token ?? "";
+}
+// Нэвтрэлт хийж token авах - гадаад ашиглалт
+const TOKEN = async (auth) => {
+    try {
+        const token = await fetchToken(auth.client_id, auth.client_secret);
+        if (token) {
+            // Тохиргоонд хадгалах
+            config_1.config.token = token;
+            config_1.config.auth = auth;
+            return {
+                success: true,
+                data: { access_token: token },
+                message: "Token амжилттай авлаа."
+            };
+        }
+        return {
+            success: false,
+            data: null,
+            message: "Token авахад амжилтгүй болсон."
+        };
+    }
+    catch (error) {
+        const axiosError = error;
+        console.error("Token хүсэлт амжилтгүй:", axiosError.message);
+        return {
+            success: false,
+            data: null,
+            message: axiosError?.response?.data?.meta?.message ?? "Алдаа гарлаа."
+        };
+    }
+};
+exports.TOKEN = TOKEN;
+// 401 алдааны үед автоматаар token шинэчлэх функц (axiosMasterLogger-т дамжуулна)
+const getToken = async () => {
+    try {
+        const token = await fetchToken(config_1.config.auth.client_id, config_1.config.auth.client_secret);
+        if (token)
+            config_1.config.token = token;
+        return token;
+    }
+    catch (error) {
+        console.error("Token шинэчлэлт амжилтгүй:", error.message);
+        return "";
+    }
+};
+exports.getToken = getToken;
+exports.default = { TOKEN: exports.TOKEN };

package/dist/api/balance.d.ts

@@ -0,0 +1,15 @@
+import { ApiResult } from "../utils/helpers";
+type BalanceData = {
+    balances: {
+        name: "balance";
+        availableBalance: {
+            amount: number;
+            currency: string;
+        };
+    };
+};
+export declare const GetBalance: () => Promise<ApiResult<BalanceData>>;
+declare const _default: {
+    GetBalance: () => Promise<ApiResult<BalanceData>>;
+};
+export default _default;

package/dist/api/balance.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetBalance = void 0;
+const config_1 = require("../config");
+const axios_master_1 = require("axios-master");
+const auth_1 = require("./auth");
+// Дансны үлдэгдлийг авах
+const GetBalance = async () => {
+    try {
+        const result = await (0, axios_master_1.axiosMasterLogger)({
+            method: "GET",
+            url: `${config_1.config.host}/v2/balance`,
+            headers: {
+                Accept: "application/json",
+                Authorization: `Bearer ${config_1.config.token}`
+            }
+        }, {
+            name: "GetBalance",
+            timeout: 20000,
+            retryFunction: auth_1.getToken,
+            shouldRetry: true,
+            shouldRetryStatus: [401],
+            logger: (data) => config_1.config.logger && console.log("GetBalance:", data.json)
+        });
+        return { success: true, data: result.data ?? null, message: "Амжилттай." };
+    }
+    catch (error) {
+        const axiosError = error;
+        console.error("GetBalance амжилтгүй:", axiosError.message);
+        return {
+            success: false,
+            data: null,
+            message: axiosError?.response?.data?.meta?.message ?? "Алдаа гарлаа."
+        };
+    }
+};
+exports.GetBalance = GetBalance;
+exports.default = { GetBalance: exports.GetBalance };

package/dist/api/misc.d.ts

@@ -0,0 +1,26 @@
+import { ApiResult } from "../utils/helpers";
+type CompatibleDevice = {
+    name: string;
+    model: string;
+    brand: string;
+    os: string;
+    compatible: boolean;
+};
+type EsimVoucher = {
+    code: string;
+    package_id: string;
+    created_at: string;
+};
+export declare const GetCompatibleDevices: () => Promise<ApiResult<CompatibleDevice[]>>;
+export declare const CreateEsimVoucher: (params: {
+    package_id: string;
+    quantity?: number;
+}) => Promise<ApiResult<EsimVoucher[]>>;
+declare const _default: {
+    GetCompatibleDevices: () => Promise<ApiResult<CompatibleDevice[]>>;
+    CreateEsimVoucher: (params: {
+        package_id: string;
+        quantity?: number;
+    }) => Promise<ApiResult<EsimVoucher[]>>;
+};
+export default _default;

package/dist/api/misc.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateEsimVoucher = exports.GetCompatibleDevices = void 0;
+const config_1 = require("../config");
+const axios_master_1 = require("axios-master");
+const auth_1 = require("./auth");
+// eSIM-тэй тохирох төхөөрөмжүүдийн жагсаалтыг авах
+const GetCompatibleDevices = async () => {
+    try {
+        const result = await (0, axios_master_1.axiosMasterLogger)({
+            method: "GET",
+            url: `${config_1.config.host}/v2/compatible-devices`,
+            headers: {
+                Accept: "application/json",
+                Authorization: `Bearer ${config_1.config.token}`
+            }
+        }, {
+            name: "GetCompatibleDevices",
+            timeout: 20000,
+            retryFunction: auth_1.getToken,
+            shouldRetry: true,
+            shouldRetryStatus: [401],
+            logger: (data) => config_1.config.logger && console.log("GetCompatibleDevices:", data.json)
+        });
+        return { success: true, data: result.data ?? [], message: "Амжилттай." };
+    }
+    catch (error) {
+        const axiosError = error;
+        console.error("GetCompatibleDevices амжилтгүй:", axiosError.message);
+        return {
+            success: false,
+            data: null,
+            message: axiosError?.response?.data?.meta?.message ?? "Алдаа гарлаа."
+        };
+    }
+};
+exports.GetCompatibleDevices = GetCompatibleDevices;
+// eSIM ваучер үүсгэх
+const CreateEsimVoucher = async (params) => {
+    try {
+        const result = await (0, axios_master_1.axiosMasterLogger)({
+            method: "POST",
+            url: `${config_1.config.host}/v2/voucher/esim`,
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${config_1.config.token}`
+            },
+            data: params
+        }, {
+            name: "CreateEsimVoucher",
+            timeout: 20000,
+            retryFunction: auth_1.getToken,
+            shouldRetry: true,
+            shouldRetryStatus: [401],
+            logger: (data) => config_1.config.logger && console.log("CreateEsimVoucher:", data.json)
+        });
+        return { success: true, data: result.data ?? [], message: "Амжилттай." };
+    }
+    catch (error) {
+        const axiosError = error;
+        console.error("CreateEsimVoucher амжилтгүй:", axiosError.message);
+        return {
+            success: false,
+            data: null,
+            message: axiosError?.response?.data?.meta?.message ?? "Алдаа гарлаа."
+        };
+    }
+};
+exports.CreateEsimVoucher = CreateEsimVoucher;
+exports.default = { GetCompatibleDevices: exports.GetCompatibleDevices, CreateEsimVoucher: exports.CreateEsimVoucher };