OTPiq Client

https://www.npmjs.com/package/otpiq
Admin
A TypeScript/JavaScript client for the OTPiq SMS service that provides a clean and type-safe way to...
Tokens:18,269
Snippets:140
Trust Score:9.6
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install OTPiq Client

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependents

Instructions for installing the OTPiq client package using npm, yarn, or pnpm.

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

--------------------------------

### Getting Project Information

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependencies

Retrieve details about the project, including its name and available credit.

```APIDOC
## Get Project Info

### Description
Retrieves information about the current project, such as its name and available credit balance.

### Method
GET (implied by `client.getProjectInfo`)

### Endpoint
`/project/info` (hypothetical)

### Parameters
None

### Request Example
(No explicit request body or query parameters for this SDK method)

### Response (ProjectInfo)
#### Success Response (200)
- **projectName** (string) - The name of the project.
- **credit** (number) - The available credit balance for the project.

#### Response Example
```json
{
  "projectName": "npmjs_package_otpiq",
  "credit": 950
}
```
```

--------------------------------

### Webhook Setup for Delivery Status

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependencies

Configure webhooks to receive real-time delivery status updates for your messages.

```APIDOC
## Webhook Setup for Delivery Status

### Description
Configure webhooks to receive real-time delivery status updates for your messages. This allows your application to be notified automatically when a message is sent, delivered, or fails.

### Method
POST (when sending a message with `deliveryReport` option enabled)

### Endpoint
`/send` (hypothetical, endpoint used for sending messages)

### Parameters
#### Request Body (within `sendSMS` options)
- **deliveryReport** (object) - Required - Configuration for delivery reports.
  - **webhookUrl** (string) - Required - HTTPS URL to receive status updates.
  - **deliveryReportType** ("all" | "final") - Optional - Specifies the types of status updates to receive. Defaults to 'all'.
    - `"all"`: Receive all status updates (sent, delivered, failed).
    - `"final"`: Receive only final status (delivered or failed).
  - **webhookSecret** (string) - Optional - A secret key for webhook authentication. Use this for security.

### Request Example (Sending SMS with Webhook Config)
```json
{
  "phoneNumber": "9647701234567",
  "smsType": "verification",
  "deliveryReport": {
    "webhookUrl": "https://your-app.com/webhooks/sms-status",
    "deliveryReportType": "all",
    "webhookSecret": "your_secret_123"
  }
}
```

### Webhook Payload Structure (Received by your endpoint)
#### Description
Your webhook endpoint will receive POST requests with the following JSON payload when a message status changes.

#### Parameters
- **smsId** (string) - The unique identifier of the SMS.
- **deliveryReportType** ("all" | "final") - The type of report requested.
- **isFinal** (boolean) - True if this is the final status update for the message.
- **channel** ("sms" | "whatsapp" | "telegram") - The channel through which the message was sent.
- **status** ("sent" | "delivered" | "failed") - The current status of the message.
- **senderId** (string) - Optional. Included only for SMS sent with a custom sender ID.
- **reason** (string) - Optional. Included only when the status is 'failed', providing details about the failure.

#### Payload Example (Delivered)
```json
{
  "smsId": "sms-1234567890",
  "deliveryReportType": "all",
  "isFinal": true,
  "channel": "sms",
  "status": "delivered",
  "senderId": "MyBrand"
}
```

#### Payload Example (Failed)
```json
{
  "smsId": "sms-abcdefghij",
  "deliveryReportType": "final",
  "isFinal": true,
  "channel": "whatsapp",
  "status": "failed",
  "reason": "Invalid phone number format"
}
```

### Example Webhook Implementation (Express.js)
```javascript
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/sms-status', (req, res) => {
  const payload = req.body;
  const webhookSecret = req.headers['x-otpiq-webhook-secret'];
  
  // Verify webhook secret if configured
  if (process.env.WEBHOOK_SECRET && webhookSecret !== process.env.WEBHOOK_SECRET) {
    return res.status(401).send('Unauthorized');
  }
  
  // Process the webhook
  console.log(`SMS ${payload.smsId} status: ${payload.status}`);
  
  if (payload.status === 'delivered') {
    // Handle successful delivery
    console.log(`Message delivered to ${payload.phoneNumber}`);
  } else if (payload.status === 'failed') {
    console.error(`Delivery failed for SMS ${payload.smsId}: ${payload.reason}`);
    // Handle failure
  }
  
  // Respond quickly to acknowledge receipt
  res.status(200).send('OK');
});

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Webhook server listening on port ${PORT}`);
});
```

