PRD-1608 - JSDoc - Features/Clerk

src/lib/src/features/clerk/enums/api-error.ts

@@ -1,5 +1,11 @@
+/**
+ * Enum containing common Clerk API error codes
+ */
 export enum ClerkApiError {
+  /** Error when a session already exists */
   SESSION_EXISTS = 'session_exists',
+  /** Error when an identifier (email/phone) already exists */
   FORM_IDENTIFIER_EXIST = 'form_identifier_exists',
+  /** Error when the verification code is incorrect */
   FORM_CODE_INCORRECT = 'form_code_incorrect',
 };

src/lib/src/features/clerk/hooks/index.ts

@@ -1,6 +1,8 @@
 export * from './use-clerk-resources';
-export * from './use-get-token';
+export * from './use-get-session-token';
 export * from './use-auth-with-sso';
 export * from './use-auth-with-ticket';
 export * from './use-otp-verification';
 export * from './use-auth-with-identifier';
+export * from './use-add-identifier';
+export * from './use-reset-password';

src/lib/src/features/clerk/hooks/use-add-identifier.ts

@@ -4,6 +4,15 @@ import { useState } from 'react';
 import { UseAddIdentifierReturn } from '../types';
 import { ClerkApiError } from '../enums';
 
+/**
+ * Hook that provides functionality to add new email or phone number identifiers to a user's account and verify them using verification codes.
+ * 
+ * @returns {UseAddIdentifierReturn} Object containing:
+ * - `createIdentifier` - A function to add a new email or phone number identifier to the user's account and prepare it for verification
+ * - `verifyCode` - A function to verify a code sent to the identifier, completing the verification process
+ * - `isCreating` - A boolean indicating whether an identifier is currently being added
+ * - `isVerifying` - A boolean indicating whether a verification code is currently being processed
+ */
 export function useAddIdentifier(): UseAddIdentifierReturn {
   const { user } = useUser();
   const [identifierResource, setIdentifierResource] = useState<PhoneNumberResource | EmailAddressResource>();

src/lib/src/features/clerk/hooks/use-auth-with-identifier.ts

@@ -10,10 +10,26 @@ import {
   UseAuthWithIdentifierReturn,
 } from '../types';
 import { useClerkResources } from './use-clerk-resources';
-import { useGetSessionToken } from './use-get-token';
+import { useGetSessionToken } from './use-get-session-token';
 import { useOtpVerification } from './use-otp-verification';
 import { SignInResource } from '@clerk/types';
 
+/**
+ * Hook that provides functionality to handle user sign-up and sign-in processes using an identifier such as an email, phone number, or username. It supports both OTP (One Time Password) and password-based authentication methods.
+ * 
+ * @template {AuthIdentifierVerifyBy} TVerifyBy - The verification method type
+ * @template {IdentifierMethodFor<TVerifyBy>} TMethod - The identifier method type
+ * @param {TMethod} method - Specifies the type of identifier used for authentication (e.g., 'emailAddress', 'phoneNumber', 'username')
+ * @param {TVerifyBy} verifyBy - Specifies the verification method ('otp' for one-time passwords or 'password')
+ * 
+ * @returns {UseAuthWithIdentifierReturn<TVerifyBy, TMethod>} Object containing:
+ * - `startSignUp` - Initiates a new user registration using the specified identifier and verification method
+ * - `startSignIn` - Initiates authentication of an existing user using the specified identifier and verification method
+ * - `startAuthorization` - Determines whether to initiate a sign-up or sign-in based on whether the user has been registered previously
+ * - `verifyCode` - Verifies an OTP code if the verification method is 'otp' (only available for non-username methods)
+ * - `isLoading` - Indicates whether an authentication request is in progress
+ * - `isVerifying` - Indicates whether an OTP verification is in progress (only available for non-username methods)
+ */
 export function useAuthWithIdentifier<
   TVerifyBy extends AuthIdentifierVerifyBy,
   TMethod extends IdentifierMethodFor<TVerifyBy>,

src/lib/src/features/clerk/hooks/use-auth-with-sso.ts

@@ -1,8 +1,15 @@
 import { useSSO } from '@clerk/clerk-expo';
 import { useState } from 'react';
 import { StartSSOArgs, UseAuthWithSSOReturn } from '../types';
-import { useGetSessionToken } from './use-get-token';
-
+import { useGetSessionToken } from './use-get-session-token';
+
+/**
+ * Hook that provides functionality to handle SSO authentication flows.
+ * 
+ * @returns {UseAuthWithSSOReturn} Object containing:
+ * - `startSSOFlow` - A function to initiate an SSO flow. It takes a strategy, redirectUrl, and optional tokenTemplate as parameters, starting the SSO authentication and returning session information or errors upon completion
+ * - `isLoading` - A boolean indicating whether an SSO process is currently ongoing
+ */
 export function useAuthWithSSO(): UseAuthWithSSOReturn {
   const { startSSOFlow: clerkStartSSOFlow } = useSSO();
   const { getSessionToken } = useGetSessionToken();

src/lib/src/features/clerk/hooks/use-auth-with-ticket.ts

@@ -1,8 +1,15 @@
 import { useState } from 'react';
 import { UseAuthWithTicketReturn } from '../types';
 import { useClerkResources } from './use-clerk-resources';
-import { useGetSessionToken } from './use-get-token';
+import { useGetSessionToken } from './use-get-session-token';
 
+/**
+ * Hook that facilitates user authentication using a ticket-based strategy (ticket is a token generated from the Backend API).
+ * 
+ * @returns {UseAuthWithTicketReturn} Object containing:
+ * - `startAuthorization` - A function to initiate authentication with a ticket. It accepts an object with ticket and optional tokenTemplate parameters to kick off the authorization process and returns the session details
+ * - `isLoading` - A boolean indicating whether the ticket-based authorization process is ongoing
+ */
 export function useAuthWithTicket(): UseAuthWithTicketReturn {
   const { signIn, setActive } = useClerkResources();
   const { getSessionToken } = useGetSessionToken();

src/lib/src/features/clerk/hooks/use-clerk-resources.ts

@@ -1,6 +1,15 @@
 import { getClerkInstance } from '@clerk/clerk-expo';
 import { UseClerkResourcesReturn } from '../types';
 
+/**
+ * Hook that provides access to essential Clerk methods and objects.
+ * 
+ * @returns {UseClerkResourcesReturn} Object containing Clerk resources:
+ * - `signUp` - Provides access to SignUp object: https://clerk.com/docs/references/javascript/sign-up 
+ * - `signIn` - Provides access to SignIn object: https://clerk.com/docs/references/javascript/sign-in 
+ * - `setActive` - A function that sets the active session
+ * - `signOut` - A function that signs out the current user
+ */
 export const useClerkResources = (): UseClerkResourcesReturn => {
   const clerk = getClerkInstance();
   const signUp = clerk.client?.signUp;

src/lib/src/features/clerk/hooks/use-get-token.ts → src/lib/src/features/clerk/hooks/use-get-session-token.ts

@@ -1,6 +1,12 @@
 import { getClerkInstance } from '@clerk/clerk-expo';
 import { UseGetSessionTokenReturn } from '../types';
 
+/**
+ * Hook that provides functionality for getting session tokens.
+ * 
+ * @returns {UseGetSessionTokenReturn} Object containing:
+ * - `getSessionToken` - A function to retrieve the session token. It takes an optional tokenTemplate parameter to specify a template for the token
+ */
 export const useGetSessionToken = (): UseGetSessionTokenReturn => {
   const clerk = getClerkInstance();
 

src/lib/src/features/clerk/hooks/use-otp-verification.ts

@@ -1,10 +1,18 @@
 import { EmailCodeFactor, PhoneCodeFactor } from '@clerk/types';
 import { useState } from 'react';
 import { useClerkResources } from './use-clerk-resources';
-import { useGetSessionToken } from './use-get-token';
+import { useGetSessionToken } from './use-get-session-token';
 import { OtpStrategy, UseOtpVerificationReturn } from '../types/types';
 
-export function useOtpVerification() {
+/**
+ * Hook that provides functionality for managing OTP (One Time Password) verification in user authentication workflows, supporting both sign-up and sign-in processes.
+ * 
+ * @returns {UseOtpVerificationReturn} Object containing:
+ * - `sendOtpCode` - Sends an OTP code to the user's identifier (email or phone number) based on the specified strategy
+ * - `verifyCode` - Verifies the OTP code provided by the user, completing the authentication process
+ * - `isVerifying` - A boolean indicating whether a verification attempt is currently in progress
+ */
+export function useOtpVerification(): UseOtpVerificationReturn {
   const { signUp, signIn, setActive } = useClerkResources();
   const { getSessionToken } = useGetSessionToken();
   const [isVerifying, setIsVerifying] = useState(false);

src/lib/src/features/clerk/hooks/use-reset-password.ts

@@ -1,8 +1,20 @@
 import { useState } from 'react';
 import { OtpMethod, UseResetPasswordReturn } from '../types';
 import { useClerkResources } from './use-clerk-resources';
-import { useGetSessionToken } from './use-get-token';
+import { useGetSessionToken } from './use-get-session-token';
 
+/**
+ * Hook that provides methods to handle password reset functionality through email or phone-based OTP.
+ * 
+ * @param {Object} params - Parameters for the hook
+ * @param {OtpMethod} params.method - The method to use for OTP (emailAddress or phoneNumber)
+ * 
+ * @returns {UseResetPasswordReturn} Object containing:
+ * - `startResetPassword` - A function to initiate the password reset process by sending a verification code to the user's email or phone number
+ * - `resetPassword` - A function to reset the user's password by verifying the code and setting a new password
+ * - `isCodeSending` - A boolean indicating if the verification code is being sent
+ * - `isResetting` - A boolean indicating if the password is being reset
+ */
 export function useResetPassword({ method }: { method: OtpMethod }): UseResetPasswordReturn {
   const strategy = method === 'emailAddress' ? 'reset_password_email_code' : 'reset_password_phone_code';
   const { signIn, setActive } = useClerkResources();

src/lib/src/features/clerk/index.ts

@@ -1,3 +1,3 @@
 export * from './enums';
 export * from './types';
-export * from './hooks';
+export * from './hooks';