@sendcraft/sdk 1.0.0

package/lib/index.js

@@ -0,0 +1,98 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SendCraft = void 0;
+const client_1 = require("./client");
+const emails_1 = require("./resources/emails");
+const campaigns_1 = require("./resources/campaigns");
+const templates_1 = require("./resources/templates");
+const subscribers_1 = require("./resources/subscribers");
+const analytics_1 = require("./resources/analytics");
+const domains_1 = require("./resources/domains");
+const webhooks_1 = require("./resources/webhooks");
+const segments_1 = require("./resources/segments");
+const automation_1 = require("./resources/automation");
+const smtp_1 = require("./resources/smtp");
+const apiKeys_1 = require("./resources/apiKeys");
+/**
+ * SendCraft SDK
+ *
+ * @example
+ * import { SendCraft } from 'sendcraft-sdk'
+ *
+ * const client = new SendCraft({ apiKey: 'sc_live_...' })
+ *
+ * // Send a transactional email
+ * await client.emails.send({ to: 'user@example.com', subject: 'Hello', html: '<p>Hi!</p>' })
+ *
+ * // Create and send a campaign
+ * const { campaign } = await client.campaigns.create({ name: 'Launch', subject: 'We are live!', from: 'hi@app.com', html: '...' })
+ * await client.campaigns.send(campaign._id)
+ *
+ * // Get SMTP relay credentials
+ * const { smtp } = await client.smtp.credentials()
+ *
+ * // Check IP warmup status
+ * const { warmup } = await client.smtp.warmupStatus()
+ *
+ * // List segments
+ * const { segments } = await client.segments.list()
+ *
+ * // Activate an automation
+ * await client.automation.activate('automation_id')
+ */
+class SendCraft {
+    constructor(config) {
+        if (!config.apiKey || typeof config.apiKey !== 'string') {
+            throw new Error('SendCraft: apiKey is required and must be a non-empty string');
+        }
+        if (config.apiKey.trim() !== config.apiKey) {
+            throw new Error('SendCraft: apiKey must not contain leading or trailing whitespace');
+        }
+        if (config.apiKey.length < 16) {
+            throw new Error('SendCraft: apiKey appears invalid — must be at least 16 characters');
+        }
+        const http = new client_1.HttpClient(config.apiKey, (config.baseUrl ?? 'https://api.sendcraft.online/api').replace(/\/$/, ''));
+        this.emails = new emails_1.Emails(http);
+        this.campaigns = new campaigns_1.Campaigns(http);
+        this.templates = new templates_1.Templates(http);
+        this.subscribers = new subscribers_1.Subscribers(http);
+        this.analytics = new analytics_1.Analytics(http);
+        this.domains = new domains_1.Domains(http);
+        this.webhooks = new webhooks_1.Webhooks(http);
+        this.segments = new segments_1.Segments(http);
+        this.automation = new automation_1.Automation(http);
+        this.smtp = new smtp_1.Smtp(http);
+        this.apiKeys = new apiKeys_1.ApiKeys(http);
+    }
+}
+exports.SendCraft = SendCraft;
+// Named + default export so both work:
+// import SendCraft from 'sendcraft-sdk'
+// import { SendCraft } from 'sendcraft-sdk'
+exports.default = SendCraft;
+// Re-export all types
+__exportStar(require("./resources/emails"), exports);
+__exportStar(require("./resources/campaigns"), exports);
+__exportStar(require("./resources/templates"), exports);
+__exportStar(require("./resources/subscribers"), exports);
+__exportStar(require("./resources/domains"), exports);
+__exportStar(require("./resources/webhooks"), exports);
+__exportStar(require("./resources/segments"), exports);
+__exportStar(require("./resources/automation"), exports);
+__exportStar(require("./resources/smtp"), exports);
+__exportStar(require("./resources/apiKeys"), exports);
+__exportStar(require("./error"), exports);

package/lib/resources/analytics.d.ts

@@ -0,0 +1,13 @@
+import { HttpClient } from '../client';
+export declare class Analytics {
+    private http;
+    constructor(http: HttpClient);
+    /** Overall account analytics (total sent, open rate, click rate). */
+    overview(): Promise<unknown>;
+    /** Daily send/open/click counts for the last N days. */
+    daily(days?: number): Promise<unknown>;
+    /** Detailed daily metrics including bounce and deliverability rates. */
+    metrics(days?: number): Promise<unknown>;
+    /** Analytics for a specific campaign. */
+    campaign(campaignId: string): Promise<unknown>;
+}

