feat: add support for returning email in user profile

CHANGELOG.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## 1.2.5-beta.0 - 2025-10-04
+### Added
+- Add support for returning email in user profile
+
 ## 1.2.4 - 2024-02-06
 
 ## 1.2.4-beta.0 - 2024-01-29

src/mapUserProfile.ts

@@ -12,13 +12,17 @@ export const mapUserProfile = (json: string | TwitterUserInfo): Profile => {
   const photos = parsedJson.profile_image_url
     ? [{ value: parsedJson.profile_image_url }]
     : [];
+  const emails = parsedJson.confirmed_email
+    ? [{ value: parsedJson.confirmed_email }]
+    : undefined;
   const profile: Profile = {
     provider: 'twitter',
     id: parsedJson.id,
     username: parsedJson.username,
     displayName: parsedJson.name,
     profileUrl: parsedJson.url,
     photos,
+    emails,
   };
 
   return profile;

src/models/strategyOptions.ts

@@ -10,6 +10,7 @@ interface TwitterStrategyOptionsBase {
   userProfileURL?: string | undefined;
   authorizationURL?: string | undefined;
   tokenURL?: string | undefined;
+  includeEmail?: boolean;
 }
 
 /**

src/models/twitterUserInfo.ts

@@ -8,4 +8,5 @@ export interface TwitterUserInfo {
   username: string;
   profile_image_url?: string;
   url: string;
+  confirmed_email?: string;
 }

src/strategy.ts

@@ -76,9 +76,12 @@ export class Strategy extends OAuth2Strategy {
     }
 
     this.name = 'twitter';
-    this._userProfileURL =
-      options.userProfileURL ||
+    let defaultUserProfileURL =
       'https://api.twitter.com/2/users/me?user.fields=profile_image_url,url';
+    if (options.includeEmail) {
+      defaultUserProfileURL += ',confirmed_email';
+    }
+    this._userProfileURL = options.userProfileURL || defaultUserProfileURL;
 
     let scope = options.scope || [];
     if (!Array.isArray(scope)) {
@@ -232,6 +235,10 @@ export class Strategy extends OAuth2Strategy {
       scopes.push('users.read');
     }
 
+    if (options.includeEmail) {
+      scopes.push('users.email');
+    }
+
     return scopes;
   }
 }

test/fixtures/example-profile.json

@@ -3,5 +3,6 @@
   "url": "https://t.co/vzQlr4B6qB",
   "profile_image_url": "https://pbs.twimg.com/profile_images/1478302204306067462/5BEbrnPO_normal.jpg",
   "username": "superface_test",
-  "id": "1466796521412771840"
+  "id": "1466796521412771840",
+  "confirmed_email": "superface_test@email.com"
 }

test/profile.test.ts

@@ -44,5 +44,12 @@ describe('mapUserProfile', function () {
         'https://pbs.twimg.com/profile_images/1478302204306067462/5BEbrnPO_normal.jpg'
       );
     });
+
+    it('should parse confirmed email', function () {
+      expect(profile.emails).to.have.length(1);
+      expect(profile.emails && profile.emails[0].value).to.equal(
+        'superface_test@email.com'
+      );
+    });
   });
 });

test/strategy.profile.test.ts

@@ -66,6 +66,76 @@ describe('TwitterOAuth2Strategy#userProfile', function () {
       expect(profile?._raw).to.be.a('string');
     });
 
+    it('should set json property', function () {
+      expect(profile?._json).to.be.an('object');
+    });
+  });
+  describe('fetched from default endpoint with confirm_email true', function () {
+    const strategy = new Strategy(
+      {
+        clientType: 'confidential',
+        clientID: 'ABC123',
+        clientSecret: 'secret',
+        includeEmail: true,
+      },
+      function () {}
+    );
+
+    (strategy as any)._oauth2.get = function (
+      url: string,
+      accessToken: string,
+      callback: (err: any, body?: any, res?: any) => void
+    ) {
+      if (
+        url !=
+        'https://api.twitter.com/2/users/me?user.fields=profile_image_url,url,confirmed_email'
+      ) {
+        return callback(new Error('incorrect url argument'));
+      }
+      if (accessToken != 'token') {
+        return callback(new Error('incorrect token argument'));
+      }
+
+      const body =
+        '{"data": {"username": "superface_test","profile_image_url": "https://pbs.twimg.com/profile_images/1478302204306067462/5BEbrnPO_normal.jpg","confirmed_email":"superface_test@email.com","id": "1466796521412771840","name": "SF Tester","url": "https://t.co/vzQlr4B6qB"}}';
+      callback(null, body, undefined);
+    };
+
+    let profile: ProfileWithMetaData | undefined;
+
+    before(function (done) {
+      strategy.userProfile(
+        'token',
+        (err: Error | null, p?: ProfileWithMetaData) => {
+          if (err) {
+            return done(err);
+          }
+          profile = p;
+          done();
+        }
+      );
+    });
+
+    it('should map profile', function () {
+      expect(profile?.provider).to.equal('twitter');
+
+      expect(profile?.id).to.equal('1466796521412771840');
+      expect(profile?.username).to.equal('superface_test');
+      expect(profile?.displayName).to.equal('SF Tester');
+      expect(profile?.profileUrl).to.equal('https://t.co/vzQlr4B6qB');
+      expect(profile?.photos).to.have.length(1);
+      expect(profile?.photos && profile?.photos[0].value).to.equal(
+        'https://pbs.twimg.com/profile_images/1478302204306067462/5BEbrnPO_normal.jpg'
+      );
+      expect(profile?.emails && profile.emails[0].value).to.equal(
+        'superface_test@email.com'
+      );
+    });
+
+    it('should set raw property', function () {
+      expect(profile?._raw).to.be.a('string');
+    });
+
     it('should set json property', function () {
       expect(profile?._json).to.be.an('object');
     });