tosend 1.0.1 → 1.2.0

package/dist/index.d.ts

@@ -15,6 +15,8 @@ interface Attachment {
     name: string;
     /** Base64 encoded content */
     content: string;
+    /** Embeds the file inline: reference it in the HTML as `cid:<content_id>` */
+    content_id?: string;
 }
 interface SendEmailParams {
     /** Sender address */
@@ -45,23 +47,36 @@ interface BatchEmailResult {
     status: 'success' | 'error' | 'spam';
     message_id?: string;
     message?: string;
-    errors?: Record<string, Record<string, string>>;
+    errors?: ValidationErrors;
 }
 interface BatchEmailResponse {
     results: BatchEmailResult[];
 }
 interface Domain {
+    id: number;
     domain_name: string;
-    verification_status: 'pending' | 'verified' | 'failed';
-    created_at: string;
+    verification_status: string;
+    /** 1 for the account's default domain, else 0 */
+    is_default: number;
+    total_sent: number;
+    total_bounced: number;
+    total_complained: number;
 }
 interface AccountInfo {
     account: {
-        title: string;
-        plan_type: string;
+        id: number;
         status: string;
-        emails_usage_this_month: number;
-        emails_sent_last_24hrs: number;
+        plan_type: string;
+        /** null means the account does not consume credits */
+        credit_balance: number | null;
+        monthly_email_limit: number;
+        limit_per_second: number;
+        ses_region: string;
+        /** @deprecated Not returned to a sending key. Use `new ToSendAdmin(key).getInfo()`. */
+        bounce_rate?: number;
+        /** @deprecated Not returned to a sending key. Use `new ToSendAdmin(key).getInfo()`. */
+        complaint_rate?: number;
+        ses_status: string;
     };
     domains: Domain[];
 }
@@ -69,8 +84,25 @@ interface ToSendErrorResponse {
     status_code: number;
     error_type: ErrorType;
     message: string;
-    errors?: Record<string, Record<string, string>>;
+    /**
+     * Field-level validation detail.
+     *
+     * The sending API returns a nested map (`{subject: {required: "..."}}`);
+     * the Worker's ApiError returns a flat one (`{name: "required"}`). Both
+     * shapes reach this type, so consumers must not assume either — see
+     * ToSendError.errors.
+     */
+    errors?: ValidationErrors;
 }
+/**
+ * Either shape the API may return for `errors`.
+ *
+ * ToSendError declared the nested form only, so `err.errors.name` was typed
+ * as an object while the Worker actually sends the string `'required'`. That
+ * compiled because the response was cast, and would have surfaced as an
+ * undefined property at runtime.
+ */
+type ValidationErrors = Record<string, string | Record<string, string>>;
 type ErrorType = 'bad_request' | 'unauthorized' | 'forbidden' | 'not_found' | 'validation_error' | 'rate_limit_exceeded' | 'internal_error';
 interface ToSendConfig {
     /** Your ToSend API key */
@@ -83,9 +115,10 @@ interface ToSendConfig {
 declare class ToSendError extends Error {
     readonly code: number;
     readonly errorType: ErrorType;
-    readonly errors: Record<string, Record<string, string>>;
+    /** See ValidationErrors — the value may be a string or a nested map. */
+    readonly errors: ValidationErrors;
     private static readonly ERROR_TYPE_MAP;
-    constructor(message: string, code?: number, errors?: Record<string, Record<string, string>>, errorType?: ErrorType);
+    constructor(message: string, code?: number, errors?: ValidationErrors, errorType?: ErrorType);
     get isValidationError(): boolean;
     get isAuthenticationError(): boolean;
     get isRateLimitError(): boolean;
@@ -154,5 +187,329 @@ declare class ToSend {
     private isValidEmail;
     private request;
 }
+interface AdminDomain {
+    /** Domain identifier used across the Admin API */
+    id: string;
+    domain_name: string;
+    verification_status: 'draft' | 'pending' | 'verified' | 'failed';
+    is_default: boolean;
+    ses_region: string | null;
+    total_sent: number;
+    total_bounced: number;
+    total_complained: number;
+    updated_at: string;
+}
+interface DnsRecord {
+    type: 'TXT' | 'MX';
+    name: string;
+    content: string;
+    TTL: string;
+    priority: string;
+    /**
+     * NOT returned by the Admin API.
+     *
+     * The domain-detail endpoint does not resolve DNS on your behalf (that
+     * would make a GET fire four lookups and a write), so there is no
+     * per-record status. Poll `verification_status` on the domain instead —
+     * it is the result of the automatic 10-minute check.
+     *
+     * @deprecated Always undefined. Kept so existing code still compiles.
+     */
+    status?: string;
+}
+interface CreatedDomain {
+    /** Same identifier the list and detail endpoints use */
+    id: string;
+    domain_name: string;
+    verification_status: string;
+    created_at: string;
+}
+interface AdminDomainDetail {
+    id: string;
+    domain_name: string;
+    verification_status: string;
+    dmarc_policy: string | null;
+    created_at: string;
+    dns_records: {
+        dkim: DnsRecord;
+        spf: DnsRecord[];
+    };
+    /** Whether the automatic 10-minute DNS check still covers this domain */
+    auto_verification: {
+        active: boolean;
+        reason: string;
+    };
+}
+interface EmailLog {
+    /** Same value POST /v2/emails returned as message_id */
+    id: string;
+    status: string;
+    subject: string | null;
+    from: string | null;
+    from_name: string | null;
+    to: Array<{
+        email: string;
+        name?: string;
+    }>;
+    reply_to: string | null;
+    recipients_count: number;
+    error: string | null;
+    has_attachments: boolean;
+    sent_at: string | null;
+    created_at: string;
+}
+interface Paginated<T> {
+    data: T[];
+    total: number;
+    page: number;
+    per_page: number;
+}
+interface ListLogsParams {
+    page?: number;
+    /** 1-100, default 25 */
+    per_page?: number;
+    status?: string;
+    /** Domain name or domain id */
+    domain?: string;
+    from?: string;
+    to?: string;
+    search?: string;
+}
+interface Suppression {
+    email: string;
+    bounce_sub_type: string | null;
+    bounce_reason: string | null;
+    hard_bounced_at: string | null;
+    last_complaint_at: string | null;
+    complaint_count: number;
+    created_at: string;
+    updated_at: string;
+}
+/** The only events toSend emits. Delivery, open and click do not exist. */
+type WebhookEvent = 'bounced' | 'complaint';
+interface Webhook {
+    id: number;
+    title: string | null;
+    url: string;
+    events: WebhookEvent[];
+    status: string;
+    include_message: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface SendingKey {
+    id: number;
+    title: string | null;
+    /** Masked. The full key is returned only by createSendingKey(). */
+    key: string;
+    status: string;
+    domain: string | null;
+    created_at: string;
+}
+interface CreatedSendingKey {
+    id: number;
+    name: string;
+    /** Shown once. Store it now — it cannot be retrieved later. */
+    api_key: string;
+    created_at: string;
+}
+/** GET /v2/info with an admin key */
+interface AdminInfo {
+    account: {
+        id: number;
+        status: string;
+        plan_type: string;
+        /** The pooled balance for the whole account, never a child team's own */
+        credit_balance: number | null;
+        credits_shared: boolean;
+        limit_per_second: number;
+        ses_region: string;
+        /** Last 30 days, fraction between 0 and 1 (0.004 = 0.4%) */
+        bounce_rate: number;
+        /** Last 30 days, fraction between 0 and 1 */
+        complaint_rate: number;
+    };
+    key: {
+        id: number;
+        title: string;
+        type: 'admin';
+        /** The team this request acted on */
+        acting_on: number;
+        /** The team that owns the key */
+        owned_by: number;
+        scopes: string[];
+    };
+    /** Present only when the key has `domains:read` */
+    domains?: AdminDomain[];
+}
+interface SuppressionReactivation {
+    deleted: boolean;
+    message: string;
+    used_today: number;
+    remaining_today: number;
+    daily_limit: number;
+}
+/** Where a team sends from. Fixed for the life of the team. */
+type SesRegion = 'us-east-1' | 'eu-central-1';
+interface TeamList {
+    account: {
+        id: number;
+        name: string | null;
+        status: string;
+        credit_balance: number | null;
+    };
+    teams: Array<{
+        id: number;
+        name: string | null;
+        status: string;
+        ses_region: SesRegion;
+    }>;
+    /** Credits pool at the parent; child teams have no separate balance */
+    credits_shared: boolean;
+}
+interface AdminConfig {
+    /** Your admin API key (tsend_admin_...) */
+    apiKey: string;
+    /** Act on a child team by default. Overridable per call. */
+    accountId?: number;
+    baseUrl?: string;
+    timeout?: number;
+}
+/**
+ * Account-level API client.
+ *
+ * Deliberately a separate class from `ToSend`: admin keys and sending keys are
+ * different credentials and are not interchangeable. A sending key cannot
+ * manage the account, and an admin key can only send when it holds the
+ * `emails:send` scope. Keeping them on separate clients means the mistake is
+ * caught at the type level rather than by a 401 in production.
+ *
+ * @example
+ * ```ts
+ * const admin = new ToSendAdmin(process.env.TOSEND_ADMIN_KEY!);
+ *
+ * const domain = await admin.createDomain('client.example.com');
+ * const detail = await admin.getDomain(domain.id);
+ * console.log(detail.dns_records.dkim);
+ * // No verify call needed — toSend checks DNS every 10 minutes.
+ * ```
+ */
+declare class ToSendAdmin {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly accountId?;
+    constructor(config: string | AdminConfig);
+    /**
+     * The team this key acts on, the key itself and its scopes. Needs no scope,
+     * so it is the way to check a key works.
+     */
+    getInfo(): Promise<AdminInfo>;
+    /** Return a client scoped to one of your child teams. */
+    forAccount(accountId: number): ToSendAdmin;
+    /**
+     * Send an email as the targeted team (the key's own, or one set with
+     * forAccount()). The key must hold the `emails:send` scope.
+     */
+    send(params: SendEmailParams): Promise<SendEmailResponse>;
+    /** Send up to 100 emails in one request; same scope and targeting as send(). */
+    batch(emails: SendEmailParams[]): Promise<BatchEmailResponse>;
+    listDomains(params?: {
+        page?: number;
+        per_page?: number;
+    }): Promise<Paginated<AdminDomain>>;
+    /**
+     * Add a sending domain.
+     *
+     * The domain starts in `draft`. There is NO verify call to make: toSend
+     * checks public DNS every 10 minutes and provisions the domain as soon as
+     * the records resolve.
+     *
+     * A duplicate throws a 409. Treat that as "already exists, go read it" —
+     * domain names are globally unique, so a retry after a timeout hits this
+     * for a domain your first call created successfully.
+     */
+    createDomain(name: string): Promise<CreatedDomain>;
+    /** Domain detail plus the DNS records your customer must publish. */
+    getDomain(id: string): Promise<AdminDomainDetail>;
+    /**
+     * Remove a domain.
+     *
+     * Does NOT remove anything from your customer's DNS zone. Records left
+     * published can allow the domain to be re-verified elsewhere, so clean them
+     * up in your own workflow.
+     */
+    deleteDomain(id: string): Promise<void>;
+    listEmails(params?: ListLogsParams): Promise<Paginated<EmailLog>>;
+    /** Look up one message by the id POST /v2/emails returned. */
+    getEmail(messageId: string): Promise<EmailLog>;
+    listSuppressions(params?: {
+        page?: number;
+        per_page?: number;
+        search?: string;
+        status?: string;
+    }): Promise<Paginated<Suppression>>;
+    /** Limited to 500 per day per account, shared with the dashboard. */
+    deleteSuppression(email: string): Promise<SuppressionReactivation>;
+    listWebhooks(params?: {
+        page?: number;
+        per_page?: number;
+    }): Promise<Paginated<Webhook>>;
+    /**
+     * The signing `secret` is generated by toSend. The API returns it only in
+     * this response (the dashboard can show it later), so store it now.
+     */
+    createWebhook(params: {
+        url: string;
+        events: WebhookEvent[];
+        title?: string;
+        include_message?: boolean;
+    }): Promise<Webhook & {
+        secret: string;
+    }>;
+    updateWebhook(id: number, params: Partial<{
+        url: string;
+        events: WebhookEvent[];
+        title: string;
+        status: 'active' | 'inactive';
+        include_message: boolean;
+    }>): Promise<Webhook>;
+    deleteWebhook(id: number): Promise<void>;
+    listSendingKeys(params?: {
+        page?: number;
+        per_page?: number;
+    }): Promise<Paginated<SendingKey>>;
+    /**
+     * Mint a sending key for this team — how you give each client their own key.
+     *
+     * The raw key is returned once and never again. Pass `domain` (a domain id)
+     * to restrict it to one domain; omit it for all domains on the team.
+     * Needs the `api_keys:write` and `emails:send` scopes.
+     */
+    createSendingKey(name: string, domain?: string): Promise<CreatedSendingKey>;
+    deleteSendingKey(id: number): Promise<void>;
+    listTeams(): Promise<TeamList>;
+    /**
+     * Only the parent account can create teams. `ses_region` defaults to
+     * 'us-east-1' and cannot be changed once the team exists.
+     */
+    createTeam(name: string, options?: {
+        ses_region?: SesRegion;
+    }): Promise<{
+        id: number;
+        name: string;
+        status: string;
+        ses_region: SesRegion;
+    }>;
+    updateTeam(id: number, params: {
+        name?: string;
+        status?: 'active' | 'suspended';
+    }): Promise<{
+        id: number;
+        name: string;
+        status: string;
+    }>;
+    private request;
+}
 
-export { type AccountInfo, type Address, type Attachment, type BatchEmailResponse, type BatchEmailResult, type Domain, type ErrorType, type SendEmailParams, type SendEmailResponse, ToSend, type ToSendConfig, ToSendError, type ToSendErrorResponse, ToSend as default };
+export { type AccountInfo, type Address, type AdminConfig, type AdminDomain, type AdminDomainDetail, type AdminInfo, type Attachment, type BatchEmailResponse, type BatchEmailResult, type CreatedDomain, type CreatedSendingKey, type DnsRecord, type Domain, type EmailLog, type ErrorType, type ListLogsParams, type Paginated, type SendEmailParams, type SendEmailResponse, type SendingKey, type SesRegion, type Suppression, type SuppressionReactivation, type TeamList, ToSend, ToSendAdmin, type ToSendConfig, ToSendError, type ToSendErrorResponse, type ValidationErrors, type Webhook, type WebhookEvent, ToSend as default };

package/dist/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ToSend: () => ToSend,
+  ToSendAdmin: () => ToSendAdmin,
   ToSendError: () => ToSendError,
   default: () => index_default
 });
@@ -28,6 +29,7 @@ module.exports = __toCommonJS(index_exports);
 var ToSendError = class _ToSendError extends Error {
   code;
   errorType;
+  /** See ValidationErrors — the value may be a string or a nested map. */
   errors;
   static ERROR_TYPE_MAP = {
     400: "bad_request",
@@ -229,10 +231,222 @@ var ToSend = class {
     }
   }
 };
+var ToSendAdmin = class _ToSendAdmin {
+  apiKey;
+  baseUrl;
+  timeout;
+  accountId;
+  constructor(config) {
+    if (typeof config === "string") {
+      this.apiKey = config;
+      this.baseUrl = "https://api.tosend.com";
+      this.timeout = 3e4;
+    } else {
+      this.apiKey = config.apiKey;
+      this.baseUrl = config.baseUrl?.replace(/\/$/, "") ?? "https://api.tosend.com";
+      this.timeout = config.timeout ?? 3e4;
+      this.accountId = config.accountId;
+    }
+    if (!this.apiKey?.trim()) {
+      throw new ToSendError("Admin API key is required", 401);
+    }
+    if (!this.apiKey.startsWith("tsend_admin_")) {
+      throw new ToSendError(
+        'This is not an admin API key. Admin keys start with "tsend_admin_" and are created in the dashboard under API Keys.',
+        401
+      );
+    }
+  }
+  /**
+   * The team this key acts on, the key itself and its scopes. Needs no scope,
+   * so it is the way to check a key works.
+   */
+  async getInfo() {
+    return this.request("GET", "/v2/info");
+  }
+  /** Return a client scoped to one of your child teams. */
+  forAccount(accountId) {
+    return new _ToSendAdmin({
+      apiKey: this.apiKey,
+      baseUrl: this.baseUrl,
+      timeout: this.timeout,
+      accountId
+    });
+  }
+  // ── Sending (requires the emails:send scope) ──
+  /**
+   * Send an email as the targeted team (the key's own, or one set with
+   * forAccount()). The key must hold the `emails:send` scope.
+   */
+  async send(params) {
+    return this.request("POST", "/v2/emails", params);
+  }
+  /** Send up to 100 emails in one request; same scope and targeting as send(). */
+  async batch(emails) {
+    return this.request("POST", "/v2/emails/batch", { emails });
+  }
+  // ── Domains ──
+  async listDomains(params = {}) {
+    return this.request("GET", "/v2/domains", void 0, params);
+  }
+  /**
+   * Add a sending domain.
+   *
+   * The domain starts in `draft`. There is NO verify call to make: toSend
+   * checks public DNS every 10 minutes and provisions the domain as soon as
+   * the records resolve.
+   *
+   * A duplicate throws a 409. Treat that as "already exists, go read it" —
+   * domain names are globally unique, so a retry after a timeout hits this
+   * for a domain your first call created successfully.
+   */
+  async createDomain(name) {
+    const res = await this.request("POST", "/v2/domains", { name });
+    return res.data;
+  }
+  /** Domain detail plus the DNS records your customer must publish. */
+  async getDomain(id) {
+    const res = await this.request("GET", `/v2/domains/${encodeURIComponent(id)}`);
+    return res.data;
+  }
+  /**
+   * Remove a domain.
+   *
+   * Does NOT remove anything from your customer's DNS zone. Records left
+   * published can allow the domain to be re-verified elsewhere, so clean them
+   * up in your own workflow.
+   */
+  async deleteDomain(id) {
+    await this.request("DELETE", `/v2/domains/${encodeURIComponent(id)}`);
+  }
+  // ── Logs ──
+  async listEmails(params = {}) {
+    return this.request("GET", "/v2/emails", void 0, params);
+  }
+  /** Look up one message by the id POST /v2/emails returned. */
+  async getEmail(messageId) {
+    const res = await this.request("GET", `/v2/emails/${encodeURIComponent(messageId)}`);
+    return res.data;
+  }
+  // ── Suppressions ──
+  async listSuppressions(params = {}) {
+    return this.request("GET", "/v2/suppressions", void 0, params);
+  }
+  /** Limited to 500 per day per account, shared with the dashboard. */
+  async deleteSuppression(email) {
+    return this.request("DELETE", "/v2/suppressions", void 0, { email });
+  }
+  // ── Webhooks ──
+  async listWebhooks(params = {}) {
+    return this.request("GET", "/v2/webhooks", void 0, params);
+  }
+  /**
+   * The signing `secret` is generated by toSend. The API returns it only in
+   * this response (the dashboard can show it later), so store it now.
+   */
+  async createWebhook(params) {
+    const res = await this.request("POST", "/v2/webhooks", params);
+    return res.data;
+  }
+  async updateWebhook(id, params) {
+    const res = await this.request("PUT", `/v2/webhooks/${id}`, params);
+    return res.data;
+  }
+  async deleteWebhook(id) {
+    await this.request("DELETE", `/v2/webhooks/${id}`);
+  }
+  // ── Sending keys ──
+  async listSendingKeys(params = {}) {
+    return this.request("GET", "/v2/api-keys", void 0, params);
+  }
+  /**
+   * Mint a sending key for this team — how you give each client their own key.
+   *
+   * The raw key is returned once and never again. Pass `domain` (a domain id)
+   * to restrict it to one domain; omit it for all domains on the team.
+   * Needs the `api_keys:write` and `emails:send` scopes.
+   */
+  async createSendingKey(name, domain) {
+    const res = await this.request("POST", "/v2/api-keys", { name, domain });
+    return res.data;
+  }
+  async deleteSendingKey(id) {
+    await this.request("DELETE", `/v2/api-keys/${id}`);
+  }
+  // ── Teams ──
+  async listTeams() {
+    const res = await this.request("GET", "/v2/teams");
+    return res.data;
+  }
+  /**
+   * Only the parent account can create teams. `ses_region` defaults to
+   * 'us-east-1' and cannot be changed once the team exists.
+   */
+  async createTeam(name, options = {}) {
+    const body = { name };
+    if (options.ses_region) body.ses_region = options.ses_region;
+    const res = await this.request("POST", "/v2/teams", body);
+    return res.data;
+  }
+  async updateTeam(id, params) {
+    const res = await this.request("PUT", `/v2/teams/${id}`, params);
+    return res.data;
+  }
+  // ── Private ──
+  async request(method, endpoint, body, query) {
+    let url = `${this.baseUrl}${endpoint}`;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0 && value !== "") params.set(key, String(value));
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+    if (this.accountId !== void 0) {
+      headers["X-Account-Id"] = String(this.accountId);
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      const data = await response.json();
+      if (!response.ok) {
+        throw new ToSendError(
+          data.message ?? "Unknown error",
+          response.status,
+          data.errors ?? {},
+          data.error_type
+        );
+      }
+      return data;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof ToSendError) throw error;
+      if (error instanceof Error) {
+        if (error.name === "AbortError") throw new ToSendError("Request timeout", 408);
+        throw new ToSendError(error.message);
+      }
+      throw new ToSendError("Unknown error");
+    }
+  }
+};
 var index_default = ToSend;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ToSend,
+  ToSendAdmin,
   ToSendError
 });
 //# sourceMappingURL=index.js.map