chore(clerk-js): Add JSDoc for auth services and cookies

Author: dimkl

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -13,8 +13,25 @@ import type { DevBrowser } from './devBrowser';
 import { createDevBrowser } from './devBrowser';
 import { SessionCookiePoller } from './SessionCookiePoller';
 
-// TODO: make AuthCookieService singleton since it handles updating cookies using a poller
+// TODO(@dimkl): make AuthCookieService singleton since it handles updating cookies using a poller
 // and we need to avoid updating them concurrently.
+/**
+ * The AuthCookieService class is a service responsible to handle
+ * all operations and helpers required in a standard browser context
+ * based on the cookies to remove the dependency between cookies
+ * and auth from the Clerk instance.
+ * This service is responsible to:
+ *   - refresh the session cookie using a poller
+ *   - refresh the session cookie on tab visibility change
+ *   - update the related cookies listening to the `token:update` event
+ *   - initialize auth related cookies for development instances (eg __client_uat, __clerk_db_jwt)
+ *   - cookie setup for production / development instances
+ * It also provides the following helpers:
+ *   - isSignedOut(): check if the current user is signed-out using cookies
+ *   - urlWithAuth(): decorates url with auth related info (eg dev browser jwt)
+ *   - handleUnauthenticatedDevBrowser(): resets dev browser in case of invalid dev browser
+ *   - setEnvironment(): update cookies (eg client_uat) related to environment
+ */
 export class AuthCookieService {
   private environment: EnvironmentResource | undefined;
   private poller: SessionCookiePoller | null = null;
@@ -40,6 +57,7 @@ export class AuthCookieService {
     });
   }
 
+  // TODO(@dimkl): Replace this method call with an event listener to decouple Clerk with setEnvironment
   public setEnvironment(environment: EnvironmentResource) {
     this.environment = environment;
     this.setClientUatCookieForDevelopmentInstances();

packages/clerk-js/src/core/auth/cookies/clientUat.ts

@@ -12,6 +12,12 @@ export type ClientUatCookieHandler = {
   get: () => number;
 };
 
+/**
+ * Create a long-lived JS cookie to store the client last updated_at timestamp
+ * for development instances (for production instance is set by FAPI).
+ * The cookie is used as hint from the Clerk Backend packages to identify
+ * if the user is authenticated or not.
+ */
 export const createClientUatCookie = (): ClientUatCookieHandler => {
   const clientUatCookie = createCookieHandler(CLIENT_UAT_COOKIE_NAME);
 

packages/clerk-js/src/core/auth/cookies/devBrowser.ts

@@ -10,6 +10,12 @@ export type DevBrowserCookieHandler = {
   remove: () => void;
 };
 
+/**
+ * Create a long-lived JS cookie to store the dev browser token
+ * ONLY for development instances.
+ * The cookie is used to authenticate FAPI requests and pass
+ * authentication from AP to the app.
+ */
 export const createDevBrowserCookie = (): DevBrowserCookieHandler => {
   const devBrowserCookie = createCookieHandler(DEV_BROWSER_JWT_KEY);
 

packages/clerk-js/src/core/auth/cookies/session.ts

@@ -10,12 +10,12 @@ export type SessionCookieHandler = {
   remove: () => void;
 };
 
+/**
+ * Create a short-lived JS cookie to store the current user JWT.
+ * The cookie is used by the Clerk backend SDKs to identify
+ * the authenticated user.
+ */
 export const createSessionCookie = (): SessionCookieHandler => {
-  /**
-   *
-   * This is a short-lived JS cookie used to store the current user JWT.
-   *
-   */
   const sessionCookie = createCookieHandler(SESSION_COOKIE_NAME);
 
   const remove = () => sessionCookie.remove();