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

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();