### Security Best Practices
1.  **Use HTTPS**: Always use HTTPS for your `webhookUrl` to ensure secure communication.
2.  **Validate Secret**: Implement webhook secret validation using the `webhookSecret` provided during setup. Check the incoming request's header against your stored secret.
3.  **Respond Quickly**: Your webhook endpoint should respond to the POST request within 10 seconds to prevent timeouts and potential retries.
4.  **Idempotency**: Design your webhook handler to be idempotent, meaning processing the same webhook payload multiple times should have the same effect as processing it once. This handles potential duplicate webhook deliveries.
5.  **Logging**: Log all incoming webhook requests and their payloads for debugging and auditing purposes.
```

--------------------------------

### Getting Credit Balance

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependencies

Retrieve the current available credit balance for your account.

```APIDOC
## Get Credit Balance

### Description
Fetches the current available SMS credit balance for your account.

### Method
GET (implied by `client.getCredits`)

### Endpoint
`/credits` (hypothetical)

### Parameters
None

### Request Example
(No explicit request body or query parameters for this SDK method)

### Response
#### Success Response (200)
A number representing the available credit balance in IQD.

#### Response Example
```json
950
```
```

--------------------------------

### Getting Sender IDs

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependencies

Retrieve a list of available sender IDs associated with your account.

```APIDOC
## Get Sender IDs

### Description
Fetches a list of all sender IDs that are available or have been approved for your account.

### Method
GET (implied by `client.getSenderIds`)

### Endpoint
`/senderids` (hypothetical)

### Parameters
None

### Request Example
(No explicit request body or query parameters for this SDK method)

### Response (SenderIdList)
#### Success Response (200)
- **data** (array of SenderId objects) - A list containing details of each sender ID.
  - **_id** (string) - The unique internal ID of the sender ID entry.
  - **senderId** (string) - The actual sender ID string.
  - **status** ("accepted" | "pending" | "rejected") - The approval status of the sender ID.
  - **pricePerSms** (object) - Pricing details for different carriers.
    - **korekTelecom** (number) - Price per SMS for Korek Telecom.
    - **asiaCell** (number) - Price per SMS for AsiaCell.
    - **zainIraq** (number) - Price per SMS for Zain Iraq.
    - **others** (number) - Price per SMS for other carriers.

#### Response Example
```json
{
  "data": [
    {
      "_id": "sender-id-abc",
      "senderId": "MyCompany",
      "status": "accepted",
      "pricePerSms": {
        "korekTelecom": 30,
        "asiaCell": 35,
        "zainIraq": 32,
        "others": 40
      }
    },
    {
      "_id": "sender-id-def",
      "senderId": "Alerts",
      "status": "pending",
      "pricePerSms": {
        "korekTelecom": 30,
        "asiaCell": 35,
        "zainIraq": 32,
        "others": 40
      }
    }
  ]
}
```
```

--------------------------------

### Webhook Implementation Example (Express.js)

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependents

An example implementation of a webhook endpoint using Express.js to receive and process SMS delivery status updates. Includes security validation using a webhook secret.

```javascript
app.post('/webhooks/sms-status', (req, res) => {
  const payload: WebhookPayload = req.body;
  const webhookSecret = req.headers['x-otpiq-webhook-secret'];
  
  // Verify webhook secret if configured
  if (webhookSecret !== process.env.WEBHOOK_SECRET) {
    return res.status(401).send('Unauthorized');
  }
  
  // Process the webhook
  console.log(`SMS ${payload.smsId} status: ${payload.status}`);
  
  if (payload.status === 'delivered') {
    // Handle successful delivery
  } else if (payload.status === 'failed') {
    console.error(`Delivery failed: ${payload.reason}`);
    // Handle failure
  }
  
  // Always respond quickly (within 10 seconds)
  res.status(200).send('OK');
});
```

--------------------------------

### Send Verification via WhatsApp and Telegram

Source: https://context7.com/context7/npmjs_package_otpiq/llms.txt

Provides examples for sending verification codes specifically through WhatsApp and Telegram. It demonstrates using dedicated methods for each platform, allowing for optional custom codes or auto-generation, and logs the SMS ID and verification code from the responses.

```javascript
// Send via WhatsApp
const whatsappResponse = await client.sendWhatsApp({
  phoneNumber: "9647701234567",
  smsType: "verification",
  verificationCode: "567890"  // optional, auto-generates if omitted
});

