@sendmailos/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,480 @@
+/**
+ * SendMailOS SDK Types
+ */
+interface SendMailOSOptions {
+    /** Base URL for the API (default: https://api.sendmailos.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Custom fetch implementation (for testing/Node.js polyfill) */
+    fetch?: typeof fetch;
+}
+interface SendEmailRequest {
+    /** Recipient email address */
+    to: string;
+    /** Email subject line (supports Handlebars variables) */
+    subject: string;
+    /** HTML content (required if no templateId) */
+    html?: string;
+    /** Template ID to use (required if no html) */
+    templateId?: string;
+    /** Sender display name (default: "System") */
+    fromName?: string;
+    /** Sender email address (must be from verified domain) */
+    fromEmail?: string;
+    /** Template variables for Handlebars interpolation */
+    variables?: Record<string, unknown>;
+    /** Email type: "transactional" (default) or "marketing" */
+    type?: 'transactional' | 'marketing';
+}
+interface SendEmailResponse {
+    success: boolean;
+    message: string;
+    id: string;
+    sandbox?: boolean;
+}
+interface Subscriber {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    status: 'subscribed' | 'unsubscribed' | 'bounced' | 'complained';
+    tags?: string[];
+    source: string;
+    createdAt: string;
+    primaryDomain?: {
+        id: string;
+        domainName: string;
+    };
+}
+interface CreateSubscriberRequest {
+    /** Subscriber email address */
+    email: string;
+    /** First name (for personalization) */
+    firstName?: string;
+    /** Last name (for personalization) */
+    lastName?: string;
+    /** Tags for segmentation */
+    tags?: string[];
+    /** Associate with a specific domain */
+    domainId?: string;
+}
+interface CreateSubscriberResponse {
+    success: boolean;
+    subscriber: Subscriber;
+}
+interface ListSubscribersRequest {
+    /** Results per page (default: 20, max: 100) */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+}
+interface ListSubscribersResponse {
+    success: boolean;
+    subscribers: Subscriber[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface SendCampaignRequest {
+    /** Campaign name (for tracking) */
+    name?: string;
+    /** Email subject line (supports Handlebars) */
+    subject: string;
+    /** Sender display name */
+    fromName: string;
+    /** Sender email (from verified domain) */
+    fromEmail: string;
+    /** HTML content (required if no templateId) */
+    html?: string;
+    /** Template ID (required if no html) */
+    templateId?: string;
+    /** Filter subscribers by tags (AND logic) */
+    tags?: string[];
+    /** Global template variables */
+    variables?: Record<string, unknown>;
+}
+interface SendCampaignResponse {
+    success: boolean;
+    message: string;
+    campaignId: string;
+}
+interface Domain {
+    id: string;
+    domainName: string;
+    status: 'pending' | 'verified' | 'failed';
+    dkimTokens: string[];
+    createdAt: string;
+    verifiedAt?: string;
+    dnsRecords?: DnsRecord[];
+}
+interface DnsRecord {
+    type: 'CNAME' | 'TXT' | 'MX';
+    name: string;
+    value: string;
+}
+interface CreateDomainRequest {
+    /** Domain name (e.g., "yourcompany.com") */
+    domain: string;
+}
+interface CreateDomainResponse {
+    success: boolean;
+    domain: Domain;
+}
+interface ListDomainsResponse {
+    success: boolean;
+    domains: Domain[];
+}
+type WebhookEventType = 'email.sent' | 'email.delivered' | 'email.opened' | 'email.clicked' | 'email.bounced' | 'email.complained';
+interface WebhookEvent {
+    id: string;
+    type: WebhookEventType;
+    createdAt: string;
+    data: {
+        emailId: string;
+        messageId: string;
+        recipient: string;
+        campaignId?: string;
+        timestamp: string;
+        metadata?: Record<string, unknown>;
+    };
+}
+interface CreateWebhookRequest {
+    /** Endpoint URL to receive webhook events */
+    url: string;
+    /** Events to subscribe to */
+    events: WebhookEventType[];
+    /** Signing secret for webhook verification */
+    secret?: string;
+}
+interface Webhook {
+    id: string;
+    url: string;
+    events: WebhookEventType[];
+    active: boolean;
+    createdAt: string;
+}
+interface ApiError {
+    success: false;
+    error: string;
+    code: string;
+    retryAfter?: number;
+}
+
+/**
+ * Emails resource for sending transactional emails
+ */
+declare class EmailsResource {
+    private request;
+    constructor(request: <T>(endpoint: string, options?: RequestInit) => Promise<T>);
+    /**
+     * Send a transactional email
+     *
+     * @example
+     * ```ts
+     * const result = await client.emails.send({
+     *   to: 'user@example.com',
+     *   fromName: 'Your Company',
+     *   fromEmail: 'hello@yourcompany.com',
+     *   subject: 'Welcome!',
+     *   html: '<h1>Hello!</h1>'
+     * });
+     * ```
+     */
+    send(params: SendEmailRequest): Promise<SendEmailResponse>;
+    /**
+     * Send email using a template
+     *
+     * @example
+     * ```ts
+     * const result = await client.emails.sendTemplate({
+     *   to: 'user@example.com',
+     *   templateId: 'tmpl_welcome',
+     *   variables: { firstName: 'John' }
+     * });
+     * ```
+     */
+    sendTemplate(params: {
+        to: string;
+        templateId: string;
+        fromName?: string;
+        fromEmail?: string;
+        subject?: string;
+        variables?: Record<string, unknown>;
+    }): Promise<SendEmailResponse>;
+}
+
+/**
+ * Subscribers resource for managing email contacts
+ */
+declare class SubscribersResource {
+    private request;
+    constructor(request: <T>(endpoint: string, options?: RequestInit) => Promise<T>);
+    /**
+     * Create or update a subscriber (upsert)
+     *
+     * @example
+     * ```ts
+     * const { subscriber } = await client.subscribers.create({
+     *   email: 'user@example.com',
+     *   firstName: 'John',
+     *   tags: ['newsletter', 'premium']
+     * });
+     * ```
+     */
+    create(params: CreateSubscriberRequest): Promise<CreateSubscriberResponse>;
+    /**
+     * List all subscribers with pagination
+     *
+     * @example
+     * ```ts
+     * const { subscribers, total } = await client.subscribers.list({
+     *   limit: 50,
+     *   offset: 0
+     * });
+     * ```
+     */
+    list(params?: ListSubscribersRequest): Promise<ListSubscribersResponse>;
+    /**
+     * Get a single subscriber by ID
+     */
+    get(subscriberId: string): Promise<{
+        success: boolean;
+        subscriber: Subscriber;
+    }>;
+    /**
+     * Update a subscriber by ID
+     */
+    update(subscriberId: string, params: Partial<CreateSubscriberRequest>): Promise<CreateSubscriberResponse>;
+    /**
+     * Update a subscriber by email address
+     */
+    updateByEmail(email: string, params: Partial<Omit<CreateSubscriberRequest, 'email'>>): Promise<CreateSubscriberResponse>;
+    /**
+     * Delete/unsubscribe a subscriber
+     */
+    delete(subscriberId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Add tags to a subscriber
+     */
+    addTags(subscriberId: string, tags: string[]): Promise<CreateSubscriberResponse>;
+    /**
+     * Remove tags from a subscriber
+     */
+    removeTags(subscriberId: string, tags: string[]): Promise<CreateSubscriberResponse>;
+}
+
+/**
+ * Campaigns resource for bulk email sending
+ */
+declare class CampaignsResource {
+    private request;
+    constructor(request: <T>(endpoint: string, options?: RequestInit) => Promise<T>);
+    /**
+     * Send a campaign to subscribers
+     *
+     * @example
+     * ```ts
+     * const result = await client.campaigns.send({
+     *   name: 'January Newsletter',
+     *   subject: 'What\'s new this month',
+     *   fromName: 'Your Company',
+     *   fromEmail: 'news@yourcompany.com',
+     *   html: '<h1>Hello {{first_name}}!</h1>',
+     *   tags: ['newsletter', 'active']
+     * });
+     * ```
+     */
+    send(params: SendCampaignRequest): Promise<SendCampaignResponse>;
+    /**
+     * Send campaign using a saved template
+     */
+    sendTemplate(params: {
+        name?: string;
+        templateId: string;
+        subject: string;
+        fromName: string;
+        fromEmail: string;
+        tags?: string[];
+        variables?: Record<string, unknown>;
+    }): Promise<SendCampaignResponse>;
+}
+
+/**
+ * Domains resource for managing sending domains
+ */
+declare class DomainsResource {
+    private request;
+    constructor(request: <T>(endpoint: string, options?: RequestInit) => Promise<T>);
+    /**
+     * Add a new sending domain
+     * Returns DKIM tokens and DNS records for verification
+     *
+     * @example
+     * ```ts
+     * const { domain } = await client.domains.create({
+     *   domain: 'yourcompany.com'
+     * });
+     *
+     * console.log('Add these DNS records:', domain.dnsRecords);
+     * ```
+     */
+    create(params: CreateDomainRequest): Promise<CreateDomainResponse>;
+    /**
+     * List all domains for the organization
+     */
+    list(): Promise<ListDomainsResponse>;
+    /**
+     * Get a single domain by ID
+     */
+    get(domainId: string): Promise<{
+        success: boolean;
+        domain: Domain;
+    }>;
+    /**
+     * Verify a domain (trigger DNS check)
+     */
+    verify(domainId: string): Promise<{
+        success: boolean;
+        domain: Domain;
+    }>;
+    /**
+     * Delete a domain
+     */
+    delete(domainId: string): Promise<{
+        success: boolean;
+    }>;
+}
+
+/**
+ * SendMailOS SDK Client
+ *
+ * @example
+ * ```ts
+ * import { SendMailOS } from '@sendmailos/sdk';
+ *
+ * const client = new SendMailOS('sk_live_your_api_key');
+ *
+ * // Send an email
+ * await client.emails.send({
+ *   to: 'user@example.com',
+ *   subject: 'Hello!',
+ *   html: '<h1>Welcome!</h1>'
+ * });
+ *
+ * // Add a subscriber
+ * await client.subscribers.create({
+ *   email: 'user@example.com',
+ *   tags: ['newsletter']
+ * });
+ * ```
+ */
+declare class SendMailOS {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly fetchFn;
+    /** Email sending operations */
+    readonly emails: EmailsResource;
+    /** Subscriber management */
+    readonly subscribers: SubscribersResource;
+    /** Campaign operations */
+    readonly campaigns: CampaignsResource;
+    /** Domain management */
+    readonly domains: DomainsResource;
+    constructor(apiKey: string, options?: SendMailOSOptions);
+    /**
+     * Make an authenticated request to the API
+     */
+    private request;
+    private safeParseJson;
+    /**
+     * Check if the API key is valid (test mode only)
+     */
+    get isTestMode(): boolean;
+    /**
+     * Get the SDK version
+     */
+    static get version(): string;
+}
+
+/**
+ * Custom error classes for SendMailOS SDK
+ */
+declare class SendMailOSError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly retryAfter?: number;
+    constructor(message: string, code: string, statusCode: number, retryAfter?: number);
+    /** Whether this error is retryable (rate limit or server error) */
+    get isRetryable(): boolean;
+}
+declare class AuthenticationError extends SendMailOSError {
+    constructor(message?: string);
+}
+declare class ValidationError extends SendMailOSError {
+    constructor(message: string);
+}
+declare class RateLimitError extends SendMailOSError {
+    constructor(message: string, retryAfter: number);
+}
+declare class NotFoundError extends SendMailOSError {
+    constructor(message: string);
+}
+
+/**
+ * Webhook signature verification utilities
+ *
+ * IMPORTANT: This module uses timing-safe comparison to prevent timing attacks.
+ */
+interface VerifyWebhookParams {
+    /** Raw request body as string */
+    payload: string;
+    /** Value of X-SendMailOS-Signature header */
+    signature: string;
+    /** Value of X-SendMailOS-Timestamp header */
+    timestamp: string;
+    /** Your webhook signing secret */
+    secret: string;
+    /** Maximum age in seconds (default: 300 = 5 minutes) */
+    tolerance?: number;
+}
+/**
+ * Verify a webhook signature to ensure the request came from SendMailOS
+ *
+ * @example
+ * ```ts
+ * import { verifyWebhookSignature } from '@sendmailos/sdk';
+ *
+ * app.post('/webhooks', (req, res) => {
+ *   const isValid = verifyWebhookSignature({
+ *     payload: JSON.stringify(req.body),
+ *     signature: req.headers['x-sendmailos-signature'],
+ *     timestamp: req.headers['x-sendmailos-timestamp'],
+ *     secret: process.env.WEBHOOK_SECRET
+ *   });
+ *
+ *   if (!isValid) {
+ *     return res.status(401).json({ error: 'Invalid signature' });
+ *   }
+ *
+ *   // Process webhook...
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature(params: VerifyWebhookParams): boolean;
+/**
+ * Async version of webhook verification (recommended for edge/browser)
+ */
+declare function verifyWebhookSignatureAsync(params: VerifyWebhookParams): Promise<boolean>;
+/**
+ * Construct a webhook event from raw request data
+ */
+declare function constructWebhookEvent<T = unknown>(payload: string, headers: {
+    signature: string;
+    timestamp: string;
+}, secret: string): T;
+
+export { type ApiError, AuthenticationError, type CreateDomainRequest, type CreateDomainResponse, type CreateSubscriberRequest, type CreateSubscriberResponse, type CreateWebhookRequest, type DnsRecord, type Domain, type ListDomainsResponse, type ListSubscribersRequest, type ListSubscribersResponse, NotFoundError, RateLimitError, type SendCampaignRequest, type SendCampaignResponse, type SendEmailRequest, type SendEmailResponse, SendMailOS, SendMailOSError, type SendMailOSOptions, type Subscriber, ValidationError, type VerifyWebhookParams, type Webhook, type WebhookEvent, type WebhookEventType, constructWebhookEvent, SendMailOS as default, verifyWebhookSignature, verifyWebhookSignatureAsync };