chore(backend,nextjs,clerk-sdk-node): Drop legacy return response in BAPI responses

.changeset/mighty-pugs-knock.md

@@ -0,0 +1,17 @@
+---
+'@clerk/clerk-sdk-node': major
+'@clerk/backend': major
+'@clerk/nextjs': major
+---
+
+Change the response payload of Backend API requests to return `{ data, errors }` instead of return the data and throwing on error response.
+Code example to keep the same behavior:
+```typescript
+import { users } from '@clerk/backend';
+import { ClerkAPIResponseError } from '@clerk/shared/error';
+
+const { data, errors, clerkTraceId, status, statusText } = await users.getUser('user_deadbeef');
+if(errors){
+    throw new ClerkAPIResponseError(statusText, { data: errors, status, clerkTraceId });
+}
+```

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

@@ -4,6 +4,7 @@ import sinon from 'sinon';
 import emailJson from '../fixtures/responses/email.json';
 import userJson from '../fixtures/responses/user.json';
 import runtime from '../runtime';
+import { assertErrorResponse, assertResponse } from '../util/assertResponse';
 import { jsonError, jsonNotOk, jsonOk } from '../util/mockFetch';
 import { createBackendApiClient } from './factory';
 
@@ -26,22 +27,17 @@ export default (QUnit: QUnit) => {
       fakeFetch = sinon.stub(runtime, 'fetch');
       fakeFetch.onCall(0).returns(jsonOk(userJson));
 
-      const payload = await apiClient.users.getUser('user_deadbeef');
+      const response = await apiClient.users.getUser('user_deadbeef');
 
-      if (!payload) {
-        // eslint-disable-next-line qunit/no-conditional-assertions
-        assert.false(true, 'This assertion should never fail. We need to check for payload to make TS happy.');
-        // eslint-disable-next-line qunit/no-early-return
-        return;
-      }
+      assertResponse(assert, response);
+      const { data: payload } = response;
 
       assert.equal(payload.firstName, 'John');
       assert.equal(payload.lastName, 'Doe');
       assert.equal(payload.emailAddresses[0].emailAddress, '[email protected]');
       assert.equal(payload.phoneNumbers[0].phoneNumber, '+311-555-2368');
       assert.equal(payload.externalAccounts[0].emailAddress, '[email protected]');
       assert.equal(payload.publicMetadata.zodiac_sign, 'leo');
-      // assert.equal(payload.errors, null);
 
       assert.ok(
         fakeFetch.calledOnceWith('https://api.clerk.test/v1/users/user_deadbeef', {
@@ -59,22 +55,16 @@ export default (QUnit: QUnit) => {
       fakeFetch = sinon.stub(runtime, 'fetch');
       fakeFetch.onCall(0).returns(jsonOk([userJson]));
 
-      const payload = await apiClient.users.getUserList({ offset: 2, limit: 5 });
-
-      if (!payload) {
-        // eslint-disable-next-line qunit/no-conditional-assertions
-        assert.false(true, 'This assertion should never fail. We need to check for payload to make TS happy.');
-        // eslint-disable-next-line qunit/no-early-return
-        return;
-      }
+      const response = await apiClient.users.getUserList({ offset: 2, limit: 5 });
+      assertResponse(assert, response);
+      const { data: payload } = response;
 
       assert.equal(payload[0].firstName, 'John');
       assert.equal(payload[0].lastName, 'Doe');
       assert.equal(payload[0].emailAddresses[0].emailAddress, '[email protected]');
       assert.equal(payload[0].phoneNumbers[0].phoneNumber, '+311-555-2368');
       assert.equal(payload[0].externalAccounts[0].emailAddress, '[email protected]');
       assert.equal(payload[0].publicMetadata.zodiac_sign, 'leo');
-      // assert.equal(payload.errors, null);
 
       assert.ok(
         fakeFetch.calledOnceWith('https://api.clerk.test/v1/users?offset=2&limit=5', {
@@ -100,14 +90,10 @@ export default (QUnit: QUnit) => {
       };
       const requestBody =
         '{"from_email_name":"foobar123","email_address_id":"[email protected]","body":"this is a test","subject":"this is a test"}';
-      const payload = await apiClient.emails.createEmail(body);
-
-      if (!payload) {
-        // eslint-disable-next-line qunit/no-conditional-assertions
-        assert.false(true, 'This assertion should never fail. We need to check for payload to make TS happy.');
-        // eslint-disable-next-line qunit/no-early-return
-        return;
-      }
+      const response = await apiClient.emails.createEmail(body);
+      assertResponse(assert, response);
+      const { data: payload } = response;
+
       assert.equal(JSON.stringify(payload.data), '{}');
       assert.equal(payload.id, 'ema_2PHa2N3bS7D6NPPQ5mpHEg0waZQ');
 
@@ -126,15 +112,19 @@ export default (QUnit: QUnit) => {
 
     test('executes a successful backend API request to create a new resource', async assert => {
       fakeFetch = sinon.stub(runtime, 'fetch');
-      fakeFetch.onCall(0).returns(jsonOk([userJson]));
+      fakeFetch.onCall(0).returns(jsonOk(userJson));
 
-      await apiClient.users.createUser({
+      const response = await apiClient.users.createUser({
         firstName: 'John',
         lastName: 'Doe',
         publicMetadata: {
           star_sign: 'Leon',
         },
       });
+      assertResponse(assert, response);
+      const { data: payload } = response;
+
+      assert.equal(payload.firstName, 'John');
 
       assert.ok(
         fakeFetch.calledOnceWith('https://api.clerk.test/v1/users', {
@@ -161,14 +151,13 @@ export default (QUnit: QUnit) => {
       fakeFetch = sinon.stub(runtime, 'fetch');
       fakeFetch.onCall(0).returns(jsonNotOk({ errors: [mockErrorPayload], clerk_trace_id: traceId }));
 
-      try {
-        await apiClient.users.getUser('user_deadbeef');
-      } catch (e: any) {
-        assert.equal(e.clerkTraceId, traceId);
-        assert.true(e.clerkError);
-        assert.equal(e.status, 422);
-        assert.equal(e.errors[0].code, 'whatever_error');
-      }
+      const response = await apiClient.users.getUser('user_deadbeef');
+      assertErrorResponse(assert, response);
+
+      assert.equal(response.clerkTraceId, traceId);
+      assert.equal(response.status, 422);
+      assert.equal(response.statusText, '422');
+      assert.equal(response.errors[0].code, 'whatever_error');
 
       assert.ok(
         fakeFetch.calledOnceWith('https://api.clerk.test/v1/users/user_deadbeef', {
@@ -186,13 +175,12 @@ export default (QUnit: QUnit) => {
       fakeFetch = sinon.stub(runtime, 'fetch');
       fakeFetch.onCall(0).returns(jsonError({ errors: [] }));
 
-      try {
-        await apiClient.users.getUser('user_deadbeef');
-      } catch (e: any) {
-        assert.true(e.clerkError);
-        assert.equal(e.status, 500);
-        assert.equal(e.clerkTraceId, 'mock_cf_ray');
-      }
+      const response = await apiClient.users.getUser('user_deadbeef');
+      assertErrorResponse(assert, response);
+
+      assert.equal(response.status, 500);
+      assert.equal(response.statusText, '500');
+      assert.equal(response.clerkTraceId, 'mock_cf_ray');
 
       assert.ok(
         fakeFetch.calledOnceWith('https://api.clerk.test/v1/users/user_deadbeef', {

packages/backend/src/api/request.ts

@@ -1,4 +1,3 @@
-import { ClerkAPIResponseError } from '@clerk/shared/error';
 import type { ClerkAPIError, ClerkAPIErrorJSON } from '@clerk/types';
 import snakecaseKeys from 'snakecase-keys';
 
@@ -36,32 +35,11 @@ export type ClerkBackendApiResponse<T> =
       data: null;
       errors: ClerkAPIError[];
       clerkTraceId?: string;
+      status?: number;
+      statusText?: string;
     };
 
 export type RequestFunction = ReturnType<typeof buildRequest>;
-type LegacyRequestFunction = <T>(requestOptions: ClerkBackendApiRequestOptions) => Promise<T>;
-
-/**
- * Switching to the { data, errors } format is a breaking change, so we will skip it for now
- * until we release v5 of the related SDKs.
- * This HOF wraps the request helper and transforms the new return to the legacy return.
- * TODO: Simply remove this wrapper and the ClerkAPIResponseError before the v5 release.
- */
-const withLegacyReturn =
-  (cb: any): LegacyRequestFunction =>
-  async (...args) => {
-    // @ts-ignore
-    const { data, errors, status, statusText, clerkTraceId } = await cb<T>(...args);
-    if (errors === null) {
-      return data;
-    } else {
-      throw new ClerkAPIResponseError(statusText || '', {
-        data: errors,
-        status: status || '',
-        clerkTraceId,
-      });
-    }
-  };
 
 type BuildRequestOptions = {
   /* Secret Key */
@@ -73,9 +51,8 @@ type BuildRequestOptions = {
   /* Library/SDK name */
   userAgent?: string;
 };
-
 export function buildRequest(options: BuildRequestOptions) {
-  const request = async <T>(requestOptions: ClerkBackendApiRequestOptions): Promise<ClerkBackendApiResponse<T>> => {
+  return async <T>(requestOptions: ClerkBackendApiRequestOptions): Promise<ClerkBackendApiResponse<T>> => {
     const { secretKey, apiUrl = API_URL, apiVersion = API_VERSION, userAgent = USER_AGENT } = options;
     const { path, method, queryParams, headerParams, bodyParams, formData } = requestOptions;
 
@@ -133,7 +110,13 @@ export function buildRequest(options: BuildRequestOptions) {
       const data = await (isJSONResponse ? res.json() : res.text());
 
       if (!res.ok) {
-        throw data;
+        return {
+          data: null,
+          errors: data?.errors || data,
+          status: res?.status,
+          statusText: res?.statusText,
+          clerkTraceId: getTraceId(data, res?.headers),
+        };
       }
 
       return {
@@ -157,16 +140,12 @@ export function buildRequest(options: BuildRequestOptions) {
       return {
         data: null,
         errors: parseErrors(err),
-        // TODO: To be removed with withLegacyReturn
-        // @ts-expect-error
         status: res?.status,
         statusText: res?.statusText,
         clerkTraceId: getTraceId(err, res?.headers),
       };
     }
   };
-
-  return withLegacyReturn(request);
 }
 
 // Returns either clerk_trace_id if present in response json, otherwise defaults to CF-Ray header

packages/backend/src/tokens/authStatus.ts

@@ -149,12 +149,9 @@ export async function signedIn<T extends AuthStatusOptionsType>(
     loadOrganization && orgId ? organizations.getOrganization({ organizationId: orgId }) : Promise.resolve(undefined),
   ]);
 
-  const session = sessionResp;
-  const user = userResp;
-  const organization = organizationResp;
-  // const session = sessionResp && !sessionResp.errors ? sessionResp.data : undefined;
-  // const user = userResp && !userResp.errors ? userResp.data : undefined;
-  // const organization = organizationResp && !organizationResp.errors ? organizationResp.data : undefined;
+  const session = sessionResp && !sessionResp.errors ? sessionResp.data : undefined;
+  const user = userResp && !userResp.errors ? userResp.data : undefined;
+  const organization = organizationResp && !organizationResp.errors ? organizationResp.data : undefined;
 
   const authObject = signedInAuthObject(
     sessionClaims,

packages/backend/src/util/assertResponse.ts

@@ -0,0 +1,9 @@
+type ApiResponse<T> = { data: T | null; errors: null | any[] };
+type SuccessApiResponse<T> = { data: T; errors: null };
+type ErrorApiResponse = { data: null; errors: any[]; clerkTraceId: string; status: number; statusText: string };
+export function assertResponse<T>(assert: Assert, resp: ApiResponse<T>): asserts resp is SuccessApiResponse<T> {
+  assert.equal(resp.errors, null);
+}
+export function assertErrorResponse<T>(assert: Assert, resp: ApiResponse<T>): asserts resp is ErrorApiResponse {
+  assert.notEqual(resp.errors, null);
+}

packages/backend/src/util/mockFetch.ts

@@ -5,6 +5,7 @@ export function jsonOk(body: unknown, status = 200) {
   const mockResponse = {
     ok: true,
     status,
+    statusText: status.toString(),
     headers: { get: mockHeadersGet },
     json() {
       return Promise.resolve(body);
@@ -19,6 +20,7 @@ export function jsonNotOk(body: unknown) {
   const mockResponse = {
     ok: false,
     status: 422,
+    statusText: 422,
     headers: { get: mockHeadersGet },
     json() {
       return Promise.resolve(body);
@@ -32,7 +34,8 @@ export function jsonError(body: unknown, status = 500) {
   // Mock response object that satisfies the window.Response interface
   const mockResponse = {
     ok: false,
-    status: status,
+    status,
+    statusText: status.toString(),
     headers: { get: mockHeadersGet },
     json() {
       return Promise.resolve(body);

packages/nextjs/src/app-router/server/currentUser.ts

@@ -5,5 +5,10 @@ import { auth } from './auth';
 
 export async function currentUser(): Promise<User | null> {
   const { userId } = auth();
-  return userId ? clerkClient.users.getUser(userId) : null;
+  if (!userId) return null;
+
+  const { data, errors } = await clerkClient.users.getUser(userId);
+  if (errors) return null;
+
+  return data;
 }

packages/sdk-node/examples/express/src/runtime-keys-middleware.ts

@@ -21,8 +21,12 @@ app.use(clerk.expressWithAuth());
 app.get('/', async (req: WithAuthProp<Request>, res: Response) => {
   const { userId, debug } = req.auth;
   console.log(debug());
-  const user = userId ? await clerk.users.getUser(userId) : null;
-  res.json({ auth: req.auth, user });
+  if (!userId) return res.json({ auth: req.auth, user: null });
+
+  const { data, errors } = await clerk.users.getUser(userId);
+  if (errors) return res.json({ auth: req.auth, user: null });
+
+  return res.json({ auth: req.auth, user: data });;
 });
 
 // @ts-ignore

packages/sdk-node/examples/node/src/organizations.ts

@@ -1,18 +1,29 @@
 import { organizations, users } from '@clerk/clerk-sdk-node';
 
 console.log('Get user to create organization');
-const [creator] = await users.getUserList();
+const { data, errors } = await users.getUserList();
+if (errors) {
+  throw new Error(errors);
+}
+
+const creator = data[0];
 
 console.log('Create organization');
-const organization = await organizations.createOrganization({
+const { data: organization } = await organizations.createOrganization({
   name: 'test-organization',
   createdBy: creator.id,
 });
 console.log(organization);
 
 console.log('Update organization metadata');
-const updatedOrganizationMetadata =
-  await organizations.updateOrganizationMetadata(organization.id, {
+const { data: updatedOrganizationMetadata, errors: uomErrors } = await organizations.updateOrganizationMetadata(
+  organization.id,
+  {
     publicMetadata: { test: 1 },
-  });
+  },
+);
+if (uomErrors) {
+  throw new Error(uomErrors);
+}
+
 console.log(updatedOrganizationMetadata);