@masters-union/outbound-sdk 0.1.0

package/README.md

@@ -0,0 +1,175 @@
+# outbound-sdk
+
+Official Node.js SDK for the [Outbound](https://github.com/AdarshChakrworty/outbound) email platform.
+
+## Install
+
+```bash
+npm install outbound-sdk
+```
+
+## Quick Start
+
+```ts
+import { OutboundClient } from 'outbound-sdk';
+
+const outbound = new OutboundClient({
+  apiKey: 'mu_outbound_...',       // or set OUTBOUND_API_KEY env var
+  baseUrl: 'https://api.your-domain.com', // or set OUTBOUND_API_URL env var
+});
+```
+
+### Send an Email
+
+```ts
+const { jobId, messageId } = await outbound.email.send({
+  toEmail: 'user@example.com',
+  fromEmail: 'noreply@company.com',
+  emailSubject: 'Welcome!',
+  htmlBody: '<h1>Hello World</h1>',
+});
+```
+
+### Send Bulk Emails
+
+```ts
+const result = await outbound.email.bulk({
+  fromEmail: 'noreply@company.com',
+  emailSubject: 'Newsletter',
+  emails: [
+    { toEmail: 'alice@example.com', htmlBody: '<h1>Hi Alice</h1>' },
+    { toEmail: 'bob@example.com', htmlBody: '<h1>Hi Bob</h1>' },
+  ],
+});
+// result.recipientCount, result.jobId
+```
+
+### Check Job Status
+
+```ts
+const status = await outbound.email.status('job-uuid');
+// status.job, status.recipients
+```
+
+### Templates
+
+```ts
+// Create
+const { template } = await outbound.templates.create({
+  name: 'welcome',
+  subject: 'Welcome {{firstName}}!',
+  htmlBody: '<h1>Hello {{firstName}}</h1>',
+  variables: ['firstName'],
+});
+
+// List
+const { templates, total } = await outbound.templates.list({ status: 'active' });
+
+// Send using template
+const { jobId } = await outbound.templates.send({
+  templateId: template.id,
+  toEmail: 'user@example.com',
+  fromEmail: 'noreply@company.com',
+  variables: { firstName: 'John' },
+});
+
+// Bulk send using template
+const bulk = await outbound.templates.bulkSend({
+  templateId: template.id,
+  fromEmail: 'noreply@company.com',
+  recipients: [
+    { toEmail: 'alice@example.com', variables: { firstName: 'Alice' } },
+    { toEmail: 'bob@example.com', variables: { firstName: 'Bob' } },
+  ],
+});
+
+// Preview
+const preview = await outbound.templates.preview(template.id, {
+  variables: { firstName: 'John' },
+});
+```
+
+### Suppressions
+
+```ts
+// Add
+await outbound.suppressions.add({ email: 'bad@example.com', reason: 'manual' });
+
+// List
+const { suppressions } = await outbound.suppressions.list({ reason: 'bounce' });
+
+// Remove
+await outbound.suppressions.remove('bad@example.com');
+```
+
+### Webhooks
+
+```ts
+// Create
+const { webhook, secret } = await outbound.webhooks.create({
+  url: 'https://myapp.com/webhooks/outbound',
+  events: ['delivery', 'bounce', 'complaint'],
+});
+// Store `secret` securely for signature verification
+
+// Verify incoming webhook
+const isValid = OutboundClient.verifyWebhookSignature(rawBody, signatureHeader, secret);
+```
+
+### Dashboard
+
+```ts
+const dashboard = await outbound.dashboard.get();
+// dashboard.last30Days.sent, dashboard.quota, etc.
+
+const quota = await outbound.dashboard.quota();
+// quota.dailyUsed, quota.monthlyUsed, quota.remaining
+```
+
+## Configuration
+
+| Option | Env Variable | Default | Description |
+|--------|-------------|---------|-------------|
+| `apiKey` | `OUTBOUND_API_KEY` | - | Your tenant API key (required) |
+| `baseUrl` | `OUTBOUND_API_URL` | `http://localhost:3000` | API base URL |
+| `timeout` | - | `30000` | Request timeout in ms |
+| `maxRetries` | - | `3` | Max retries on 429/5xx |
+| `retryDelay` | - | `1000` | Initial retry delay in ms (exponential backoff) |
+
+## Error Handling
+
+All errors extend `OutboundError` with `statusCode`, `message`, and `details`:
+
+```ts
+import { OutboundClient, RateLimitError, NotFoundError } from 'outbound-sdk';
+
+try {
+  await outbound.email.send({ ... });
+} catch (err) {
+  if (err instanceof RateLimitError) {
+    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
+  } else if (err instanceof NotFoundError) {
+    console.log('Resource not found');
+  }
+}
+```
+
+| Error Class | Status Code |
+|------------|-------------|
+| `BadRequestError` | 400 |
+| `AuthenticationError` | 401 |
+| `ForbiddenError` | 403 |
+| `NotFoundError` | 404 |
+| `ConflictError` | 409 |
+| `RateLimitError` | 429 |
+| `ServerError` | 5xx |
+| `TimeoutError` | - |
+| `NetworkError` | - |
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,420 @@
+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 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;
+    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;
+}
+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;
+    suppressedEmails: string[];
+    duplicatesRemoved: number;
+}
+interface JobStatusResponse {
+    job: Record<string, unknown>;
+    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';
+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;
+    metadata?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    tracking?: Record<string, unknown>;
+}
+interface TemplateBulkSendParams {
+    templateId: string;
+    fromEmail: string;
+    senderName?: string;
+    replyTo?: string;
+    idempotencyKey?: 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;
+    suppressedEmails: string[];
+    duplicatesRemoved: number;
+    usingSesTemplate: 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>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+    private request;
+    private buildUrl;
+    private parseError;
+    private sleep;
+}
+
+declare class EmailResource {
+    private http;
+    constructor(http: HttpClient);
+    send(params: SendEmailParams): Promise<SendEmailResponse>;
+    bulk(params: BulkEmailParams): Promise<BulkEmailResponse>;
+    status(jobId: string): Promise<JobStatusResponse>;
+}
+
+declare class TemplatesResource {
+    private http;
+    constructor(http: HttpClient);
+    create(params: CreateTemplateParams): Promise<TemplateResponse>;
+    list(params?: ListTemplatesParams): Promise<ListTemplatesResponse>;
+    listAll(params?: Omit<ListTemplatesParams, 'page'>): AsyncGenerator<Template>;
+    get(id: string): Promise<TemplateResponse>;
+    update(id: string, params: UpdateTemplateParams): Promise<TemplateResponse>;
+    delete(id: string): Promise<{
+        message: string;
+        id: string;
+    }>;
+    duplicate(id: string, params?: {
+        name?: string;
+    }): Promise<TemplateResponse>;
+    preview(id: string, params?: TemplatePreviewParams): Promise<TemplatePreviewResponse>;
+    send(params: TemplateSendParams): Promise<SendEmailResponse>;
+    bulkSend(params: TemplateBulkSendParams): Promise<TemplateBulkSendResponse>;
+    stats(): Promise<TemplateStatsResponse>;
+}
+
+declare class SuppressionsResource {
+    private http;
+    constructor(http: HttpClient);
+    list(params?: ListSuppressionsParams): Promise<ListSuppressionsResponse>;
+    listAll(params?: Omit<ListSuppressionsParams, 'page'>): AsyncGenerator<Suppression>;
+    add(params: AddSuppressionParams): Promise<SuppressionResponse>;
+    remove(email: string): Promise<{
+        message: string;
+    }>;
+}
+
+declare class WebhooksResource {
+    private http;
+    constructor(http: HttpClient);
+    create(params: CreateWebhookParams): Promise<CreateWebhookResponse>;
+    list(): Promise<ListWebhooksResponse>;
+    update(id: string, params: UpdateWebhookParams): Promise<UpdateWebhookResponse>;
+    delete(id: string): Promise<{
+        message: string;
+        id: string;
+    }>;
+}
+
+declare class DashboardResource {
+    private http;
+    constructor(http: HttpClient);
+    get(): Promise<DashboardResponse>;
+    quota(): 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;
+    private getEnv;
+}
+
+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, ConflictError, type CreateTemplateParams, type CreateWebhookParams, type CreateWebhookResponse, type DashboardResponse, 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 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 };