Merge pull request #151 from kinde-oss/docs/add-jsdoc

Author: DanielRivers

lib/utils/isCustomDomain.ts

@@ -1,3 +1,37 @@
+/**
+ * Checks if a domain is a custom domain (not a Kinde.com domain).
+ *
+ * This function determines whether the provided domain is a custom domain
+ * by checking if it matches the pattern for Kinde.com domains. A domain
+ * is considered custom if it does NOT match the Kinde.com pattern.
+ *
+ * The function accepts domains with or without protocol (http/https) and
+ * checks against the pattern: `*.kinde.com` (case insensitive).
+ *
+ * @param domain - The domain string to check (can include protocol)
+ * @returns True if the domain is a custom domain, false if it's a Kinde.com domain
+ *
+ * @example
+ * ```typescript
+ * isCustomDomain("https://app.kinde.com")
+ * // Returns: false
+ *
+ * isCustomDomain("app.kinde.com")
+ * // Returns: false
+ *
+ * isCustomDomain("https://myapp.com")
+ * // Returns: true
+ *
+ * isCustomDomain("myapp.com")
+ * // Returns: true
+ *
+ * isCustomDomain("https://auth.mycompany.com")
+ * // Returns: true
+ *
+ * isCustomDomain("https://subdomain.kinde.com")
+ * // Returns: false
+ * ```
+ */
 export const isCustomDomain = (domain: string): boolean => {
   return !domain.match(
     /^(?:https?:\/\/)?[a-zA-Z0-9][.-a-zA-Z0-9]*\.kinde\.com$/i,

lib/utils/navigateToKinde.ts

@@ -1,21 +1,73 @@
+/**
+ * Configuration options for popup window dimensions and position.
+ */
 export type PopupOptions = {
+  /** Width of the popup window in pixels (default: 500) */
   width?: number;
+  /** Height of the popup window in pixels (default: 600) */
   height?: number;
+  /** Left position of the popup window in pixels (default: centered) */
   left?: number;
+  /** Top position of the popup window in pixels (default: centered) */
   top?: number;
 };
 
+/**
+ * Checks if the current window is running inside a popup.
+ *
+ * @returns True if the current window is a popup (self !== top), false otherwise
+ */
 export const openInPopup = (): boolean => {
   return window.self !== window.top;
 };
 
+/**
+ * Configuration options for navigating to Kinde authentication.
+ */
 export type NavigateToKindeOptions = {
+  /** The URL to navigate to for authentication */
   url: string;
+  /** Optional popup window configuration */
   popupOptions?: PopupOptions;
+  /** Optional callback to handle authentication results */
   handleResult?: (result: URLSearchParams) => Promise<void>;
+  /** Force popup window (default: false) */
   forcePopup?: boolean;
 };
 
+/**
+ * Navigates to Kinde authentication URL, either in a popup or by redirecting the current page.
+ *
+ * This function determines whether to open the authentication URL in a popup window
+ * or redirect the current page based on the current context and options provided.
+ * If the current window is in an iFrame a popup or forcePopup is true, it will create
+ * a new popup window. Otherwise, it redirects the current page.
+ *
+ * @param options - Configuration options for the navigation
+ * @returns A promise that resolves when navigation is complete
+ *
+ * @example
+ * ```typescript
+ * // Navigate to authentication in popup
+ * await navigateToKinde({
+ *   url: "https://app.kinde.com/oauth/authorize?client_id=...",
+ *   popupOptions: { width: 600, height: 700 },
+ *   handleResult: async (result) => {
+ *     console.log("Auth result:", result);
+ *     // Handle authentication result
+ *   },
+ *   forcePopup: true
+ * });
+ *
+ * // Navigate by redirecting current page
+ * await navigateToKinde({
+ *   url: "https://app.kinde.com/oauth/authorize?client_id=...",
+ *   handleResult: async (result) => {
+ *     // This will only be called if in popup mode on completion
+ *   }
+ * });
+ * ```
+ */
 export const navigateToKinde = async ({
   url,
   popupOptions = {},
@@ -33,6 +85,34 @@ export const navigateToKinde = async ({
   }
 };
 
+/**
+ * Creates a popup window for Kinde authentication and waits for the result.
+ *
+ * This function opens a popup window with the specified URL and waits for
+ * a message from the popup containing authentication results. The popup
+ * window is configured with the provided options and positioned on screen.
+ *
+ * @param options - Configuration options for the popup
+ * @returns A promise that resolves with the popup window reference, or null if blocked
+ * @throws {Error} When the popup is blocked by the browser
+ * @throws {Error} When authentication fails
+ *
+ * @example
+ * ```typescript
+ * const popup = await createPopup({
+ *   url: "https://app.kinde.com/oauth/authorize?client_id=...",
+ *   popupOptions: {
+ *     width: 600,
+ *     height: 700,
+ *     left: 100,
+ *     top: 100
+ *   },
+ *   handleResult: async (result) => {
+ *     console.log("Authentication completed:", result);
+ *   }
+ * });
+ * ```
+ */
 export const createPopup = async ({
   url,
   popupOptions = {},
@@ -82,6 +162,25 @@ export const createPopup = async ({
   return popup;
 };
 
+/**
+ * Waits for a popup window to close by polling its closed state.
+ *
+ * This function creates a promise that resolves when the specified popup window
+ * is closed. It polls the popup's closed property every 100ms until the window
+ * is no longer open.
+ *
+ * @param popup - The popup window to monitor
+ * @returns A promise that resolves when the popup is closed
+ *
+ * @example
+ * ```typescript
+ * const popup = await createPopup({ url: "https://example.com" });
+ *
+ * // Wait for popup to close
+ * await waitForPopupClose(popup);
+ * console.log("Popup has been closed");
+ * ```
+ */
 export const waitForPopupClose = (popup: Window): Promise<void> => {
   return new Promise((resolve) => {
     const checkClosed = () => {

lib/utils/refreshTimer.ts

@@ -1,5 +1,40 @@
+/**
+ * Global timer reference for managing refresh timers.
+ * Used to store the timeout ID for the current refresh timer.
+ */
 let refreshTimer: number | undefined;
 
+/**
+ * Sets a refresh timer with automatic cleanup and safety constraints.
+ *
+ * This function creates a new timer that will execute the provided callback function.
+ * It automatically clears any existing timer before setting a new one to prevent
+ * multiple timers from running simultaneously. The timer duration is constrained
+ * to prevent extremely long or short timers.
+ *
+ * The timer duration is automatically adjusted to be at least 10 seconds less than
+ * the requested duration and capped at 24 hours (86400000ms) for safety.
+ *
+ * @param timer - The timer duration in seconds
+ * @param callback - The function to execute when the timer expires
+ * @throws {Error} When called outside of a browser environment
+ * @throws {Error} When timer duration is not positive
+ *
+ * @example
+ * ```typescript
+ * // Set a timer for 60 seconds
+ * setRefreshTimer(60, () => {
+ *   console.log("Timer expired!");
+ *   // Perform refresh logic here
+ * });
+ *
+ * // Set a timer for 1 hour (3600 seconds)
+ * setRefreshTimer(3600, () => {
+ *   // Refresh authentication token
+ *   refreshAuthToken();
+ * });
+ * ```
+ */
 export function setRefreshTimer(timer: number, callback: () => void) {
   clearRefreshTimer();
   if (typeof window === "undefined") {
@@ -14,6 +49,24 @@ export function setRefreshTimer(timer: number, callback: () => void) {
   );
 }
 
+/**
+ * Clears the current refresh timer if one exists.
+ *
+ * This function safely clears any active refresh timer and resets the timer reference.
+ * It's safe to call even if no timer is currently active.
+ *
+ * @example
+ * ```typescript
+ * // Clear any existing timer
+ * clearRefreshTimer();
+ *
+ * // Set a new timer
+ * setRefreshTimer(300, handleRefresh);
+ *
+ * // Later, clear it before it expires
+ * clearRefreshTimer();
+ * ```
+ */
 export function clearRefreshTimer() {
   if (refreshTimer !== undefined) {
     window.clearTimeout(refreshTimer);

lib/utils/sanitizeUrl.ts

@@ -1,4 +1,28 @@
-//function to remove trailing slash
+/**
+ * Removes trailing slashes from a URL string.
+ *
+ * This function uses a regular expression to remove any trailing forward slash
+ * from the end of a URL string. It only removes the slash if it's at the very
+ * end of the string, preserving any other slashes within the URL.
+ *
+ * @param url - The URL string to sanitize
+ * @returns The URL string with trailing slash removed, or the original string if no trailing slash exists
+ *
+ * @example
+ * ```typescript
+ * sanitizeUrl("https://example.com/")
+ * // Returns: "https://example.com"
+ *
+ * sanitizeUrl("https://example.com/api/v1/")
+ * // Returns: "https://example.com/api/v1"
+ *
+ * sanitizeUrl("https://example.com")
+ * // Returns: "https://example.com" (no change)
+ *
+ * sanitizeUrl("https://example.com/path/to/resource/")
+ * // Returns: "https://example.com/path/to/resource"
+ * ```
+ */
 export const sanitizeUrl = (url: string): string => {
   return url.replace(/\/$/, "");
 };

lib/utils/snakeToCamelCase.ts

@@ -1,3 +1,62 @@
+/**
+ * Recursively converts object keys from snake_case to camelCase.
+ *
+ * This function traverses an object (including nested objects and arrays) and converts
+ * all property names from snake_case format to camelCase format. The function handles
+ * nested objects, arrays, and primitive values appropriately.
+ *
+ * @template T - The expected return type (defaults to unknown)
+ * @param obj - The object whose keys should be converted from snake_case to camelCase
+ * @returns A new object with all keys converted to camelCase format
+ *
+ * @example
+ * ```typescript
+ * const input = {
+ *   user_name: "John",
+ *   user_details: {
+ *     first_name: "John",
+ *     last_name: "Doe",
+ *     contact_info: {
+ *       email_address: "john@example.com",
+ *       phone_number: "123-456-7890"
+ *     }
+ *   },
+ *   active_status: true
+ * };
+ *
+ * const result = snakeToCamelCase(input);
+ * // Returns:
+ * // {
+ * //   userName: "John",
+ * //   userDetails: {
+ * //     firstName: "John",
+ * //     lastName: "Doe",
+ * //     contactInfo: {
+ * //       emailAddress: "john@example.com",
+ * //       phoneNumber: "123-456-7890"
+ * //     }
+ * //   },
+ * //   activeStatus: true
+ * // }
+ *
+ * // With arrays
+ * const arrayInput = {
+ *   user_list: [
+ *     { first_name: "John", last_name: "Doe" },
+ *     { first_name: "Jane", last_name: "Smith" }
+ *   ]
+ * };
+ *
+ * const arrayResult = snakeToCamelCase(arrayInput);
+ * // Returns:
+ * // {
+ * //   userList: [
+ * //     { firstName: "John", lastName: "Doe" },
+ * //     { firstName: "Jane", lastName: "Smith" }
+ * //   ]
+ * // }
+ * ```
+ */
 export const snakeToCamelCase = <T = unknown>(obj: object): T => {
   if (typeof obj !== "object" || obj === null) return obj;
 

lib/utils/splitString.ts

@@ -1,3 +1,26 @@
+/**
+ * Splits a string into an array of substrings, each with a maximum specified length.
+ *
+ * This function uses a regular expression to split the input string into chunks,
+ * where each chunk has a maximum length specified by the `length` parameter.
+ * If the length is less than or equal to 0, an empty array is returned.
+ *
+ * @param str - The string to be split into chunks
+ * @param length - The maximum length of each chunk. Must be greater than 0
+ * @returns An array of strings, where each string has a maximum length of `length`
+ *
+ * @example
+ * ```typescript
+ * splitString("Hello World", 3)
+ * // Returns: ["Hel", "lo ", "Wor", "ld"]
+ *
+ * splitString("JavaScript", 5)
+ * // Returns: ["JavaS", "cript"]
+ *
+ * splitString("Test", 0)
+ * // Returns: []
+ * ```
+ */
 export function splitString(str: string, length: number): string[] {
   if (length <= 0) {
     return [];