shipmail 0.1.0 → 0.1.19

package/dist/index.d.cts

@@ -17,6 +17,7 @@ type ShipMailConfig = {
     readonly maxRetries?: number | undefined;
     readonly timeout?: number | undefined;
     readonly fetch?: typeof fetch | undefined;
+    readonly defaultHeaders?: Record<string, string> | undefined;
 };
 type PaginationParams = {
     readonly cursor?: string | undefined;
@@ -27,9 +28,10 @@ type PaginatedResponse<T> = {
     readonly pagination: {
         readonly next_cursor: string | null;
         readonly has_more: boolean;
+        readonly limit: number;
     };
 };
-type ErrorType = "validation_error" | "authentication_error" | "authorization_error" | "not_found" | "rate_limit_error" | "conflict" | "internal_error";
+type ErrorType = "validation_error" | "authentication_error" | "authorization_error" | "quota_exceeded" | "not_found" | "rate_limit_error" | "conflict" | "internal_error";
 type ApiErrorBody = {
     readonly error: {
         readonly type: ErrorType;
@@ -46,7 +48,8 @@ type EmailRecipient = {
     readonly address: string;
     readonly name?: string | null | undefined;
 };
-declare const WEBHOOK_EVENT_TYPES: readonly ["message.received", "message.queued", "message.sent", "message.delivered", "message.bounced", "message.complained", "domain.verified", "domain.verification_failed", "domain.degraded"];
+type EmailRecipientInput = EmailRecipient | string;
+declare const WEBHOOK_EVENT_TYPES: readonly ["message.received", "message.sent", "message.delivered", "message.bounced", "message.complained", "domain.verified", "domain.verification_failed", "domain.degraded", "org.reputation_warning", "org.sending_throttled", "org.sending_suspended", "org.reputation_recovered"];
 type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
 type StatusResponse = {
     readonly status: string;
@@ -54,22 +57,39 @@ type StatusResponse = {
     readonly time: string;
     readonly request_id: string;
 };
+declare const DOMAIN_STATUSES: readonly ["pending", "verifying", "verified", "degraded", "failed"];
+type DomainStatus = (typeof DOMAIN_STATUSES)[number];
+declare const MESSAGE_STATUSES: readonly ["queued", "sent", "delivered", "bounced", "complained", "failed"];
+type MessageStatus = (typeof MESSAGE_STATUSES)[number];
+declare const MESSAGE_SOURCES: readonly ["api", "dashboard", "inbound", "smtp"];
+type MessageSource = (typeof MESSAGE_SOURCES)[number];
+declare const WEBHOOK_DELIVERY_STATUSES: readonly ["pending", "delivered", "failed"];
+type WebhookDeliveryStatus = (typeof WEBHOOK_DELIVERY_STATUSES)[number];
+type MethodOptions = {
+    readonly timeout?: number | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly headers?: Record<string, string> | undefined;
+    readonly idempotencyKey?: string | undefined;
+};
 
 type Domain = {
+    readonly object: "domain";
     readonly id: string;
     readonly name: string;
-    readonly status: string;
+    readonly status: DomainStatus;
+    readonly managed_by: "external" | "namecom";
     readonly dns_provider: string | null;
-    readonly ownership_verified: boolean;
     readonly mx_verified: boolean;
     readonly spf_verified: boolean;
     readonly dkim_verified: boolean;
     readonly dmarc_verified: boolean;
-    readonly ses_verified: boolean;
+    readonly dmarc_managed_externally: boolean;
+    readonly outbound_verified: boolean;
     readonly catch_all_mailbox_id: string | null;
     readonly verified_at: string | null;
     readonly created_at: string;
     readonly updated_at: string;
+    readonly registration?: DomainRegistrationInfo | undefined;
 };
 type CreateDomainParams = {
     readonly name: string;
@@ -81,35 +101,87 @@ type ListDomainsParams = PaginationParams;
 type DomainVerificationResult = {
     readonly all_verified: boolean;
     readonly records: {
-        readonly ownership: boolean;
         readonly mx: boolean;
         readonly spf: boolean;
         readonly dkim: boolean;
         readonly dmarc: boolean;
     };
-    readonly ses_verified: boolean;
-    readonly ses_error: boolean;
+    readonly outbound_verified: boolean;
+    readonly outbound_error: boolean;
     readonly existing_spf: string | null;
     readonly suggested_spf: string | null;
     readonly conflicting_mx: readonly string[];
+    readonly dmarc_valid: boolean;
+    readonly dmarc_exact_match: boolean;
+    readonly dmarc_record_value: string | null;
+    readonly dmarc_managed_externally: boolean;
+};
+type DomainSearchResult = {
+    readonly domain_name: string;
+    readonly available: boolean;
+    readonly purchase_price: number | null;
+    readonly renewal_price: number | null;
+    readonly currency: string;
+    readonly premium: boolean;
+};
+type SearchDomainsParams = {
+    readonly keyword: string;
+};
+type RegistrationContact = {
+    readonly first_name: string;
+    readonly last_name: string;
+    readonly address1: string;
+    readonly address2?: string | undefined;
+    readonly city: string;
+    readonly state?: string | undefined;
+    readonly zip: string;
+    readonly country: string;
+    readonly phone: string;
+    readonly email: string;
+};
+type RegisterDomainParams = {
+    readonly name: string;
+    readonly years?: number | undefined;
+    readonly contact: RegistrationContact;
+};
+type DomainRegistrationInfo = {
+    readonly expires_at: string;
+    readonly auto_renew: boolean;
+    readonly renewal_price: number;
+    readonly privacy_enabled: boolean;
+    readonly currency: string;
+    readonly registered_at: string;
 };
 
 declare class Domains extends ApiResource {
-    create(params: CreateDomainParams): Promise<Domain>;
-    list(params?: ListDomainsParams): Promise<PaginatedResponse<Domain>>;
+    create(params: CreateDomainParams, options?: MethodOptions): Promise<Domain>;
+    list(params?: ListDomainsParams, options?: MethodOptions): Promise<PaginatedResponse<Domain>>;
     listAutoPaginating(params?: Omit<ListDomainsParams, "cursor">): Page<Domain>;
-    get(id: string): Promise<Domain>;
-    update(id: string, params: UpdateDomainParams): Promise<Domain>;
-    delete(id: string): Promise<void>;
-    verify(id: string): Promise<DomainVerificationResult>;
+    get(id: string, options?: MethodOptions): Promise<Domain>;
+    update(id: string, params: UpdateDomainParams, options?: MethodOptions): Promise<Domain>;
+    delete(id: string, options?: MethodOptions): Promise<void>;
+    verify(id: string, options?: MethodOptions): Promise<DomainVerificationResult>;
+    search(params: SearchDomainsParams, options?: MethodOptions): Promise<{
+        readonly results: readonly DomainSearchResult[];
+    }>;
+    register(params: RegisterDomainParams, options?: MethodOptions): Promise<Domain>;
 }
 
+type AutoReply = {
+    readonly enabled: boolean;
+    readonly subject: string | null;
+    readonly body: string | null;
+    readonly from_date: string | null;
+    readonly to_date: string | null;
+};
 type Mailbox = {
+    readonly object: "mailbox";
     readonly id: string;
     readonly domain_id: string;
     readonly address: string;
     readonly display_name: string | null;
-    readonly avatar_url: string | null;
+    readonly suspended_at: string | null;
+    readonly auto_reply: AutoReply;
     readonly created_at: string;
     readonly updated_at: string;
 };
@@ -124,50 +196,109 @@ type UpdateMailboxParams = {
 type ListMailboxesParams = PaginationParams & {
     readonly domain_id?: string | undefined;
 };
-type UploadAvatarResponse = {
-    readonly avatar_url: string;
+type UpdateAutoReplyParams = {
+    readonly enabled: boolean;
+    readonly subject?: string | null | undefined;
+    readonly body?: string | null | undefined;
+    readonly from_date?: string | null | undefined;
+    readonly to_date?: string | null | undefined;
 };
 
 declare class Mailboxes extends ApiResource {
-    create(params: CreateMailboxParams): Promise<Mailbox>;
-    list(params?: ListMailboxesParams): Promise<PaginatedResponse<Mailbox>>;
+    create(params: CreateMailboxParams, options?: MethodOptions): Promise<Mailbox>;
+    list(params?: ListMailboxesParams, options?: MethodOptions): Promise<PaginatedResponse<Mailbox>>;
     listAutoPaginating(params?: Omit<ListMailboxesParams, "cursor">): Page<Mailbox>;
-    get(id: string): Promise<Mailbox>;
-    update(id: string, params: UpdateMailboxParams): Promise<Mailbox>;
-    delete(id: string): Promise<void>;
-    uploadAvatar(id: string, data: ArrayBuffer, contentType: string): Promise<UploadAvatarResponse>;
-    deleteAvatar(id: string): Promise<void>;
+    get(id: string, options?: MethodOptions): Promise<Mailbox>;
+    update(id: string, params: UpdateMailboxParams, options?: MethodOptions): Promise<Mailbox>;
+    delete(id: string, options?: MethodOptions): Promise<void>;
+    updateAutoReply(id: string, params: UpdateAutoReplyParams, options?: MethodOptions): Promise<Mailbox>;
 }
 
 type Message = {
+    readonly object: "message";
     readonly id: string;
     readonly mailbox_id: string;
     readonly thread_id: string | null;
-    readonly source: string;
-    readonly status: string;
+    readonly subject: string | null;
+    readonly from_address: string | null;
+    readonly to_addresses: readonly {
+        readonly address: string;
+        readonly name?: string | null;
+    }[] | null;
+    readonly cc_addresses: readonly {
+        readonly address: string;
+        readonly name?: string | null;
+    }[] | null;
+    readonly bcc_addresses: readonly {
+        readonly address: string;
+        readonly name?: string | null;
+    }[] | null;
+    readonly attachments: readonly {
+        readonly filename: string;
+        readonly size: number;
+        readonly content_type: string;
+    }[] | null;
+    readonly source: MessageSource;
+    readonly status: MessageStatus;
     readonly created_at: string;
     readonly updated_at: string;
 };
+type Attachment = {
+    readonly filename: string;
+    readonly content: string;
+    readonly content_type?: string | undefined;
+};
 type SendMessageParams = {
-    readonly mailbox_id: string;
-    readonly to: readonly EmailRecipient[];
-    readonly cc?: readonly EmailRecipient[] | undefined;
-    readonly bcc?: readonly EmailRecipient[] | undefined;
-    readonly reply_to?: EmailRecipient | undefined;
+    readonly mailbox_id?: string | undefined;
+    readonly from?: string | undefined;
+    readonly to: readonly EmailRecipientInput[];
+    readonly cc?: readonly EmailRecipientInput[] | undefined;
+    readonly bcc?: readonly EmailRecipientInput[] | undefined;
+    readonly reply_to?: EmailRecipientInput | undefined;
     readonly subject: string;
-    readonly body_html?: string | undefined;
-    readonly body_text?: string | undefined;
+    readonly html?: string | undefined;
+    readonly text?: string | undefined;
     readonly in_reply_to?: string | undefined;
     readonly references?: readonly string[] | undefined;
+    readonly attachments?: readonly Attachment[] | undefined;
+};
+type ListMessagesParams = PaginationParams & {
+    readonly mailbox_id: string;
+};
+type ReplyToMessageParams = {
+    readonly html?: string | undefined;
+    readonly text?: string | undefined;
+    readonly to: readonly EmailRecipientInput[];
+    readonly cc?: readonly EmailRecipientInput[] | undefined;
 };
 
 declare class Messages extends ApiResource {
-    send(params: SendMessageParams): Promise<Message>;
-    get(id: string): Promise<Message>;
+    send(params: SendMessageParams, options?: MethodOptions): Promise<Message>;
+    list(params: ListMessagesParams, options?: MethodOptions): Promise<PaginatedResponse<Message>>;
+    listAutoPaginating(params: Omit<ListMessagesParams, "cursor">): Page<Message>;
+    get(id: string, options?: MethodOptions): Promise<Message>;
+    reply(id: string, params: ReplyToMessageParams, options?: MethodOptions): Promise<Message>;
 }
 
 declare class Status extends ApiResource {
-    get(): Promise<StatusResponse>;
+    get(options?: MethodOptions): Promise<StatusResponse>;
+}
+
+type Suppression = {
+    readonly object: "suppression";
+    readonly email_address: string;
+    readonly reason: string;
+    readonly created_at: string;
+};
+type ListSuppressionsParams = {
+    readonly cursor?: string;
+    readonly limit?: number;
+};
+
+declare class Suppressions extends ApiResource {
+    list(params?: ListSuppressionsParams, options?: MethodOptions): Promise<PaginatedResponse<Suppression>>;
+    listAutoPaginating(params?: Omit<ListSuppressionsParams, "cursor">): Page<Suppression>;
+    remove(email: string, options?: MethodOptions): Promise<void>;
 }
 
 type ListThreadsParams = PaginationParams & {
@@ -175,20 +306,21 @@ type ListThreadsParams = PaginationParams & {
 };
 type GetThreadParams = PaginationParams;
 type ReplyToThreadParams = {
-    readonly body_html?: string | undefined;
-    readonly body_text?: string | undefined;
-    readonly to?: readonly EmailRecipient[] | undefined;
-    readonly cc?: readonly EmailRecipient[] | undefined;
+    readonly html?: string | undefined;
+    readonly text?: string | undefined;
+    readonly to?: readonly EmailRecipientInput[] | undefined;
+    readonly cc?: readonly EmailRecipientInput[] | undefined;
 };
 
 declare class Threads extends ApiResource {
-    list(params: ListThreadsParams): Promise<PaginatedResponse<Message>>;
+    list(params: ListThreadsParams, options?: MethodOptions): Promise<PaginatedResponse<Message>>;
     listAutoPaginating(params: Omit<ListThreadsParams, "cursor">): Page<Message>;
-    get(id: string, params?: GetThreadParams): Promise<PaginatedResponse<Message>>;
-    reply(id: string, params: ReplyToThreadParams): Promise<Message>;
+    get(id: string, params?: GetThreadParams, options?: MethodOptions): Promise<PaginatedResponse<Message>>;
+    reply(id: string, params: ReplyToThreadParams, options?: MethodOptions): Promise<Message>;
 }
 
 type Webhook = {
+    readonly object: "webhook";
     readonly id: string;
     readonly url: string;
     readonly events: readonly string[];
@@ -220,10 +352,11 @@ type TestWebhookResponse = {
     readonly event_id: string;
 };
 type WebhookDelivery = {
+    readonly object: "webhook_delivery";
     readonly id: string;
     readonly event_id: string;
     readonly event_type: string;
-    readonly status: string;
+    readonly status: WebhookDeliveryStatus;
     readonly attempts: number;
     readonly last_status_code: number | null;
     readonly last_error: string | null;
@@ -242,15 +375,15 @@ type WebhookEvent<T = unknown> = {
 };
 
 declare class Webhooks extends ApiResource {
-    create(params: CreateWebhookParams): Promise<WebhookWithSecret>;
-    list(params?: ListWebhooksParams): Promise<PaginatedResponse<Webhook>>;
+    create(params: CreateWebhookParams, options?: MethodOptions): Promise<WebhookWithSecret>;
+    list(params?: ListWebhooksParams, options?: MethodOptions): Promise<PaginatedResponse<Webhook>>;
     listAutoPaginating(params?: Omit<ListWebhooksParams, "cursor">): Page<Webhook>;
-    get(id: string): Promise<Webhook>;
-    update(id: string, params: UpdateWebhookParams): Promise<Webhook>;
-    delete(id: string): Promise<void>;
-    rotateSecret(id: string): Promise<RotateSecretResponse>;
-    test(id: string): Promise<TestWebhookResponse>;
-    listDeliveries(id: string, params?: ListDeliveriesParams): Promise<PaginatedResponse<WebhookDelivery>>;
+    get(id: string, options?: MethodOptions): Promise<Webhook>;
+    update(id: string, params: UpdateWebhookParams, options?: MethodOptions): Promise<Webhook>;
+    delete(id: string, options?: MethodOptions): Promise<void>;
+    rotateSecret(id: string, options?: MethodOptions): Promise<RotateSecretResponse>;
+    test(id: string, options?: MethodOptions): Promise<TestWebhookResponse>;
+    listDeliveries(id: string, params?: ListDeliveriesParams, options?: MethodOptions): Promise<PaginatedResponse<WebhookDelivery>>;
     listDeliveriesAutoPaginating(id: string, params?: Omit<ListDeliveriesParams, "cursor">): Page<WebhookDelivery>;
 }
 
@@ -261,19 +394,29 @@ type RequestOptions = {
     readonly query?: Record<string, string | number | boolean | undefined> | undefined;
     readonly rawBody?: ArrayBuffer | undefined;
     readonly contentType?: string | undefined;
+    readonly methodOptions?: MethodOptions | undefined;
 };
+/**
+ * Client for the ShipMail API. Handles authentication, retries, and resource access.
+ */
 declare class ShipMailClient {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly maxRetries;
     private readonly timeout;
     private readonly fetchFn;
+    private readonly defaultHeaders;
     readonly domains: Domains;
     readonly mailboxes: Mailboxes;
     readonly messages: Messages;
+    readonly suppressions: Suppressions;
     readonly threads: Threads;
     readonly webhooks: Webhooks;
     readonly status: Status;
+    /**
+     * Create a new ShipMail client.
+     * @param config - API key string or full configuration object.
+     */
     constructor(config: string | ShipMailConfig);
     request<T>(options: RequestOptions): Promise<T>;
     private buildUrl;
@@ -310,6 +453,9 @@ declare class ValidationError extends ShipMailError {
         }[] | undefined;
     });
 }
+declare class QuotaExceededError extends ShipMailError {
+    constructor(message: string, requestId?: string);
+}
 declare class NotFoundError extends ShipMailError {
     constructor(message: string, requestId?: string);
 }
@@ -339,8 +485,12 @@ type WebhookHeaders = {
     readonly "x-shipmail-event-id"?: string;
     readonly [key: string]: string | undefined;
 };
+/**
+ * Verify an incoming webhook signature. Throws `WebhookVerificationError` on failure.
+ * Returns the parsed webhook event on success.
+ */
 declare function verifyWebhook(body: string, headers: WebhookHeaders | Headers, secret: string, options?: {
     readonly toleranceInSeconds?: number | undefined;
-}): WebhookEvent;
+}): Promise<WebhookEvent>;
 
-export { type ApiErrorBody, AuthenticationError, AuthorizationError, ConflictError, ConnectionError, type CreateDomainParams, type CreateMailboxParams, type CreateWebhookParams, type Domain, type DomainVerificationResult, type EmailRecipient, type ErrorType, type GetThreadParams, InternalServerError, type ListDeliveriesParams, type ListDomainsParams, type ListMailboxesParams, type ListThreadsParams, type ListWebhooksParams, type Message, NotFoundError, Page, type PaginatedResponse, type PaginationParams, RateLimitError, type ReplyToThreadParams, type RotateSecretResponse, type SendMessageParams, ShipMailClient, type ShipMailConfig, ShipMailError, type StatusResponse, type TestWebhookResponse, type UpdateDomainParams, type UpdateMailboxParams, type UpdateWebhookParams, type UploadAvatarResponse, ValidationError, WEBHOOK_EVENT_TYPES, type Webhook, type WebhookDelivery, type WebhookEvent, type WebhookEventType, WebhookVerificationError, type WebhookWithSecret, ShipMailClient as default, verifyWebhook };
+export { type ApiErrorBody, AuthenticationError, AuthorizationError, ConflictError, ConnectionError, type CreateDomainParams, type CreateMailboxParams, type CreateWebhookParams, DOMAIN_STATUSES, type Domain, type DomainRegistrationInfo, type DomainSearchResult, type DomainStatus, type DomainVerificationResult, type EmailRecipient, type EmailRecipientInput, type ErrorType, type GetThreadParams, InternalServerError, type ListDeliveriesParams, type ListDomainsParams, type ListMailboxesParams, type ListMessagesParams, type ListSuppressionsParams, type ListThreadsParams, type ListWebhooksParams, MESSAGE_SOURCES, MESSAGE_STATUSES, type Mailbox, type Message, type MessageSource, type MessageStatus, type MethodOptions, NotFoundError, Page, type PaginatedResponse, type PaginationParams, QuotaExceededError, RateLimitError, type RegisterDomainParams, type RegistrationContact, type ReplyToMessageParams, type ReplyToThreadParams, type RequestOptions, type RotateSecretResponse, type SearchDomainsParams, type SendMessageParams, ShipMailClient, type ShipMailConfig, ShipMailError, type StatusResponse, type Suppression, type TestWebhookResponse, type UpdateAutoReplyParams, type UpdateDomainParams, type UpdateMailboxParams, type UpdateWebhookParams, ValidationError, WEBHOOK_DELIVERY_STATUSES, WEBHOOK_EVENT_TYPES, type Webhook, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEvent, type WebhookEventType, WebhookVerificationError, type WebhookWithSecret, ShipMailClient as default, verifyWebhook };