chore(backend,clerk-js,types): Deprecate profile_image_url / avatar_url / logo_url (#1543)

* refactor(backend): Deprecate logo_url / profile_image_url / avatar_url for image_url

* refactor(clerk-js): Deprecate logo_url / profile_image_url / avatar_url for image_url

* refactor(types): Deprecate logo_url / profile_image_url / avatar_url for image_url

* chore(repo): Add changeset for image fields deprecation

Author: dimkl

.changeset/beige-apes-cry.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/backend': patch
+'@clerk/types': patch
+---
+
+Deprecate usage of old image fields in favor of `imageUrl`

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

@@ -11,6 +11,9 @@ export class ExternalAccount {
     readonly emailAddress: string,
     readonly firstName: string,
     readonly lastName: string,
+    /**
+     * @deprecated  Use `imageUrl` instead.
+     */
     readonly picture: string,
     readonly imageUrl: string,
     readonly username: string | null,

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

@@ -92,10 +92,10 @@ export interface ExternalAccountJSON extends ClerkResourceJSON {
   email_address: string;
   first_name: string;
   last_name: string;
-  avatar_url: string;
   /**
-   * @experimental
+   * @deprecated  Use `image_url` instead.
    */
+  avatar_url: string;
   image_url: string;
   username: string | null;
   public_metadata: Record<string, unknown> | null;
@@ -133,10 +133,10 @@ export interface OrganizationJSON extends ClerkResourceJSON {
   object: ObjectType.Organization;
   name: string;
   slug: string | null;
-  logo_url: string | null;
   /**
-   * @experimental
+   * @deprecated  Use `image_url` instead.
    */
+  logo_url: string | null;
   image_url: string;
   public_metadata: OrganizationPublicMetadata | null;
   private_metadata?: OrganizationPrivateMetadata;
@@ -173,10 +173,10 @@ export interface OrganizationMembershipPublicUserDataJSON {
   identifier: string;
   first_name: string | null;
   last_name: string | null;
-  profile_image_url: string;
   /**
-   * @experimental
+   * @deprecated  Use `image_url` instead.
    */
+  profile_image_url: string;
   image_url: string;
   user_id: string;
 }
@@ -259,10 +259,10 @@ export interface UserJSON extends ClerkResourceJSON {
   last_name: string;
   gender: string;
   birthday: string;
-  profile_image_url: string;
   /**
-   * @experimental
+   * @deprecated  Use `image_url` instead.
    */
+  profile_image_url: string;
   image_url: string;
   primary_email_address_id: string;
   primary_phone_number_id: string | null;

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

@@ -5,6 +5,9 @@ export class Organization {
     readonly id: string,
     readonly name: string,
     readonly slug: string | null,
+    /**
+     * @deprecated  Use `imageUrl` instead.
+     */
     readonly logoUrl: string | null,
     readonly imageUrl: string,
     readonly createdBy: string,

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

@@ -33,6 +33,9 @@ export class OrganizationMembershipPublicUserData {
     readonly identifier: string,
     readonly firstName: string | null,
     readonly lastName: string | null,
+    /**
+     * @deprecated  Use `imageUrl` instead.
+     */
     readonly profileImageUrl: string,
     readonly imageUrl: string,
     readonly userId: string,

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

@@ -14,6 +14,9 @@ export class User {
     readonly banned: boolean,
     readonly createdAt: number,
     readonly updatedAt: number,
+    /**
+     * @deprecated  Use `imageUrl` instead.
+     */
     readonly profileImageUrl: string,
     readonly imageUrl: string,
     readonly gender: string,

packages/clerk-js/src/core/resources/ExternalAccount.ts

@@ -19,6 +19,9 @@ export class ExternalAccount extends BaseResource implements ExternalAccountReso
   approvedScopes = '';
   firstName = '';
   lastName = '';
+  /**
+   * @deprecated  Use `imageUrl` instead.
+   */
   avatarUrl = '';
   imageUrl = '';
   username = '';

packages/clerk-js/src/core/resources/Organization.ts

@@ -24,6 +24,9 @@ export class Organization extends BaseResource implements OrganizationResource {
   id!: string;
   name!: string;
   slug!: string;
+  /**
+   * @deprecated  Use `imageUrl` instead.
+   */
   logoUrl!: string;
   imageUrl!: string;
   publicMetadata: OrganizationPublicMetadata = {};

packages/clerk-js/src/core/resources/User.ts

@@ -74,6 +74,9 @@ export class User extends BaseResource implements UserResource {
   primaryPhoneNumber: PhoneNumberResource | null = null;
   primaryWeb3WalletId: string | null = null;
   primaryWeb3Wallet: Web3WalletResource | null = null;
+  /**
+   * @deprecated  Use `imageUrl` instead.
+   */
   profileImageUrl = '';
   imageUrl = '';
   twoFactorEnabled = false;

packages/types/src/externalAccount.ts

@@ -16,6 +16,9 @@ export interface ExternalAccountResource extends ClerkResource {
   approvedScopes: string;
   firstName: string;
   lastName: string;
+  /**
+   * @deprecated  Use `imageUrl` instead.
+   */
   avatarUrl: string;
   imageUrl: string;
   username?: string;

packages/types/src/json.ts

@@ -151,10 +151,10 @@ export interface ExternalAccountJSON extends ClerkResourceJSON {
   email_address: string;
   first_name: string;
   last_name: string;
-  avatar_url: string;
   /**
-   * @experimental
+   * @deprecated  Use `image_url` instead.
    */
+  avatar_url: string;
   image_url: string;
   username: string;
   public_metadata: Record<string, unknown>;
@@ -183,10 +183,10 @@ export interface UserJSON extends ClerkResourceJSON {
   primary_email_address_id: string;
   primary_phone_number_id: string;
   primary_web3_wallet_id: string;
-  profile_image_url: string;
   /**
-   * @experimental
+   * @deprecated  Use `image_url` instead.
    */
+  profile_image_url: string;
   image_url: string;
   username: string;
   email_addresses: EmailAddressJSON[];
@@ -223,10 +223,10 @@ export interface UserJSON extends ClerkResourceJSON {
 export interface PublicUserDataJSON extends ClerkResourceJSON {
   first_name: string | null;
   last_name: string | null;
-  profile_image_url: string;
   /**
-   * @experimental
+   * @deprecated  Use `image_url` instead.
    */
+  profile_image_url: string;
   image_url: string;
   identifier: string;
   user_id?: string;
@@ -301,10 +301,10 @@ export interface SessionActivityJSON extends ClerkResourceJSON {
 export interface OrganizationJSON extends ClerkResourceJSON {
   object: 'organization';
   id: string;
-  logo_url: string;
   /**
-   * @experimental
+   * @deprecated  Use `image_url` instead.
    */
+  logo_url: string;
   image_url: string;
   name: string;
   slug: string;
@@ -355,10 +355,10 @@ export interface UserOrganizationInvitationJSON extends ClerkResourceJSON {
 export interface UserDataJSON {
   first_name?: string;
   last_name?: string;
-  profile_image_url?: string;
   /**
-   * @experimental
+   * @deprecated  Use `image_url` instead.
    */
+  profile_image_url?: string;
   image_url: string;
 }
 

packages/types/src/session.ts

@@ -55,6 +55,9 @@ export type SessionStatus = 'abandoned' | 'active' | 'ended' | 'expired' | 'remo
 export interface PublicUserData {
   firstName: string | null;
   lastName: string | null;
+  /**
+   * @deprecated  Use `imageUrl` instead.
+   */
   profileImageUrl: string;
   imageUrl: string;
   identifier: string;

packages/types/src/signIn.ts

@@ -121,6 +121,9 @@ export type SignInSecondFactor = PhoneCodeFactor | TOTPFactor | BackupCodeFactor
 export interface UserData {
   firstName?: string;
   lastName?: string;
+  /**
+   * @deprecated  Use `imageUrl` instead.
+   */
   profileImageUrl?: string;
   imageUrl?: string;
 }

packages/types/src/user.ts

@@ -59,6 +59,9 @@ export interface UserResource extends ClerkResource {
   fullName: string | null;
   firstName: string | null;
   lastName: string | null;
+  /**
+   * @deprecated  Use `imageUrl` instead.
+   */
   profileImageUrl: string;
   imageUrl: string;
   emailAddresses: EmailAddressResource[];