[ci] Update Typedoc (74dd3b8)

.github/workflows/typedoc.yml

@@ -11,10 +11,6 @@ jobs:
 
     runs-on: ubuntu-latest
     steps:
-      - name: Get current date
-        id: current_date
-        run: echo "date=$(date +'%Y-%m-%d')" >> $GITHUB_ENV
-
       - name: Checkout current repository
         uses: actions/checkout@v4
         with:
@@ -30,6 +26,11 @@ jobs:
           fetch-depth: 1
           show-progress: false
 
+      - name: Get clerk/javascript commit SHA
+        id: clerk_sha
+        working-directory: ./clerk-javascript
+        run: echo "sha=$(git rev-parse --short HEAD)" >> $GITHUB_ENV
+
       - name: Install pnpm
         uses: pnpm/action-setup@v4
         with:
@@ -52,24 +53,63 @@ jobs:
       - name: Copy docs to main repo
         run: |
           # Copy the generated docs to the root of the main repo
-          cp -r ./clerk-javascript/.typedoc/docs ./clerk-docs/clerk-typedoc
+          cp -r ./clerk-javascript/.typedoc/docs/* ./clerk-docs/clerk-typedoc
 
       - name: Configure Git
         working-directory: ./clerk-docs
         run: |
           git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git config --global user.name "github-actions[bot]"
 
-      - name: Commit and push changes
+      - name: Check for changes and create PR
         working-directory: ./clerk-docs
         run: |
-          git checkout -b typedoc-${{ env.date }}
-          git add .
-          git commit -m "initial"
-          git push origin typedoc-${{ env.date }}
+          # 1. Check if there are any changes
+          if [ -z "$(git status --porcelain)" ]; then
+            echo "ℹ️  No changes detected in TypeDoc documentation, exiting early"
+            exit 0
+          fi
 
-      - name: Create Pull Request
-        working-directory: ./clerk-docs
-        run: gh pr create --base main --head typedoc-${{ env.date }} --title "[ci] Update Typedoc (${{ env.date }})" --body "Auto-generated PR to update Typedoc documentation from clerk/javascript"
+          echo "✅ Changes detected, processing..."
+
+          # 2. Check if branch already exists and handle accordingly
+          if git ls-remote --exit-code --heads origin typedoc-${{ env.sha }} > /dev/null 2>&1; then
+            echo "ℹ️  Branch typedoc-${{ env.sha }} already exists, checking it out and updating"
+            git stash push -u -m "Temporary stash for branch switch"
+            git fetch origin typedoc-${{ env.sha }}
+            git checkout typedoc-${{ env.sha }}
+
+            # Try to pop stash, but don't fail if it conflicts (files already exist)
+            if git stash pop; then
+              echo "✅ Successfully applied stashed changes"
+            else
+              echo "ℹ️  Stash pop failed (likely files already exist), dropping stash and checking for changes"
+              git stash drop
+            fi
+
+            # Check if there are any changes to commit after checkout/stash
+            if [ -z "$(git status --porcelain)" ]; then
+              echo "ℹ️  No new changes detected on existing branch, exiting successfully"
+              exit 0
+            fi
+
+            git add .
+            git commit -m "docs: update TypeDoc documentation from clerk/javascript@${{ env.sha }}"
+            git push origin typedoc-${{ env.sha }}
+          else
+            echo "✅ Creating new branch typedoc-${{ env.sha }}"
+            git checkout -b typedoc-${{ env.sha }}
+            git add .
+            git commit -m "docs: update TypeDoc documentation from clerk/javascript@${{ env.sha }}"
+            git push origin typedoc-${{ env.sha }}
+          fi
+
+          # 3. Check if PR already exists
+          if gh pr list --head typedoc-${{ env.sha }} --json number --jq length | grep -q "^0$"; then
+            echo "✅ Creating new PR for typedoc-${{ env.sha }}"
+            gh pr create --base main --head typedoc-${{ env.sha }} --title "[ci] Update Typedoc (${{ env.sha }})" --body "Auto-generated PR to update Typedoc documentation from clerk/javascript@${{ env.sha }}"
+          else
+            echo "ℹ️  PR already exists for typedoc-${{ env.sha }}, skipping PR creation"
+          fi
         env:
           GH_TOKEN: ${{ github.token }}

clerk-typedoc/backend/auth-object.mdx

@@ -1,8 +1,8 @@
 ## Properties
 
-| Property                           | Type                                                                                          | Description                                                                                                                                                                |
-| ---------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="debug"></a> `debug`         | <code>() => \{ [key: string]: any; \}</code>                                                  | Used to help debug issues when using Clerk in development.                                                                                                                 |
-| <a id="gettoken"></a> `getToken`   | <code>ServerGetToken \| () => Promise\<string\> \| () => Promise\<null\></code>               | A function that gets the current user's [session token](/docs/backend-requests/resources/session-tokens) or a [custom JWT template](/docs/backend-requests/jwt-templates). |
-| <a id="has"></a> `has`             | [`CheckAuthorizationFromSessionClaims`](../types/check-authorization-from-session-claims.mdx) | A function that checks if the user has an organization role or custom permission.                                                                                          |
-| <a id="tokentype"></a> `tokenType` | <code>"session_token" \| "api_key" \| "machine_token" \| "oauth_token"</code>                 | The allowed token type.                                                                                                                                                    |
+| Property                           | Type                                                                                                                                      | Description                                                                                                                                                                |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="debug"></a> `debug`         | <code>() => \{ [key: string]: any; \}</code>                                                                                              | Used to help debug issues when using Clerk in development.                                                                                                                 |
+| <a id="gettoken"></a> `getToken`   | <code>() => Promise\<null\> \| () => Promise\<string\> \| [ServerGetToken](../types/server-get-token.mdx) \| () => Promise\<null\></code> | A function that gets the current user's [session token](/docs/backend-requests/resources/session-tokens) or a [custom JWT template](/docs/backend-requests/jwt-templates). |
+| <a id="has"></a> `has`             | <code>[CheckAuthorizationFromSessionClaims](../types/check-authorization-from-session-claims.mdx) \| () => false</code>                   | A function that checks if the user has an organization role or custom permission.                                                                                          |
+| <a id="tokentype"></a> `tokenType` | <code>null \| "api_key" \| "session_token" \| "machine_token" \| "oauth_token"</code>                                                     | The allowed token type.                                                                                                                                                    |

clerk-typedoc/backend/get-auth-fn.mdx

@@ -0,0 +1,101 @@
+Shared generic overload type for getAuth() helpers across SDKs.
+
+- Parameterized by the request type (RequestType).
+- Handles different accepted token types and their corresponding return types.
+
+## Call Signature
+
+Shared generic overload type for getAuth() helpers across SDKs.
+
+- Parameterized by the request type (RequestType).
+- Handles different accepted token types and their corresponding return types.
+
+### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                               |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `req`     | `RequestType`                                                                                                                                                                                                                                                                      |
+| `options` | <code>\{ treatPendingAsSignedOut?: boolean; \}</code> & <code>\{ acceptsToken?: "api_key" \| "session_token" \| "machine_token" \| "oauth_token" \| ("api_key" \| "session_token" \| "machine_token" \| "oauth_token")[] \| "any"; \}</code> & <code>\{ acceptsToken: T; \}</code> |
+
+### Returns
+
+`MaybePromise`\<<code>InvalidTokenAuthObject \| [InferAuthObjectFromTokenArray](infer-auth-object-from-token-array.mdx)\<T, SessionAuthObject, MachineAuthObject\<Exclude\<T\[number\], "session_token"\>\>\></code>, `ReturnsPromise`\>
+
+### Example
+
+```ts
+const auth = await getAuth(req, { acceptsToken: ["session_token", "api_key"] });
+```
+
+## Call Signature
+
+Shared generic overload type for getAuth() helpers across SDKs.
+
+- Parameterized by the request type (RequestType).
+- Handles different accepted token types and their corresponding return types.
+
+### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                               |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `req`     | `RequestType`                                                                                                                                                                                                                                                                      |
+| `options` | <code>\{ treatPendingAsSignedOut?: boolean; \}</code> & <code>\{ acceptsToken?: "api_key" \| "session_token" \| "machine_token" \| "oauth_token" \| ("api_key" \| "session_token" \| "machine_token" \| "oauth_token")[] \| "any"; \}</code> & <code>\{ acceptsToken: T; \}</code> |
+
+### Returns
+
+`MaybePromise`\<[`InferAuthObjectFromToken`](infer-auth-object-from-token.mdx)\<`T`, `SessionAuthObject`, `MachineAuthObject`\<`Exclude`\<`T`, `"session_token"`\>\>\>, `ReturnsPromise`\>
+
+### Example
+
+```ts
+const auth = await getAuth(req, { acceptsToken: "session_token" });
+```
+
+## Call Signature
+
+Shared generic overload type for getAuth() helpers across SDKs.
+
+- Parameterized by the request type (RequestType).
+- Handles different accepted token types and their corresponding return types.
+
+### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                   |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `req`     | `RequestType`                                                                                                                                                                                                                                                                          |
+| `options` | <code>\{ treatPendingAsSignedOut?: boolean; \}</code> & <code>\{ acceptsToken?: "api_key" \| "session_token" \| "machine_token" \| "oauth_token" \| ("api_key" \| "session_token" \| "machine_token" \| "oauth_token")[] \| "any"; \}</code> & <code>\{ acceptsToken: "any"; \}</code> |
+
+### Returns
+
+`MaybePromise`\<[`AuthObject`](auth-object.mdx), `ReturnsPromise`\>
+
+### Example
+
+```ts
+const auth = await getAuth(req, { acceptsToken: "any" });
+```
+
+## Call Signature
+
+Shared generic overload type for getAuth() helpers across SDKs.
+
+- Parameterized by the request type (RequestType).
+- Handles different accepted token types and their corresponding return types.
+
+### Parameters
+
+| Parameter                          | Type                                                  | Description                                                                                                |
+| ---------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `req`                              | `RequestType`                                         | -                                                                                                          |
+| `options?`                         | <code>\{ treatPendingAsSignedOut?: boolean; \}</code> | -                                                                                                          |
+| `options.treatPendingAsSignedOut?` | `boolean`                                             | A boolean that indicates whether pending sessions are considered as signed out or not. Defaults to `true`. |
+
+### Returns
+
+`MaybePromise`\<`SessionAuthObject`, `ReturnsPromise`\>
+
+### Example
+
+```ts
+const auth = await getAuth(req);
+```

clerk-typedoc/backend/infer-auth-object-from-token-array.mdx

@@ -0,0 +1,5 @@
+Infers auth object type from an array of token types.
+
+- Session token only -> SessionType
+- Mixed tokens -> SessionType | MachineType
+- Machine tokens only -> MachineType

clerk-typedoc/backend/infer-auth-object-from-token.mdx

@@ -0,0 +1,2 @@
+Infers auth object type from a single token type.
+Returns SessionType for session tokens, or MachineType for machine tokens.

clerk-typedoc/backend/user.mdx

@@ -36,3 +36,67 @@ The Backend `User` object is similar to the `User` object as it holds informatio
 | <a id="updatedat"></a> `updatedAt`                                 | `number`                                                                                  | The date when the user was last updated.                                                                                                                                                             |
 | <a id="username"></a> `username`                                   | <code>null \| string</code>                                                               | The user's username.                                                                                                                                                                                 |
 | <a id="web3wallets"></a> `web3Wallets`                             | <code>[Web3Wallet](/docs/references/backend/types/backend-web3-wallet)[]</code>           | An array of all the `Web3Wallet` objects associated with the user. Includes the primary.                                                                                                             |
+
+## Accessors
+
+### fullName
+
+#### Get Signature
+
+```ts
+get fullName(): <code>null | string</code>
+```
+
+The full name of the user.
+
+##### Returns
+
+<code>null \| string</code>
+
+---
+
+### primaryEmailAddress
+
+#### Get Signature
+
+```ts
+get primaryEmailAddress(): <code>null | EmailAddress</code>
+```
+
+The primary email address of the user.
+
+##### Returns
+
+<code>null \| [EmailAddress](/docs/references/backend/types/backend-email-address)</code>
+
+---
+
+### primaryPhoneNumber
+
+#### Get Signature
+
+```ts
+get primaryPhoneNumber(): <code>null | PhoneNumber</code>
+```
+
+The primary phone number of the user.
+
+##### Returns
+
+<code>null \| [PhoneNumber](/docs/references/backend/types/backend-phone-number)</code>
+
+---
+
+### primaryWeb3Wallet
+
+#### Get Signature
+
+```ts
+get primaryWeb3Wallet(): <code>null | Web3Wallet</code>
+```
+
+The primary web3 wallet of the user.
+
+##### Returns
+
+<code>null \| [Web3Wallet](/docs/references/backend/types/backend-web3-wallet)</code>