console.log("WhatsApp verification sent:", whatsappResponse.smsId);
console.log("Code:", whatsappResponse.verificationCode);

// Send via Telegram
const telegramResponse = await client.sendTelegram({
  phoneNumber: "9647701234567",
  smsType: "verification",
  digitCount: 8
});

console.log("Telegram verification sent:", telegramResponse.smsId);
console.log("Code:", telegramResponse.verificationCode);
```

--------------------------------

### Get Sender IDs

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependencies

Retrieves a list of all approved sender IDs associated with your account.

```APIDOC
## Get Sender IDs

Retrieves a list of all your approved sender IDs.

### Method

`GET` (implicitly through the client method)

### Endpoint

N/A (Client-side method)

### Request Example

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

### Response

#### Success Response (200)

- **data** (array) - An array of strings, where each string is an approved sender ID.

#### Response Example

```json
{
  "data": ["MyBrand", "ServiceAlert", "OTP-Verify"]
}
```
```

--------------------------------

### Get Credit Balance and SMS Status

Source: https://www.npmjs.com/package/otpiq/index_activetab=code

Retrieve the available credit balance and the status of a specific SMS. The `getCredits` method returns the remaining credit, while `getSMSStatus` (an alias for `trackSMS`) provides the delivery status of an SMS.

```javascript
const credits = await client.getCredits();
console.log(`Available credits: ${credits} IQD`);

const status = await client.getSMSStatus("sms-1234567890");
```

--------------------------------

### Get Project Info

Source: https://www.npmjs.com/package/otpiq/index

Retrieves information about the current project, including its name and available credit balance.

```APIDOC
## Get Project Info

### Method

`GET`

### Endpoint

`/project/info`

### Response

#### Success Response (200)

- **projectName** (string) - The name of the project.
- **credit** (number) - The available credit balance for the project.

#### Response Example

```json
{
  "projectName": "npmjs_package_otpiq",
  "credit": 100.50
}
```
```

--------------------------------

### Get Project Info

Source: https://www.npmjs.com/package/otpiq/index_activetab=readme

Retrieves information about the current project, including its name and available credits.

```APIDOC
## Get Project Info

### Description

This endpoint retrieves information about the current project, such as its name and available credit balance.

### Method

GET (or client method equivalent)

### Endpoint

N/A (Client method)

### Response

#### Success Response (200)

- **projectName** (string) - The name of the project.
- **credit** (number) - The remaining credit balance for the project.

### Request Example

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

### Response Example

```json
{
  "projectName": "MyProject",
  "credit": 100.50
}
```
```

--------------------------------

### Configure otpiq Webhooks for Delivery Reports

Source: https://context7.com/context7/npmjs_package_otpiq/llms.txt

Set up webhooks to receive asynchronous SMS delivery status updates. This includes sending an SMS with a specified webhook URL and secret, and an example Express.js handler for processing incoming webhook payloads.

```javascript
// Send SMS with webhook delivery reports
const response = await client.sendSMS({
  phoneNumber: "9647701234567",
  smsType: "verification",
  deliveryReport: {
    webhookUrl: "https://your-app.com/webhooks/sms-status",
    deliveryReportType: "all",  // "all" or "final"
    webhookSecret: "your_secret_key_123"
  }
});

console.log("SMS sent with webhook:", response.smsId);

// Webhook handler (Express.js example)
import express from "express";
const app = express();

app.post('/webhooks/sms-status', express.json(), (req, res) => {
  const payload = req.body;
  const secret = req.headers['x-otpiq-webhook-secret'];

  if (secret !== process.env.WEBHOOK_SECRET) {
    return res.status(401).send('Unauthorized');
  }

  console.log(`SMS ${payload.smsId} status: ${payload.status}`);
  console.log(`Channel: ${payload.channel}`);
  console.log(`Is final: ${payload.isFinal}`);

  if (payload.status === 'delivered') {
    // Update database
  } else if (payload.status === 'failed') {
    console.error(`Failed: ${payload.reason}`);
  }

  res.status(200).send('OK');
});
```

--------------------------------

### Handle Verification Codes with OTPiq Client (TypeScript/JavaScript)

Source: https://www.npmjs.com/package/otpiq/index_activetab=versions

Provides examples for sending verification SMS using the OTPiq client. Demonstrates both auto-generated codes (with optional digit count customization) and using a pre-defined custom verification code. The client handles code generation if not provided.

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

const generatedCode = response.verificationCode;

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

--------------------------------

### Get Project Information

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependents

Retrieves information about the current project, including its name and available credit balance. This method does not require any parameters.

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

--------------------------------

### Get Sender IDs

Source: https://www.npmjs.com/package/otpiq/index

Fetches a list of available sender IDs associated with your account.

```APIDOC
## Get Sender IDs

