mail-time 5.1.0 → 5.2.0

package/index.d.cts

@@ -50,15 +50,103 @@ export type MailTimeScheduler = {
     ping: () => Promise<MailTimePingResult>;
     setInterval: (func: (...args: any[]) => unknown, delay: number, uid: string) => Promise<string>;
     destroy: () => boolean;
+    shutdown: (opts?: {
+        timeout?: number;
+    }) => Promise<boolean>;
     pause: (timerId?: string) => boolean;
     resume: (timerId?: string) => boolean;
 };
+export type MailTimeMailbox = string | {
+    address: string;
+    name?: string;
+};
+export type MailTimePolicyRecipient = {
+    address: string;
+    sources: Array<"envelope" | "to" | "cc" | "bcc">;
+};
+export type MailTimePolicyDecision = {
+    address: string;
+    status: "suppressed" | "rejected" | "retry";
+    reason: string;
+};
+export type MailTimePolicyResult = {
+    decisions?: MailTimePolicyDecision[];
+};
+export type MailTimePolicyTransport = {
+    index: number;
+    name?: string;
+};
+export type MailTimePolicyEnvelope = {
+    from?: string;
+    to: string[];
+};
+export type MailTimePolicyContext = {
+    task: MailTimeTask;
+    attempt: number;
+    transport: MailTimePolicyTransport;
+    envelope: MailTimePolicyEnvelope;
+    recipients: MailTimePolicyRecipient[];
+};
+export type MailTimeBeforeSendPolicyContext = MailTimePolicyContext;
+export type MailTimeStructuredRejection = {
+    address: string | null;
+    command?: string;
+    responseCode?: number;
+    response?: string;
+    message?: string;
+    transportIndex: number;
+    transportName?: string;
+};
+export type MailTimeRejectionPolicyContext = MailTimePolicyContext & {
+    error?: unknown;
+    info?: unknown;
+    rejections: MailTimeStructuredRejection[];
+};
+export type MailTimeRecipientResult = {
+    address: string;
+    status: "sent" | "error" | "suppressed" | "rejected";
+    sources?: Array<"envelope" | "to" | "cc" | "bcc">;
+    reasons: Array<{
+        provider: string;
+        reason: string;
+    }>;
+    attempt: number;
+    transportIndex?: number;
+    transportName?: string;
+    command?: string;
+    responseCode?: number;
+    response?: string;
+    message?: string;
+};
+export type MailTimeRecipientAttemptContext = MailTimeRejectionPolicyContext & {
+    decisions: MailTimeRecipientResult[];
+};
+export type MailTimeRecipientSummary = {
+    uuid: string;
+    tries: number;
+    isSettled: boolean;
+    recipients: {
+        sent: MailTimeRecipientResult[];
+        error: MailTimeRecipientResult[];
+        suppressed: MailTimeRecipientResult[];
+        rejected: MailTimeRecipientResult[];
+    };
+};
+export type MailTimeRecipientPolicy = {
+    name: string;
+    failureMode?: "retry" | "continue";
+    beforeSend?: (context: MailTimeBeforeSendPolicyContext) => void | MailTimePolicyResult | Promise<void | MailTimePolicyResult>;
+    classifyRejections?: (context: MailTimeRejectionPolicyContext) => void | MailTimePolicyResult | Promise<void | MailTimePolicyResult>;
+    observeAttempt?: (context: MailTimeRecipientAttemptContext) => void | Promise<void>;
+};
 export type MailTimeTask = {
     uuid: string;
-    to?: string | string[];
+    to?: MailTimeMailbox | MailTimeMailbox[];
     tries: number;
     sendAt: number;
     isSent: boolean;
+    isSettled?: boolean;
+    recipientResults?: MailTimeRecipientResult[];
     isCancelled: boolean;
     isFailed: boolean;
     isSending?: boolean;
@@ -84,6 +172,7 @@ export type CustomQueue = {
     }) => Promise<boolean>;
     update: (email: MailTimeTask | object, updateObj: object) => Promise<boolean>;
     ready?: () => Promise<void>;
