chore(backend): Apply deprecation warnings

.changeset/eighty-swans-trade.md

@@ -2,7 +2,7 @@
 '@clerk/shared': patch
 ---
 
-Apply deprecation warnings:
+Apply deprecation warnings for `@clerk/shared`:
 - `OrganizationContext`
 - `organizationList`
 - `useOrganizations`

.changeset/late-carrots-notice.md

@@ -1,5 +1,5 @@
 ---
 '@clerk/clerk-react': patch
 ---
-
-Warn about `setSession` deprecation.
+Apply deprecation warnings for `@clerk/clerk-react`:
+- `setSession`

.changeset/silent-fishes-change.md

@@ -2,4 +2,4 @@
 '@clerk/backend': minor
 ---
 
-Replace utilities with @clerk/shared exports
+Replace utilities with `@clerk/shared` exports

.changeset/spicy-toys-change.md

@@ -2,4 +2,9 @@
 '@clerk/nextjs': patch
 ---
 
-Warn about deprecations that will be dropped in next major version
+Apply deprecation warnings for `@clerk/nextjs`:
+- `CLERK_JS_VERSION` environment variable
+- `CLERK_API_KEY` environment variable
+- `NEXT_PUBLIC_CLERK_FRONTEND_API` environment variable
+- `withClerkMiddleware`
+- `withServerSideAuth`

.changeset/two-ads-type.md

@@ -0,0 +1,14 @@
+---
+"@clerk/backend": patch
+---
+
+Apply deprecation warnings for `@clerk/backend`:
+-  backend api return format
+- `clockSkewInSeconds`
+- `pkgVersion`
+- `picture`/`logoUrl`/`profileImageUrl`
+- `InterstitialAPI`
+- `httpOptions`
+- `apiKey`
+- `frontendApi`
+- `__unstable_options`

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

@@ -1,10 +1,15 @@
+import { deprecated } from '../../util/shared';
 import { AbstractAPI } from './AbstractApi';