### Method

`GET`

### Endpoint

`/sender-ids`

### Response

#### Success Response (200)

- **data** (array) - An array of sender ID objects.
  - Each object contains:
    - **_id** (string) - The unique identifier of the sender ID.
    - **senderId** (string) - The sender ID string.
    - **status** (string) - The status of the sender ID (accepted, pending, rejected).
    - **pricePerSms** (object) - Pricing details per SMS for different carriers.

#### Response Example

```json
{
  "data": [
    {
      "_id": "sender-id-1",
      "senderId": "MyBrand",
      "status": "accepted",
      "pricePerSms": {
        "korekTelecom": 0.04,
        "asiaCell": 0.03,
        "zainIraq": 0.04,
        "others": 0.05
      }
    }
  ]
}
```
```

--------------------------------

### Get Sender IDs

Source: https://www.npmjs.com/package/otpiq/index_activetab=readme

Retrieves a list of available sender IDs associated with your account.

```APIDOC
## Get Sender IDs

### Description

This endpoint retrieves a list of sender IDs that are available for use with your account.

### Method

GET (or client method equivalent)

### Endpoint

N/A (Client method)

### Response

#### Success Response (200)

- **data** (array) - An array of sender ID objects.
  - Each object contains details about a sender ID, including:
    - **_id** (string) - The unique identifier for the sender ID.
    - **senderId** (string) - The sender ID string.
    - **status** (string) - The status of the sender ID (`accepted`, `pending`, `rejected`).
    - **pricePerSms** (object) - Pricing details per SMS for different carriers.
      - **korekTelecom** (number)
      - **asiaCell** (number)
      - **zainIraq** (number)
      - **others** (number)

### Request Example

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

### Response Example

```json
{
  "data": [
    {
      "_id": "sender-id-1",
      "senderId": "MyBrand",
      "status": "accepted",
      "pricePerSms": {
        "korekTelecom": 0.04,
        "asiaCell": 0.045,
        "zainIraq": 0.042,
        "others": 0.05
      }
    }
  ]
}
```
```

--------------------------------

### Get Sender IDs API

Source: https://www.npmjs.com/package/otpiq/index_activetab=readme

Retrieve a list of all approved sender IDs associated with your account.

```APIDOC
## Get Sender IDs

### Description
Retrieves a list of all approved sender IDs available for your account.

### Method
`client.getSenderIds()`

### Response
#### Success Response (200)
- **data** (array) - An array of strings, where each string is an approved sender ID.

#### Response Example
```json
{
  "data": ["MyBrand", "ServiceAlert", "OTPVerify"]
}
```
```

--------------------------------

### Get Credit Balance

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependents

Retrieves the current credit balance available for the account. This method does not require any parameters and returns the balance in IQD.

```javascript
const credits = await client.getCredits();
console.log(`Available credits: ${credits} IQD`);
```

--------------------------------

### Handle OTPiq API Errors in JavaScript

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependents

Demonstrates how to catch and handle various specific error types thrown by the OTPiq API, such as InsufficientCreditError, RateLimitError, and ValidationError. This code requires the 'otpiq' package to be installed.

```javascript
import {
  OTPiqError,
  InsufficientCreditError,
  RateLimitError,
  SpendingThresholdError,
  SenderIdError,
  TrialModeError,
  ValidationError,
  NotFoundError,
  UnauthorizedError
} 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}, Can cover: ${error.canCover}`
    );
  } 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 SpendingThresholdError) {
    console.log(
      `Spending threshold exceeded! Current: ${error.currentSpending}, ` +
        `Threshold: ${error.spendingThreshold}, Transaction cost: ${error.cost}`
    );
  } else if (error instanceof TrialModeError) {
    console.log("Trial mode: Can only send to your own phone number");
  } else if (error instanceof SenderIdError) {
    console.log("Sender ID error:", error.message);
  } else if (error instanceof ValidationError) {
    console.log("Validation error:", error.message);
  } else if (error instanceof NotFoundError) {
    console.log("Not found:", error.message);
  } else if (error instanceof UnauthorizedError) {
    console.log("Unauthorized:", error.message);
  } else if (error instanceof OTPiqError) {
    console.log("API Error:", error.message);
  }
}
```