+    supportsRecipientPolicies?: boolean;
 };
 export type MailTimeRejectedRecipient = {
     address: string;
@@ -91,7 +180,9 @@ export type MailTimeRejectedRecipient = {
 };
 export type MailTimeMailOptions = {
     [key: string]: any;
-    to: string | string[];
+    to: MailTimeMailbox | MailTimeMailbox[];
+    cc?: MailTimeMailbox | MailTimeMailbox[];
+    bcc?: MailTimeMailbox | MailTimeMailbox[];
     sendAt?: Date | number;
     template?: string;
     concatSubject?: string;
@@ -139,8 +230,11 @@ export type MailTimeOptions = {
     prefix?: string;
     debug?: boolean;
     josk?: MailTimeJoSkOptions;
-    onError?: (error: unknown, email: MailTimeTask | null, details?: object) => void;
-    onSent?: (email: MailTimeTask, details?: object) => void;
+    recipientPolicies?: MailTimeRecipientPolicy[];
+    onError?: (error: unknown, email: MailTimeTask | null, details?: object, recipients?: MailTimeRecipientResult[], summary?: MailTimeRecipientSummary) => void | Promise<void>;
+    onSent?: (email: MailTimeTask, details?: object, recipients?: MailTimeRecipientResult[], summary?: MailTimeRecipientSummary) => void | Promise<void>;
+    onSuppressed?: (email: MailTimeTask, recipients: MailTimeRecipientResult[], summary: MailTimeRecipientSummary) => void | Promise<void>;
+    onRejected?: (email: MailTimeTask, recipients: MailTimeRecipientResult[], summary: MailTimeRecipientSummary) => void | Promise<void>;
 };
 /**
  * @typedef {import('./presets.js').MailTimePresetName} MailTimePresetName
@@ -167,22 +261,41 @@ export type MailTimeOptions = {
  * @typedef {{ [key: string]: any, adapter: MailTimeJoSkAdapterOptions | object, debug?: boolean, autoClear?: boolean, zombieTime?: number, lockLeaseTime?: number, minRevolvingDelay?: number, maxRevolvingDelay?: number, execute?: 'batch' | 'one', concurrency?: number, lockOwnerId?: string, resetOnInit?: boolean, onError?: (title: string, details: object) => void, onExecuted?: (uid: string, details: object) => void }} MailTimeJoSkOptions
  */
 /**
- * @typedef {{ [key: string]: any, ping: () => Promise<MailTimePingResult>, setInterval: (func: (...args: any[]) => unknown, delay: number, uid: string) => Promise<string>, destroy: () => boolean, pause: (timerId?: string) => boolean, resume: (timerId?: string) => boolean }} MailTimeScheduler
+ * @typedef {{ [key: string]: any, ping: () => Promise<MailTimePingResult>, setInterval: (func: (...args: any[]) => unknown, delay: number, uid: string) => Promise<string>, destroy: () => boolean, shutdown: (opts?: { timeout?: number }) => Promise<boolean>, pause: (timerId?: string) => boolean, resume: (timerId?: string) => boolean }} MailTimeScheduler
+ */
+/**
+ * @typedef {string | { address: string, name?: string }} MailTimeMailbox
  */
 /**
- * @typedef {{ uuid: string, to?: string | string[], tries: number, sendAt: number, isSent: boolean, isCancelled: boolean, isFailed: boolean, isSending?: boolean, sendingAt?: number, template?: string | false, transport: number, concatSubject?: string | false, mailOptions: MailTimeMailOptions[] }} MailTimeTask
+ * @typedef {{ address: string, sources: Array<'envelope' | 'to' | 'cc' | 'bcc'> }} MailTimePolicyRecipient
+ * @typedef {{ address: string, status: 'suppressed' | 'rejected' | 'retry', reason: string }} MailTimePolicyDecision
+ * @typedef {{ decisions?: MailTimePolicyDecision[] }} MailTimePolicyResult
+ * @typedef {{ index: number, name?: string }} MailTimePolicyTransport
+ * @typedef {{ from?: string, to: string[] }} MailTimePolicyEnvelope
+ * @typedef {{ task: MailTimeTask, attempt: number, transport: MailTimePolicyTransport, envelope: MailTimePolicyEnvelope, recipients: MailTimePolicyRecipient[] }} MailTimePolicyContext
+ * @typedef {MailTimePolicyContext} MailTimeBeforeSendPolicyContext
+ * @typedef {{ address: string | null, command?: string, responseCode?: number, response?: string, message?: string, transportIndex: number, transportName?: string }} MailTimeStructuredRejection
+ * @typedef {MailTimePolicyContext & { error?: unknown, info?: unknown, rejections: MailTimeStructuredRejection[] }} MailTimeRejectionPolicyContext
+ * @typedef {{ address: string, status: 'sent' | 'error' | 'suppressed' | 'rejected', sources?: Array<'envelope' | 'to' | 'cc' | 'bcc'>, reasons: Array<{ provider: string, reason: string }>, attempt: number, transportIndex?: number, transportName?: string, command?: string, responseCode?: number, response?: string, message?: string }} MailTimeRecipientResult
+ * @typedef {MailTimeRejectionPolicyContext & { decisions: MailTimeRecipientResult[] }} MailTimeRecipientAttemptContext
+ * @typedef {{ uuid: string, tries: number, isSettled: boolean, recipients: { sent: MailTimeRecipientResult[], error: MailTimeRecipientResult[], suppressed: MailTimeRecipientResult[], rejected: MailTimeRecipientResult[] } }} MailTimeRecipientSummary
+ * @typedef {{ name: string, failureMode?: 'retry' | 'continue', beforeSend?: (context: MailTimeBeforeSendPolicyContext) => void | MailTimePolicyResult | Promise<void | MailTimePolicyResult>, classifyRejections?: (context: MailTimeRejectionPolicyContext) => void | MailTimePolicyResult | Promise<void | MailTimePolicyResult>, observeAttempt?: (context: MailTimeRecipientAttemptContext) => void | Promise<void> }} MailTimeRecipientPolicy
+ * @description Policy contexts are read-only by contract. Providers must bound their own I/O; renewal budgets do not limit hook duration.
+ */
+/**
+ * @typedef {{ uuid: string, to?: MailTimeMailbox | MailTimeMailbox[], tries: number, sendAt: number, isSent: boolean, isSettled?: boolean, recipientResults?: MailTimeRecipientResult[], isCancelled: boolean, isFailed: boolean, isSending?: boolean, sendingAt?: number, template?: string | false, transport: number, concatSubject?: string | false, mailOptions: MailTimeMailOptions[] }} MailTimeTask
  */
 /**
  * @typedef {{ limit?: number, sendingTimeout?: number }} MailTimeIterateOptions
  */
 /**
- * @typedef {{ ping: () => Promise<MailTimePingResult>, iterate: (opts?: MailTimeIterateOptions) => Promise<void> | void, getPendingTo: (to: string, sendAt: number) => Promise<MailTimeTask | object | null>, push: (email: MailTimeTask) => Promise<void> | void, cancel: (uuid: string) => Promise<boolean>, remove: (email: MailTimeTask | object, opts?: { leaseTries: number, leaseSendingAt: number }) => Promise<boolean>, update: (email: MailTimeTask | object, updateObj: object) => Promise<boolean>, ready?: () => Promise<void> }} CustomQueue
+ * @typedef {{ ping: () => Promise<MailTimePingResult>, iterate: (opts?: MailTimeIterateOptions) => Promise<void> | void, getPendingTo: (to: string, sendAt: number) => Promise<MailTimeTask | object | null>, push: (email: MailTimeTask) => Promise<void> | void, cancel: (uuid: string) => Promise<boolean>, remove: (email: MailTimeTask | object, opts?: { leaseTries: number, leaseSendingAt: number }) => Promise<boolean>, update: (email: MailTimeTask | object, updateObj: object) => Promise<boolean>, ready?: () => Promise<void>, supportsRecipientPolicies?: boolean }} CustomQueue
  */
 /**
  * @typedef {{ address: string, error: string }} MailTimeRejectedRecipient
  */
 /**
- * @typedef {{ [key: string]: any, to: string | string[], sendAt?: Date | number, template?: string, concatSubject?: string, text?: string | false, html?: string | false, subject?: string, accepted?: string[], rejected?: MailTimeRejectedRecipient[] }} MailTimeMailOptions
+ * @typedef {{ [key: string]: any, to: MailTimeMailbox | MailTimeMailbox[], cc?: MailTimeMailbox | MailTimeMailbox[], bcc?: MailTimeMailbox | MailTimeMailbox[], sendAt?: Date | number, template?: string, concatSubject?: string, text?: string | false, html?: string | false, subject?: string, accepted?: string[], rejected?: MailTimeRejectedRecipient[] }} MailTimeMailOptions
  */
 /**
  * @typedef {{ subject?: string }} MailTimeConcatEmailsOptions
@@ -191,9 +304,15 @@ export type MailTimeOptions = {
  * @typedef {{ index: number, from: string | undefined }} MailTimeFromDetails
  */
 /**
- * @typedef {{ queue: RedisQueue | MongoQueue | PostgresQueue | CustomQueue, type?: 'server' | 'client', from?: string | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string), transports?: MailTimeTransport[], strategy?: 'backup' | 'balancer', failsToNext?: number, shouldFailOver?: (error: unknown, info: object | undefined, email: MailTimeTask) => boolean, retries?: number, maxTries?: number, retryDelay?: number, interval?: number, keepHistory?: boolean, concatEmails?: boolean | MailTimeConcatEmailsOptions, concatSubject?: string, concatDelimiter?: string, concatDelay?: number, concatThrottling?: number, revolvingInterval?: number, mode?: 'one' | 'batch', concurrency?: number, sendingTimeout?: number, renewClaim?: boolean | number, maxRenewals?: number, strictPayload?: boolean, allowedMailFields?: string[], verifyTransports?: boolean, template?: string, prefix?: string, debug?: boolean, josk?: MailTimeJoSkOptions, onError?: (error: unknown, email: MailTimeTask | null, details?: object) => void, onSent?: (email: MailTimeTask, details?: object) => void }} MailTimeOptions
+ * @typedef {{ queue: RedisQueue | MongoQueue | PostgresQueue | CustomQueue, type?: 'server' | 'client', from?: string | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string), transports?: MailTimeTransport[], strategy?: 'backup' | 'balancer', failsToNext?: number, shouldFailOver?: (error: unknown, info: object | undefined, email: MailTimeTask) => boolean, retries?: number, maxTries?: number, retryDelay?: number, interval?: number, keepHistory?: boolean, concatEmails?: boolean | MailTimeConcatEmailsOptions, concatSubject?: string, concatDelimiter?: string, concatDelay?: number, concatThrottling?: number, revolvingInterval?: number, mode?: 'one' | 'batch', concurrency?: number, sendingTimeout?: number, renewClaim?: boolean | number, maxRenewals?: number, strictPayload?: boolean, allowedMailFields?: string[], verifyTransports?: boolean, template?: string, prefix?: string, debug?: boolean, josk?: MailTimeJoSkOptions, recipientPolicies?: MailTimeRecipientPolicy[], onError?: (error: unknown, email: MailTimeTask | null, details?: object, recipients?: MailTimeRecipientResult[], summary?: MailTimeRecipientSummary) => void | Promise<void>, onSent?: (email: MailTimeTask, details?: object, recipients?: MailTimeRecipientResult[], summary?: MailTimeRecipientSummary) => void | Promise<void>, onSuppressed?: (email: MailTimeTask, recipients: MailTimeRecipientResult[], summary: MailTimeRecipientSummary) => void | Promise<void>, onRejected?: (email: MailTimeTask, recipients: MailTimeRecipientResult[], summary: MailTimeRecipientSummary) => void | Promise<void> }} MailTimeOptions
+ */
+/**
+ * Class of MailTime.
+ * With recipientPolicies, terminal callbacks receive grouped recipients and a complete summary after persistence.
+ * isSettled includes exhausted errors; isSent means all accepted; isFailed means an error or permanent rejection.
+ * Unparseable terminal preparation failures invoke onError with an empty recipient group.
+ * Hooks must bound their own I/O. Callback notifications are best-effort, not durable exactly-once delivery.
  */
-/** Class of MailTime */
 export class MailTime {
     static set Template(newVal: string);
     static get Template(): string;
@@ -223,8 +342,10 @@ export class MailTime {
     retryDelay: number;
     template: string;
     keepHistory: boolean;
-    onSent: (email: MailTimeTask, details?: object) => void;
-    onError: (error: unknown, email: MailTimeTask | null, details?: object) => void;
+    onSent: (email: MailTimeTask, details?: object, recipients?: MailTimeRecipientResult[], summary?: MailTimeRecipientSummary) => void | Promise<void>;
+    onError: (error: unknown, email: MailTimeTask | null, details?: object, recipients?: MailTimeRecipientResult[], summary?: MailTimeRecipientSummary) => void | Promise<void>;
+    onSuppressed: (email: MailTimeTask, recipients: MailTimeRecipientResult[], summary: MailTimeRecipientSummary) => void | Promise<void>;
+    onRejected: (email: MailTimeTask, recipients: MailTimeRecipientResult[], summary: MailTimeRecipientSummary) => void | Promise<void>;
     revolvingInterval: number;
     mode: "one" | "batch";
     concurrency: number;
@@ -283,12 +404,13 @@ export class MailTime {
     /**
      * @memberOf MailTime
      * @name destroy
-     * @description Stop the scheduler and block future dispatches. Without `{ drain: true }`, any in-flight SMTP attempts are neutralized on completion — they perform no storage writes, no `onSent`/`onError` callbacks, and no logging once `destroy()` returns; their claimed rows are recovered by stale-lock timeout (`sendingTimeout`). Pass `{ drain: true }` to instead let in-flight attempts run to completion (returns a Promise that resolves once they settle).
-     * @param {{ drain?: boolean }} [opts]
+     * @description Stop the scheduler and block future dispatches. Without `{ drain: true }`, in-flight SMTP attempts are neutralized and their claims recover after `sendingTimeout`. With `{ drain: true }`, await JoSk shutdown and in-flight SMTP; resolves false if a scheduler handler exceeds `schedulerTimeout` (default 10000ms) or JoSk shutdown throws (logged); never rejects. The timeout does not bound SMTP drain time.
+     * @param {{ drain?: boolean, schedulerTimeout?: number }} [opts] - schedulerTimeout must be finite and non-negative; used only with drain
      * @returns {boolean | Promise<boolean>}
      */
     destroy(opts?: {
         drain?: boolean;
+        schedulerTimeout?: number;
     }): boolean | Promise<boolean>;
     /**
      * @async

package/index.d.ts

@@ -50,15 +50,103 @@ export type MailTimeScheduler = {
     ping: () => Promise<MailTimePingResult>;
     setInterval: (func: (...args: any[]) => unknown, delay: number, uid: string) => Promise<string>;
     destroy: () => boolean;
+    shutdown: (opts?: {
+        timeout?: number;
+    }) => Promise<boolean>;
     pause: (timerId?: string) => boolean;
     resume: (timerId?: string) => boolean;
 };
+export type MailTimeMailbox = string | {
+    address: string;
+    name?: string;
+};
+export type MailTimePolicyRecipient = {
+    address: string;
+    sources: Array<"envelope" | "to" | "cc" | "bcc">;
+};
+export type MailTimePolicyDecision = {
+    address: string;
+    status: "suppressed" | "rejected" | "retry";
+    reason: string;
+};
+export type MailTimePolicyResult = {
+    decisions?: MailTimePolicyDecision[];
+};
+export type MailTimePolicyTransport = {
+    index: number;
+    name?: string;
+};
+export type MailTimePolicyEnvelope = {
+    from?: string;
+    to: string[];
+};
+export type MailTimePolicyContext = {
+    task: MailTimeTask;
+    attempt: number;
+    transport: MailTimePolicyTransport;
+    envelope: MailTimePolicyEnvelope;
+    recipients: MailTimePolicyRecipient[];
+};
+export type MailTimeBeforeSendPolicyContext = MailTimePolicyContext;
+export type MailTimeStructuredRejection = {
+    address: string | null;
+    command?: string;
+    responseCode?: number;
+    response?: string;
+    message?: string;
+    transportIndex: number;
+    transportName?: string;
+};
+export type MailTimeRejectionPolicyContext = MailTimePolicyContext & {
+    error?: unknown;
+    info?: unknown;
+    rejections: MailTimeStructuredRejection[];
+};
+export type MailTimeRecipientResult = {
+    address: string;
+    status: "sent" | "error" | "suppressed" | "rejected";
+    sources?: Array<"envelope" | "to" | "cc" | "bcc">;
+    reasons: Array<{
+        provider: string;
+        reason: string;
+    }>;
+    attempt: number;
+    transportIndex?: number;
+    transportName?: string;
+    command?: string;
+    responseCode?: number;
+    response?: string;
+    message?: string;
+};
+export type MailTimeRecipientAttemptContext = MailTimeRejectionPolicyContext & {
+    decisions: MailTimeRecipientResult[];
+};
+export type MailTimeRecipientSummary = {
+    uuid: string;
+    tries: number;
+    isSettled: boolean;
+    recipients: {
+        sent: MailTimeRecipientResult[];
+        error: MailTimeRecipientResult[];
+        suppressed: MailTimeRecipientResult[];
+        rejected: MailTimeRecipientResult[];
+    };
+};
+export type MailTimeRecipientPolicy = {
+    name: string;
+    failureMode?: "retry" | "continue";
+    beforeSend?: (context: MailTimeBeforeSendPolicyContext) => void | MailTimePolicyResult | Promise<void | MailTimePolicyResult>;
+    classifyRejections?: (context: MailTimeRejectionPolicyContext) => void | MailTimePolicyResult | Promise<void | MailTimePolicyResult>;
+    observeAttempt?: (context: MailTimeRecipientAttemptContext) => void | Promise<void>;
+};
 export type MailTimeTask = {
     uuid: string;
-    to?: string | string[];
+    to?: MailTimeMailbox | MailTimeMailbox[];
     tries: number;
     sendAt: number;
     isSent: boolean;
+    isSettled?: boolean;
+    recipientResults?: MailTimeRecipientResult[];
     isCancelled: boolean;
     isFailed: boolean;
     isSending?: boolean;
@@ -84,6 +172,7 @@ export type CustomQueue = {
     }) => Promise<boolean>;
     update: (email: MailTimeTask | object, updateObj: object) => Promise<boolean>;
     ready?: () => Promise<void>;
+    supportsRecipientPolicies?: boolean;
 };
 export type MailTimeRejectedRecipient = {
     address: string;
@@ -91,7 +180,9 @@ export type MailTimeRejectedRecipient = {
 };
 export type MailTimeMailOptions = {
     [key: string]: any;
-    to: string | string[];
+    to: MailTimeMailbox | MailTimeMailbox[];
+    cc?: MailTimeMailbox | MailTimeMailbox[];
+    bcc?: MailTimeMailbox | MailTimeMailbox[];
     sendAt?: Date | number;
     template?: string;
     concatSubject?: string;
@@ -139,8 +230,11 @@ export type MailTimeOptions = {
     prefix?: string;
     debug?: boolean;
     josk?: MailTimeJoSkOptions;
-    onError?: (error: unknown, email: MailTimeTask | null, details?: object) => void;
-    onSent?: (email: MailTimeTask, details?: object) => void;
+    recipientPolicies?: MailTimeRecipientPolicy[];
+    onError?: (error: unknown, email: MailTimeTask | null, details?: object, recipients?: MailTimeRecipientResult[], summary?: MailTimeRecipientSummary) => void | Promise<void>;
+    onSent?: (email: MailTimeTask, details?: object, recipients?: MailTimeRecipientResult[], summary?: MailTimeRecipientSummary) => void | Promise<void>;
+    onSuppressed?: (email: MailTimeTask, recipients: MailTimeRecipientResult[], summary: MailTimeRecipientSummary) => void | Promise<void>;
+    onRejected?: (email: MailTimeTask, recipients: MailTimeRecipientResult[], summary: MailTimeRecipientSummary) => void | Promise<void>;
 };
 /**
  * @typedef {import('./presets.js').MailTimePresetName} MailTimePresetName
@@ -167,22 +261,41 @@ export type MailTimeOptions = {
  * @typedef {{ [key: string]: any, adapter: MailTimeJoSkAdapterOptions | object, debug?: boolean, autoClear?: boolean, zombieTime?: number, lockLeaseTime?: number, minRevolvingDelay?: number, maxRevolvingDelay?: number, execute?: 'batch' | 'one', concurrency?: number, lockOwnerId?: string, resetOnInit?: boolean, onError?: (title: string, details: object) => void, onExecuted?: (uid: string, details: object) => void }} MailTimeJoSkOptions
  */
 /**
- * @typedef {{ [key: string]: any, ping: () => Promise<MailTimePingResult>, setInterval: (func: (...args: any[]) => unknown, delay: number, uid: string) => Promise<string>, destroy: () => boolean, pause: (timerId?: string) => boolean, resume: (timerId?: string) => boolean }} MailTimeScheduler
+ * @typedef {{ [key: string]: any, ping: () => Promise<MailTimePingResult>, setInterval: (func: (...args: any[]) => unknown, delay: number, uid: string) => Promise<string>, destroy: () => boolean, shutdown: (opts?: { timeout?: number }) => Promise<boolean>, pause: (timerId?: string) => boolean, resume: (timerId?: string) => boolean }} MailTimeScheduler
+ */
+/**
+ * @typedef {string | { address: string, name?: string }} MailTimeMailbox
  */
 /**
- * @typedef {{ uuid: string, to?: string | string[], tries: number, sendAt: number, isSent: boolean, isCancelled: boolean, isFailed: boolean, isSending?: boolean, sendingAt?: number, template?: string | false, transport: number, concatSubject?: string | false, mailOptions: MailTimeMailOptions[] }} MailTimeTask
+ * @typedef {{ address: string, sources: Array<'envelope' | 'to' | 'cc' | 'bcc'> }} MailTimePolicyRecipient
+ * @typedef {{ address: string, status: 'suppressed' | 'rejected' | 'retry', reason: string }} MailTimePolicyDecision
+ * @typedef {{ decisions?: MailTimePolicyDecision[] }} MailTimePolicyResult
+ * @typedef {{ index: number, name?: string }} MailTimePolicyTransport
+ * @typedef {{ from?: string, to: string[] }} MailTimePolicyEnvelope
+ * @typedef {{ task: MailTimeTask, attempt: number, transport: MailTimePolicyTransport, envelope: MailTimePolicyEnvelope, recipients: MailTimePolicyRecipient[] }} MailTimePolicyContext
+ * @typedef {MailTimePolicyContext} MailTimeBeforeSendPolicyContext
+ * @typedef {{ address: string | null, command?: string, responseCode?: number, response?: string, message?: string, transportIndex: number, transportName?: string }} MailTimeStructuredRejection
+ * @typedef {MailTimePolicyContext & { error?: unknown, info?: unknown, rejections: MailTimeStructuredRejection[] }} MailTimeRejectionPolicyContext
+ * @typedef {{ address: string, status: 'sent' | 'error' | 'suppressed' | 'rejected', sources?: Array<'envelope' | 'to' | 'cc' | 'bcc'>, reasons: Array<{ provider: string, reason: string }>, attempt: number, transportIndex?: number, transportName?: string, command?: string, responseCode?: number, response?: string, message?: string }} MailTimeRecipientResult
+ * @typedef {MailTimeRejectionPolicyContext & { decisions: MailTimeRecipientResult[] }} MailTimeRecipientAttemptContext
+ * @typedef {{ uuid: string, tries: number, isSettled: boolean, recipients: { sent: MailTimeRecipientResult[], error: MailTimeRecipientResult[], suppressed: MailTimeRecipientResult[], rejected: MailTimeRecipientResult[] } }} MailTimeRecipientSummary
+ * @typedef {{ name: string, failureMode?: 'retry' | 'continue', beforeSend?: (context: MailTimeBeforeSendPolicyContext) => void | MailTimePolicyResult | Promise<void | MailTimePolicyResult>, classifyRejections?: (context: MailTimeRejectionPolicyContext) => void | MailTimePolicyResult | Promise<void | MailTimePolicyResult>, observeAttempt?: (context: MailTimeRecipientAttemptContext) => void | Promise<void> }} MailTimeRecipientPolicy
+ * @description Policy contexts are read-only by contract. Providers must bound their own I/O; renewal budgets do not limit hook duration.
+ */
+/**
+ * @typedef {{ uuid: string, to?: MailTimeMailbox | MailTimeMailbox[], tries: number, sendAt: number, isSent: boolean, isSettled?: boolean, recipientResults?: MailTimeRecipientResult[], isCancelled: boolean, isFailed: boolean, isSending?: boolean, sendingAt?: number, template?: string | false, transport: number, concatSubject?: string | false, mailOptions: MailTimeMailOptions[] }} MailTimeTask
  */
 /**
  * @typedef {{ limit?: number, sendingTimeout?: number }} MailTimeIterateOptions
  */
 /**
- * @typedef {{ ping: () => Promise<MailTimePingResult>, iterate: (opts?: MailTimeIterateOptions) => Promise<void> | void, getPendingTo: (to: string, sendAt: number) => Promise<MailTimeTask | object | null>, push: (email: MailTimeTask) => Promise<void> | void, cancel: (uuid: string) => Promise<boolean>, remove: (email: MailTimeTask | object, opts?: { leaseTries: number, leaseSendingAt: number }) => Promise<boolean>, update: (email: MailTimeTask | object, updateObj: object) => Promise<boolean>, ready?: () => Promise<void> }} CustomQueue
+ * @typedef {{ ping: () => Promise<MailTimePingResult>, iterate: (opts?: MailTimeIterateOptions) => Promise<void> | void, getPendingTo: (to: string, sendAt: number) => Promise<MailTimeTask | object | null>, push: (email: MailTimeTask) => Promise<void> | void, cancel: (uuid: string) => Promise<boolean>, remove: (email: MailTimeTask | object, opts?: { leaseTries: number, leaseSendingAt: number }) => Promise<boolean>, update: (email: MailTimeTask | object, updateObj: object) => Promise<boolean>, ready?: () => Promise<void>, supportsRecipientPolicies?: boolean }} CustomQueue
  */
 /**
  * @typedef {{ address: string, error: string }} MailTimeRejectedRecipient
  */
 /**
- * @typedef {{ [key: string]: any, to: string | string[], sendAt?: Date | number, template?: string, concatSubject?: string, text?: string | false, html?: string | false, subject?: string, accepted?: string[], rejected?: MailTimeRejectedRecipient[] }} MailTimeMailOptions
+ * @typedef {{ [key: string]: any, to: MailTimeMailbox | MailTimeMailbox[], cc?: MailTimeMailbox | MailTimeMailbox[], bcc?: MailTimeMailbox | MailTimeMailbox[], sendAt?: Date | number, template?: string, concatSubject?: string, text?: string | false, html?: string | false, subject?: string, accepted?: string[], rejected?: MailTimeRejectedRecipient[] }} MailTimeMailOptions
  */
 /**
  * @typedef {{ subject?: string }} MailTimeConcatEmailsOptions
@@ -191,9 +304,15 @@ export type MailTimeOptions = {
  * @typedef {{ index: number, from: string | undefined }} MailTimeFromDetails
  */
 /**
- * @typedef {{ queue: RedisQueue | MongoQueue | PostgresQueue | CustomQueue, type?: 'server' | 'client', from?: string | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string), transports?: MailTimeTransport[], strategy?: 'backup' | 'balancer', failsToNext?: number, shouldFailOver?: (error: unknown, info: object | undefined, email: MailTimeTask) => boolean, retries?: number, maxTries?: number, retryDelay?: number, interval?: number, keepHistory?: boolean, concatEmails?: boolean | MailTimeConcatEmailsOptions, concatSubject?: string, concatDelimiter?: string, concatDelay?: number, concatThrottling?: number, revolvingInterval?: number, mode?: 'one' | 'batch', concurrency?: number, sendingTimeout?: number, renewClaim?: boolean | number, maxRenewals?: number, strictPayload?: boolean, allowedMailFields?: string[], verifyTransports?: boolean, template?: string, prefix?: string, debug?: boolean, josk?: MailTimeJoSkOptions, onError?: (error: unknown, email: MailTimeTask | null, details?: object) => void, onSent?: (email: MailTimeTask, details?: object) => void }} MailTimeOptions
+ * @typedef {{ queue: RedisQueue | MongoQueue | PostgresQueue | CustomQueue, type?: 'server' | 'client', from?: string | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string), transports?: MailTimeTransport[], strategy?: 'backup' | 'balancer', failsToNext?: number, shouldFailOver?: (error: unknown, info: object | undefined, email: MailTimeTask) => boolean, retries?: number, maxTries?: number, retryDelay?: number, interval?: number, keepHistory?: boolean, concatEmails?: boolean | MailTimeConcatEmailsOptions, concatSubject?: string, concatDelimiter?: string, concatDelay?: number, concatThrottling?: number, revolvingInterval?: number, mode?: 'one' | 'batch', concurrency?: number, sendingTimeout?: number, renewClaim?: boolean | number, maxRenewals?: number, strictPayload?: boolean, allowedMailFields?: string[], verifyTransports?: boolean, template?: string, prefix?: string, debug?: boolean, josk?: MailTimeJoSkOptions, recipientPolicies?: MailTimeRecipientPolicy[], onError?: (error: unknown, email: MailTimeTask | null, details?: object, recipients?: MailTimeRecipientResult[], summary?: MailTimeRecipientSummary) => void | Promise<void>, onSent?: (email: MailTimeTask, details?: object, recipients?: MailTimeRecipientResult[], summary?: MailTimeRecipientSummary) => void | Promise<void>, onSuppressed?: (email: MailTimeTask, recipients: MailTimeRecipientResult[], summary: MailTimeRecipientSummary) => void | Promise<void>, onRejected?: (email: MailTimeTask, recipients: MailTimeRecipientResult[], summary: MailTimeRecipientSummary) => void | Promise<void> }} MailTimeOptions
+ */
+/**
+ * Class of MailTime.
+ * With recipientPolicies, terminal callbacks receive grouped recipients and a complete summary after persistence.
+ * isSettled includes exhausted errors; isSent means all accepted; isFailed means an error or permanent rejection.
+ * Unparseable terminal preparation failures invoke onError with an empty recipient group.
+ * Hooks must bound their own I/O. Callback notifications are best-effort, not durable exactly-once delivery.
  */
-/** Class of MailTime */
 export class MailTime {
     static set Template(newVal: string);
     static get Template(): string;
@@ -223,8 +342,10 @@ export class MailTime {
     retryDelay: number;
     template: string;
     keepHistory: boolean;
-    onSent: (email: MailTimeTask, details?: object) => void;
-    onError: (error: unknown, email: MailTimeTask | null, details?: object) => void;
+    onSent: (email: MailTimeTask, details?: object, recipients?: MailTimeRecipientResult[], summary?: MailTimeRecipientSummary) => void | Promise<void>;
+    onError: (error: unknown, email: MailTimeTask | null, details?: object, recipients?: MailTimeRecipientResult[], summary?: MailTimeRecipientSummary) => void | Promise<void>;
+    onSuppressed: (email: MailTimeTask, recipients: MailTimeRecipientResult[], summary: MailTimeRecipientSummary) => void | Promise<void>;
+    onRejected: (email: MailTimeTask, recipients: MailTimeRecipientResult[], summary: MailTimeRecipientSummary) => void | Promise<void>;
     revolvingInterval: number;
     mode: "one" | "batch";
     concurrency: number;
@@ -283,12 +404,13 @@ export class MailTime {
     /**
      * @memberOf MailTime
      * @name destroy
-     * @description Stop the scheduler and block future dispatches. Without `{ drain: true }`, any in-flight SMTP attempts are neutralized on completion — they perform no storage writes, no `onSent`/`onError` callbacks, and no logging once `destroy()` returns; their claimed rows are recovered by stale-lock timeout (`sendingTimeout`). Pass `{ drain: true }` to instead let in-flight attempts run to completion (returns a Promise that resolves once they settle).
-     * @param {{ drain?: boolean }} [opts]
+     * @description Stop the scheduler and block future dispatches. Without `{ drain: true }`, in-flight SMTP attempts are neutralized and their claims recover after `sendingTimeout`. With `{ drain: true }`, await JoSk shutdown and in-flight SMTP; resolves false if a scheduler handler exceeds `schedulerTimeout` (default 10000ms) or JoSk shutdown throws (logged); never rejects. The timeout does not bound SMTP drain time.
+     * @param {{ drain?: boolean, schedulerTimeout?: number }} [opts] - schedulerTimeout must be finite and non-negative; used only with drain
      * @returns {boolean | Promise<boolean>}
      */
     destroy(opts?: {
         drain?: boolean;
+        schedulerTimeout?: number;
     }): boolean | Promise<boolean>;
     /**
      * @async