@semboja/connect 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,739 @@
+interface HttpClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    timeout: number;
+    retries: number;
+}
+interface RequestOptions {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/**
+ * HTTP client for making API requests
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    private readonly retries;
+    constructor(options: HttpClientOptions);
+    /**
+     * Make an HTTP request with retry logic
+     */
+    request<T>(options: RequestOptions): Promise<T>;
+    /**
+     * Parse error response into appropriate error class
+     */
+    private parseError;
+    /**
+     * GET request
+     */
+    get<T>(path: string): Promise<T>;
+    /**
+     * POST request
+     */
+    post<T>(path: string, body?: unknown): Promise<T>;
+}
+
+/**
+ * Client configuration options
+ */
+interface ClientOptions {
+    /** API key (sk_live_* or sk_test_*) */
+    apiKey: string;
+    /** Base URL for the API (default: https://connect.semboja.tech) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Number of retry attempts for failed requests (default: 3) */
+    retries?: number;
+}
+/**
+ * Standard API response wrapper
+ */
+interface ApiResponse<T> {
+    success: boolean;
+    data: T;
+    meta: {
+        request_id: string;
+        latency_ms?: number;
+    };
+}
+/**
+ * API error response
+ */
+interface ApiErrorResponse {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+    };
+    meta: {
+        request_id: string;
+    };
+}
+type MessageType = 'text' | 'template' | 'image' | 'video' | 'audio' | 'document' | 'interactive' | 'reaction';
+interface SendMessageOptions {
+    /** Meta Phone Number ID */
+    phoneNumberId: string;
+    /** Recipient phone number with country code (e.g., +6281234567890) */
+    to: string;
+}
+interface SendTextOptions extends SendMessageOptions {
+    /** Message text content (max 4096 characters) */
+    text: string;
+    /** Enable URL preview in the message */
+    previewUrl?: boolean;
+    /** Message ID to reply to */
+    replyTo?: string;
+}
+interface TemplateLanguage {
+    code: string;
+}
+interface TemplateComponent {
+    type: 'header' | 'body' | 'button';
+    parameters?: TemplateParameter[];
+    sub_type?: string;
+    index?: number;
+}
+interface TemplateParameter {
+    type: 'text' | 'currency' | 'date_time' | 'image' | 'document' | 'video';
+    text?: string;
+    currency?: {
+        fallback_value: string;
+        code: string;
+        amount_1000: number;
+    };
+    date_time?: {
+        fallback_value: string;
+    };
+    image?: MediaObject;
+    document?: MediaObject;
+    video?: MediaObject;
+}
+interface Template {
+    name: string;
+    language: TemplateLanguage;
+    components?: TemplateComponent[];
+}
+interface SendTemplateOptions extends SendMessageOptions {
+    /** Template configuration */
+    template: Template;
+}
+interface MediaObject {
+    /** URL of the media file */
+    link?: string;
+    /** Media ID (if uploaded to WhatsApp) */
+    id?: string;
+    /** Caption for the media */
+    caption?: string;
+    /** Filename (for documents) */
+    filename?: string;
+}
+interface SendImageOptions extends SendMessageOptions {
+    /** Image configuration */
+    image: MediaObject;
+    /** Message ID to reply to */
+    replyTo?: string;
+}
+interface SendVideoOptions extends SendMessageOptions {
+    /** Video configuration */
+    video: MediaObject;
+    /** Message ID to reply to */
+    replyTo?: string;
+}
+interface SendAudioOptions extends SendMessageOptions {
+    /** Audio configuration */
+    audio: MediaObject;
+    /** Message ID to reply to */
+    replyTo?: string;
+}
+interface SendDocumentOptions extends SendMessageOptions {
+    /** Document configuration */
+    document: MediaObject;
+    /** Message ID to reply to */
+    replyTo?: string;
+}
+interface SendReactionOptions extends SendMessageOptions {
+    /** Reaction configuration */
+    reaction: {
+        /** Message ID to react to */
+        messageId: string;
+        /** Emoji to react with (empty string to remove reaction) */
+        emoji: string;
+    };
+}
+interface InteractiveButton {
+    type: 'reply';
+    reply: {
+        id: string;
+        title: string;
+    };
+}
+interface InteractiveListSection {
+    title?: string;
+    rows: Array<{
+        id: string;
+        title: string;
+        description?: string;
+    }>;
+}
+interface InteractiveMessage {
+    type: 'button' | 'list' | 'product' | 'product_list';
+    header?: {
+        type: 'text' | 'image' | 'video' | 'document';
+        text?: string;
+        image?: MediaObject;
+        video?: MediaObject;
+        document?: MediaObject;
+    };
+    body: {
+        text: string;
+    };
+    footer?: {
+        text: string;
+    };
+    action: {
+        button?: string;
+        buttons?: InteractiveButton[];
+        sections?: InteractiveListSection[];
+    };
+}
+interface SendInteractiveOptions extends SendMessageOptions {
+    /** Interactive message configuration */
+    interactive: InteractiveMessage;
+    /** Message ID to reply to */
+    replyTo?: string;
+}
+interface MessageContact {
+    input: string;
+    wa_id: string;
+}
+interface MessageResult {
+    id: string;
+}
+interface MessageResponseData {
+    messaging_product: 'whatsapp';
+    contacts: MessageContact[];
+    messages: MessageResult[];
+}
+type TemplateStatus = 'APPROVED' | 'PENDING' | 'REJECTED';
+interface TemplateInfo {
+    name: string;
+    status: TemplateStatus;
+    category: string;
+    language: string;
+}
+interface ListTemplatesOptions {
+    /** Filter by status */
+    status?: TemplateStatus;
+}
+interface PhoneNumber {
+    id: string;
+    display_phone_number: string;
+    verified_name: string;
+    quality_rating?: string;
+}
+interface UsagePeriod {
+    start: string;
+    end: string;
+}
+interface UsageMessages {
+    sent: number;
+    received: number;
+}
+interface UsageData {
+    period: UsagePeriod;
+    messages: UsageMessages;
+    api_calls: number;
+}
+interface TriggerWebhookOptions {
+    /** Phone Number ID */
+    phoneNumberId: string;
+    /** Type of incoming message to simulate */
+    type?: 'text' | 'image';
+    /** Sender phone number */
+    from?: string;
+    /** Text content (for text type) */
+    text?: string;
+}
+interface VerifyWebhookOptions {
+    /** Raw request body (string or object) */
+    payload: string | object;
+    /** X-Semboja-Signature header value */
+    signature: string;
+    /** X-Semboja-Timestamp header value */
+    timestamp: string;
+    /** Your webhook secret */
+    secret: string;
+}
+
+/**
+ * Messages API resource
+ *
+ * @example
+ * ```typescript
+ * await client.messages.sendText({
+ *   phoneNumberId: '123456789',
+ *   to: '+6281234567890',
+ *   text: 'Hello from Semboja!',
+ * });
+ * ```
+ */
+declare class Messages {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Send a text message
+     *
+     * @param options - Text message options
+     * @returns Message response with message ID
+     *
+     * @example
+     * ```typescript
+     * const result = await client.messages.sendText({
+     *   phoneNumberId: '123456789',
+     *   to: '+6281234567890',
+     *   text: 'Hello, World!',
+     *   previewUrl: true,
+     * });
+     * console.log('Message ID:', result.data.messages[0].id);
+     * ```
+     */
+    sendText(options: SendTextOptions): Promise<ApiResponse<MessageResponseData>>;
+    /**
+     * Send a template message
+     *
+     * @param options - Template message options
+     * @returns Message response with message ID
+     *
+     * @example
+     * ```typescript
+     * const result = await client.messages.sendTemplate({
+     *   phoneNumberId: '123456789',
+     *   to: '+6281234567890',
+     *   template: {
+     *     name: 'hello_world',
+     *     language: { code: 'en' },
+     *   },
+     * });
+     * ```
+     */
+    sendTemplate(options: SendTemplateOptions): Promise<ApiResponse<MessageResponseData>>;
+    /**
+     * Send an image message
+     *
+     * @param options - Image message options
+     * @returns Message response with message ID
+     *
+     * @example
+     * ```typescript
+     * const result = await client.messages.sendImage({
+     *   phoneNumberId: '123456789',
+     *   to: '+6281234567890',
+     *   image: {
+     *     link: 'https://example.com/image.jpg',
+     *     caption: 'Check this out!',
+     *   },
+     * });
+     * ```
+     */
+    sendImage(options: SendImageOptions): Promise<ApiResponse<MessageResponseData>>;
+    /**
+     * Send a video message
+     *
+     * @param options - Video message options
+     * @returns Message response with message ID
+     */
+    sendVideo(options: SendVideoOptions): Promise<ApiResponse<MessageResponseData>>;
+    /**
+     * Send an audio message
+     *
+     * @param options - Audio message options
+     * @returns Message response with message ID
+     */
+    sendAudio(options: SendAudioOptions): Promise<ApiResponse<MessageResponseData>>;
+    /**
+     * Send a document message
+     *
+     * @param options - Document message options
+     * @returns Message response with message ID
+     *
+     * @example
+     * ```typescript
+     * const result = await client.messages.sendDocument({
+     *   phoneNumberId: '123456789',
+     *   to: '+6281234567890',
+     *   document: {
+     *     link: 'https://example.com/invoice.pdf',
+     *     filename: 'invoice.pdf',
+     *     caption: 'Your invoice',
+     *   },
+     * });
+     * ```
+     */
+    sendDocument(options: SendDocumentOptions): Promise<ApiResponse<MessageResponseData>>;
+    /**
+     * Send a reaction to a message
+     *
+     * @param options - Reaction options
+     * @returns Message response
+     *
+     * @example
+     * ```typescript
+     * // Add reaction
+     * await client.messages.sendReaction({
+     *   phoneNumberId: '123456789',
+     *   to: '+6281234567890',
+     *   reaction: {
+     *     messageId: 'wamid.xxx',
+     *     emoji: '👍',
+     *   },
+     * });
+     *
+     * // Remove reaction
+     * await client.messages.sendReaction({
+     *   phoneNumberId: '123456789',
+     *   to: '+6281234567890',
+     *   reaction: {
+     *     messageId: 'wamid.xxx',
+     *     emoji: '',
+     *   },
+     * });
+     * ```
+     */
+    sendReaction(options: SendReactionOptions): Promise<ApiResponse<MessageResponseData>>;
+    /**
+     * Send an interactive message (buttons, lists, etc.)
+     *
+     * @param options - Interactive message options
+     * @returns Message response with message ID
+     *
+     * @example
+     * ```typescript
+     * // Button message
+     * await client.messages.sendInteractive({
+     *   phoneNumberId: '123456789',
+     *   to: '+6281234567890',
+     *   interactive: {
+     *     type: 'button',
+     *     body: { text: 'Choose an option:' },
+     *     action: {
+     *       buttons: [
+     *         { type: 'reply', reply: { id: 'yes', title: 'Yes' } },
+     *         { type: 'reply', reply: { id: 'no', title: 'No' } },
+     *       ],
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    sendInteractive(options: SendInteractiveOptions): Promise<ApiResponse<MessageResponseData>>;
+}
+
+/**
+ * Templates API resource
+ *
+ * @example
+ * ```typescript
+ * const templates = await client.templates.list();
+ * const approved = await client.templates.list({ status: 'APPROVED' });
+ * ```
+ */
+declare class Templates {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List all message templates
+     *
+     * @param options - Optional filters
+     * @returns List of templates
+     *
+     * @example
+     * ```typescript
+     * const templates = await client.templates.list();
+     * console.log('Templates:', templates.data);
+     *
+     * // Filter by status
+     * const approved = await client.templates.list({ status: 'APPROVED' });
+     * ```
+     */
+    list(options?: ListTemplatesOptions): Promise<ApiResponse<TemplateInfo[]>>;
+}
+
+/**
+ * Phone Numbers API resource
+ *
+ * @example
+ * ```typescript
+ * const phoneNumbers = await client.phoneNumbers.list();
+ * ```
+ */
+declare class PhoneNumbers {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List all phone numbers configured for your account
+     *
+     * @returns List of phone numbers
+     *
+     * @example
+     * ```typescript
+     * const phoneNumbers = await client.phoneNumbers.list();
+     * for (const phone of phoneNumbers.data) {
+     *   console.log(`${phone.verified_name}: ${phone.display_phone_number}`);
+     * }
+     * ```
+     */
+    list(): Promise<ApiResponse<PhoneNumber[]>>;
+}
+
+/**
+ * Usage API resource
+ *
+ * @example
+ * ```typescript
+ * const usage = await client.usage.get();
+ * console.log(`Sent: ${usage.data.messages.sent}`);
+ * ```
+ */
+declare class Usage {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get current usage statistics for the billing period
+     *
+     * @returns Usage statistics
+     *
+     * @example
+     * ```typescript
+     * const usage = await client.usage.get();
+     * console.log(`Period: ${usage.data.period.start} - ${usage.data.period.end}`);
+     * console.log(`Messages sent: ${usage.data.messages.sent}`);
+     * console.log(`Messages received: ${usage.data.messages.received}`);
+     * console.log(`API calls: ${usage.data.api_calls}`);
+     * ```
+     */
+    get(): Promise<ApiResponse<UsageData>>;
+}
+
+/**
+ * Test API resource (only works with sk_test_* keys)
+ *
+ * @example
+ * ```typescript
+ * // Trigger a test webhook
+ * await client.test.triggerWebhook({
+ *   phoneNumberId: '123456789',
+ *   type: 'text',
+ *   from: '+6281234567890',
+ *   text: 'Test message',
+ * });
+ * ```
+ */
+declare class Test {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Trigger a test webhook to simulate an incoming message
+     *
+     * **Note:** This only works with test API keys (sk_test_*)
+     *
+     * @param options - Webhook trigger options
+     * @returns Success response
+     *
+     * @example
+     * ```typescript
+     * await client.test.triggerWebhook({
+     *   phoneNumberId: '123456789',
+     *   type: 'text',
+     *   from: '+6281234567890',
+     *   text: 'Hello, this is a test incoming message!',
+     * });
+     * ```
+     */
+    triggerWebhook(options: TriggerWebhookOptions): Promise<ApiResponse<{
+        queued: boolean;
+    }>>;
+}
+
+/**
+ * Semboja WhatsApp API Client
+ *
+ * @example
+ * ```typescript
+ * import { SembojaClient } from '@semboja/connect';
+ *
+ * // Simple initialization
+ * const client = new SembojaClient('sk_live_your_api_key');
+ *
+ * // With options
+ * const client = new SembojaClient({
+ *   apiKey: process.env.SEMBOJA_API_KEY!,
+ *   timeout: 60000,
+ *   retries: 5,
+ * });
+ *
+ * // Send a message
+ * await client.messages.sendText({
+ *   phoneNumberId: '123456789',
+ *   to: '+6281234567890',
+ *   text: 'Hello from Semboja!',
+ * });
+ * ```
+ */
+declare class SembojaClient {
+    /** Messages API */
+    readonly messages: Messages;
+    /** Templates API */
+    readonly templates: Templates;
+    /** Phone Numbers API */
+    readonly phoneNumbers: PhoneNumbers;
+    /** Usage API */
+    readonly usage: Usage;
+    /** Test API (only works with sk_test_* keys) */
+    readonly test: Test;
+    /** Whether the client is in test mode */
+    readonly isTestMode: boolean;
+    private readonly http;
+    /**
+     * Create a new Semboja client
+     *
+     * @param optionsOrApiKey - API key string or client options object
+     *
+     * @example
+     * ```typescript
+     * // Using API key directly
+     * const client = new SembojaClient('sk_live_xxx');
+     *
+     * // Using options object
+     * const client = new SembojaClient({
+     *   apiKey: 'sk_live_xxx',
+     *   timeout: 60000,
+     *   retries: 5,
+     * });
+     * ```
+     */
+    constructor(optionsOrApiKey: string | ClientOptions);
+}
+
+/**
+ * Verify a webhook signature from Semboja
+ *
+ * @param options - Verification options
+ * @returns true if the signature is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from '@semboja/connect';
+ *
+ * // Express.js example
+ * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const isValid = verifyWebhookSignature({
+ *     payload: req.body,
+ *     signature: req.headers['x-semboja-signature'] as string,
+ *     timestamp: req.headers['x-semboja-timestamp'] as string,
+ *     secret: process.env.WEBHOOK_SECRET!,
+ *   });
+ *
+ *   if (!isValid) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   // Process the webhook
+ *   const event = JSON.parse(req.body.toString());
+ *   console.log('Received event:', event);
+ *
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Hono example
+ * app.post('/webhook', async (c) => {
+ *   const body = await c.req.text();
+ *   const signature = c.req.header('x-semboja-signature');
+ *   const timestamp = c.req.header('x-semboja-timestamp');
+ *
+ *   const isValid = verifyWebhookSignature({
+ *     payload: body,
+ *     signature: signature!,
+ *     timestamp: timestamp!,
+ *     secret: process.env.WEBHOOK_SECRET!,
+ *   });
+ *
+ *   if (!isValid) {
+ *     return c.text('Invalid signature', 401);
+ *   }
+ *
+ *   const event = JSON.parse(body);
+ *   // Process the webhook...
+ *
+ *   return c.text('OK');
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature(options: VerifyWebhookOptions): boolean;
+/**
+ * Parse a webhook payload into a typed event object
+ *
+ * @param payload - Raw webhook payload (string or object)
+ * @returns Parsed webhook event
+ */
+declare function parseWebhookPayload<T = unknown>(payload: string | object): T;
+
+/**
+ * Base error class for all Semboja API errors
+ */
+declare class SembojaError extends Error {
+    /** Error code from the API */
+    readonly code: string;
+    /** HTTP status code */
+    readonly statusCode: number;
+    /** Request ID for debugging */
+    readonly requestId?: string;
+    constructor(message: string, code: string, statusCode: number, requestId?: string);
+}
+/**
+ * Authentication error (invalid or missing API key)
+ */
+declare class AuthenticationError extends SembojaError {
+    constructor(message: string, requestId?: string);
+}
+/**
+ * Rate limit exceeded error
+ */
+declare class RateLimitError extends SembojaError {
+    /** When the rate limit resets (Unix timestamp) */
+    readonly resetAt?: number;
+    constructor(message: string, requestId?: string, resetAt?: number);
+}
+/**
+ * Validation error (invalid request parameters)
+ */
+declare class ValidationError extends SembojaError {
+    constructor(message: string, requestId?: string);
+}
+/**
+ * Resource not found error
+ */
+declare class NotFoundError extends SembojaError {
+    constructor(message: string, code: string, requestId?: string);
+}
+/**
+ * Server error from Semboja API
+ */
+declare class ServerError extends SembojaError {
+    constructor(message: string, requestId?: string);
+}
+/**
+ * Network or connection error
+ */
+declare class NetworkError extends SembojaError {
+    constructor(message: string);
+}
+
+export { type ApiErrorResponse, type ApiResponse, AuthenticationError, type ClientOptions, type InteractiveButton, type InteractiveListSection, type InteractiveMessage, type ListTemplatesOptions, type MediaObject, type MessageContact, type MessageResponseData, type MessageResult, type MessageType, NetworkError, NotFoundError, type PhoneNumber, RateLimitError, SembojaClient, SembojaError, type SendAudioOptions, type SendDocumentOptions, type SendImageOptions, type SendInteractiveOptions, type SendMessageOptions, type SendReactionOptions, type SendTemplateOptions, type SendTextOptions, type SendVideoOptions, ServerError, type Template, type TemplateComponent, type TemplateInfo, type TemplateLanguage, type TemplateParameter, type TemplateStatus, type TriggerWebhookOptions, type UsageData, type UsageMessages, type UsagePeriod, ValidationError, type VerifyWebhookOptions, parseWebhookPayload, verifyWebhookSignature };