fix(shared, nextjs): Support importing @clerk/shared in @clerk/backend

.changeset/metal-lions-switch.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Introduce `getClerkJsMajorVersionOrTag()`, `getScriptUrl()`, `callWithRetry()`

.changeset/silent-fishes-change.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Replace utilities with @clerk/shared exports

packages/backend/package.json

@@ -44,6 +44,7 @@
     "test:cloudflare-workerd": "tests/cloudflare-workerd/run.sh"
   },
   "dependencies": {
+    "@clerk/shared": "^0.23.1",
     "@clerk/types": "^3.52.1",
     "@peculiar/webcrypto": "1.4.1",
     "@types/node": "16.18.6",

packages/backend/global.d.ts → packages/backend/src/global.d.ts

@@ -1,7 +1,7 @@
-export {};
-
 declare global {
   const PACKAGE_NAME: string;
   const PACKAGE_VERSION: string;
   const __DEV__: boolean;
 }
+
+export {};

packages/backend/src/redirections.test.ts

@@ -75,7 +75,7 @@ export default (QUnit: QUnit) => {
       assert.raises(
         () => redirectToSignIn({ returnBackUrl }),
         new Error(
-          'Missing publishableKey. You can get your key at https://dashboard.clerk.com/last-active?path=api-keys.',
+          '@clerk/backend: Missing publishableKey. You can get your key at https://dashboard.clerk.com/last-active?path=api-keys.',
         ),
       );
     });
@@ -221,7 +221,7 @@ export default (QUnit: QUnit) => {
       assert.raises(
         () => redirectToSignUp({ returnBackUrl }),
         new Error(
-          'Missing publishableKey. You can get your key at https://dashboard.clerk.com/last-active?path=api-keys.',
+          '@clerk/backend: Missing publishableKey. You can get your key at https://dashboard.clerk.com/last-active?path=api-keys.',
         ),
       );
     });

packages/backend/src/redirections.ts

@@ -1,5 +1,4 @@
-import { missingPublishableKeyErrorMessage } from './shared';
-import { parsePublishableKey } from './shared';
+import { errorThrower, parsePublishableKey } from './util/shared';
 
 type RedirectAdapter = (url: string) => any;
 