--------------------------------

### Get Credit Balance and SMS Status

Source: https://www.npmjs.com/package/otpiq/index

Allows retrieving the available credit balance and the status of a specific SMS using its ID. The `getCredits` method returns the remaining credit, while `getSMSStatus` (aliased as `trackSMS`) provides delivery details.

```javascript
const credits = await client.getCredits();
console.log(`Available credits: ${credits} IQD`);
```

```javascript
const status = await client.getSMSStatus("sms-1234567890");
```

--------------------------------

### Get SMS Status (Alias)

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependents

An alias for the `trackSMS` method, used to retrieve the delivery status of an SMS by its ID.

```javascript
const status = await client.getSMSStatus("sms-1234567890");
```

--------------------------------

### OTPiq Client Initialization

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependencies

Initializes the OTPiq Client with your API key.

```APIDOC
## Initialization

```typescript
import { OTPiqClient } from "otpiq";

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

### Parameters

- **apiKey** (string) - Required - Your unique OTPiq API key.
```

--------------------------------

### Initialize OTPiq Client and Send SMS

Source: https://context7.com/context7/npmjs_package_otpiq/llms.txt

Demonstrates how to initialize the OTPiq client using an API key and send a verification SMS. It includes error handling for the API call and logs the generated verification code, SMS ID, cost, remaining credit, and payment type from the response.

```javascript
import { OTPiqClient } from "otpiq";

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

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

  console.log("Generated code:", response.verificationCode);
  console.log("SMS ID:", response.smsId);
  console.log("Cost:", response.cost, "IQD");
  console.log("Remaining credit:", response.remainingCredit, "IQD");
  console.log("Payment type:", response.paymentType);
} catch (error) {
  console.error("Failed to send SMS:", error.message);
}
```

--------------------------------

### OTPiq Client Initialization - TypeScript/JavaScript

Source: https://www.npmjs.com/package/otpiq/index_activetab=code

This is the basic structure for initializing the OTPiqClient. You need to provide your API key during instantiation. This client object is then used to interact with the OTPiq API.

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

--------------------------------

### OTPIQ Client API Reference - Initialization and Methods

Source: https://www.npmjs.com/package/otpiq/index

Documents the core API of the OTPiq Client, including how to initialize the client with an API key and detailed usage for the `sendSMS` method with various options like `smsType`, `verificationCode`, `customMessage`, `senderId`, `digitCount`, and `provider`.

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

// 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 responseWithCustomCode = await client.sendSMS({
  phoneNumber: "9647701234567",
  smsType: "verification",
  verificationCode: "123456",
  provider: "whatsapp", // Optional
});

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

--------------------------------

### Initialize OTPiq Client

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependents

Demonstrates how to initialize the OTPiqClient with an API key.

```typescript
import { OTPiqClient } from "otpiq";

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

--------------------------------

### Initialize OTPiq Client and Send SMS (TypeScript/JavaScript)

Source: https://www.npmjs.com/package/otpiq/index_activetab=versions

Demonstrates how to initialize the OTPiqClient with an API key and send verification SMS. It shows how to access the generated code, SMS ID, and cost from the response. Supports auto-generated codes and custom messages with sender IDs.

```typescript
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);
console.log("Cost:", response.cost, "IQD");
console.log("Remaining credit:", response.remainingCredit, "IQD");

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

--------------------------------

### OTPiq Client Initialization

Source: https://www.npmjs.com/package/otpiq/index_activetab=readme

Initialize the OTPiq client with your API key.

```APIDOC
## Initialization

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

--------------------------------

### Handle verification codes with OTPiq Client

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependencies

Illustrates two ways to handle verification codes: automatically generating them or providing a custom code during SMS sending. It shows how to specify the digit count for auto-generated codes.

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

const generatedCode = response.verificationCode;

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

--------------------------------

### Check otpiq Credit Balance and Project Info

Source: https://context7.com/context7/npmjs_package_otpiq/llms.txt

Retrieve account credit balance and detailed project information for billing purposes. 'getCredits' returns only the available credits, while 'getProjectInfo' provides project name, credit balance, ID, and payment type.

