@mailermine/node 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -20,6 +20,18 @@ interface ConfigurationOptions {
20
20
  * User-Agent header value sent with every request.
21
21
  */
22
22
  userAgent?: string;
23
+ /**
24
+ * How many times a rate-limited (429), temporarily unavailable
25
+ * (502/503/504) or network-failed request is retried. Defaults to 2;
26
+ * 0 disables retries. Email sends always carry an Idempotency-Key, so a
27
+ * retry is never delivered twice.
28
+ */
29
+ maxRetries?: number;
30
+ /**
31
+ * Longest single wait between retries, in milliseconds. A 429 asking to
32
+ * wait longer than this is thrown as a RateLimitError. Defaults to 30_000.
33
+ */
34
+ maxRetryDelay?: number;
23
35
  /**
24
36
  * Optional fetch implementation. Useful for tests and custom transports.
25
37
  * @internal
@@ -34,6 +46,8 @@ interface ResolvedConfiguration {
34
46
  readonly baseUrl: string;
35
47
  readonly timeout: number;
36
48
  readonly userAgent: string;
49
+ readonly maxRetries: number;
50
+ readonly maxRetryDelay: number;
37
51
  readonly fetchApi?: typeof fetch;
38
52
  }
39
53
 
@@ -47,6 +61,8 @@ declare class Configuration implements ResolvedConfiguration {
47
61
  readonly baseUrl: string;
48
62
  readonly timeout: number;
49
63
  readonly userAgent: string;
64
+ readonly maxRetries: number;
65
+ readonly maxRetryDelay: number;
50
66
  readonly fetchApi?: typeof fetch;
51
67
  constructor(options: ConfigurationOptions);
52
68
  /**
@@ -59,6 +75,26 @@ declare class Configuration implements ResolvedConfiguration {
59
75
  toJSON(): ResolvedConfiguration;
60
76
  }
61
77
 
78
+ /** Rate-limit state reported by the API in `X-RateLimit-*` headers. */
79
+ declare class RateLimitInfo {
80
+ /** Requests allowed per window. */
81
+ readonly limit: number;
82
+ /** Requests left in the current window. */
83
+ readonly remaining: number;
84
+ /** When the window resets, or null if unknown. */
85
+ readonly resetsAt: Date | null;
86
+ constructor(
87
+ /** Requests allowed per window. */
88
+ limit: number,
89
+ /** Requests left in the current window. */
90
+ remaining: number,
91
+ /** When the window resets, or null if unknown. */
92
+ resetsAt: Date | null);
93
+ /** Seconds until the window resets (0 when unknown or past). */
94
+ get secondsUntilReset(): number;
95
+ static fromHeaders(headers: Headers): RateLimitInfo | null;
96
+ }
97
+
62
98
  interface InternalAnalyticsApi {
63
99
  overview(query: object): Promise<unknown>;
64
100
  messages(query: object): Promise<unknown>;
@@ -182,7 +218,9 @@ interface InternalExportsApi {
182
218
  }
183
219
 
184
220
  interface InternalEmailsApi {
185
- send(body: object): Promise<unknown>;
221
+ send(body: object, options?: {
222
+ idempotencyKey?: string;
223
+ }): Promise<unknown>;
186
224
  list(query: object): Promise<unknown>;
187
225
  get(messageId: string): Promise<unknown>;
188
226
  events(messageId: string): Promise<unknown>;
@@ -293,6 +331,15 @@ interface EmailAttachmentInput {
293
331
  content: string;
294
332
  contentType?: string;
295
333
  }
334
+ /** Per-request options for {@link Emails.send}. */
335
+ interface SendEmailOptions {
336
+ /**
337
+ * Unique key (max 255 chars). Repeating a send with the same key and body
338
+ * returns the original response instead of sending again. Generated
339
+ * automatically when omitted.
340
+ */
341
+ idempotencyKey?: string;
342
+ }
296
343
  interface SendEmailInput {
297
344
  from: string;
298
345
  to: string | readonly string[];
@@ -1561,8 +1608,11 @@ declare class Emails extends BaseResource {
1561
1608
  * text: 'Hello',
1562
1609
  * });
1563
1610
  * ```
1611
+ *
1612
+ * Pass `{ idempotencyKey }` to make retries from your own code safe:
1613
+ * the same key never sends twice.
1564
1614
  */
1565
- send(input: SendEmailInput): Promise<Response<EmailMessage>>;
1615
+ send(input: SendEmailInput, options?: SendEmailOptions): Promise<Response<EmailMessage>>;
1566
1616
  /**
1567
1617
  * List recently sent and queued messages for the authenticated project.
1568
1618
  */
@@ -1817,8 +1867,31 @@ declare class Webhooks extends BaseResource {
1817
1867
  replay(webhookId: string, input?: ReplayWebhookInput): Promise<Response<Record<string, unknown>>>;
1818
1868
  /** Retry one webhook delivery. */
1819
1869
  retry(deliveryId: string): Promise<Response<WebhookDelivery>>;
1820
- /** Verify a MailerMine HMAC-SHA256 webhook signature locally. */
1821
- static verify(payload: string, signature: string, secret: string): boolean;
1870
+ /** Default maximum age, in seconds, of a signed webhook timestamp. */
1871
+ static readonly DEFAULT_TOLERANCE_SECONDS = 300;
1872
+ /**
1873
+ * Verify a MailerMine webhook signature locally.
1874
+ *
1875
+ * MailerMine signs `{timestamp}.{rawBody}` with HMAC-SHA256 and sends the
1876
+ * timestamp in `X-MailerMine-Timestamp` and the signature in
1877
+ * `X-MailerMine-Signature` (`sha256=<hex>`). Pass the timestamp so the
1878
+ * signature matches and stale deliveries are rejected (replay protection).
1879
+ * Without a timestamp only a body-only signature is checked (legacy).
1880
+ * Prefer {@link Webhooks.verifyHeaders}.
1881
+ */
1882
+ static verify(payload: string, signature: string, secret: string, timestamp?: string | number | null, toleranceSeconds?: number): boolean;
1883
+ /**
1884
+ * Verify a webhook from its request headers (`X-MailerMine-Signature` and
1885
+ * `X-MailerMine-Timestamp`, falling back to legacy `X-Relay-*`).
1886
+ *
1887
+ * @example
1888
+ * ```ts
1889
+ * app.post('/hooks', express.raw({ type: 'application/json' }), (req, res) => {
1890
+ * if (!Webhooks.verifyHeaders(req.body.toString(), req.headers, secret)) return res.sendStatus(401);
1891
+ * });
1892
+ * ```
1893
+ */
1894
+ static verifyHeaders(payload: string, headers: Headers | Record<string, string | string[] | undefined>, secret: string, toleranceSeconds?: number): boolean;
1822
1895
  }
1823
1896
 
1824
1897
  /**
@@ -1842,6 +1915,7 @@ declare class Webhooks extends BaseResource {
1842
1915
  declare class MailerMine {
1843
1916
  readonly configuration: Configuration;
1844
1917
  private readonly apis;
1918
+ private readonly transport;
1845
1919
  private emailsResource?;
1846
1920
  private projectsResource?;
1847
1921
  private apiKeysResource?;
@@ -1861,6 +1935,11 @@ declare class MailerMine {
1861
1935
  private webhooksResource?;
1862
1936
  private suppressionsResource?;
1863
1937
  constructor(apiKeyOrOptions: string | ConfigurationOptions | Configuration);
1938
+ /**
1939
+ * Rate-limit state from the most recent API response (null until a
1940
+ * response carrying `X-RateLimit-*` headers has been received).
1941
+ */
1942
+ get rateLimit(): RateLimitInfo | null;
1864
1943
  /** Transactional email operations. */
1865
1944
  get emails(): Emails;
1866
1945
  /** Workspace project operations. */
@@ -1902,7 +1981,7 @@ declare class MailerMine {
1902
1981
  /**
1903
1982
  * SDK version. Keep in sync with package.json when releasing.
1904
1983
  */
1905
- declare const VERSION = "1.0.0";
1984
+ declare const VERSION = "1.1.0";
1906
1985
  /**
1907
1986
  * Default MailerMine API base URL.
1908
1987
  */
@@ -1911,16 +1990,28 @@ declare const DEFAULT_BASE_URL = "https://mailermine.com/api/v1";
1911
1990
  * Default request timeout in milliseconds.
1912
1991
  */
1913
1992
  declare const DEFAULT_TIMEOUT_MS = 30000;
1993
+ /**
1994
+ * Default number of automatic retries for 429/502/503/504 and network errors.
1995
+ */
1996
+ declare const DEFAULT_MAX_RETRIES = 2;
1997
+ /**
1998
+ * Default longest single wait between retries, in milliseconds.
1999
+ */
2000
+ declare const DEFAULT_MAX_RETRY_DELAY_MS = 30000;
1914
2001
  /**
1915
2002
  * Default User-Agent header value.
1916
2003
  */
1917
- declare const DEFAULT_USER_AGENT = "mailermine-node/1.0.0";
2004
+ declare const DEFAULT_USER_AGENT = "mailermine-node/1.1.0";
1918
2005
 
1919
2006
  /** Base error thrown for MailerMine API and transport failures. */
1920
2007
  declare class ApiError extends Error {
1921
2008
  readonly status: number;
1922
2009
  readonly body?: unknown | undefined;
1923
2010
  readonly name: string;
2011
+ /** Rate-limit state from the error response, when the API sent it. */
2012
+ rateLimit: RateLimitInfo | null;
2013
+ /** Whether retrying the same request later may succeed (429 and 5xx). */
2014
+ get isRetryable(): boolean;
1924
2015
  constructor(message: string, status: number, body?: unknown | undefined, options?: ErrorOptions);
1925
2016
  }
1926
2017
  /** The API key is missing, invalid, expired, or revoked. */
@@ -1929,7 +2020,20 @@ declare class AuthenticationError extends ApiError {
1929
2020
  }
1930
2021
  /** The account plan or API-key scope does not permit the operation. */
1931
2022
  declare class PlanError extends ApiError {
1932
- readonly name = "PlanError";
2023
+ readonly name: string;
2024
+ }
2025
+ /**
2026
+ * The API key is valid but lacks a scope this endpoint requires (403 with
2027
+ * `errors.scope`). Subclass of PlanError, so existing `instanceof PlanError`
2028
+ * checks keep matching.
2029
+ */
2030
+ declare class MissingScopeError extends PlanError {
2031
+ /** Scopes the key would need, e.g. `['domains.read']`. */
2032
+ readonly missingScopes: readonly string[];
2033
+ readonly name = "MissingScopeError";
2034
+ constructor(message: string, status: number,
2035
+ /** Scopes the key would need, e.g. `['domains.read']`. */
2036
+ missingScopes: readonly string[], body?: unknown, options?: ErrorOptions);
1933
2037
  }
1934
2038
  /** The requested MailerMine object does not exist. */
1935
2039
  declare class NotFoundError extends ApiError {
@@ -1948,4 +2052,48 @@ declare class RateLimitError extends ApiError {
1948
2052
  constructor(message: string, status: number, retryAfter: number | null, body?: unknown, options?: ErrorOptions);
1949
2053
  }
1950
2054
 
1951
- export { Analytics, type AnalyticsFilters, ApiError, type ApiKey, type ApiKeyScope, ApiKeys, type Audience, type AudienceListOptions, type AudienceSource, Audiences, AuthenticationError, type Campaign, type CampaignActivityEntry, type CampaignAnalytics, type CampaignEventEntry, type CampaignLink, type CampaignListOptions, type CampaignPreview, type CampaignProgress, type CampaignRecipient, type CampaignRecipientCount, type CampaignRecipientListOptions, type CampaignRecipientPreview, type CampaignSenderInput, type CampaignStatusSummary, type CampaignTimelineEntry, type CampaignValidation, Campaigns, Collection, Configuration, type ConfigurationOptions, type ConfigureImportInput, type Contact, type ContactList, type ContactListOptions, type ContactStatus, Contacts, type CreateApiKeyInput, type CreateAudienceInput, type CreateCampaignInput, type CreateContactInput, type CreateContactListInput, type CreateDomainInput, type CreateExportInput, type CreateImportInput, type CreateProjectInput, type CreateSegmentInput, type CreateSuppressionInput, type CreateTagInput, type CreateTemplateInput, type CreateWebhookInput, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, DEFAULT_USER_AGENT, type DeleteResult, type DnsRecord, type Domain, type DomainStatus, Domains, type DuplicateCampaignInput, type DuplicateTemplateInput, type EmailAttachmentInput, type EmailEvent, type EmailListOptions, type EmailMessage, Emails, type Event, type EventListOptions, Events, type ExportJob, Exports, type ImportFileInput, type ImportJob, Imports, type JsonObject, type JsonPrimitive, type JsonValue, type ListMembershipResult, type ListOptions, Lists, MailerMine, type MessageListOptions, Messages, NotFoundError, Pagination, type PaginationOptions, PlanError, type PreviewTemplateInput, type Project, type ProjectEnvironment, Projects, RateLimitError, type ReplayWebhookInput, type ResolvedConfiguration, Response, type ScheduleCampaignInput, type Segment, type SegmentListOptions, type SegmentLogic, type SegmentPreview, type SegmentRuleCondition, type SegmentRules, Segments, type SendEmailInput, type SortDirection, type Suppression, type SuppressionCheck, type SuppressionListOptions, type SuppressionReason, Suppressions, type Tag, type TagAssignmentInput, type TagAssignmentResult, type TagListOptions, Tags, type Template, type TemplateBrandingInput, type TemplatePreview, type TemplateStatus, type TemplateTestResult, type TemplateVariableInput, type TemplateVariableType, Templates, type TestTemplateInput, type TestWebhookInput, type UpdateApiKeyInput, type UpdateAudienceInput, type UpdateCampaignInput, type UpdateContactInput, type UpdateContactListInput, type UpdateProjectInput, type UpdateSegmentInput, type UpdateTagInput, type UpdateTemplateInput, type UpdateWebhookInput, VERSION, ValidationError, type Webhook, type WebhookDelivery, type WebhookDeliveryListOptions, type WebhookEventType, type WebhookListOptions, Webhooks };
2055
+ /**
2056
+ * API key scopes. A `.write` scope also grants the matching `.read`;
2057
+ * `admin` grants everything; a key created without scopes has full access.
2058
+ *
2059
+ * @example
2060
+ * ```ts
2061
+ * await mm.apiKeys.create(projectId, { name: 'Mailer', scopes: ScopePresets.sendingOnly });
2062
+ * ```
2063
+ */
2064
+ declare const Scopes: {
2065
+ readonly EmailsSend: "emails.send";
2066
+ readonly EmailsRead: "emails.read";
2067
+ readonly TemplatesRead: "templates.read";
2068
+ readonly TemplatesWrite: "templates.write";
2069
+ readonly DomainsRead: "domains.read";
2070
+ readonly DomainsWrite: "domains.write";
2071
+ readonly ContactsRead: "contacts.read";
2072
+ readonly ContactsWrite: "contacts.write";
2073
+ readonly CampaignsRead: "campaigns.read";
2074
+ readonly CampaignsWrite: "campaigns.write";
2075
+ readonly AnalyticsRead: "analytics.read";
2076
+ readonly BillingRead: "billing.read";
2077
+ readonly ProjectsRead: "projects.read";
2078
+ readonly ProjectsWrite: "projects.write";
2079
+ readonly ApiKeysRead: "api_keys.read";
2080
+ readonly ApiKeysWrite: "api_keys.write";
2081
+ readonly WebhooksRead: "webhooks.read";
2082
+ readonly WebhooksWrite: "webhooks.write";
2083
+ readonly SuppressionsRead: "suppressions.read";
2084
+ readonly SuppressionsWrite: "suppressions.write";
2085
+ readonly EventsRead: "events.read";
2086
+ readonly Admin: "admin";
2087
+ };
2088
+ type Scope = (typeof Scopes)[keyof typeof Scopes];
2089
+ /** Ready-made scope bundles. */
2090
+ declare const ScopePresets: {
2091
+ /** Send email only. */
2092
+ readonly sendingOnly: readonly ["emails.send"];
2093
+ /** Send email and read delivery logs, events and analytics. */
2094
+ readonly sendingAndLogs: readonly ["emails.send", "emails.read", "events.read", "analytics.read"];
2095
+ /** Manage contacts and campaigns; read templates and analytics. */
2096
+ readonly marketing: readonly ["contacts.read", "contacts.write", "campaigns.read", "campaigns.write", "templates.read", "analytics.read"];
2097
+ };
2098
+
2099
+ export { Analytics, type AnalyticsFilters, ApiError, type ApiKey, type ApiKeyScope, ApiKeys, type Audience, type AudienceListOptions, type AudienceSource, Audiences, AuthenticationError, type Campaign, type CampaignActivityEntry, type CampaignAnalytics, type CampaignEventEntry, type CampaignLink, type CampaignListOptions, type CampaignPreview, type CampaignProgress, type CampaignRecipient, type CampaignRecipientCount, type CampaignRecipientListOptions, type CampaignRecipientPreview, type CampaignSenderInput, type CampaignStatusSummary, type CampaignTimelineEntry, type CampaignValidation, Campaigns, Collection, Configuration, type ConfigurationOptions, type ConfigureImportInput, type Contact, type ContactList, type ContactListOptions, type ContactStatus, Contacts, type CreateApiKeyInput, type CreateAudienceInput, type CreateCampaignInput, type CreateContactInput, type CreateContactListInput, type CreateDomainInput, type CreateExportInput, type CreateImportInput, type CreateProjectInput, type CreateSegmentInput, type CreateSuppressionInput, type CreateTagInput, type CreateTemplateInput, type CreateWebhookInput, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_MAX_RETRY_DELAY_MS, DEFAULT_TIMEOUT_MS, DEFAULT_USER_AGENT, type DeleteResult, type DnsRecord, type Domain, type DomainStatus, Domains, type DuplicateCampaignInput, type DuplicateTemplateInput, type EmailAttachmentInput, type EmailEvent, type EmailListOptions, type EmailMessage, Emails, type Event, type EventListOptions, Events, type ExportJob, Exports, type ImportFileInput, type ImportJob, Imports, type JsonObject, type JsonPrimitive, type JsonValue, type ListMembershipResult, type ListOptions, Lists, MailerMine, type MessageListOptions, Messages, MissingScopeError, NotFoundError, Pagination, type PaginationOptions, PlanError, type PreviewTemplateInput, type Project, type ProjectEnvironment, Projects, RateLimitError, RateLimitInfo, type ReplayWebhookInput, type ResolvedConfiguration, Response, type ScheduleCampaignInput, type Scope, ScopePresets, Scopes, type Segment, type SegmentListOptions, type SegmentLogic, type SegmentPreview, type SegmentRuleCondition, type SegmentRules, Segments, type SendEmailInput, type SendEmailOptions, type SortDirection, type Suppression, type SuppressionCheck, type SuppressionListOptions, type SuppressionReason, Suppressions, type Tag, type TagAssignmentInput, type TagAssignmentResult, type TagListOptions, Tags, type Template, type TemplateBrandingInput, type TemplatePreview, type TemplateStatus, type TemplateTestResult, type TemplateVariableInput, type TemplateVariableType, Templates, type TestTemplateInput, type TestWebhookInput, type UpdateApiKeyInput, type UpdateAudienceInput, type UpdateCampaignInput, type UpdateContactInput, type UpdateContactListInput, type UpdateProjectInput, type UpdateSegmentInput, type UpdateTagInput, type UpdateTemplateInput, type UpdateWebhookInput, VERSION, ValidationError, type Webhook, type WebhookDelivery, type WebhookDeliveryListOptions, type WebhookEventType, type WebhookListOptions, Webhooks };
package/dist/index.d.ts CHANGED
@@ -20,6 +20,18 @@ interface ConfigurationOptions {
20
20
  * User-Agent header value sent with every request.
21
21
  */
22
22
  userAgent?: string;
23
+ /**
24
+ * How many times a rate-limited (429), temporarily unavailable
25
+ * (502/503/504) or network-failed request is retried. Defaults to 2;
26
+ * 0 disables retries. Email sends always carry an Idempotency-Key, so a
27
+ * retry is never delivered twice.
28
+ */
29
+ maxRetries?: number;
30
+ /**
31
+ * Longest single wait between retries, in milliseconds. A 429 asking to
32
+ * wait longer than this is thrown as a RateLimitError. Defaults to 30_000.
33
+ */
34
+ maxRetryDelay?: number;
23
35
  /**
24
36
  * Optional fetch implementation. Useful for tests and custom transports.
25
37
  * @internal
@@ -34,6 +46,8 @@ interface ResolvedConfiguration {
34
46
  readonly baseUrl: string;
35
47
  readonly timeout: number;
36
48
  readonly userAgent: string;
49
+ readonly maxRetries: number;
50
+ readonly maxRetryDelay: number;
37
51
  readonly fetchApi?: typeof fetch;
38
52
  }
39
53
 
@@ -47,6 +61,8 @@ declare class Configuration implements ResolvedConfiguration {
47
61
  readonly baseUrl: string;
48
62
  readonly timeout: number;
49
63
  readonly userAgent: string;
64
+ readonly maxRetries: number;
65
+ readonly maxRetryDelay: number;
50
66
  readonly fetchApi?: typeof fetch;
51
67
  constructor(options: ConfigurationOptions);
52
68
  /**
@@ -59,6 +75,26 @@ declare class Configuration implements ResolvedConfiguration {
59
75
  toJSON(): ResolvedConfiguration;
60
76
  }
61
77
 
78
+ /** Rate-limit state reported by the API in `X-RateLimit-*` headers. */
79
+ declare class RateLimitInfo {
80
+ /** Requests allowed per window. */
81
+ readonly limit: number;
82
+ /** Requests left in the current window. */
83
+ readonly remaining: number;
84
+ /** When the window resets, or null if unknown. */
85
+ readonly resetsAt: Date | null;
86
+ constructor(
87
+ /** Requests allowed per window. */
88
+ limit: number,
89
+ /** Requests left in the current window. */
90
+ remaining: number,
91
+ /** When the window resets, or null if unknown. */
92
+ resetsAt: Date | null);
93
+ /** Seconds until the window resets (0 when unknown or past). */
94
+ get secondsUntilReset(): number;
95
+ static fromHeaders(headers: Headers): RateLimitInfo | null;
96
+ }
97
+
62
98
  interface InternalAnalyticsApi {
63
99
  overview(query: object): Promise<unknown>;
64
100
  messages(query: object): Promise<unknown>;
@@ -182,7 +218,9 @@ interface InternalExportsApi {
182
218
  }
183
219
 
184
220
  interface InternalEmailsApi {
185
- send(body: object): Promise<unknown>;
221
+ send(body: object, options?: {
222
+ idempotencyKey?: string;
223
+ }): Promise<unknown>;
186
224
  list(query: object): Promise<unknown>;
187
225
  get(messageId: string): Promise<unknown>;
188
226
  events(messageId: string): Promise<unknown>;
@@ -293,6 +331,15 @@ interface EmailAttachmentInput {
293
331
  content: string;
294
332
  contentType?: string;
295
333
  }
334
+ /** Per-request options for {@link Emails.send}. */
335
+ interface SendEmailOptions {
336
+ /**
337
+ * Unique key (max 255 chars). Repeating a send with the same key and body
338
+ * returns the original response instead of sending again. Generated
339
+ * automatically when omitted.
340
+ */
341
+ idempotencyKey?: string;
342
+ }
296
343
  interface SendEmailInput {
297
344
  from: string;
298
345
  to: string | readonly string[];
@@ -1561,8 +1608,11 @@ declare class Emails extends BaseResource {
1561
1608
  * text: 'Hello',
1562
1609
  * });
1563
1610
  * ```
1611
+ *
1612
+ * Pass `{ idempotencyKey }` to make retries from your own code safe:
1613
+ * the same key never sends twice.
1564
1614
  */
1565
- send(input: SendEmailInput): Promise<Response<EmailMessage>>;
1615
+ send(input: SendEmailInput, options?: SendEmailOptions): Promise<Response<EmailMessage>>;
1566
1616
  /**
1567
1617
  * List recently sent and queued messages for the authenticated project.
1568
1618
  */
@@ -1817,8 +1867,31 @@ declare class Webhooks extends BaseResource {
1817
1867
  replay(webhookId: string, input?: ReplayWebhookInput): Promise<Response<Record<string, unknown>>>;
1818
1868
  /** Retry one webhook delivery. */
1819
1869
  retry(deliveryId: string): Promise<Response<WebhookDelivery>>;
1820
- /** Verify a MailerMine HMAC-SHA256 webhook signature locally. */
1821
- static verify(payload: string, signature: string, secret: string): boolean;
1870
+ /** Default maximum age, in seconds, of a signed webhook timestamp. */
1871
+ static readonly DEFAULT_TOLERANCE_SECONDS = 300;
1872
+ /**
1873
+ * Verify a MailerMine webhook signature locally.
1874
+ *
1875
+ * MailerMine signs `{timestamp}.{rawBody}` with HMAC-SHA256 and sends the
1876
+ * timestamp in `X-MailerMine-Timestamp` and the signature in
1877
+ * `X-MailerMine-Signature` (`sha256=<hex>`). Pass the timestamp so the
1878
+ * signature matches and stale deliveries are rejected (replay protection).
1879
+ * Without a timestamp only a body-only signature is checked (legacy).
1880
+ * Prefer {@link Webhooks.verifyHeaders}.
1881
+ */
1882
+ static verify(payload: string, signature: string, secret: string, timestamp?: string | number | null, toleranceSeconds?: number): boolean;
1883
+ /**
1884
+ * Verify a webhook from its request headers (`X-MailerMine-Signature` and
1885
+ * `X-MailerMine-Timestamp`, falling back to legacy `X-Relay-*`).
1886
+ *
1887
+ * @example
1888
+ * ```ts
1889
+ * app.post('/hooks', express.raw({ type: 'application/json' }), (req, res) => {
1890
+ * if (!Webhooks.verifyHeaders(req.body.toString(), req.headers, secret)) return res.sendStatus(401);
1891
+ * });
1892
+ * ```
1893
+ */
1894
+ static verifyHeaders(payload: string, headers: Headers | Record<string, string | string[] | undefined>, secret: string, toleranceSeconds?: number): boolean;
1822
1895
  }
1823
1896
 
1824
1897
  /**
@@ -1842,6 +1915,7 @@ declare class Webhooks extends BaseResource {
1842
1915
  declare class MailerMine {
1843
1916
  readonly configuration: Configuration;
1844
1917
  private readonly apis;
1918
+ private readonly transport;
1845
1919
  private emailsResource?;
1846
1920
  private projectsResource?;
1847
1921
  private apiKeysResource?;
@@ -1861,6 +1935,11 @@ declare class MailerMine {
1861
1935
  private webhooksResource?;
1862
1936
  private suppressionsResource?;
1863
1937
  constructor(apiKeyOrOptions: string | ConfigurationOptions | Configuration);
1938
+ /**
1939
+ * Rate-limit state from the most recent API response (null until a
1940
+ * response carrying `X-RateLimit-*` headers has been received).
1941
+ */
1942
+ get rateLimit(): RateLimitInfo | null;
1864
1943
  /** Transactional email operations. */
1865
1944
  get emails(): Emails;
1866
1945
  /** Workspace project operations. */
@@ -1902,7 +1981,7 @@ declare class MailerMine {
1902
1981
  /**
1903
1982
  * SDK version. Keep in sync with package.json when releasing.
1904
1983
  */
1905
- declare const VERSION = "1.0.0";
1984
+ declare const VERSION = "1.1.0";
1906
1985
  /**
1907
1986
  * Default MailerMine API base URL.
1908
1987
  */
@@ -1911,16 +1990,28 @@ declare const DEFAULT_BASE_URL = "https://mailermine.com/api/v1";
1911
1990
  * Default request timeout in milliseconds.
1912
1991
  */
1913
1992
  declare const DEFAULT_TIMEOUT_MS = 30000;
1993
+ /**
1994
+ * Default number of automatic retries for 429/502/503/504 and network errors.
1995
+ */
1996
+ declare const DEFAULT_MAX_RETRIES = 2;
1997
+ /**
1998
+ * Default longest single wait between retries, in milliseconds.
1999
+ */
2000
+ declare const DEFAULT_MAX_RETRY_DELAY_MS = 30000;
1914
2001
  /**
1915
2002
  * Default User-Agent header value.
1916
2003
  */
1917
- declare const DEFAULT_USER_AGENT = "mailermine-node/1.0.0";
2004
+ declare const DEFAULT_USER_AGENT = "mailermine-node/1.1.0";
1918
2005
 
1919
2006
  /** Base error thrown for MailerMine API and transport failures. */
1920
2007
  declare class ApiError extends Error {
1921
2008
  readonly status: number;
1922
2009
  readonly body?: unknown | undefined;
1923
2010
  readonly name: string;
2011
+ /** Rate-limit state from the error response, when the API sent it. */
2012
+ rateLimit: RateLimitInfo | null;
2013
+ /** Whether retrying the same request later may succeed (429 and 5xx). */
2014
+ get isRetryable(): boolean;
1924
2015
  constructor(message: string, status: number, body?: unknown | undefined, options?: ErrorOptions);
1925
2016
  }
1926
2017
  /** The API key is missing, invalid, expired, or revoked. */
@@ -1929,7 +2020,20 @@ declare class AuthenticationError extends ApiError {
1929
2020
  }
1930
2021
  /** The account plan or API-key scope does not permit the operation. */
1931
2022
  declare class PlanError extends ApiError {
1932
- readonly name = "PlanError";
2023
+ readonly name: string;
2024
+ }
2025
+ /**
2026
+ * The API key is valid but lacks a scope this endpoint requires (403 with
2027
+ * `errors.scope`). Subclass of PlanError, so existing `instanceof PlanError`
2028
+ * checks keep matching.
2029
+ */
2030
+ declare class MissingScopeError extends PlanError {
2031
+ /** Scopes the key would need, e.g. `['domains.read']`. */
2032
+ readonly missingScopes: readonly string[];
2033
+ readonly name = "MissingScopeError";
2034
+ constructor(message: string, status: number,
2035
+ /** Scopes the key would need, e.g. `['domains.read']`. */
2036
+ missingScopes: readonly string[], body?: unknown, options?: ErrorOptions);
1933
2037
  }
1934
2038
  /** The requested MailerMine object does not exist. */
1935
2039
  declare class NotFoundError extends ApiError {
@@ -1948,4 +2052,48 @@ declare class RateLimitError extends ApiError {
1948
2052
  constructor(message: string, status: number, retryAfter: number | null, body?: unknown, options?: ErrorOptions);
1949
2053
  }
1950
2054
 
1951
- export { Analytics, type AnalyticsFilters, ApiError, type ApiKey, type ApiKeyScope, ApiKeys, type Audience, type AudienceListOptions, type AudienceSource, Audiences, AuthenticationError, type Campaign, type CampaignActivityEntry, type CampaignAnalytics, type CampaignEventEntry, type CampaignLink, type CampaignListOptions, type CampaignPreview, type CampaignProgress, type CampaignRecipient, type CampaignRecipientCount, type CampaignRecipientListOptions, type CampaignRecipientPreview, type CampaignSenderInput, type CampaignStatusSummary, type CampaignTimelineEntry, type CampaignValidation, Campaigns, Collection, Configuration, type ConfigurationOptions, type ConfigureImportInput, type Contact, type ContactList, type ContactListOptions, type ContactStatus, Contacts, type CreateApiKeyInput, type CreateAudienceInput, type CreateCampaignInput, type CreateContactInput, type CreateContactListInput, type CreateDomainInput, type CreateExportInput, type CreateImportInput, type CreateProjectInput, type CreateSegmentInput, type CreateSuppressionInput, type CreateTagInput, type CreateTemplateInput, type CreateWebhookInput, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, DEFAULT_USER_AGENT, type DeleteResult, type DnsRecord, type Domain, type DomainStatus, Domains, type DuplicateCampaignInput, type DuplicateTemplateInput, type EmailAttachmentInput, type EmailEvent, type EmailListOptions, type EmailMessage, Emails, type Event, type EventListOptions, Events, type ExportJob, Exports, type ImportFileInput, type ImportJob, Imports, type JsonObject, type JsonPrimitive, type JsonValue, type ListMembershipResult, type ListOptions, Lists, MailerMine, type MessageListOptions, Messages, NotFoundError, Pagination, type PaginationOptions, PlanError, type PreviewTemplateInput, type Project, type ProjectEnvironment, Projects, RateLimitError, type ReplayWebhookInput, type ResolvedConfiguration, Response, type ScheduleCampaignInput, type Segment, type SegmentListOptions, type SegmentLogic, type SegmentPreview, type SegmentRuleCondition, type SegmentRules, Segments, type SendEmailInput, type SortDirection, type Suppression, type SuppressionCheck, type SuppressionListOptions, type SuppressionReason, Suppressions, type Tag, type TagAssignmentInput, type TagAssignmentResult, type TagListOptions, Tags, type Template, type TemplateBrandingInput, type TemplatePreview, type TemplateStatus, type TemplateTestResult, type TemplateVariableInput, type TemplateVariableType, Templates, type TestTemplateInput, type TestWebhookInput, type UpdateApiKeyInput, type UpdateAudienceInput, type UpdateCampaignInput, type UpdateContactInput, type UpdateContactListInput, type UpdateProjectInput, type UpdateSegmentInput, type UpdateTagInput, type UpdateTemplateInput, type UpdateWebhookInput, VERSION, ValidationError, type Webhook, type WebhookDelivery, type WebhookDeliveryListOptions, type WebhookEventType, type WebhookListOptions, Webhooks };
2055
+ /**
2056
+ * API key scopes. A `.write` scope also grants the matching `.read`;
2057
+ * `admin` grants everything; a key created without scopes has full access.
2058
+ *
2059
+ * @example
2060
+ * ```ts
2061
+ * await mm.apiKeys.create(projectId, { name: 'Mailer', scopes: ScopePresets.sendingOnly });
2062
+ * ```
2063
+ */
2064
+ declare const Scopes: {
2065
+ readonly EmailsSend: "emails.send";
2066
+ readonly EmailsRead: "emails.read";
2067
+ readonly TemplatesRead: "templates.read";
2068
+ readonly TemplatesWrite: "templates.write";
2069
+ readonly DomainsRead: "domains.read";
2070
+ readonly DomainsWrite: "domains.write";
2071
+ readonly ContactsRead: "contacts.read";
2072
+ readonly ContactsWrite: "contacts.write";
2073
+ readonly CampaignsRead: "campaigns.read";
2074
+ readonly CampaignsWrite: "campaigns.write";
2075
+ readonly AnalyticsRead: "analytics.read";
2076
+ readonly BillingRead: "billing.read";
2077
+ readonly ProjectsRead: "projects.read";
2078
+ readonly ProjectsWrite: "projects.write";
2079
+ readonly ApiKeysRead: "api_keys.read";
2080
+ readonly ApiKeysWrite: "api_keys.write";
2081
+ readonly WebhooksRead: "webhooks.read";
2082
+ readonly WebhooksWrite: "webhooks.write";
2083
+ readonly SuppressionsRead: "suppressions.read";
2084
+ readonly SuppressionsWrite: "suppressions.write";
2085
+ readonly EventsRead: "events.read";
2086
+ readonly Admin: "admin";
2087
+ };
2088
+ type Scope = (typeof Scopes)[keyof typeof Scopes];
2089
+ /** Ready-made scope bundles. */
2090
+ declare const ScopePresets: {
2091
+ /** Send email only. */
2092
+ readonly sendingOnly: readonly ["emails.send"];
2093
+ /** Send email and read delivery logs, events and analytics. */
2094
+ readonly sendingAndLogs: readonly ["emails.send", "emails.read", "events.read", "analytics.read"];
2095
+ /** Manage contacts and campaigns; read templates and analytics. */
2096
+ readonly marketing: readonly ["contacts.read", "contacts.write", "campaigns.read", "campaigns.write", "templates.read", "analytics.read"];
2097
+ };
2098
+
2099
+ export { Analytics, type AnalyticsFilters, ApiError, type ApiKey, type ApiKeyScope, ApiKeys, type Audience, type AudienceListOptions, type AudienceSource, Audiences, AuthenticationError, type Campaign, type CampaignActivityEntry, type CampaignAnalytics, type CampaignEventEntry, type CampaignLink, type CampaignListOptions, type CampaignPreview, type CampaignProgress, type CampaignRecipient, type CampaignRecipientCount, type CampaignRecipientListOptions, type CampaignRecipientPreview, type CampaignSenderInput, type CampaignStatusSummary, type CampaignTimelineEntry, type CampaignValidation, Campaigns, Collection, Configuration, type ConfigurationOptions, type ConfigureImportInput, type Contact, type ContactList, type ContactListOptions, type ContactStatus, Contacts, type CreateApiKeyInput, type CreateAudienceInput, type CreateCampaignInput, type CreateContactInput, type CreateContactListInput, type CreateDomainInput, type CreateExportInput, type CreateImportInput, type CreateProjectInput, type CreateSegmentInput, type CreateSuppressionInput, type CreateTagInput, type CreateTemplateInput, type CreateWebhookInput, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_MAX_RETRY_DELAY_MS, DEFAULT_TIMEOUT_MS, DEFAULT_USER_AGENT, type DeleteResult, type DnsRecord, type Domain, type DomainStatus, Domains, type DuplicateCampaignInput, type DuplicateTemplateInput, type EmailAttachmentInput, type EmailEvent, type EmailListOptions, type EmailMessage, Emails, type Event, type EventListOptions, Events, type ExportJob, Exports, type ImportFileInput, type ImportJob, Imports, type JsonObject, type JsonPrimitive, type JsonValue, type ListMembershipResult, type ListOptions, Lists, MailerMine, type MessageListOptions, Messages, MissingScopeError, NotFoundError, Pagination, type PaginationOptions, PlanError, type PreviewTemplateInput, type Project, type ProjectEnvironment, Projects, RateLimitError, RateLimitInfo, type ReplayWebhookInput, type ResolvedConfiguration, Response, type ScheduleCampaignInput, type Scope, ScopePresets, Scopes, type Segment, type SegmentListOptions, type SegmentLogic, type SegmentPreview, type SegmentRuleCondition, type SegmentRules, Segments, type SendEmailInput, type SendEmailOptions, type SortDirection, type Suppression, type SuppressionCheck, type SuppressionListOptions, type SuppressionReason, Suppressions, type Tag, type TagAssignmentInput, type TagAssignmentResult, type TagListOptions, Tags, type Template, type TemplateBrandingInput, type TemplatePreview, type TemplateStatus, type TemplateTestResult, type TemplateVariableInput, type TemplateVariableType, Templates, type TestTemplateInput, type TestWebhookInput, type UpdateApiKeyInput, type UpdateAudienceInput, type UpdateCampaignInput, type UpdateContactInput, type UpdateContactListInput, type UpdateProjectInput, type UpdateSegmentInput, type UpdateTagInput, type UpdateTemplateInput, type UpdateWebhookInput, VERSION, ValidationError, type Webhook, type WebhookDelivery, type WebhookDeliveryListOptions, type WebhookEventType, type WebhookListOptions, Webhooks };