tosend 1.0.1 → 1.1.0

package/README.md

@@ -110,15 +110,46 @@ response.results.forEach((result) => {
 ```typescript
 const info = await tosend.getAccountInfo();
 
-console.log(info.account.title);
-console.log(info.account.emails_usage_this_month);
-console.log(info.account.emails_sent_last_24hrs);
+console.log(info.account.status);          // 'active'
+console.log(info.account.credit_balance);  // null = no credit limit
+console.log(info.account.limit_per_second);
 
 info.domains.forEach((domain) => {
   console.log(domain.domain_name, domain.verification_status);
 });
 ```
 
+## Admin API
+
+`ToSendAdmin` is a separate client for the [Admin API](https://tosend.com/docs/api/admin-api). It takes an admin key (`tsend_admin_...`) and refuses a sending key at construction. Each call needs the matching [scope](https://tosend.com/docs/api/admin-api#scopes) on the key.
+
+```typescript
+import { ToSendAdmin } from 'tosend';
+
+const admin = new ToSendAdmin(process.env.TOSEND_ADMIN_KEY!);
+
+// Act on one of your client teams (sends X-Account-Id)
+const client = admin.forAccount(4203);
+
+const domain = await client.createDomain('client.example.com');
+const detail = await client.getDomain(domain.id);
+console.log(detail.dns_records.dkim); // show these records to your client
+
+// Needs api_keys:write and emails:send
+const key = await client.createSendingKey('Client: Acme Corp');
+console.log(key.api_key); // returned once, store it now
+
+// Needs emails:send
+await client.send({
+  from: { email: 'hello@client.example.com' },
+  to: [{ email: 'user@example.com' }],
+  subject: 'Hi',
+  html: '<p>Hello</p>',
+});
+```
+
+Also available: `getInfo` (checks the key and lists its scopes), `listDomains`, `deleteDomain`, `listEmails`, `getEmail`, `listSuppressions`, `deleteSuppression`, `listWebhooks`, `createWebhook`, `updateWebhook`, `deleteWebhook`, `listSendingKeys`, `deleteSendingKey`, `listTeams`, `createTeam`, `updateTeam` and `batch`. List methods take `page` and `per_page` and return `{ data, total, page, per_page }`.
+
 ## Configuration
 
 ### Simple (API key only)

package/dist/index.d.mts

@@ -45,23 +45,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;
+        /** Fraction between 0 and 1, not a percentage */
+        bounce_rate: number;
+        /** Fraction between 0 and 1, not a percentage */
+        complaint_rate: number;
+        ses_status: string;
     };
     domains: Domain[];
 }
@@ -69,8 +82,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 +113,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 +185,318 @@ 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;
+        bounce_rate: number;
+        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;
+}
+interface TeamList {
+    account: {
+        id: number;
+        name: string | null;
+        status: string;
+        credit_balance: number | null;
+    };
+    teams: Array<{
+        id: number;
+        name: string | null;
+        status: string;
+    }>;
+    /** 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. */
+    createTeam(name: string): Promise<{
+        id: number;
+        name: string;
+        status: string;
+    }>;
+    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 Suppression, type SuppressionReactivation, type TeamList, ToSend, ToSendAdmin, type ToSendConfig, ToSendError, type ToSendErrorResponse, type ValidationErrors, type Webhook, type WebhookEvent, ToSend as default };