@sendmailos/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 SendMailOS
+
+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,204 @@
+# @sendmailos/sdk
+
+Official JavaScript/TypeScript SDK for SendMailOS email API.
+
+## Installation
+
+```bash
+npm install @sendmailos/sdk
+# or
+yarn add @sendmailos/sdk
+# or
+pnpm add @sendmailos/sdk
+```
+
+## Quick Start
+
+```typescript
+import { SendMailOS } from '@sendmailos/sdk';
+
+const client = new SendMailOS('sk_live_your_api_key');
+
+// Send a transactional email
+await client.emails.send({
+  to: 'user@example.com',
+  fromName: 'Your Company',
+  fromEmail: 'hello@yourcompany.com',
+  subject: 'Welcome!',
+  html: '<h1>Hello!</h1><p>Welcome to our platform.</p>'
+});
+```
+
+## Features
+
+- **Type-safe**: Full TypeScript support with exported types
+- **Lightweight**: Zero dependencies for core SDK
+- **React Components**: Pre-built components for common patterns
+- **Webhook Verification**: Secure signature verification utilities
+- **Error Handling**: Custom error classes for different scenarios
+
+## API Reference
+
+### Emails
+
+```typescript
+// Send transactional email
+await client.emails.send({
+  to: 'user@example.com',
+  subject: 'Hello!',
+  html: '<h1>Welcome!</h1>',
+  fromName: 'Acme',
+  fromEmail: 'hello@acme.com',
+});
+
+// Send with template
+await client.emails.sendTemplate({
+  to: 'user@example.com',
+  templateId: 'tmpl_welcome',
+  variables: { firstName: 'John' }
+});
+```
+
+### Subscribers
+
+```typescript
+// Create subscriber
+const { subscriber } = await client.subscribers.create({
+  email: 'user@example.com',
+  firstName: 'John',
+  tags: ['newsletter', 'premium']
+});
+
+// List subscribers
+const { subscribers, total } = await client.subscribers.list({
+  limit: 50,
+  offset: 0
+});
+```
+
+### Campaigns
+
+```typescript
+// Send campaign
+await client.campaigns.send({
+  name: 'Weekly Newsletter',
+  subject: 'What\'s new this week',
+  fromName: 'Company Newsletter',
+  fromEmail: 'news@company.com',
+  html: '<h1>Hello {{first_name}}!</h1>',
+  tags: ['newsletter'] // Filter by subscriber tags
+});
+```
+
+### Domains
+
+```typescript
+// Add sending domain
+const { domain } = await client.domains.create({
+  domain: 'yourcompany.com'
+});
+
+console.log('DNS Records to add:', domain.dnsRecords);
+```
+
+## React Integration
+
+```tsx
+import { SendMailOSProvider, SubscribeForm } from '@sendmailos/sdk/react';
+
+function App() {
+  return (
+    <SendMailOSProvider publicKey="pk_live_...">
+      <SubscribeForm
+        tags={['newsletter']}
+        onSuccess={() => console.log('Subscribed!')}
+        buttonText="Join Newsletter"
+      />
+    </SendMailOSProvider>
+  );
+}
+```
+
+### Custom Form with Hook
+
+```tsx
+import { useSubscribe } from '@sendmailos/sdk/react';
+
+function CustomForm() {
+  const { subscribe, isLoading, error, isSuccess } = useSubscribe();
+  const [email, setEmail] = useState('');
+
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    await subscribe({ email, tags: ['newsletter'] });
+  };
+
+  if (isSuccess) return <p>Thanks for subscribing!</p>;
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+      />
+      <button disabled={isLoading}>
+        {isLoading ? 'Subscribing...' : 'Subscribe'}
+      </button>
+      {error && <p>{error.message}</p>}
+    </form>
+  );
+}
+```
+
+## Webhook Verification
+
+```typescript
+import { verifyWebhookSignature } from '@sendmailos/sdk';
+
+app.post('/webhooks', (req, res) => {
+  const isValid = verifyWebhookSignature({
+    payload: JSON.stringify(req.body),
+    signature: req.headers['x-sendmailos-signature'],
+    timestamp: req.headers['x-sendmailos-timestamp'],
+    secret: process.env.WEBHOOK_SECRET
+  });
+
+  if (!isValid) {
+    return res.status(401).json({ error: 'Invalid signature' });
+  }
+
+  // Process webhook event
+  const event = req.body;
+  console.log('Event:', event.type);
+
+  res.status(200).json({ received: true });
+});
+```
+
+## Error Handling
+
+```typescript
+import { SendMailOS, SendMailOSError, RateLimitError } from '@sendmailos/sdk';
+
+try {
+  await client.emails.send({ ... });
+} catch (error) {
+  if (error instanceof RateLimitError) {
+    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
+  } else if (error instanceof SendMailOSError) {
+    console.log(`Error: ${error.message} (${error.code})`);
+  }
+}
+```
+
+## Security
+
+- **Never expose secret keys** (`sk_*`) in client-side code
+- Use **public keys** (`pk_*`) for React components
+- Verify webhook signatures to prevent spoofing
+- Use environment variables for API keys
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,480 @@
+/**
+ * SendMailOS SDK Types
+ */
+interface SendMailOSOptions {
+    /** Base URL for the API (default: https://api.sendmailos.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Custom fetch implementation (for testing/Node.js polyfill) */
+    fetch?: typeof fetch;
+}
+interface SendEmailRequest {
+    /** Recipient email address */
+    to: string;
+    /** Email subject line (supports Handlebars variables) */
+    subject: string;
+    /** HTML content (required if no templateId) */
+    html?: string;
+    /** Template ID to use (required if no html) */
+    templateId?: string;
+    /** Sender display name (default: "System") */
+    fromName?: string;
+    /** Sender email address (must be from verified domain) */
+    fromEmail?: string;
+    /** Template variables for Handlebars interpolation */
+    variables?: Record<string, unknown>;
+    /** Email type: "transactional" (default) or "marketing" */
+    type?: 'transactional' | 'marketing';
+}
+interface SendEmailResponse {
+    success: boolean;
+    message: string;
+    id: string;
+    sandbox?: boolean;
+}
+interface Subscriber {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    status: 'subscribed' | 'unsubscribed' | 'bounced' | 'complained';
+    tags?: string[];
+    source: string;
+    createdAt: string;
+    primaryDomain?: {
+        id: string;
+        domainName: string;
+    };
+}
+interface CreateSubscriberRequest {
+    /** Subscriber email address */
+    email: string;
+    /** First name (for personalization) */
+    firstName?: string;
+    /** Last name (for personalization) */
+    lastName?: string;
+    /** Tags for segmentation */
+    tags?: string[];
+    /** Associate with a specific domain */
+    domainId?: string;
+}
+interface CreateSubscriberResponse {
+    success: boolean;
+    subscriber: Subscriber;
+}
+interface ListSubscribersRequest {
+    /** Results per page (default: 20, max: 100) */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+}
+interface ListSubscribersResponse {
+    success: boolean;
+    subscribers: Subscriber[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface SendCampaignRequest {
+    /** Campaign name (for tracking) */
+    name?: string;
+    /** Email subject line (supports Handlebars) */
+    subject: string;
+    /** Sender display name */
+    fromName: string;
+    /** Sender email (from verified domain) */
+    fromEmail: string;
+    /** HTML content (required if no templateId) */
+    html?: string;
+    /** Template ID (required if no html) */
+    templateId?: string;
+    /** Filter subscribers by tags (AND logic) */
+    tags?: string[];
+    /** Global template variables */
+    variables?: Record<string, unknown>;
+}
+interface SendCampaignResponse {
+    success: boolean;
+    message: string;
+    campaignId: string;
+}
+interface Domain {
+    id: string;
+    domainName: string;
+    status: 'pending' | 'verified' | 'failed';
+    dkimTokens: string[];
+    createdAt: string;
+    verifiedAt?: string;
+    dnsRecords?: DnsRecord[];
+}
+interface DnsRecord {
+    type: 'CNAME' | 'TXT' | 'MX';
+    name: string;
+    value: string;
+}
+interface CreateDomainRequest {
+    /** Domain name (e.g., "yourcompany.com") */
+    domain: string;
+}
+interface CreateDomainResponse {
+    success: boolean;
+    domain: Domain;
+}
+interface ListDomainsResponse {
+    success: boolean;
+    domains: Domain[];
+}
+type WebhookEventType = 'email.sent' | 'email.delivered' | 'email.opened' | 'email.clicked' | 'email.bounced' | 'email.complained';
+interface WebhookEvent {
+    id: string;
+    type: WebhookEventType;
+    createdAt: string;
+    data: {
+        emailId: string;
+        messageId: string;
+        recipient: string;
+        campaignId?: string;
+        timestamp: string;
+        metadata?: Record<string, unknown>;
+    };
+}
+interface CreateWebhookRequest {
+    /** Endpoint URL to receive webhook events */
+    url: string;
+    /** Events to subscribe to */
+    events: WebhookEventType[];
+    /** Signing secret for webhook verification */
+    secret?: string;
+}
+interface Webhook {
+    id: string;
+    url: string;
+    events: WebhookEventType[];
+    active: boolean;
+    createdAt: string;
+}
+interface ApiError {
+    success: false;
+    error: string;
+    code: string;
+    retryAfter?: number;
+}
+
+/**
+ * Emails resource for sending transactional emails
+ */
+declare class EmailsResource {
+    private request;
+    constructor(request: <T>(endpoint: string, options?: RequestInit) => Promise<T>);
+    /**
+     * Send a transactional email
+     *
+     * @example
+     * ```ts
+     * const result = await client.emails.send({
+     *   to: 'user@example.com',
+     *   fromName: 'Your Company',
+     *   fromEmail: 'hello@yourcompany.com',
+     *   subject: 'Welcome!',
+     *   html: '<h1>Hello!</h1>'
+     * });
+     * ```
+     */
+    send(params: SendEmailRequest): Promise<SendEmailResponse>;
+    /**
+     * Send email using a template
+     *
+     * @example
+     * ```ts
+     * const result = await client.emails.sendTemplate({
+     *   to: 'user@example.com',
+     *   templateId: 'tmpl_welcome',
+     *   variables: { firstName: 'John' }
+     * });
+     * ```
+     */
+    sendTemplate(params: {
+        to: string;
+        templateId: string;
+        fromName?: string;
+        fromEmail?: string;
+        subject?: string;
+        variables?: Record<string, unknown>;
+    }): Promise<SendEmailResponse>;
+}
+
+/**
+ * Subscribers resource for managing email contacts
+ */
+declare class SubscribersResource {
+    private request;
+    constructor(request: <T>(endpoint: string, options?: RequestInit) => Promise<T>);
+    /**
+     * Create or update a subscriber (upsert)
+     *
+     * @example
+     * ```ts
+     * const { subscriber } = await client.subscribers.create({
+     *   email: 'user@example.com',
+     *   firstName: 'John',
+     *   tags: ['newsletter', 'premium']
+     * });
+     * ```
+     */
+    create(params: CreateSubscriberRequest): Promise<CreateSubscriberResponse>;
+    /**
+     * List all subscribers with pagination
+     *
+     * @example
+     * ```ts
+     * const { subscribers, total } = await client.subscribers.list({
+     *   limit: 50,
+     *   offset: 0
+     * });
+     * ```
+     */
+    list(params?: ListSubscribersRequest): Promise<ListSubscribersResponse>;
+    /**
+     * Get a single subscriber by ID
+     */
+    get(subscriberId: string): Promise<{
+        success: boolean;
+        subscriber: Subscriber;
+    }>;
+    /**
+     * Update a subscriber by ID
+     */
+    update(subscriberId: string, params: Partial<CreateSubscriberRequest>): Promise<CreateSubscriberResponse>;
+    /**
+     * Update a subscriber by email address
+     */
+    updateByEmail(email: string, params: Partial<Omit<CreateSubscriberRequest, 'email'>>): Promise<CreateSubscriberResponse>;
+    /**
+     * Delete/unsubscribe a subscriber
+     */
+    delete(subscriberId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Add tags to a subscriber
+     */
+    addTags(subscriberId: string, tags: string[]): Promise<CreateSubscriberResponse>;
+    /**
+     * Remove tags from a subscriber
+     */
+    removeTags(subscriberId: string, tags: string[]): Promise<CreateSubscriberResponse>;
+}
+
+/**
+ * Campaigns resource for bulk email sending
+ */
+declare class CampaignsResource {
+    private request;
+    constructor(request: <T>(endpoint: string, options?: RequestInit) => Promise<T>);
+    /**
+     * Send a campaign to subscribers
+     *
+     * @example
+     * ```ts
+     * const result = await client.campaigns.send({
+     *   name: 'January Newsletter',
+     *   subject: 'What\'s new this month',
+     *   fromName: 'Your Company',
+     *   fromEmail: 'news@yourcompany.com',
+     *   html: '<h1>Hello {{first_name}}!</h1>',
+     *   tags: ['newsletter', 'active']
+     * });
+     * ```
+     */
+    send(params: SendCampaignRequest): Promise<SendCampaignResponse>;
+    /**
+     * Send campaign using a saved template
+     */
+    sendTemplate(params: {
+        name?: string;
+        templateId: string;
+        subject: string;
+        fromName: string;
+        fromEmail: string;
+        tags?: string[];
+        variables?: Record<string, unknown>;
+    }): Promise<SendCampaignResponse>;
+}
+
+/**
+ * Domains resource for managing sending domains
+ */
+declare class DomainsResource {
+    private request;
+    constructor(request: <T>(endpoint: string, options?: RequestInit) => Promise<T>);
+    /**
+     * Add a new sending domain
+     * Returns DKIM tokens and DNS records for verification
+     *
+     * @example
+     * ```ts
+     * const { domain } = await client.domains.create({
+     *   domain: 'yourcompany.com'
+     * });
+     *
+     * console.log('Add these DNS records:', domain.dnsRecords);
+     * ```
+     */
+    create(params: CreateDomainRequest): Promise<CreateDomainResponse>;
+    /**
+     * List all domains for the organization
+     */
+    list(): Promise<ListDomainsResponse>;
+    /**
+     * Get a single domain by ID
+     */
+    get(domainId: string): Promise<{
+        success: boolean;
+        domain: Domain;
+    }>;
+    /**
+     * Verify a domain (trigger DNS check)
+     */
+    verify(domainId: string): Promise<{
+        success: boolean;
+        domain: Domain;
+    }>;
+    /**
+     * Delete a domain
+     */
+    delete(domainId: string): Promise<{
+        success: boolean;
+    }>;
+}
+
+/**
+ * SendMailOS SDK Client
+ *
+ * @example
+ * ```ts
+ * import { SendMailOS } from '@sendmailos/sdk';
+ *
+ * const client = new SendMailOS('sk_live_your_api_key');
+ *
+ * // Send an email
+ * await client.emails.send({
+ *   to: 'user@example.com',
+ *   subject: 'Hello!',
+ *   html: '<h1>Welcome!</h1>'
+ * });
+ *
+ * // Add a subscriber
+ * await client.subscribers.create({
+ *   email: 'user@example.com',
+ *   tags: ['newsletter']
+ * });
+ * ```
+ */
+declare class SendMailOS {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly fetchFn;
+    /** Email sending operations */
+    readonly emails: EmailsResource;
+    /** Subscriber management */
+    readonly subscribers: SubscribersResource;
+    /** Campaign operations */
+    readonly campaigns: CampaignsResource;
+    /** Domain management */
+    readonly domains: DomainsResource;
+    constructor(apiKey: string, options?: SendMailOSOptions);
+    /**
+     * Make an authenticated request to the API
+     */
+    private request;
+    private safeParseJson;
+    /**
+     * Check if the API key is valid (test mode only)
+     */
+    get isTestMode(): boolean;
+    /**
+     * Get the SDK version
+     */
+    static get version(): string;
+}
+
+/**
+ * Custom error classes for SendMailOS SDK
+ */
+declare class SendMailOSError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly retryAfter?: number;
+    constructor(message: string, code: string, statusCode: number, retryAfter?: number);
+    /** Whether this error is retryable (rate limit or server error) */
+    get isRetryable(): boolean;
+}
+declare class AuthenticationError extends SendMailOSError {
+    constructor(message?: string);
+}
+declare class ValidationError extends SendMailOSError {
+    constructor(message: string);
+}
+declare class RateLimitError extends SendMailOSError {
+    constructor(message: string, retryAfter: number);
+}
+declare class NotFoundError extends SendMailOSError {
+    constructor(message: string);
+}
+
+/**
+ * Webhook signature verification utilities
+ *
+ * IMPORTANT: This module uses timing-safe comparison to prevent timing attacks.
+ */
+interface VerifyWebhookParams {
+    /** Raw request body as string */
+    payload: string;
+    /** Value of X-SendMailOS-Signature header */
+    signature: string;
+    /** Value of X-SendMailOS-Timestamp header */
+    timestamp: string;
+    /** Your webhook signing secret */
+    secret: string;
+    /** Maximum age in seconds (default: 300 = 5 minutes) */
+    tolerance?: number;
+}
+/**
+ * Verify a webhook signature to ensure the request came from SendMailOS
+ *
+ * @example
+ * ```ts
+ * import { verifyWebhookSignature } from '@sendmailos/sdk';
+ *
+ * app.post('/webhooks', (req, res) => {
+ *   const isValid = verifyWebhookSignature({
+ *     payload: JSON.stringify(req.body),
+ *     signature: req.headers['x-sendmailos-signature'],
+ *     timestamp: req.headers['x-sendmailos-timestamp'],
+ *     secret: process.env.WEBHOOK_SECRET
+ *   });
+ *
+ *   if (!isValid) {
+ *     return res.status(401).json({ error: 'Invalid signature' });
+ *   }
+ *
+ *   // Process webhook...
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature(params: VerifyWebhookParams): boolean;
+/**
+ * Async version of webhook verification (recommended for edge/browser)
+ */
+declare function verifyWebhookSignatureAsync(params: VerifyWebhookParams): Promise<boolean>;
+/**
+ * Construct a webhook event from raw request data
+ */
+declare function constructWebhookEvent<T = unknown>(payload: string, headers: {
+    signature: string;
+    timestamp: string;
+}, secret: string): T;
+
+export { type ApiError, AuthenticationError, type CreateDomainRequest, type CreateDomainResponse, type CreateSubscriberRequest, type CreateSubscriberResponse, type CreateWebhookRequest, type DnsRecord, type Domain, type ListDomainsResponse, type ListSubscribersRequest, type ListSubscribersResponse, NotFoundError, RateLimitError, type SendCampaignRequest, type SendCampaignResponse, type SendEmailRequest, type SendEmailResponse, SendMailOS, SendMailOSError, type SendMailOSOptions, type Subscriber, ValidationError, type VerifyWebhookParams, type Webhook, type WebhookEvent, type WebhookEventType, constructWebhookEvent, SendMailOS as default, verifyWebhookSignature, verifyWebhookSignatureAsync };