@clerk/types 4.53.0 → 4.53.1-canary.v20250411131008

package/dist/index.d.mts

@@ -461,7 +461,13 @@ interface OrganizationDomainVerification {
     attempts: number;
     expiresAt: Date;
 }
+/**
+ * @inline
+ */
 type OrganizationDomainVerificationStatus = 'unverified' | 'verified';
+/**
+ * @inline
+ */
 type OrganizationEnrollmentMode = 'manual_invitation' | 'automatic_invitation' | 'automatic_suggestion';
 interface OrganizationDomainResource extends ClerkResource {
     id: string;
@@ -513,6 +519,9 @@ interface OrganizationInvitationResource extends ClerkResource {
     updatedAt: Date;
     revoke: () => Promise<OrganizationInvitationResource>;
 }
+/**
+ * @inline
+ */
 type OrganizationInvitationStatus = 'pending' | 'accepted' | 'revoked';
 
 type SnakeToCamel<T> = T extends `${infer A}_${infer B}` ? `${Uncapitalize<A>}${Capitalize<SnakeToCamel<B>>}` : T extends object ? {
@@ -527,6 +536,9 @@ type DeepCamelToSnake<T> = T extends `${infer C0}${infer R}` ? `${C0 extends Upp
 type CamelToSnake<T> = T extends `${infer C0}${infer R}` ? `${C0 extends Uppercase<C0> ? '_' : ''}${Lowercase<C0>}${CamelToSnake<R>}` : T extends object ? {
     [K in keyof T as CamelToSnake<Extract<K, string>>]: T[K];
 } : T;
+/**
+ * @internal
+ */
 type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
 };
@@ -981,6 +993,9 @@ interface ImageResource extends ClerkResource {
     publicUrl: string | null;
 }
 
+/**
+ * @inline
+ */
 type OrganizationSuggestionStatus = 'pending' | 'accepted';
 interface OrganizationSuggestionResource extends ClerkResource {
     id: string;
@@ -1149,6 +1164,15 @@ declare global {
         [k: string]: unknown;
     }
 }
+/**
+ * The `User` object holds all of the information for a single user of your application and provides a set of methods to manage their account. Each `User` has at least one authentication [identifier](https://clerk.com/docs/authentication/configuration/sign-up-sign-in-options#identifiers), which might be their email address, phone number, or a username.
+ *
+ * A user can be contacted at their primary email address or primary phone number. They can have more than one registered email address, but only one of them will be their primary email address. This goes for phone numbers as well; a user can have more than one, but only one phone number will be their primary. At the same time, a user can also have one or more external accounts by connecting to [social providers](https://clerk.com/docs/authentication/social-connections/oauth) such as Google, Apple, Facebook, and many more.
+ *
+ * Finally, a `User` object holds profile data like the user's name, profile picture, and a set of [metadata](/docs/users/metadata) that can be used internally to store arbitrary information. The metadata are split into `publicMetadata` and `privateMetadata`. Both types are set from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}, but public metadata can also be accessed from the [Frontend API](https://clerk.com/docs/reference/frontend-api){{ target: '_blank' }}.
+ *
+ * The ClerkJS SDK provides some helper [methods](#methods) on the `User` object to help retrieve and update user information and authentication status.
+ */
 interface UserResource extends ClerkResource {
     id: string;
     externalId: string | null;
@@ -1253,6 +1277,9 @@ type GetUserOrganizationSuggestionsParams = ClerkPaginationParams<{
 type GetUserOrganizationMembershipParams = ClerkPaginationParams;
 type GetOrganizationMemberships = (params?: GetUserOrganizationMembershipParams) => Promise<ClerkPaginatedResponse<OrganizationMembershipResource>>;
 
+/**
+ * @inline
+ */
 type PendingSessionOptions = {
     /**
      * Determines if pending sessions are considered as signed-out state.
@@ -1261,7 +1288,9 @@ type PendingSessionOptions = {
     treatPendingAsSignedOut?: boolean;
 };
 type DisallowSystemPermissions<P extends string> = P extends `${OrganizationSystemPermissionPrefix}${string}` ? 'System permissions are not included in session claims and cannot be used on the server-side' : P;
+/** @inline */
 type CheckAuthorizationFn<Params> = (isAuthorizedParams: Params) => boolean;
+/** @inline */
 type CheckAuthorizationWithCustomPermissions = CheckAuthorizationFn<CheckAuthorizationParamsWithCustomPermissions>;
 type WithReverification<T> = T & {
     reverification?: ReverificationConfig;
@@ -1421,6 +1450,9 @@ type GetTokenOptions = {
     leewayInSeconds?: number;
     skipCache?: boolean;
 };
+/**
+ * @inline
+ */
 type GetToken = (options?: GetTokenOptions) => Promise<string | null>;
 type SessionVerifyCreateParams = {
     level: SessionVerificationLevel;
@@ -1596,7 +1628,11 @@ interface OrganizationMembershipResource extends ClerkResource {
 }
 type OrganizationCustomPermissionKey = ClerkAuthorization extends Placeholder ? ClerkAuthorization['permission'] extends string ? ClerkAuthorization['permission'] : Base['permission'] : Base['permission'];
 /**
- * OrganizationCustomRoleKey will be string unless the developer has provided their own types through `ClerkAuthorization`
+ * `OrganizationCustomRoleKey` is a type that represents the user's role in an organization. It will be string unless the developer has provided their own types through [`ClerkAuthorization`](https://clerk.com/docs/guides/custom-types#example-custom-roles-and-permissions).
+ *
+ * Clerk provides the [default roles](https://clerk.com/docs/organizations/roles-permissions#default-roles) `org:admin` and `org:member`. However, you can create [custom roles](https://clerk.com/docs/organizations/create-roles-permissions) as well.
+ *
+ * @interface
  */
 type OrganizationCustomRoleKey = ClerkAuthorization extends Placeholder ? ClerkAuthorization['role'] extends string ? ClerkAuthorization['role'] : Base['role'] : Base['role'];
 type OrganizationSystemPermissionPrefix = 'org:sys_';
@@ -2058,6 +2094,7 @@ type SignInForceRedirectUrl = {
 
 /**
  * The `SignIn` object holds the state of the current sign-in and provides helper methods to navigate and complete the sign-in process. It is used to manage the sign-in lifecycle, including the first and second factor verification, and the creation of a new session.
+ * @interface
  */
 interface SignInResource extends ClerkResource {
     /**
@@ -6133,10 +6170,17 @@ type CreateBulkOrganizationInvitationParams = {
     role: OrganizationCustomRoleKey;
 };
 /**
- * @inline
+ * Parameters for the `createOrganization()` method.
+ * @interface
  */
 interface CreateOrganizationParams {
+    /**
+     * The name of the organization.
+     */
     name: string;
+    /**
+     * The slug of the organization.
+     */
     slug?: string;
 }
 interface ClerkAuthenticateWithWeb3Params {
@@ -6201,12 +6245,22 @@ interface EnvironmentResource extends ClerkResource {
     __internal_toSnapshot: () => EnvironmentJSONSnapshot;
 }
 
+/**
+ * @inline
+ */
 type CheckAuthorizationSignedOut = undefined;
+/**
+ * @inline
+ */
 type CheckAuthorizationWithoutOrgOrUser = (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => false;
 /**
  * @inline
  */
-type UseAuthReturn = {
+type UseAuthReturn = 
+/**
+ * During initialization
+ */
+{
     /**
      * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
      */
@@ -6255,7 +6309,11 @@ type UseAuthReturn = {
      * A function that retrieves the current user's session token or a custom JWT template. Returns a promise that resolves to the token. See the [reference doc](https://clerk.com/docs/references/javascript/session#get-token).
      */
     getToken: GetToken;
-} | {
+}
+/**
+ * When signed out
+ */
+ | {
     isLoaded: true;
     isSignedIn: false;
     userId: null;
@@ -6268,7 +6326,11 @@ type UseAuthReturn = {
     has: CheckAuthorizationWithoutOrgOrUser;
     signOut: SignOut;
     getToken: GetToken;
-} | {
+}
+/**
+ * When signed in (no active organization)
+ */
+ | {
     isLoaded: true;
     isSignedIn: true;
     userId: string;
@@ -6281,7 +6343,11 @@ type UseAuthReturn = {
     has: CheckAuthorizationWithCustomPermissions;
     signOut: SignOut;
     getToken: GetToken;
-} | {
+}
+/**
+ * When signed in (with active organization)
+ */
+ | {
     isLoaded: true;
     isSignedIn: true;
     userId: string;
@@ -6396,7 +6462,7 @@ type UseUserReturn = {
      */
     isSignedIn: undefined;
     /**
-     * The [`User`](https://clerk.com/docs/references/javascript/user) object for the current user. If the user isn't signed in, `user` will be `null`.
+     * The `User` object for the current user. If the user isn't signed in, `user` will be `null`.
      */
     user: undefined;
 } | {

package/dist/index.d.ts

@@ -461,7 +461,13 @@ interface OrganizationDomainVerification {
     attempts: number;
     expiresAt: Date;
 }
+/**
+ * @inline
+ */
 type OrganizationDomainVerificationStatus = 'unverified' | 'verified';
+/**
+ * @inline
+ */
 type OrganizationEnrollmentMode = 'manual_invitation' | 'automatic_invitation' | 'automatic_suggestion';
 interface OrganizationDomainResource extends ClerkResource {
     id: string;
@@ -513,6 +519,9 @@ interface OrganizationInvitationResource extends ClerkResource {
     updatedAt: Date;
     revoke: () => Promise<OrganizationInvitationResource>;
 }
+/**
+ * @inline
+ */
 type OrganizationInvitationStatus = 'pending' | 'accepted' | 'revoked';
 
 type SnakeToCamel<T> = T extends `${infer A}_${infer B}` ? `${Uncapitalize<A>}${Capitalize<SnakeToCamel<B>>}` : T extends object ? {
@@ -527,6 +536,9 @@ type DeepCamelToSnake<T> = T extends `${infer C0}${infer R}` ? `${C0 extends Upp
 type CamelToSnake<T> = T extends `${infer C0}${infer R}` ? `${C0 extends Uppercase<C0> ? '_' : ''}${Lowercase<C0>}${CamelToSnake<R>}` : T extends object ? {
     [K in keyof T as CamelToSnake<Extract<K, string>>]: T[K];
 } : T;
+/**
+ * @internal
+ */
 type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
 };
@@ -981,6 +993,9 @@ interface ImageResource extends ClerkResource {
     publicUrl: string | null;
 }
 
+/**
+ * @inline
+ */
 type OrganizationSuggestionStatus = 'pending' | 'accepted';
 interface OrganizationSuggestionResource extends ClerkResource {
     id: string;
@@ -1149,6 +1164,15 @@ declare global {
         [k: string]: unknown;
     }
 }
+/**
+ * The `User` object holds all of the information for a single user of your application and provides a set of methods to manage their account. Each `User` has at least one authentication [identifier](https://clerk.com/docs/authentication/configuration/sign-up-sign-in-options#identifiers), which might be their email address, phone number, or a username.
+ *
+ * A user can be contacted at their primary email address or primary phone number. They can have more than one registered email address, but only one of them will be their primary email address. This goes for phone numbers as well; a user can have more than one, but only one phone number will be their primary. At the same time, a user can also have one or more external accounts by connecting to [social providers](https://clerk.com/docs/authentication/social-connections/oauth) such as Google, Apple, Facebook, and many more.
+ *
+ * Finally, a `User` object holds profile data like the user's name, profile picture, and a set of [metadata](/docs/users/metadata) that can be used internally to store arbitrary information. The metadata are split into `publicMetadata` and `privateMetadata`. Both types are set from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}, but public metadata can also be accessed from the [Frontend API](https://clerk.com/docs/reference/frontend-api){{ target: '_blank' }}.
+ *
+ * The ClerkJS SDK provides some helper [methods](#methods) on the `User` object to help retrieve and update user information and authentication status.
+ */
 interface UserResource extends ClerkResource {
     id: string;
     externalId: string | null;
@@ -1253,6 +1277,9 @@ type GetUserOrganizationSuggestionsParams = ClerkPaginationParams<{
 type GetUserOrganizationMembershipParams = ClerkPaginationParams;
 type GetOrganizationMemberships = (params?: GetUserOrganizationMembershipParams) => Promise<ClerkPaginatedResponse<OrganizationMembershipResource>>;
 
+/**
+ * @inline
+ */
 type PendingSessionOptions = {
     /**
      * Determines if pending sessions are considered as signed-out state.
@@ -1261,7 +1288,9 @@ type PendingSessionOptions = {
     treatPendingAsSignedOut?: boolean;
 };
 type DisallowSystemPermissions<P extends string> = P extends `${OrganizationSystemPermissionPrefix}${string}` ? 'System permissions are not included in session claims and cannot be used on the server-side' : P;
+/** @inline */
 type CheckAuthorizationFn<Params> = (isAuthorizedParams: Params) => boolean;
+/** @inline */
 type CheckAuthorizationWithCustomPermissions = CheckAuthorizationFn<CheckAuthorizationParamsWithCustomPermissions>;
 type WithReverification<T> = T & {
     reverification?: ReverificationConfig;
@@ -1421,6 +1450,9 @@ type GetTokenOptions = {
     leewayInSeconds?: number;
     skipCache?: boolean;
 };
+/**
+ * @inline
+ */
 type GetToken = (options?: GetTokenOptions) => Promise<string | null>;
 type SessionVerifyCreateParams = {
     level: SessionVerificationLevel;
@@ -1596,7 +1628,11 @@ interface OrganizationMembershipResource extends ClerkResource {
 }
 type OrganizationCustomPermissionKey = ClerkAuthorization extends Placeholder ? ClerkAuthorization['permission'] extends string ? ClerkAuthorization['permission'] : Base['permission'] : Base['permission'];
 /**
- * OrganizationCustomRoleKey will be string unless the developer has provided their own types through `ClerkAuthorization`
+ * `OrganizationCustomRoleKey` is a type that represents the user's role in an organization. It will be string unless the developer has provided their own types through [`ClerkAuthorization`](https://clerk.com/docs/guides/custom-types#example-custom-roles-and-permissions).
+ *
+ * Clerk provides the [default roles](https://clerk.com/docs/organizations/roles-permissions#default-roles) `org:admin` and `org:member`. However, you can create [custom roles](https://clerk.com/docs/organizations/create-roles-permissions) as well.
+ *
+ * @interface
  */
 type OrganizationCustomRoleKey = ClerkAuthorization extends Placeholder ? ClerkAuthorization['role'] extends string ? ClerkAuthorization['role'] : Base['role'] : Base['role'];
 type OrganizationSystemPermissionPrefix = 'org:sys_';
@@ -2058,6 +2094,7 @@ type SignInForceRedirectUrl = {
 
 /**
  * The `SignIn` object holds the state of the current sign-in and provides helper methods to navigate and complete the sign-in process. It is used to manage the sign-in lifecycle, including the first and second factor verification, and the creation of a new session.
+ * @interface
  */
 interface SignInResource extends ClerkResource {
     /**
@@ -6133,10 +6170,17 @@ type CreateBulkOrganizationInvitationParams = {
     role: OrganizationCustomRoleKey;
 };
 /**
- * @inline
+ * Parameters for the `createOrganization()` method.
+ * @interface
  */
 interface CreateOrganizationParams {
+    /**
+     * The name of the organization.
+     */
     name: string;
+    /**
+     * The slug of the organization.
+     */
     slug?: string;
 }
 interface ClerkAuthenticateWithWeb3Params {
@@ -6201,12 +6245,22 @@ interface EnvironmentResource extends ClerkResource {
     __internal_toSnapshot: () => EnvironmentJSONSnapshot;
 }
 
+/**
+ * @inline
+ */
 type CheckAuthorizationSignedOut = undefined;
+/**
+ * @inline
+ */
 type CheckAuthorizationWithoutOrgOrUser = (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => false;
 /**
  * @inline
  */
-type UseAuthReturn = {
+type UseAuthReturn = 
+/**
+ * During initialization
+ */
+{
     /**
      * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
      */
@@ -6255,7 +6309,11 @@ type UseAuthReturn = {
      * A function that retrieves the current user's session token or a custom JWT template. Returns a promise that resolves to the token. See the [reference doc](https://clerk.com/docs/references/javascript/session#get-token).
      */
     getToken: GetToken;
-} | {
+}
+/**
+ * When signed out
+ */
+ | {
     isLoaded: true;
     isSignedIn: false;
     userId: null;
@@ -6268,7 +6326,11 @@ type UseAuthReturn = {
     has: CheckAuthorizationWithoutOrgOrUser;
     signOut: SignOut;
     getToken: GetToken;
-} | {
+}
+/**
+ * When signed in (no active organization)
+ */
+ | {
     isLoaded: true;
     isSignedIn: true;
     userId: string;
@@ -6281,7 +6343,11 @@ type UseAuthReturn = {
     has: CheckAuthorizationWithCustomPermissions;
     signOut: SignOut;
     getToken: GetToken;
-} | {
+}
+/**
+ * When signed in (with active organization)
+ */
+ | {
     isLoaded: true;
     isSignedIn: true;
     userId: string;
@@ -6396,7 +6462,7 @@ type UseUserReturn = {
      */
     isSignedIn: undefined;
     /**
-     * The [`User`](https://clerk.com/docs/references/javascript/user) object for the current user. If the user isn't signed in, `user` will be `null`.
+     * The `User` object for the current user. If the user isn't signed in, `user` will be `null`.
      */
     user: undefined;
 } | {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clerk/types",
-  "version": "4.53.0",
+  "version": "4.53.1-canary.v20250411131008",
   "description": "Typings for Clerk libraries.",
   "keywords": [
     "clerk",