@sendcraft/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SendCraft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,326 @@
+# sendcraft-sdk
+
+<p align="center">
+  <img src="https://sendcraft.online/logo.png" alt="SendCraft" width="72" />
+</p>
+
+<p align="center">
+  <strong>Official Node.js / TypeScript SDK for <a href="https://sendcraft.online">SendCraft</a></strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/sendcraft-sdk"><img src="https://img.shields.io/npm/v/sendcraft-sdk?color=6366f1&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/sendcraft-sdk"><img src="https://img.shields.io/npm/dm/sendcraft-sdk?color=10b981&label=downloads" alt="downloads" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node" />
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT" />
+</p>
+
+---
+
+## Installation
+
+```bash
+npm install sendcraft-sdk
+```
+
+**React Email support** (optional):
+```bash
+npm install @react-email/render react react-dom
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { SendCraft } from 'sendcraft-sdk';
+
+const client = new SendCraft({ apiKey: process.env.SENDCRAFT_API_KEY });
+
+// Send a transactional email
+await client.emails.send({
+  to: 'user@example.com',
+  subject: 'Hello!',
+  html: '<h1>Welcome aboard</h1>',
+});
+```
+
+Get your API key from the [SendCraft Dashboard](https://sendcraft.online/dashboard/settings).
+
+---
+
+## API Reference
+
+### `client.emails`
+
+#### `emails.send(options)`
+
+```typescript
+await client.emails.send({
+  to: 'user@example.com',
+  toName: 'Alice',
+  subject: 'Your order shipped',
+  html: '<p>Your order is on the way!</p>',
+  text: 'Your order is on the way!',       // optional plain-text fallback
+  from: 'orders@mystore.com',              // optional, defaults to account default
+  fromName: 'My Store',
+  replyTo: 'support@mystore.com',
+  cc: 'manager@mystore.com',
+  bcc: ['audit@mystore.com'],
+  idempotencyKey: 'order-123-shipped',     // prevent duplicate sends
+});
+```
+
+#### `emails.batch(emails[])`
+
+Send up to 100 emails in one request.
+
+```typescript
+await client.emails.batch([
+  { to: 'alice@example.com', subject: 'Hi Alice', html: '<p>Hello</p>' },
+  { to: 'bob@example.com',   subject: 'Hi Bob',   html: '<p>Hello</p>' },
+]);
+```
+
+#### `emails.schedule(options)`
+
+```typescript
+await client.emails.schedule({
+  to: 'user@example.com',
+  subject: 'Reminder',
+  html: '<p>Just a reminder!</p>',
+  scheduledAt: new Date('2026-04-01T09:00:00Z'),
+});
+```
+
+#### `emails.cancelSchedule(id)` · `emails.updateSchedule(id, scheduledAt)`
+
+```typescript
+await client.emails.cancelSchedule('email_id');
+await client.emails.updateSchedule('email_id', new Date('2026-05-01T09:00:00Z'));
+```
+
+#### `emails.get(id)` · `emails.list(options?)` · `emails.stats()` · `emails.export(options?)`
+
+```typescript
+const email = await client.emails.get('email_id');
+const { emails, total } = await client.emails.list({ page: 1, limit: 20, status: 'sent' });
+const { stats } = await client.emails.stats();
+const csvUrl = await client.emails.export({ days: 30 });
+```
+
+#### `emails.render(options)` — React Email (no send)
+
+```typescript
+import WelcomeEmail from './emails/WelcomeEmail';
+
+const html = await client.emails.render({ react: <WelcomeEmail name="Alice" /> });
+```
+
+---
+
+### `client.campaigns`
+
+```typescript
+// Create
+const { campaign } = await client.campaigns.create({
+  name: 'Summer Sale',
+  subject: 'Big discounts inside',
+  from: 'deals@mystore.com',
+  html: '<h1>Up to 50% off!</h1>',
+  recipients: ['a@example.com', 'b@example.com'],
+});
+
+// Send
+await client.campaigns.send('campaign_id');
+
+// List / Get / Update / Delete
+await client.campaigns.list({ page: 1, limit: 10 });
+await client.campaigns.get('campaign_id');
+await client.campaigns.update('campaign_id', { subject: 'Updated subject' });
+await client.campaigns.delete('campaign_id');
+
+// Analytics
+const { analytics } = await client.campaigns.analytics('campaign_id');
+```
+
+---
+
+### `client.subscribers`
+
+```typescript
+await client.subscribers.add({
+  email: 'user@example.com',
+  listId: 'list_id',
+  firstName: 'Alice',
+  customFields: { plan: 'pro' },
+});
+
+await client.subscribers.import({
+  listId: 'list_id',
+  subscribers: [{ email: 'a@b.com' }, { email: 'c@d.com' }],
+});
+
+await client.subscribers.list({ page: 1, limit: 50, status: 'active' });
+await client.subscribers.update('subscriber_id', { firstName: 'Alicia' });
+await client.subscribers.delete('subscriber_id');
+```
+
+---
+
+### `client.templates`
+
+```typescript
+const { template } = await client.templates.create({
+  name: 'Welcome Email',
+  subject: 'Welcome to {{appName}}',
+  html: '<p>Hi {{firstName}}, welcome!</p>',
+});
+
+await client.templates.list();
+await client.templates.get('template_id');
+await client.templates.update('template_id', { subject: 'New subject' });
+await client.templates.delete('template_id');
+```
+
+---
+
+### `client.domains`
+
+```typescript
+const { domain, dnsRecords } = await client.domains.add('myapp.com');
+dnsRecords.forEach(r => console.log(`${r.type} ${r.name} → ${r.value}`));
+
+await client.domains.verify(domain._id);
+await client.domains.list();
+await client.domains.get('domain_id');
+await client.domains.delete('domain_id');
+```
+
+---
+
+### `client.webhooks`
+
+```typescript
+await client.webhooks.create({
+  url: 'https://myapp.com/hooks/sendcraft',
+  events: ['email.bounced', 'email.opened', 'email.clicked'],
+});
+
+await client.webhooks.list();
+await client.webhooks.delete('webhook_id');
+```
+
+#### Signature Verification
+
+```typescript
+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 = client.webhooks.parse(req.body.toString());
+  // event.type: 'email.bounced' | 'email.opened' | 'email.clicked' | ...
+  res.sendStatus(200);
+});
+```
+
+---
+
+### `client.analytics`
+
+```typescript
+await client.analytics.overview();
+await client.analytics.daily(30);
+await client.analytics.campaign('campaign_id');
+```
+
+---
+
+### `client.segments` · `client.automation` · `client.smtp` · `client.apiKeys` · `client.topics`
+
+```typescript
+// Segments
+await client.segments.list();
+await client.segments.create({ name: 'VIP users', rules: [...] });
+
+// API Keys
+await client.apiKeys.list();
+await client.apiKeys.create('CI key', { permissions: 'sending_access' });
+await client.apiKeys.revoke('key_id');
+
+// SMTP warmup
+await client.smtp.warmupStatus();
+```
+
+---
+
+## Error Handling
+
+```typescript
+import { SendCraft, AuthenticationError, RateLimitError, NotFoundError, SendCraftError } from 'sendcraft-sdk';
+
+try {
+  await client.emails.send({ to: '...', subject: '...', html: '...' });
+} catch (err) {
+  if (err instanceof AuthenticationError) console.error('Invalid API key');
+  else if (err instanceof RateLimitError)  console.error('Rate limited — retry later');
+  else if (err instanceof NotFoundError)   console.error('Resource not found');
+  else if (err instanceof SendCraftError)  console.error(`API error ${err.status}: ${err.message}`);
+  else throw err;
+}
+```
+
+| Class | HTTP | When |
+|---|---|---|
+| `AuthenticationError` | 401 | Invalid or missing API key |
+| `ForbiddenError` | 403 | Insufficient permissions |
+| `NotFoundError` | 404 | Resource not found |
+| `RateLimitError` | 429 | Too many requests |
+| `ConflictError` | 409 | Duplicate resource |
+| `ValidationError` | 422 | Invalid request data |
+| `ServerError` | 500 | Server error |
+
+---
+
+## TypeScript
+
+Full TypeScript support — all options and responses are typed.
+
+```typescript
+import type { SendEmailOptions, CreateCampaignOptions } from 'sendcraft-sdk';
+```
+
+---
+
+## CI/CD
+
+```yaml
+# GitHub Actions
+- name: Send deploy notification
+  env:
+    SENDCRAFT_API_KEY: ${{ secrets.SENDCRAFT_API_KEY }}
+  run: |
+    npx sendcraft-sdk emails.send \
+      --to team@myapp.com \
+      --subject "Deployed ${{ github.sha }}"
+```
+
+---
+
+## Related
+
+| Package | Description |
+|---------|-------------|
+| [`@sendcraft/cli`](https://www.npmjs.com/package/@sendcraft/cli) | Official CLI |
+| [`sendcraft-mcp`](https://www.npmjs.com/package/sendcraft-mcp) | MCP server for AI agents |
+| [`sendcraft-sdk` (PyPI)](https://pypi.org/project/sendcraft-sdk/) | Python SDK |
+
+---
+
+## License
+
+MIT © [SendCraft](https://sendcraft.online)

package/lib/client.d.ts

@@ -0,0 +1,10 @@
+export declare class HttpClient {
+    private axios;
+    constructor(apiKey: string, baseUrl: string);
+    get<T>(path: string, params?: Record<string, unknown>): Promise<T>;
+    post<T>(path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string, body?: unknown): Promise<T>;
+    private wrap;
+}

package/lib/client.js

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+const error_1 = require("./error");
+class HttpClient {
+    constructor(apiKey, baseUrl) {
+        // Reject non-http(s) baseUrl schemes to prevent SSRF via javascript:/file:/data: URIs.
+        let parsedUrl;
+        try {
+            parsedUrl = new URL(baseUrl);
+        }
+        catch {
+            throw new Error(`SendCraft: invalid baseUrl — must be a valid URL, got: ${baseUrl}`);
+        }
+        if (parsedUrl.protocol !== 'https:' && parsedUrl.protocol !== 'http:') {
+            throw new Error(`SendCraft: invalid baseUrl scheme "${parsedUrl.protocol}" — only http: and https: are allowed`);
+        }
+        this.axios = axios_1.default.create({
+            baseURL: baseUrl,
+            headers: {
+                'x-api-key': apiKey,
+                'Content-Type': 'application/json',
+            },
+            timeout: 30000,
+        });
+    }
+    async get(path, params) {
+        try {
+            const res = await this.axios.get(path, { params });
+            return res.data;
+        }
+        catch (err) {
+            throw this.wrap(err);
+        }
+    }
+    async post(path, body, extraHeaders) {
+        try {
+            const res = await this.axios.post(path, body, extraHeaders ? { headers: extraHeaders } : undefined);
+            return res.data;
+        }
+        catch (err) {
+            throw this.wrap(err);
+        }
+    }
+    async put(path, body) {
+        try {
+            const res = await this.axios.put(path, body);
+            return res.data;
+        }
+        catch (err) {
+            throw this.wrap(err);
+        }
+    }
+    async patch(path, body) {
+        try {
+            const res = await this.axios.patch(path, body);
+            return res.data;
+        }
+        catch (err) {
+            throw this.wrap(err);
+        }
+    }
+    async delete(path, body) {
+        try {
+            const res = await this.axios.delete(path, { data: body });
+            return res.data;
+        }
+        catch (err) {
+            throw this.wrap(err);
+        }
+    }
+    wrap(err) {
+        if (axios_1.default.isAxiosError(err)) {
+            const e = err;
+            const msg = e.response?.data?.error ?? e.response?.data?.message ?? e.message;
+            switch (e.response?.status) {
+                case 401: return new error_1.AuthError(msg);
+                case 403: return new error_1.ForbiddenError(msg);
+                case 404: return new error_1.NotFoundError(msg);
+                case 409: return new error_1.ConflictError(msg);
+                case 422: return new error_1.ValidationError(msg);
+                case 429: return new error_1.RateLimitError();
+                case 500: return new error_1.ServerError(msg);
+                default: return new error_1.SendCraftError(msg, e.response?.status ?? 0, 'api_error');
+            }
+        }
+        if (err instanceof error_1.SendCraftError)
+            return err;
+        return new error_1.SendCraftError(String(err), 0, 'unknown');
+    }
+}
+exports.HttpClient = HttpClient;

package/lib/error.d.ts

@@ -0,0 +1,26 @@
+export declare class SendCraftError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status: number, code: string);
+}
+export declare class AuthError extends SendCraftError {
+    constructor(message?: string);
+}
+export declare class ForbiddenError extends SendCraftError {
+    constructor(message?: string);
+}
+export declare class NotFoundError extends SendCraftError {
+    constructor(message?: string);
+}
+export declare class ConflictError extends SendCraftError {
+    constructor(message?: string);
+}
+export declare class ValidationError extends SendCraftError {
+    constructor(message?: string);
+}
+export declare class RateLimitError extends SendCraftError {
+    constructor(message?: string);
+}
+export declare class ServerError extends SendCraftError {
+    constructor(message?: string);
+}

package/lib/error.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerError = exports.RateLimitError = exports.ValidationError = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.AuthError = exports.SendCraftError = void 0;
+class SendCraftError extends Error {
+    constructor(message, status, code) {
+        super(message);
+        this.name = 'SendCraftError';
+        this.status = status;
+        this.code = code;
+    }
+}
+exports.SendCraftError = SendCraftError;
+class AuthError extends SendCraftError {
+    constructor(message = 'Invalid or missing API key') {
+        super(message, 401, 'unauthorized');
+        this.name = 'AuthError';
+    }
+}
+exports.AuthError = AuthError;
+class ForbiddenError extends SendCraftError {
+    constructor(message = 'You do not have permission to perform this action') {
+        super(message, 403, 'forbidden');
+        this.name = 'ForbiddenError';
+    }
+}
+exports.ForbiddenError = ForbiddenError;
+class NotFoundError extends SendCraftError {
+    constructor(message = 'Resource not found') {
+        super(message, 404, 'not_found');
+        this.name = 'NotFoundError';
+    }
+}
+exports.NotFoundError = NotFoundError;
+class ConflictError extends SendCraftError {
+    constructor(message = 'Resource already exists or conflicts with existing data') {
+        super(message, 409, 'conflict');
+        this.name = 'ConflictError';
+    }
+}
+exports.ConflictError = ConflictError;
+class ValidationError extends SendCraftError {
+    constructor(message = 'Validation failed — check your request parameters') {
+        super(message, 422, 'validation_error');
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+class RateLimitError extends SendCraftError {
+    constructor(message = 'Too many requests — please wait before retrying') {
+        super(message, 429, 'rate_limited');
+        this.name = 'RateLimitError';
+    }
+}
+exports.RateLimitError = RateLimitError;
+class ServerError extends SendCraftError {
+    constructor(message = 'An internal server error occurred') {
+        super(message, 500, 'server_error');
+        this.name = 'ServerError';
+    }
+}
+exports.ServerError = ServerError;

package/lib/index.d.ts

@@ -0,0 +1,68 @@
+import { Emails } from './resources/emails';
+import { Campaigns } from './resources/campaigns';
+import { Templates } from './resources/templates';
+import { Subscribers } from './resources/subscribers';
+import { Analytics } from './resources/analytics';
+import { Domains } from './resources/domains';
+import { Webhooks } from './resources/webhooks';
+import { Segments } from './resources/segments';
+import { Automation } from './resources/automation';
+import { Smtp } from './resources/smtp';
+import { ApiKeys } from './resources/apiKeys';
+export interface SendCraftConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+/**
+ * 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')
+ */
+export declare class SendCraft {
+    readonly emails: Emails;
+    readonly campaigns: Campaigns;
+    readonly templates: Templates;
+    readonly subscribers: Subscribers;
+    readonly analytics: Analytics;
+    readonly domains: Domains;
+    readonly webhooks: Webhooks;
+    readonly segments: Segments;
+    readonly automation: Automation;
+    readonly smtp: Smtp;
+    readonly apiKeys: ApiKeys;
+    constructor(config: SendCraftConfig);
+}
+export default SendCraft;
+export * from './resources/emails';
+export * from './resources/campaigns';
+export * from './resources/templates';
+export * from './resources/subscribers';
+export * from './resources/domains';
+export * from './resources/webhooks';
+export * from './resources/segments';
+export * from './resources/automation';
+export * from './resources/smtp';
+export * from './resources/apiKeys';
+export * from './error';