@sendcraft/sdk 1.0.0

package/lib/resources/emails.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Emails = void 0;
+/**
+ * Render a React Email component to an HTML string.
+ * Throws if `@react-email/render` is not installed.
+ */
+async function renderReact(element) {
+    let render;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const mod = require('@react-email/render');
+        render = mod.render ?? mod.default?.render;
+        if (typeof render !== 'function') {
+            throw new Error('@react-email/render does not export a `render` function — check the installed version');
+        }
+    }
+    catch (err) {
+        // Re-throw a helpful install message, but chain the root cause so
+        // callers can inspect it (e.g. module-not-found vs wrong-version).
+        const cause = err instanceof Error ? err.message : String(err);
+        throw new Error('[sendcraft-sdk] The `react` option requires @react-email/render.\n' +
+            'Install it: npm install @react-email/render react react-dom\n' +
+            `Root cause: ${cause}`);
+    }
+    return render(element);
+}
+class Emails {
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Send a single transactional email.
+     * @example — plain HTML
+     * await client.emails.send({ to: 'user@example.com', subject: 'Hi', html: '<p>Hello</p>' })
+     *
+     * @example — React Email component (requires @react-email/render)
+     * await client.emails.send({ to: 'user@example.com', subject: 'Hi', react: <WelcomeEmail /> })
+     */
+    async send(options) {
+        const html = options.react ? await renderReact(options.react) : options.html;
+        if (!html)
+            throw new Error('[sendcraft-sdk] Provide either `html` or `react` in send()');
+        return this.http.post('/emails/send', {
+            toEmail: options.to,
+            toName: options.toName,
+            subject: options.subject,
+            htmlContent: html,
+            plainTextContent: options.text,
+            fromEmail: options.from,
+            fromName: options.fromName,
+            replyTo: options.replyTo,
+            cc: options.cc,
+            bcc: options.bcc,
+        }, options.idempotencyKey ? { 'X-Idempotency-Key': options.idempotencyKey } : undefined);
+    }
+    /**
+     * Render a React Email component (or return a plain HTML string) without sending.
+     * Useful for previewing templates locally or in tests.
+     * @example
+     * const html = await client.emails.render({ react: <WelcomeEmail name="Alice" /> });
+     * console.log(html); // full HTML string
+     */
+    async render(options) {
+        if (options.react)
+            return renderReact(options.react);
+        if (options.html)
+            return options.html;
+        throw new Error('[sendcraft-sdk] Provide either `html` or `react` in render()');
+    }
+    /**
+     * Send the same email to multiple recipients.
+     * @example
+     * await client.emails.sendBulk({ emails: ['a@b.com', 'c@d.com'], subject: 'News', html: '...' })
+     */
+    async sendBulk(options) {
+        const html = options.react ? await renderReact(options.react) : options.html;
+        if (!html)
+            throw new Error('[sendcraft-sdk] Provide either `html` or `react` in sendBulk()');
+        return this.http.post('/emails/send-bulk', {
+            emails: options.emails,
+            subject: options.subject,
+            htmlContent: html,
+            plainTextContent: options.text,
+            fromEmail: options.from,
+            fromName: options.fromName,
+        });
+    }
+    /**
+     * Schedule an email for future delivery.
+     * @example
+     * await client.emails.schedule({ to: '...', subject: '...', html: '...', scheduledAt: '2026-04-01T09:00:00Z' })
+     */
+    async schedule(options) {
+        const html = options.react ? await renderReact(options.react) : options.html;
+        if (!html)
+            throw new Error('[sendcraft-sdk] Provide either `html` or `react` in schedule()');
+        return this.http.post('/emails/schedule', {
+            toEmail: options.to,
+            subject: options.subject,
+            htmlContent: html,
+            fromEmail: options.from,
+            scheduledTime: options.scheduledAt instanceof Date
+                ? options.scheduledAt.toISOString()
+                : options.scheduledAt,
+        });
+    }
+    /**
+     * Send up to 100 distinct emails in a single API call.
+     * Each item can have a different to, subject, and html.
+     * @example
+     * await client.emails.batch([
+     *   { to: 'a@example.com', subject: 'Hello A', html: '<p>Hi A</p>' },
+     *   { to: 'b@example.com', subject: 'Hello B', html: '<p>Hi B</p>' },
+     * ])
+     */
+    async batch(emails, idempotencyKey) {
+        const rendered = await Promise.all(emails.map(async (e) => {
+            const html = e.react ? await renderReact(e.react) : e.html;
+            if (!html)
+                throw new Error('[sendcraft-sdk] Each email in batch() must have `html` or `react`');
+            return {
+                toEmail: e.to,
+                toName: e.toName,
+                subject: e.subject,
+                htmlContent: html,
+                plainTextContent: e.text,
+                fromEmail: e.from,
+                fromName: e.fromName,
+                replyTo: e.replyTo,
+            };
+        }));
+        return this.http.post('/emails/batch', { emails: rendered }, idempotencyKey ? { 'X-Idempotency-Key': idempotencyKey } : undefined);
+    }
+    /** Get a single email by ID. */
+    get(id) {
+        return this.http.get(`/emails/${id}`);
+    }
+    /** Update the scheduled delivery time of a scheduled email. */
+    updateSchedule(id, scheduledAt) {
+        return this.http.patch(`/emails/${id}/schedule`, {
+            scheduledTime: scheduledAt instanceof Date ? scheduledAt.toISOString() : scheduledAt,
+        });
+    }
+    /** Cancel a scheduled email before it is sent. */
+    cancelSchedule(id) {
+        return this.http.delete(`/emails/${id}/schedule`);
+    }
+    /** List sent emails with optional filters. */
+    list(options = {}) {
+        return this.http.get('/emails', options);
+    }
+    /** Get account-level email stats (open rate, click rate, etc.). */
+    stats() {
+        return this.http.get('/emails/stats/summary');
+    }
+}
+exports.Emails = Emails;

