Mobiska SDK

A TypeScript SDK for interacting with Mobiska's SMS and Payment APIs.

Installation

npm install @mobiska/client
# or
yarn add @mobiska/client
# or
pnpm add @mobiska/client
# or
bun add @mobiska/client
# or
deno add npm:@mobiska/client

Configuration

Before using the SDK, you need to initialize it with your Mobiska credentials:

NB: Credentials can be passed via env, meaning no arguments will have to be passed into the initialization functions

MOBISKA_USER_NAME=
MOBISKA_PASSWORD=
MOBISKA_SERVICE_ID=
MOBISKA_SMS_SENDER_ID=

MOBISKA_API_URL= # We pass by default, a better provision would be provided soon

import { InitSMS, InitPayment } from "@mobiska/client";

// Initialize SMS client with env
const smsClient = InitSMS();

// Initialize SMS client without env / manually
const smsClient = InitSMS({
  MOBISKA_USER_NAME: "your_username",
  MOBISKA_PASSWORD: "your_password",
  MOBISKA_SERVICE_ID: "your_service_id",
  SMS_SENDER_ID: "your_sender_id",
});

// Initialize Payment client env
const paymentClient = InitPayment();

// Initialize Payment client without env / manually
const paymentClient = InitPayment({
  MOBISKA_USER_NAME: "your_username",
  MOBISKA_PASSWORD: "your_password",
  MOBISKA_SERVICE_ID: "your_service_id",
});

Advanced init options

Both InitSMS and InitPayment accept an optional second argument with request controls: { timeout?: number; retryCount?: number; retryDelay?: number; }

// Example type for clarity
type ClientOptions = {
  timeout?: number;
  retryCount?: number;
  retryDelay?: number;
};

// Using env-based config + options (pass undefined for the first arg to use env)
const smsClient = InitSMS(undefined, {
  timeout: 10_000,
  retryCount: 3,
  retryDelay: 500,
});

// Using manual config + options
const paymentClient = InitPayment(
  {
    MOBISKA_USER_NAME: "your_username",
    MOBISKA_PASSWORD: "your_password",
    MOBISKA_SERVICE_ID: "your_service_id",
  },
  { timeout: 8_000, retryCount: 2, retryDelay: 400 }
);

SMS Features

Send SMS

Send SMS messages to recipients:

const response = await smsClient.sendSMS({
  phone: "recipient_phone_number",
  message: "Your message content",
  responseMessage: "Optional custom response message",
});

SMS Balance Alert Feature

The SDK includes an automatic SMS balance alert system that monitors your balance and sends alerts when it falls below a specified threshold.

Parameters:

• alertLimit (optional): The minimum balance threshold. When balance falls below this value, alerts will be triggered.
• alertPhones (optional): Array of phone numbers to receive balance alerts.
• alertDelay (optional): Minimum time in milliseconds between alerts (default: 10 minutes / 600,000ms). This prevents alert spam.

How it works:

1. When you send an SMS, the SDK automatically checks your remaining balance.
2. If the balance is below alertLimit and alertPhones are configured, an alert SMS is sent.
3. The alert system uses rate limiting to prevent spam - alerts are only sent if enough time has passed since the last alert (controlled by alertDelay).
4. Alert state is stored locally to track when the last alert was sent.

Example:

const response = await smsClient.sendSMS({
  phone: "recipient_phone_number",
  message: "Your message content",
  alertLimit: 100, // Alert when balance is below 100
  alertPhones: ["+1234567890", "+0987654321"], // Numbers to receive alerts
  alertDelay: 600000, // Minimum 10 minutes between alerts (optional, defaults to 10 mins)
  responseMessage: "Optional custom response message",
});

Alert Message Format: When an alert is triggered, the recipients in alertPhones will receive an SMS with the format:

Alert: Low on credit, balance left {current_balance}!

Check SMS Balance

Check your SMS balance for a specific date:

const balance = await smsClient.checkBalance(new Date());
// Returns: { sms_balance, service_id }

Payment Features

Make Payment

Initiate a payment transaction:

Parameters

{
  "service_id": 0,
  "reference": "",
  "nickname": "",
  "transaction_id": "",
  "trans_type": "",
  "customer_number": "",
  "nw": "",
  "amount": 0,
  "payment_option": "",
  "callback_url": "",
  "currency_code": "",
  "currency_val": 1,
  "request_time": ""
}

const payment = await paymentClient.makePayment({
  // Payment details
  amount: 1000,
  phone: "customer_phone_number",
  // Additional optional parameters
  responseMessage: "Optional custom response message",
});

Check Payment Status

Verify the status of a payment transaction:

const status = await paymentClient.checkPaymentStatus("transaction_id");
// Returns: { transaction_id, status_desc, status }

Payment Account Lookup

Look up payment account details:

const account = await paymentClient.paymentAccountLookup({
  // Account lookup parameters
  phone: "account_phone_number",
});
// Returns: { name }

Type Safety

This SDK is written in TypeScript and includes comprehensive type definitions for all methods and parameters, providing excellent IDE support and compile-time type checking.

Response Handling

All API methods return a standardized response format that includes:

• Success/failure status
• Response data (if applicable)
• Error information (if any)

Error Handling

The SDK includes built-in error handling. All API calls are wrapped in a try-catch block and will return appropriate error messages if something goes wrong.