```javascript
// Get just the credit balance
const credits = await client.getCredits();
console.log(`Available credits: ${credits} IQD`);

// Get full project information
const info = await client.getProjectInfo();
console.log("Project name:", info.projectName);
console.log("Available credits:", info.credit, "IQD");
console.log("Project ID:", info._id);
console.log("Payment type:", info.paymentType);
```

--------------------------------

### OTPiq Client Initialization and Send SMS Method Reference (TypeScript/JavaScript)

Source: https://www.npmjs.com/package/otpiq/index_activetab=versions

API reference for the OTPiq client, detailing initialization with an API key and the parameters for the `sendSMS` method. It covers options for verification SMS (auto-generated or custom code, digit count, provider) and custom messages with sender IDs.

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

// 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 (always uses SMS provider)
const response = await client.sendSMS({
  phoneNumber: "9647701234567",
  smsType: "custom",
  customMessage: "Your message here",
  senderId: "MyBrand",
});
```

--------------------------------

### OTPiq Client API Reference - sendSMS method

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependencies

Details the different ways to use the `sendSMS` method, including sending verification SMS with auto-generated or custom codes, and sending custom messages with sender IDs. It also shows optional parameters like `digitCount` and `provider`.

```typescript
// 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 responseCustom = await client.sendSMS({
  phoneNumber: "9647701234567",
  smsType: "verification",
  verificationCode: "123456",
  provider: "whatsapp", // Optional
});

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

--------------------------------

### Sending Messages

Source: https://www.npmjs.com/package/otpiq/index_activetab=dependencies

Convenient methods for sending messages via WhatsApp, Telegram, or custom SMS, along with options for verification codes and delivery reports.

```APIDOC
## Sending Messages

### Description
Provides methods to send messages through various channels like WhatsApp, Telegram, and custom SMS. Supports verification codes and detailed delivery reporting.

### Method
POST (implied by `client.send...` methods)

### Endpoint
`/send` (hypothetical, as these are client-side SDK methods)

### Parameters
#### Request Body (for `sendSMS` or similar)
- **phoneNumber** (string) - Required - The recipient's phone number.
- **smsType** ("verification" | "custom") - Required - Type of SMS to send.
- **verificationCode** (string | number) - Optional - The verification code to send (for `smsType: 'verification'`).
- **customMessage** (string) - Optional - The custom message content (for `smsType: 'custom'`).
- **senderId** (string) - Optional - The sender ID to use for the message.
- **provider** ("auto" | "sms" | "whatsapp" | "telegram") - Optional - The message provider to use. Defaults to 'auto'.
- **digitCount** (number) - Optional - The number of digits for the verification code.
- **deliveryReport** (object) - Optional - Configuration for delivery reports and webhooks.
  - **webhookUrl** (string) - Required - HTTPS URL to receive status updates.
  - **deliveryReportType** ("all" | "final") - Optional - Specifies the types of status updates to receive. Defaults to 'all'.
  - **webhookSecret** (string) - Optional - A secret key for webhook authentication.

### Request Example (WhatsApp Verification)
```json
{
  "phoneNumber": "9647701234567",
  "smsType": "verification",
  "verificationCode": "123456"
}
```

### Request Example (Custom SMS)
```json
{
  "phoneNumber": "9647701234567",
  "smsType": "custom",
  "customMessage": "Your order is ready for pickup!",
  "senderId": "MyBrand"
}
```

### Request Example (SMS with Delivery Report)
```json
{
  "phoneNumber": "9647701234567",
  "smsType": "verification",
  "deliveryReport": {
    "webhookUrl": "https://your-app.com/webhooks/sms-status",
    "deliveryReportType": "all",
    "webhookSecret": "your_secret_123"
  }
}
```

### Response (SMSResponse)
#### Success Response (200)
- **message** (string) - Confirmation message.
- **smsId** (string) - Unique identifier for the sent SMS.
- **remainingCredit** (number) - The remaining credit balance after sending the message.
- **cost** (number) - The cost of the sent SMS.
- **canCover** (boolean) - Indicates if the credit was sufficient for the message.
- **verificationCode** (string) - Included only for verification SMS.

#### Response Example
```json
{
  "message": "SMS sent successfully",
  "smsId": "sms-1234567890",
  "remainingCredit": 950,
  "cost": 50,
  "canCover": true,
  "verificationCode": "123456"
}
```
```

--------------------------------

### TypeScript Interface for DeliveryReport

