@masters-union/outbound-sdk 0.0.10

package/README.md

@@ -0,0 +1,180 @@
+# outbound-sdk
+
+Official Node.js SDK for the [Outbound](https://github.com/AdarshChakrworty/outbound) email platform.
+
+
+## Installation
+
+::: code-group
+```bash [npm]
+npm install @masters-union/outbound-sdk
+```
+```bash [yarn]
+yarn add @masters-union/outbound-sdk
+```
+```bash [pnpm]
+pnpm add @masters-union/outbound-sdk
+```
+:::
+
+**Requirements:** Node.js 18+ (uses native `fetch`)
+
+## Quick Setup
+
+### 1. Get your API key
+
+Your Outbound admin will provide you with an API key. It looks like:
+
+```
+mu_outbound_a1b2c3d4e5f6...
+```
+
+### 2. Initialize the client
+
+::: code-group
+```ts [ESM]
+import { Outbound } from '@masters-union/outbound-sdk';
+
+const outbound = new Outbound({ apiKey: 'mu_outbound_...' });
+```
+```js [CommonJS]
+const { Outbound } = require('@masters-union/outbound-sdk');
+
+const outbound = new Outbound({ apiKey: 'mu_outbound_...' });
+```
+:::
+
+Once you set the API key in the constructor, every method uses it automatically. No need to pass it on every call.
+
+### 3. Send your first email
+
+```ts
+const { jobId, messageId } = await outbound.email.send({
+  toEmail: 'user@example.com',
+  fromEmail: 'noreply@yourcompany.com', // must be a verified domain
+  emailSubject: 'Welcome!',
+  htmlBody: '<h1>Hello World</h1>',
+});
+
+console.log(`Email queued: ${jobId}`);
+```
+
+::: warning Verified Domains Only
+The `fromEmail` must use a domain that has been verified and assigned to your tenant account by the admin. Sending from an unverified domain will return a `403 Forbidden` error.
+:::
+
+### 4. Check delivery status
+
+```ts
+const status = await outbound.email.status(jobId);
+
+for (const recipient of status.recipients) {
+  console.log(`${recipient.recipient_email}: ${recipient.status}`);
+  // "sent" → "delivered" → "opened" → "clicked"
+}
+```
+
+### 5. Send with a template
+
+```ts
+// Create a reusable template
+const { template } = await outbound.templates.create({
+  name: 'welcome-email',
+  subject: 'Welcome {{firstName}}!',
+  htmlBody: '<h1>Hello {{firstName}}</h1><p>Welcome to {{company}}.</p>',
+  variables: ['firstName', 'company'],
+});
+
+// Send to one person
+await outbound.templates.send({
+  templateId: template.id,
+  toEmail: 'user@example.com',
+  fromEmail: 'noreply@yourcompany.com',
+  variables: { firstName: 'John', company: 'Acme' },
+});
+
+// Send to many people
+await outbound.templates.bulkSend({
+  templateId: template.id,
+  fromEmail: 'noreply@yourcompany.com',
+  recipients: [
+    { toEmail: 'alice@example.com', variables: { firstName: 'Alice', company: 'Acme' } },
+    { toEmail: 'bob@example.com', variables: { firstName: 'Bob', company: 'Acme' } },
+  ],
+});
+```
+
+### 6. Multi-tenant usage
+
+The SDK supports multi-tenant applications. You can override the API key on any individual call using the optional last argument:
+
+```ts
+const outbound = new Outbound(); // no default apiKey
+
+const tenantAKey = 'mu_outbound_tenant_a_...';
+const tenantBKey = 'mu_outbound_tenant_b_...';
+
+// Pass { apiKey } as the last argument to override per call
+await outbound.email.send({ /* ... */ }, { apiKey: tenantAKey });
+await outbound.email.send({ /* ... */ }, { apiKey: tenantBKey });
+```
+
+You can also set a default in the constructor and override only when needed:
+
+```ts
+const outbound = new Outbound({ apiKey: tenantAKey }); // default
+
+await outbound.email.send({ /* ... */ });                        // uses tenantAKey
+await outbound.email.send({ /* ... */ }, { apiKey: tenantBKey }); // uses tenantBKey
+```
+
+## Key Concepts
+
+### Email Lifecycle
+
+Every email goes through these statuses:
+
+```
+queued → processing → sent → delivered
+                         ↘ bounced
+                         ↘ complained
+                      delivered → opened → clicked
+```
+
+| Status | Meaning |
+|--------|---------|
+| `queued` | Email is in the queue, waiting to be processed |
+| `processing` | Email is being sent to AWS SES |
+| `sent` | SES accepted the email |
+| `delivered` | Email landed in recipient's inbox |
+| `bounced` | Email bounced (bad address or mailbox full) |
+| `complained` | Recipient marked it as spam |
+| `opened` | Recipient opened the email (requires tracking) |
+| `clicked` | Recipient clicked a link (requires tracking) |
+| `failed` | Failed to send (SES rejection or error) |
+
+### Suppression List
+
+The platform automatically suppresses emails that bounce or receive complaints. You can also manually suppress emails. Any future send to a suppressed address is **silently filtered out** — it won't count against your quota.
+
+### Quotas
+
+Your tenant account has:
+- **Daily limit** — Max emails per day
+- **Monthly limit** — Max emails per month
+- **Rate limit** — Max emails per second
+- **Template limit** — Max number of templates
+
+Check your quota anytime with `outbound.dashboard.quota()`.
+
+## What's Next?
+
+- [Configuration](/guide/configuration) — Customize timeouts, retries, and more
+- [Error Handling](/guide/error-handling) — Handle every error type
+- [Email API](/api/email) — Single and bulk sending reference
+- [Templates API](/api/templates) — Full template lifecycle
+- [Webhooks API](/api/webhooks) — Real-time event notifications
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -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 };