-
 /**
  * @deprecated Switch to the public interstitial endpoint from Clerk Backend API.
  */
 export class InterstitialAPI extends AbstractAPI {
   public async getInterstitial() {
+    deprecated(
+      'getInterstitial()',
+      'Switch to `Clerk(...).localInterstitial(...)` from `import { Clerk } from "@clerk/backend"`.',
+    );
+
     return this.request<string>({
       path: 'internal/interstitial',
       method: 'GET',

packages/backend/src/api/request.ts

@@ -8,6 +8,7 @@ import { API_URL, API_VERSION, constants, USER_AGENT } from '../constants';
 import runtime from '../runtime';
 import { assertValidSecretKey } from '../util/assertValidSecretKey';
 import { joinPaths } from '../util/path';
+import { deprecated } from '../util/shared';
 import type { CreateBackendApiOptions } from './factory';
 import { deserialize } from './resources/Deserializer';
 
@@ -50,6 +51,11 @@ type LegacyRequestFunction = <T>(requestOptions: ClerkBackendApiRequestOptions)
 const withLegacyReturn =
   (cb: any): LegacyRequestFunction =>
   async (...args) => {
+    deprecated(
+      '',
+      'Resources return format will switch to `{ data: any, errors: ClerkAPIError[] }` from `data | never` the next major version.',
+      'resources-legacy-return',
+    );
     // @ts-ignore
     const { data, errors, status, statusText } = await cb<T>(...args);
     if (errors === null) {
@@ -67,11 +73,21 @@ export function buildRequest(options: CreateBackendApiOptions) {
     const {
       apiKey,
       secretKey,
+      httpOptions,
       apiUrl = API_URL,
       apiVersion = API_VERSION,
       userAgent = USER_AGENT,
-      httpOptions = {},
     } = options;
+    if (apiKey) {
+      deprecated('apiKey', 'Use `secretKey` instead.');
+    }
+    if (httpOptions) {
+      deprecated(
+        'httpOptions',
+        'This option has been deprecated and will be removed with the next major release.\nA RequestInit init object used by the `request` method.',
+      );
+    }
+
     const { path, method, queryParams, headerParams, bodyParams, formData } = requestOptions;
     const key = secretKey || apiKey;
 
@@ -119,7 +135,7 @@ export function buildRequest(options: CreateBackendApiOptions) {
 
         res = await runtime.fetch(
           finalUrl.href,
-          deepmerge(httpOptions, {
+          deepmerge(httpOptions || {}, {
             method,
             headers,
             ...body,

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

@@ -1,3 +1,4 @@
+import { deprecatedProperty } from '../../util/shared';
 import type { ExternalAccountJSON } from './JSON';
 import { Verification } from './Verification';
 
@@ -41,3 +42,5 @@ export class ExternalAccount {
     );
   }
 }
+
+deprecatedProperty(ExternalAccount, 'picture', 'Use `imageUrl` instead.');

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

@@ -1,3 +1,4 @@
+import { deprecatedProperty } from '../../util/shared';
 import type { OrganizationJSON } from './JSON';
 
 export class Organization {
@@ -40,3 +41,5 @@ export class Organization {
     );
   }
 }
+
+deprecatedProperty(Organization, 'logoUrl', 'Use `imageUrl` instead.');

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

@@ -1,3 +1,4 @@
+import { deprecatedProperty } from '../../util/shared';
 import { Organization } from '../resources';
 import type { OrganizationMembershipRole } from './Enums';
 import type { OrganizationMembershipJSON, OrganizationMembershipPublicUserDataJSON } from './JSON';
@@ -54,3 +55,5 @@ export class OrganizationMembershipPublicUserData {
     );
   }
 }
+
+deprecatedProperty(OrganizationMembershipPublicUserData, 'profileImageUrl', 'Use `imageUrl` instead.');

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

@@ -1,3 +1,4 @@
+import { deprecatedProperty } from '../../util/shared';
 import { EmailAddress } from './EmailAddress';
 import { ExternalAccount } from './ExternalAccount';
 import type { ExternalAccountJSON, UserJSON } from './JSON';
@@ -72,3 +73,5 @@ export class User {
     );
   }
 }
+
+deprecatedProperty(User, 'profileImageUrl', 'Use `imageUrl` instead.');

packages/backend/src/index.ts

@@ -1,3 +1,5 @@
+import { deprecatedObjectProperty } from '@clerk/shared';
+
 import type { CreateBackendApiOptions } from './api';
 import { createBackendApiClient } from './api';
 import type { CreateAuthenticateRequestOptions } from './tokens';
@@ -26,12 +28,22 @@ export function Clerk(options: ClerkOptions) {
   const apiClient = createBackendApiClient(opts);
   const requestState = createAuthenticateRequest({ options: opts, apiClient });
 
-  return {
+  const clerkInstance = {
     ...apiClient,
     ...requestState,
     /**
      * @deprecated This prop has been deprecated and will be removed in the next major release.
      */
     __unstable_options: opts,
   };
+
+  // The __unstable_options is not being used internally and
+  // it's only being set in packages/sdk-node/src/clerkClient.ts#L86
+  deprecatedObjectProperty(
+    clerkInstance,
+    '__unstable_options',
+    'Use `createClerkClient({...})` to create a new clerk instance instead.',
+  );
+
+  return clerkInstance;
 }

packages/backend/src/redirections.ts

@@ -1,4 +1,4 @@
-import { errorThrower, parsePublishableKey } from './util/shared';
+import { deprecated, errorThrower, parsePublishableKey } from './util/shared';
 
 type RedirectAdapter = (url: string) => any;
 
@@ -39,6 +39,8 @@ type RedirectParams = {
 export function redirect({ redirectAdapter, signUpUrl, signInUrl, frontendApi, publishableKey }: RedirectParams) {
   if (!frontendApi) {
     frontendApi = parsePublishableKey(publishableKey)?.frontendApi;
+  } else {
+    deprecated('frontentApi', 'Use `publishableKey` instead.');
   }
 
   const accountsBaseUrl = buildAccountsBaseUrl(frontendApi);

packages/backend/src/tokens/interstitial.ts

@@ -8,6 +8,7 @@ import { joinPaths } from '../util/path';
 import {
   addClerkPrefix,
   callWithRetry,
+  deprecated,
   getClerkJsMajorVersionOrTag,
   getScriptUrl,
   isDevOrStagingUrl,
@@ -33,6 +34,13 @@ export type LoadInterstitialOptions = {
 } & MultiDomainAndOrProxyPrimitives;
 
 export function loadInterstitialFromLocal(options: Omit<LoadInterstitialOptions, 'apiUrl'>) {
+  if (options.frontendApi) {
+    deprecated('frontentApi', 'Use `publishableKey` instead.');
+  }
+  if (options.pkgVersion) {
+    deprecated('pkgVersion', 'Use `clerkJSVersion` instead.');
+  }
+
   options.frontendApi = parsePublishableKey(options.publishableKey)?.frontendApi || options.frontendApi || '';
   const domainOnlyInProd = !isDevOrStagingUrl(options.frontendApi) ? addClerkPrefix(options.domain) : '';
   const {
@@ -126,6 +134,12 @@ export function loadInterstitialFromLocal(options: Omit<LoadInterstitialOptions,
 
 // TODO: Add caching to Interstitial
 export async function loadInterstitialFromBAPI(options: LoadInterstitialOptions) {
+  if (options.frontendApi) {
+    deprecated('frontentApi', 'Use `publishableKey` instead.');
+  }
+  if (options.pkgVersion) {
+    deprecated('pkgVersion', 'Use `clerkJSVersion` instead.');
+  }
   options.frontendApi = parsePublishableKey(options.publishableKey)?.frontendApi || options.frontendApi || '';
   const url = buildPublicInterstitialUrl(options);
   const response = await callWithRetry(() =>
@@ -149,6 +163,10 @@ export async function loadInterstitialFromBAPI(options: LoadInterstitialOptions)
 }
 
 export function buildPublicInterstitialUrl(options: LoadInterstitialOptions) {
+  if (options.frontendApi) {
+    deprecated('frontentApi', 'Use `publishableKey` instead.');
+  }
+
   options.frontendApi = parsePublishableKey(options.publishableKey)?.frontendApi || options.frontendApi || '';
   const { apiUrl, frontendApi, pkgVersion, clerkJSVersion, publishableKey, proxyUrl, isSatellite, domain, signInUrl } =
     options;

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

@@ -4,6 +4,7 @@ import type { Jwt, JwtPayload } from '@clerk/types';
 // For more information refer to https://sinonjs.org/how-to/stub-dependency/
 import runtime from '../../runtime';
 import { base64url } from '../../util/rfc4648';
+import { deprecated } from '../../util/shared';
 import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from '../errors';
 import type { IssuerResolver } from './assertions';
 import {
@@ -114,6 +115,10 @@ export async function verifyJwt(
   token: string,
   { audience, authorizedParties, clockSkewInSeconds, clockSkewInMs, issuer, key }: VerifyJwtOptions,
 ): Promise<JwtPayload> {
+  if (clockSkewInSeconds) {
+    deprecated('clockSkewInSeconds', 'Use `clockSkewInMs` instead.');
+  }
+
   const clockSkew = clockSkewInMs || clockSkewInSeconds || DEFAULT_CLOCK_SKEW_IN_SECONDS;
 
   const decoded = decodeJwt(token);

packages/backend/src/tokens/request.ts

@@ -1,7 +1,7 @@
 import { API_URL, API_VERSION, constants } from '../constants';
 import { assertValidSecretKey } from '../util/assertValidSecretKey';
 import { buildRequest, stripAuthorizationHeader } from '../util/IsomorphicRequest';
-import { isDevelopmentFromApiKey, parsePublishableKey } from '../util/shared';
+import { deprecated, isDevelopmentFromApiKey, parsePublishableKey } from '../util/shared';
 import type { RequestState } from './authStatus';
 import { AuthErrorReason, interstitial, signedOut, unknownState } from './authStatus';
 import type { TokenCarrier } from './errors';
@@ -120,6 +120,14 @@ function assertProxyUrlOrDomain(proxyUrlOrDomain: string | undefined) {
 export async function authenticateRequest(options: AuthenticateRequestOptions): Promise<RequestState> {
   const { cookies, headers, searchParams } = buildRequest(options?.request);
 
+  if (options.frontendApi) {
+    deprecated('frontentApi', 'Use `publishableKey` instead.');
+  }
+
+  if (options.apiKey) {
+    deprecated('apiKey', 'Use `secretKey` instead.');
+  }
+
   options = {
     ...options,
     frontendApi: parsePublishableKey(options.publishableKey)?.frontendApi || options.frontendApi,

packages/backend/src/tokens/verify.ts

@@ -1,5 +1,6 @@
 import type { JwtPayload } from '@clerk/types';
 
+import { deprecated } from '../util/shared';
 import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from './errors';
 import type { VerifyJwtOptions } from './jwt';
 import { decodeJwt, verifyJwt } from './jwt';
@@ -33,6 +34,10 @@ export async function verifyToken(token: string, options: VerifyTokenOptions): P
     skipJwksCache,
   } = options;
 
+  if (options.apiKey) {
+    deprecated('apiKey', 'Use `secretKey` instead.');
+  }
+
   const { header } = decodeJwt(token);
   const { kid } = header;
 

packages/backend/src/util/shared.ts

@@ -6,6 +6,8 @@ export {
   isDevelopmentFromApiKey,
   isProductionFromApiKey,
   parsePublishableKey,
+  deprecated,
+  deprecatedProperty,
 } from '@clerk/shared';
 
 import { buildErrorThrower } from '@clerk/shared';