fix(backend): JSDoc for verifyWebook & verifyToken#6060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
LekoArts merged 4 commits into from
Jun 4, 2025
Merged

fix(backend): JSDoc for verifyWebook & verifyToken#6060

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
789c65b
verifyToken & verifyWebhook
LekoArts Jun 4, 2025
15ae059
add changeset
LekoArts Jun 4, 2025
4e7f16f
update types
LekoArts Jun 4, 2025
d1b452a
update snapshot
LekoArts Jun 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/six-lions-wear.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/backend': patch
---

Improve JSDoc comments for verifyWebhook and verifyToken
1 change: 1 addition & 0 deletions .typedoc/__tests__/__snapshots__/file-structure.test.ts.snap
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -157,6 +157,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
"backend/organization-invitation.mdx",
"backend/organization-membership-public-user-data.mdx",
"backend/organization-membership.mdx",
"backend/organization-sync-options.mdx",
"backend/organization-sync-target.mdx",
"backend/organization.mdx",
"backend/paginated-resource-response.mdx",
Expand Down
1 change: 1 addition & 0 deletions .typedoc/custom-plugin.mjs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,7 @@ const LINK_REPLACEMENTS = [
['phone-number', '/docs/references/backend/types/backend-phone-number'],
['saml-account', '/docs/references/backend/types/backend-saml-account'],
['web3-wallet', '/docs/references/backend/types/backend-web3-wallet'],
['verify-token-options', '#verify-token-options'],
];

/**
Expand Down
172 changes: 168 additions & 4 deletions .typedoc/custom-theme.mjs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
// @ts-check
import { ReflectionType, UnionType } from 'typedoc';
import { ReflectionKind, ReflectionType, UnionType } from 'typedoc';
import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';

/**
Expand DownExpand Up@@ -47,22 +47,111 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
this.partials = {
...superPartials,
/**
* This hides the "Type parameters" section and the signature title from the output
* This hides the "Type parameters" section and the signature title from the output (by default). Shows the signature title if the `@displayFunctionSignature` tag is present.
* @param {import('typedoc').SignatureReflection} model
* @param {{ headingLevel: number, nested?: boolean, accessor?: string, multipleSignatures?: boolean; hideTitle?: boolean }} options
*/
signature: (model, options) => {
const displayFunctionSignatureTag = model.comment?.getTag('@displayFunctionSignature');
const paramExtensionTag = model.comment?.getTag('@paramExtension');
const delimiter = '\n\n';

const customizedOptions = {
...options,
hideTitle: true,
// Hide the title by default, only show it if the `@displayFunctionSignature` tag is present
hideTitle: !displayFunctionSignatureTag,
};
const customizedModel = model;
customizedModel.typeParameters = undefined;

const output = superPartials.signature(customizedModel, customizedOptions);
let output = superPartials.signature(customizedModel, customizedOptions);

// If there are extra tags, split the output by the delimiter and do the work
if (displayFunctionSignatureTag || paramExtensionTag) {
let splitOutput = output.split(delimiter);

if (displayFunctionSignatureTag) {
// Change position of the 0 index and 2 index of the output
// This way the function signature is below the description
splitOutput = swap(splitOutput, 0, 2);
}

if (paramExtensionTag) {
const stuff = this.helpers.getCommentParts(paramExtensionTag.content);

// Find the index of the item that contains '## Returns'
const index = splitOutput.findIndex(item => item.includes('## Returns'));

// If the index is found, insert the stuff before it
if (index !== -1) {
splitOutput.splice(index, 0, stuff);
}
}

// Join the output again
output = splitOutput.join(delimiter);
}

return output;
},
/**
* If `signature` has @displayFunctionSignature tag, the function will run `signatureTitle`. We want to use a completely custom code block here.
* @param {import('typedoc').SignatureReflection} model
* @param {{ accessor?: string; includeType?: boolean }} [options]
* https://github.com/typedoc2md/typedoc-plugin-markdown/blob/c83cff97b72ab25b224463ceec118c34e940cb8a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureTitle.ts
*/
signatureTitle: (model, options) => {
/**
* @type {string[]}
*/
const md = [];

const keyword = this.helpers.getKeyword(model.parent.kind);

if (this.helpers.isGroupKind(model.parent) && keyword) {
md.push(keyword + ' ');
}

if (options?.accessor) {
md.push(options?.accessor + ' ');
}

if (model.parent) {
const flagsString = this.helpers.getReflectionFlags(model.parent?.flags);
if (flagsString.length) {
md.push(this.helpers.getReflectionFlags(model.parent.flags) + ' ');
}
}

if (!['__call', '__type'].includes(model.name)) {
/**
* @type {string[]}
*/
const name = [];
if (model.kind === ReflectionKind.ConstructorSignature) {
name.push('new');
}
name.push(escapeChars(model.name));
md.push(name.join(' '));
}

if (model.typeParameters) {
md.push(
`${this.helpers.getAngleBracket('<')}${model.typeParameters
.map(typeParameter => typeParameter.name)
.join(', ')}${this.helpers.getAngleBracket('>')}`,
);
}

md.push(this.partials.signatureParameters(model.parameters || []));

if (model.type) {
md.push(`: ${this.partials.someType(model.type)}`);
}

const result = md.join('');
return codeBlock(result);
},
/**
* This condenses the output if only a "simple" return type + `@returns` is given.
* @param {import('typedoc').SignatureReflection} model
Expand DownExpand Up@@ -326,3 +415,78 @@ ${tabs}
};
}
}

/**
* @param {string} str - The string to unescape
*/
function unEscapeChars(str) {
return str
.replace(/(`[^`]*?)\\*([^`]*?`)/g, (_match, p1, p2) => `${p1}${p2.replace(/\*/g, '\\*')}`)
.replace(/\\\\/g, '\\')
.replace(/(?<!\\)\*/g, '')
.replace(/\\</g, '<')
.replace(/\\>/g, '>')
.replace(/&lt;/g, '<')
.replace(/&gt;/g, '>')
.replace(/\\_/g, '_')
.replace(/\\{/g, '{')
.replace(/\\}/g, '}')
.replace(/``.*?``|(?<!\\)`/g, match => (match.startsWith('``') ? match : ''))
.replace(/`` /g, '')
.replace(/ ``/g, '')
.replace(/\\`/g, '`')
.replace(/\\\*/g, '*')
.replace(/\\\|/g, '|')
.replace(/\\\]/g, ']')
.replace(/\\\[/g, '[')
.replace(/\[([^[\]]*)\]\((.*?)\)/gm, '$1');
}

/**
* @param {string} content
*/
function codeBlock(content) {
/**
* @param {string} content
*/
const trimLastLine = content => {
const lines = content.split('\n');
return lines.map((line, index) => (index === lines.length - 1 ? line.trim() : line)).join('\n');
};
const trimmedContent =
content.endsWith('}') || content.endsWith('};') || content.endsWith('>') || content.endsWith('>;')
? trimLastLine(content)
: content;
return '```ts\n' + unEscapeChars(trimmedContent) + '\n```';
}

