mailchannels-sdk 0.8.0-0 → 0.8.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Yizack Rangel
+Copyright (c) 2026 MailChannels
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -4,7 +4,6 @@
 
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
-[![codecov][codecov-coverage-src]][codecov-coverage-href]
 
 > Built and tested against Email API `0.21.1`
 
@@ -109,7 +108,7 @@ This package includes a local MailChannels simulator you can run via the CLI. It
 
 | API         | Source                                                                                                         |
 | ----------- | -------------------------------------------------------------------------------------------------------------- |
-| Email API   | [`src/simulator/email-api.mjs`](https://github.com/Yizack/mailchannels/blob/main/src/simulator/email-api.mjs)  |
+| Email API   | [`src/simulator/email-api.mjs`](https://bitbucket.org/mailchannels/mailchannels-email-api-sdk-js/src/main/src/simulator/email-api.mjs)  |
 
 > [!IMPORTANT]
 > The simulator approximates the MailChannels service for local development and testing. It is not a production implementation and may differ from the live service.
@@ -212,7 +211,7 @@ pnpm parity:fixtures
 pnpm simulate
 
 # Run a playground script
-npx jiti playground/emails/send.ts
+pnpx jiti playground/emails/send.ts
 
 # Release new version
 pnpm release
@@ -226,6 +225,3 @@ pnpm release
 
 [npm-downloads-src]: https://img.shields.io/npm/dm/mailchannels-sdk.svg?style=flat&colorA=070a30&colorB=35a047
 [npm-downloads-href]: https://npmjs.com/package/mailchannels-sdk
-
-[codecov-coverage-src]: https://img.shields.io/codecov/c/github/yizack/mailchannels?style=flat&colorA=070a30&token=HTSBRHSJ5M
-[codecov-coverage-href]: https://codecov.io/gh/Yizack/mailchannels

package/dist/mailchannels.d.mts

@@ -20,13 +20,24 @@ interface MailChannelsClientOptions {
    * @default false
    */
   retry?: number | false;
+  /**
+   * Request timeout in milliseconds.
+   * Set to `false` or `0` to disable timeout handling.
+   * @default 120000
+   */
+  timeout?: number | false;
+  /**
+   * Abort signal applied to requests made by the client.
+   */
+  signal?: AbortSignal;
 }
 declare class MailChannelsClient {
   #private;
   private static readonly DEFAULT_BASE_URL;
+  private static readonly DEFAULT_TIMEOUT;
   private readonly options;
   constructor(key: string, options?: MailChannelsClientOptions);
-  protected _fetch<T>(path: string, options?: FetchOptions<"json">): Promise<T>;
+  protected _fetch<T>(path: string, options: FetchOptions<"json">): Promise<T>;
   post<T>(path: string, options?: Omit<FetchOptions<"json">, "method">): Promise<T>;
   get<T>(path: string, options?: Omit<FetchOptions<"json">, "method">): Promise<T>;
   delete<T>(path: string, options?: Omit<FetchOptions<"json">, "method">): Promise<T>;
@@ -96,7 +107,15 @@ interface EmailsSendAttachment {
   /**
    * The MIME type of the attachment.
    */
-  type: string;
+  type?: string;
+  /**
+   * The `Content-ID` header value for inline attachments, referenced from HTML with `cid:`.
+   */
+  contentId?: string;
+  /**
+   * The `Content-Disposition` header value for the attachment.
+   */
+  disposition?: "attachment" | "inline";
 }
 interface EmailsSendTracking {
   /**
@@ -211,7 +230,7 @@ interface EmailsSendOptionsBase {
   /**
    * An array of attachments to be sent with the email.
    */
-  attachments?: EmailsSendAttachment[];
+  attachments?: (EmailsSendAttachment | Promise<EmailsSendAttachment>)[];
   /**
    * The campaign identifier. If specified, this ID will be included in all relevant webhooks. It can be up to 48 UTF-8 characters long and must not contain spaces.
    */
@@ -438,7 +457,7 @@ type EmailsSendResponse = DataResponse<{
     status: "sent" | "failed";
   }[];
 }>;
-type EmailsSendAsyncResponse = DataResponse<{
+type EmailsQueueResponse = DataResponse<{
   /**
    * ISO 8601 timestamp when the request was queued for processing.
    */
@@ -448,6 +467,7 @@ type EmailsSendAsyncResponse = DataResponse<{
    */
   requestId: string;
 }>;
+type EmailsSendAsyncResponse = EmailsQueueResponse;
 declare class Emails {
   protected mailchannels: MailChannelsClient;
   constructor(mailchannels: MailChannelsClient);
@@ -478,7 +498,7 @@ declare class Emails {
    * @example
    * ```ts
    * const mailchannels = new MailChannels('your-api-key')
-   * const { data, error } = await mailchannels.emails.sendAsync({
+   * const { data, error } = await mailchannels.emails.queue({
    *   to: 'to@example.com',
    *   from: 'from@example.com',
    *   subject: 'Test',
@@ -486,7 +506,11 @@ declare class Emails {
    * })
    * ```
    */
-  sendAsync(options: EmailsSendOptions): Promise<EmailsSendAsyncResponse>;
+  queue(options: EmailsSendOptions): Promise<EmailsQueueResponse>;
+  /**
+   * @deprecated Use `queue` instead.
+   */
+  sendAsync(options: EmailsSendOptions): Promise<EmailsQueueResponse>;
 }
 interface DomainsDkimCreateOptions {
   /**
@@ -578,10 +602,6 @@ interface DomainsCheckOptions {
    * 6. If `selector` is present and `domain` is not, the domain will be taken from the domain field of the request.
    */
   dkim?: DomainsCheck[] | DomainsCheck;
-  /**
-   * Domain used for sending emails. If `dkim` settings are not provided, or `dkim` settings are provided with no `domain`, the stored dkim settings for this domain will be used.
-   */
-  domain: string;
   /**
    * Used exclusively for [Domain Lockdown](https://support.mailchannels.com/hc/en-us/articles/16918954360845-Secure-your-domain-name-against-spoofing-with-Domain-Lockdown) verification. If you're not using senderid to associate your domain with your account, you can disregard this field. The corresponding value is included in the `X-MailChannels-SenderId` header of emails sent via MailChannels.
    */
@@ -676,7 +696,7 @@ interface DomainsDkimListOptions {
 }
 type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 type DomainsDkimListResponse = DataResponse<Optional<DomainsDkimKey, "dnsRecords">[]>;
-interface DomainsDkimUpdateOptions {
+interface DomainsDkimUpdateStatusOptions {
   /**
    * Selector of the DKIM key pair to update. Must be a maximum of 63 characters.
    */
@@ -707,22 +727,22 @@ declare class Domains {
   constructor(mailchannels: MailChannelsClient);
   /**
    * Validates a domain's email authentication setup by retrieving its DKIM, SPF, and Domain Lockdown status. This endpoint checks whether the domain is properly configured for secure email delivery.
+   * @param domain - Domain used for sending emails. If `dkim` settings are not provided, or `dkim` settings are provided with no `domain`, the stored dkim settings for this domain will be used.
    * @param options - The domain options to check.
    * @example
    * ```ts
    * const mailchannels = new MailChannels('your-api-key')
-   * const { data, error } = await mailchannels.domains.check({
+   * const { data, error } = await mailchannels.domains.check('example.com', {
    *   dkim: [{
    *     domain: 'example.com',
    *     privateKey: 'your-private-key',
    *     selector: 'mailchannels'
    *   }],
-   *   domain: 'example.com',
    *   senderId: 'sender-id'
    * })
    * ```
    */
-  check(options: DomainsCheckOptions): Promise<DomainsCheckResponse>;
+  check(domain: string, options?: DomainsCheckOptions): Promise<DomainsCheckResponse>;
 }
 declare class DomainsDkim {
   private mailchannels;
@@ -760,12 +780,12 @@ declare class DomainsDkim {
    * @example
    * ```ts
    * const mailchannels = new MailChannels('your-api-key')
-   * const { success, error } = await mailchannels.domains.dkim.update('example.com', {
+   * const { success, error } = await mailchannels.domains.dkim.updateStatus('example.com', {
    *   selector: 'mailchannels',
    *   status: 'retired'
    * })
    */
-  update(domain: string, options: DomainsDkimUpdateOptions): Promise<SuccessResponse>;
+  updateStatus(domain: string, options: DomainsDkimUpdateStatusOptions): Promise<SuccessResponse>;
   /**
    * Rotate an active DKIM key pair. Mark the original key as `rotated`, and create a new key pair with the required new key selector, reusing the same algorithm and key length. The rotated key remains valid for signing for a 3-day grace period, and is automatically changed to `retired` 2 weeks after rotation. Publish the new key to its DNS TXT record before rotated key expires for signing as emails sent with an unpublished key will fail DKIM validation by receiving providers. After the grace period, only the new key is valid for signing if published.
    * @param domain - The domain the DKIM key belongs to.
@@ -832,6 +852,78 @@ type WebhooksValidateResponse = DataResponse<{
     } | null;
   }[];
 }>;
+type WebhookEventType = "processed" | "delivered" | "open" | "click" | "hard-bounced" | "soft-bounced" | "dropped" | "complained" | "unsubscribed" | "test";
+interface WebhookEventBase<T extends WebhookEventType> {
+  /**
+   * The sender's email address
+   */
+  email?: string;
+  /**
+   * The MailChannels account ID that generated the webhook.
+   * If the message was sent by a sub-account, this field contains the sub-account handle.
+   */
+  customerHandle: string;
+  /**
+   * The Unix timestamp (in seconds) when the event occurred; the timezone is always UTC
+   */
+  timestamp: number;
+  /**
+   * The Message-Id of the message that generated the event
+   */
+  smtpId?: string;
+  /**
+   * The type of event that occurred
+   */
+  event: T;
+  /**
+   * A unique identifier generated to track the original HTTP request
+   */
+  requestId?: string;
+  /**
+   * The campaign identifier for the message that generated the event
+   */
+  campaignId?: string;
+  /**
+   * The recipients of the message
+   */
+  recipients?: string[];
+}
+interface WebhookEventProcessed extends WebhookEventBase<"processed"> {}
+interface WebhookEventDelivered extends WebhookEventBase<"delivered"> {}
+interface WebhookEventWithTracking {
+  /**
+   * The User-Agent header given when the recipient opened the message
+   */
+  userAgent?: string;
+  /**
+   * The IP address of the host that made the HTTP request
+   */
+  ip?: string;
+}
+interface WebhookEventOpen extends WebhookEventBase<"open">, WebhookEventWithTracking {}
+interface WebhookEventClick extends WebhookEventBase<"click">, WebhookEventWithTracking {
+  /**
+   * The URL that was clicked by the recipient
+   */
+  url?: string;
+}
+interface WebhookEventWithStatus {
+  /**
+   * The SMTP status code that caused the bounce
+   */
+  status?: string;
+  /**
+   * A human-readable explanation of why the message hard-bounced
+   */
+  reason?: string;
+}
+interface WebhookEventHardBounced extends WebhookEventBase<"hard-bounced">, WebhookEventWithStatus {}
+interface WebhookEventSoftBounced extends WebhookEventBase<"soft-bounced">, WebhookEventWithStatus {}
+interface WebhookEventDropped extends WebhookEventBase<"dropped">, WebhookEventWithStatus {}
+interface WebhookEventComplained extends WebhookEventBase<"complained"> {}
+interface WebhookEventUnsubscribed extends WebhookEventBase<"unsubscribed"> {}
+interface WebhookEventTest extends Omit<WebhookEventBase<"test">, "recipients" | "campaignId"> {}
+type WebhookEvent = WebhookEventProcessed | WebhookEventDelivered | WebhookEventOpen | WebhookEventClick | WebhookEventHardBounced | WebhookEventSoftBounced | WebhookEventDropped | WebhookEventComplained | WebhookEventUnsubscribed | WebhookEventTest;
 interface WebhooksVerifyOptions {
   /**
    * The raw body of the incoming webhook request as a string. This should be the exact payload received from the webhook, without any modifications or parsing, to ensure accurate signature verification.
@@ -855,6 +947,7 @@ interface WebhooksVerifyOptions {
    */
   cache?: boolean;
 }
+type WebhooksVerifyResponse = DataResponse<WebhookEvent[]>;
 type WebhooksBatchStatus = "1xx" | "2xx" | "3xx" | "4xx" | "5xx" | "no_response";
 type WebhooksBatchResponseStatus = "1xx_response" | "2xx_response" | "3xx_response" | "4xx_response" | "5xx_response" | "no_response";
 interface WebhooksBatchesOptions {
@@ -963,10 +1056,10 @@ declare class Webhooks {
    * @example
    * ```ts
    * const mailchannels = new MailChannels('your-api-key')
-   * const { success, error } = mailchannels.webhooks.enroll('https://example.com/api/webhooks/mailchannels')
+   * const { success, error } = await mailchannels.webhooks.create('https://example.com/api/webhooks/mailchannels')
    * ```
    */
-  enroll(endpoint: string): Promise<SuccessResponse>;
+  create(endpoint: string): Promise<SuccessResponse>;
   /**
    * Retrieves all registered webhook endpoints associated with the customer.
    * @example
@@ -981,10 +1074,10 @@ declare class Webhooks {
    * @example
    * ```ts
    * const mailchannels = new MailChannels('your-api-key')
-   * const { success, error } = await mailchannels.webhooks.delete()
+   * const { success, error } = await mailchannels.webhooks.deleteAll()
    * ```
    */
-  delete(): Promise<SuccessResponse>;
+  deleteAll(): Promise<SuccessResponse>;
   /**
    * Retrieves the public key used to verify signatures on incoming webhook payloads.
    * @param id - The ID of the key.
@@ -1010,20 +1103,20 @@ declare class Webhooks {
    * @param options - The options for verifying the webhook.
    * @example
    * ```ts
-   * const isValid = await Webhooks.verify({ payload: rawBody, headers })
+   * const { data, error } = await Webhooks.verify({ payload: rawBody, headers })
    * ```
    */
-  static verify(options: WebhooksVerifyOptions): Promise<boolean>;
+  static verify(options: WebhooksVerifyOptions): Promise<WebhooksVerifyResponse>;
   /**
    * Verifies the authenticity of incoming webhook requests by validating their signatures using the provided options.
    * @param options - The options for verifying the webhook.
    * @example
    * ```ts
    * const mailchannels = new MailChannels('your-api-key')
-   * const isValid = await mailchannels.webhooks.verify({ payload: rawBody, headers })
+   * const { data, error } = await mailchannels.webhooks.verify({ payload: rawBody, headers })
    * ```
    */
-  verify(options: WebhooksVerifyOptions): Promise<boolean>;
+  verify(options: WebhooksVerifyOptions): Promise<WebhooksVerifyResponse>;
   /**
    * Retrieves paged webhook batches associated with the customer. The time range specified by `createdAfter` and `createdBefore` must not exceed 31 days. If neither is specified, the default time range is the last 3 days.
    * @param options - The options for listing webhook batches.
@@ -1664,79 +1757,13 @@ declare class Suppressions {
    */
   list(options?: SuppressionsListOptions): Promise<SuppressionsListResponse>;
 }
-type WebhookEventType = "processed" | "delivered" | "open" | "click" | "hard-bounced" | "soft-bounced" | "dropped" | "complained" | "unsubscribed" | "test";
-interface WebhookEventBase<T extends WebhookEventType> {
-  /**
-   * The sender's email address
-   */
-  email?: string;
-  /**
-   * The MailChannels account ID that generated the webhook.
-   * If the message was sent by a sub-account, this field contains the sub-account handle.
-   */
-  customer_handle: string;
-  /**
-   * The Unix timestamp (in seconds) when the event occurred; the timezone is always UTC
-   */
-  timestamp: number;
-  /**
-   * The Message-Id of the message that generated the event
-   */
-  smtp_id?: string;
-  /**
-   * The type of event that occurred
-   */
-  event: T;
-  /**
-   * A unique identifier generated to track the original HTTP request
-   */
-  request_id?: string;
-  /**
-   * The campaign identifier for the message that generated the event
-   */
-  campaign_id?: string;
-  /**
-   * The recipients of the message
-   */
-  recipients?: string[];
-}
-interface WebhookEventProcessed extends WebhookEventBase<"processed"> {}
-interface WebhookEventDelivered extends WebhookEventBase<"delivered"> {}
-interface WebhookEventWithTracking {
-  /**
-   * The User-Agent header given when the recipient opened the message
-   */
-  user_agent?: string;
-  /**
-   * The IP address of the host that made the HTTP request
-   */
-  ip?: string;
+type AttachmentOptions = Omit<EmailsSendAttachment, "content">;
+declare class Attachment {
+  static fromBytes(data: ArrayBuffer | Uint8Array, options: AttachmentOptions): EmailsSendAttachment;
+  static fromFile(path: string | URL, options?: Partial<AttachmentOptions>): Promise<EmailsSendAttachment>;
+  static fromUrl(url: string, options?: Partial<AttachmentOptions>): Promise<EmailsSendAttachment>;
+  static inlineFile(path: string | URL, options?: Partial<Omit<AttachmentOptions, "disposition">>): Promise<EmailsSendAttachment>;
 }
-interface WebhookEventOpen extends WebhookEventBase<"open">, WebhookEventWithTracking {}
-interface WebhookEventClick extends WebhookEventBase<"click">, WebhookEventWithTracking {
-  /**
-   * The URL that was clicked by the recipient
-   */
-  url?: string;
-}
-interface WebhookEventWithStatus {
-  /**
-   * The SMTP status code that caused the bounce
-   */
-  status?: string;
-  /**
-   * A human-readable explanation of why the message hard-bounced
-   */
-  reason?: string;
-}
-interface WebhookEventHardBounced extends WebhookEventBase<"hard-bounced">, WebhookEventWithStatus {}
-interface WebhookEventSoftBounced extends WebhookEventBase<"soft-bounced">, WebhookEventWithStatus {}
-interface WebhookEventDropped extends WebhookEventBase<"dropped">, WebhookEventWithStatus {}
-interface WebhookEventComplained extends WebhookEventBase<"complained"> {}
-interface WebhookEventUnsubscribed extends WebhookEventBase<"unsubscribed"> {}
-interface WebhookEventTest extends Omit<WebhookEventBase<"test">, "recipients" | "campaign_id"> {}
-type WebhookEvent = WebhookEventProcessed | WebhookEventDelivered | WebhookEventOpen | WebhookEventClick | WebhookEventHardBounced | WebhookEventSoftBounced | WebhookEventDropped | WebhookEventComplained | WebhookEventUnsubscribed | WebhookEventTest;
-type WebhookEvents = WebhookEvent[];
 declare class MailChannels extends MailChannelsClient {
   readonly emails: Emails;
   readonly domains: Domains;
@@ -1746,4 +1773,4 @@ declare class MailChannels extends MailChannelsClient {
   readonly suppressions: Suppressions;
   constructor(key: string, options?: MailChannelsClientOptions);
 }
-export { DataResponse, Domains, DomainsCheckOptions, DomainsCheckResponse, DomainsCheckVerdict, DomainsDkimCreateOptions, DomainsDkimCreateResponse, DomainsDkimKey, DomainsDkimKeyStatus, DomainsDkimListOptions, DomainsDkimListResponse, DomainsDkimRotateOptions, DomainsDkimRotateResponse, DomainsDkimUpdateOptions, Emails, EmailsSendAsyncResponse, EmailsSendAttachment, EmailsSendContent, EmailsSendDkim, EmailsSendOptions, EmailsSendPersonalization, EmailsSendRecipient, EmailsSendRecipientInput, EmailsSendResponse, EmailsSendTemplate, EmailsSendTemplateType, EmailsSendTemplateValue, EmailsSendTracking, ErrorResponse, MailChannels, MailChannelsClient, MailChannelsClientOptions, Metrics, MetricsBucket, MetricsEngagement, MetricsEngagementResponse, MetricsOptions, MetricsPerformance, MetricsPerformanceResponse, MetricsRecipientBehaviour, MetricsRecipientBehaviourResponse, MetricsSenders, MetricsSendersOptions, MetricsSendersResponse, MetricsSendersType, MetricsUsageResponse, MetricsVolume, MetricsVolumeResponse, SubAccounts, SubAccountsAccount, SubAccountsApiKey, SubAccountsCreateApiKeyResponse, SubAccountsCreateResponse, SubAccountsCreateSmtpPasswordResponse, SubAccountsLimit, SubAccountsLimitResponse, SubAccountsListApiKeyOptions, SubAccountsListApiKeyResponse, SubAccountsListOptions, SubAccountsListResponse, SubAccountsListSmtpPasswordResponse, SubAccountsSmtpPassword, SubAccountsUsage, SubAccountsUsageResponse, SuccessResponse, Suppressions, SuppressionsCreateOptions, SuppressionsListEntry, SuppressionsListOptions, SuppressionsListResponse, SuppressionsSource, SuppressionsTypes, WebhookEvent, WebhookEventClick, WebhookEventComplained, WebhookEventDelivered, WebhookEventDropped, WebhookEventHardBounced, WebhookEventOpen, WebhookEventProcessed, WebhookEventSoftBounced, WebhookEventTest, WebhookEventType, WebhookEventUnsubscribed, WebhookEvents, Webhooks, WebhooksBatch, WebhooksBatchResponseStatus, WebhooksBatchStatus, WebhooksBatchesOptions, WebhooksBatchesResponse, WebhooksListResponse, WebhooksResendBatch, WebhooksResendBatchResponse, WebhooksSigningKeyResponse, WebhooksValidateResponse, WebhooksVerifyOptions };
+export { Attachment, type DataResponse, Domains, type DomainsCheckOptions, type DomainsCheckResponse, type DomainsCheckVerdict, type DomainsDkimCreateOptions, type DomainsDkimCreateResponse, type DomainsDkimKey, type DomainsDkimKeyStatus, type DomainsDkimListOptions, type DomainsDkimListResponse, type DomainsDkimRotateOptions, type DomainsDkimRotateResponse, type DomainsDkimUpdateStatusOptions, Emails, type EmailsQueueResponse, type EmailsSendAsyncResponse, type EmailsSendAttachment, type EmailsSendContent, type EmailsSendDkim, type EmailsSendOptions, type EmailsSendPersonalization, type EmailsSendRecipient, type EmailsSendRecipientInput, type EmailsSendResponse, type EmailsSendTemplate, type EmailsSendTemplateType, type EmailsSendTemplateValue, type EmailsSendTracking, type ErrorResponse, MailChannels, MailChannelsClient, type MailChannelsClientOptions, Metrics, type MetricsBucket, type MetricsEngagement, type MetricsEngagementResponse, type MetricsOptions, type MetricsPerformance, type MetricsPerformanceResponse, type MetricsRecipientBehaviour, type MetricsRecipientBehaviourResponse, type MetricsSenders, type MetricsSendersOptions, type MetricsSendersResponse, type MetricsSendersType, type MetricsUsageResponse, type MetricsVolume, type MetricsVolumeResponse, SubAccounts, type SubAccountsAccount, type SubAccountsApiKey, type SubAccountsCreateApiKeyResponse, type SubAccountsCreateResponse, type SubAccountsCreateSmtpPasswordResponse, type SubAccountsLimit, type SubAccountsLimitResponse, type SubAccountsListApiKeyOptions, type SubAccountsListApiKeyResponse, type SubAccountsListOptions, type SubAccountsListResponse, type SubAccountsListSmtpPasswordResponse, type SubAccountsSmtpPassword, type SubAccountsUsage, type SubAccountsUsageResponse, type SuccessResponse, Suppressions, type SuppressionsCreateOptions, type SuppressionsListEntry, type SuppressionsListOptions, type SuppressionsListResponse, type SuppressionsSource, type SuppressionsTypes, type WebhookEvent, type WebhookEventClick, type WebhookEventComplained, type WebhookEventDelivered, type WebhookEventDropped, type WebhookEventHardBounced, type WebhookEventOpen, type WebhookEventProcessed, type WebhookEventSoftBounced, type WebhookEventTest, type WebhookEventType, type WebhookEventUnsubscribed, Webhooks, type WebhooksBatch, type WebhooksBatchResponseStatus, type WebhooksBatchStatus, type WebhooksBatchesOptions, type WebhooksBatchesResponse, type WebhooksListResponse, type WebhooksResendBatch, type WebhooksResendBatchResponse, type WebhooksSigningKeyResponse, type WebhooksValidateResponse, type WebhooksVerifyOptions, type WebhooksVerifyResponse };

package/dist/mailchannels.mjs

@@ -1,16 +1,22 @@
 import { $fetch } from "ofetch";
 import { subtle } from "node:crypto";
 import { Buffer } from "node:buffer";
-var version = "0.8.0-0";
+import { basename } from "node:path";
+import { readFile } from "node:fs/promises";
+import mime from "mime";
+var version = "0.8.0";
 var MailChannelsClient = class MailChannelsClient {
 	static DEFAULT_BASE_URL = "https://api.mailchannels.net";
+	static DEFAULT_TIMEOUT = 12e4;
 	options;
 	#headers;
 	constructor(key, options = {}) {
 		if (!key) throw new Error("Missing MailChannels API key.");
 		this.options = {
 			baseUrl: options.baseUrl || MailChannelsClient.DEFAULT_BASE_URL,
-			retry: options.retry ?? false
+			retry: options.retry ?? false,
+			signal: options.signal,
+			timeout: options.timeout ?? MailChannelsClient.DEFAULT_TIMEOUT
 		};
 		this.#headers = {
 			"X-API-Key": key,
@@ -20,13 +26,16 @@ var MailChannelsClient = class MailChannelsClient {
 		};
 	}
 	async _fetch(path, options) {
+		const { headers, signal = this.options.signal, ...fetchOptions } = options;
 		return $fetch(path, {
 			baseURL: this.options.baseUrl,
 			retry: this.options.retry,
-			...options,
+			signal,
+			timeout: this.options.timeout === false ? void 0 : this.options.timeout,
+			...fetchOptions,
 			headers: {
 				...this.#headers,
-				...options?.headers
+				...headers
 			}
 		});
 	}
@@ -85,7 +94,6 @@ const validatePagination = (pagination = {}) => {
 	if (typeof offset === "number" && offset < 0) return createError("Offset must be greater than or equal to 0.");
 	return null;
 };
-const stripPemHeaders = (pem) => pem.replace(/-----[^-]+-----|\s|#.*$/gm, "");
 const clean = (data) => {
 	if (Array.isArray(data)) {
 		const result = [];
@@ -108,25 +116,6 @@ const clean = (data) => {
 	}
 	return data;
 };
-const mapBuckets = (arr) => {
-	return arr.map(({ count, period_start }) => ({
-		count,
-		periodStart: period_start
-	}));
-};
-const mapDkimKey = (key) => ({
-	algorithm: key.algorithm,
-	createdAt: key.created_at,
-	dnsRecords: key.dkim_dns_records,
-	domain: key.domain,
-	gracePeriodExpiresAt: key.gracePeriodExpiresAt,
-	length: key.key_length,
-	publicKey: key.public_key,
-	retiresAt: key.retiresAt,
-	selector: key.selector,
-	status: key.status,
-	statusModifiedAt: key.status_modified_at
-});
 const isValidEmail = (email) => {
 	return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
 };
@@ -157,6 +146,7 @@ const parseArrayRecipients = (recipients) => {
 	const filtered = (typeof recipients === "string" ? [parseRecipientString(recipients)] : Array.isArray(recipients) ? recipients.map(parseRecipient) : [recipients]).filter((recipient) => Boolean(recipient));
 	return filtered.length > 0 ? filtered : void 0;
 };
+const stripPemHeaders = (pem) => pem.replace(/-----[^-]+-----|\s|#.*$/gm, "");
 const RESERVED_HEADER_NAMES = new Set([
 	"authentication-results",
 	"bcc",
@@ -207,6 +197,13 @@ const mapDkim = (dkim) => ({
 	dkim_private_key: dkim?.privateKey ? stripPemHeaders(dkim.privateKey) : void 0,
 	dkim_selector: dkim?.selector
 });
+const mapAttachment = (attachment) => ({
+	content: attachment.content,
+	filename: attachment.filename,
+	type: attachment.type,
+	content_id: attachment.contentId,
+	disposition: attachment.disposition
+});
 const mapPersonalization = (personalization, index, rootTemplateData) => {
 	const to = parseArrayRecipients(personalization.to);
 	if (!to || !to.length) return `Personalization at index ${index} must include at least one recipient in the 'to' field.`;
@@ -238,7 +235,11 @@ const mapPersonalization = (personalization, index, rootTemplateData) => {
 		to
 	};
 };
-const buildSendPayload = (options) => {
+const resolveAttachments = async (attachments) => {
+	if (!attachments) return;
+	return Promise.all(attachments.map((a) => Promise.resolve(a))).catch((e) => e.message);
+};
+const buildSendPayload = async (options) => {
 	const { from, html, text } = options;
 	const contentTypes = options.content ? new Set(options.content.map((item) => item.type.toLowerCase())) : void 0;
 	const parsedFrom = parseRecipient(from);
@@ -307,8 +308,10 @@ const buildSendPayload = (options) => {
 		value: item.value,
 		template_type
 	});
+	const resolvedAttachments = await resolveAttachments(options.attachments);
+	if (typeof resolvedAttachments === "string") return resolvedAttachments;
 	return {
-		attachments: options.attachments,
+		attachments: resolvedAttachments?.map((a) => mapAttachment(a)),
 		campaign_id: options.campaignId,
 		...mapDkim(options.dkim),
 		envelope_from: parseRecipient(options.envelopeFrom),
@@ -332,7 +335,7 @@ var Emails = class {
 	}
 	async _sendEmail(options, flags) {
 		let error = null;
-		const payload = buildSendPayload(options);
+		const payload = await buildSendPayload(options);
 		if (typeof payload === "string") {
 			error = createError(payload);
 			return {
@@ -387,10 +390,26 @@ var Emails = class {
 	async send(options, dryRun = false) {
 		return this._sendEmail(options, { dryRun });
 	}
-	async sendAsync(options) {
+	async queue(options) {
 		return this._sendEmail(options, { async: true });
 	}
+	async sendAsync(options) {
+		return this.queue(options);
+	}
 };
+const mapDkimKey = (key) => ({
+	algorithm: key.algorithm,
+	createdAt: key.created_at,
+	dnsRecords: key.dkim_dns_records,
+	domain: key.domain,
+	gracePeriodExpiresAt: key.gracePeriodExpiresAt,
+	length: key.key_length,
+	publicKey: key.public_key,
+	retiresAt: key.retiresAt,
+	selector: key.selector,
+	status: key.status,
+	statusModifiedAt: key.status_modified_at
+});
 var Domains = class {
 	mailchannels;
 	dkim;
@@ -398,10 +417,16 @@ var Domains = class {
 		this.mailchannels = mailchannels;
 		this.dkim = new DomainsDkim(mailchannels);
 	}
-	async check(options) {
+	async check(domain, options) {
 		let error = null;
-		const { dkim, domain, senderId } = options;
-		const dkimOptions = dkim ? Array.isArray(dkim) ? dkim : [dkim] : void 0;
+		if (!domain) {
+			error = createError("No domain provided.");
+			return {
+				data: null,
+				error
+			};
+		}
+		const dkimOptions = options?.dkim ? Array.isArray(options.dkim) ? options.dkim : [options.dkim] : void 0;
 		if (dkimOptions && dkimOptions.length > 10) {
 			error = createError("A maximum of 10 DKIM settings can be provided.");
 			return {
@@ -417,13 +442,13 @@ var Domains = class {
 			};
 		}
 		const payload = {
-			dkim_settings: dkimOptions?.map(({ domain, privateKey, selector }) => ({
-				dkim_domain: domain,
-				dkim_private_key: privateKey ? stripPemHeaders(privateKey) : void 0,
-				dkim_selector: selector
+			dkim_settings: dkimOptions?.map((dkim) => ({
+				dkim_domain: dkim.domain,
+				dkim_private_key: dkim.privateKey ? stripPemHeaders(dkim.privateKey) : void 0,
+				dkim_selector: dkim.selector
 			})),
 			domain,
-			sender_id: senderId
+			sender_id: options?.senderId
 		};
 		const response = await this.mailchannels.post("/tx/v1/check-domain", {
 			body: payload,
@@ -466,6 +491,13 @@ var DomainsDkim = class {
 	}
 	async create(domain, options) {
 		let error = null;
+		if (!domain) {
+			error = createError("No domain provided.");
+			return {
+				data: null,
+				error
+			};
+		}
 		if (!options.selector || options.selector.length > 63) {
 			error = createError("Selector must be between 1 and 63 characters.");
 			return {
@@ -501,6 +533,13 @@ var DomainsDkim = class {
 	}
 	async list(domain, options) {
 		let error = null;
+		if (!domain) {
+			error = createError("No domain provided.");
+			return {
+				data: null,
+				error
+			};
+		}
 		if (options?.selector && options.selector.length > 63) {
 			error = createError("Selector must be between 1 and 63 characters.");
 			return {
@@ -541,8 +580,15 @@ var DomainsDkim = class {
 			error: null
 		};
 	}
-	async update(domain, options) {
+	async updateStatus(domain, options) {
 		let error = null;
+		if (!domain) {
+			error = createError("No domain provided.");
+			return {
+				success: false,
+				error
+			};
+		}
 		if (!options.selector || options.selector.length > 63) {
 			error = createError("Selector must be between 1 and 63 characters.");
 			return {
@@ -560,7 +606,7 @@ var DomainsDkim = class {
 				});
 			}
 		}).catch((e) => {
-			error ||= getResultError(e, "Failed to update DKIM key.");
+			error ||= getResultError(e, "Failed to update status of DKIM key.");
 		});
 		return {
 			success: !error,
@@ -569,6 +615,13 @@ var DomainsDkim = class {
 	}
 	async rotate(domain, selector, options) {
 		let error = null;
+		if (!domain) {
+			error = createError("No domain provided.");
+			return {
+				data: null,
+				error
+			};
+		}
 		if (!selector || selector.length > 63) {
 			error = createError("Selector must be between 1 and 63 characters.");
 			return {
@@ -687,7 +740,7 @@ var Webhooks = class Webhooks {
 	constructor(mailchannels) {
 		this.mailchannels = mailchannels;
 	}
-	async enroll(endpoint) {
+	async create(endpoint) {
 		let error = null;
 		if (!endpoint) {
 			error = createError("No endpoint provided.");
@@ -709,7 +762,7 @@ var Webhooks = class Webhooks {
 				error = getStatusError(response, { [409]: `Endpoint '${endpoint}' is already enrolled to receive notifications.` });
 			}
 		}).catch((e) => {
-			error ||= getResultError(e, "Failed to enroll webhook.");
+			error ||= getResultError(e, "Failed to create webhook.");
 		});
 		return {
 			success: !error,
@@ -733,7 +786,7 @@ var Webhooks = class Webhooks {
 			error: null
 		};
 	}
-	async delete() {
+	async deleteAll() {
 		let error = null;
 		await this.mailchannels.delete("/tx/v1/webhook", { onResponseError: async ({ response }) => {
 			error = getStatusError(response);
@@ -805,7 +858,48 @@ var Webhooks = class Webhooks {
 		};
 	}
 	static async verify(options) {
-		return isValidWebhook(options).catch(() => false);
+		let error = null;
+		if (!await isValidWebhook(options).catch(() => false)) {
+			error = createError("Invalid webhook signature.");
+			return {
+				data: null,
+				error
+			};
+		}
+		try {
+			const payload = JSON.parse(options.payload);
+			if (!Array.isArray(payload)) {
+				error = createError("Invalid webhook payload.");
+				return {
+					data: null,
+					error
+				};
+			}
+			return {
+				data: clean(payload.map((event) => ({
+					email: event.email,
+					customerHandle: event.customer_handle,
+					timestamp: event.timestamp,
+					smtpId: event.smtp_id,
+					event: event.event,
+					requestId: event.request_id,
+					campaignId: "campaign_id" in event ? event.campaign_id : void 0,
+					recipients: "recipients" in event ? event.recipients : void 0,
+					userAgent: "user_agent" in event ? event.user_agent : void 0,
+					ip: "ip" in event ? event.ip : void 0,
+					url: "url" in event ? event.url : void 0,
+					status: "status" in event ? event.status : void 0,
+					reason: "reason" in event ? event.reason : void 0
+				}))),
+				error: null
+			};
+		} catch {
+			error = createError("Invalid webhook payload.");
+			return {
+				data: null,
+				error
+			};
+		}
 	}
 	async verify(options) {
 		return Webhooks.verify(options);
@@ -1322,6 +1416,12 @@ var SubAccounts = class SubAccounts {
 		};
 	}
 };
+const mapBucket = (bucket) => {
+	return {
+		count: bucket.count,
+		periodStart: bucket.period_start
+	};
+};
 var Metrics = class {
 	mailchannels;
 	constructor(mailchannels) {
@@ -1350,10 +1450,10 @@ var Metrics = class {
 		return {
 			data: clean({
 				buckets: {
-					click: mapBuckets(response.buckets.click),
-					clickTrackingDelivered: mapBuckets(response.buckets.click_tracking_delivered),
-					open: mapBuckets(response.buckets.open),
-					openTrackingDelivered: mapBuckets(response.buckets.open_tracking_delivered)
+					click: response.buckets.click.map(mapBucket),
+					clickTrackingDelivered: response.buckets.click_tracking_delivered.map(mapBucket),
+					open: response.buckets.open.map(mapBucket),
+					openTrackingDelivered: response.buckets.open_tracking_delivered.map(mapBucket)
 				},
 				click: response.click,
 				clickTrackingDelivered: response.click_tracking_delivered,
@@ -1389,9 +1489,9 @@ var Metrics = class {
 			data: clean({
 				bounced: response.bounced,
 				buckets: {
-					bounced: mapBuckets(response.buckets.bounced),
-					delivered: mapBuckets(response.buckets.delivered),
-					processed: mapBuckets(response.buckets.processed)
+					bounced: response.buckets.bounced.map(mapBucket),
+					delivered: response.buckets.delivered.map(mapBucket),
+					processed: response.buckets.processed.map(mapBucket)
 				},
 				delivered: response.delivered,
 				endTime: response.end_time,
@@ -1424,8 +1524,8 @@ var Metrics = class {
 		return {
 			data: clean({
 				buckets: {
-					unsubscribeDelivered: mapBuckets(response.buckets.unsubscribe_delivered),
-					unsubscribed: mapBuckets(response.buckets.unsubscribed)
+					unsubscribeDelivered: response.buckets.unsubscribe_delivered.map(mapBucket),
+					unsubscribed: response.buckets.unsubscribed.map(mapBucket)
 				},
 				endTime: response.end_time,
 				startTime: response.start_time,
@@ -1458,9 +1558,9 @@ var Metrics = class {
 		return {
 			data: clean({
 				buckets: {
-					delivered: mapBuckets(response.buckets.delivered),
-					dropped: mapBuckets(response.buckets.dropped),
-					processed: mapBuckets(response.buckets.processed)
+					delivered: response.buckets.delivered.map(mapBucket),
+					dropped: response.buckets.dropped.map(mapBucket),
+					processed: response.buckets.processed.map(mapBucket)
 				},
 				delivered: response.delivered,
 				dropped: response.dropped,
@@ -1640,6 +1740,62 @@ var Suppressions = class {
 		};
 	}
 };
+const base64Content = (data) => {
+	if (data instanceof ArrayBuffer) return Buffer.from(data).toString("base64");
+	return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("base64");
+};
+const guessContentType = (filename) => {
+	return mime.getType(filename) || void 0;
+};
+var Attachment = class Attachment {
+	static fromBytes(data, options) {
+		const { filename, type, contentId, disposition = "attachment" } = options;
+		return {
+			content: base64Content(data),
+			filename: decodeURIComponent(filename) || "attachment",
+			type: type || guessContentType(filename),
+			contentId,
+			disposition
+		};
+	}
+	static async fromFile(path, options) {
+		try {
+			const data = await readFile(path);
+			return Attachment.fromBytes(data, {
+				filename: basename(path.toString()),
+				...options
+			});
+		} catch (error) {
+			throw new Error(`Unable to read attachment file: ${path}`, { cause: error });
+		}
+	}
+	static async fromUrl(url, options) {
+		try {
+			let contentType;
+			const data = await $fetch(url, {
+				responseType: "arrayBuffer",
+				timeout: 12e4,
+				onResponse: ({ response }) => {
+					const contentTypeHeader = response.headers.get("content-type");
+					if (contentTypeHeader) contentType = contentTypeHeader.split(";", 1)[0]?.trim();
+				}
+			});
+			return Attachment.fromBytes(data, {
+				type: contentType,
+				filename: basename(new URL(url).pathname),
+				...options
+			});
+		} catch (error) {
+			throw new Error(`Unable to fetch attachment from URL: ${url}`, { cause: error });
+		}
+	}
+	static inlineFile(path, options) {
+		return Attachment.fromFile(path, {
+			...options,
+			disposition: "inline"
+		});
+	}
+};
 var MailChannels = class extends MailChannelsClient {
 	emails = new Emails(this);
 	domains = new Domains(this);
@@ -1651,4 +1807,4 @@ var MailChannels = class extends MailChannelsClient {
 		super(key, options);
 	}
 };
-export { Domains, Emails, MailChannels, MailChannelsClient, Metrics, SubAccounts, Suppressions, Webhooks };
+export { Attachment, Domains, Emails, MailChannels, MailChannelsClient, Metrics, SubAccounts, Suppressions, Webhooks };

package/package.json

@@ -1,26 +1,24 @@
 {
   "name": "mailchannels-sdk",
-  "version": "0.8.0-0",
+  "version": "0.8.0",
   "description": "Node.js SDK to integrate MailChannels Email API into your JavaScript or TypeScript server-side applications.",
   "type": "module",
   "license": "MIT",
   "keywords": [
     "mailchannels",
-    "javascript",
     "typescript",
-    "node",
-    "sdk",
-    "email"
+    "email",
+    "transactional-email",
+    "sdk"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Yizack/mailchannels.git"
+    "url": "git+https://bitbucket.org/mailchannels/mailchannels-email-api-sdk-js.git"
   },
   "homepage": "https://mailchannels.yizack.com",
   "author": {
-    "name": "Yizack Rangel",
-    "email": "yizackr@gmail.com",
-    "url": "https://yizack.com"
+    "name": "MailChannels",
+    "email": "dev@mailchannels.com"
   },
   "main": "./dist/mailchannels.mjs",
   "exports": {
@@ -38,22 +36,26 @@
     "dist"
   ],
   "dependencies": {
+    "mime": "^4.1.0",
     "ofetch": "^2.0.0-alpha.3"
   },
   "devDependencies": {
     "@stylistic/eslint-plugin": "^5.10.0",
     "@types/markdown-it": "^14.1.2",
-    "@types/node": "^25.8.0",
-    "@vitest/coverage-v8": "^4.1.6",
+    "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "^4.1.7",
     "changelogen": "^0.6.2",
-    "obuild": "^0.4.35",
-    "oxlint": "^1.64.0",
+    "obuild": "^0.4.36",
+    "oxlint": "^1.67.0",
     "scule": "^1.3.0",
     "typescript": "^6.0.3",
     "vitepress": "^2.0.0-alpha.17",
     "vitepress-plugin-group-icons": "^1.7.5",
-    "vitepress-plugin-llms": "^1.12.2",
-    "vitest": "^4.1.6"
+    "vitepress-plugin-llms": "^1.13.0",
+    "vitest": "^4.1.7"
+  },
+  "engines": {
+    "node": ">=20"
   },
   "scripts": {
     "build": "obuild",