docs(auth): document explicit auth modes and oauth2 test env 📜

- Add oauth2 env placeholders and integration test toggle in env example
- Document password auth type in README config and test export examples
- Update usage guide with explicit password or oauth2 auth configuration

Author: NeaByteLab

.env.example

@@ -1,3 +1,10 @@
+# Ethereal SMTP credentials for integration tests.
 ETHEREAL_USER=your-ethereal-username
 ETHEREAL_PASS=your-ethereal-password
+
+# OAuth2 integration token (optional).
+SMTP_OAUTH2_ACCESS_TOKEN=your-oauth2-access-token
+
+# Integration test flags.
 RUN_SECURE_SMTP_TEST=false
+RUN_OAUTH2_SMTP_TEST=false

README.md

@@ -37,6 +37,7 @@ const transporter = mailer.transporter({
   port: 587,
   secure: false,
   auth: {
+    type: 'password',
     user: 'user@domain.com',
     pass: 'password'
   }
@@ -76,6 +77,10 @@ deno task test
 export ETHEREAL_USER=your-ethereal-username
 export ETHEREAL_PASS=your-ethereal-password
 
+# Optional: run OAuth2 integration test too.
+export SMTP_OAUTH2_ACCESS_TOKEN=your-oauth2-access-token
+export RUN_OAUTH2_SMTP_TEST=true
+
 # Optional: run secure TLS (port 465) integration test too.
 export RUN_SECURE_SMTP_TEST=true
 

USAGE.md

@@ -51,6 +51,7 @@ const config = {
   port: 587,
   secure: false,
   auth: {
+    type: 'password',
     user: 'your-email@gmail.com',
     pass: 'your-app-password'
   }
@@ -59,15 +60,26 @@ const config = {
 
 ### Authentication
 
-Deno Mailer supports LOGIN and PLAIN authentication methods.
+Deno Mailer supports two explicit authentication modes:
+
+- `type: 'password'` using LOGIN with PLAIN fallback
+- `type: 'oauth2'` using XOAUTH2 bearer token
 
 ```ts
-// Basic authentication object.
+// Password authentication object.
 auth: {
+  type: 'password',
   user: 'username',
   pass: 'password'
 }
 
+// OAuth2 authentication object.
+auth: {
+  type: 'oauth2',
+  user: 'username',
+  accessToken: 'access-token-value'
+}
+
 // For local SMTP without auth, omit `auth`.
 ```
 
@@ -368,13 +380,15 @@ await transporter.send({
 
 ### Configuration Options
 
-| Option      | Type    | Required | Description          | Example                     |
-| ----------- | ------- | -------- | -------------------- | --------------------------- |
-| `host`      | string  | yes      | SMTP server hostname | `'smtp.gmail.com'`          |
-| `port`      | number  | yes      | SMTP server port     | `587`, `465`, `25`          |
-| `secure`    | boolean | no       | Use TLS connection   | `true` (465), `false` (587) |
-| `auth.user` | string  | no       | SMTP username        | `'user@example.com'`        |
-| `auth.pass` | string  | no       | SMTP password        | `'your-password'`           |
+| Option             | Type    | Required | Description          | Example                     |
+| ------------------ | ------- | -------- | -------------------- | --------------------------- |
+| `host`             | string  | yes      | SMTP server hostname | `'smtp.gmail.com'`          |
+| `port`             | number  | yes      | SMTP server port     | `587`, `465`, `25`          |
+| `secure`           | boolean | no       | Use TLS connection   | `true` (465), `false` (587) |
+| `auth.type`        | string  | no       | Auth mode            | `'password'`, `'oauth2'`    |
+| `auth.user`        | string  | no       | SMTP username        | `'user@example.com'`        |
+| `auth.pass`        | string  | no       | SMTP password        | `'your-password'`           |
+| `auth.accessToken` | string  | no       | OAuth2 bearer token  | `'ya29.a0...'`              |
 
 ### Message Properties
 
@@ -423,6 +437,7 @@ const transporter = mailer.transporter({
   port: 587,
   secure: false,
   auth: {
+    type: 'password',
     user: 'your-email@gmail.com',
     pass: 'your-app-password'
   }
@@ -438,6 +453,7 @@ const transporter = mailer.transporter({
   port: 587,
   secure: false,
   auth: {
+    type: 'password',
     user: 'your-email@outlook.com',
     pass: 'your-password'
   }
@@ -453,6 +469,7 @@ const transporter = mailer.transporter({
   port: 587,
   secure: false,
   auth: {
+    type: 'password',
     user: 'noreply@yourcompany.com',
     pass: 'your-password'
   }