package/lib/resources/analytics.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Analytics = void 0;
+class Analytics {
+    constructor(http) {
+        this.http = http;
+    }
+    /** Overall account analytics (total sent, open rate, click rate). */
+    overview() {
+        return this.http.get('/analytics/overview');
+    }
+    /** Daily send/open/click counts for the last N days. */
+    daily(days = 30) {
+        return this.http.get('/analytics/daily', { days });
+    }
+    /** Detailed daily metrics including bounce and deliverability rates. */
+    metrics(days = 30) {
+        return this.http.get('/analytics/metrics', { days });
+    }
+    /** Analytics for a specific campaign. */
+    campaign(campaignId) {
+        return this.http.get(`/analytics/campaign/${campaignId}`);
+    }
+}
+exports.Analytics = Analytics;

package/lib/resources/apiKeys.d.ts

@@ -0,0 +1,61 @@
+import { HttpClient } from '../client';
+export type ApiKeyPermission = 'full_access' | 'sending_access';
+export interface ApiKey {
+    id: string;
+    name: string;
+    maskedKey: string;
+    prefix: string;
+    isActive: boolean;
+    permissions: ApiKeyPermission;
+    /** If set, the from address must use one of these domains */
+    allowedDomains: string[];
+    createdAt: string;
+    lastUsedAt?: string;
+    revokedAt?: string;
+    totalRequests: number;
+}
+export interface CreatedApiKey extends ApiKey {
+    /** Full key — shown ONCE on creation, never retrievable again. Store it securely. */
+    key: string;
+}
+export declare class ApiKeys {
+    private http;
+    constructor(http: HttpClient);
+    /** List all API keys for the authenticated account */
+    list(): Promise<{
+        success: boolean;
+        keys: ApiKey[];
+        total: number;
+        limit: number;
+        canCreateMore: boolean;
+    }>;
+    /**
+     * Create a new API key.
+     * The full key is returned **once** in the response — store it immediately.
+     */
+    create(name: string, options?: {
+        permissions?: ApiKeyPermission;
+        allowedDomains?: string[];
+    }): Promise<{
+        success: boolean;
+        message: string;
+        apiKey: CreatedApiKey;
+        warning: string;
+        activeKeysCount: number;
+        remainingSlots: number;
+    }>;
+    /** Rename an existing API key */
+    rename(keyId: string, name: string): Promise<{
+        success: boolean;
+        message: string;
+        key: Pick<ApiKey, 'id' | 'name' | 'maskedKey'>;
+    }>;
+    /** Revoke an API key — permanently disables it */
+    revoke(keyId: string, reason?: string): Promise<{
+        success: boolean;
+        message: string;
+        key: Pick<ApiKey, 'id' | 'name' | 'maskedKey' | 'revokedAt'> & {
+            revokedReason?: string;
+        };
+    }>;
+}

package/lib/resources/apiKeys.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiKeys = void 0;
+class ApiKeys {
+    constructor(http) {
+        this.http = http;
+    }
+    /** List all API keys for the authenticated account */
+    list() {
+        return this.http.get('/user/keys');
+    }
+    /**
+     * Create a new API key.
+     * The full key is returned **once** in the response — store it immediately.
+     */
+    create(name, options) {
+        // Explicitly pick only known fields instead of spreading `options` to
+        // prevent accidental prototype-pollution keys (__proto__, constructor, etc.)
+        // from being forwarded to the API.
+        return this.http.post('/user/keys', {
+            name,
+            ...(options?.permissions !== undefined ? { permissions: options.permissions } : {}),
+            ...(options?.allowedDomains !== undefined ? { allowedDomains: options.allowedDomains } : {}),
+        });
+    }
+    /** Rename an existing API key */
+    rename(keyId, name) {
+        return this.http.patch(`/user/keys/${keyId}`, { name });
+    }
+    /** Revoke an API key — permanently disables it */
+    revoke(keyId, reason) {
+        return this.http.delete(`/user/keys/${keyId}`, { reason });
+    }
+}
+exports.ApiKeys = ApiKeys;

package/lib/resources/automation.d.ts

