mailchannels-sdk 1.2.0 → 1.3.0

package/.agents/skills/mailchannels-js/resources/suppressions.md

@@ -10,8 +10,8 @@ import { MailChannels } from 'mailchannels-sdk'
 
 const mc = new MailChannels('YOUR-API-KEY')
 
-const { success, error } = await mc.suppressions.create({
-  entries: [
+const { success, error } = await mc.suppressions.create(
+  [
     {
       recipient: 'out@example.net',
       types: ['non-transactional'],          // optional; defaults to non-transactional
@@ -22,8 +22,8 @@ const { success, error } = await mc.suppressions.create({
       types: ['transactional', 'non-transactional']
     }
   ],
-  addToSubAccounts: true   // parent only; copies entries to every sub-account
-})
+  { addToSubAccounts: true }   // parent only; copies entries to every sub-account
+)
 ```
 
 Constraints:
@@ -83,9 +83,9 @@ that recipient regardless of origin.
 
 ### Patterns
 
-- **Preference center opt-out**: set `type` according to the email category, e.g. `non-transactional` for marketing 
-  emails, `transactional` for order updates, and so on. 
+- **Preference center opt-out**: set `types` according to the email category, e.g. `non-transactional` for marketing
+  emails, `transactional` for order updates, and so on.
   Configure `addToSubAccounts` depending on whether the preference applies to all sub-accounts or just the parent account.
   Add a note to indicate the source, e.g. "Opted out via preference center".
-- **Migrating from another ESP**: bulk-create with `addToSubAccounts: true` so every tenant
+- **Migrating from another ESP**: bulk-create with option `addToSubAccounts: true` so every tenant
   inherits the list.

package/README.md

@@ -9,7 +9,7 @@
 [![TypeScript][typescript-src]][typescript-href]
 [![Node.js][node-src]][node-href]
 
-> Built and tested against Email API `1.4.0`
+> Built and tested against Email API `1.5.0`
 
 Node.js SDK to integrate [MailChannels Email API](https://docs.mailchannels.com/email-api) into your JavaScript or TypeScript server-side applications.
 

package/dist/_chunks/simulator.mjs

@@ -55,6 +55,7 @@ const createMetricsBuckets = (count) => [{
 const createAccountState = (apiKey) => ({
 	apiKey,
 	customerHandle: createId("customer"),
+	limit: { sends: 1e5 },
 	customTrackingDomains: [],
 	dkimKeysByDomain: /* @__PURE__ */ new Map(),
 	messages: [],
@@ -600,10 +601,13 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 					return;
 				}
 				if (suffix === "usage" && method === "GET") {
+					const subLimitSends = subAccount.limit?.sends ?? -1;
+					const monthlyLimit = subLimitSends === -1 ? account.limit.sends : subLimitSends;
 					sendJson(response, 200, {
 						period_end_date: currentTimestamp(),
 						period_start_date: new Date((/* @__PURE__ */ new Date()).setDate(1)).toISOString(),
-						total_usage: subAccount.usage
+						total_usage: subAccount.usage,
+						monthly_limit: monthlyLimit
 					});
 					return;
 				}
@@ -720,10 +724,21 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 				return;
 			}
 			if (url.pathname === "/tx/v1/usage" && method === "GET") {
+				let totalUsage = account.messages.length;
+				let monthlyLimit = account.limit.sends;
+				if (scopeHandle) {
+					const subAccount = account.subAccounts.get(scopeHandle);
+					if (subAccount) {
+						totalUsage = subAccount.usage;
+						const subLimitSends = subAccount.limit?.sends ?? -1;
+						monthlyLimit = subLimitSends === -1 ? account.limit.sends : subLimitSends;
+					}
+				}
 				sendJson(response, 200, {
 					period_end_date: currentTimestamp(),
 					period_start_date: new Date((/* @__PURE__ */ new Date()).setDate(1)).toISOString(),
-					total_usage: account.messages.length
+					total_usage: totalUsage,
+					monthly_limit: monthlyLimit
 				});
 				return;
 			}

package/dist/mailchannels.d.mts

@@ -1440,8 +1440,15 @@ interface SubAccountsUsage {
   startDate?: string;
   /**
    * The total usage for the current billing period.
+   * @example 5000
    */
   total: number;
+  /**
+   * The effective monthly limit for the current billing period. A limit of zero means the account cannot send any messages.
+   * For sub-accounts with no explicit limit set (i.e., -1), the monthly limit for the parent account is returned.
+   * @example 10000
+   */
+  monthlyLimit: number;
 }
 type SubAccountsUsageResponse = DataResponse<SubAccountsUsage>;
 interface MetricsEngagement {
@@ -1612,8 +1619,15 @@ type MetricsUsageResponse = DataResponse<{
   startDate?: string;
   /**
    * The total usage for the current billing period.
+   * @example 5000
    */
   total: number;
+  /**
+   * The effective monthly limit for the current billing period. A limit of zero means the account cannot send any messages.
+   * For sub-accounts with no explicit limit set (i.e., -1), the monthly limit for the parent account is returned.
+   * @example 10000
+   */
+  monthlyLimit: number;
 }>;
 type MetricsSendersType = "sub-accounts" | "campaigns";
 interface MetricsSendersOptions {
@@ -1696,6 +1710,21 @@ interface MetricsOptions {
   interval?: "hour" | "day" | "week" | "month";
 }
 type SuppressionsTypes = "transactional" | "non-transactional";
+interface SuppressionsCreateEntry {
+  /**
+   * Must be less than `1024` characters.
+   */
+  notes?: string;
+  /**
+   * The email address to suppress. Must be a valid email address format and less than `255` characters.
+   */
+  recipient: string;
+  /**
+   * An array of types of suppression to apply to the recipient.
+   * @default ["non-transactional"]
+   */
+  types?: SuppressionsTypes[];
+}
 interface SuppressionsCreateOptions {
   /**
    * If true, the parent account creates suppression entries for all associated sub-accounts. This field is only applicable to parent accounts. Sub-accounts cannot create entries for other sub-accounts.
@@ -1704,22 +1733,9 @@ interface SuppressionsCreateOptions {
   addToSubAccounts?: boolean;
   /**
    * The total number of suppression entries to create, for the parent and/or its sub-accounts, must not exceed `1000`.
+   * @deprecated Use `create(entries, options?)` instead.
    */
-  entries: {
-    /**
-     * Must be less than `1024` characters.
-     */
-    notes?: string;
-    /**
-     * The email address to suppress. Must be a valid email address format and less than `255` characters.
-     */
-    recipient: string;
-    /**
-     * An array of types of suppression to apply to the recipient.
-     * @default ["non-transactional"]
-     */
-    types?: SuppressionsTypes[];
-  }[];
+  entries: SuppressionsCreateEntry[];
 }
 type SuppressionsSource = "api" | "unsubscribe_link" | "list_unsubscribe" | "hard_bounce" | "spam_complaint" | "all";
 interface SuppressionsListOptions {
@@ -2025,14 +2041,21 @@ declare class Suppressions {
   constructor(mailchannels: MailChannelsClient);
   /**
    * Creates suppression entries for the specified account. Parent accounts can create suppression entries for all associated sub-accounts. If `types` is not provided, it defaults to `non-transactional`. The operation is atomic, meaning all entries are successfully added or none are added if an error occurs.
-   * @param options - The details of the suppression entries to create.
+   * @param entries - The total number of suppression entries to create, for the parent and/or its sub-accounts, must not exceed `1000`.
+   * @param options - The options of the suppression entries to create.
    * @example
    * ```ts
    * const mailchannels = new MailChannels('your-api-key')
-   * const { success, error } = await mailchannels.suppressions.create({
-   * // ...
-   * });
+   * const { success, error } = await mailchannels.suppressions.create([
+   *   {
+   *     notes: "test",
+   *     recipient: "name@example.com",
+   *     types: ["transactional"]
+   *   }
+   * ], { addToSubAccounts: false });
    */
+  create(entries: SuppressionsCreateEntry[], options?: Omit<SuppressionsCreateOptions, "entries">): Promise<SuccessResponse>;
+  /** @deprecated Use positional params `create(entries, options?)` instead. */
   create(options: SuppressionsCreateOptions): Promise<SuccessResponse>;
   /**
    * Deletes suppression entry associated with the account based on the specified recipient and source.
@@ -2070,4 +2093,4 @@ declare class MailChannels extends MailChannelsClient {
   readonly suppressions: Suppressions;
   constructor(key: string, options?: MailChannelsClientOptions);
 }
-export { Attachment, type DataResponse, Domains, type DomainsCheckOptions, type DomainsCheckResponse, type DomainsCheckVerdict, type DomainsCustomTrackingCreateResponse, type DomainsCustomTrackingDnsSetupRequired, type DomainsCustomTrackingDomain, type DomainsCustomTrackingListOptions, type DomainsCustomTrackingListResponse, type DomainsCustomTrackingScope, type DomainsCustomTrackingUpdateOptions, type DomainsCustomTrackingUpdateResponse, type DomainsCustomTrackingWithDnsSetupRequired, 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, type ErrorType, 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, type SubAccount, SubAccounts, type SubAccountsAccount, type SubAccountsApiKey, type SubAccountsApiKeysCreateResponse, type SubAccountsApiKeysListOptions, type SubAccountsApiKeysListResponse, type SubAccountsCreateApiKeyResponse, type SubAccountsCreateResponse, type SubAccountsCreateSmtpPasswordResponse, type SubAccountsLimit, type SubAccountsLimitResponse, type SubAccountsLimitsGetResponse, type SubAccountsLimitsSetOptions, type SubAccountsListApiKeyOptions, type SubAccountsListApiKeyResponse, type SubAccountsListOptions, type SubAccountsListResponse, type SubAccountsListSmtpPasswordResponse, type SubAccountsSmtpPassword, type SubAccountsSmtpPasswordsCreateResponse, type SubAccountsSmtpPasswordsListResponse, 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 };
+export { Attachment, type DataResponse, Domains, type DomainsCheckOptions, type DomainsCheckResponse, type DomainsCheckVerdict, type DomainsCustomTrackingCreateResponse, type DomainsCustomTrackingDnsSetupRequired, type DomainsCustomTrackingDomain, type DomainsCustomTrackingListOptions, type DomainsCustomTrackingListResponse, type DomainsCustomTrackingScope, type DomainsCustomTrackingUpdateOptions, type DomainsCustomTrackingUpdateResponse, type DomainsCustomTrackingWithDnsSetupRequired, 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, type ErrorType, 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, type SubAccount, SubAccounts, type SubAccountsAccount, type SubAccountsApiKey, type SubAccountsApiKeysCreateResponse, type SubAccountsApiKeysListOptions, type SubAccountsApiKeysListResponse, type SubAccountsCreateApiKeyResponse, type SubAccountsCreateResponse, type SubAccountsCreateSmtpPasswordResponse, type SubAccountsLimit, type SubAccountsLimitResponse, type SubAccountsLimitsGetResponse, type SubAccountsLimitsSetOptions, type SubAccountsListApiKeyOptions, type SubAccountsListApiKeyResponse, type SubAccountsListOptions, type SubAccountsListResponse, type SubAccountsListSmtpPasswordResponse, type SubAccountsSmtpPassword, type SubAccountsSmtpPasswordsCreateResponse, type SubAccountsSmtpPasswordsListResponse, type SubAccountsUsage, type SubAccountsUsageResponse, type SuccessResponse, Suppressions, type SuppressionsCreateEntry, 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

@@ -2,7 +2,7 @@ import { $fetch } from "ofetch";
 import { subtle } from "node:crypto";
 import { Buffer } from "node:buffer";
 import mime from "mime";
-var version = "1.2.0";
+var version = "1.3.0";
 var MailChannelsClient = class MailChannelsClient {
 	static DEFAULT_BASE_URL = "https://api.mailchannels.net";
 	static DEFAULT_TIMEOUT = 12e4;
@@ -1743,7 +1743,8 @@ var SubAccounts = class SubAccounts {
 			data: clean({
 				endDate: response.period_end_date,
 				startDate: response.period_start_date,
-				total: response.total_usage
+				total: response.total_usage,
+				monthlyLimit: response.monthly_limit
 			}),
 			error: null
 		};
@@ -1989,7 +1990,8 @@ var Metrics = class {
 			data: clean({
 				endDate: response.period_end_date,
 				startDate: response.period_start_date,
-				total: response.total_usage
+				total: response.total_usage,
+				monthlyLimit: response.monthly_limit
 			}),
 			error: null
 		};
@@ -2049,9 +2051,10 @@ var Suppressions = class {
 	constructor(mailchannels) {
 		this.mailchannels = mailchannels;
 	}
-	async create(options) {
+	async create(entriesOrOptions, options) {
 		let error = null;
-		const { addToSubAccounts, entries } = options;
+		const entries = Array.isArray(entriesOrOptions) ? entriesOrOptions : entriesOrOptions.entries;
+		const createOptions = Array.isArray(entriesOrOptions) ? options : entriesOrOptions;
 		if (entries.length > 1e3) {
 			error = createValidationError("The number of suppression entries must not exceed 1000.");
 			return {
@@ -2060,7 +2063,7 @@ var Suppressions = class {
 			};
 		}
 		const payload = {
-			add_to_sub_accounts: addToSubAccounts,
+			add_to_sub_accounts: createOptions?.addToSubAccounts,
 			suppression_entries: entries.map((entry) => ({
 				notes: entry.notes,
 				recipient: entry.recipient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailchannels-sdk",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Node.js SDK to integrate MailChannels Email API into your JavaScript or TypeScript server-side applications.",
   "type": "module",
   "license": "MIT",
@@ -46,13 +46,13 @@
     "@types/node": "^26.1.1",
     "@vitest/coverage-v8": "^4.1.10",
     "changelogen": "^0.6.2",
-    "obuild": "^0.4.37",
-    "oxlint": "^1.73.0",
+    "obuild": "^0.4.38",
+    "oxlint": "^1.74.0",
     "scule": "^1.3.0",
     "typescript": "^6.0.3",
     "vitepress": "^2.0.0-alpha.18",
     "vitepress-plugin-group-icons": "^1.7.5",
-    "vitepress-plugin-llms": "^1.13.2",
+    "vitepress-plugin-llms": "^1.13.3",
     "vitest": "^4.1.10"
   },
   "engines": {