clerk · dimkl · Dec 15, 2023 · Nov 18, 2023 · Dec 14, 2023 · Dec 14, 2023
diff --git a/.changeset/fifty-snakes-accept.md b/.changeset/fifty-snakes-accept.md
@@ -0,0 +1,12 @@
+---
+'@clerk/clerk-sdk-node': major
+---
+
+Drop all pre-instantiated Backend API resources (`allowlistIdentifiers`, `clients`, `emailAddresses`, `emails`, `invitations`, `organizations`, `phoneNumbers`, `redirectUrls`, `sessions`, `signInTokens`, `users`, `domains`). Use the `clerkClient` import instead.
+```typescript
+// Before
+import { users } from "@clerk/clerk-sdk-node"
+// After
+import { clerkClient } from "@clerk/clerk-sdk-node"
+clerkClient.users
+```
diff --git a/.changeset/tasty-terms-fly.md b/.changeset/tasty-terms-fly.md
@@ -0,0 +1,23 @@
+---
+'@clerk/clerk-sdk-node': major
+'@clerk/backend': major
+'@clerk/nextjs': major
+---
+
+Changes in `@clerk/backend` exports:
+- Drop Internal `deserialize` helper
+- Introduce `/errors` subpath export, eg:
+ ```typescript
+ import { 
+ TokenVerificationError,
+ TokenVerificationErrorAction,
+ TokenVerificationErrorCode,
+ TokenVerificationErrorReason } from '@clerk/backend/errors';
+ ```
+- Drop errors from top-level export
+ ```typescript
+ // Before
+ import { TokenVerificationError, TokenVerificationErrorReason } from '@clerk/backend';
+ // After
+ import { TokenVerificationError, TokenVerificationErrorReason } from '@clerk/backend/errors';
+ ```
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -58,11 +58,11 @@ jobs:
 
  - name: Lint types using attw
  timeout-minutes: ${{ fromJSON(vars.TIMEOUT_MINUTES_SHORT) }}
- run: npx turbo lint:attw $TURBO_ARGS --filter=!nextjs --only
+ run: npx turbo lint:attw $TURBO_ARGS --filter=!nextjs --filter=!backend --only
 
  - name: Lint types using attw [Errors Allowed]
  timeout-minutes: ${{ fromJSON(vars.TIMEOUT_MINUTES_SHORT) }}
- run: npx turbo lint:attw $TURBO_ARGS --filter=nextjs --continue --only
+ run: npx turbo lint:attw $TURBO_ARGS --filter=nextjs --filter=backend --continue --only
  continue-on-error: true # TODO: Remove this when all related errors are fixed
 
  - name: Run lint

diff --git a/packages/backend/package.json b/packages/backend/package.json
@@ -24,9 +24,30 @@
  "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"
+ }
+ },
+ "./package.json": "./package.json"
+ },
  "main": "./dist/index.js",
- "module": "./dist/esm/index.js",
- "types": "./dist/types/index.d.ts",
  "files": [
  "dist"
  ],

diff --git a/packages/backend/src/__tests__/exports.test.ts b/packages/backend/src/__tests__/exports.test.ts
@@ -1,5 +1,6 @@
 import type QUnit from 'qunit';
 
+import * as errorExports from '../errors';
 import * as publicExports from '../index';
 
 export default (QUnit: QUnit) => {
@@ -29,8 +30,6 @@ export default (QUnit: QUnit) => {
  'Session',
  'SignInToken',
  'Token',
- 'TokenVerificationError',
- 'TokenVerificationErrorReason',
  'User',
  'Verification',
  'buildRequestUrl',
@@ -40,7 +39,6 @@ export default (QUnit: QUnit) => {
  'createIsomorphicRequest',
  'debugRequestState',
  'decodeJwt',
- 'deserialize',
  'hasValidSignature',
  'makeAuthObjectSerializable',
  'prunePrivateMetadata',
@@ -55,4 +53,16 @@ export default (QUnit: QUnit) => {
  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);
+ });
+ });
 };
diff --git a/packages/backend/src/api/resources/index.ts b/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';
 

diff --git a/packages/backend/src/tokens/errors.ts → packages/backend/src/errors.ts b/packages/backend/src/tokens/errors.ts → packages/backend/src/errors.ts
diff --git a/packages/backend/src/index.ts b/packages/backend/src/index.ts
@@ -2,7 +2,7 @@ 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';
@@ -25,7 +25,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 });

diff --git a/packages/backend/src/runtime.ts b/packages/backend/src/runtime.ts
@@ -13,7 +13,7 @@
  */
 
 // @ts-ignore - These are package subpaths
