feat(auth): add smtpRequired option to enforce SMTP settings during I…

[radenkovic]

Add smtpRequired Option for Hosted Authentication

Summary

Adds support for the smtp_required option in hosted authentication URLs. This option has been available in the Nylas API since March 2025 but was not previously exposed in the Node SDK.

What Changed

• Model (src/models/auth.ts): Added smtpRequired?: boolean property to URLForAuthenticationConfig
• Resource (src/resources/auth.ts): Updated urlAuthBuilder to append options=smtp_required query parameter when smtpRequired is true
• Tests (tests/resources/auth.spec.ts): Added test coverage for the new option

Why This Matters

When authenticating IMAP users, SMTP settings are optional by default. This can lead to grants that appear valid but fail when sending emails with the error:

"grant is missing imap username or password or smtphost or smtpport, unable to fetch connection details"

By setting smtpRequired: true, the authentication flow proactively validates SMTP configuration upfront, preventing these runtime errors.

Usage

// Require SMTP settings during IMAP authentication
const url = nylas.auth.urlForOAuth2({
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'https://yourapp.com/callback',
  provider: 'imap',
  smtpRequired: true,
});

// The generated URL will include options=smtp_required
// Example: https://api.us.nylas.com/v3/connect/auth?client_id=...&provider=imap&options=smtp_required

This option works with:

• urlForOAuth2() - Standard OAuth flow
• urlForOAuth2PKCE() - OAuth with PKCE
• urlForAdminConsent() - Microsoft admin consent flow

Reference

Nylas Support: How can I ensure users enter their SMTP settings during authentication

Test Results

All tests passing:

• ✅ URL includes options=smtp_required when smtpRequired: true
• ✅ URL excludes options parameter when smtpRequired is not set
• ✅ 100% coverage on auth.ts

---

Note

Low Risk
Small, additive change limited to URL query construction plus tests; low risk aside from potential behavior changes for callers who start opting into the new parameter.

Overview
Adds a new smtpRequired?: boolean option to URLForAuthenticationConfig and wires it into hosted auth URL generation so urlForOAuth2 (and any flows using the shared builder, e.g. PKCE/admin consent) can append options=smtp_required.

Expands auth URL-building tests to assert the options query param is included only when smtpRequired is set and omitted otherwise.

^{Written by Cursor Bugbot for commit c85ba1d. This will update automatically on new commits. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.60%. Comparing base (cd97b2c) to head (c85ba1d).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #702   +/-   ##
=======================================
  Coverage   98.60%   98.60%           
=======================================
  Files          35       35           
  Lines         789      791    +2     
  Branches       67       68    +1     
=======================================
+ Hits          778      780    +2     
  Misses         11       11           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[AaronDDM]

Add a change log please