Otpiq NPM | npm.io

OTPiq Client

A TypeScript/JavaScript client for the OTPiq SMS service. This package provides a clean and type-safe way to interact with the OTPiq API, supporting verification codes, custom messages, sender IDs, and message tracking.

Features

📱 SMS verification code sending
💬 Custom message support with sender IDs
🎲 Automatic or custom verification code generation
✨ WhatsApp & Telegram message support
✅ Full TypeScript support
🔄 SMS status tracking
💳 Credit management
⚡ Promise-based API
🛡️ Comprehensive error handling

Installation

npm install otpiq
# or
yarn add otpiq
# or
pnpm add otpiq

Quick Start

import { OTPiqClient } from "otpiq";

// Initialize the client
const client = new OTPiqClient({
  apiKey: "your_api_key_here",
});

// Send verification SMS with auto-generated code
const response = await client.sendSMS({
  phoneNumber: "9647701234567",
  smsType: "verification",
});

console.log("Generated code:", response.verificationCode);
console.log("SMS ID:", response.smsId);

// Send custom message with sender ID
const customResponse = await client.sendSMS({
  phoneNumber: "9647701234567",
  smsType: "custom",
  customMessage: "Welcome to our service!",
  senderId: "MyBrand",
});

Handling Verification Codes

Auto-generated Codes

When no verification code is provided, the client automatically generates one:

const response = await client.sendSMS({
  phoneNumber: "9647701234567",
  smsType: "verification",
  digitCount: 6, // Optional: customize length (default: 6)
});

const generatedCode = response.verificationCode;

Custom Verification Codes

You can provide your own verification code:

const response = await client.sendSMS({
  phoneNumber: "9647701234567",
  smsType: "verification",
  verificationCode: "123456",
});

Sending Custom Messages

Custom messages require a sender ID and will automatically use the SMS provider:

const response = await client.sendSMS({
  phoneNumber: "9647701234567",
  smsType: "custom",
  customMessage: "Your appointment is confirmed for tomorrow at 2 PM",
  senderId: "MyBrand",
});

Managing Sender IDs

Retrieve all your approved sender IDs:

const senderIds = await client.getSenderIds();
console.log("Available sender IDs:", senderIds.senderIds);

Next.js Example

Here's a complete Next.js API route implementation:

// pages/api/send-verification.ts
import { OTPiqClient } from "otpiq";
import type { NextApiRequest, NextApiResponse } from "next";

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== "POST") {
    return res.status(405).json({ message: "Method not allowed" });
  }

  const client = new OTPiqClient({
    apiKey: process.env.OTPIQ_API_KEY!,
  });

  try {
    const response = await client.sendSMS({
      phoneNumber: req.body.phoneNumber,
      smsType: "verification",
    });

    // Store the code securely (e.g., in your database or session)
    await storeVerificationCode({
      phoneNumber: req.body.phoneNumber,
      code: response.verificationCode,
      smsId: response.smsId,
    });

    res.status(200).json({
      message: "Verification code sent",
      smsId: response.smsId,
    });
  } catch (error) {
    if (error instanceof Error) {
      res.status(500).json({ error: error.message });
    } else {
      res.status(500).json({ error: "An unknown error occurred" });
    }
  }
}

API Reference

Initialization

const client = new OTPiqClient({
  apiKey: "your_api_key_here",
});

Methods

Send SMS

// Verification SMS with auto-generated code
const response = await client.sendSMS({
  phoneNumber: "9647701234567",
  smsType: "verification",
  digitCount: 6, // Optional
  provider: "auto", // Optional: 'auto' | 'sms' | 'whatsapp' | 'telegram'
});

// Verification SMS with custom code
const response = await client.sendSMS({
  phoneNumber: "9647701234567",
  smsType: "verification",
  verificationCode: "123456",
  provider: "whatsapp", // Optional
});

// Custom message with sender ID
const response = await client.sendSMS({
  phoneNumber: "9647701234567",
  smsType: "custom",
  customMessage: "Your message here",
  senderId: "MyBrand",
});

Track SMS Status

const status = await client.trackSMS("sms-1234567890");
console.log("Delivery status:", status.status);
console.log("Cost:", status.cost);

Get Project Info

const info = await client.getProjectInfo();
console.log("Project name:", info.projectName);
console.log("Available credits:", info.credit);

Get Sender IDs

const senderIds = await client.getSenderIds();
console.log("Available sender IDs:", senderIds.senderIds);

Type Definitions

SendSMSOptions

interface SendSMSOptions {
  phoneNumber: string;
  smsType: "verification" | "custom";
  verificationCode?: string | number;
  customMessage?: string;
  senderId?: string;
  provider?: "auto" | "sms" | "whatsapp";
  digitCount?: number;
}

SMSResponse

interface SMSResponse {
  message: string;
  smsId: string;
  remainingCredit: number;
  verificationCode?: string; // Only included for verification SMS
}

SMSTrackingResponse

interface SMSTrackingResponse {
  status: "pending" | "delivered" | "failed";
  phoneNumber: string;
  smsId: string;
  cost: number;
}

SenderId

interface SenderId {
  id: string;
  senderId: string;
  status: "accepted" | "pending";
  createdAt: string;
}

Error Handling

The package includes built-in error classes for common API errors:

import { OTPiqError, InsufficientCreditError, RateLimitError } from "otpiq";

try {
  await client.sendSMS({
    phoneNumber: "9647701234567",
    smsType: "verification",
  });
} catch (error) {
  if (error instanceof InsufficientCreditError) {
    console.log(
      `Need more credits! Required: ${error.requiredCredit}, ` +
        `Available: ${error.yourCredit}`
    );
  } else if (error instanceof RateLimitError) {
    console.log(
      `Rate limit exceeded. Try again in ${error.waitMinutes} minutes. ` +
        `Limit: ${error.maxRequests} requests per ${error.timeWindowMinutes} minutes`
    );
  } else if (error instanceof OTPiqError) {
    console.log("API Error:", error.message);
  }
}

Best Practices

Error Handling: Always implement proper error handling to catch and handle specific error types.
Verification Codes: Never send verification codes back to the client. Store them securely server-side.
Provider Selection: Use 'auto' provider for verification codes unless you have a specific reason not to.
Custom Messages: Always use an approved sender ID when sending custom messages.
Environment Variables: Store your API key in environment variables, never hardcode it.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.