sendrly/dist/index.d.mts

Official Sendrly TypeScript/JavaScript SDK - Simple, type-safe email automation for developers

/**
 * Configuration for initializing the Sendrly SDK
 */
interface SendrlyConfig {
    /** Your Sendrly API key */
    apiKey: string;
    /** Enable debug logging */
    debug?: boolean;
}
/**
 * Error codes for Sendrly SDK errors
 */
type SendrlyErrorCode = 'INVALID_CONFIG' | 'INVALID_API_KEY' | 'NOT_FOUND' | 'API_ERROR' | 'UNKNOWN_ERROR';
/**
 * Custom error class for Sendrly SDK errors
 */
declare class SendrlyError extends Error {
    readonly code: SendrlyErrorCode;
    constructor(message: string, code: SendrlyErrorCode);
}
/**
 * User-facing payload for triggering events
 * This is what users of the SDK will provide
 */
type EventPayload = {
    /** Contact's email address */
    email: string;
    /** Name of the event to trigger */
    event: string;
    /** Whether the contact has opted out of marketing */
    marketing_opt_out?: boolean;
    /** Properties to attach to the contact */
    contact_properties?: Record<string, unknown>;
    /** Properties to attach to the event */
    event_properties?: Record<string, unknown>;
};
/**
 * Response from the /find-contact edge function
 */
interface ContactResponse {
    /** Unique identifier for the contact */
    id: string;
    /** Whether the contact has opted out of marketing */
    marketing_opt_out: boolean;
    /** Custom properties associated with the contact */
    properties: Record<string, unknown>;
    /** List of email addresses associated with the contact */
    emails: Array<{
        /** Email address */
        email: string;
        /** Status of the email (e.g., "active", "bounced") */
        status: string;
    }>;
}
/**
 * Response from the /get-event edge function
 */
interface EventResponse {
    /** Unique identifier for the event */
    id: string;
    /** Name of the event */
    event_name: string;
    /** Properties associated with the event */
    event_properties: Record<string, unknown>;
    /** ID of the contact who triggered the event */
    contact_id: string;
    /** When the event was received */
    received_at: string;
    /** Email addresses associated with the contact */
    contact_emails: Array<{
        /** Email address */
        email: string;
        /** Status of the email */
        status: string;
    }>;
}

/**
 * Main Sendrly SDK class for tracking events and managing contacts
 * @example
 * const sendrly = new Sendrly({
 *   apiKey: 'your_api_key',
 *   debug: true
 * })
 */
declare class Sendrly {
    #private;
    constructor(config: SendrlyConfig);
    /**
     * Send an event for a contact
     * @example
     * // Simple event tracking
     * await sendrly.sendEvent({
     *   email: 'sarah@startup.com',
     *   event: 'user.welcome'
     * })
     *
     * // Event with properties
     * await sendrly.sendEvent({
     *   email: 'john@company.com',
     *   event: 'order.completed',
     *   contact_properties: {
     *     name: 'John Smith',
     *     plan: 'enterprise'
     *   },
     *   event_properties: {
     *     order_id: 'ORD-123',
     *     amount: 499.99
     *   }
     * })
     */
    sendEvent(payload: EventPayload): Promise<void>;
    /**
     * Get a contact by email address
     * @example
     * // Get contact details
     * const contact = await sendrly.getContact('sarah@startup.com')
     * console.log(contact.properties.name) // 'Sarah'
     *
     * // Handle non-existent contact
     * try {
     *   const contact = await sendrly.getContact('unknown@email.com')
     * } catch (error) {
     *   if (error.code === 'NOT_FOUND') {
     *     console.log('Contact does not exist')
     *   }
     * }
     */
    getContact(email: string): Promise<ContactResponse>;
    /**
     * List all events with a specific name
     * @example
     * // List all signup events
     * const signups = await sendrly.listEvents('user.signup')
     * console.log(signups[0].event_properties.source)
     *
     * // Process completed orders
     * const orders = await sendrly.listEvents('order.completed')
     * const totalRevenue = orders.reduce((sum, order) =>
     *   sum + order.event_properties.amount, 0
     * )
     */
    listEvents(eventName: string): Promise<EventResponse[]>;
    /**
     * Delete a contact and all associated data
     * @example
     * // Delete a contact
     * await sendrly.deleteContact('sarah@startup.com')
     *
     * // Handle non-existent contact
     * try {
     *   await sendrly.deleteContact('unknown@email.com')
     * } catch (error) {
     *   if (error.code === 'NOT_FOUND') {
     *     console.log('Contact already deleted')
     *   }
     * }
     */
    deleteContact(email: string): Promise<void>;
}

export { type ContactResponse, type EventPayload, type EventResponse, Sendrly, type SendrlyConfig, SendrlyError, Sendrly as default };