From ad24540b290f2fa3d8f281671e61b969faee9357 Mon Sep 17 00:00:00 2001
From: LekoArts <lekoarts@gmail.com>
Date: Fri, 7 Feb 2025 14:06:09 +0100
Subject: [PATCH 1/2] initial

---
 package.json                               |   2 +-
 packages/shared/src/telemetry/throttler.ts |   2 +-
 packages/shared/typedoc.json               |   7 +
 packages/types/src/hooks.ts                | 156 +--------------------
 pnpm-lock.yaml                             |  15 +-
 typedoc.config.mjs                         |  17 ++-
 6 files changed, 37 insertions(+), 162 deletions(-)
 create mode 100644 packages/shared/typedoc.json

diff --git a/package.json b/package.json
index ad825d6b1ae..86dcee0f8de 100644
--- a/package.json
+++ b/package.json
@@ -128,7 +128,7 @@
     "turbo": "^2.0.14",
     "turbo-ignore": "^2.0.6",
     "typedoc": "0.27.6",
-    "typedoc-plugin-missing-exports": "3.1.0",
+    "typedoc-plugin-markdown": "4.4.1",
     "typescript": "catalog:repo",
     "typescript-eslint": "8.21.0",
     "uuid": "8.3.2",
diff --git a/packages/shared/src/telemetry/throttler.ts b/packages/shared/src/telemetry/throttler.ts
index fd3a698e755..d5898f88662 100644
--- a/packages/shared/src/telemetry/throttler.ts
+++ b/packages/shared/src/telemetry/throttler.ts
@@ -48,7 +48,7 @@ export class TelemetryEventThrottler {
   #generateKey(event: TelemetryEvent): string {
     const { sk: _sk, pk: _pk, payload, ...rest } = event;
 
-    const sanitizedEvent = {
+    const sanitizedEvent: Omit<TelemetryEvent, 'sk' | 'pk' | 'payload'> & TelemetryEvent['payload'] = {
       ...payload,
       ...rest,
     };
diff --git a/packages/shared/typedoc.json b/packages/shared/typedoc.json
new file mode 100644
index 00000000000..b893b67ec3b
--- /dev/null
+++ b/packages/shared/typedoc.json
@@ -0,0 +1,7 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["./src/index.ts", "./src/react/index.ts"],
+  "compilerOptions": {
+    "noImplicitAny": false
+  }
+}
diff --git a/packages/types/src/hooks.ts b/packages/types/src/hooks.ts
index 820f92f03dc..4a1a05c66ba 100644
--- a/packages/types/src/hooks.ts
+++ b/packages/types/src/hooks.ts
@@ -17,6 +17,7 @@ type CheckAuthorizationWithoutOrgOrUser = (params: Parameters<CheckAuthorization
 
 /**
  * Return values of the `useAuth()` hook
+ * @interface
  */
 export type UseAuthReturn =
   | {
@@ -63,137 +64,48 @@ export type UseAuthReturn =
       getToken: GetToken;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * A boolean that indicates whether a user is currently signed in.
-       */
       isSignedIn: false;
-      /**
-       * The ID of the current user.
-       */
       userId: null;
-      /**
-       * The ID for the current session.
-       */
       sessionId: null;
       actor: null;
-      /**
-       * The ID of the user's active organization.
-       */
       orgId: null;
-      /**
-       * The current user's role in their active organization.
-       */
       orgRole: null;
-      /**
-       * The URL-friendly identifier of the user's active organization.
-       */
       orgSlug: null;
-      /**
-       * A function that checks if the user has specific permissions or roles. See the [reference doc](https://clerk.com/docs/references/backend/types/auth-object#has).
-       */
       has: CheckAuthorizationWithoutOrgOrUser;
-      /**
-       * A function that signs out the current user. Returns a promise that resolves when complete. See the [reference doc](https://clerk.com/docs/references/javascript/clerk/clerk#sign-out).
-       */
       signOut: SignOut;
-      /**
-       * 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;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * A boolean that indicates whether a user is currently signed in.
-       */
       isSignedIn: true;
-      /**
-       * The ID of the current user.
-       */
       userId: string;
-      /**
-       * The ID for the current session.
-       */
       sessionId: string;
       actor: ActJWTClaim | null;
-      /**
-       * The ID of the user's active organization.
-       */
       orgId: null;
-      /**
-       * The current user's role in their active organization.
-       */
       orgRole: null;
-      /**
-       * The URL-friendly identifier of the user's active organization.
-       */
       orgSlug: null;
-      /**
-       * A function that checks if the user has specific permissions or roles. See the [reference doc](https://clerk.com/docs/references/backend/types/auth-object#has).
-       */
       has: CheckAuthorizationWithCustomPermissions;
-      /**
-       * A function that signs out the current user. Returns a promise that resolves when complete. See the [reference doc](https://clerk.com/docs/references/javascript/clerk/clerk#sign-out).
-       */
       signOut: SignOut;
-      /**
-       * 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;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * A boolean that indicates whether a user is currently signed in.
-       */
       isSignedIn: true;
-      /**
-       * The ID of the current user.
-       */
       userId: string;
-      /**
-       * The ID for the current session.
-       */
       sessionId: string;
       actor: ActJWTClaim | null;
-      /**
-       * The ID of the user's active organization.
-       */
       orgId: string;
-      /**
-       * The current user's role in their active organization.
-       */
       orgRole: OrganizationCustomRoleKey;
-      /**
-       * The URL-friendly identifier of the user's active organization.
-       */
       orgSlug: string | null;
-      /**
-       * A function that checks if the user has specific permissions or roles. See the [reference doc](https://clerk.com/docs/references/backend/types/auth-object#has).
-       */
       has: CheckAuthorizationWithCustomPermissions;
-      /**
-       * A function that signs out the current user. Returns a promise that resolves when complete. See the [reference doc](https://clerk.com/docs/references/javascript/clerk/clerk#sign-out).
-       */
       signOut: SignOut;
-      /**
-       * 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;
     };
 
 /**
  * Return values of the `useSignIn()` hook
+ * @interface
  */
 export type UseSignInReturn =
   | {
@@ -211,22 +123,14 @@ export type UseSignInReturn =
       setActive: undefined;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * An object that contains the current sign-in attempt status and methods to create a new sign-in attempt.
-       */
       signIn: SignInResource;
-      /**
-       * A function that sets the active session.
-       */
       setActive: SetActive;
     };
 
 /**
  * Return values of the `useSignUp()` hook
+ * @interface
  */
 export type UseSignUpReturn =
   | {
@@ -244,22 +148,14 @@ export type UseSignUpReturn =
       setActive: undefined;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * An object that contains the current sign-up attempt status and methods to create a new sign-up attempt.
-       */
       signUp: SignUpResource;
-      /**
-       * A function that sets the active session.
-       */
       setActive: SetActive;
     };
 
 /**
  * Return values of the `useSession()` hook
+ * @interface
  */
 export type UseSessionReturn =
   | {
@@ -277,36 +173,19 @@ export type UseSessionReturn =
       session: undefined;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * A boolean that indicates whether a user is currently signed in.
-       */
       isSignedIn: false;
-      /**
-       * Holds the current active session for the user.
-       */
       session: null;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * A boolean that indicates whether a user is currently signed in.
-       */
       isSignedIn: true;
-      /**
-       * Holds the current active session for the user.
-       */
       session: ActiveSessionResource;
     };
 
 /**
  * Return values of the `useSessionList()` hook
+ * @interface
  */
 export type UseSessionListReturn =
   | {
@@ -324,22 +203,14 @@ export type UseSessionListReturn =
       setActive: undefined;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * A list of sessions that have been registered on the client device.
-       */
       sessions: SessionResource[];
-      /**
-       * A function that sets the active session and/or organization.
-       */
       setActive: SetActive;
     };
 
 /**
  * Return values of the `useUser()` hook
+ * @interface
  */
 export type UseUserReturn =
   | {
@@ -358,26 +229,11 @@ export type UseUserReturn =
     }
   | {
       isLoaded: true;
-      /**
-       * A boolean that indicates whether a user is currently signed in.
-       */
       isSignedIn: false;
-      /**
-       * The `User` object for the current user. If the user isn't signed in, `user` will be `null`.
-       */
       user: null;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * A boolean that indicates whether a user is currently signed in.
-       */
       isSignedIn: true;
-      /**
-       * The `User` object for the current user. If the user isn't signed in, `user` will be `null`.
-       */
       user: UserResource;
     };
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 856f7ffc0c2..495de5d518b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -277,9 +277,9 @@ importers:
       typedoc:
         specifier: 0.27.6
         version: 0.27.6(typescript@5.6.3)
-      typedoc-plugin-missing-exports:
-        specifier: 3.1.0
-        version: 3.1.0(typedoc@0.27.6(typescript@5.6.3))
+      typedoc-plugin-markdown:
+        specifier: 4.4.1
+        version: 4.4.1(typedoc@0.27.6(typescript@5.6.3))
       typescript:
         specifier: catalog:repo
         version: 5.6.3
@@ -13912,10 +13912,11 @@ packages:
     resolution: {integrity: sha512-q7QNVDGTdl702bVFiI5eY4l/HkgCM6at9KhcFbgUAzezHFbOVy4+0O/lCjsABEQwbZPravVfBIiBVGo89yzHFg==}
     engines: {node: '>= 0.4'}
 
-  typedoc-plugin-missing-exports@3.1.0:
-    resolution: {integrity: sha512-Sogbaj+qDa21NjB3SlIw4JXSwmcl/WOjwiPNaVEcPhpNG/MiRTtpwV81cT7h1cbu9StpONFPbddYWR0KV/fTWA==}
+  typedoc-plugin-markdown@4.4.1:
+    resolution: {integrity: sha512-fx23nSCvewI9IR8lzIYtzDphETcgTDuxKcmHKGD4lo36oexC+B1k4NaCOY58Snqb4OlE8OXDAGVcQXYYuLRCNw==}
+    engines: {node: '>= 18'}
     peerDependencies:
-      typedoc: 0.26.x || 0.27.x
+      typedoc: 0.27.x
 
   typedoc@0.27.6:
     resolution: {integrity: sha512-oBFRoh2Px6jFx366db0lLlihcalq/JzyCVp7Vaq1yphL/tbgx2e+bkpkCgJPunaPvPwoTOXSwasfklWHm7GfAw==}
@@ -31905,7 +31906,7 @@ snapshots:
       typed-array-buffer: 1.0.3
       typed-array-byte-offset: 1.0.4
 
-  typedoc-plugin-missing-exports@3.1.0(typedoc@0.27.6(typescript@5.6.3)):
+  typedoc-plugin-markdown@4.4.1(typedoc@0.27.6(typescript@5.6.3)):
     dependencies:
       typedoc: 0.27.6(typescript@5.6.3)
 
diff --git a/typedoc.config.mjs b/typedoc.config.mjs
index 82d6f8871d0..0cd279d82d2 100644
--- a/typedoc.config.mjs
+++ b/typedoc.config.mjs
@@ -23,13 +23,20 @@ function getPackages() {
   return packages.filter(dir => !IGNORE_LIST.includes(dir)).map(dir => path.join('packages', dir));
 }
 
+/** @type {import("typedoc-plugin-markdown").PluginOptions} */
+const typedocPluginMarkdownOptions = {
+  hidePageHeader: true,
+  hideBreadcrumbs: true,
+  hidePageTitle: true,
+};
+
 /** @type {Partial<import("typedoc").TypeDocOptions>} */
 const config = {
   out: './.typedoc/docs',
   // TODO: Once we're happy with the output the JSON should be written to a non-gitignored location as we want to consume it in other places
   json: './.typedoc/output.json',
   entryPointStrategy: 'packages',
-  plugin: ['typedoc-plugin-missing-exports'],
+  plugin: ['typedoc-plugin-markdown'],
   packageOptions: {
     includeVersion: false,
     excludePrivate: true,
@@ -39,11 +46,15 @@ const config = {
     excludeInternal: true,
     excludeNotDocumented: true,
     gitRevision: 'main',
-    blockTags: [...OptionDefaults.blockTags, '@warning', '@note', '@important'],
+    blockTags: [...OptionDefaults.blockTags, '@warning', '@note', '@important', '@memberof'],
     modifierTags: [...OptionDefaults.modifierTags],
     exclude: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
+    readme: 'none',
+    disableGit: true,
+    disableSources: true,
   },
-  entryPoints: ['packages/nextjs', 'packages/react', 'packages/backend', 'packages/types'], // getPackages(),
+  entryPoints: ['packages/nextjs', 'packages/react', 'packages/shared', 'packages/types'], // getPackages(),
+  ...typedocPluginMarkdownOptions,
 };
 
 export default config;

From 65b1862681dd74f5c5e65889c16975824c0c287a Mon Sep 17 00:00:00 2001
From: LekoArts <lekoarts@gmail.com>
Date: Fri, 7 Feb 2025 14:07:50 +0100
Subject: [PATCH 2/2] add changeset

---
 .changeset/late-bags-hang.md | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 .changeset/late-bags-hang.md

diff --git a/.changeset/late-bags-hang.md b/.changeset/late-bags-hang.md
new file mode 100644
index 00000000000..46339d495be
--- /dev/null
+++ b/.changeset/late-bags-hang.md
@@ -0,0 +1,6 @@
+---
+'@clerk/shared': patch
+'@clerk/types': patch
+---
+
+Small JSDoc and type improvements