feat(backend,clerk-js): Add providerUserId field to ExternalAccount (#7778)

Author: Jibaru

.changeset/legal-crabs-shout.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/backend': minor
+---
+
+Add `providerUserId` field to `ExternalAccount` resource as the preferred way to access the unique user ID from the OAuth provider. The existing `externalId` field is now deprecated in favor of `providerUserId` for better clarity and consistency across the API.

packages/backend/src/api/resources/ExternalAccount.ts

@@ -16,12 +16,17 @@ export class ExternalAccount {
      * The provider name (e.g., `google`).
      */
     readonly provider: string,
+    /**
+     * The unique ID of the user in the provider.
+     */
+    readonly providerUserId: string,
     /**
      * The identification with which this external account is associated.
      */
     readonly identificationId: string,
     /**
      * The unique ID of the user in the provider.
+     * @deprecated Use providerUserId instead
      */
     readonly externalId: string,
     /**
@@ -70,6 +75,7 @@ export class ExternalAccount {
     return new ExternalAccount(
       data.id,
       data.provider,
+      data.provider_user_id,
       data.identification_id,
       data.provider_user_id,
       data.approved_scopes,

packages/clerk-js/src/core/resources/__tests__/ExternalAccount.test.ts

@@ -9,6 +9,8 @@ describe('External account', () => {
     const externalAccountJSON = {
       object: 'external_account',
       id: targetId,
+      provider_user_id: 'test_provider_user_id',
+      identification_id: 'test_identification_id',
     };
 
     // @ts-ignore
@@ -35,6 +37,8 @@ describe('External account', () => {
       object: 'external_account',
       id: targetId,
       deleted: true,
+      provider_user_id: 'test_provider_user_id',
+      identification_id: 'test_identification_id',
     };
 
     // @ts-ignore