semaphoreco 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,507 @@
+/**
+ * Context information about an HTTP request, used for error reporting.
+ * API keys in headers are redacted for security.
+ */
+interface RequestContext {
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Options for HTTP requests made by the client.
+ */
+interface HttpRequestOptions {
+    method?: 'GET' | 'POST' | 'DELETE';
+    body?: unknown;
+    timeout?: number;
+    headers?: Record<string, string>;
+}
+/**
+ * Options for configuring retry behavior.
+ */
+interface RetryOptions {
+    maxRetries?: number;
+    onRetry?: (attempt: number, delayMs: number) => void;
+}
+
+/**
+ * Configuration for HttpClient.
+ */
+interface HttpClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeout: number;
+    maxRetries?: number;
+    onRetry?: (attempt: number, delayMs: number) => void;
+}
+/**
+ * HTTP client with timeout and retry support for the Semaphore API.
+ *
+ * Features:
+ * - Configurable timeout using AbortSignal.timeout()
+ * - Automatic retry on 429 (rate limit) responses with Retry-After header support
+ * - Maps HTTP status codes to typed error classes
+ * - Includes sanitized request context in errors for debugging
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly onRetry?;
+    constructor(config: HttpClientConfig);
+    /**
+     * Map HTTP response to appropriate error class.
+     *
+     * @param response - The HTTP response
+     * @param bodyText - Response body text (first 500 chars)
+     * @returns Appropriate error instance
+     */
+    private mapResponseToError;
+    /**
+     * Make an HTTP request to the Semaphore API.
+     *
+     * @param path - API path (e.g., "/messages")
+     * @param options - Request and retry options
+     * @returns Parsed JSON response
+     * @throws {NetworkError} On connection failures
+     * @throws {TimeoutError} On request timeout
+     * @throws {AuthenticationError} On 401 responses
+     * @throws {RateLimitError} On 429 responses (after retries exhausted)
+     * @throws {ValidationError} On 4xx responses
+     * @throws {SemaphoreError} On 5xx responses
+     */
+    request<T>(path: string, options?: HttpRequestOptions & RetryOptions): Promise<T>;
+}
+
+/** Configuration options for SemaphoreClient */
+interface SemaphoreClientOptions {
+    /** API key. Falls back to SEMAPHORE_API_KEY env var if not provided */
+    apiKey?: string;
+    /** Base URL. Defaults to https://api.semaphore.co/api/v4 */
+    baseUrl?: string;
+    /** Request timeout in ms. Defaults to 30000 */
+    timeout?: number;
+    /** Callback invoked when a rate-limited request is retried */
+    onRetry?: (attempt: number, delayMs: number) => void;
+}
+/** Generic paginated response wrapper */
+interface PaginatedResponse<T> {
+    data: T[];
+    total?: number;
+    page?: number;
+    limit?: number;
+}
+
+/** Request to send SMS message(s) */
+interface SendMessageRequest {
+    /** Recipient number(s). Single string or array up to 1000 */
+    number: string | string[];
+    /** Message content */
+    message: string;
+    /** Approved sender name */
+    sendername: string;
+}
+/** Response from send message API */
+interface SendMessageResponse {
+    message_id: number;
+    user_id: number;
+    user: string;
+    account_id: number;
+    account: string;
+    recipient: string;
+    message: string;
+    sender_name: string;
+    network: string;
+    status: string;
+    type: string;
+    source: string;
+    created_at: string;
+    updated_at: string;
+}
+/** Bulk send returns array of responses */
+type BulkSendMessageResponse = SendMessageResponse[];
+/** Request params for listing messages */
+interface MessageListRequest {
+    page?: number;
+    limit?: number;
+    startDate?: string;
+    endDate?: string;
+    network?: string;
+    status?: string;
+    sendername?: string;
+}
+/** Message object from list/get endpoints */
+interface Message {
+    id: number;
+    message_id: number;
+    user_id: number;
+    user: string;
+    account_id: number;
+    account: string;
+    recipient: string;
+    message: string;
+    sender_name: string;
+    network: string;
+    status: string;
+    type: string;
+    source: string;
+    created_at: string;
+    updated_at: string;
+}
+
+/** Request to send OTP message */
+interface SendOtpRequest {
+    /** Recipient phone number */
+    number: string;
+    /** OTP message template. Use {otp} placeholder */
+    message: string;
+    /** Approved sender name */
+    sendername: string;
+    /** OTP code length (default 6) */
+    code_length?: number;
+}
+/** Response from send OTP API */
+interface SendOtpResponse {
+    message_id: number;
+    user_id: number;
+    user: string;
+    account_id: number;
+    account: string;
+    recipient: string;
+    message: string;
+    sender_name: string;
+    network: string;
+    status: string;
+    type: string;
+    source: string;
+    code: string;
+    created_at: string;
+    updated_at: string;
+}
+
+/** Account information and balance */
+interface AccountInfo {
+    account_id: number;
+    account_name: string;
+    status: string;
+    credit_balance: string;
+}
+/** Transaction history entry */
+interface Transaction {
+    id: number;
+    account_id: number;
+    user_id: number;
+    type: string;
+    amount: string;
+    balance_before: string;
+    balance_after: string;
+    description: string;
+    created_at: string;
+}
+/** Request params for transaction history */
+interface TransactionListRequest {
+    page?: number;
+    limit?: number;
+    startDate?: string;
+    endDate?: string;
+}
+/** Approved sender name */
+interface SenderName {
+    name: string;
+    status: string;
+    created_at: string;
+}
+
+/**
+ * Resource class for SMS message operations.
+ *
+ * Provides methods for sending messages, listing sent messages,
+ * and retrieving message details by ID.
+ *
+ * @example
+ * ```typescript
+ * const client = new SemaphoreClient({ apiKey: 'your-api-key' });
+ *
+ * // Send a single message
+ * const response = await client.messages.send({
+ *   number: '09171234567',
+ *   message: 'Hello!',
+ *   sendername: 'SEMAPHORE',
+ * });
+ * ```
+ */
+declare class MessagesResource {
+    private readonly http;
+    /**
+     * Create a new MessagesResource instance.
+     *
+     * @param http - HttpClient instance for making API requests
+     */
+    constructor(http: HttpClient);
+    /**
+     * Send an SMS message to one or more recipients.
+     *
+     * When sending to multiple recipients (up to 1000), pass an array of numbers.
+     * The API will return an array of responses, one for each recipient.
+     *
+     * @param params - Message parameters including recipient(s), message content, and sender name
+     * @returns Single response for one recipient, array of responses for multiple recipients
+     *
+     * @example
+     * ```typescript
+     * // Send to single recipient
+     * const response = await client.messages.send({
+     *   number: '09171234567',
+     *   message: 'Hello!',
+     *   sendername: 'SEMAPHORE',
+     * });
+     * console.log(response.message_id);
+     *
+     * // Send to multiple recipients (bulk)
+     * const responses = await client.messages.send({
+     *   number: ['09171234567', '09181234567'],
+     *   message: 'Hello everyone!',
+     *   sendername: 'SEMAPHORE',
+     * });
+     * console.log(responses.length); // 2
+     * ```
+     */
+    send(params: SendMessageRequest): Promise<SendMessageResponse | BulkSendMessageResponse>;
+    /**
+     * List sent messages with optional filtering.
+     *
+     * Supports pagination and filtering by date range, network, status, and sender name.
+     *
+     * @param params - Optional filter parameters
+     * @returns Array of message objects
+     *
+     * @example
+     * ```typescript
+     * // List all messages
+     * const messages = await client.messages.list();
+     *
+     * // List with filters
+     * const filtered = await client.messages.list({
+     *   page: 1,
+     *   limit: 50,
+     *   status: 'Sent',
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-01-31',
+     * });
+     * ```
+     */
+    list(params?: MessageListRequest): Promise<Message[]>;
+    /**
+     * Get a specific message by ID.
+     *
+     * @param id - The message ID to retrieve
+     * @returns The message object
+     *
+     * @example
+     * ```typescript
+     * const message = await client.messages.get(12345);
+     * console.log(message.status); // 'Sent'
+     * console.log(message.recipient); // '09171234567'
+     * ```
+     */
+    get(id: number): Promise<Message>;
+    /**
+     * Build query string from optional MessageListRequest parameters.
+     *
+     * @param params - Optional filter parameters
+     * @returns Query string including leading '?' if params exist, empty string otherwise
+     */
+    private buildQueryString;
+}
+
+/**
+ * Resource for sending OTP (One-Time Password) messages.
+ *
+ * OTP messages use a priority route with no rate limit.
+ * Each message costs 2 credits per 160 characters.
+ */
+declare class OtpResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Send an OTP message to a recipient.
+     *
+     * Uses priority route - no rate limit, 2 credits per 160-char message.
+     * The API generates the OTP code and replaces the {otp} placeholder in your message.
+     *
+     * @param params - OTP parameters including recipient, message template, sender name
+     * @returns Response including the generated OTP code
+     *
+     * @example
+     * ```typescript
+     * const response = await client.otp.send({
+     *   number: '+639171234567',
+     *   message: 'Your verification code is {otp}',
+     *   sendername: 'MyApp',
+     * });
+     * console.log('OTP sent:', response.code);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With custom code length
+     * const response = await client.otp.send({
+     *   number: '+639171234567',
+     *   message: 'Your code is {otp}',
+     *   sendername: 'MyApp',
+     *   code_length: 4,
+     * });
+     * ```
+     */
+    send(params: SendOtpRequest): Promise<SendOtpResponse>;
+}
+
+/**
+ * Resource for retrieving account information.
+ */
+declare class AccountResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get account information including credit balance.
+     *
+     * @returns Account info with balance
+     *
+     * @example
+     * ```typescript
+     * const info = await client.account.info();
+     * console.log('Account:', info.account_name);
+     * console.log('Balance:', info.credit_balance);
+     * ```
+     */
+    info(): Promise<AccountInfo>;
+    /**
+     * Get transaction history.
+     *
+     * @param params - Optional pagination and date filter parameters
+     * @returns Array of transactions
+     *
+     * @example
+     * ```typescript
+     * // Get all transactions
+     * const transactions = await client.account.transactions();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get paginated transactions with date range
+     * const transactions = await client.account.transactions({
+     *   page: 1,
+     *   limit: 50,
+     *   startDate: '2026-01-01',
+     *   endDate: '2026-01-31',
+     * });
+     * ```
+     */
+    transactions(params?: TransactionListRequest): Promise<Transaction[]>;
+    /**
+     * Get list of approved sender names.
+     *
+     * @returns Array of sender names with status
+     *
+     * @example
+     * ```typescript
+     * const senderNames = await client.account.senderNames();
+     * for (const sender of senderNames) {
+     *   console.log(`${sender.name}: ${sender.status}`);
+     * }
+     * ```
+     */
+    senderNames(): Promise<SenderName[]>;
+    /**
+     * Build query string from optional transaction list parameters.
+     *
+     * @param params - Optional filter parameters
+     * @returns Query string (empty string or ?param1=value1&param2=value2)
+     */
+    private buildQueryString;
+}
+
+/**
+ * Semaphore API client for sending SMS and OTP messages.
+ *
+ * @example
+ * ```typescript
+ * // Send SMS
+ * const client = new SemaphoreClient({ apiKey: 'your-api-key' });
+ * await client.messages.send({
+ *   number: '+639171234567',
+ *   message: 'Hello!',
+ *   sendername: 'MyApp',
+ * });
+ *
+ * // Check balance
+ * const info = await client.account.info();
+ * console.log('Balance:', info.credit_balance);
+ * ```
+ */
+declare class SemaphoreClient {
+    /** @internal HTTP client used by resource classes. */
+    protected readonly http: HttpClient;
+    /** SMS message operations */
+    readonly messages: MessagesResource;
+    /** OTP message operations (priority route, no rate limit) */
+    readonly otp: OtpResource;
+    /** Account information operations */
+    readonly account: AccountResource;
+    constructor(options?: SemaphoreClientOptions);
+}
+
+/**
+ * Base error class for all Semaphore API errors.
+ * Extend this for specific error types.
+ */
+declare class SemaphoreError extends Error {
+    readonly statusCode?: number;
+    readonly code?: string;
+    constructor(message: string, statusCode?: number, code?: string);
+}
+/**
+ * Thrown when the API key is invalid or missing.
+ */
+declare class AuthenticationError extends SemaphoreError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when rate limits are exceeded.
+ * Check `retryAfter` for seconds to wait before retrying.
+ */
+declare class RateLimitError extends SemaphoreError {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
+}
+/**
+ * Thrown when request parameters are invalid.
+ */
+declare class ValidationError extends SemaphoreError {
+    readonly field?: string;
+    constructor(message: string, field?: string);
+}
+/**
+ * Thrown when a network error occurs (connection failure, DNS resolution, etc.).
+ * The `request` property contains context about the failed request.
+ * The `cause` property contains the underlying error if available.
+ */
+declare class NetworkError extends SemaphoreError {
+    readonly request: RequestContext;
+    readonly cause?: Error;
+    constructor(message: string, request: RequestContext, cause?: Error);
+}
+/**
+ * Thrown when a request times out.
+ * The `request` property contains context about the timed-out request.
+ * The `timeoutMs` property indicates the timeout duration that was exceeded.
+ */
+declare class TimeoutError extends SemaphoreError {
+    readonly request: RequestContext;
+    readonly timeoutMs: number;
+    constructor(message: string, request: RequestContext, timeoutMs: number);
+}
+
+export { type AccountInfo, AccountResource, AuthenticationError, type BulkSendMessageResponse, HttpClient, type HttpRequestOptions, type Message, type MessageListRequest, MessagesResource, NetworkError, OtpResource, type PaginatedResponse, RateLimitError, type RequestContext, type RetryOptions, SemaphoreClient, type SemaphoreClientOptions, SemaphoreError, type SendMessageRequest, type SendMessageResponse, type SendOtpRequest, type SendOtpResponse, type SenderName, TimeoutError, type Transaction, type TransactionListRequest, ValidationError };