@@ -0,0 +1,87 @@
+import { HttpClient } from '../client';
+export interface AutomationStep {
+    type: 'send_email' | 'wait' | 'add_tag' | 'remove_tag' | 'condition';
+    config: Record<string, unknown>;
+}
+export interface AutomationTrigger {
+    type: 'subscriber.added' | 'email.opened' | 'email.clicked' | 'tag.added' | 'manual';
+    filters?: Record<string, unknown>;
+}
+export interface Automation {
+    _id: string;
+    name: string;
+    status: 'draft' | 'active' | 'paused' | 'archived';
+    trigger: AutomationTrigger;
+    steps: AutomationStep[];
+    enrolledCount: number;
+    completedCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateAutomationParams {
+    name: string;
+    trigger: AutomationTrigger;
+    steps: AutomationStep[];
+}
+export interface AutomationEnrollment {
+    _id: string;
+    subscriberId: string;
+    automationId: string;
+    status: 'active' | 'completed' | 'cancelled' | 'failed';
+    currentStepId?: string;
+    nextActionAt?: string;
+    createdAt: string;
+}
+export declare class Automation {
+    private http;
+    constructor(http: HttpClient);
+    /** List all automations */
+    list(): Promise<{
+        success: boolean;
+        automations: Automation[];
+    }>;
+    /** Get an automation by ID */
+    get(id: string): Promise<{
+        success: boolean;
+        automation: Automation;
+    }>;
+    /** Create a new automation */
+    create(params: CreateAutomationParams): Promise<{
+        success: boolean;
+        automation: Automation;
+    }>;
+    /** Update an automation */
+    update(id: string, params: Partial<CreateAutomationParams>): Promise<{
+        success: boolean;
+        automation: Automation;
+    }>;
+    /** Delete an automation */
+    delete(id: string): Promise<{
+        success: boolean;
+    }>;
+    /** Activate an automation */
+    activate(id: string): Promise<{
+        success: boolean;
+        automation: Automation;
+    }>;
+    /** Pause an automation */
+    pause(id: string): Promise<{
+        success: boolean;
+        automation: Automation;
+    }>;
+    /** Get enrollments for an automation */
+    enrollments(id: string, params?: {
+        page?: number;
+        limit?: number;
+        status?: string;
+    }): Promise<{
+        success: boolean;
+        enrollments: AutomationEnrollment[];
+        total: number;
+    }>;
+    /** Manually enroll a subscriber into an automation */
+    enroll(id: string, subscriberId: string): Promise<{
+        success: boolean;
+        enrollment: AutomationEnrollment;
+    }>;
+}

package/lib/resources/automation.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Automation = void 0;
+class Automation {
+    constructor(http) {
+        this.http = http;
+    }
+    /** List all automations */
+    list() {
+        return this.http.get('/automation');
+    }
+    /** Get an automation by ID */
+    get(id) {
+        return this.http.get(`/automation/${id}`);
+    }
+    /** Create a new automation */
+    create(params) {
+        return this.http.post('/automation', params);
+    }
+    /** Update an automation */
+    update(id, params) {
+        return this.http.put(`/automation/${id}`, params);
+    }
+    /** Delete an automation */
+    delete(id) {
+        return this.http.delete(`/automation/${id}`);
+    }
+    /** Activate an automation */
+    activate(id) {
+        return this.http.post(`/automation/${id}/activate`);
+    }
+    /** Pause an automation */
+    pause(id) {
+        return this.http.post(`/automation/${id}/pause`);
+    }
+    /** Get enrollments for an automation */
+    enrollments(id, params) {
+        return this.http.get(`/automation/${id}/enrollments`, params);
+    }
+    /** Manually enroll a subscriber into an automation */
+    enroll(id, subscriberId) {
+        return this.http.post(`/automation/${id}/enroll`, { subscriberId });
+    }
+}
+exports.Automation = Automation;

package/lib/resources/campaigns.d.ts

@@ -0,0 +1,67 @@
+import { HttpClient } from '../client';
+export interface CreateCampaignOptions {
+    name: string;
+    subject: string;
+    /** Sender email address */
+    from: string;
+    fromName?: string;
+    html?: string;
+    text?: string;
+    templateId?: string;
+    recipients?: Array<string | {
+        email?: string;
+        toEmail?: string;
+        address?: string;
+    }>;
+    /** Send immediately after creation */
+    sendImmediately?: boolean;
+    tags?: string[];
+    replyTo?: string;
+    trackOpens?: boolean;
+    trackClicks?: boolean;
+}
+export interface UpdateCampaignOptions {
+    name?: string;
+    subject?: string;
+    from?: string;
+    fromName?: string;
+    html?: string;
+    text?: string;
+    preheader?: string;
+    scheduledAt?: string | Date;
+    tags?: string[];
+    recipients?: string[];
+}
+export interface ListCampaignsOptions {
+    page?: number;
+    limit?: number;
+}
+export declare class Campaigns {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Create a new campaign (draft by default).
+     * @example
+     * const { campaign } = await client.campaigns.create({ name: 'Launch', subject: 'We're live!', from: 'hi@app.com', html: '...' })
+     */
+    create(options: CreateCampaignOptions): Promise<unknown>;
+    /** List all campaigns. */
+    list(options?: ListCampaignsOptions): Promise<unknown>;
+    /** Get a single campaign by ID. */
+    get(campaignId: string): Promise<unknown>;
+    /**
+     * Update a draft campaign.
+     * Only draft campaigns can be edited.
+     */
+    update(campaignId: string, options: UpdateCampaignOptions): Promise<unknown>;
+    /**
+     * Send a campaign to all its recipients.
+     * @example
+     * await client.campaigns.send('campaign_id')
+     */
+    send(campaignId: string): Promise<unknown>;
+    /** Delete (soft-delete) a campaign. */
+    delete(campaignId: string): Promise<unknown>;
+    /** Get analytics for a specific campaign. */
+    analytics(campaignId: string): Promise<unknown>;
+}

package/lib/resources/campaigns.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Campaigns = void 0;
+class Campaigns {
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Create a new campaign (draft by default).
+     * @example
+     * const { campaign } = await client.campaigns.create({ name: 'Launch', subject: 'We're live!', from: 'hi@app.com', html: '...' })
+     */
+    create(options) {
+        return this.http.post('/campaigns', {
+            name: options.name,
+            subject: options.subject,
+            fromEmail: options.from,
+            fromName: options.fromName,
+            htmlContent: options.html,
+            plainTextContent: options.text,
+            templateId: options.templateId,
+            recipients: options.recipients,
+            sendImmediately: options.sendImmediately,
+            tags: options.tags,
+            replyTo: options.replyTo,
+            trackOpens: options.trackOpens,
+            trackClicks: options.trackClicks,
+        });
+    }
+    /** List all campaigns. */
+    list(options = {}) {
+        return this.http.get('/campaigns', options);
+    }
+    /** Get a single campaign by ID. */
+    get(campaignId) {
+        return this.http.get(`/campaigns/${campaignId}`);
+    }
+    /**
+     * Update a draft campaign.
+     * Only draft campaigns can be edited.
+     */
+    update(campaignId, options) {
+        return this.http.put(`/campaigns/${campaignId}`, {
+            name: options.name,
+            subject: options.subject,
+            fromEmail: options.from,
+            fromName: options.fromName,
+            htmlContent: options.html,
+            textContent: options.text,
+            preheader: options.preheader,
+            scheduledAt: options.scheduledAt instanceof Date ? options.scheduledAt.toISOString() : options.scheduledAt,
+            tags: options.tags,
+            recipients: options.recipients,
+        });
+    }
+    /**
+     * Send a campaign to all its recipients.
+     * @example
+     * await client.campaigns.send('campaign_id')
+     */
+    send(campaignId) {
+        return this.http.post(`/campaigns/${campaignId}/send`);
+    }
+    /** Delete (soft-delete) a campaign. */
+    delete(campaignId) {
+        return this.http.delete(`/campaigns/${campaignId}`);
+    }
+    /** Get analytics for a specific campaign. */
+    analytics(campaignId) {
+        return this.http.get(`/analytics/campaign/${campaignId}`);
+    }
+}
+exports.Campaigns = Campaigns;

package/lib/resources/domains.d.ts

@@ -0,0 +1,19 @@
+import { HttpClient } from '../client';
+export declare class Domains {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Add a sending domain. Returns DNS records (SPF, DKIM, DMARC) to add at your registrar.
+     * @example
+     * const { domain, dnsRecords } = await client.domains.add('myapp.com')
+     */
+    add(domain: string): Promise<unknown>;
+    /** List all sending domains. */
+    list(status?: 'pending' | 'verified' | 'failed'): Promise<unknown>;
+    /** Get a domain and its DNS records by ID. */
+    get(domainId: string): Promise<unknown>;
+    /** Trigger a DNS verification check. */
+    verify(domainId: string): Promise<unknown>;
+    /** Remove a sending domain. */
+    delete(domainId: string): Promise<unknown>;
+}

package/lib/resources/domains.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Domains = void 0;
+class Domains {
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Add a sending domain. Returns DNS records (SPF, DKIM, DMARC) to add at your registrar.
+     * @example
+     * const { domain, dnsRecords } = await client.domains.add('myapp.com')
+     */
+    add(domain) {
+        return this.http.post('/domains', { domain });
+    }
+    /** List all sending domains. */
+    list(status) {
+        return this.http.get('/domains', status ? { status } : undefined);
+    }
+    /** Get a domain and its DNS records by ID. */
+    get(domainId) {
+        return this.http.get(`/domains/${domainId}`);
+    }
+    /** Trigger a DNS verification check. */
+    verify(domainId) {
+        return this.http.post(`/domains/${domainId}/verify`);
+    }
+    /** Remove a sending domain. */
+    delete(domainId) {
+        return this.http.delete(`/domains/${domainId}`);
+    }
+}
+exports.Domains = Domains;

package/lib/resources/emails.d.ts

@@ -0,0 +1,121 @@
+import { HttpClient } from '../client';
+type ReactElement = {
+    type: any;
+    props: any;
+    key: string | null;
+};
+export interface SendEmailOptions {
+    /** Recipient email address */
+    to: string;
+    toName?: string;
+    subject: string;
+    /**
+     * Idempotency key — prevents duplicate sends on network retries.
+     * Same key + same user within 24h returns the cached response.
+     * Pass via X-Idempotency-Key header automatically.
+     */
+    idempotencyKey?: string;
+    /**
+     * HTML body string.
+     * Mutually exclusive with `react` — provide one or the other.
+     */
+    html?: string;
+    /**
+     * React Email component. Requires `@react-email/render` to be installed.
+     * @example
+     * import WelcomeEmail from './emails/welcome';
+     * await client.emails.send({ to: '...', subject: '...', react: <WelcomeEmail name="Alice" /> });
+     */
+    react?: ReactElement;
+    /** Plain-text fallback (auto-generated from HTML if omitted) */
+    text?: string;
+    from?: string;
+    fromName?: string;
+    replyTo?: string;
+    /** CC recipients */
+    cc?: string | string[];
+    /** BCC recipients */
+    bcc?: string | string[];
+}
+export interface SendBulkEmailOptions {
+    /** Array of email addresses or `{ toEmail, toName }` objects */
+    emails: Array<string | {
+        toEmail: string;
+        toName?: string;
+    }>;
+    subject: string;
+    html?: string;
+    react?: ReactElement;
+    text?: string;
+    from?: string;
+    fromName?: string;
+}
+export interface ScheduleEmailOptions {
+    to: string;
+    subject: string;
+    html?: string;
+    react?: ReactElement;
+    /** ISO string or Date — when to deliver */
+    scheduledAt: string | Date;
+    from?: string;
+}
+export interface ListEmailsOptions {
+    page?: number;
+    limit?: number;
+    status?: 'sent' | 'failed' | 'bounced' | 'pending';
+    campaignId?: string;
+}
+export declare class Emails {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * 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 /> })
+     */
+    send(options: SendEmailOptions): Promise<unknown>;
+    /**
+     * 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
+     */
+    render(options: Pick<SendEmailOptions, 'html' | 'react'>): Promise<string>;
+    /**
+     * Send the same email to multiple recipients.
+     * @example
+     * await client.emails.sendBulk({ emails: ['a@b.com', 'c@d.com'], subject: 'News', html: '...' })
+     */
+    sendBulk(options: SendBulkEmailOptions): Promise<unknown>;
+    /**
+     * Schedule an email for future delivery.
+     * @example
+     * await client.emails.schedule({ to: '...', subject: '...', html: '...', scheduledAt: '2026-04-01T09:00:00Z' })
+     */
+    schedule(options: ScheduleEmailOptions): Promise<unknown>;
+    /**
+     * 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>' },
+     * ])
+     */
+    batch(emails: Array<Omit<SendEmailOptions, 'idempotencyKey'>>, idempotencyKey?: string): Promise<unknown>;
+    /** Get a single email by ID. */
+    get(id: string): Promise<unknown>;
+    /** Update the scheduled delivery time of a scheduled email. */
+    updateSchedule(id: string, scheduledAt: string | Date): Promise<unknown>;
+    /** Cancel a scheduled email before it is sent. */
+    cancelSchedule(id: string): Promise<unknown>;
+    /** List sent emails with optional filters. */
+    list(options?: ListEmailsOptions): Promise<unknown>;
+    /** Get account-level email stats (open rate, click rate, etc.). */
+    stats(): Promise<unknown>;
+}
+export {};