chore(*): Improve @clerk/backend DX

packages/backend/package.json

@@ -12,18 +12,50 @@
     "directory": "packages/backend"
   },
   "license": "MIT",
-  "imports": {
-    "#crypto": {
-      "edge-light": "./dist/runtime/browser/crypto.mjs",
-      "worker": "./dist/runtime/browser/crypto.mjs",
-      "browser": "./dist/runtime/browser/crypto.mjs",
-      "node": "./dist/runtime/node/crypto.js",
-      "default": "./dist/runtime/browser/crypto.mjs"
-    }
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./errors": {
+      "import": {
+        "types": "./dist/errors.d.ts",
+        "default": "./dist/errors.mjs"
+      },
+      "require": {
+        "types": "./dist/errors.d.ts",
+        "default": "./dist/errors.js"
+      }
+    },
+    "./internal": {
+      "import": {
+        "types": "./dist/internal.d.ts",
+        "default": "./dist/internal.mjs"
+      },
+      "require": {
+        "types": "./dist/internal.d.ts",
+        "default": "./dist/internal.js"
+      }
+    },
+    "./jwt": {
+      "import": {
+        "types": "./dist/jwt/index.d.ts",
+        "default": "./dist/jwt/index.mjs"
+      },
+      "require": {
+        "types": "./dist/jwt/index.d.ts",
+        "default": "./dist/jwt/index.js"
+      }
+    },
+    "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
-  "module": "./dist/esm/index.js",
-  "types": "./dist/types/index.d.ts",
   "files": [
     "dist"
   ],

packages/backend/src/__tests__/exports.test.ts

@@ -0,0 +1,56 @@
+import type QUnit from 'qunit';
+
+import * as errorExports from '../errors';
+import * as publicExports from '../index';
+import * as internalExports from '../internal';
+import * as jwtExports from '../jwt';
+
+export default (QUnit: QUnit) => {
+  const { module, test } = QUnit;
+
+  module('public exports', () => {
+    test('should not include a breaking change', assert => {
+      const exportedApiKeys = ['createClerkClient', 'verifyToken'];
+      assert.deepEqual(Object.keys(publicExports).sort(), exportedApiKeys);
+    });
+  });
+
+  module('subpath /errors exports', () => {
+    test('should not include a breaking change', assert => {
+      const exportedApiKeys = [
+        'TokenVerificationError',
+        'TokenVerificationErrorAction',
+        'TokenVerificationErrorCode',
+        'TokenVerificationErrorReason',
+      ];
+      assert.deepEqual(Object.keys(errorExports).sort(), exportedApiKeys);
+    });
+  });
+
+  module('subpath /internal exports', () => {
+    test('should not include a breaking change', assert => {
+      const exportedApiKeys = [
+        'AuthStatus',
+        'buildRequestUrl',
+        'constants',
+        'createAuthenticateRequest',
+        'createIsomorphicRequest',
+        'debugRequestState',
+        'makeAuthObjectSerializable',
+        'prunePrivateMetadata',
+        'redirect',
+        'sanitizeAuthObject',
+        'signedInAuthObject',
+        'signedOutAuthObject',
+      ];
+      assert.deepEqual(Object.keys(internalExports).sort(), exportedApiKeys);
+    });
+  });
+
+  module('subpath /jwt exports', () => {
+    test('should not include a breaking change', assert => {
+      const exportedApiKeys = ['decodeJwt', 'hasValidSignature', 'signJwt', 'verifyJwt'];
+      assert.deepEqual(Object.keys(jwtExports).sort(), exportedApiKeys);
+    });
+  });
+};

packages/backend/src/redirections.test.ts → packages/backend/src/__tests__/redirections.test.ts

@@ -1,7 +1,7 @@
 import type QUnit from 'qunit';
 import sinon from 'sinon';
 
