mozosubz-sdk 1.0.0

package/README.md

@@ -0,0 +1,86 @@
+# Mozosubz SDK
+
+Buy cheap data and airtime in Nigeria programmatically via the [Mozosubz V1 API](https://mozosubz.xyz/doc).
+
+Purchases process synchronously in milliseconds — the API response you get back **is** the final transaction status (`success`, `transaction_id`, amount, and your new wallet balance). No polling or webhooks needed.
+
+| Method | Endpoint |
+|---|---|
+| `getDataPlans(service)` | `GET /api/v1/data/plans?service=...` |
+| `buyData({ service, planId, phone })` | `POST /api/v1/data/purchase` |
+| `buyAirtime({ network, amount, phone })` | `POST /api/v1/airtime/purchase` |
+
+## Install
+
+```bash
+npm install mozosubz-sdk
+```
+
+Zero dependencies. Node 18+.
+
+## Quick start
+
+```js
+const { Mozosubz } = require('mozosubz-sdk');
+
+const client = new Mozosubz({ apiKey: process.env.MOZOSUBZ_API_KEY });
+
+// 1. Fetch plans in real-time (docs: never hardcode plan IDs)
+const { plans } = await client.getDataPlans('mtn_sme');
+
+// 2. Buy data — response is the final status
+const order = await client.buyData({
+  service: 'mtn_sme',
+  planId: plans[0].id,
+  phone: '08012345678',
+});
+console.log(order.transaction_id, order.balance_after);
+
+// 3. Buy airtime (minimum ₦50)
+await client.buyAirtime({ network: 'mtn', amount: 100, phone: '08012345678' });
+```
+
+Get your Connect Key (format `connect_...`) from the API Keys page on [mozosubz.xyz](https://mozosubz.xyz) — the SDK sends it in the `X-Connect-Key` header for you.
+
+## Data services
+
+`mtn_sme`, `mtn_datashare`, `mtn_gifting`, `mtn_awoof`, `glo_data`, `glo_sme`, `airtel_sme`, `airtel_gifting`, `etisalat_data`
+
+Also available as constants: `Mozosubz.DATA_SERVICES.MTN_SME`, etc.
+
+## Airtime networks
+
+`mtn`, `glo`, `airtel`, `etisalat` (9mobile)
+
+## Error handling
+
+All failures throw `MozosubzError` with helpers mapped to the documented status codes:
+
+```js
+const { MozosubzError } = require('mozosubz-sdk');
+
+try {
+  await client.buyData({ service: 'mtn_sme', planId: 'plan_1', phone: '08012345678' });
+} catch (err) {
+  if (err instanceof MozosubzError) {
+    if (err.isAuthError) {                  // 401 — bad/missing key
+    } else if (err.isInsufficientBalance) { // 402 — fund your wallet
+    } else if (err.isRateLimited) {         // 429 — 10,000 requests/day limit
+    } else {
+      console.error(err.status, err.message); // 400, 500, or network failure (status null)
+    }
+  }
+}
+```
+
+## Safety choices
+
+- **Purchases are never auto-retried.** A network failure mid-purchase is ambiguous — retrying could double-charge your wallet. Only the read-only `getDataPlans` retries (2× by default).
+- Phone numbers are validated client-side (`08012345678` form) before any request is sent.
+- Airtime below the documented ₦50 minimum is rejected locally.
+
+## Notes
+
+- Rate limit: 10,000 requests/day.
+- Keep your key server-side only — never ship it in client-side code.
+- Base URL: `https://mozosubz.xyz/api/v1` (overridable via `new Mozosubz({ baseUrl })`).

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "mozosubz-sdk",
+  "version": "1.0.0",
+  "description": "Node.js SDK for the Mozosubz V1 API — buy cheap data and airtime in Nigeria programmatically. Purchases process in milliseconds.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "type": "commonjs",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://mozosubz.xyz/doc",
+  "keywords": [
+    "mozosubz",
+    "vtu",
+    "data",
+    "airtime",
+    "nigeria",
+    "mtn",
+    "glo",
+    "airtel",
+    "9mobile"
+  ],
+  "license": "MIT"
+}

package/src/index.d.ts

@@ -0,0 +1,73 @@
+export interface DataPlan {
+  id: string;
+  displayName: string;
+  price: number;
+  validity: string;
+}
+
+export interface DataPlansResponse {
+  success: true;
+  service: string;
+  plans: DataPlan[];
+}
+
+export interface DataPurchaseResponse {
+  success: true;
+  transaction_id: string;
+  plan: string;
+  phone: string;
+  amount: number;
+  balance_after: number;
+}
+
+export interface AirtimePurchaseResponse {
+  success: true;
+  transaction_id: string;
+  network: string;
+  phone: string;
+  amount: number;
+  balance_after: number;
+}
+
+export type DataService =
+  | 'mtn_sme'
+  | 'mtn_datashare'
+  | 'mtn_gifting'
+  | 'mtn_awoof'
+  | 'glo_data'
+  | 'glo_sme'
+  | 'airtel_sme'
+  | 'airtel_gifting'
+  | 'etisalat_data';
+
+export type AirtimeNetwork = 'mtn' | 'glo' | 'airtel' | 'etisalat';
+
+export declare class MozosubzError extends Error {
+  status: number | null;
+  body: object | null;
+  isAuthError: boolean;
+  isInsufficientBalance: boolean;
+  isRateLimited: boolean;
+}
+
+export interface MozosubzOptions {
+  apiKey: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  maxRetries?: number;
+}
+
+export declare class Mozosubz {
+  constructor(options: MozosubzOptions);
+  getDataPlans(service: DataService): Promise<DataPlansResponse>;
+  buyData(params: { service: DataService; planId: string; phone: string }): Promise<DataPurchaseResponse>;
+  buyAirtime(params: { network: AirtimeNetwork; amount: number; phone: string }): Promise<AirtimePurchaseResponse>;
+
+  static DATA_SERVICES: Record<string, DataService>;
+  static AIRTIME_NETWORKS: Record<string, AirtimeNetwork>;
+  static MIN_AIRTIME_AMOUNT: number;
+}
+
+export declare const DATA_SERVICES: Record<string, DataService>;
+export declare const AIRTIME_NETWORKS: Record<string, AirtimeNetwork>;
+export declare const MIN_AIRTIME_AMOUNT: number;

package/src/index.js

@@ -0,0 +1,208 @@
+'use strict';
+
+/**
+ * Mozosubz Node.js SDK
+ *
+ * Built strictly on the documented Mozosubz V1 API (https://mozosubz.xyz/doc):
+ *   - GET  /api/v1/data/plans?service=<service_id>
+ *   - POST /api/v1/data/purchase
+ *   - POST /api/v1/airtime/purchase
+ *
+ * Auth: X-Connect-Key header. All responses are JSON.
+ */
+
+const BASE_URL = 'https://mozosubz.xyz/api/v1';
+
+/** Data service IDs, exactly as listed in the API reference. */
+const DATA_SERVICES = Object.freeze({
+  MTN_SME: 'mtn_sme',
+  MTN_DATASHARE: 'mtn_datashare',
+  MTN_GIFTING: 'mtn_gifting',
+  MTN_AWOOF: 'mtn_awoof',
+  GLO_DATA: 'glo_data',
+  GLO_SME: 'glo_sme',
+  AIRTEL_SME: 'airtel_sme',
+  AIRTEL_GIFTING: 'airtel_gifting',
+  ETISALAT_DATA: 'etisalat_data',
+});
+
+/** Airtime network IDs, exactly as listed in the API reference. */
+const AIRTIME_NETWORKS = Object.freeze({
+  MTN: 'mtn',
+  GLO: 'glo',
+  AIRTEL: 'airtel',
+  ETISALAT: 'etisalat',
+});
+
+/** Documented minimum airtime amount (₦). */
+const MIN_AIRTIME_AMOUNT = 50;
+
+class MozosubzError extends Error {
+  /**
+   * @param {string} message
+   * @param {number|null} status HTTP status code, null for network failures
+   * @param {object|null} body   Parsed response body if available
+   */
+  constructor(message, status = null, body = null) {
+    super(message);
+    this.name = 'MozosubzError';
+    this.status = status;
+    this.body = body;
+    // Documented statuses: 400, 401, 402, 429, 500
+    this.isAuthError = status === 401;
+    this.isInsufficientBalance = status === 402;
+    this.isRateLimited = status === 429;
+  }
+}
+
+class Mozosubz {
+  /**
+   * @param {object} options
+   * @param {string} options.apiKey  Your Connect Key (format: connect_...)
+   * @param {string} [options.baseUrl] Override base URL (default: https://mozosubz.xyz/api/v1)
+   * @param {number} [options.timeoutMs] Request timeout in ms (default: 30000)
+   * @param {number} [options.maxRetries] Retries for network failures on GET requests only (default: 2)
+   */
+  constructor({ apiKey, baseUrl = BASE_URL, timeoutMs = 30000, maxRetries = 2 } = {}) {
+    if (!apiKey || typeof apiKey !== 'string') {
+      throw new MozosubzError('apiKey is required. Get one from the API Keys page on mozosubz.xyz.');
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.timeoutMs = timeoutMs;
+    this.maxRetries = maxRetries;
+  }
+
+  /**
+   * GET /data/plans — list plans for a data service.
+   * Docs: fetch plans in real-time, don't hardcode plan IDs.
+   * @param {string} service e.g. 'mtn_sme', 'glo_data' (see Mozosubz.DATA_SERVICES)
+   * @returns {Promise<{success: boolean, service: string, plans: Array<{id: string, displayName: string, price: number, validity: string}>}>}
+   */
+  async getDataPlans(service) {
+    assertOneOf('service', service, Object.values(DATA_SERVICES));
+    const qs = new URLSearchParams({ service }).toString();
+    // Safe to retry: read-only request.
+    return this._request('GET', `/data/plans?${qs}`, null, { retriable: true });
+  }
+
+  /**
+   * POST /data/purchase — buy a data plan.
+   * NOT retried automatically: retrying a purchase after an ambiguous network
+   * failure could double-charge your wallet.
+   * @param {object} params
+   * @param {string} params.service Data service ID, e.g. 'mtn_sme'
+   * @param {string} params.planId  Plan ID from getDataPlans()
+   * @param {string} params.phone   Nigerian phone number, e.g. '08012345678'
+   * @returns {Promise<{success: boolean, transaction_id: string, plan: string, phone: string, amount: number, balance_after: number}>}
+   */
+  async buyData({ service, planId, phone } = {}) {
+    assertOneOf('service', service, Object.values(DATA_SERVICES));
+    assertNonEmptyString('planId', planId);
+    assertPhone(phone);
+    return this._request('POST', '/data/purchase', {
+      service,
+      plan_id: planId,
+      phone,
+    });
+  }
+
+  /**
+   * POST /airtime/purchase — buy airtime.
+   * NOT retried automatically (same double-charge risk as buyData).
+   * @param {object} params
+   * @param {string} params.network 'mtn' | 'glo' | 'airtel' | 'etisalat'
+   * @param {number} params.amount  Amount in ₦. Minimum ₦50 per the docs.
+   * @param {string} params.phone   Nigerian phone number
+   * @returns {Promise<{success: boolean, transaction_id: string, network: string, phone: string, amount: number, balance_after: number}>}
+   */
+  async buyAirtime({ network, amount, phone } = {}) {
+    assertOneOf('network', network, Object.values(AIRTIME_NETWORKS));
+    if (typeof amount !== 'number' || !Number.isFinite(amount) || amount < MIN_AIRTIME_AMOUNT) {
+      throw new MozosubzError(`amount must be a number >= ₦${MIN_AIRTIME_AMOUNT}`);
+    }
+    assertPhone(phone);
+    return this._request('POST', '/airtime/purchase', { network, amount, phone });
+  }
+
+  async _request(method, path, body, { retriable = false } = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const attempts = retriable ? this.maxRetries + 1 : 1;
+    let lastNetworkError;
+
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      let res;
+      try {
+        res = await fetch(url, {
+          method,
+          headers: {
+            'X-Connect-Key': this.apiKey,
+            Accept: 'application/json',
+            ...(body ? { 'Content-Type': 'application/json' } : {}),
+          },
+          body: body ? JSON.stringify(body) : undefined,
+          signal: controller.signal,
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        lastNetworkError = err;
+        if (attempt < attempts) {
+          await sleep(300 * attempt);
+          continue;
+        }
+        throw new MozosubzError(`Network error calling ${method} ${path}: ${err.message}`, null, null);
+      }
+      clearTimeout(timer);
+
+      let json = null;
+      try {
+        json = await res.json();
+      } catch {
+        // Non-JSON response despite docs saying all responses are JSON.
+      }
+
+      if (res.ok && json && json.success === true) return json;
+
+      // Error shape confirmed against the live API: {"success":false,"error":"..."}
+      const message =
+        (json && (json.error || json.message)) || `HTTP ${res.status} from ${method} ${path}`;
+      throw new MozosubzError(message, res.status, json);
+    }
+
+    throw new MozosubzError(`Network error: ${lastNetworkError?.message}`, null, null);
+  }
+}
+
+function assertNonEmptyString(name, value) {
+  if (!value || typeof value !== 'string') {
+    throw new MozosubzError(`${name} is required and must be a non-empty string`);
+  }
+}
+
+function assertOneOf(name, value, allowed) {
+  assertNonEmptyString(name, value);
+  if (!allowed.includes(value)) {
+    throw new MozosubzError(`${name} must be one of: ${allowed.join(', ')} (got "${value}")`);
+  }
+}
+
+// Docs say "Nigerian phone number" and show the 0-prefixed 11-digit form
+// (e.g. 08012345678). Validate that documented form only.
+function assertPhone(phone) {
+  assertNonEmptyString('phone', phone);
+  if (!/^0\d{10}$/.test(phone)) {
+    throw new MozosubzError('phone must be an 11-digit Nigerian number starting with 0, e.g. 08012345678');
+  }
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+Mozosubz.DATA_SERVICES = DATA_SERVICES;
+Mozosubz.AIRTIME_NETWORKS = AIRTIME_NETWORKS;
+Mozosubz.MIN_AIRTIME_AMOUNT = MIN_AIRTIME_AMOUNT;
+
+module.exports = { Mozosubz, MozosubzError, DATA_SERVICES, AIRTIME_NETWORKS, MIN_AIRTIME_AMOUNT };