Type Reference

Complete TypeScript type definitions for the MsGine SDK.

Client Types

MsGineClientConfig

Configuration options for initializing the MsGine client.

interface MsGineClientConfig {
  /** Your MsGine API key */
  apiKey: string

  /** API base URL (default: https://api.msgine.net/api/v1) */
  baseUrl?: string
}

Message Types

SendSmsRequest

Parameters for sending an SMS message.

interface SendSmsRequest {
  /** Recipient phone number(s) in E.164 format */
  to: string | string[]

  /** Message content (max 1000 characters) */
  message: string

  /** Sender ID (optional) */
  from?: string
}

SendSmsResponse

Response from sending an SMS message.

interface SendSmsResponse {
  /** Unique message identifier */
  id: string

  /** Provider-specific message ID */
  sid: string | null

  /** Message channel (e.g., "sms") */
  channel: string

  /** Recipient phone numbers */
  to: string[]

  /** Sender ID */
  from: string

  /** Message content */
  content: string

  /** Current message status */
  status: MessageStatus

  /** Message cost */
  cost: number

  /** Currency code (e.g., "UGX") */
  currency: string

  /** Message creation timestamp (ISO 8601) */
  createdAt: string

  /** Last update timestamp (ISO 8601) */
  updatedAt?: string
}

MessageStatus

Possible message delivery statuses.

type MessageStatus =
  | 'pending'    // Message is queued for delivery
  | 'sent'       // Message has been sent to carrier
  | 'delivered'  // Message was successfully delivered
  | 'failed'     // Message delivery failed

MessageListResponse

Response from listing messages.

interface MessageListResponse {
  /** Array of messages */
  data: SendSmsResponse[]

  /** Pagination information */
  pagination: {
    /** Current page number */
    page: number

    /** Items per page */
    limit: number

    /** Total number of messages */
    total: number

    /** Total number of pages */
    pages: number
  }
}

Account Types

AccountInfo

Account information and balance.

interface AccountInfo {
  /** Account ID */
  id: string

  /** Account email */
  email: string

  /** Current balance */
  balance: number

  /** Currency code */
  currency: string

  /** Account plan */
  plan: string

  /** Account creation timestamp */
  createdAt: string
}

Error Types

MsGineError

Base error class for SDK errors.

class MsGineError extends Error {
  /** Error name */
  name: string

  /** Human-readable error message */
  message: string

  /** HTTP status code */
  statusCode: number

  /** Machine-readable error code */
  code: string

  /** Additional error details */
  details?: Record<string, any>
}

Common Error Codes

type ErrorCode =
  | 'unauthorized'           // Invalid or missing API key
  | 'forbidden'             // Insufficient permissions
  | 'invalid_phone_number'  // Phone number validation failed
  | 'invalid_message'       // Message content validation failed
  | 'rate_limit_exceeded'   // Too many requests
  | 'insufficient_balance'  // Not enough credits
  | 'internal_error'        // Server error
  | 'network_error'         // Network connectivity issue

Webhook Types

WebhookPayload

Payload posted to a registered webhook URL.

type WebhookEvent =
  | 'sms.sent'
  | 'sms.failed'
  | 'email.sent'
  | 'email.failed'
  | 'push.sent'
  | 'push.partial'
  | 'push.failed'
  | 'whatsapp.delivered'
  | 'whatsapp.read'
  | 'whatsapp.failed'
  | 'webhook.test'

interface WebhookPayload {
  /** Event type */
  event: WebhookEvent

  /** Channel the event came from */
  channel: 'sms' | 'email' | 'push' | 'whatsapp' | 'system'

  /** Message the event concerns; absent for webhook.test */
  messageId?: string

  /** ISO 8601 timestamp of the event */
  timestamp: string

  /** Channel-specific detail */
  data: Record<string, unknown>
}

Utility Types

E164PhoneNumber

Type alias for phone numbers in E.164 format.

/** Phone number in E.164 format (e.g., +256701521269) */
type E164PhoneNumber = string

ISO8601DateTime

Type alias for ISO 8601 datetime strings.

/** ISO 8601 datetime string (e.g., 2024-01-15T10:30:00Z) */
type ISO8601DateTime = string

Type Guards

isMsGineError

Type guard to check if an error is a MsGineError.

function isMsGineError(error: unknown): error is MsGineError {
  return error instanceof MsGineError
}

// Usage
try {
  await client.sms.send({ to: phone, message: text })
} catch (error) {
  if (isMsGineError(error)) {
    console.error('API Error:', error.code)
  }
}

Next Steps

• API Reference - Complete client documentation
• Error Reference - Detailed error information
• Error Handling - Error handling guide