@@ -46,7 +45,7 @@ export function redirect({ redirectAdapter, signUpUrl, signInUrl, frontendApi, p
 
   const redirectToSignUp = ({ returnBackUrl }: SignUpParams = {}) => {
     if (!signUpUrl && !accountsBaseUrl) {
-      throw new Error(missingPublishableKeyErrorMessage);
+      errorThrower.throwMissingPublishableKeyError();
     }
 
     const accountsSignUpUrl = `${accountsBaseUrl}/sign-up`;
@@ -55,7 +54,7 @@ export function redirect({ redirectAdapter, signUpUrl, signInUrl, frontendApi, p
 
   const redirectToSignIn = ({ returnBackUrl }: SignInParams = {}) => {
     if (!signInUrl && !accountsBaseUrl) {
-      throw new Error(missingPublishableKeyErrorMessage);
+      errorThrower.throwMissingPublishableKeyError();
     }
 
     const accountsSignInUrl = `${accountsBaseUrl}/sign-in`;

packages/backend/src/tokens/interstitial.ts

@@ -4,15 +4,15 @@ import { API_VERSION, USER_AGENT } from '../constants';
 // 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 {
   addClerkPrefix,
   callWithRetry,
   getClerkJsMajorVersionOrTag,
   getScriptUrl,
   isDevOrStagingUrl,
   parsePublishableKey,
-} from '../shared';
-import { joinPaths } from '../util/path';
+} from '../util/shared';
 import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from './errors';
 import type { DebugRequestSate } from './request';
 

packages/backend/src/tokens/interstitialRule.ts

@@ -1,5 +1,5 @@
-import { isDevelopmentFromApiKey, isProductionFromApiKey } from '../shared';
 import { checkCrossOrigin } from '../util/request';
+import { isDevelopmentFromApiKey, isProductionFromApiKey } from '../util/shared';
 import type { RequestState } from './authStatus';
 import { AuthErrorReason, interstitial, signedIn, signedOut } from './authStatus';
 import type { AuthenticateRequestOptions } from './request';

packages/backend/src/tokens/keys.ts

@@ -2,9 +2,9 @@ import { API_URL, API_VERSION, MAX_CACHE_LAST_UPDATED_AT_SECONDS } from '../cons
 // 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 { callWithRetry } from '../shared';
 import { joinPaths } from '../util/path';
 import { getErrorObjectByCode } from '../util/request';
+import { callWithRetry } from '../util/shared';
 import {
   TokenVerificationError,
   TokenVerificationErrorAction,

packages/backend/src/tokens/request.ts

@@ -1,7 +1,7 @@
 import { API_URL, API_VERSION, constants } from '../constants';
-import { isDevelopmentFromApiKey, parsePublishableKey } from '../shared';
 import { assertValidSecretKey } from '../util/assertValidSecretKey';
 import { buildRequest, stripAuthorizationHeader } from '../util/IsomorphicRequest';
+import { isDevelopmentFromApiKey, parsePublishableKey } from '../util/shared';
 import type { RequestState } from './authStatus';
 import { AuthErrorReason, interstitial, signedOut, unknownState } from './authStatus';
 import type { TokenCarrier } from './errors';

packages/backend/src/util/shared.ts

@@ -0,0 +1,16 @@
+export {
+  addClerkPrefix,
+  callWithRetry,
+  getClerkJsMajorVersionOrTag,
+  getScriptUrl,
+  isDevelopmentFromApiKey,
+  isProductionFromApiKey,
+  parsePublishableKey,
+} from '@clerk/shared';
+
+import { buildErrorThrower } from '@clerk/shared';
+// TODO: replace packageName with `${PACKAGE_NAME}@${PACKAGE_VERSION}` from tsup.config.ts
+export const errorThrower = buildErrorThrower({ packageName: '@clerk/backend' });
+
+import { createDevOrStagingUrlCache } from '@clerk/shared';
+export const { isDevOrStagingUrl } = createDevOrStagingUrlCache();

packages/backend/src/shared/callWithRetry.ts → packages/shared/src/utils/callWithRetry.ts

@@ -4,7 +4,12 @@ function wait(ms: number) {
 
 const MAX_NUMBER_OF_RETRIES = 5;
 
-// TODO: Move this to @clerk/shared and reuse it with @clerk/clerk-js
+/**
+ * Retry callback function every few hundred ms (with an exponential backoff
+ * based on the current attempt) until the maximum attempts has reached or
+ * the callback is executed successfully. The default number of maximum
+ * attempts is 5 and retries are triggered when callback throws an error.
+ */
 export async function callWithRetry<T>(
   fn: (...args: unknown[]) => Promise<T>,
   attempt = 1,

packages/shared/src/utils/index.ts

@@ -24,3 +24,5 @@ export * from './globs';
 export * from './loadScript';
 export * from './runtimeEnvironment';
 export { deprecated, deprecatedProperty, deprecatedObjectProperty } from './deprecated';
+export { callWithRetry } from './callWithRetry';
+export { isDevelopmentFromApiKey, isProductionFromApiKey, isStaging } from './instance';

packages/shared/src/utils/keys.ts

@@ -55,6 +55,7 @@ export function isLegacyFrontendApiKey(key: string) {
 }
 
 export function createDevOrStagingUrlCache() {
+  // TODO: Check if we can merge it with `./instance.ts#isStaging()`
   const DEV_OR_STAGING_SUFFIXES = [
     '.lcl.dev',
     '.stg.dev',

packages/shared/src/utils/url.ts

@@ -1,3 +1,5 @@
+import { isStaging } from './instance';
+
 export function parseSearchParams(queryString = ''): URLSearchParams {
   if (queryString.startsWith('?')) {
     queryString = queryString.slice(1);
@@ -25,3 +27,40 @@ export function addClerkPrefix(str: string | undefined) {
   const stripped = str.replace(regex, '');
   return `clerk.${stripped}`;
 }
+
+/**
+ *
+ * Retrieve the clerk-js major tag using the major version from the pkgVersion
+ * param or use the frontendApi to determine if the staging tag should be used.
+ * The default tag is `latest` and a `next` pkgVersion also exists to retrieve
+ * the next canary release.
+ */
+export const getClerkJsMajorVersionOrTag = (frontendApi: string, pkgVersion?: string) => {
+  if (!pkgVersion && isStaging(frontendApi)) {
+    return 'staging';
+  }
+
+  if (!pkgVersion) {
+    return 'latest';
+  }
+
+  if (pkgVersion.includes('next')) {
+    return 'next';
+  }
+
+  return pkgVersion.split('.')[0] || 'latest';
+};
+
+/**
+ *
+ * Retrieve the clerk-js script url from the frontendApi and the major tag
+ * using the {@link getClerkJsMajorVersionOrTag} or a provided clerkJSVersion tag.
+ */
+export const getScriptUrl = (
+  frontendApi: string,
+  { pkgVersion, clerkJSVersion }: { pkgVersion?: string; clerkJSVersion?: string },
+) => {
+  const noSchemeFrontendApi = frontendApi.replace(/http(s)?:\/\//, '');
+  const major = getClerkJsMajorVersionOrTag(frontendApi, pkgVersion);
+  return `https://${noSchemeFrontendApi}/npm/@clerk/clerk-js@${clerkJSVersion || major}/dist/clerk.browser.js`;
+};