@upyo/smtp 0.5.0-dev.120 → 0.5.0-dev.136

package/dist/index.d.cts

@@ -182,19 +182,63 @@ interface SmtpConfig {
 /**
  * Authentication configuration for SMTP connections.
  *
- * Defines the credentials and authentication method to use when
- * connecting to an SMTP server that requires authentication.
+ * This is a discriminated union of the supported authentication strategies:
+ *
+ *  -  {@link SmtpUserPassAuth}: traditional username/password authentication
+ *     (SASL `PLAIN`, `LOGIN`, …), discriminated by the `pass` field.
+ *  -  {@link SmtpOAuth2TokenAuth}: OAuth 2.0 authentication using a static or
+ *     dynamically provided access token, discriminated by the `accessToken`
+ *     field.
+ *  -  {@link SmtpOAuth2RefreshAuth}: OAuth 2.0 authentication using the built-in
+ *     `refresh_token` grant flow, discriminated by the `refreshToken` field.
+ *
+ * @example
+ * ```typescript
+ * // Username/password
+ * const passwordAuth: SmtpAuth = {
+ *   user: 'username@domain.com',
+ *   pass: 'password',
+ *   method: 'plain' // or 'login', 'cram-md5'
+ * };
+ *
+ * // OAuth 2.0 with a (possibly refreshing) access token
+ * const tokenAuth: SmtpAuth = {
+ *   user: 'username@gmail.com',
+ *   accessToken: 'ya29.a0Af…',
+ *   method: 'xoauth2' // or 'oauthbearer'
+ * };
+ * ```
+ */
+type SmtpAuth = SmtpUserPassAuth | SmtpOAuth2TokenAuth | SmtpOAuth2RefreshAuth;
+/**
+ * OAuth 2.0 access token aggregate that supplies access tokens on demand.
+ *
+ * The transport invokes the provider each time it needs to authenticate a new
+ * connection, which lets the caller plug in an external OAuth client (e.g.,
+ * `google-auth-library` or `msal-node`) and refresh expired tokens
+ * transparently.
+ *
+ * @param signal An optional {@link AbortSignal} to cancel token acquisition.
+ * @returns The OAuth 2.0 access token (bearer token), or a promise of it.
+ * @since 0.5.0
+ */
+type OAuth2TokenProvider = (signal?: AbortSignal) => string | Promise<string>;
+/**
+ * Username/password authentication configuration for SMTP connections.
+ *
+ * Defines the credentials and SASL method to use when connecting to an SMTP
+ * server that requires password-based authentication.
  *
  * @example
  * ```typescript
- * const auth: SmtpAuth = {
+ * const auth: SmtpUserPassAuth = {
  *   user: 'username@domain.com',
  *   pass: 'password',
  *   method: 'plain' // or 'login', 'cram-md5'
  * };
  * ```
  */
-interface SmtpAuth {
+interface SmtpUserPassAuth {
   /**
    * Username for authentication.
    */
@@ -209,6 +253,110 @@ interface SmtpAuth {
    */
   readonly method?: "plain" | "login" | "cram-md5";
 }
+/**
+ * OAuth 2.0 authentication configuration using a directly supplied access
+ * token.
+ *
+ * The `accessToken` may be a static string or an {@link OAuth2TokenProvider}
+ * callback that returns a fresh token on demand.  Use the callback form to
+ * integrate an external OAuth client (such as `google-auth-library` or
+ * `msal-node`) so that expired tokens are refreshed automatically.
+ *
+ * @example
+ * ```typescript
+ * const auth: SmtpOAuth2TokenAuth = {
+ *   user: 'username@gmail.com',
+ *   accessToken: async () => await getFreshAccessToken(),
+ *   method: 'xoauth2',
+ * };
+ * ```
+ * @since 0.5.0
+ */
+interface SmtpOAuth2TokenAuth {
+  /**
+   * The user (email address) to authenticate as.
+   */
+  readonly user: string;
+  /**
+   * The OAuth 2.0 access token, or a provider callback returning one.
+   *
+   * When a callback is given, it is invoked every time a new connection is
+   * authenticated, allowing the caller to refresh expired tokens.
+   */
+  readonly accessToken: string | OAuth2TokenProvider;
+  /**
+   * The SASL mechanism to use.  When omitted, the mechanism is chosen
+   * automatically based on the server's advertised capabilities, preferring
+   * `xoauth2`.
+   * @default "xoauth2"
+   */
+  readonly method?: "xoauth2" | "oauthbearer";
+}
+/**
+ * OAuth 2.0 authentication configuration using the built-in `refresh_token`
+ * grant flow.
+ *
+ * The transport exchanges the refresh token for an access token at the given
+ * token endpoint and caches it until shortly before it expires, refreshing it
+ * automatically as needed.  No external OAuth library is required.
+ *
+ * @example
+ * ```typescript
+ * const auth: SmtpOAuth2RefreshAuth = {
+ *   user: 'username@gmail.com',
+ *   clientId: '…apps.googleusercontent.com',
+ *   clientSecret: '…',
+ *   refreshToken: '1//…',
+ *   tokenEndpoint: 'https://oauth2.googleapis.com/token',
+ * };
+ * ```
+ * @since 0.5.0
+ */
+interface SmtpOAuth2RefreshAuth {
+  /**
+   * The user (email address) to authenticate as.
+   */
+  readonly user: string;
+  /**
+   * The OAuth 2.0 client identifier.
+   */
+  readonly clientId: string;
+  /**
+   * The OAuth 2.0 client secret.  May be omitted for public clients (e.g.,
+   * clients using PKCE) that have no secret.
+   */
+  readonly clientSecret?: string;
+  /**
+   * The OAuth 2.0 refresh token used to obtain access tokens.
+   */
+  readonly refreshToken: string;
+  /**
+   * The token endpoint URL where the refresh token is exchanged for an access
+   * token (e.g., `https://oauth2.googleapis.com/token`).
+   */
+  readonly tokenEndpoint: string;
+  /**
+   * An optional space-delimited list of OAuth 2.0 scopes to request.
+   */
+  readonly scope?: string;
+  /**
+   * The SASL mechanism to use.  When omitted, the mechanism is chosen
+   * automatically based on the server's advertised capabilities, preferring
+   * `xoauth2`.
+   * @default "xoauth2"
+   */
+  readonly method?: "xoauth2" | "oauthbearer";
+}
+/**
+ * OAuth 2.0 authentication configuration for SMTP connections.
+ *
+ * A union of the OAuth 2.0 authentication strategies: a directly supplied
+ * (or callback-provided) access token ({@link SmtpOAuth2TokenAuth}) or the
+ * built-in `refresh_token` grant flow ({@link SmtpOAuth2RefreshAuth}).
+ *
+ * @since 0.5.0
+ */
+type SmtpOAuth2Auth = SmtpOAuth2TokenAuth | SmtpOAuth2RefreshAuth;
 /**
  * TLS/SSL configuration options for secure SMTP connections.
  *
@@ -304,6 +452,13 @@ declare class SmtpTransport implements Transport, AsyncDisposable {
    */
   poolSize: number;
   private connectionPool;
+  /**
+   * A token manager shared across all pooled connections, present only when the
+   * configured authentication uses OAuth 2.0.  Sharing it ensures the
+   * refresh-token exchange happens at most once per token lifetime instead of
+   * once per connection.
+   */
+  private readonly tokenManager;
   /**
    * Creates a new SMTP transport instance.
    *
@@ -402,4 +557,33 @@ declare class SmtpTransport implements Transport, AsyncDisposable {
   [Symbol.asyncDispose](): Promise<void>;
 }
 //#endregion
-export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, SmtpAuth, SmtpConfig, SmtpTlsOptions, SmtpTransport };
+//#region src/oauth2.d.ts
+/**
+ * An error thrown when SMTP authentication fails, including OAuth 2.0 token
+ * acquisition and SASL exchange failures.
+ *
+ * @since 0.5.0
+ */
+declare class SmtpAuthError extends Error {
+  /**
+   * Creates a new {@link SmtpAuthError}.
+   * @param message A human-readable description of the failure.
+   */
+  constructor(message: string);
+}
+/**
+ * Builds the SASL `XOAUTH2` initial client response for SMTP authentication.
+ *
+ * The unencoded payload follows Google's XOAUTH2 format
+ * (`user=<user>^Aauth=Bearer <token>^A^A`, where `^A` is the `0x01` control
+ * character) and is returned Base64-encoded, ready to be sent as the argument
+ * of `AUTH XOAUTH2`.
+ *
+ * @param user The user (email address) to authenticate as.
+ * @param accessToken The OAuth 2.0 access token.
+ * @returns The Base64-encoded XOAUTH2 initial client response.
+ * @since 0.5.0
+ */
+
+//#endregion
+export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpTlsOptions, SmtpTransport, SmtpUserPassAuth };

package/dist/index.d.ts

@@ -182,19 +182,63 @@ interface SmtpConfig {
 /**
  * Authentication configuration for SMTP connections.
  *
- * Defines the credentials and authentication method to use when
- * connecting to an SMTP server that requires authentication.
+ * This is a discriminated union of the supported authentication strategies:
+ *
+ *  -  {@link SmtpUserPassAuth}: traditional username/password authentication
+ *     (SASL `PLAIN`, `LOGIN`, …), discriminated by the `pass` field.
+ *  -  {@link SmtpOAuth2TokenAuth}: OAuth 2.0 authentication using a static or
+ *     dynamically provided access token, discriminated by the `accessToken`
+ *     field.
+ *  -  {@link SmtpOAuth2RefreshAuth}: OAuth 2.0 authentication using the built-in
+ *     `refresh_token` grant flow, discriminated by the `refreshToken` field.
+ *
+ * @example
+ * ```typescript
+ * // Username/password
+ * const passwordAuth: SmtpAuth = {
+ *   user: 'username@domain.com',
+ *   pass: 'password',
+ *   method: 'plain' // or 'login', 'cram-md5'
+ * };
+ *
+ * // OAuth 2.0 with a (possibly refreshing) access token
+ * const tokenAuth: SmtpAuth = {
+ *   user: 'username@gmail.com',
+ *   accessToken: 'ya29.a0Af…',
+ *   method: 'xoauth2' // or 'oauthbearer'
+ * };
+ * ```
+ */
+type SmtpAuth = SmtpUserPassAuth | SmtpOAuth2TokenAuth | SmtpOAuth2RefreshAuth;
+/**
+ * OAuth 2.0 access token aggregate that supplies access tokens on demand.
+ *
+ * The transport invokes the provider each time it needs to authenticate a new
+ * connection, which lets the caller plug in an external OAuth client (e.g.,
+ * `google-auth-library` or `msal-node`) and refresh expired tokens
+ * transparently.
+ *
+ * @param signal An optional {@link AbortSignal} to cancel token acquisition.
+ * @returns The OAuth 2.0 access token (bearer token), or a promise of it.
+ * @since 0.5.0
+ */
+type OAuth2TokenProvider = (signal?: AbortSignal) => string | Promise<string>;
+/**
+ * Username/password authentication configuration for SMTP connections.
+ *
+ * Defines the credentials and SASL method to use when connecting to an SMTP
+ * server that requires password-based authentication.
  *
  * @example
  * ```typescript
- * const auth: SmtpAuth = {
+ * const auth: SmtpUserPassAuth = {
  *   user: 'username@domain.com',
  *   pass: 'password',
  *   method: 'plain' // or 'login', 'cram-md5'
  * };
  * ```
  */
-interface SmtpAuth {
+interface SmtpUserPassAuth {
   /**
    * Username for authentication.
    */
@@ -209,6 +253,110 @@ interface SmtpAuth {
    */
   readonly method?: "plain" | "login" | "cram-md5";
 }
+/**
+ * OAuth 2.0 authentication configuration using a directly supplied access
+ * token.
+ *
+ * The `accessToken` may be a static string or an {@link OAuth2TokenProvider}
+ * callback that returns a fresh token on demand.  Use the callback form to
+ * integrate an external OAuth client (such as `google-auth-library` or
+ * `msal-node`) so that expired tokens are refreshed automatically.
+ *
+ * @example
+ * ```typescript
+ * const auth: SmtpOAuth2TokenAuth = {
+ *   user: 'username@gmail.com',
+ *   accessToken: async () => await getFreshAccessToken(),
+ *   method: 'xoauth2',
+ * };
+ * ```
+ * @since 0.5.0
+ */
+interface SmtpOAuth2TokenAuth {
+  /**
+   * The user (email address) to authenticate as.
+   */
+  readonly user: string;
+  /**
+   * The OAuth 2.0 access token, or a provider callback returning one.
+   *
+   * When a callback is given, it is invoked every time a new connection is
+   * authenticated, allowing the caller to refresh expired tokens.
+   */
+  readonly accessToken: string | OAuth2TokenProvider;
+  /**
+   * The SASL mechanism to use.  When omitted, the mechanism is chosen
+   * automatically based on the server's advertised capabilities, preferring
+   * `xoauth2`.
+   * @default "xoauth2"
+   */
+  readonly method?: "xoauth2" | "oauthbearer";
+}
+/**
+ * OAuth 2.0 authentication configuration using the built-in `refresh_token`
+ * grant flow.
+ *
+ * The transport exchanges the refresh token for an access token at the given
+ * token endpoint and caches it until shortly before it expires, refreshing it
+ * automatically as needed.  No external OAuth library is required.
+ *
+ * @example
+ * ```typescript
+ * const auth: SmtpOAuth2RefreshAuth = {
+ *   user: 'username@gmail.com',
+ *   clientId: '…apps.googleusercontent.com',
+ *   clientSecret: '…',
+ *   refreshToken: '1//…',
+ *   tokenEndpoint: 'https://oauth2.googleapis.com/token',
+ * };
+ * ```
+ * @since 0.5.0
+ */
+interface SmtpOAuth2RefreshAuth {
+  /**
+   * The user (email address) to authenticate as.
+   */
+  readonly user: string;
+  /**
+   * The OAuth 2.0 client identifier.
+   */
+  readonly clientId: string;
+  /**
+   * The OAuth 2.0 client secret.  May be omitted for public clients (e.g.,
+   * clients using PKCE) that have no secret.
+   */
+  readonly clientSecret?: string;
+  /**
+   * The OAuth 2.0 refresh token used to obtain access tokens.
+   */
+  readonly refreshToken: string;
+  /**
+   * The token endpoint URL where the refresh token is exchanged for an access
+   * token (e.g., `https://oauth2.googleapis.com/token`).
+   */
+  readonly tokenEndpoint: string;
+  /**
+   * An optional space-delimited list of OAuth 2.0 scopes to request.
+   */
+  readonly scope?: string;
+  /**
+   * The SASL mechanism to use.  When omitted, the mechanism is chosen
+   * automatically based on the server's advertised capabilities, preferring
+   * `xoauth2`.
+   * @default "xoauth2"
+   */
+  readonly method?: "xoauth2" | "oauthbearer";
+}
+/**
+ * OAuth 2.0 authentication configuration for SMTP connections.
+ *
+ * A union of the OAuth 2.0 authentication strategies: a directly supplied
+ * (or callback-provided) access token ({@link SmtpOAuth2TokenAuth}) or the
+ * built-in `refresh_token` grant flow ({@link SmtpOAuth2RefreshAuth}).
+ *
+ * @since 0.5.0
+ */
+type SmtpOAuth2Auth = SmtpOAuth2TokenAuth | SmtpOAuth2RefreshAuth;
 /**
  * TLS/SSL configuration options for secure SMTP connections.
  *
@@ -304,6 +452,13 @@ declare class SmtpTransport implements Transport, AsyncDisposable {
    */
   poolSize: number;
   private connectionPool;
+  /**
+   * A token manager shared across all pooled connections, present only when the
+   * configured authentication uses OAuth 2.0.  Sharing it ensures the
+   * refresh-token exchange happens at most once per token lifetime instead of
+   * once per connection.
+   */
+  private readonly tokenManager;
   /**
    * Creates a new SMTP transport instance.
    *
@@ -402,4 +557,33 @@ declare class SmtpTransport implements Transport, AsyncDisposable {
   [Symbol.asyncDispose](): Promise<void>;
 }
 //#endregion
-export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, SmtpAuth, SmtpConfig, SmtpTlsOptions, SmtpTransport };
+//#region src/oauth2.d.ts
+/**
+ * An error thrown when SMTP authentication fails, including OAuth 2.0 token
+ * acquisition and SASL exchange failures.
+ *
+ * @since 0.5.0
+ */
+declare class SmtpAuthError extends Error {
+  /**
+   * Creates a new {@link SmtpAuthError}.
+   * @param message A human-readable description of the failure.
+   */
+  constructor(message: string);
+}
+/**
+ * Builds the SASL `XOAUTH2` initial client response for SMTP authentication.
+ *
+ * The unencoded payload follows Google's XOAUTH2 format
+ * (`user=<user>^Aauth=Bearer <token>^A^A`, where `^A` is the `0x01` control
+ * character) and is returned Base64-encoded, ready to be sent as the argument
+ * of `AUTH XOAUTH2`.
+ *
+ * @param user The user (email address) to authenticate as.
+ * @param accessToken The OAuth 2.0 access token.
+ * @returns The Base64-encoded XOAUTH2 initial client response.
+ * @since 0.5.0
+ */
+
+//#endregion
+export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpTlsOptions, SmtpTransport, SmtpUserPassAuth };