-import crypto from '#crypto';
+import { webcrypto as crypto } from '#crypto';
 
 type Runtime = {
  crypto: Crypto;

diff --git a/packages/backend/src/runtime/browser/crypto.mjs b/packages/backend/src/runtime/browser/crypto.mjs
@@ -1 +1 @@
-export default crypto;
+export const webcrypto = crypto;
diff --git a/packages/backend/src/runtime/node/crypto.js b/packages/backend/src/runtime/node/crypto.js
@@ -1,11 +1 @@
-let webcrypto;
-try {
- webcrypto = require('node:crypto').webcrypto;
- if (!webcrypto) {
- webcrypto = global.crypto;
- }
-} catch (e) {
- webcrypto = global.crypto;
-}
-
-module.exports = webcrypto;
+module.exports.webcrypto = require('node:crypto').webcrypto;
diff --git a/packages/backend/src/tokens/__tests__/keys.test.ts b/packages/backend/src/tokens/__tests__/keys.test.ts
@@ -1,9 +1,9 @@
 import type QUnit from 'qunit';
 import sinon from 'sinon';
 
+import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from '../../errors';
 import runtime from '../../runtime';
 import { jsonError, jsonOk } from '../../util/testUtils';
-import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from '../errors';
 import {
  mockJwks,
  mockJwtPayload,

diff --git a/packages/backend/src/tokens/__tests__/request.test.ts b/packages/backend/src/tokens/__tests__/request.test.ts
@@ -1,10 +1,10 @@
 import type QUnit from 'qunit';
 import sinon from 'sinon';
 
+import { TokenVerificationErrorReason } from '../../errors';
 import runtime from '../../runtime';
 import { jsonOk } from '../../util/testUtils';
 import { AuthErrorReason, type AuthReason, AuthStatus, type RequestState } from '../authStatus';
-import { TokenVerificationErrorReason } from '../errors';
 import { mockInvalidSignatureJwt, mockJwks, mockJwt, mockJwtPayload, mockMalformedJwt } from '../fixtures';
 import type { AuthenticateRequestOptions } from '../request';
 import { authenticateRequest, loadOptionsFromHeaders } from '../request';

diff --git a/packages/backend/src/tokens/authStatus.ts b/packages/backend/src/tokens/authStatus.ts
@@ -1,9 +1,9 @@
 import type { JwtPayload } from '@clerk/types';
 
 import { createBackendApiClient } from '../api';
+import type { TokenVerificationErrorReason } from '../errors';
 import type { SignedInAuthObject, SignedInAuthObjectOptions, SignedOutAuthObject } from './authObjects';
 import { signedInAuthObject, signedOutAuthObject } from './authObjects';
-import type { TokenVerificationErrorReason } from './errors';
 
 export enum AuthStatus {
  SignedIn = 'signed-in',

diff --git a/packages/backend/src/tokens/handshake.ts b/packages/backend/src/tokens/handshake.ts
@@ -1,4 +1,4 @@
-import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from './errors';
+import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from '../errors';
 import { decodeJwt, hasValidSignature, type VerifyJwtOptions } from './jwt';
 import { assertHeaderAlgorithm, assertHeaderType } from './jwt/assertions';
 import { loadClerkJWKFromLocal, loadClerkJWKFromRemote } from './keys';

diff --git a/packages/backend/src/tokens/index.ts b/packages/backend/src/tokens/index.ts
@@ -1,7 +1,6 @@
 export * from './authObjects';
 export { AuthStatus } from './authStatus';
 export type { RequestState } from './authStatus';
-export { TokenVerificationError, TokenVerificationErrorReason } from './errors';
 export * from './factory';
 export { debugRequestState } from './request';
 export type { AuthenticateRequestOptions, OptionalVerifyTokenOptions } from './request';
diff --git a/packages/backend/src/tokens/jwt/assertions.ts b/packages/backend/src/tokens/jwt/assertions.ts
@@ -1,4 +1,4 @@
-import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from '../errors';
+import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from '../../errors';
 import { algs } from './algorithms';
 
 export type IssuerResolver = string | ((iss: string) => boolean);

diff --git a/packages/backend/src/tokens/jwt/verifyJwt.ts b/packages/backend/src/tokens/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 { getCryptoAlgorithm } from './algorithms';
 import {
  assertActivationClaim,

diff --git a/packages/backend/src/tokens/keys.ts b/packages/backend/src/tokens/keys.ts
@@ -1,16 +1,16 @@
 import { API_URL, API_VERSION, JWKS_CACHE_TTL_MS, MAX_CACHE_LAST_UPDATED_AT_SECONDS } from '../constants';
+import {
+ TokenVerificationError,
+ TokenVerificationErrorAction,
+ TokenVerificationErrorCode,
+ 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 { joinPaths } from '../util/path';
 import { getErrorObjectByCode } from '../util/request';
 import { callWithRetry } from '../util/shared';
-import {
- TokenVerificationError,
- TokenVerificationErrorAction,
- TokenVerificationErrorCode,
- TokenVerificationErrorReason,
-} from './errors';
 
 type JsonWebKeyWithKid = JsonWebKey & { kid: string };
 

diff --git a/packages/backend/src/tokens/request.ts b/packages/backend/src/tokens/request.ts
@@ -2,13 +2,13 @@ import { parsePublishableKey } from '@clerk/shared/keys';
 import type { JwtPayload } from '@clerk/types';
 
 import { constants } from '../constants';
+import type { TokenCarrier } from '../errors';
+import { TokenVerificationError, TokenVerificationErrorReason } from '../errors';
 import { assertValidSecretKey } from '../util/assertValidSecretKey';
 import { buildRequest, stripAuthorizationHeader } from '../util/IsomorphicRequest';
 import { isDevelopmentFromSecretKey } from '../util/shared';
 import type { AuthStatusOptionsType, RequestState } from './authStatus';
 import { AuthErrorReason, handshake, signedIn, signedOut } from './authStatus';
-import type { TokenCarrier } from './errors';
-import { TokenVerificationError, TokenVerificationErrorReason } from './errors';
 import { verifyHandshakeToken } from './handshake';
 import { decodeJwt } from './jwt';
 import { verifyToken, type VerifyTokenOptions } from './verify';

diff --git a/packages/backend/src/tokens/verify.ts b/packages/backend/src/tokens/verify.ts
@@ -1,6 +1,6 @@
 import type { JwtPayload } from '@clerk/types';
 
-import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from './errors';
+import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from '../errors';
 import type { VerifyJwtOptions } from './jwt';
 import { decodeJwt, verifyJwt } from './jwt';
 import type { LoadClerkJWKFromRemoteOptions } from './keys';

diff --git a/packages/backend/tsconfig.declarations.json b/packages/backend/tsconfig.declarations.json
@@ -7,6 +7,6 @@
  "emitDeclarationOnly": true,
  "declarationMap": true,
  "sourceMap": false,
- "declarationDir": "./dist/types"
+ "declarationDir": "./dist"
  }
 }
diff --git a/packages/backend/tsup.config.ts b/packages/backend/tsup.config.ts
@@ -10,7 +10,7 @@ export default defineConfig(overrideOptions => {
  const shouldPublish = !!overrideOptions.env?.publish;
 
  const common: Options = {
- entry: ['src/index.ts'],
+ entry: ['src/index.ts', 'src/errors.ts'],
  onSuccess: `cpy 'src/runtime/**/*.{mjs,js,cjs}' dist/runtime`,
  sourcemap: true,
  define: {
@@ -19,7 +19,6 @@ export default defineConfig(overrideOptions => {
  __DEV__: `${isWatch}`,
  },
  external: ['#crypto'],
- legacyOutput: true,
  bundle: true,
  clean: true,
  minify: false,

diff --git a/packages/sdk-node/src/__tests__/__snapshots__/exports.test.ts.snap b/packages/sdk-node/src/__tests__/__snapshots__/exports.test.ts.snap
@@ -25,14 +25,10 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "Session",
  "SignInToken",
  "Token",
- "TokenVerificationError",
- "TokenVerificationErrorReason",
  "User",
  "Verification",
- "allowlistIdentifiers",
  "buildRequestUrl",
  "clerkClient",
- "clients",
  "constants",
  "createAuthenticateRequest",
  "createClerkClient",
@@ -41,24 +37,15 @@ exports[`module exports should not change unless explicitly set 1`] = `
  "createIsomorphicRequest",
  "debugRequestState",
  "decodeJwt",
- "deserialize",
- "domains",
- "emailAddresses",
- "emails",
  "hasValidSignature",
- "invitations",
  "makeAuthObjectSerializable",
- "organizations",
- "phoneNumbers",
  "prunePrivateMetadata",
  "redirect",
  "requireAuth",
  "sanitizeAuthObject",
- "sessions",
  "signJwt",
  "signedInAuthObject",
  "signedOutAuthObject",
- "users",
  "verifyJwt",
  "verifyToken",
  "withAuth",
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		export default crypto;
		export const webcrypto = crypto;