/**
* @param {string} str
*/
function escapeChars(str) {
return str
.replace(/>/g, '\\>')
.replace(/</g, '\\<')
.replace(/{/g, '\\{')
.replace(/}/g, '\\}')
.replace(/_/g, '\\_')
.replace(/`/g, '\\`')
.replace(/\|/g, '\\|')
.replace(/\[/g, '\\[')
.replace(/\]/g, '\\]')
.replace(/\*/g, '\\*');
}

/**
*
* @param {string[]} arr
* @param {number} i
* @param {number} j
* @returns
*/
function swap(arr, i, j) {
let t = arr[i];
arr[i] = arr[j];
arr[j] = t;
return arr;
}
5 changes: 4 additions & 1 deletion eslint.config.mjs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -432,7 +432,10 @@ export default tseslint.config([
...pluginJsDoc.configs['flat/recommended-typescript'].rules,
'jsdoc/check-examples': 'off',
'jsdoc/informative-docs': 'warn',
'jsdoc/check-tag-names': ['warn', { definedTags: ['inline', 'unionReturnHeadings'], typed: false }],
'jsdoc/check-tag-names': [
'warn',
{ definedTags: ['inline', 'unionReturnHeadings', 'displayFunctionSignature', 'paramExtension'], typed: false },
],
'jsdoc/require-hyphen-before-param-description': 'warn',
'jsdoc/require-description': 'warn',
'jsdoc/require-description-complete-sentence': 'warn',
Expand Down
6 changes: 4 additions & 2 deletions packages/backend/src/tokens/types.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ export type AuthenticateRequestOptions = {
acceptsToken?: TokenType | TokenType[] | 'any';
} & VerifyTokenOptions;

/**
* @inline
*/
export type OrganizationSyncOptions = {
/**
* Specifies URL patterns that are organization-specific, containing an organization ID or slug as a path parameter. If a request matches this path, the organization identifier will be used to set that org as active.
Expand All@@ -68,8 +71,7 @@ export type OrganizationSyncOptions = {
*
* Patterns must have a path parameter named either `:id` (to match a Clerk organization ID) or `:slug` (to match a Clerk organization slug).
*
* > [!WARNING]
* > If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
* If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
*
* @example
* ["/orgs/:slug", "/orgs/:slug/(.*)"]
Expand Down
13 changes: 13 additions & 0 deletions packages/backend/src/tokens/verify.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -39,6 +39,19 @@ export type VerifyTokenOptions = Omit<VerifyJwtOptions, 'key'> &
* @param token - The token to verify.
* @param options - Options for verifying the token.
*
* @displayFunctionSignature
*
* @paramExtension
*
* ### `VerifyTokenOptions`
*
* It is recommended to set these options as [environment variables](/docs/deployments/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })`.
*
* > [!WARNING]
* You must provide either `jwtKey` or `secretKey`.
*
* <Typedoc src="backend/verify-token-options" />
*
* @example
*
* The following example demonstrates how to use the [JavaScript Backend SDK](https://clerk.com/docs/references/backend/overview) to verify the token signature.
Expand Down
2 changes: 2 additions & 0 deletions packages/backend/src/webhooks.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,8 @@ export * from './api/resources/Webhooks';
* @param request - The request object.
* @param options - Optional configuration object.
*
* @displayFunctionSignature
*
* @example
* See the [guide on syncing data](https://clerk.com/docs/webhooks/sync-data) for more comprehensive and framework-specific examples that you can copy and paste into your app.
*
Expand Down
6 changes: 3 additions & 3 deletions typedoc.config.mjs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@ import fs from 'node:fs';
import { OptionDefaults } from 'typedoc';

const IGNORE_LIST = ['.DS_Store', 'dev-cli', 'expo-passkeys', 'testing', 'themes', 'upgrade'];
const CUSTOM_TAGS = ['@unionReturnHeadings'];
const CUSTOM_BLOCK_TAGS = ['@unionReturnHeadings', '@displayFunctionSignature', '@paramExtension'];

/**
* Return an array of relative paths to all folders in the "packages" folder to be used for the "entryPoints" option.
Expand DownExpand Up@@ -90,7 +90,7 @@ const config = {
theme: 'clerkTheme',
router: 'clerk-router',
readme: 'none',
notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_TAGS],
notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_BLOCK_TAGS],
packageOptions: {
includeVersion: false,
excludePrivate: true,
Expand All@@ -100,7 +100,7 @@ const config = {
excludeInternal: true,
excludeNotDocumented: true,
gitRevision: 'main',
blockTags: [...OptionDefaults.blockTags, ...CUSTOM_TAGS],
blockTags: [...OptionDefaults.blockTags, ...CUSTOM_BLOCK_TAGS],
modifierTags: [...OptionDefaults.modifierTags],
exclude: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
readme: 'none',
Expand Down
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
fix(backend): JSDoc for verifyWebook & verifyToken#6060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

LekoArts
merged 4 commits into

from

Jun 4, 2025
 Merged


fix(backend): JSDoc for verifyWebook & verifyToken#6060
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
789c65b

verifyToken & verifyWebhook


LekoArts Jun 4, 2025
15ae059

add changeset


LekoArts Jun 4, 2025
4e7f16f

update types


LekoArts Jun 4, 2025
d1b452a

update snapshot


LekoArts Jun 4, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/six-lions-wear.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/backend': patch
---

Improve JSDoc comments for verifyWebhook and verifyToken

1 change: 1 addition & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -157,6 +157,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "backend/organization-invitation.mdx",
 "backend/organization-membership-public-user-data.mdx",
 "backend/organization-membership.mdx",
 "backend/organization-sync-options.mdx",
 "backend/organization-sync-target.mdx",
 "backend/organization.mdx",
 "backend/paginated-resource-response.mdx",
Expand Down

1 change: 1 addition & 0 deletions
.typedoc/custom-plugin.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,7 @@ const LINK_REPLACEMENTS = [
 ['phone-number', '/docs/references/backend/types/backend-phone-number'],
 ['saml-account', '/docs/references/backend/types/backend-saml-account'],
 ['web3-wallet', '/docs/references/backend/types/backend-web3-wallet'],
 ['verify-token-options', '#verify-token-options'],
];

/**
Expand Down

172 changes: 168 additions & 4 deletions
.typedoc/custom-theme.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
// @ts-check
import { ReflectionType, UnionType } from 'typedoc';
import { ReflectionKind, ReflectionType, UnionType } from 'typedoc';
import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';

/**
Expand DownExpand Up@@ -47,22 +47,111 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 this.partials = {
 ...superPartials,
 /**
 * This hides the "Type parameters" section and the signature title from the output
 * This hides the "Type parameters" section and the signature title from the output (by default). Shows the signature title if the `@displayFunctionSignature` tag is present.
 * @param {import('typedoc').SignatureReflection} model
 * @param {{ headingLevel: number, nested?: boolean, accessor?: string, multipleSignatures?: boolean; hideTitle?: boolean }} options
 */
 signature: (model, options) => {
 const displayFunctionSignatureTag = model.comment?.getTag('@displayFunctionSignature');
 const paramExtensionTag = model.comment?.getTag('@paramExtension');
 const delimiter = '\n\n';

 const customizedOptions = {
 ...options,
 hideTitle: true,
 // Hide the title by default, only show it if the `@displayFunctionSignature` tag is present
 hideTitle: !displayFunctionSignatureTag,
 };
 const customizedModel = model;
 customizedModel.typeParameters = undefined;

 const output = superPartials.signature(customizedModel, customizedOptions);
 let output = superPartials.signature(customizedModel, customizedOptions);

 // If there are extra tags, split the output by the delimiter and do the work
 if (displayFunctionSignatureTag || paramExtensionTag) {
 let splitOutput = output.split(delimiter);

 if (displayFunctionSignatureTag) {
 // Change position of the 0 index and 2 index of the output
 // This way the function signature is below the description
 splitOutput = swap(splitOutput, 0, 2);
 }

 if (paramExtensionTag) {
 const stuff = this.helpers.getCommentParts(paramExtensionTag.content);

 // Find the index of the item that contains '## Returns'
 const index = splitOutput.findIndex(item => item.includes('## Returns'));

 // If the index is found, insert the stuff before it
 if (index !== -1) {
 splitOutput.splice(index, 0, stuff);
 }
 }

 // Join the output again
 output = splitOutput.join(delimiter);
 }

 return output;
 },
 /**
 * If `signature` has @displayFunctionSignature tag, the function will run `signatureTitle`. We want to use a completely custom code block here.
 * @param {import('typedoc').SignatureReflection} model
 * @param {{ accessor?: string; includeType?: boolean }} [options]
 * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/c83cff97b72ab25b224463ceec118c34e940cb8a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureTitle.ts
 */
 signatureTitle: (model, options) => {
 /**
 * @type {string[]}
 */
 const md = [];

 const keyword = this.helpers.getKeyword(model.parent.kind);

 if (this.helpers.isGroupKind(model.parent) && keyword) {
 md.push(keyword + ' ');
 }

 if (options?.accessor) {
 md.push(options?.accessor + ' ');
 }

 if (model.parent) {
 const flagsString = this.helpers.getReflectionFlags(model.parent?.flags);
 if (flagsString.length) {
 md.push(this.helpers.getReflectionFlags(model.parent.flags) + ' ');
 }
 }

 if (!['__call', '__type'].includes(model.name)) {
 /**
 * @type {string[]}
 */
 const name = [];
 if (model.kind === ReflectionKind.ConstructorSignature) {
 name.push('new');
 }
 name.push(escapeChars(model.name));
 md.push(name.join(' '));
 }

 if (model.typeParameters) {
 md.push(
 `${this.helpers.getAngleBracket('<')}${model.typeParameters
 .map(typeParameter => typeParameter.name)
 .join(', ')}${this.helpers.getAngleBracket('>')}`,
 );
 }

 md.push(this.partials.signatureParameters(model.parameters || []));

 if (model.type) {
 md.push(`: ${this.partials.someType(model.type)}`);
 }

 const result = md.join('');
 return codeBlock(result);
 },
 /**
 * This condenses the output if only a "simple" return type + `@returns` is given.
 * @param {import('typedoc').SignatureReflection} model
Expand DownExpand Up@@ -326,3 +415,78 @@ ${tabs}
 };
 }
}

/**
 * @param {string} str - The string to unescape
 */
function unEscapeChars(str) {
 return str
 .replace(/(`[^`]*?)\\*([^`]*?`)/g, (_match, p1, p2) => `${p1}${p2.replace(/\*/g, '\\*')}`)
 .replace(/\\\\/g, '\\')
 .replace(/(?<!\\)\*/g, '')
 .replace(/\\</g, '<')
 .replace(/\\>/g, '>')
 .replace(/&lt;/g, '<')
 .replace(/&gt;/g, '>')
 .replace(/\\_/g, '_')
 .replace(/\\{/g, '{')
 .replace(/\\}/g, '}')
 .replace(/``.*?``|(?<!\\)`/g, match => (match.startsWith('``') ? match : ''))
 .replace(/`` /g, '')
 .replace(/ ``/g, '')
 .replace(/\\`/g, '`')
 .replace(/\\\*/g, '*')
 .replace(/\\\|/g, '|')
 .replace(/\\\]/g, ']')
 .replace(/\\\[/g, '[')
 .replace(/\[([^[\]]*)\]\((.*?)\)/gm, '$1');
}

/**
 * @param {string} content
 */
function codeBlock(content) {
 /**
 * @param {string} content
 */
 const trimLastLine = content => {
 const lines = content.split('\n');
 return lines.map((line, index) => (index === lines.length - 1 ? line.trim() : line)).join('\n');
 };
 const trimmedContent =
 content.endsWith('}') || content.endsWith('};') || content.endsWith('>') || content.endsWith('>;')
 ? trimLastLine(content)
 : content;
 return '```ts\n' + unEscapeChars(trimmedContent) + '\n```';
}

/**
 * @param {string} str
 */
function escapeChars(str) {
 return str
 .replace(/>/g, '\\>')
 .replace(/</g, '\\<')
 .replace(/{/g, '\\{')
 .replace(/}/g, '\\}')
 .replace(/_/g, '\\_')
 .replace(/`/g, '\\`')
 .replace(/\|/g, '\\|')
 .replace(/\[/g, '\\[')
 .replace(/\]/g, '\\]')
 .replace(/\*/g, '\\*');
}

/**
 *
 * @param {string[]} arr
 * @param {number} i
 * @param {number} j
 * @returns
 */
function swap(arr, i, j) {
 let t = arr[i];
 arr[i] = arr[j];
 arr[j] = t;
 return arr;
}

5 changes: 4 additions & 1 deletion
eslint.config.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -432,7 +432,10 @@ export default tseslint.config([
 ...pluginJsDoc.configs['flat/recommended-typescript'].rules,
 'jsdoc/check-examples': 'off',
 'jsdoc/informative-docs': 'warn',
 'jsdoc/check-tag-names': ['warn', { definedTags: ['inline', 'unionReturnHeadings'], typed: false }],
 'jsdoc/check-tag-names': [
 'warn',
 { definedTags: ['inline', 'unionReturnHeadings', 'displayFunctionSignature', 'paramExtension'], typed: false },
 ],
 'jsdoc/require-hyphen-before-param-description': 'warn',
 'jsdoc/require-description': 'warn',
 'jsdoc/require-description-complete-sentence': 'warn',
Expand Down

6 changes: 4 additions & 2 deletions
packages/backend/src/tokens/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ export type AuthenticateRequestOptions = {
 acceptsToken?: TokenType | TokenType[] | 'any';
} & VerifyTokenOptions;

/**
 * @inline
 */
export type OrganizationSyncOptions = {
 /**
 * Specifies URL patterns that are organization-specific, containing an organization ID or slug as a path parameter. If a request matches this path, the organization identifier will be used to set that org as active.
Expand All@@ -68,8 +71,7 @@ export type OrganizationSyncOptions = {
 *
 * Patterns must have a path parameter named either `:id` (to match a Clerk organization ID) or `:slug` (to match a Clerk organization slug).
 *
 * > [!WARNING]
 * > If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
 * If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
 *
 * @example
 * ["/orgs/:slug", "/orgs/:slug/(.*)"]
Expand Down

13 changes: 13 additions & 0 deletions
packages/backend/src/tokens/verify.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -39,6 +39,19 @@ export type VerifyTokenOptions = Omit<VerifyJwtOptions, 'key'> &
 * @param token - The token to verify.
 * @param options - Options for verifying the token.
 *
 * @displayFunctionSignature
 *
 * @paramExtension
 *
 * ### `VerifyTokenOptions`
 *
 * It is recommended to set these options as [environment variables](/docs/deployments/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })`.
 *
 * > [!WARNING]
 * You must provide either `jwtKey` or `secretKey`.
 *
 * <Typedoc src="backend/verify-token-options" />
 *
 * @example
 *
 * The following example demonstrates how to use the [JavaScript Backend SDK](https://clerk.com/docs/references/backend/overview) to verify the token signature.
Expand Down

2 changes: 2 additions & 0 deletions
packages/backend/src/webhooks.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,8 @@ export * from './api/resources/Webhooks';
 * @param request - The request object.
 * @param options - Optional configuration object.
 *
 * @displayFunctionSignature
 *
 * @example
 * See the [guide on syncing data](https://clerk.com/docs/webhooks/sync-data) for more comprehensive and framework-specific examples that you can copy and paste into your app.
 *
Expand Down

6 changes: 3 additions & 3 deletions
typedoc.config.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@ import fs from 'node:fs';
import { OptionDefaults } from 'typedoc';

const IGNORE_LIST = ['.DS_Store', 'dev-cli', 'expo-passkeys', 'testing', 'themes', 'upgrade'];
const CUSTOM_TAGS = ['@unionReturnHeadings'];
const CUSTOM_BLOCK_TAGS = ['@unionReturnHeadings', '@displayFunctionSignature', '@paramExtension'];

/**
 * Return an array of relative paths to all folders in the "packages" folder to be used for the "entryPoints" option.
Expand DownExpand Up@@ -90,7 +90,7 @@ const config = {
 theme: 'clerkTheme',
 router: 'clerk-router',
 readme: 'none',
 notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_TAGS],
 notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_BLOCK_TAGS],
 packageOptions: {
 includeVersion: false,
 excludePrivate: true,
Expand All@@ -100,7 +100,7 @@ const config = {
 excludeInternal: true,
 excludeNotDocumented: true,
 gitRevision: 'main',
 blockTags: [...OptionDefaults.blockTags, ...CUSTOM_TAGS],
 blockTags: [...OptionDefaults.blockTags, ...CUSTOM_BLOCK_TAGS],
 modifierTags: [...OptionDefaults.modifierTags],
 exclude: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
 readme: 'none',
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
fix(backend): JSDoc for verifyWebook & verifyToken#6060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

LekoArts
merged 4 commits into

from

Jun 4, 2025
 Merged


fix(backend): JSDoc for verifyWebook & verifyToken#6060
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
789c65b

verifyToken & verifyWebhook


LekoArts Jun 4, 2025
15ae059

add changeset


LekoArts Jun 4, 2025
4e7f16f

update types


LekoArts Jun 4, 2025
d1b452a

update snapshot


LekoArts Jun 4, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/six-lions-wear.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/backend': patch
---

Improve JSDoc comments for verifyWebhook and verifyToken

1 change: 1 addition & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -157,6 +157,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "backend/organization-invitation.mdx",
 "backend/organization-membership-public-user-data.mdx",
 "backend/organization-membership.mdx",
 "backend/organization-sync-options.mdx",
 "backend/organization-sync-target.mdx",
 "backend/organization.mdx",
 "backend/paginated-resource-response.mdx",
Expand Down

1 change: 1 addition & 0 deletions
.typedoc/custom-plugin.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,7 @@ const LINK_REPLACEMENTS = [
 ['phone-number', '/docs/references/backend/types/backend-phone-number'],
 ['saml-account', '/docs/references/backend/types/backend-saml-account'],
 ['web3-wallet', '/docs/references/backend/types/backend-web3-wallet'],
 ['verify-token-options', '#verify-token-options'],
];

/**
Expand Down

172 changes: 168 additions & 4 deletions
.typedoc/custom-theme.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
// @ts-check
import { ReflectionType, UnionType } from 'typedoc';
import { ReflectionKind, ReflectionType, UnionType } from 'typedoc';
import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';

/**
Expand DownExpand Up@@ -47,22 +47,111 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 this.partials = {
 ...superPartials,
 /**
 * This hides the "Type parameters" section and the signature title from the output
 * This hides the "Type parameters" section and the signature title from the output (by default). Shows the signature title if the `@displayFunctionSignature` tag is present.
 * @param {import('typedoc').SignatureReflection} model
 * @param {{ headingLevel: number, nested?: boolean, accessor?: string, multipleSignatures?: boolean; hideTitle?: boolean }} options
 */
 signature: (model, options) => {
 const displayFunctionSignatureTag = model.comment?.getTag('@displayFunctionSignature');
 const paramExtensionTag = model.comment?.getTag('@paramExtension');
 const delimiter = '\n\n';

 const customizedOptions = {
 ...options,
 hideTitle: true,
 // Hide the title by default, only show it if the `@displayFunctionSignature` tag is present
 hideTitle: !displayFunctionSignatureTag,
 };
 const customizedModel = model;
 customizedModel.typeParameters = undefined;

 const output = superPartials.signature(customizedModel, customizedOptions);
 let output = superPartials.signature(customizedModel, customizedOptions);

 // If there are extra tags, split the output by the delimiter and do the work
 if (displayFunctionSignatureTag || paramExtensionTag) {
 let splitOutput = output.split(delimiter);

 if (displayFunctionSignatureTag) {
 // Change position of the 0 index and 2 index of the output
 // This way the function signature is below the description
 splitOutput = swap(splitOutput, 0, 2);
 }

 if (paramExtensionTag) {
 const stuff = this.helpers.getCommentParts(paramExtensionTag.content);

 // Find the index of the item that contains '## Returns'
 const index = splitOutput.findIndex(item => item.includes('## Returns'));

 // If the index is found, insert the stuff before it
 if (index !== -1) {
 splitOutput.splice(index, 0, stuff);
 }
 }

 // Join the output again
 output = splitOutput.join(delimiter);
 }

 return output;
 },
 /**
 * If `signature` has @displayFunctionSignature tag, the function will run `signatureTitle`. We want to use a completely custom code block here.
 * @param {import('typedoc').SignatureReflection} model
 * @param {{ accessor?: string; includeType?: boolean }} [options]
 * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/c83cff97b72ab25b224463ceec118c34e940cb8a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureTitle.ts
 */
 signatureTitle: (model, options) => {
 /**
 * @type {string[]}
 */
 const md = [];

 const keyword = this.helpers.getKeyword(model.parent.kind);

 if (this.helpers.isGroupKind(model.parent) && keyword) {
 md.push(keyword + ' ');
 }

 if (options?.accessor) {
 md.push(options?.accessor + ' ');
 }

 if (model.parent) {
 const flagsString = this.helpers.getReflectionFlags(model.parent?.flags);
 if (flagsString.length) {
 md.push(this.helpers.getReflectionFlags(model.parent.flags) + ' ');
 }
 }

 if (!['__call', '__type'].includes(model.name)) {
 /**
 * @type {string[]}
 */
 const name = [];
 if (model.kind === ReflectionKind.ConstructorSignature) {
 name.push('new');
 }
 name.push(escapeChars(model.name));
 md.push(name.join(' '));
 }

 if (model.typeParameters) {
 md.push(
 `${this.helpers.getAngleBracket('<')}${model.typeParameters
 .map(typeParameter => typeParameter.name)
 .join(', ')}${this.helpers.getAngleBracket('>')}`,
 );
 }

 md.push(this.partials.signatureParameters(model.parameters || []));

 if (model.type) {
 md.push(`: ${this.partials.someType(model.type)}`);
 }

 const result = md.join('');
 return codeBlock(result);
 },
 /**
 * This condenses the output if only a "simple" return type + `@returns` is given.
 * @param {import('typedoc').SignatureReflection} model
Expand DownExpand Up@@ -326,3 +415,78 @@ ${tabs}
 };
 }
}

/**
 * @param {string} str - The string to unescape
 */
function unEscapeChars(str) {
 return str
 .replace(/(`[^`]*?)\\*([^`]*?`)/g, (_match, p1, p2) => `${p1}${p2.replace(/\*/g, '\\*')}`)
 .replace(/\\\\/g, '\\')
 .replace(/(?<!\\)\*/g, '')
 .replace(/\\</g, '<')
 .replace(/\\>/g, '>')
 .replace(/&lt;/g, '<')
 .replace(/&gt;/g, '>')
 .replace(/\\_/g, '_')
 .replace(/\\{/g, '{')
 .replace(/\\}/g, '}')
 .replace(/``.*?``|(?<!\\)`/g, match => (match.startsWith('``') ? match : ''))
 .replace(/`` /g, '')
 .replace(/ ``/g, '')
 .replace(/\\`/g, '`')
 .replace(/\\\*/g, '*')
 .replace(/\\\|/g, '|')
 .replace(/\\\]/g, ']')
 .replace(/\\\[/g, '[')
 .replace(/\[([^[\]]*)\]\((.*?)\)/gm, '$1');
}

/**
 * @param {string} content
 */
function codeBlock(content) {
 /**
 * @param {string} content
 */
 const trimLastLine = content => {
 const lines = content.split('\n');
 return lines.map((line, index) => (index === lines.length - 1 ? line.trim() : line)).join('\n');
 };
 const trimmedContent =
 content.endsWith('}') || content.endsWith('};') || content.endsWith('>') || content.endsWith('>;')
 ? trimLastLine(content)
 : content;
 return '```ts\n' + unEscapeChars(trimmedContent) + '\n```';
}

/**
 * @param {string} str
 */
function escapeChars(str) {
 return str
 .replace(/>/g, '\\>')
 .replace(/</g, '\\<')
 .replace(/{/g, '\\{')
 .replace(/}/g, '\\}')
 .replace(/_/g, '\\_')
 .replace(/`/g, '\\`')
 .replace(/\|/g, '\\|')
 .replace(/\[/g, '\\[')
 .replace(/\]/g, '\\]')
 .replace(/\*/g, '\\*');
}

/**
 *
 * @param {string[]} arr
 * @param {number} i
 * @param {number} j
 * @returns
 */
function swap(arr, i, j) {
 let t = arr[i];
 arr[i] = arr[j];
 arr[j] = t;
 return arr;
}

5 changes: 4 additions & 1 deletion
eslint.config.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -432,7 +432,10 @@ export default tseslint.config([
 ...pluginJsDoc.configs['flat/recommended-typescript'].rules,
 'jsdoc/check-examples': 'off',
 'jsdoc/informative-docs': 'warn',
 'jsdoc/check-tag-names': ['warn', { definedTags: ['inline', 'unionReturnHeadings'], typed: false }],
 'jsdoc/check-tag-names': [
 'warn',
 { definedTags: ['inline', 'unionReturnHeadings', 'displayFunctionSignature', 'paramExtension'], typed: false },
 ],
 'jsdoc/require-hyphen-before-param-description': 'warn',
 'jsdoc/require-description': 'warn',
 'jsdoc/require-description-complete-sentence': 'warn',
Expand Down

6 changes: 4 additions & 2 deletions
packages/backend/src/tokens/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ export type AuthenticateRequestOptions = {
 acceptsToken?: TokenType | TokenType[] | 'any';
} & VerifyTokenOptions;

/**
 * @inline
 */
export type OrganizationSyncOptions = {
 /**
 * Specifies URL patterns that are organization-specific, containing an organization ID or slug as a path parameter. If a request matches this path, the organization identifier will be used to set that org as active.
Expand All@@ -68,8 +71,7 @@ export type OrganizationSyncOptions = {
 *
 * Patterns must have a path parameter named either `:id` (to match a Clerk organization ID) or `:slug` (to match a Clerk organization slug).
 *
 * > [!WARNING]
 * > If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
 * If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
 *
 * @example
 * ["/orgs/:slug", "/orgs/:slug/(.*)"]
Expand Down

13 changes: 13 additions & 0 deletions
packages/backend/src/tokens/verify.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -39,6 +39,19 @@ export type VerifyTokenOptions = Omit<VerifyJwtOptions, 'key'> &
 * @param token - The token to verify.
 * @param options - Options for verifying the token.
 *
 * @displayFunctionSignature
 *
 * @paramExtension
 *
 * ### `VerifyTokenOptions`
 *
 * It is recommended to set these options as [environment variables](/docs/deployments/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })`.
 *
 * > [!WARNING]
 * You must provide either `jwtKey` or `secretKey`.
 *
 * <Typedoc src="backend/verify-token-options" />
 *
 * @example
 *
 * The following example demonstrates how to use the [JavaScript Backend SDK](https://clerk.com/docs/references/backend/overview) to verify the token signature.
Expand Down

2 changes: 2 additions & 0 deletions
packages/backend/src/webhooks.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,8 @@ export * from './api/resources/Webhooks';
 * @param request - The request object.
 * @param options - Optional configuration object.
 *
 * @displayFunctionSignature
 *
 * @example
 * See the [guide on syncing data](https://clerk.com/docs/webhooks/sync-data) for more comprehensive and framework-specific examples that you can copy and paste into your app.
 *
Expand Down

6 changes: 3 additions & 3 deletions
typedoc.config.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@ import fs from 'node:fs';
import { OptionDefaults } from 'typedoc';

const IGNORE_LIST = ['.DS_Store', 'dev-cli', 'expo-passkeys', 'testing', 'themes', 'upgrade'];
const CUSTOM_TAGS = ['@unionReturnHeadings'];
const CUSTOM_BLOCK_TAGS = ['@unionReturnHeadings', '@displayFunctionSignature', '@paramExtension'];

/**
 * Return an array of relative paths to all folders in the "packages" folder to be used for the "entryPoints" option.
Expand DownExpand Up@@ -90,7 +90,7 @@ const config = {
 theme: 'clerkTheme',
 router: 'clerk-router',
 readme: 'none',
 notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_TAGS],
 notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_BLOCK_TAGS],
 packageOptions: {
 includeVersion: false,
 excludePrivate: true,
Expand All@@ -100,7 +100,7 @@ const config = {
 excludeInternal: true,
 excludeNotDocumented: true,
 gitRevision: 'main',
 blockTags: [...OptionDefaults.blockTags, ...CUSTOM_TAGS],
 blockTags: [...OptionDefaults.blockTags, ...CUSTOM_BLOCK_TAGS],
 modifierTags: [...OptionDefaults.modifierTags],
 exclude: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
 readme: 'none',
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
fix(backend): JSDoc for verifyWebook & verifyToken#6060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

LekoArts
merged 4 commits into

from

Jun 4, 2025
 Merged


fix(backend): JSDoc for verifyWebook & verifyToken#6060
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
789c65b

verifyToken & verifyWebhook


LekoArts Jun 4, 2025
15ae059

add changeset


LekoArts Jun 4, 2025
4e7f16f

update types


LekoArts Jun 4, 2025
d1b452a

update snapshot


LekoArts Jun 4, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/six-lions-wear.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/backend': patch
---

Improve JSDoc comments for verifyWebhook and verifyToken

1 change: 1 addition & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -157,6 +157,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "backend/organization-invitation.mdx",
 "backend/organization-membership-public-user-data.mdx",
 "backend/organization-membership.mdx",
 "backend/organization-sync-options.mdx",
 "backend/organization-sync-target.mdx",
 "backend/organization.mdx",
 "backend/paginated-resource-response.mdx",
Expand Down

1 change: 1 addition & 0 deletions
.typedoc/custom-plugin.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,7 @@ const LINK_REPLACEMENTS = [
 ['phone-number', '/docs/references/backend/types/backend-phone-number'],
 ['saml-account', '/docs/references/backend/types/backend-saml-account'],
 ['web3-wallet', '/docs/references/backend/types/backend-web3-wallet'],
 ['verify-token-options', '#verify-token-options'],
];

/**
Expand Down

172 changes: 168 additions & 4 deletions
.typedoc/custom-theme.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
// @ts-check
import { ReflectionType, UnionType } from 'typedoc';
import { ReflectionKind, ReflectionType, UnionType } from 'typedoc';
import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';

/**
Expand DownExpand Up@@ -47,22 +47,111 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 this.partials = {
 ...superPartials,
 /**
 * This hides the "Type parameters" section and the signature title from the output
 * This hides the "Type parameters" section and the signature title from the output (by default). Shows the signature title if the `@displayFunctionSignature` tag is present.
 * @param {import('typedoc').SignatureReflection} model
 * @param {{ headingLevel: number, nested?: boolean, accessor?: string, multipleSignatures?: boolean; hideTitle?: boolean }} options
 */
 signature: (model, options) => {
 const displayFunctionSignatureTag = model.comment?.getTag('@displayFunctionSignature');
 const paramExtensionTag = model.comment?.getTag('@paramExtension');
 const delimiter = '\n\n';

 const customizedOptions = {
 ...options,
 hideTitle: true,
 // Hide the title by default, only show it if the `@displayFunctionSignature` tag is present
 hideTitle: !displayFunctionSignatureTag,
 };
 const customizedModel = model;
 customizedModel.typeParameters = undefined;

 const output = superPartials.signature(customizedModel, customizedOptions);
 let output = superPartials.signature(customizedModel, customizedOptions);

 // If there are extra tags, split the output by the delimiter and do the work
 if (displayFunctionSignatureTag || paramExtensionTag) {
 let splitOutput = output.split(delimiter);

 if (displayFunctionSignatureTag) {
 // Change position of the 0 index and 2 index of the output
 // This way the function signature is below the description
 splitOutput = swap(splitOutput, 0, 2);
 }

 if (paramExtensionTag) {
 const stuff = this.helpers.getCommentParts(paramExtensionTag.content);

 // Find the index of the item that contains '## Returns'
 const index = splitOutput.findIndex(item => item.includes('## Returns'));

 // If the index is found, insert the stuff before it
 if (index !== -1) {
 splitOutput.splice(index, 0, stuff);
 }
 }

 // Join the output again
 output = splitOutput.join(delimiter);
 }

 return output;
 },
 /**
 * If `signature` has @displayFunctionSignature tag, the function will run `signatureTitle`. We want to use a completely custom code block here.
 * @param {import('typedoc').SignatureReflection} model
 * @param {{ accessor?: string; includeType?: boolean }} [options]
 * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/c83cff97b72ab25b224463ceec118c34e940cb8a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureTitle.ts
 */
 signatureTitle: (model, options) => {
 /**
 * @type {string[]}
 */
 const md = [];

 const keyword = this.helpers.getKeyword(model.parent.kind);

 if (this.helpers.isGroupKind(model.parent) && keyword) {
 md.push(keyword + ' ');
 }

 if (options?.accessor) {
 md.push(options?.accessor + ' ');
 }

 if (model.parent) {
 const flagsString = this.helpers.getReflectionFlags(model.parent?.flags);
 if (flagsString.length) {
 md.push(this.helpers.getReflectionFlags(model.parent.flags) + ' ');
 }
 }

 if (!['__call', '__type'].includes(model.name)) {
 /**
 * @type {string[]}
 */
 const name = [];
 if (model.kind === ReflectionKind.ConstructorSignature) {
 name.push('new');
 }
 name.push(escapeChars(model.name));
 md.push(name.join(' '));
 }

 if (model.typeParameters) {
 md.push(
 `${this.helpers.getAngleBracket('<')}${model.typeParameters
 .map(typeParameter => typeParameter.name)
 .join(', ')}${this.helpers.getAngleBracket('>')}`,
 );
 }

 md.push(this.partials.signatureParameters(model.parameters || []));

 if (model.type) {
 md.push(`: ${this.partials.someType(model.type)}`);
 }

 const result = md.join('');
 return codeBlock(result);
 },
 /**
 * This condenses the output if only a "simple" return type + `@returns` is given.
 * @param {import('typedoc').SignatureReflection} model
Expand DownExpand Up@@ -326,3 +415,78 @@ ${tabs}
 };
 }
}

/**
 * @param {string} str - The string to unescape
 */
function unEscapeChars(str) {
 return str
 .replace(/(`[^`]*?)\\*([^`]*?`)/g, (_match, p1, p2) => `${p1}${p2.replace(/\*/g, '\\*')}`)
 .replace(/\\\\/g, '\\')
 .replace(/(?<!\\)\*/g, '')
 .replace(/\\</g, '<')
 .replace(/\\>/g, '>')
 .replace(/&lt;/g, '<')
 .replace(/&gt;/g, '>')
 .replace(/\\_/g, '_')
 .replace(/\\{/g, '{')
 .replace(/\\}/g, '}')
 .replace(/``.*?``|(?<!\\)`/g, match => (match.startsWith('``') ? match : ''))
 .replace(/`` /g, '')
 .replace(/ ``/g, '')
 .replace(/\\`/g, '`')
 .replace(/\\\*/g, '*')
 .replace(/\\\|/g, '|')
 .replace(/\\\]/g, ']')
 .replace(/\\\[/g, '[')
 .replace(/\[([^[\]]*)\]\((.*?)\)/gm, '$1');
}

/**
 * @param {string} content
 */
function codeBlock(content) {
 /**
 * @param {string} content
 */
 const trimLastLine = content => {
 const lines = content.split('\n');
 return lines.map((line, index) => (index === lines.length - 1 ? line.trim() : line)).join('\n');
 };
 const trimmedContent =
 content.endsWith('}') || content.endsWith('};') || content.endsWith('>') || content.endsWith('>;')
 ? trimLastLine(content)
 : content;
 return '```ts\n' + unEscapeChars(trimmedContent) + '\n```';
}

/**
 * @param {string} str
 */
function escapeChars(str) {
 return str
 .replace(/>/g, '\\>')
 .replace(/</g, '\\<')
 .replace(/{/g, '\\{')
 .replace(/}/g, '\\}')
 .replace(/_/g, '\\_')
 .replace(/`/g, '\\`')
 .replace(/\|/g, '\\|')
 .replace(/\[/g, '\\[')
 .replace(/\]/g, '\\]')
 .replace(/\*/g, '\\*');
}

/**
 *
 * @param {string[]} arr
 * @param {number} i
 * @param {number} j
 * @returns
 */
function swap(arr, i, j) {
 let t = arr[i];
 arr[i] = arr[j];
 arr[j] = t;
 return arr;
}

5 changes: 4 additions & 1 deletion
eslint.config.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -432,7 +432,10 @@ export default tseslint.config([
 ...pluginJsDoc.configs['flat/recommended-typescript'].rules,
 'jsdoc/check-examples': 'off',
 'jsdoc/informative-docs': 'warn',
 'jsdoc/check-tag-names': ['warn', { definedTags: ['inline', 'unionReturnHeadings'], typed: false }],
 'jsdoc/check-tag-names': [
 'warn',
 { definedTags: ['inline', 'unionReturnHeadings', 'displayFunctionSignature', 'paramExtension'], typed: false },
 ],
 'jsdoc/require-hyphen-before-param-description': 'warn',
 'jsdoc/require-description': 'warn',
 'jsdoc/require-description-complete-sentence': 'warn',
Expand Down

6 changes: 4 additions & 2 deletions
packages/backend/src/tokens/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ export type AuthenticateRequestOptions = {
 acceptsToken?: TokenType | TokenType[] | 'any';
} & VerifyTokenOptions;

/**
 * @inline
 */
export type OrganizationSyncOptions = {
 /**
 * Specifies URL patterns that are organization-specific, containing an organization ID or slug as a path parameter. If a request matches this path, the organization identifier will be used to set that org as active.
Expand All@@ -68,8 +71,7 @@ export type OrganizationSyncOptions = {
 *
 * Patterns must have a path parameter named either `:id` (to match a Clerk organization ID) or `:slug` (to match a Clerk organization slug).
 *
 * > [!WARNING]
 * > If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
 * If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
 *
 * @example
 * ["/orgs/:slug", "/orgs/:slug/(.*)"]
Expand Down

13 changes: 13 additions & 0 deletions
packages/backend/src/tokens/verify.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -39,6 +39,19 @@ export type VerifyTokenOptions = Omit<VerifyJwtOptions, 'key'> &
 * @param token - The token to verify.
 * @param options - Options for verifying the token.
 *
 * @displayFunctionSignature
 *
 * @paramExtension
 *
 * ### `VerifyTokenOptions`
 *
 * It is recommended to set these options as [environment variables](/docs/deployments/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })`.
 *
 * > [!WARNING]
 * You must provide either `jwtKey` or `secretKey`.
 *
 * <Typedoc src="backend/verify-token-options" />
 *
 * @example
 *
 * The following example demonstrates how to use the [JavaScript Backend SDK](https://clerk.com/docs/references/backend/overview) to verify the token signature.
Expand Down

2 changes: 2 additions & 0 deletions
packages/backend/src/webhooks.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,8 @@ export * from './api/resources/Webhooks';
 * @param request - The request object.
 * @param options - Optional configuration object.
 *
 * @displayFunctionSignature
 *
 * @example
 * See the [guide on syncing data](https://clerk.com/docs/webhooks/sync-data) for more comprehensive and framework-specific examples that you can copy and paste into your app.
 *
Expand Down

6 changes: 3 additions & 3 deletions
typedoc.config.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@ import fs from 'node:fs';
import { OptionDefaults } from 'typedoc';

const IGNORE_LIST = ['.DS_Store', 'dev-cli', 'expo-passkeys', 'testing', 'themes', 'upgrade'];
const CUSTOM_TAGS = ['@unionReturnHeadings'];
const CUSTOM_BLOCK_TAGS = ['@unionReturnHeadings', '@displayFunctionSignature', '@paramExtension'];

/**
 * Return an array of relative paths to all folders in the "packages" folder to be used for the "entryPoints" option.
Expand DownExpand Up@@ -90,7 +90,7 @@ const config = {
 theme: 'clerkTheme',
 router: 'clerk-router',
 readme: 'none',
 notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_TAGS],
 notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_BLOCK_TAGS],
 packageOptions: {
 includeVersion: false,
 excludePrivate: true,
Expand All@@ -100,7 +100,7 @@ const config = {
 excludeInternal: true,
 excludeNotDocumented: true,
 gitRevision: 'main',
 blockTags: [...OptionDefaults.blockTags, ...CUSTOM_TAGS],
 blockTags: [...OptionDefaults.blockTags, ...CUSTOM_BLOCK_TAGS],
 modifierTags: [...OptionDefaults.modifierTags],
 exclude: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
 readme: 'none',
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
fix(backend): JSDoc for verifyWebook & verifyToken#6060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

LekoArts
merged 4 commits into

from

Jun 4, 2025
 Merged


fix(backend): JSDoc for verifyWebook & verifyToken#6060
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
789c65b

verifyToken & verifyWebhook


LekoArts Jun 4, 2025
15ae059

add changeset


LekoArts Jun 4, 2025
4e7f16f

update types


LekoArts Jun 4, 2025
d1b452a

update snapshot


LekoArts Jun 4, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/six-lions-wear.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/backend': patch
---

Improve JSDoc comments for verifyWebhook and verifyToken

1 change: 1 addition & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -157,6 +157,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "backend/organization-invitation.mdx",
 "backend/organization-membership-public-user-data.mdx",
 "backend/organization-membership.mdx",
 "backend/organization-sync-options.mdx",
 "backend/organization-sync-target.mdx",
 "backend/organization.mdx",
 "backend/paginated-resource-response.mdx",
Expand Down

1 change: 1 addition & 0 deletions
.typedoc/custom-plugin.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,7 @@ const LINK_REPLACEMENTS = [
 ['phone-number', '/docs/references/backend/types/backend-phone-number'],
 ['saml-account', '/docs/references/backend/types/backend-saml-account'],
 ['web3-wallet', '/docs/references/backend/types/backend-web3-wallet'],
 ['verify-token-options', '#verify-token-options'],
];

/**
Expand Down

172 changes: 168 additions & 4 deletions
.typedoc/custom-theme.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
// @ts-check
import { ReflectionType, UnionType } from 'typedoc';
import { ReflectionKind, ReflectionType, UnionType } from 'typedoc';
import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';

/**
Expand DownExpand Up@@ -47,22 +47,111 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 this.partials = {
 ...superPartials,
 /**
 * This hides the "Type parameters" section and the signature title from the output
 * This hides the "Type parameters" section and the signature title from the output (by default). Shows the signature title if the `@displayFunctionSignature` tag is present.
 * @param {import('typedoc').SignatureReflection} model
 * @param {{ headingLevel: number, nested?: boolean, accessor?: string, multipleSignatures?: boolean; hideTitle?: boolean }} options
 */
 signature: (model, options) => {
 const displayFunctionSignatureTag = model.comment?.getTag('@displayFunctionSignature');
 const paramExtensionTag = model.comment?.getTag('@paramExtension');
 const delimiter = '\n\n';

 const customizedOptions = {
 ...options,
 hideTitle: true,
 // Hide the title by default, only show it if the `@displayFunctionSignature` tag is present
 hideTitle: !displayFunctionSignatureTag,
 };
 const customizedModel = model;
 customizedModel.typeParameters = undefined;

 const output = superPartials.signature(customizedModel, customizedOptions);
 let output = superPartials.signature(customizedModel, customizedOptions);

 // If there are extra tags, split the output by the delimiter and do the work
 if (displayFunctionSignatureTag || paramExtensionTag) {
 let splitOutput = output.split(delimiter);

 if (displayFunctionSignatureTag) {
 // Change position of the 0 index and 2 index of the output
 // This way the function signature is below the description
 splitOutput = swap(splitOutput, 0, 2);
 }

 if (paramExtensionTag) {
 const stuff = this.helpers.getCommentParts(paramExtensionTag.content);

 // Find the index of the item that contains '## Returns'
 const index = splitOutput.findIndex(item => item.includes('## Returns'));

 // If the index is found, insert the stuff before it
 if (index !== -1) {
 splitOutput.splice(index, 0, stuff);
 }
 }

 // Join the output again
 output = splitOutput.join(delimiter);
 }

 return output;
 },
 /**
 * If `signature` has @displayFunctionSignature tag, the function will run `signatureTitle`. We want to use a completely custom code block here.
 * @param {import('typedoc').SignatureReflection} model
 * @param {{ accessor?: string; includeType?: boolean }} [options]
 * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/c83cff97b72ab25b224463ceec118c34e940cb8a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureTitle.ts
 */
 signatureTitle: (model, options) => {
 /**
 * @type {string[]}
 */
 const md = [];

 const keyword = this.helpers.getKeyword(model.parent.kind);

 if (this.helpers.isGroupKind(model.parent) && keyword) {
 md.push(keyword + ' ');
 }

 if (options?.accessor) {
 md.push(options?.accessor + ' ');
 }

 if (model.parent) {
 const flagsString = this.helpers.getReflectionFlags(model.parent?.flags);
 if (flagsString.length) {
 md.push(this.helpers.getReflectionFlags(model.parent.flags) + ' ');
 }
 }

 if (!['__call', '__type'].includes(model.name)) {
 /**
 * @type {string[]}
 */
 const name = [];
 if (model.kind === ReflectionKind.ConstructorSignature) {
 name.push('new');
 }
 name.push(escapeChars(model.name));
 md.push(name.join(' '));
 }

 if (model.typeParameters) {
 md.push(
 `${this.helpers.getAngleBracket('<')}${model.typeParameters
 .map(typeParameter => typeParameter.name)
 .join(', ')}${this.helpers.getAngleBracket('>')}`,
 );
 }

 md.push(this.partials.signatureParameters(model.parameters || []));

 if (model.type) {
 md.push(`: ${this.partials.someType(model.type)}`);
 }

 const result = md.join('');
 return codeBlock(result);
 },
 /**
 * This condenses the output if only a "simple" return type + `@returns` is given.
 * @param {import('typedoc').SignatureReflection} model
Expand DownExpand Up@@ -326,3 +415,78 @@ ${tabs}
 };
 }
}

/**
 * @param {string} str - The string to unescape
 */
function unEscapeChars(str) {
 return str
 .replace(/(`[^`]*?)\\*([^`]*?`)/g, (_match, p1, p2) => `${p1}${p2.replace(/\*/g, '\\*')}`)
 .replace(/\\\\/g, '\\')
 .replace(/(?<!\\)\*/g, '')
 .replace(/\\</g, '<')
 .replace(/\\>/g, '>')
 .replace(/&lt;/g, '<')
 .replace(/&gt;/g, '>')
 .replace(/\\_/g, '_')
 .replace(/\\{/g, '{')
 .replace(/\\}/g, '}')
 .replace(/``.*?``|(?<!\\)`/g, match => (match.startsWith('``') ? match : ''))
 .replace(/`` /g, '')
 .replace(/ ``/g, '')
 .replace(/\\`/g, '`')
 .replace(/\\\*/g, '*')
 .replace(/\\\|/g, '|')
 .replace(/\\\]/g, ']')
 .replace(/\\\[/g, '[')
 .replace(/\[([^[\]]*)\]\((.*?)\)/gm, '$1');
}

/**
 * @param {string} content
 */
function codeBlock(content) {
 /**
 * @param {string} content
 */
 const trimLastLine = content => {
 const lines = content.split('\n');
 return lines.map((line, index) => (index === lines.length - 1 ? line.trim() : line)).join('\n');
 };
 const trimmedContent =
 content.endsWith('}') || content.endsWith('};') || content.endsWith('>') || content.endsWith('>;')
 ? trimLastLine(content)
 : content;
 return '```ts\n' + unEscapeChars(trimmedContent) + '\n```';
}

/**
 * @param {string} str
 */
function escapeChars(str) {
 return str
 .replace(/>/g, '\\>')
 .replace(/</g, '\\<')
 .replace(/{/g, '\\{')
 .replace(/}/g, '\\}')
 .replace(/_/g, '\\_')
 .replace(/`/g, '\\`')
 .replace(/\|/g, '\\|')
 .replace(/\[/g, '\\[')
 .replace(/\]/g, '\\]')
 .replace(/\*/g, '\\*');
}

/**
 *
 * @param {string[]} arr
 * @param {number} i
 * @param {number} j
 * @returns
 */
function swap(arr, i, j) {
 let t = arr[i];
 arr[i] = arr[j];
 arr[j] = t;
 return arr;
}

5 changes: 4 additions & 1 deletion
eslint.config.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -432,7 +432,10 @@ export default tseslint.config([
 ...pluginJsDoc.configs['flat/recommended-typescript'].rules,
 'jsdoc/check-examples': 'off',
 'jsdoc/informative-docs': 'warn',
 'jsdoc/check-tag-names': ['warn', { definedTags: ['inline', 'unionReturnHeadings'], typed: false }],
 'jsdoc/check-tag-names': [
 'warn',
 { definedTags: ['inline', 'unionReturnHeadings', 'displayFunctionSignature', 'paramExtension'], typed: false },
 ],
 'jsdoc/require-hyphen-before-param-description': 'warn',
 'jsdoc/require-description': 'warn',
 'jsdoc/require-description-complete-sentence': 'warn',
Expand Down

6 changes: 4 additions & 2 deletions
packages/backend/src/tokens/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ export type AuthenticateRequestOptions = {
 acceptsToken?: TokenType | TokenType[] | 'any';
} & VerifyTokenOptions;

/**
 * @inline
 */
export type OrganizationSyncOptions = {
 /**
 * Specifies URL patterns that are organization-specific, containing an organization ID or slug as a path parameter. If a request matches this path, the organization identifier will be used to set that org as active.
Expand All@@ -68,8 +71,7 @@ export type OrganizationSyncOptions = {
 *
 * Patterns must have a path parameter named either `:id` (to match a Clerk organization ID) or `:slug` (to match a Clerk organization slug).
 *
 * > [!WARNING]
 * > If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
 * If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
 *
 * @example
 * ["/orgs/:slug", "/orgs/:slug/(.*)"]
Expand Down

13 changes: 13 additions & 0 deletions
packages/backend/src/tokens/verify.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -39,6 +39,19 @@ export type VerifyTokenOptions = Omit<VerifyJwtOptions, 'key'> &
 * @param token - The token to verify.
 * @param options - Options for verifying the token.
 *
 * @displayFunctionSignature
 *
 * @paramExtension
 *
 * ### `VerifyTokenOptions`
 *
 * It is recommended to set these options as [environment variables](/docs/deployments/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })`.
 *
 * > [!WARNING]
 * You must provide either `jwtKey` or `secretKey`.
 *
 * <Typedoc src="backend/verify-token-options" />
 *
 * @example
 *
 * The following example demonstrates how to use the [JavaScript Backend SDK](https://clerk.com/docs/references/backend/overview) to verify the token signature.
Expand Down

2 changes: 2 additions & 0 deletions
packages/backend/src/webhooks.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,8 @@ export * from './api/resources/Webhooks';
 * @param request - The request object.
 * @param options - Optional configuration object.
 *
 * @displayFunctionSignature
 *
 * @example
 * See the [guide on syncing data](https://clerk.com/docs/webhooks/sync-data) for more comprehensive and framework-specific examples that you can copy and paste into your app.
 *
Expand Down

6 changes: 3 additions & 3 deletions
typedoc.config.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@ import fs from 'node:fs';
import { OptionDefaults } from 'typedoc';

const IGNORE_LIST = ['.DS_Store', 'dev-cli', 'expo-passkeys', 'testing', 'themes', 'upgrade'];
const CUSTOM_TAGS = ['@unionReturnHeadings'];
const CUSTOM_BLOCK_TAGS = ['@unionReturnHeadings', '@displayFunctionSignature', '@paramExtension'];

/**
 * Return an array of relative paths to all folders in the "packages" folder to be used for the "entryPoints" option.
Expand DownExpand Up@@ -90,7 +90,7 @@ const config = {
 theme: 'clerkTheme',
 router: 'clerk-router',
 readme: 'none',
 notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_TAGS],
 notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_BLOCK_TAGS],
 packageOptions: {
 includeVersion: false,
 excludePrivate: true,
Expand All@@ -100,7 +100,7 @@ const config = {
 excludeInternal: true,
 excludeNotDocumented: true,
 gitRevision: 'main',
 blockTags: [...OptionDefaults.blockTags, ...CUSTOM_TAGS],
 blockTags: [...OptionDefaults.blockTags, ...CUSTOM_BLOCK_TAGS],
 modifierTags: [...OptionDefaults.modifierTags],
 exclude: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
 readme: 'none',
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
fix(backend): JSDoc for verifyWebook & verifyToken#6060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

LekoArts
merged 4 commits into

from

Jun 4, 2025
 Merged


fix(backend): JSDoc for verifyWebook & verifyToken#6060
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
789c65b

verifyToken & verifyWebhook


LekoArts Jun 4, 2025
15ae059

add changeset


LekoArts Jun 4, 2025
4e7f16f

update types


LekoArts Jun 4, 2025
d1b452a

update snapshot


LekoArts Jun 4, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/six-lions-wear.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/backend': patch
---

Improve JSDoc comments for verifyWebhook and verifyToken

1 change: 1 addition & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -157,6 +157,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "backend/organization-invitation.mdx",
 "backend/organization-membership-public-user-data.mdx",
 "backend/organization-membership.mdx",
 "backend/organization-sync-options.mdx",
 "backend/organization-sync-target.mdx",
 "backend/organization.mdx",
 "backend/paginated-resource-response.mdx",
Expand Down

1 change: 1 addition & 0 deletions
.typedoc/custom-plugin.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,7 @@ const LINK_REPLACEMENTS = [
 ['phone-number', '/docs/references/backend/types/backend-phone-number'],
 ['saml-account', '/docs/references/backend/types/backend-saml-account'],
 ['web3-wallet', '/docs/references/backend/types/backend-web3-wallet'],
 ['verify-token-options', '#verify-token-options'],
];

/**
Expand Down

172 changes: 168 additions & 4 deletions
.typedoc/custom-theme.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
// @ts-check
import { ReflectionType, UnionType } from 'typedoc';
import { ReflectionKind, ReflectionType, UnionType } from 'typedoc';
import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';

/**
Expand DownExpand Up@@ -47,22 +47,111 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 this.partials = {
 ...superPartials,
 /**
 * This hides the "Type parameters" section and the signature title from the output
 * This hides the "Type parameters" section and the signature title from the output (by default). Shows the signature title if the `@displayFunctionSignature` tag is present.
 * @param {import('typedoc').SignatureReflection} model
 * @param {{ headingLevel: number, nested?: boolean, accessor?: string, multipleSignatures?: boolean; hideTitle?: boolean }} options
 */
 signature: (model, options) => {
 const displayFunctionSignatureTag = model.comment?.getTag('@displayFunctionSignature');
 const paramExtensionTag = model.comment?.getTag('@paramExtension');
 const delimiter = '\n\n';

 const customizedOptions = {
 ...options,
 hideTitle: true,
 // Hide the title by default, only show it if the `@displayFunctionSignature` tag is present
 hideTitle: !displayFunctionSignatureTag,
 };
 const customizedModel = model;
 customizedModel.typeParameters = undefined;

 const output = superPartials.signature(customizedModel, customizedOptions);
 let output = superPartials.signature(customizedModel, customizedOptions);

 // If there are extra tags, split the output by the delimiter and do the work
 if (displayFunctionSignatureTag || paramExtensionTag) {
 let splitOutput = output.split(delimiter);

 if (displayFunctionSignatureTag) {
 // Change position of the 0 index and 2 index of the output
 // This way the function signature is below the description
 splitOutput = swap(splitOutput, 0, 2);
 }

 if (paramExtensionTag) {
 const stuff = this.helpers.getCommentParts(paramExtensionTag.content);

 // Find the index of the item that contains '## Returns'
 const index = splitOutput.findIndex(item => item.includes('## Returns'));

 // If the index is found, insert the stuff before it
 if (index !== -1) {
 splitOutput.splice(index, 0, stuff);
 }
 }

 // Join the output again
 output = splitOutput.join(delimiter);
 }

 return output;
 },
 /**
 * If `signature` has @displayFunctionSignature tag, the function will run `signatureTitle`. We want to use a completely custom code block here.
 * @param {import('typedoc').SignatureReflection} model
 * @param {{ accessor?: string; includeType?: boolean }} [options]
 * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/c83cff97b72ab25b224463ceec118c34e940cb8a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureTitle.ts
 */
 signatureTitle: (model, options) => {
 /**
 * @type {string[]}
 */
 const md = [];

 const keyword = this.helpers.getKeyword(model.parent.kind);

 if (this.helpers.isGroupKind(model.parent) && keyword) {
 md.push(keyword + ' ');
 }

 if (options?.accessor) {
 md.push(options?.accessor + ' ');
 }

 if (model.parent) {
 const flagsString = this.helpers.getReflectionFlags(model.parent?.flags);
 if (flagsString.length) {
 md.push(this.helpers.getReflectionFlags(model.parent.flags) + ' ');
 }
 }

 if (!['__call', '__type'].includes(model.name)) {
 /**
 * @type {string[]}
 */
 const name = [];
 if (model.kind === ReflectionKind.ConstructorSignature) {
 name.push('new');
 }
 name.push(escapeChars(model.name));
 md.push(name.join(' '));
 }

 if (model.typeParameters) {
 md.push(
 `${this.helpers.getAngleBracket('<')}${model.typeParameters
 .map(typeParameter => typeParameter.name)
 .join(', ')}${this.helpers.getAngleBracket('>')}`,
 );
 }

 md.push(this.partials.signatureParameters(model.parameters || []));

 if (model.type) {
 md.push(`: ${this.partials.someType(model.type)}`);
 }

 const result = md.join('');
 return codeBlock(result);
 },
 /**
 * This condenses the output if only a "simple" return type + `@returns` is given.
 * @param {import('typedoc').SignatureReflection} model
Expand DownExpand Up@@ -326,3 +415,78 @@ ${tabs}
 };
 }
}

/**
 * @param {string} str - The string to unescape
 */
function unEscapeChars(str) {
 return str
 .replace(/(`[^`]*?)\\*([^`]*?`)/g, (_match, p1, p2) => `${p1}${p2.replace(/\*/g, '\\*')}`)
 .replace(/\\\\/g, '\\')
 .replace(/(?<!\\)\*/g, '')
 .replace(/\\</g, '<')
 .replace(/\\>/g, '>')
 .replace(/&lt;/g, '<')
 .replace(/&gt;/g, '>')
 .replace(/\\_/g, '_')
 .replace(/\\{/g, '{')
 .replace(/\\}/g, '}')
 .replace(/``.*?``|(?<!\\)`/g, match => (match.startsWith('``') ? match : ''))
 .replace(/`` /g, '')
 .replace(/ ``/g, '')
 .replace(/\\`/g, '`')
 .replace(/\\\*/g, '*')
 .replace(/\\\|/g, '|')
 .replace(/\\\]/g, ']')
 .replace(/\\\[/g, '[')
 .replace(/\[([^[\]]*)\]\((.*?)\)/gm, '$1');
}

/**
 * @param {string} content
 */
function codeBlock(content) {
 /**
 * @param {string} content
 */
 const trimLastLine = content => {
 const lines = content.split('\n');
 return lines.map((line, index) => (index === lines.length - 1 ? line.trim() : line)).join('\n');
 };
 const trimmedContent =
 content.endsWith('}') || content.endsWith('};') || content.endsWith('>') || content.endsWith('>;')
 ? trimLastLine(content)
 : content;
 return '```ts\n' + unEscapeChars(trimmedContent) + '\n```';
}

/**
 * @param {string} str
 */
function escapeChars(str) {
 return str
 .replace(/>/g, '\\>')
 .replace(/</g, '\\<')
 .replace(/{/g, '\\{')
 .replace(/}/g, '\\}')
 .replace(/_/g, '\\_')
 .replace(/`/g, '\\`')
 .replace(/\|/g, '\\|')
 .replace(/\[/g, '\\[')
 .replace(/\]/g, '\\]')
 .replace(/\*/g, '\\*');
}

/**
 *
 * @param {string[]} arr
 * @param {number} i
 * @param {number} j
 * @returns
 */
function swap(arr, i, j) {
 let t = arr[i];
 arr[i] = arr[j];
 arr[j] = t;
 return arr;
}

5 changes: 4 additions & 1 deletion
eslint.config.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -432,7 +432,10 @@ export default tseslint.config([
 ...pluginJsDoc.configs['flat/recommended-typescript'].rules,
 'jsdoc/check-examples': 'off',
 'jsdoc/informative-docs': 'warn',
 'jsdoc/check-tag-names': ['warn', { definedTags: ['inline', 'unionReturnHeadings'], typed: false }],
 'jsdoc/check-tag-names': [
 'warn',
 { definedTags: ['inline', 'unionReturnHeadings', 'displayFunctionSignature', 'paramExtension'], typed: false },
 ],
 'jsdoc/require-hyphen-before-param-description': 'warn',
 'jsdoc/require-description': 'warn',
 'jsdoc/require-description-complete-sentence': 'warn',
Expand Down

6 changes: 4 additions & 2 deletions
packages/backend/src/tokens/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ export type AuthenticateRequestOptions = {
 acceptsToken?: TokenType | TokenType[] | 'any';
} & VerifyTokenOptions;

/**
 * @inline
 */
export type OrganizationSyncOptions = {
 /**
 * Specifies URL patterns that are organization-specific, containing an organization ID or slug as a path parameter. If a request matches this path, the organization identifier will be used to set that org as active.
Expand All@@ -68,8 +71,7 @@ export type OrganizationSyncOptions = {
 *
 * Patterns must have a path parameter named either `:id` (to match a Clerk organization ID) or `:slug` (to match a Clerk organization slug).
 *
 * > [!WARNING]
 * > If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
 * If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
 *
 * @example
 * ["/orgs/:slug", "/orgs/:slug/(.*)"]
Expand Down

13 changes: 13 additions & 0 deletions
packages/backend/src/tokens/verify.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -39,6 +39,19 @@ export type VerifyTokenOptions = Omit<VerifyJwtOptions, 'key'> &
 * @param token - The token to verify.
 * @param options - Options for verifying the token.
 *
 * @displayFunctionSignature
 *
 * @paramExtension
 *
 * ### `VerifyTokenOptions`
 *
 * It is recommended to set these options as [environment variables](/docs/deployments/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })`.
 *
 * > [!WARNING]
 * You must provide either `jwtKey` or `secretKey`.
 *
 * <Typedoc src="backend/verify-token-options" />
 *
 * @example
 *
 * The following example demonstrates how to use the [JavaScript Backend SDK](https://clerk.com/docs/references/backend/overview) to verify the token signature.
Expand Down

2 changes: 2 additions & 0 deletions
packages/backend/src/webhooks.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,8 @@ export * from './api/resources/Webhooks';
 * @param request - The request object.
 * @param options - Optional configuration object.
 *
 * @displayFunctionSignature
 *
 * @example
 * See the [guide on syncing data](https://clerk.com/docs/webhooks/sync-data) for more comprehensive and framework-specific examples that you can copy and paste into your app.
 *
Expand Down

6 changes: 3 additions & 3 deletions
typedoc.config.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@ import fs from 'node:fs';
import { OptionDefaults } from 'typedoc';

const IGNORE_LIST = ['.DS_Store', 'dev-cli', 'expo-passkeys', 'testing', 'themes', 'upgrade'];
const CUSTOM_TAGS = ['@unionReturnHeadings'];
const CUSTOM_BLOCK_TAGS = ['@unionReturnHeadings', '@displayFunctionSignature', '@paramExtension'];

/**
 * Return an array of relative paths to all folders in the "packages" folder to be used for the "entryPoints" option.
Expand DownExpand Up@@ -90,7 +90,7 @@ const config = {
 theme: 'clerkTheme',
 router: 'clerk-router',
 readme: 'none',
 notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_TAGS],
 notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_BLOCK_TAGS],
 packageOptions: {
 includeVersion: false,
 excludePrivate: true,
Expand All@@ -100,7 +100,7 @@ const config = {
 excludeInternal: true,
 excludeNotDocumented: true,
 gitRevision: 'main',
 blockTags: [...OptionDefaults.blockTags, ...CUSTOM_TAGS],
 blockTags: [...OptionDefaults.blockTags, ...CUSTOM_BLOCK_TAGS],
 modifierTags: [...OptionDefaults.modifierTags],
 exclude: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
 readme: 'none',
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
fix(backend): JSDoc for verifyWebook & verifyToken#6060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

LekoArts
merged 4 commits into

from

Jun 4, 2025
 Merged


fix(backend): JSDoc for verifyWebook & verifyToken#6060
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
789c65b

verifyToken & verifyWebhook


LekoArts Jun 4, 2025
15ae059

add changeset


LekoArts Jun 4, 2025
4e7f16f

update types


LekoArts Jun 4, 2025
d1b452a

update snapshot


LekoArts Jun 4, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/six-lions-wear.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/backend': patch
---

Improve JSDoc comments for verifyWebhook and verifyToken

1 change: 1 addition & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -157,6 +157,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "backend/organization-invitation.mdx",
 "backend/organization-membership-public-user-data.mdx",
 "backend/organization-membership.mdx",
 "backend/organization-sync-options.mdx",
 "backend/organization-sync-target.mdx",
 "backend/organization.mdx",
 "backend/paginated-resource-response.mdx",
Expand Down

1 change: 1 addition & 0 deletions
.typedoc/custom-plugin.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,7 @@ const LINK_REPLACEMENTS = [
 ['phone-number', '/docs/references/backend/types/backend-phone-number'],
 ['saml-account', '/docs/references/backend/types/backend-saml-account'],
 ['web3-wallet', '/docs/references/backend/types/backend-web3-wallet'],
 ['verify-token-options', '#verify-token-options'],
];

/**
Expand Down

172 changes: 168 additions & 4 deletions
.typedoc/custom-theme.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
// @ts-check
import { ReflectionType, UnionType } from 'typedoc';
import { ReflectionKind, ReflectionType, UnionType } from 'typedoc';
import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';

/**
Expand DownExpand Up@@ -47,22 +47,111 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 this.partials = {
 ...superPartials,
 /**
 * This hides the "Type parameters" section and the signature title from the output
 * This hides the "Type parameters" section and the signature title from the output (by default). Shows the signature title if the `@displayFunctionSignature` tag is present.
 * @param {import('typedoc').SignatureReflection} model
 * @param {{ headingLevel: number, nested?: boolean, accessor?: string, multipleSignatures?: boolean; hideTitle?: boolean }} options
 */
 signature: (model, options) => {
 const displayFunctionSignatureTag = model.comment?.getTag('@displayFunctionSignature');
 const paramExtensionTag = model.comment?.getTag('@paramExtension');
 const delimiter = '\n\n';

 const customizedOptions = {
 ...options,
 hideTitle: true,
 // Hide the title by default, only show it if the `@displayFunctionSignature` tag is present
 hideTitle: !displayFunctionSignatureTag,
 };
 const customizedModel = model;
 customizedModel.typeParameters = undefined;

 const output = superPartials.signature(customizedModel, customizedOptions);
 let output = superPartials.signature(customizedModel, customizedOptions);

 // If there are extra tags, split the output by the delimiter and do the work
 if (displayFunctionSignatureTag || paramExtensionTag) {
 let splitOutput = output.split(delimiter);

 if (displayFunctionSignatureTag) {
 // Change position of the 0 index and 2 index of the output
 // This way the function signature is below the description
 splitOutput = swap(splitOutput, 0, 2);
 }

 if (paramExtensionTag) {
 const stuff = this.helpers.getCommentParts(paramExtensionTag.content);

 // Find the index of the item that contains '## Returns'
 const index = splitOutput.findIndex(item => item.includes('## Returns'));

 // If the index is found, insert the stuff before it
 if (index !== -1) {
 splitOutput.splice(index, 0, stuff);
 }
 }

 // Join the output again
 output = splitOutput.join(delimiter);
 }

 return output;
 },
 /**
 * If `signature` has @displayFunctionSignature tag, the function will run `signatureTitle`. We want to use a completely custom code block here.
 * @param {import('typedoc').SignatureReflection} model
 * @param {{ accessor?: string; includeType?: boolean }} [options]
 * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/c83cff97b72ab25b224463ceec118c34e940cb8a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureTitle.ts
 */
 signatureTitle: (model, options) => {
 /**
 * @type {string[]}
 */
 const md = [];

 const keyword = this.helpers.getKeyword(model.parent.kind);

 if (this.helpers.isGroupKind(model.parent) && keyword) {
 md.push(keyword + ' ');
 }

 if (options?.accessor) {
 md.push(options?.accessor + ' ');
 }

 if (model.parent) {
 const flagsString = this.helpers.getReflectionFlags(model.parent?.flags);
 if (flagsString.length) {
 md.push(this.helpers.getReflectionFlags(model.parent.flags) + ' ');
 }
 }

 if (!['__call', '__type'].includes(model.name)) {
 /**
 * @type {string[]}
 */
 const name = [];
 if (model.kind === ReflectionKind.ConstructorSignature) {
 name.push('new');
 }
 name.push(escapeChars(model.name));
 md.push(name.join(' '));
 }

 if (model.typeParameters) {
 md.push(
 `${this.helpers.getAngleBracket('<')}${model.typeParameters
 .map(typeParameter => typeParameter.name)
 .join(', ')}${this.helpers.getAngleBracket('>')}`,
 );
 }

 md.push(this.partials.signatureParameters(model.parameters || []));

 if (model.type) {
 md.push(`: ${this.partials.someType(model.type)}`);
 }

 const result = md.join('');
 return codeBlock(result);
 },
 /**
 * This condenses the output if only a "simple" return type + `@returns` is given.
 * @param {import('typedoc').SignatureReflection} model
Expand DownExpand Up@@ -326,3 +415,78 @@ ${tabs}
 };
 }
}

/**
 * @param {string} str - The string to unescape
 */
function unEscapeChars(str) {
 return str
 .replace(/(`[^`]*?)\\*([^`]*?`)/g, (_match, p1, p2) => `${p1}${p2.replace(/\*/g, '\\*')}`)
 .replace(/\\\\/g, '\\')
 .replace(/(?<!\\)\*/g, '')
 .replace(/\\</g, '<')
 .replace(/\\>/g, '>')
 .replace(/&lt;/g, '<')
 .replace(/&gt;/g, '>')
 .replace(/\\_/g, '_')
 .replace(/\\{/g, '{')
 .replace(/\\}/g, '}')
 .replace(/``.*?``|(?<!\\)`/g, match => (match.startsWith('``') ? match : ''))
 .replace(/`` /g, '')
 .replace(/ ``/g, '')
 .replace(/\\`/g, '`')
 .replace(/\\\*/g, '*')
 .replace(/\\\|/g, '|')
 .replace(/\\\]/g, ']')
 .replace(/\\\[/g, '[')
 .replace(/\[([^[\]]*)\]\((.*?)\)/gm, '$1');
}

/**
 * @param {string} content
 */
function codeBlock(content) {
 /**
 * @param {string} content
 */
 const trimLastLine = content => {
 const lines = content.split('\n');
 return lines.map((line, index) => (index === lines.length - 1 ? line.trim() : line)).join('\n');
 };
 const trimmedContent =
 content.endsWith('}') || content.endsWith('};') || content.endsWith('>') || content.endsWith('>;')
 ? trimLastLine(content)
 : content;
 return '```ts\n' + unEscapeChars(trimmedContent) + '\n```';
}

/**
 * @param {string} str
 */
function escapeChars(str) {
 return str
 .replace(/>/g, '\\>')
 .replace(/</g, '\\<')
 .replace(/{/g, '\\{')
 .replace(/}/g, '\\}')
 .replace(/_/g, '\\_')
 .replace(/`/g, '\\`')
 .replace(/\|/g, '\\|')
 .replace(/\[/g, '\\[')
 .replace(/\]/g, '\\]')
 .replace(/\*/g, '\\*');
}

/**
 *
 * @param {string[]} arr
 * @param {number} i
 * @param {number} j
 * @returns
 */
function swap(arr, i, j) {
 let t = arr[i];
 arr[i] = arr[j];
 arr[j] = t;
 return arr;
}

5 changes: 4 additions & 1 deletion
eslint.config.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -432,7 +432,10 @@ export default tseslint.config([
 ...pluginJsDoc.configs['flat/recommended-typescript'].rules,
 'jsdoc/check-examples': 'off',
 'jsdoc/informative-docs': 'warn',
 'jsdoc/check-tag-names': ['warn', { definedTags: ['inline', 'unionReturnHeadings'], typed: false }],
 'jsdoc/check-tag-names': [
 'warn',
 { definedTags: ['inline', 'unionReturnHeadings', 'displayFunctionSignature', 'paramExtension'], typed: false },
 ],
 'jsdoc/require-hyphen-before-param-description': 'warn',
 'jsdoc/require-description': 'warn',
 'jsdoc/require-description-complete-sentence': 'warn',
Expand Down

6 changes: 4 additions & 2 deletions
packages/backend/src/tokens/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ export type AuthenticateRequestOptions = {
 acceptsToken?: TokenType | TokenType[] | 'any';
} & VerifyTokenOptions;

/**
 * @inline
 */
export type OrganizationSyncOptions = {
 /**
 * Specifies URL patterns that are organization-specific, containing an organization ID or slug as a path parameter. If a request matches this path, the organization identifier will be used to set that org as active.
Expand All@@ -68,8 +71,7 @@ export type OrganizationSyncOptions = {
 *
 * Patterns must have a path parameter named either `:id` (to match a Clerk organization ID) or `:slug` (to match a Clerk organization slug).
 *
 * > [!WARNING]
 * > If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
 * If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
 *
 * @example
 * ["/orgs/:slug", "/orgs/:slug/(.*)"]
Expand Down

13 changes: 13 additions & 0 deletions
packages/backend/src/tokens/verify.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -39,6 +39,19 @@ export type VerifyTokenOptions = Omit<VerifyJwtOptions, 'key'> &
 * @param token - The token to verify.
 * @param options - Options for verifying the token.
 *
 * @displayFunctionSignature
 *
 * @paramExtension
 *
 * ### `VerifyTokenOptions`
 *
 * It is recommended to set these options as [environment variables](/docs/deployments/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })`.
 *
 * > [!WARNING]
 * You must provide either `jwtKey` or `secretKey`.
 *
 * <Typedoc src="backend/verify-token-options" />
 *
 * @example
 *
 * The following example demonstrates how to use the [JavaScript Backend SDK](https://clerk.com/docs/references/backend/overview) to verify the token signature.
Expand Down

2 changes: 2 additions & 0 deletions
packages/backend/src/webhooks.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,8 @@ export * from './api/resources/Webhooks';
 * @param request - The request object.
 * @param options - Optional configuration object.
 *
 * @displayFunctionSignature
 *
 * @example
 * See the [guide on syncing data](https://clerk.com/docs/webhooks/sync-data) for more comprehensive and framework-specific examples that you can copy and paste into your app.
 *
Expand Down

6 changes: 3 additions & 3 deletions
typedoc.config.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@ import fs from 'node:fs';
import { OptionDefaults } from 'typedoc';

const IGNORE_LIST = ['.DS_Store', 'dev-cli', 'expo-passkeys', 'testing', 'themes', 'upgrade'];
const CUSTOM_TAGS = ['@unionReturnHeadings'];
const CUSTOM_BLOCK_TAGS = ['@unionReturnHeadings', '@displayFunctionSignature', '@paramExtension'];

/**
 * Return an array of relative paths to all folders in the "packages" folder to be used for the "entryPoints" option.
Expand DownExpand Up@@ -90,7 +90,7 @@ const config = {
 theme: 'clerkTheme',
 router: 'clerk-router',
 readme: 'none',
 notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_TAGS],
 notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_BLOCK_TAGS],
 packageOptions: {
 includeVersion: false,
 excludePrivate: true,
Expand All@@ -100,7 +100,7 @@ const config = {
 excludeInternal: true,
 excludeNotDocumented: true,
 gitRevision: 'main',
 blockTags: [...OptionDefaults.blockTags, ...CUSTOM_TAGS],
 blockTags: [...OptionDefaults.blockTags, ...CUSTOM_BLOCK_TAGS],
 modifierTags: [...OptionDefaults.modifierTags],
 exclude: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
 readme: 'none',
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
fix(backend): JSDoc for verifyWebook & verifyToken#6060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

LekoArts
merged 4 commits into

from

Jun 4, 2025
 Merged


fix(backend): JSDoc for verifyWebook & verifyToken#6060
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
789c65b

verifyToken & verifyWebhook


LekoArts Jun 4, 2025
15ae059

add changeset


LekoArts Jun 4, 2025
4e7f16f

update types


LekoArts Jun 4, 2025
d1b452a

update snapshot


LekoArts Jun 4, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/six-lions-wear.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/backend': patch
---

Improve JSDoc comments for verifyWebhook and verifyToken

1 change: 1 addition & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -157,6 +157,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "backend/organization-invitation.mdx",
 "backend/organization-membership-public-user-data.mdx",
 "backend/organization-membership.mdx",
 "backend/organization-sync-options.mdx",
 "backend/organization-sync-target.mdx",
 "backend/organization.mdx",
 "backend/paginated-resource-response.mdx",
Expand Down

1 change: 1 addition & 0 deletions
.typedoc/custom-plugin.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,7 @@ const LINK_REPLACEMENTS = [
 ['phone-number', '/docs/references/backend/types/backend-phone-number'],
 ['saml-account', '/docs/references/backend/types/backend-saml-account'],
 ['web3-wallet', '/docs/references/backend/types/backend-web3-wallet'],
 ['verify-token-options', '#verify-token-options'],
];

/**
Expand Down

172 changes: 168 additions & 4 deletions
.typedoc/custom-theme.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
// @ts-check
import { ReflectionType, UnionType } from 'typedoc';
import { ReflectionKind, ReflectionType, UnionType } from 'typedoc';
import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';

/**
Expand DownExpand Up@@ -47,22 +47,111 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 this.partials = {
 ...superPartials,
 /**
 * This hides the "Type parameters" section and the signature title from the output
 * This hides the "Type parameters" section and the signature title from the output (by default). Shows the signature title if the `@displayFunctionSignature` tag is present.
 * @param {import('typedoc').SignatureReflection} model
 * @param {{ headingLevel: number, nested?: boolean, accessor?: string, multipleSignatures?: boolean; hideTitle?: boolean }} options
 */
 signature: (model, options) => {
 const displayFunctionSignatureTag = model.comment?.getTag('@displayFunctionSignature');
 const paramExtensionTag = model.comment?.getTag('@paramExtension');
 const delimiter = '\n\n';

 const customizedOptions = {
 ...options,
 hideTitle: true,
 // Hide the title by default, only show it if the `@displayFunctionSignature` tag is present
 hideTitle: !displayFunctionSignatureTag,
 };
 const customizedModel = model;
 customizedModel.typeParameters = undefined;

 const output = superPartials.signature(customizedModel, customizedOptions);
 let output = superPartials.signature(customizedModel, customizedOptions);

 // If there are extra tags, split the output by the delimiter and do the work
 if (displayFunctionSignatureTag || paramExtensionTag) {
 let splitOutput = output.split(delimiter);

 if (displayFunctionSignatureTag) {
 // Change position of the 0 index and 2 index of the output
 // This way the function signature is below the description
 splitOutput = swap(splitOutput, 0, 2);
 }

 if (paramExtensionTag) {
 const stuff = this.helpers.getCommentParts(paramExtensionTag.content);

 // Find the index of the item that contains '## Returns'
 const index = splitOutput.findIndex(item => item.includes('## Returns'));

 // If the index is found, insert the stuff before it
 if (index !== -1) {
 splitOutput.splice(index, 0, stuff);
 }
 }

 // Join the output again
 output = splitOutput.join(delimiter);
 }

 return output;
 },
 /**
 * If `signature` has @displayFunctionSignature tag, the function will run `signatureTitle`. We want to use a completely custom code block here.
 * @param {import('typedoc').SignatureReflection} model
 * @param {{ accessor?: string; includeType?: boolean }} [options]
 * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/c83cff97b72ab25b224463ceec118c34e940cb8a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureTitle.ts
 */
 signatureTitle: (model, options) => {
 /**
 * @type {string[]}
 */
 const md = [];

 const keyword = this.helpers.getKeyword(model.parent.kind);

 if (this.helpers.isGroupKind(model.parent) && keyword) {
 md.push(keyword + ' ');
 }

 if (options?.accessor) {
 md.push(options?.accessor + ' ');
 }

 if (model.parent) {
 const flagsString = this.helpers.getReflectionFlags(model.parent?.flags);
 if (flagsString.length) {
 md.push(this.helpers.getReflectionFlags(model.parent.flags) + ' ');
 }
 }

 if (!['__call', '__type'].includes(model.name)) {
 /**
 * @type {string[]}
 */
 const name = [];
 if (model.kind === ReflectionKind.ConstructorSignature) {
 name.push('new');
 }
 name.push(escapeChars(model.name));
 md.push(name.join(' '));
 }

 if (model.typeParameters) {
 md.push(
 `${this.helpers.getAngleBracket('<')}${model.typeParameters
 .map(typeParameter => typeParameter.name)
 .join(', ')}${this.helpers.getAngleBracket('>')}`,
 );
 }

 md.push(this.partials.signatureParameters(model.parameters || []));

 if (model.type) {
 md.push(`: ${this.partials.someType(model.type)}`);
 }

 const result = md.join('');
 return codeBlock(result);
 },
 /**
 * This condenses the output if only a "simple" return type + `@returns` is given.
 * @param {import('typedoc').SignatureReflection} model
Expand DownExpand Up@@ -326,3 +415,78 @@ ${tabs}
 };
 }
}

/**
 * @param {string} str - The string to unescape
 */
function unEscapeChars(str) {
 return str
 .replace(/(`[^`]*?)\\*([^`]*?`)/g, (_match, p1, p2) => `${p1}${p2.replace(/\*/g, '\\*')}`)
 .replace(/\\\\/g, '\\')
 .replace(/(?<!\\)\*/g, '')
 .replace(/\\</g, '<')
 .replace(/\\>/g, '>')
 .replace(/&lt;/g, '<')
 .replace(/&gt;/g, '>')
 .replace(/\\_/g, '_')
 .replace(/\\{/g, '{')
 .replace(/\\}/g, '}')
 .replace(/``.*?``|(?<!\\)`/g, match => (match.startsWith('``') ? match : ''))
 .replace(/`` /g, '')
 .replace(/ ``/g, '')
 .replace(/\\`/g, '`')
 .replace(/\\\*/g, '*')
 .replace(/\\\|/g, '|')
 .replace(/\\\]/g, ']')
 .replace(/\\\[/g, '[')
 .replace(/\[([^[\]]*)\]\((.*?)\)/gm, '$1');
}

/**
 * @param {string} content
 */
function codeBlock(content) {
 /**
 * @param {string} content
 */
 const trimLastLine = content => {
 const lines = content.split('\n');
 return lines.map((line, index) => (index === lines.length - 1 ? line.trim() : line)).join('\n');
 };
 const trimmedContent =
 content.endsWith('}') || content.endsWith('};') || content.endsWith('>') || content.endsWith('>;')
 ? trimLastLine(content)
 : content;
 return '```ts\n' + unEscapeChars(trimmedContent) + '\n```';
}

/**
 * @param {string} str
 */
function escapeChars(str) {
 return str
 .replace(/>/g, '\\>')
 .replace(/</g, '\\<')
 .replace(/{/g, '\\{')
 .replace(/}/g, '\\}')
 .replace(/_/g, '\\_')
 .replace(/`/g, '\\`')
 .replace(/\|/g, '\\|')
 .replace(/\[/g, '\\[')
 .replace(/\]/g, '\\]')
 .replace(/\*/g, '\\*');
}

/**
 *
 * @param {string[]} arr
 * @param {number} i
 * @param {number} j
 * @returns
 */
function swap(arr, i, j) {
 let t = arr[i];
 arr[i] = arr[j];
 arr[j] = t;
 return arr;
}

5 changes: 4 additions & 1 deletion
eslint.config.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -432,7 +432,10 @@ export default tseslint.config([
 ...pluginJsDoc.configs['flat/recommended-typescript'].rules,
 'jsdoc/check-examples': 'off',
 'jsdoc/informative-docs': 'warn',
 'jsdoc/check-tag-names': ['warn', { definedTags: ['inline', 'unionReturnHeadings'], typed: false }],
 'jsdoc/check-tag-names': [
 'warn',
 { definedTags: ['inline', 'unionReturnHeadings', 'displayFunctionSignature', 'paramExtension'], typed: false },
 ],
 'jsdoc/require-hyphen-before-param-description': 'warn',
 'jsdoc/require-description': 'warn',
 'jsdoc/require-description-complete-sentence': 'warn',
Expand Down

6 changes: 4 additions & 2 deletions
packages/backend/src/tokens/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ export type AuthenticateRequestOptions = {
 acceptsToken?: TokenType | TokenType[] | 'any';
} & VerifyTokenOptions;

/**
 * @inline
 */
export type OrganizationSyncOptions = {
 /**
 * Specifies URL patterns that are organization-specific, containing an organization ID or slug as a path parameter. If a request matches this path, the organization identifier will be used to set that org as active.
Expand All@@ -68,8 +71,7 @@ export type OrganizationSyncOptions = {
 *
 * Patterns must have a path parameter named either `:id` (to match a Clerk organization ID) or `:slug` (to match a Clerk organization slug).
 *
 * > [!WARNING]
 * > If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
 * If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
 *
 * @example
 * ["/orgs/:slug", "/orgs/:slug/(.*)"]
Expand Down

13 changes: 13 additions & 0 deletions
packages/backend/src/tokens/verify.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -39,6 +39,19 @@ export type VerifyTokenOptions = Omit<VerifyJwtOptions, 'key'> &
 * @param token - The token to verify.
 * @param options - Options for verifying the token.
 *
 * @displayFunctionSignature
 *
 * @paramExtension
 *
 * ### `VerifyTokenOptions`
 *
 * It is recommended to set these options as [environment variables](/docs/deployments/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })`.
 *
 * > [!WARNING]
 * You must provide either `jwtKey` or `secretKey`.
 *
 * <Typedoc src="backend/verify-token-options" />
 *
 * @example
 *
 * The following example demonstrates how to use the [JavaScript Backend SDK](https://clerk.com/docs/references/backend/overview) to verify the token signature.
Expand Down

2 changes: 2 additions & 0 deletions
packages/backend/src/webhooks.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,8 @@ export * from './api/resources/Webhooks';
 * @param request - The request object.
 * @param options - Optional configuration object.
 *
 * @displayFunctionSignature
 *
 * @example
 * See the [guide on syncing data](https://clerk.com/docs/webhooks/sync-data) for more comprehensive and framework-specific examples that you can copy and paste into your app.
 *
Expand Down

6 changes: 3 additions & 3 deletions
typedoc.config.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,7 @@ import fs from 'node:fs';
import { OptionDefaults } from 'typedoc';

const IGNORE_LIST = ['.DS_Store', 'dev-cli', 'expo-passkeys', 'testing', 'themes', 'upgrade'];
const CUSTOM_TAGS = ['@unionReturnHeadings'];
const CUSTOM_BLOCK_TAGS = ['@unionReturnHeadings', '@displayFunctionSignature', '@paramExtension'];

/**
 * Return an array of relative paths to all folders in the "packages" folder to be used for the "entryPoints" option.
Expand DownExpand Up@@ -90,7 +90,7 @@ const config = {
 theme: 'clerkTheme',
 router: 'clerk-router',
 readme: 'none',
 notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_TAGS],
 notRenderedTags: [...OptionDefaults.notRenderedTags, ...CUSTOM_BLOCK_TAGS],
 packageOptions: {
 includeVersion: false,
 excludePrivate: true,
Expand All@@ -100,7 +100,7 @@ const config = {
 excludeInternal: true,
 excludeNotDocumented: true,
 gitRevision: 'main',
 blockTags: [...OptionDefaults.blockTags, ...CUSTOM_TAGS],
 blockTags: [...OptionDefaults.blockTags, ...CUSTOM_BLOCK_TAGS],
 modifierTags: [...OptionDefaults.modifierTags],
 exclude: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
 readme: 'none',
Expand Down