chore(backend): Deprecate usage of the oauth_ prefix in getUserOauthAccessToken()

.changeset/violet-seas-speak.md

@@ -0,0 +1,10 @@
+---
+'@clerk/backend': minor
+---
+
+Deprecate usage of the `oauth_` prefix in `client.users.getUserOauthAccessToken()`. Going forward, please use the provider name without that prefix. Example:
+
+```diff
+- client.users.getUserOauthAccessToken('user_id', 'oauth_google')
++ client.users.getUserOauthAccessToken('user_id', 'google')
+```

packages/backend/src/api/__tests__/factory.test.ts

@@ -170,7 +170,7 @@ describe('api.client', () => {
     await apiClient.domains.deleteDomain(DOMAIN_ID);
   });
 
-  it('successfully retrieves user access tokens from backend API for a specific provider', async () => {
+  it('successfully retrieves user access tokens from backend API for a specific provider (with prefix)', async () => {
     server.use(
       http.get(
         'https://api.clerk.test/v1/users/user_deadbeef/oauth_access_tokens/oauth_google',
@@ -206,4 +206,41 @@ describe('api.client', () => {
     expect(data[0].token).toBe('<token>');
     expect(data[0].scopes).toEqual(['email', 'profile']);
   });
+
+  it('successfully retrieves user access tokens from backend API for a specific provider', async () => {
+    server.use(
+      http.get(
+        'https://api.clerk.test/v1/users/user_deadbeef/oauth_access_tokens/oauth_google',
+        validateHeaders(({ request }): any => {
+          const paginated = new URL(request.url).searchParams.get('paginated');
+
+          if (!paginated) {
+            return new HttpResponse(null, { status: 404 });
+          }
+
+          return HttpResponse.json({
+            data: [
+              {
+                external_account_id: 'eac_2dYS7stz9bgxQsSRvNqEAHhuxvW',
+                object: 'oauth_access_token',
+                token: '<token>',
+                provider: 'oauth_google',
+                public_metadata: {},
+                label: null,
+                scopes: ['email', 'profile'],
+              },
+            ],
+            total_count: 1,
+          });
+        }),
+      ),
+    );
+
+    const { data } = await apiClient.users.getUserOauthAccessToken('user_deadbeef', 'google');
+
+    expect(data[0].externalAccountId).toBe('eac_2dYS7stz9bgxQsSRvNqEAHhuxvW');
+    expect(data[0].provider).toBe('oauth_google');
+    expect(data[0].token).toBe('<token>');
+    expect(data[0].scopes).toEqual(['email', 'profile']);
+  });
 });

packages/backend/src/api/endpoints/UserApi.ts

@@ -2,6 +2,7 @@ import type { ClerkPaginationRequest, OAuthProvider } from '@clerk/types';
 
 import { runtime } from '../../runtime';
 import { joinPaths } from '../../util/path';
+import { deprecated } from '../../util/shared';
 import type { OauthAccessToken, OrganizationMembership, User } from '../resources';
 import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
@@ -201,11 +202,30 @@ export class UserAPI extends AbstractAPI {
     });
   }
 
-  public async getUserOauthAccessToken(userId: string, provider: `oauth_${OAuthProvider}`) {
+  /** @deprecated Please use getUserOauthAccessToken without the `oauth_` provider prefix . */
+  public async getUserOauthAccessToken(
+    userId: string,
+    provider: `oauth_${OAuthProvider}`,
+  ): Promise<PaginatedResourceResponse<OauthAccessToken[]>>;
+  public async getUserOauthAccessToken(
+    userId: string,
+    provider: OAuthProvider,
+  ): Promise<PaginatedResourceResponse<OauthAccessToken[]>>;
+  public async getUserOauthAccessToken(userId: string, provider: `oauth_${OAuthProvider}` | OAuthProvider) {
     this.requireId(userId);
+    const hasPrefix = provider.startsWith('oauth_');
+    const _provider = hasPrefix ? provider : `oauth_${provider}`;
+
+    if (hasPrefix) {
+      deprecated(
+        'getUserOauthAccessToken(userId, provider)',
+        'Remove the `oauth_` prefix from the `provider` argument.',
+      );
+    }
+
     return this.request<PaginatedResourceResponse<OauthAccessToken[]>>({
       method: 'GET',
-      path: joinPaths(basePath, userId, 'oauth_access_tokens', provider),
+      path: joinPaths(basePath, userId, 'oauth_access_tokens', _provider),
       queryParams: { paginated: true },
     });
   }