Configuration

Customize the MsGine SDK to fit your needs.

Basic Configuration

The simplest configuration requires only an API token:

import { MsGineClient } from '@msgine/sdk'

const client = new MsGineClient({
  apiToken: 'your-api-token'
})

Advanced Configuration

Customize retry behavior, timeouts, and more:

import { MsGineClient } from '@msgine/sdk'

const client = new MsGineClient({
  apiToken: process.env.MSGINE_API_TOKEN!,

  // Optional: Custom API base URL
  baseUrl: 'https://api.msgine.net/api/v1',

  // Optional: Request timeout in milliseconds (default: 30000)
  timeout: 30000,

  // Optional: Retry configuration
  retry: {
    maxRetries: 3,                    // Max retry attempts (default: 3)
    initialDelay: 1000,               // Initial delay in ms (default: 1000)
    maxDelay: 10000,                  // Max delay in ms (default: 10000)
    backoffMultiplier: 2,             // Backoff multiplier (default: 2)
    retryableStatusCodes: [           // HTTP codes to retry (default shown)
      408,  // Request Timeout
      429,  // Too Many Requests
      500,  // Internal Server Error
      502,  // Bad Gateway
      503,  // Service Unavailable
      504   // Gateway Timeout
    ]
  }
})

Configuration Options

apiToken

Type: string (required)

Your MsGine API token. Get one from the Developer Dashboard.

const client = new MsGineClient({
  apiToken: 'your-api-token'
})

WARNING

Never hardcode your API token in your source code. Use environment variables instead.

baseUrl

Type: string (optional) Default: https://api.msgine.net/api/v1

The base URL for API requests. Useful for testing or custom deployments.

const client = new MsGineClient({
  apiToken: process.env.MSGINE_API_TOKEN!,
  baseUrl: 'https://api-staging.msgine.net/api/v1'
})

timeout

Type: number (optional) Default: 30000 (30 seconds)

Request timeout in milliseconds.

const client = new MsGineClient({
  apiToken: process.env.MSGINE_API_TOKEN!,
  timeout: 60000 // 60 seconds
})

retry

Type: RetryConfig (optional)

Configure automatic retry behavior for failed requests.

const client = new MsGineClient({
  apiToken: process.env.MSGINE_API_TOKEN!,
  retry: {
    maxRetries: 5,           // Retry up to 5 times
    initialDelay: 2000,      // Start with 2 second delay
    maxDelay: 30000,         // Max 30 second delay
    backoffMultiplier: 2     // Double delay each retry
  }
})

Retry Configuration

Property	Type	Default	Description
maxRetries	number	3	Maximum number of retry attempts
initialDelay	number	1000	Initial delay in milliseconds
maxDelay	number	10000	Maximum delay between retries
backoffMultiplier	number	2	Multiplier for exponential backoff
retryableStatusCodes	number[]	[408, 429, 500, 502, 503, 504]	HTTP status codes that trigger a retry

fetch

Type: typeof fetch (optional) Default: Global fetch

Provide a custom fetch implementation. Useful for testing or adding custom middleware.

const customFetch = async (url: string, options: RequestInit) => {
  console.log('Making request to:', url)
  return fetch(url, options)
}

const client = new MsGineClient({
  apiToken: process.env.MSGINE_API_TOKEN!,
  fetch: customFetch
})

Retry Behavior

The SDK automatically retries failed requests with exponential backoff:

1. First retry: Wait initialDelay ms (default: 1s)
2. Second retry: Wait initialDelay × backoffMultiplier ms (default: 2s)
3. Third retry: Wait initialDelay × backoffMultiplier² ms (default: 4s)
4. And so on, up to maxDelay

Example Retry Timeline

With default settings:

Attempt 1: Immediate
Attempt 2: +1s delay
Attempt 3: +2s delay
Attempt 4: +4s delay (final attempt)

TIP

The SDK only retries on network errors and specific HTTP status codes (408, 429, 500, 502, 503, 504). Client errors (4xx, except 408 and 429) are not retried.

Factory Function

You can also use the createClient factory function:

import { createClient } from '@msgine/sdk'

const client = createClient({
  apiToken: process.env.MSGINE_API_TOKEN!
})

This is functionally identical to using new MsGineClient().

Environment-Specific Configuration

Development

const client = new MsGineClient({
  apiToken: process.env.MSGINE_API_TOKEN!,
  timeout: 60000,  // Longer timeout for debugging
  retry: {
    maxRetries: 1  // Fail fast in development
  }
})

Production

const client = new MsGineClient({
  apiToken: process.env.MSGINE_API_TOKEN!,
  timeout: 30000,
  retry: {
    maxRetries: 5,      // More retries for reliability
    initialDelay: 1000,
    maxDelay: 30000
  }
})

Testing

const client = new MsGineClient({
  apiToken: 'test-token',
  baseUrl: 'https://api-test.msgine.net/api/v1',
  retry: {
    maxRetries: 0  // No retries in tests
  },
  fetch: mockFetch  // Use mock fetch
})

Next Steps

• Send Messages - Learn how to send SMS
• Batch Messaging - Send to multiple recipients
• Error Handling - Handle errors gracefully