package/lib/resources/segments.d.ts

@@ -0,0 +1,55 @@
+import { HttpClient } from '../client';
+export interface SegmentRule {
+    field: string;
+    operator: string;
+    value: unknown;
+}
+export interface Segment {
+    _id: string;
+    name: string;
+    description?: string;
+    rules: SegmentRule[];
+    matchType: 'all' | 'any';
+    subscriberCount?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateSegmentParams {
+    name: string;
+    description?: string;
+    rules: SegmentRule[];
+    matchType?: 'all' | 'any';
+}
+export declare class Segments {
+    private http;
+    constructor(http: HttpClient);
+    /** List all segments */
+    list(): Promise<{
+        success: boolean;
+        segments: Segment[];
+    }>;
+    /** Get a segment by ID */
+    get(id: string): Promise<{
+        success: boolean;
+        segment: Segment;
+    }>;
+    /** Create a new segment */
+    create(params: CreateSegmentParams): Promise<{
+        success: boolean;
+        segment: Segment;
+    }>;
+    /** Update a segment */
+    update(id: string, params: Partial<CreateSegmentParams>): Promise<{
+        success: boolean;
+        segment: Segment;
+    }>;
+    /** Delete a segment */
+    delete(id: string): Promise<{
+        success: boolean;
+    }>;
+    /** Preview subscriber count matching a segment's rules */
+    preview(id: string): Promise<{
+        success: boolean;
+        count: number;
+    }>;
+}

package/lib/resources/segments.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Segments = void 0;
+class Segments {
+    constructor(http) {
+        this.http = http;
+    }
+    /** List all segments */
+    list() {
+        return this.http.get('/segments');
+    }
+    /** Get a segment by ID */
+    get(id) {
+        return this.http.get(`/segments/${id}`);
+    }
+    /** Create a new segment */
+    create(params) {
+        return this.http.post('/segments', params);
+    }
+    /** Update a segment */
+    update(id, params) {
+        return this.http.put(`/segments/${id}`, params);
+    }
+    /** Delete a segment */
+    delete(id) {
+        return this.http.delete(`/segments/${id}`);
+    }
+    /** Preview subscriber count matching a segment's rules */
+    preview(id) {
+        return this.http.get(`/segments/${id}/preview`);
+    }
+}
+exports.Segments = Segments;

package/lib/resources/smtp.d.ts

@@ -0,0 +1,44 @@
+import { HttpClient } from '../client';
+export interface SmtpCredentials {
+    host: string;
+    port: number;
+    encryption: string;
+    username: string;
+    passwordHint: string;
+    instructions: {
+        note: string;
+        apiKeyLocation: string;
+    };
+}
+export interface SmtpWarmupStatus {
+    warmupDay: number;
+    dailyLimit: number | null;
+    todayCount: number;
+    remainingToday: number | null;
+    isWarmedUp: boolean;
+    percentComplete: number;
+    warmupStartDate: string;
+    totalSent: number;
+}
+export declare class Smtp {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Get SMTP relay credentials for your account.
+     * Use the returned host/port/username + your API key as the SMTP password
+     * in any nodemailer, smtplib, or PHPMailer integration.
+     */
+    credentials(): Promise<{
+        success: boolean;
+        smtp: SmtpCredentials;
+        examples: Record<string, string>;
+    }>;
+    /**
+     * Get current IP warmup status for the self-hosted SMTP server.
+     * Shows daily limit, emails sent today, and warmup progress.
+     */
+    warmupStatus(): Promise<{
+        success: boolean;
+        warmup: SmtpWarmupStatus;
+    }>;
+}

package/lib/resources/smtp.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Smtp = void 0;
+class Smtp {
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Get SMTP relay credentials for your account.
+     * Use the returned host/port/username + your API key as the SMTP password
+     * in any nodemailer, smtplib, or PHPMailer integration.
+     */
+    credentials() {
+        return this.http.get('/smtp/credentials');
+    }
+    /**
+     * Get current IP warmup status for the self-hosted SMTP server.
+     * Shows daily limit, emails sent today, and warmup progress.
+     */
+    warmupStatus() {
+        return this.http.get('/smtp/warmup');
+    }
+}
+exports.Smtp = Smtp;

package/lib/resources/subscribers.d.ts

@@ -0,0 +1,61 @@
+import { HttpClient } from '../client';
+export interface AddSubscriberOptions {
+    email: string;
+    listId: string;
+    firstName?: string;
+    lastName?: string;
+    customFields?: Record<string, unknown>;
+}
+export interface ImportSubscribersOptions {
+    listId: string;
+    subscribers: Array<{
+        email: string;
+        firstName?: string;
+        lastName?: string;
+        phone?: string;
+        customFields?: Record<string, unknown>;
+    }>;
+}
+export interface ListSubscribersOptions {
+    page?: number;
+    limit?: number;
+    status?: 'active' | 'unsubscribed' | 'bounced';
+}
+export interface UpdateSubscriberOptions {
+    firstName?: string;
+    lastName?: string;
+    customFields?: Record<string, unknown>;
+    emailPreferences?: Record<string, unknown>;
+}
+export declare class Subscribers {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Add a single subscriber to a list.
+     * @example
+     * await client.subscribers.add({ email: 'user@example.com', listId: 'list_id' })
+     */
+    add(options: AddSubscriberOptions): Promise<unknown>;
+    /**
+     * Bulk import up to 10,000 subscribers into a list.
+     * @example
+     * await client.subscribers.import({ listId: '...', subscribers: [{ email: 'a@b.com' }, { email: 'c@d.com' }] })
+     */
+    import(options: ImportSubscribersOptions): Promise<unknown>;
+    /** List all subscribers across all your lists. */
+    list(options?: ListSubscribersOptions): Promise<unknown>;
+    /** Get subscribers for a specific list. */
+    listByList(listId: string, options?: {
+        status?: string;
+        limit?: number;
+        skip?: number;
+    }): Promise<unknown>;
+    /** Update subscriber details. */
+    update(subscriberId: string, options: UpdateSubscriberOptions): Promise<unknown>;
+    /** Soft-delete (archive) a subscriber. */
+    delete(subscriberId: string): Promise<unknown>;
+    /** Get a subscriber's email preferences. */
+    preferences(subscriberId: string): Promise<unknown>;
+    /** Update a subscriber's email preferences. */
+    updatePreferences(subscriberId: string, emailPreferences: Record<string, unknown>): Promise<unknown>;
+}

package/lib/resources/subscribers.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Subscribers = void 0;
+class Subscribers {
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Add a single subscriber to a list.
+     * @example
+     * await client.subscribers.add({ email: 'user@example.com', listId: 'list_id' })
+     */
+    add(options) {
+        return this.http.post('/subscribers/add', {
+            email: options.email,
+            listId: options.listId,
+            firstName: options.firstName,
+            lastName: options.lastName,
+            customFields: options.customFields,
+        });
+    }
+    /**
+     * Bulk import up to 10,000 subscribers into a list.
+     * @example
+     * await client.subscribers.import({ listId: '...', subscribers: [{ email: 'a@b.com' }, { email: 'c@d.com' }] })
+     */
+    import(options) {
+        return this.http.post('/subscribers/import', {
+            listId: options.listId,
+            subscribers: options.subscribers,
+        });
+    }
+    /** List all subscribers across all your lists. */
+    list(options = {}) {
+        return this.http.get('/subscribers', options);
+    }
+    /** Get subscribers for a specific list. */
+    listByList(listId, options = {}) {
+        return this.http.get(`/subscribers/list/${listId}`, options);
+    }
+    /** Update subscriber details. */
+    update(subscriberId, options) {
+        return this.http.put(`/subscribers/${subscriberId}`, options);
+    }
+    /** Soft-delete (archive) a subscriber. */
+    delete(subscriberId) {
+        return this.http.delete(`/subscribers/${subscriberId}`);
+    }
+    /** Get a subscriber's email preferences. */
+    preferences(subscriberId) {
+        return this.http.get(`/subscribers/preferences/${subscriberId}`);
+    }
+    /** Update a subscriber's email preferences. */
+    updatePreferences(subscriberId, emailPreferences) {
+        return this.http.put(`/subscribers/${subscriberId}/preferences`, { emailPreferences });
+    }
+}
+exports.Subscribers = Subscribers;

package/lib/resources/templates.d.ts

@@ -0,0 +1,34 @@
+import { HttpClient } from '../client';
+export interface CreateTemplateOptions {
+    name: string;
+    subject: string;
+    html: string;
+    category?: string;
+    variables?: string[];
+}
+export interface UpdateTemplateOptions {
+    name?: string;
+    subject?: string;
+    html?: string;
+    text?: string;
+    previewText?: string;
+    category?: string;
+}
+export declare class Templates {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Create a reusable email template.
+     * @example
+     * await client.templates.create({ name: 'Welcome', subject: 'Welcome to {{appName}}', html: '<p>Hi {{firstName}}</p>' })
+     */
+    create(options: CreateTemplateOptions): Promise<unknown>;
+    /** List all templates. */
+    list(): Promise<unknown>;
+    /** Get a template by ID. */
+    get(templateId: string): Promise<unknown>;
+    /** Update a template. */
+    update(templateId: string, options: UpdateTemplateOptions): Promise<unknown>;
+    /** Delete a template. */
+    delete(templateId: string): Promise<unknown>;
+}

package/lib/resources/templates.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Templates = void 0;
+class Templates {
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Create a reusable email template.
+     * @example
+     * await client.templates.create({ name: 'Welcome', subject: 'Welcome to {{appName}}', html: '<p>Hi {{firstName}}</p>' })
+     */
+    create(options) {
+        return this.http.post('/templates', {
+            name: options.name,
+            subject: options.subject,
+            htmlContent: options.html,
+            category: options.category,
+            variables: options.variables,
+        });
+    }
+    /** List all templates. */
+    list() {
+        return this.http.get('/templates');
+    }
+    /** Get a template by ID. */
+    get(templateId) {
+        return this.http.get(`/templates/${templateId}`);
+    }
+    /** Update a template. */
+    update(templateId, options) {
+        return this.http.put(`/templates/${templateId}`, {
+            name: options.name,
+            subject: options.subject,
+            htmlContent: options.html,
+            plainTextContent: options.text,
+            previewText: options.previewText,
+            category: options.category,
+        });
+    }
+    /** Delete a template. */
+    delete(templateId) {
+        return this.http.delete(`/templates/${templateId}`);
+    }
+}
+exports.Templates = Templates;

package/lib/resources/webhooks.d.ts

@@ -0,0 +1,58 @@
+import { HttpClient } from '../client';
+export interface CreateWebhookOptions {
+    url: string;
+    events: string[];
+    name?: string;
+}
+export interface WebhookEvent {
+    type: string;
+    messageId: string;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export declare class Webhooks {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Register a webhook endpoint.
+     * @example
+     * await client.webhooks.create({ url: 'https://myapp.com/hooks/email', events: ['email.bounced', 'email.opened'] })
+     */
+    create(options: CreateWebhookOptions): Promise<unknown>;
+    /** List all registered webhooks. */
+    list(): Promise<unknown>;
+    /** Delete a webhook by ID. */
+    delete(webhookId: string): Promise<unknown>;
+    /**
+     * Verify the HMAC-SHA256 signature of an incoming webhook request.
+     * Use this in your webhook handler to confirm the request came from SendCraft.
+     *
+     * @param payload   - Raw request body string (before JSON.parse)
+     * @param signature - Value of the `x-sendcraft-signature` header
+     * @param secret    - Your webhook signing secret from the SendCraft dashboard
+     * @returns `true` if the signature is valid
+     *
+     * @example — Express
+     * app.post('/hooks/sendcraft', express.raw({ type: 'application/json' }), (req, res) => {
+     *   const valid = client.webhooks.verify(
+     *     req.body.toString(),
+     *     req.headers['x-sendcraft-signature'] as string,
+     *     process.env.SENDCRAFT_WEBHOOK_SECRET!,
+     *   );
+     *   if (!valid) return res.sendStatus(401);
+     *   const event = JSON.parse(req.body.toString()) as WebhookEvent;
+     *   // handle event...
+     *   res.sendStatus(200);
+     * });
+     */
+    verify(payload: string, signature: string, secret: string): boolean;
+    /**
+     * Parse and type a raw webhook payload string.
+     * Throws a descriptive error on malformed JSON rather than an opaque
+     * SyntaxError from the runtime.
+     * @example
+     * const event = client.webhooks.parse(req.body.toString());
+     * if (event.type === 'email.bounced') { ... }
+     */
+    parse(payload: string): WebhookEvent;
+}

package/lib/resources/webhooks.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Webhooks = void 0;
+const crypto_1 = require("crypto");
+class Webhooks {
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Register a webhook endpoint.
+     * @example
+     * await client.webhooks.create({ url: 'https://myapp.com/hooks/email', events: ['email.bounced', 'email.opened'] })
+     */
+    create(options) {
+        return this.http.post('/webhooks', options);
+    }
+    /** List all registered webhooks. */
+    list() {
+        return this.http.get('/webhooks');
+    }
+    /** Delete a webhook by ID. */
+    delete(webhookId) {
+        return this.http.delete(`/webhooks/${webhookId}`);
+    }
+    /**
+     * Verify the HMAC-SHA256 signature of an incoming webhook request.
+     * Use this in your webhook handler to confirm the request came from SendCraft.
+     *
+     * @param payload   - Raw request body string (before JSON.parse)
+     * @param signature - Value of the `x-sendcraft-signature` header
+     * @param secret    - Your webhook signing secret from the SendCraft dashboard
+     * @returns `true` if the signature is valid
+     *
+     * @example — Express
+     * app.post('/hooks/sendcraft', express.raw({ type: 'application/json' }), (req, res) => {
+     *   const valid = client.webhooks.verify(
+     *     req.body.toString(),
+     *     req.headers['x-sendcraft-signature'] as string,
+     *     process.env.SENDCRAFT_WEBHOOK_SECRET!,
+     *   );
+     *   if (!valid) return res.sendStatus(401);
+     *   const event = JSON.parse(req.body.toString()) as WebhookEvent;
+     *   // handle event...
+     *   res.sendStatus(200);
+     * });
+     */
+    verify(payload, signature, secret) {
+        if (!payload || !signature || !secret)
+            return false;
+        const expected = (0, crypto_1.createHmac)('sha256', secret).update(payload).digest('hex');
+        // Use Node's built-in constant-time comparison — avoids manual loop and
+        // the early-exit length check that leaks whether the provided signature
+        // is the right length (expected is always 64 hex chars).
+        try {
+            return (0, crypto_1.timingSafeEqual)(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'));
+        }
+        catch {
+            // Buffer.from() throws if signature is not valid hex; treat as invalid.
+            return false;
+        }
+    }
+    /**
+     * Parse and type a raw webhook payload string.
+     * Throws a descriptive error on malformed JSON rather than an opaque
+     * SyntaxError from the runtime.
+     * @example
+     * const event = client.webhooks.parse(req.body.toString());
+     * if (event.type === 'email.bounced') { ... }
+     */
+    parse(payload) {
+        if (typeof payload !== 'string' || payload.length === 0) {
+            throw new Error('[sendcraft-sdk] webhooks.parse() received an empty payload');
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(payload);
+        }
+        catch {
+            throw new Error('[sendcraft-sdk] webhooks.parse() received invalid JSON');
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('[sendcraft-sdk] webhooks.parse() expected a JSON object');
+        }
+        // Guard against prototype pollution: __proto__ / constructor overrides
+        const obj = parsed;
+        if (Object.prototype.hasOwnProperty.call(obj, '__proto__') ||
+            Object.prototype.hasOwnProperty.call(obj, 'constructor') ||
+            Object.prototype.hasOwnProperty.call(obj, 'prototype')) {
+            throw new Error('[sendcraft-sdk] webhooks.parse() rejected payload with forbidden keys');
+        }
+        return obj;
+    }
+}
+exports.Webhooks = Webhooks;