@masters-union/outbound-sdk 0.0.10

package/dist/index.d.ts

@@ -0,0 +1,473 @@
+interface OutboundConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+}
+interface ResolvedConfig {
+    apiKey?: string;
+    baseUrl: string;
+    timeout: number;
+    maxRetries: number;
+    retryDelay: number;
+}
+interface RequestOverrides {
+    apiKey?: string;
+}
+interface SendEmailParams {
+    toEmail: string;
+    fromEmail: string;
+    emailSubject: string;
+    htmlBody: string;
+    ccEmail?: string;
+    bccEmail?: string;
+    senderName?: string;
+    replyTo?: string;
+    textBody?: string;
+    priority?: 'low' | 'normal' | 'high';
+    idempotencyKey?: string;
+    campaignId?: string;
+    metadata?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    tracking?: Record<string, unknown>;
+    attachments?: Attachment[];
+}
+interface Attachment {
+    filename: string;
+    content: string;
+    contentType: string;
+}
+interface SendEmailResponse {
+    message: string;
+    jobId: string;
+    messageId: string;
+    duplicate?: boolean;
+}
+interface BulkEmailParams {
+    fromEmail: string;
+    emailSubject: string;
+    emails: BulkEmailRecipient[];
+    senderName?: string;
+    replyTo?: string;
+    idempotencyKey?: string;
+    campaignId?: string;
+}
+interface BulkEmailRecipient {
+    toEmail: string;
+    htmlBody: string;
+    subject?: string;
+    textBody?: string;
+    ccEmail?: string;
+    bccEmail?: string;
+    metadata?: Record<string, unknown>;
+    attachments?: Attachment[];
+}
+interface BulkEmailResponse {
+    message: string;
+    jobId: string;
+    recipientCount: number;
+    suppressedCount: number;
+    /**
+     * List of email addresses that were filtered out due to suppression.
+     * Present on the first (live) response only.
+     * Absent when `duplicate: true` — use `suppressedCount` instead.
+     */
+    suppressedEmails?: string[];
+    duplicatesRemoved?: number;
+    duplicate?: boolean;
+}
+interface EmailJob {
+    job_id: string;
+    tenant_id: string;
+    status: 'queued' | 'processing' | 'completed' | 'failed' | 'partial' | 'retrying' | 'cancelled';
+    campaign_id?: string;
+    recipient_count: number;
+    sent_count: number;
+    failed_count: number;
+    metadata?: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+interface JobStatusResponse {
+    lookupType: 'jobId' | 'sesMessageId';
+    job?: EmailJob;
+    recipients?: EmailRecipientStatus[];
+}
+interface EmailRecipientStatus {
+    message_id: string;
+    recipient_email: string;
+    status: EmailStatus;
+    ses_message_id?: string;
+    error_message?: string;
+    created_at: string;
+}
+type EmailStatus = 'queued' | 'processing' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'opened' | 'clicked' | 'failed' | 'cancelled';
+interface CancelEmailParams {
+    /** Cancel all jobs belonging to this campaign. */
+    campaignId?: string;
+    /** Cancel a specific job by its ID. */
+    jobId?: string;
+}
+interface CancelEmailResponse {
+    message: string;
+    /** Number of jobs that were cancelled. */
+    cancelledJobs: number;
+    /** Number of individual recipient records set to cancelled. */
+    cancelledRecipients: number;
+    /** Number of jobs successfully removed from the queue before processing started. */
+    removedFromQueue: number;
+}
+interface CreateTemplateParams {
+    name: string;
+    subject: string;
+    htmlBody: string;
+    textBody?: string;
+    variables?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface UpdateTemplateParams {
+    name?: string;
+    subject?: string;
+    htmlBody?: string;
+    textBody?: string;
+    variables?: string[];
+    metadata?: Record<string, unknown>;
+    status?: 'active' | 'archived';
+}
+interface ListTemplatesParams {
+    status?: 'active' | 'archived';
+    search?: string;
+    sortBy?: 'name' | 'createdAt' | 'use_count' | 'last_sent_at';
+    sortOrder?: 'ASC' | 'DESC';
+    page?: number;
+    limit?: number;
+}
+interface ListTemplatesResponse {
+    templates: Template[];
+    total: number;
+    page: number;
+    limit: number;
+    quota: {
+        used: number;
+        allocated: number;
+        remaining: number;
+    };
+}
+interface Template {
+    id: string;
+    tenant_id: string;
+    name: string;
+    subject: string;
+    html_body: string;
+    text_body?: string;
+    variables: string[];
+    use_count: number;
+    last_sent_at?: string;
+    ses_template_name?: string;
+    status: 'active' | 'archived';
+    metadata?: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+interface TemplateResponse {
+    message?: string;
+    template: Template;
+}
+interface TemplateSendParams {
+    templateId: string;
+    toEmail: string;
+    fromEmail: string;
+    senderName?: string;
+    replyTo?: string;
+    ccEmail?: string;
+    bccEmail?: string;
+    variables?: Record<string, string>;
+    priority?: 'low' | 'normal' | 'high';
+    idempotencyKey?: string;
+    campaignId?: string;
+    metadata?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    tracking?: Record<string, unknown>;
+}
+interface TemplateBulkSendParams {
+    templateId: string;
+    fromEmail: string;
+    senderName?: string;
+    replyTo?: string;
+    idempotencyKey?: string;
+    campaignId?: string;
+    recipients: TemplateBulkRecipient[];
+}
+interface TemplateBulkRecipient {
+    toEmail: string;
+    variables?: Record<string, string>;
+    ccEmail?: string;
+    bccEmail?: string;
+    metadata?: Record<string, unknown>;
+}
+interface TemplateBulkSendResponse {
+    message: string;
+    jobId: string;
+    recipientCount: number;
+    suppressedCount: number;
+    /**
+     * List of email addresses filtered out due to suppression.
+     * Present on the first (live) response only.
+     * Absent when `duplicate: true` — use `suppressedCount` instead.
+     */
+    suppressedEmails?: string[];
+    duplicatesRemoved?: number;
+    usingSesTemplate?: boolean;
+    duplicate?: boolean;
+}
+interface TemplatePreviewParams {
+    variables?: Record<string, string>;
+}
+interface TemplatePreviewResponse {
+    subject: string;
+    htmlBody: string;
+    textBody?: string;
+    missingVariables?: string[];
+}
+interface TemplateStatsResponse {
+    quota: {
+        used: number;
+        allocated: number;
+        remaining: number;
+    };
+    counts: {
+        total: number;
+        active: number;
+        archived: number;
+        neverUsed: number;
+    };
+    totalEmailsSentViaTemplates: number;
+    mostUsed: Template[];
+    leastUsed: Template[];
+    recentlyUsed: Template[];
+}
+interface ListSuppressionsParams {
+    page?: number;
+    limit?: number;
+    reason?: 'bounce' | 'complaint' | 'manual' | 'unsubscribe';
+}
+interface ListSuppressionsResponse {
+    suppressions: Suppression[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+    };
+}
+interface Suppression {
+    id: string;
+    tenant_id: string;
+    email: string;
+    reason: string;
+    created_at: string;
+}
+interface AddSuppressionParams {
+    email: string;
+    reason?: 'bounce' | 'complaint' | 'manual' | 'unsubscribe';
+}
+interface SuppressionResponse {
+    suppression: Suppression;
+}
+type WebhookEvent = 'send' | 'delivery' | 'bounce' | 'complaint' | 'open' | 'click' | 'reject' | 'rendering_failure';
+interface CreateWebhookParams {
+    url: string;
+    events: WebhookEvent[];
+    retryInterval?: number;
+    maxRetries?: number;
+}
+interface UpdateWebhookParams {
+    url?: string;
+    events?: WebhookEvent[];
+    active?: boolean;
+    retryInterval?: number;
+    maxRetries?: number;
+}
+interface Webhook {
+    id: string;
+    tenant_id: string;
+    url: string;
+    events: WebhookEvent[];
+    retry_interval: number;
+    max_retries: number;
+    active: boolean;
+    status: 'active' | 'defective';
+    created_at: string;
+}
+interface CreateWebhookResponse {
+    webhook: Webhook;
+    secret: string;
+    warning: string;
+}
+interface UpdateWebhookResponse {
+    message: string;
+    webhook: Webhook;
+}
+interface ListWebhooksResponse {
+    webhooks: Webhook[];
+}
+interface DashboardResponse {
+    quota: Record<string, unknown>;
+    templates: {
+        used: number;
+        active: number;
+        allocated: number;
+        remaining: number;
+    };
+    last30Days: {
+        sent: number;
+        delivered: number;
+        bounced: number;
+        complained: number;
+        opened: number;
+        clicked: number;
+        failed: number;
+    };
+    recentJobs: Record<string, unknown>[];
+}
+interface QuotaResponse {
+    used: number;
+    allocated: number;
+    remaining: number;
+    dailyUsed: number;
+    dailyLimit: number;
+    monthlyUsed: number;
+    monthlyLimit: number;
+    percentageUsed: number;
+    resetDate: string;
+}
+
+declare class HttpClient {
+    private config;
+    constructor(config: ResolvedConfig);
+    get<T>(path: string, params?: Record<string, unknown>, apiKey?: string): Promise<T>;
+    post<T>(path: string, body?: unknown, apiKey?: string): Promise<T>;
+    patch<T>(path: string, body?: unknown, apiKey?: string): Promise<T>;
+    delete<T>(path: string, apiKey?: string): Promise<T>;
+    private resolveApiKey;
+    private request;
+    private buildUrl;
+    private parseError;
+    private sleep;
+}
+
+declare class EmailResource {
+    private http;
+    constructor(http: HttpClient);
+    send(params: SendEmailParams, overrides?: RequestOverrides): Promise<SendEmailResponse>;
+    bulk(params: BulkEmailParams, overrides?: RequestOverrides): Promise<BulkEmailResponse>;
+    status(jobId: string, overrides?: RequestOverrides): Promise<JobStatusResponse>;
+    /**
+     * Cancel all queued/processing emails for a campaign or job.
+     * Provide either `campaignId` (cancels all jobs in that campaign) or `jobId` (cancels one job).
+     * Already-sent emails cannot be recalled — only recipients still in `queued` or `processing` state are cancelled.
+     */
+    cancel(params: CancelEmailParams, overrides?: RequestOverrides): Promise<CancelEmailResponse>;
+}
+
+declare class TemplatesResource {
+    private http;
+    constructor(http: HttpClient);
+    create(params: CreateTemplateParams, overrides?: RequestOverrides): Promise<TemplateResponse>;
+    list(params?: ListTemplatesParams, overrides?: RequestOverrides): Promise<ListTemplatesResponse>;
+    listAll(params?: Omit<ListTemplatesParams, 'page'>, overrides?: RequestOverrides): AsyncGenerator<Template>;
+    get(id: string, overrides?: RequestOverrides): Promise<TemplateResponse>;
+    update(id: string, params: UpdateTemplateParams, overrides?: RequestOverrides): Promise<TemplateResponse>;
+    delete(id: string, overrides?: RequestOverrides): Promise<{
+        message: string;
+        id: string;
+    }>;
+    duplicate(id: string, params?: {
+        name?: string;
+    }, overrides?: RequestOverrides): Promise<TemplateResponse>;
+    preview(id: string, params?: TemplatePreviewParams, overrides?: RequestOverrides): Promise<TemplatePreviewResponse>;
+    send(params: TemplateSendParams, overrides?: RequestOverrides): Promise<SendEmailResponse>;
+    bulkSend(params: TemplateBulkSendParams, overrides?: RequestOverrides): Promise<TemplateBulkSendResponse>;
+    stats(overrides?: RequestOverrides): Promise<TemplateStatsResponse>;
+}
+
+declare class SuppressionsResource {
+    private http;
+    constructor(http: HttpClient);
+    list(params?: ListSuppressionsParams, overrides?: RequestOverrides): Promise<ListSuppressionsResponse>;
+    listAll(params?: Omit<ListSuppressionsParams, 'page'>, overrides?: RequestOverrides): AsyncGenerator<Suppression>;
+    add(params: AddSuppressionParams, overrides?: RequestOverrides): Promise<SuppressionResponse>;
+    remove(email: string, overrides?: RequestOverrides): Promise<{
+        message: string;
+    }>;
+}
+
+declare class WebhooksResource {
+    private http;
+    constructor(http: HttpClient);
+    create(params: CreateWebhookParams, overrides?: RequestOverrides): Promise<CreateWebhookResponse>;
+    list(overrides?: RequestOverrides): Promise<ListWebhooksResponse>;
+    update(id: string, params: UpdateWebhookParams, overrides?: RequestOverrides): Promise<UpdateWebhookResponse>;
+    delete(id: string, overrides?: RequestOverrides): Promise<{
+        message: string;
+        id: string;
+    }>;
+}
+
+declare class DashboardResource {
+    private http;
+    constructor(http: HttpClient);
+    get(overrides?: RequestOverrides): Promise<DashboardResponse>;
+    quota(overrides?: RequestOverrides): Promise<QuotaResponse>;
+}
+
+declare class Outbound {
+    readonly email: EmailResource;
+    readonly templates: TemplatesResource;
+    readonly suppressions: SuppressionsResource;
+    readonly webhooks: WebhooksResource;
+    readonly dashboard: DashboardResource;
+    constructor(config?: OutboundConfig);
+    /**
+     * Verify a webhook signature using HMAC-SHA256.
+     * Use this in your webhook handler to validate incoming requests.
+     */
+    static verifyWebhookSignature(payload: string | Buffer, signature: string, secret: string): boolean;
+}
+
+declare class OutboundError extends Error {
+    readonly statusCode: number;
+    readonly details?: unknown | undefined;
+    readonly requestId?: string | undefined;
+    constructor(message: string, statusCode: number, details?: unknown | undefined, requestId?: string | undefined);
+}
+declare class BadRequestError extends OutboundError {
+    constructor(message: string, details?: unknown, requestId?: string);
+}
+declare class AuthenticationError extends OutboundError {
+    constructor(message: string, details?: unknown, requestId?: string);
+}
+declare class ForbiddenError extends OutboundError {
+    constructor(message: string, details?: unknown, requestId?: string);
+}
+declare class NotFoundError extends OutboundError {
+    constructor(message: string, details?: unknown, requestId?: string);
+}
+declare class ConflictError extends OutboundError {
+    constructor(message: string, details?: unknown, requestId?: string);
+}
+declare class RateLimitError extends OutboundError {
+    readonly retryAfter?: number;
+    constructor(message: string, retryAfter?: number, details?: unknown, requestId?: string);
+}
+declare class ServerError extends OutboundError {
+    constructor(message: string, statusCode?: number, details?: unknown, requestId?: string);
+}
+declare class TimeoutError extends OutboundError {
+    constructor(message?: string);
+}
+declare class NetworkError extends OutboundError {
+    constructor(message?: string);
+}
+
+export { type AddSuppressionParams, type Attachment, AuthenticationError, BadRequestError, type BulkEmailParams, type BulkEmailRecipient, type BulkEmailResponse, type CancelEmailParams, type CancelEmailResponse, ConflictError, type CreateTemplateParams, type CreateWebhookParams, type CreateWebhookResponse, type DashboardResponse, type EmailJob, type EmailRecipientStatus, type EmailStatus, ForbiddenError, type JobStatusResponse, type ListSuppressionsParams, type ListSuppressionsResponse, type ListTemplatesParams, type ListTemplatesResponse, type ListWebhooksResponse, NetworkError, NotFoundError, Outbound, type OutboundConfig, OutboundError, type QuotaResponse, RateLimitError, type RequestOverrides, type ResolvedConfig, type SendEmailParams, type SendEmailResponse, ServerError, type Suppression, type SuppressionResponse, type Template, type TemplateBulkRecipient, type TemplateBulkSendParams, type TemplateBulkSendResponse, type TemplatePreviewParams, type TemplatePreviewResponse, type TemplateResponse, type TemplateSendParams, type TemplateStatsResponse, TimeoutError, type UpdateTemplateParams, type UpdateWebhookParams, type UpdateWebhookResponse, type Webhook, type WebhookEvent };