-import { redirect } from './redirections';
+import { redirect } from '../redirections';
 
 export default (QUnit: QUnit) => {
   const { module, test } = QUnit;

packages/backend/src/utils.test.ts → packages/backend/src/__tests__/utils.test.ts

@@ -1,6 +1,6 @@
 import type QUnit from 'qunit';
 
-import { buildOrigin, buildRequestUrl } from './utils';
+import { buildOrigin, buildRequestUrl } from '../utils';
 
 export default (QUnit: QUnit) => {
   const { module, test } = QUnit;

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

@@ -1,12 +1,20 @@
 import type QUnit from 'qunit';
 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, jsonPaginatedOk } from '../util/mockFetch';
-import { createBackendApiClient } from './factory';
+// @ts-ignore
+import emailJson from '../../fixtures/email.json';
+// @ts-ignore
+import userJson from '../../fixtures/user.json';
+import runtime from '../../runtime';
+import {
+  assertErrorResponse,
+  assertResponse,
+  jsonError,
+  jsonNotOk,
+  jsonOk,
+  jsonPaginatedOk,
+} from '../../util/testUtils';
+import { createBackendApiClient } from '../factory';
 
 export default (QUnit: QUnit) => {
   const { module, test } = QUnit;

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

@@ -1,7 +1,6 @@
 export * from './AllowlistIdentifier';
 export * from './Client';
 export * from './DeletedObject';
-export * from './Deserializer';
 export * from './Email';
 export * from './EmailAddress';
 

packages/backend/src/index.ts

@@ -2,20 +2,14 @@ import type { TelemetryCollectorOptions } from '@clerk/shared/telemetry';
 import { TelemetryCollector } from '@clerk/shared/telemetry';
 import type { SDKMetadata } from '@clerk/types';
 
-import type { CreateBackendApiOptions } from './api';
+import type { ApiClient, CreateBackendApiOptions } from './api';
 import { createBackendApiClient } from './api';
-import type { CreateAuthenticateRequestOptions } from './tokens';
-import { createAuthenticateRequest } from './tokens';
+import type { CreateAuthenticateRequestOptions } from './tokens/factory';
+import { createAuthenticateRequest } from './tokens/factory';
 
-export { createIsomorphicRequest } from './util/IsomorphicRequest';
-
-export * from './api/resources';
-export * from './tokens';
-export * from './tokens/jwt';
-export * from './tokens/verify';
-export { constants } from './constants';
-export { redirect } from './redirections';
-export { buildRequestUrl } from './utils';
+export type { Organization, Session, User } from './api/resources';
+export type { VerifyTokenOptions } from './tokens/verify';
+export { verifyToken } from './tokens/verify';
 
 export type ClerkOptions = CreateBackendApiOptions &
   Partial<
@@ -25,7 +19,14 @@ export type ClerkOptions = CreateBackendApiOptions &
     >
   > & { sdkMetadata?: SDKMetadata; telemetry?: Pick<TelemetryCollectorOptions, 'disabled' | 'debug'> };
 
-export function createClerkClient(options: ClerkOptions) {
+// The current exported type resolves the following issue in packages importing createClerkClient
+// TS4023: Exported variable 'clerkClient' has or is using name 'AuthErrorReason' from external module "/packages/backend/dist/index" but cannot be named.
+export type ClerkClient = {
+  telemetry: TelemetryCollector;
+} & ApiClient &
+  ReturnType<typeof createAuthenticateRequest>;
+
+export function createClerkClient(options: ClerkOptions): ClerkClient {
   const opts = { ...options };
   const apiClient = createBackendApiClient(opts);
   const requestState = createAuthenticateRequest({ options: opts, apiClient });

packages/backend/src/internal.ts

@@ -0,0 +1,28 @@
+export { constants } from './constants';
+export { redirect } from './redirections';
+export { buildRequestUrl } from './utils';
+
+export type { CreateAuthenticateRequestOptions } from './tokens/factory';
+export { createAuthenticateRequest } from './tokens/factory';
+
+export { debugRequestState } from './tokens/request';
+
+export type { AuthenticateRequestOptions, OptionalVerifyTokenOptions } from './tokens/request';
+
+export type {
+  SignedInAuthObjectOptions,
+  SignedInAuthObject,
+  SignedOutAuthObject,
+  AuthObject,
+} from './tokens/authObjects';
+export {
+  makeAuthObjectSerializable,
+  sanitizeAuthObject,
+  prunePrivateMetadata,
+  signedOutAuthObject,
+  signedInAuthObject,
+} from './tokens/authObjects';
+export { createIsomorphicRequest } from './util/IsomorphicRequest';
+
+export { AuthStatus } from './tokens/authStatus';
+export type { RequestState } from './tokens/authStatus';

packages/backend/src/tokens/jwt/assertions.test.ts → packages/backend/src/jwt/__tests__/assertions.test.ts

@@ -10,7 +10,7 @@ import {
   assertHeaderType,
   assertIssuedAtClaim,
   assertSubClaim,
-} from './assertions';
+} from '../assertions';
 
 export default (QUnit: QUnit) => {
   const { module, test } = QUnit;

packages/backend/src/tokens/jwt/cryptoKeys.test.ts → packages/backend/src/jwt/__tests__/cryptoKeys.test.ts

@@ -1,7 +1,7 @@
 import type QUnit from 'qunit';
 
-import { pemEncodedPublicKey, pemEncodedSignKey, publicJwks, signingJwks } from '../fixtures';
-import { importKey } from './cryptoKeys';
+import { pemEncodedPublicKey, pemEncodedSignKey, publicJwks, signingJwks } from '../../fixtures';
+import { importKey } from '../cryptoKeys';
 
 export default (QUnit: QUnit) => {
   const { module, test } = QUnit;

packages/backend/src/tokens/jwt/signJwt.test.ts → packages/backend/src/jwt/__tests__/signJwt.test.ts

@@ -8,9 +8,9 @@ import {
   pemEncodedSignKey,
   publicJwks,
   signingJwks,
-} from '../fixtures';
-import { signJwt } from './signJwt';
-import { verifyJwt } from './verifyJwt';
+} from '../../fixtures';
+import { signJwt } from '../signJwt';
+import { verifyJwt } from '../verifyJwt';
 
 export default (QUnit: QUnit) => {
   const { module, test } = QUnit;

packages/backend/src/tokens/jwt/verifyJwt.test.ts → packages/backend/src/jwt/__tests__/verifyJwt.test.ts

@@ -10,8 +10,8 @@ import {
   publicJwks,
   signedJwt,
   someOtherPublicKey,
-} from '../fixtures';
-import { decodeJwt, hasValidSignature, verifyJwt } from './verifyJwt';
+} from '../../fixtures';
+import { decodeJwt, hasValidSignature, verifyJwt } from '../verifyJwt';
 
 export default (QUnit: QUnit) => {
   const { module, test } = QUnit;

packages/backend/src/tokens/jwt/cryptoKeys.ts → packages/backend/src/jwt/cryptoKeys.ts

@@ -1,6 +1,6 @@
 import { isomorphicAtob } from '@clerk/shared/isomorphicAtob';
 
-import runtime from '../../runtime';
+import runtime from '../runtime';
 
 // https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#pkcs_8_import
 function pemToBuffer(secret: string): ArrayBuffer {

packages/backend/src/tokens/jwt/signJwt.ts → packages/backend/src/jwt/signJwt.ts

@@ -1,5 +1,5 @@
-import runtime from '../../runtime';
-import { base64url } from '../../util/rfc4648';
+import runtime from '../runtime';
+import { base64url } from '../util/rfc4648';
 import { getCryptoAlgorithm } from './algorithms';
 import { importKey } from './cryptoKeys';
 

packages/backend/src/tokens/jwt/verifyJwt.ts → packages/backend/src/jwt/verifyJwt.ts

@@ -1,10 +1,10 @@
 import type { Jwt, JwtPayload } from '@clerk/types';
 
+import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from '../errors';
 // DO NOT CHANGE: Runtime needs to be imported as a default export so that we can stub its dependencies with Sinon.js
 // For more information refer to https://sinonjs.org/how-to/stub-dependency/
-import runtime from '../../runtime';
-import { base64url } from '../../util/rfc4648';
-import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from '../errors';
+import runtime from '../runtime';
+import { base64url } from '../util/rfc4648';
 import { getCryptoAlgorithm } from './algorithms';
 import {
   assertActivationClaim,