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 token */
  apiToken: string

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

  /** Request timeout in milliseconds (default: 30000) */
  timeoutMs?: number

  /** Custom retry configuration */
  retryConfig?: RetryConfig

  /** Error callback handler */
  onError?: (error: MsGineError) => void
}

RetryConfig

Configuration for automatic retry behavior.

interface RetryConfig {
  /** Maximum number of retry attempts (default: 3) */
  maxRetries?: number

  /** Initial delay between retries in ms (default: 1000) */
  initialDelayMs?: number

  /** Maximum delay between retries in ms (default: 10000) */
  maxDelayMs?: number

  /** Exponential backoff multiplier (default: 2) */
  backoffMultiplier?: number
}

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 1600 characters) */
  message: string

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

  /** Webhook URL for delivery status updates (optional) */
  callbackUrl?: 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., "USD") */
  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 token
  | '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 sent to webhook URLs for delivery status updates.

interface WebhookPayload {
  /** Message ID */
  id: string

  /** Event type */
  event: 'message.sent' | 'message.delivered' | 'message.failed'

  /** Message status */
  status: MessageStatus

  /** Recipient phone number */
  to: string

  /** Failure reason (if failed) */
  failureReason?: string

  /** Event timestamp */
  timestamp: string
}

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.sendSms({ 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