budgetsms-client 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,460 @@
+/**
+ * BudgetSMS API Base URL and Endpoints
+ */
+declare const API_BASE = "https://api.budgetsms.net";
+declare const ENDPOINTS: {
+    readonly SEND_SMS: "/sendsms/";
+    readonly TEST_SMS: "/testsms/";
+    readonly CHECK_CREDIT: "/checkcredit/";
+    readonly CHECK_OPERATOR: "/checkoperator/";
+    readonly HLR: "/hlr/";
+    readonly CHECK_SMS: "/checksms/";
+    readonly GET_PRICING: "/getpricing/";
+};
+/**
+ * BudgetSMS API Error Codes
+ * Source: HTTP API Specification V2.7, Chapter 11
+ */
+declare enum BudgetSMSErrorCode {
+    NOT_ENOUGH_CREDITS = 1001,
+    INVALID_CREDENTIALS = 1002,
+    ACCOUNT_NOT_ACTIVE = 1003,
+    IP_NOT_ALLOWED = 1004,
+    NO_HANDLE_PROVIDED = 1005,
+    NO_USERID_PROVIDED = 1006,
+    NO_USERNAME_PROVIDED = 1007,
+    SMS_TEXT_EMPTY = 2001,
+    SMS_NUMERIC_SENDER_TOO_LONG = 2002,
+    SMS_ALPHANUMERIC_SENDER_TOO_LONG = 2003,
+    SMS_SENDER_EMPTY_OR_INVALID = 2004,
+    DESTINATION_TOO_SHORT = 2005,
+    DESTINATION_NOT_NUMERIC = 2006,
+    DESTINATION_EMPTY = 2007,
+    SMS_TEXT_NOT_OK = 2008,
+    PARAMETER_ISSUE = 2009,
+    DESTINATION_INVALIDLY_FORMATTED = 2010,
+    DESTINATION_INVALID = 2011,
+    SMS_TEXT_TOO_LONG = 2012,
+    SMS_MESSAGE_INVALID = 2013,
+    CUSTOM_ID_ALREADY_USED = 2014,
+    CHARSET_PROBLEM = 2015,
+    INVALID_UTF8_ENCODING = 2016,
+    INVALID_SMS_ID = 2017,
+    NO_ROUTE_TO_DESTINATION = 3001,
+    NO_ROUTES_SETUP = 3002,
+    INVALID_DESTINATION = 3003,
+    SYSTEM_ERROR_CUSTOM_ID = 4001,
+    SYSTEM_ERROR_TEMPORARY = 4002,
+    SYSTEM_ERROR_TEMPORARY_2 = 4003,
+    SYSTEM_ERROR_CONTACT_SUPPORT = 4004,
+    SYSTEM_ERROR_PERMANENT = 4005,
+    GATEWAY_NOT_REACHABLE = 4006,
+    SYSTEM_ERROR_CONTACT_SUPPORT_2 = 4007,
+    SEND_ERROR = 5001,
+    WRONG_SMS_TYPE = 5002,
+    WRONG_OPERATOR = 5003,
+    UNKNOWN_ERROR = 6001,
+    NO_HLR_PROVIDER = 7001,
+    UNEXPECTED_HLR_RESULTS = 7002,
+    BAD_NUMBER_FORMAT = 7003,
+    HLR_UNEXPECTED_ERROR = 7901,
+    HLR_PROVIDER_ERROR = 7902,
+    HLR_PROVIDER_ERROR_2 = 7903
+}
+/**
+ * Error code descriptions for better error messages
+ */
+declare const ERROR_MESSAGES: Record<BudgetSMSErrorCode, string>;
+/**
+ * DLR (Delivery Report) Status Codes
+ * Source: HTTP API Specification V2.7, Chapter 12
+ */
+declare enum DLRStatus {
+    /** Message is sent, no status yet (default) */
+    SENT_NO_STATUS = 0,
+    /** Message is delivered */
+    DELIVERED = 1,
+    /** Message is not sent */
+    NOT_SENT = 2,
+    /** Message delivery failed */
+    DELIVERY_FAILED = 3,
+    /** Message is sent */
+    SENT = 4,
+    /** Message expired */
+    EXPIRED = 5,
+    /** Message has a invalid destination address */
+    INVALID_DESTINATION = 6,
+    /** SMSC error, message could not be processed */
+    SMSC_ERROR = 7,
+    /** Message is not allowed */
+    NOT_ALLOWED = 8,
+    /** Message status unknown, usually after 24 hours without status update SMSC */
+    STATUS_UNKNOWN_24H = 11,
+    /** Message status unknown, SMSC received unknown status code */
+    STATUS_UNKNOWN_CODE = 12,
+    /** Message status unknown, no status update received from SMSC after 72 hours after submit */
+    STATUS_UNKNOWN_72H = 13
+}
+/**
+ * DLR status descriptions for better understanding
+ */
+declare const DLR_STATUS_MESSAGES: Record<DLRStatus, string>;
+
+/**
+ * Authentication credentials for BudgetSMS API
+ */
+interface BudgetSMSCredentials {
+    /** Your BudgetSMS username */
+    username: string;
+    /** Your BudgetSMS userid (numeric) */
+    userid: string;
+    /** Your API handle (unique identifier) */
+    handle: string;
+}
+/**
+ * Parameters for sending an SMS message
+ */
+interface SendSMSParams {
+    /** The SMS message text (UTF-8 encoded, max 612 characters recommended) */
+    msg: string;
+    /** Sender ID (alphanumeric max 11 chars, or numeric max 16 digits) */
+    from: string;
+    /** Receiver phone number in international format (no +, no spaces) */
+    to: string;
+    /** Optional custom message ID (alphanumeric, max 50 chars, must be unique) */
+    customid?: string;
+    /** Request price information in response (default: false) */
+    price?: boolean;
+    /** Request MCC/MNC information in response (default: false) */
+    mccmnc?: boolean;
+    /** Show remaining credit in response (default: false) */
+    credit?: boolean;
+}
+/**
+ * Parameters for test SMS (same as SendSMSParams)
+ * Test SMS simulates sending without actually sending or reducing credit
+ */
+type TestSMSParams = SendSMSParams;
+/**
+ * Response from sending an SMS
+ */
+interface SendSMSResponse {
+    /** Whether the SMS was successfully submitted */
+    success: true;
+    /** The SMS message ID assigned by BudgetSMS */
+    smsId: string;
+    /** Price per SMS part (if price parameter was set to true) */
+    price?: number;
+    /** Number of SMS parts (if price parameter was set to true) */
+    parts?: number;
+    /** Mobile Country Code + Mobile Network Code (if mccmnc parameter was set to true) */
+    mccMnc?: string;
+    /** Remaining account credit (if credit parameter was set to true) */
+    credit?: number;
+}
+/**
+ * Response from test SMS (same as SendSMSResponse)
+ */
+type TestSMSResponse = SendSMSResponse;
+/**
+ * Response from checking account credit
+ */
+interface CheckCreditResponse {
+    /** Whether the check was successful */
+    success: true;
+    /** Remaining credit amount */
+    credit: number;
+}
+/**
+ * Response from checking operator or HLR lookup
+ */
+interface OperatorResponse {
+    /** Whether the check was successful */
+    success: true;
+    /** Mobile Country Code + Mobile Network Code combined (e.g., "20416") */
+    mccMnc: string;
+    /** Name of the mobile operator */
+    operatorName: string;
+    /** Cost per SMS message to this operator */
+    messageCost: number;
+}
+/**
+ * Response from HLR lookup (same structure as OperatorResponse)
+ */
+type HLRResponse = OperatorResponse;
+/**
+ * Response from checking SMS status
+ */
+interface SMSStatusResponse {
+    /** Whether the check was successful */
+    success: true;
+    /** The SMS message ID */
+    smsId: string;
+    /** Current delivery status */
+    status: DLRStatus;
+}
+/**
+ * Single pricing entry for an operator
+ */
+interface PricingEntry {
+    /** Country prefix (e.g., "31" for Netherlands) */
+    countryprefix: string;
+    /** Country name */
+    countryname: string;
+    /** Mobile Country Code */
+    mcc: string;
+    /** Operator name */
+    operatorname: string;
+    /** Mobile Network Code */
+    mnc: string;
+    /** Price per SMS part in euro */
+    price: string;
+    /** Old price before the change */
+    old_price: string;
+    /** Last modified date (GMT+1) */
+    last_modified: string;
+}
+/**
+ * Response from getting account pricing
+ * Returns a JSON array of pricing entries
+ */
+type GetPricingResponse = PricingEntry[];
+/**
+ * Configuration options for BudgetSMS client
+ */
+interface BudgetSMSConfig extends BudgetSMSCredentials {
+    /** Custom base URL (default: https://api.budgetsms.net) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+
+/**
+ * BudgetSMS API Client
+ *
+ * A modern, type-safe client for the BudgetSMS.net HTTP API.
+ * Supports all API endpoints with proper error handling and response parsing.
+ *
+ * @example
+ * ```typescript
+ * const client = new BudgetSMS({
+ *   username: 'your-username',
+ *   userid: 'your-userid',
+ *   handle: 'your-api-handle'
+ * });
+ *
+ * // Send an SMS
+ * const result = await client.sendSMS({
+ *   msg: 'Hello World!',
+ *   from: 'YourApp',
+ *   to: '31612345678'
+ * });
+ * ```
+ */
+declare class BudgetSMS {
+    private readonly username;
+    private readonly userid;
+    private readonly handle;
+    private readonly baseUrl;
+    private readonly timeout;
+    /**
+     * Create a new BudgetSMS client
+     * @param config - Configuration object with credentials and optional settings
+     */
+    constructor(config: BudgetSMSConfig);
+    /**
+     * Make an HTTP GET request to the API
+     * @param endpoint - API endpoint path
+     * @param params - Query parameters
+     * @returns Response text
+     */
+    private request;
+    /**
+     * Get base authentication parameters
+     */
+    private getAuthParams;
+    /**
+     * Send an SMS message
+     *
+     * @param params - SMS parameters
+     * @returns Promise resolving to SendSMSResponse
+     * @throws {BudgetSMSError} If the API returns an error
+     *
+     * @example
+     * ```typescript
+     * const result = await client.sendSMS({
+     *   msg: 'Hello World!',
+     *   from: 'YourApp',
+     *   to: '31612345678',
+     *   price: true,  // Get price info in response
+     *   mccmnc: true  // Get operator info in response
+     * });
+     *
+     * console.log(`SMS sent with ID: ${result.smsId}`);
+     * if (result.price) {
+     *   console.log(`Cost: €${result.price} for ${result.parts} part(s)`);
+     * }
+     * ```
+     */
+    sendSMS(params: SendSMSParams): Promise<SendSMSResponse>;
+    /**
+     * Test SMS sending without actually sending or reducing credit
+     *
+     * Useful for testing your implementation without consuming credits.
+     *
+     * @param params - SMS parameters (same as sendSMS)
+     * @returns Promise resolving to TestSMSResponse
+     * @throws {BudgetSMSError} If the API returns an error
+     *
+     * @example
+     * ```typescript
+     * const result = await client.testSMS({
+     *   msg: 'Test message',
+     *   from: 'TestApp',
+     *   to: '31612345678'
+     * });
+     *
+     * console.log(`Test successful, would get SMS ID: ${result.smsId}`);
+     * ```
+     */
+    testSMS(params: TestSMSParams): Promise<TestSMSResponse>;
+    /**
+     * Check remaining account credit
+     *
+     * @returns Promise resolving to CheckCreditResponse
+     * @throws {BudgetSMSError} If the API returns an error
+     *
+     * @example
+     * ```typescript
+     * const result = await client.checkCredit();
+     * console.log(`Remaining credit: €${result.credit}`);
+     * ```
+     */
+    checkCredit(): Promise<CheckCreditResponse>;
+    /**
+     * Check operator based on phone number prefix
+     *
+     * Note: This checks the original operator based on prefix.
+     * If a number has been ported, use hlr() instead.
+     *
+     * @param phoneNumber - Phone number to check (international format, no +)
+     * @returns Promise resolving to OperatorResponse
+     * @throws {BudgetSMSError} If the API returns an error
+     *
+     * @example
+     * ```typescript
+     * const result = await client.checkOperator('31612345678');
+     * console.log(`Operator: ${result.operatorName} (${result.mccMnc})`);
+     * console.log(`Cost: €${result.messageCost}`);
+     * ```
+     */
+    checkOperator(phoneNumber: string): Promise<OperatorResponse>;
+    /**
+     * Perform HLR (Home Location Register) lookup
+     *
+     * Returns the actual current operator, even if the number has been ported.
+     * More accurate than checkOperator() but may cost credits.
+     *
+     * @param phoneNumber - Phone number to lookup (international format, no +)
+     * @returns Promise resolving to HLRResponse
+     * @throws {BudgetSMSError} If the API returns an error
+     *
+     * @example
+     * ```typescript
+     * const result = await client.hlr('31612345678');
+     * console.log(`Current operator: ${result.operatorName}`);
+     * console.log(`Network: ${result.mccMnc}`);
+     * ```
+     */
+    hlr(phoneNumber: string): Promise<HLRResponse>;
+    /**
+     * Check SMS delivery status (Pull DLR)
+     *
+     * Retrieve the current delivery status of a sent message.
+     * For automatic updates, consider using Push DLR instead.
+     *
+     * @param smsId - The SMS ID returned from sendSMS()
+     * @returns Promise resolving to SMSStatusResponse
+     * @throws {BudgetSMSError} If the API returns an error
+     *
+     * @example
+     * ```typescript
+     * const result = await client.checkSMS('12345678');
+     * console.log(`Status: ${result.status}`); // DLRStatus enum value
+     * ```
+     */
+    checkSMS(smsId: string): Promise<SMSStatusResponse>;
+    /**
+     * Get account pricing for all operators
+     *
+     * Returns a comprehensive list of pricing for all available operators.
+     * Each entry includes country, operator, MCC/MNC codes, and pricing info.
+     *
+     * @returns Promise resolving to GetPricingResponse (array of pricing entries)
+     * @throws {BudgetSMSError} If the API returns an error
+     *
+     * @example
+     * ```typescript
+     * const pricing = await client.getPricing();
+     * for (const entry of pricing) {
+     *   console.log(`${entry.countryname} - ${entry.operatorname}: €${entry.price}`);
+     * }
+     * ```
+     */
+    getPricing(): Promise<GetPricingResponse>;
+}
+
+/**
+ * Custom error class for BudgetSMS API errors
+ */
+declare class BudgetSMSError extends Error {
+    readonly code: BudgetSMSErrorCode;
+    /**
+     * Creates a new BudgetSMSError
+     * @param code - The BudgetSMS error code
+     * @param message - Optional custom error message (defaults to standard message for the code)
+     */
+    constructor(code: BudgetSMSErrorCode, message?: string);
+    /**
+     * Returns true if the error code indicates a temporary/retryable error
+     */
+    isRetryable(): boolean;
+    /**
+     * Returns true if the error code indicates an authentication/credentials issue
+     */
+    isAuthenticationError(): boolean;
+    /**
+     * Returns true if the error code indicates insufficient credits
+     */
+    isInsufficientCredits(): boolean;
+    /**
+     * Convert error to JSON for logging/serialization
+     */
+    toJSON(): {
+        name: string;
+        code: BudgetSMSErrorCode;
+        message: string;
+        stack: string | undefined;
+    };
+}
+
+/**
+ * Validate phone number format (basic MSISDN validation)
+ * @param phoneNumber - Phone number to validate
+ * @returns true if valid, false otherwise
+ */
+declare function validatePhoneNumber(phoneNumber: string): boolean;
+/**
+ * Validate sender ID format
+ * @param sender - Sender ID to validate
+ * @returns true if valid, false otherwise
+ */
+declare function validateSender(sender: string): boolean;
+/**
+ * Validate message text
+ * @param message - Message text to validate
+ * @returns true if valid, false otherwise
+ */
+declare function validateMessage(message: string): boolean;
+
+export { API_BASE, BudgetSMS, type BudgetSMSConfig, type BudgetSMSCredentials, BudgetSMSError, BudgetSMSErrorCode, type CheckCreditResponse, DLRStatus, DLR_STATUS_MESSAGES, ENDPOINTS, ERROR_MESSAGES, type GetPricingResponse, type HLRResponse, type OperatorResponse, type PricingEntry, type SMSStatusResponse, type SendSMSParams, type SendSMSResponse, type TestSMSParams, type TestSMSResponse, validateMessage, validatePhoneNumber, validateSender };