Source: https://www.npmjs.com/package/otpiq/index_activetab=code

Defines the configuration for delivery reports, including the webhook URL, the type of delivery report (all or final), and an optional webhook secret for security.

```typescript
interface DeliveryReport {
  webhookUrl: string;
  deliveryReportType?: "all" | "final";
  webhookSecret?: string;
}
```

--------------------------------

### Retrieve and Process Sender IDs

Source: https://context7.com/context7/npmjs_package_otpiq/llms.txt

Demonstrates how to retrieve a list of all approved sender IDs and their associated carrier-specific pricing information. The output includes the total number of sender IDs, and for each sender, its status and pricing for Korek, AsiaCell, Zain, and other carriers.

```javascript
const senderIds = await client.getSenderIds();

console.log("Total sender IDs:", senderIds.data.length);

senderIds.data.forEach(sender => {
  console.log("Sender ID:", sender.senderId);
  console.log("Status:", sender.status);
  console.log("Pricing:");
  console.log("  Korek:", sender.pricePerSms.korekTelecom, "IQD");
  console.log("  AsiaCell:", sender.pricePerSms.asiaCell, "IQD");
  console.log("  Zain:", sender.pricePerSms.zainIraq, "IQD");
  console.log("  Others:", sender.pricePerSms.others, "IQD");
});
```

--------------------------------

### TypeScript Interface for SenderId

Source: https://www.npmjs.com/package/otpiq/index_activetab=code

Represents a sender ID object, including its unique ID, the sender ID string, its status (accepted, pending, or rejected), and the price per SMS for different telecom providers.

```typescript
interface SenderId {
  _id: string;
  senderId: string;
  status: "accepted" | "pending" | "rejected";
  pricePerSms: {
    korekTelecom: number;
    asiaCell: number;
    zainIraq: number;
    others: number;
  };
}
```

--------------------------------

### TypeScript Interface for SMSResponse

Source: https://www.npmjs.com/package/otpiq/index_activetab=code

Represents the response received after sending an SMS. Includes message details, SMS ID, remaining credit, cost, payment type, and optionally the verification code.

```typescript
interface SMSResponse {
  message: string;
  smsId: string;
  remainingCredit: number;
  cost: number;
  canCover: boolean;
  paymentType: "prepaid" | "postpaid";
  verificationCode?: string; // Only included for verification SMS
}
```

--------------------------------

### Convenience Methods

Source: https://www.npmjs.com/package/otpiq/index_activetab=readme

Provides simplified methods for sending messages via different providers and retrieving account information.

```APIDOC
## Convenience Methods

### Send via WhatsApp

This method sends a verification SMS via WhatsApp.

**Method:** POST (or equivalent client method)

**Endpoint:** N/A (Client method)

**Parameters:**

#### Request Body

- **phoneNumber** (string) - Required - The recipient's phone number.
- **smsType** (string) - Required - Type of SMS, should be 'verification'.
- **verificationCode** (string | number) - Optional - The verification code to send.

### Send via Telegram

This method sends a verification SMS via Telegram.

**Method:** POST (or equivalent client method)

**Endpoint:** N/A (Client method)

**Parameters:**

#### Request Body

- **phoneNumber** (string) - Required - The recipient's phone number.
- **smsType** (string) - Required - Type of SMS, should be 'verification'.

### Send Custom Message

This method sends a custom message to a specified phone number.

**Method:** POST (or equivalent client method)

**Endpoint:** N/A (Client method)

**Parameters:**

#### Request Body

- **phoneNumber** (string) - Required - The recipient's phone number.
- **customMessage** (string) - Required - The custom message content.
- **senderId** (string) - Optional - The sender ID to use for the message.

### Get Credit Balance

Retrieves the available credit balance for the account.

**Method:** GET (or equivalent client method)

**Endpoint:** N/A (Client method)

**Response:**

#### Success Response (200)

- **credits** (number) - The available credit balance.

### Get SMS Status (Alias for trackSMS)

Retrieves the status of a previously sent SMS.

**Method:** GET (or equivalent client method)

**Endpoint:** N/A (Client method)

**Parameters:**

#### Query Parameters

- **smsId** (string) - Required - The ID of the SMS to track.

**Response:**

#### Success Response (200)

- **status** (string) - The delivery status of the SMS.
- **cost** (number) - The cost of the SMS.

```

--------------------------------

### TypeScript Interface for SendSMSOptions

Source: https://www.npmjs.com/package/otpiq/index_activetab=code

Defines the structure for options when sending an SMS. It includes parameters for phone number, message type, verification code, custom message, sender ID, provider, digit count, and delivery report configuration.

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

--------------------------------

### Send Verification SMS with Custom Options

Source: https://context7.com/context7/npmjs_package_otpiq/llms.txt

Shows how to send verification SMS with specific configurations. This includes auto-generating a code with a specified digit count or providing a custom verification code directly. The response includes the SMS ID and the sent verification code.

```javascript
// Auto-generate 6-digit code (default)
const response1 = await client.sendSMS({
  phoneNumber: "9647701234567",
  smsType: "verification",
  digitCount: 6,
  provider: "auto"  // auto, sms, whatsapp, telegram
});

console.log("Auto-generated code:", response1.verificationCode);

// Custom 4-digit code
const response2 = await client.sendSMS({
  phoneNumber: "9647701234567",
  smsType: "verification",
  verificationCode: "1234"
});

console.log("Custom code sent:", response2.smsId);
```

--------------------------------

### Convenience Methods

Source: https://www.npmjs.com/package/otpiq/index

Provides simplified methods for sending messages via WhatsApp, Telegram, custom messages, and retrieving credit balance or SMS status.

```APIDOC
## Convenience Methods

### Send via WhatsApp

```javascript
const response = await client.sendWhatsApp({
  phoneNumber: "9647701234567",
  smsType: "verification",
  verificationCode: "123456", // Optional
});
```

### Send via Telegram

```javascript
const response = await client.sendTelegram({
  phoneNumber: "9647701234567",
  smsType: "verification",
});
```

### Send Custom Message

```javascript
const response = await client.sendCustomMessage({
  phoneNumber: "9647701234567",
  customMessage: "Your order is ready for pickup!",
  senderId: "MyBrand",
});
```

### Get Credit Balance

```javascript
const credits = await client.getCredits();
console.log(`Available credits: ${credits} IQD`);
```

### Get SMS Status (Alias)

```javascript
const status = await client.getSMSStatus("sms-1234567890");
```
```

--------------------------------

### TypeScript Interface for SMSTrackingResponse

Source: https://www.npmjs.com/package/otpiq/index_activetab=code

Defines the structure for the response when tracking an SMS status. Includes the delivery status, phone number, SMS ID, and cost.

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

--------------------------------

### Handle otpiq API Errors Comprehensively

Source: https://context7.com/context7/npmjs_package_otpiq/llms.txt

Implement robust error handling for various otpiq API exceptions. This code demonstrates catching specific error types such as InsufficientCreditError, RateLimitError, and others, providing detailed information for debugging.

```javascript
import {
  InsufficientCreditError,
  RateLimitError,
  SpendingThresholdError,
  SenderIdError,
  TrialModeError,
  ValidationError,
  NotFoundError,
  UnauthorizedError,
  OTPiqError
} from "otpiq";

try {
  const response = await client.sendSMS({
    phoneNumber: "9647701234567",
    smsType: "verification"
  });
  console.log("Success:", response.smsId);
} catch (error) {
  if (error instanceof InsufficientCreditError) {
    console.log(`Need more credits!`);
    console.log(`Required: ${error.requiredCredit} IQD`);
    console.log(`Available: ${error.yourCredit} IQD`);
    console.log(`Can cover: ${error.canCover}`);
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limit exceeded`);
    console.log(`Wait ${error.waitMinutes} minutes`);
    console.log(`Limit: ${error.maxRequests} per ${error.timeWindowMinutes} min`);
  } else if (error instanceof SpendingThresholdError) {
    console.log(`Spending threshold exceeded`);
    console.log(`Current: ${error.currentSpending} IQD`);
    console.log(`Threshold: ${error.spendingThreshold} IQD`);
    console.log(`Transaction: ${error.cost} IQD`);
  } else if (error instanceof TrialModeError) {
    console.log("Trial mode: can only send to registered phone");
  } else if (error instanceof SenderIdError) {
    console.log("Sender ID issue:", error.message);
  } else if (error instanceof ValidationError) {
    console.log("Invalid input:", error.message);
  } else if (error instanceof UnauthorizedError) {
    console.log("Invalid API key");
  } else if (error instanceof NotFoundError) {
    console.log("Resource not found:", error.message);
  } else if (error instanceof OTPiqError) {
    console.log("API error:", error.message);
  }
}
```
Tokens:
Raw