diff --git a/.changeset/docs-backend-typedoc.md b/.changeset/docs-backend-typedoc.md new file mode 100644 index 00000000000..a845151cc84 --- /dev/null +++ b/.changeset/docs-backend-typedoc.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/.typedoc/__tests__/__snapshots__/clerk-properties.mdx b/.typedoc/__tests__/__snapshots__/clerk-properties.mdx index 0960bc01e54..571d450cf7a 100644 --- a/.typedoc/__tests__/__snapshots__/clerk-properties.mdx +++ b/.typedoc/__tests__/__snapshots__/clerk-properties.mdx @@ -14,9 +14,14 @@ | `proxyUrl` | undefined \| string | **Required for applications that run behind a reverse proxy**. Your Clerk app's proxy URL. Can be either a relative path (`/__clerk`) or a full URL (`https:///__clerk`). | | `publishableKey` | `string` | Your Clerk [Publishable Key](!publishable-key). | | `sdkMetadata` | undefined \| \{ environment?: string; name: string; version: string; \} | If present, contains information about the SDK that the host application is using. For example, if Clerk is loaded through `@clerk/nextjs`, this would be `{ name: '@clerk/nextjs', version: '1.0.0' }`. You don't need to set this value yourself unless you're [developing an SDK](/docs/guides/development/sdk-development/overview). | +| `sdkMetadata.environment?` | `string` | Typically this will be the `NODE_ENV` that the SDK is currently running in. | +| `sdkMetadata.name` | `string` | The npm package name of the SDK. | +| `sdkMetadata.version` | `string` | The npm package version of the SDK. | | `session` | undefined \| null \| [SignedInSessionResource](/docs/reference/objects/session) | The currently active `Session`, which is guaranteed to be one of the sessions in `Client.sessions`. If there is no active session, this field will be `null`. If the session is loading, this field will be `undefined`. | | `status` | "error" \| "degraded" \| "loading" \| "ready" | The status of the `Clerk` instance. Possible values are: | | `telemetry` | undefined \| \{ isDebug: boolean; isEnabled: boolean; record: void; recordLog: void; \} | [Telemetry](/docs/guides/how-clerk-works/security/clerk-telemetry) configuration. | +| `telemetry.isDebug` | `boolean` | If `true`, telemetry events are only logged to the console and not sent to Clerk. | +| `telemetry.isEnabled` | `boolean` | Indicates whether telemetry is enabled. | | `uiVersion` | undefined \| string | The version of `@clerk/ui` that is currently loaded, or `undefined` if the prebuilt UI has not been loaded yet. | | `user` | undefined \| null \| [UserResource](/docs/reference/objects/user) | A shortcut to `Session.user` which holds the currently active `User` object. If the session is `null` or `undefined`, the user field will match. | | `version` | undefined \| string | The Clerk SDK version number. | diff --git a/.typedoc/__tests__/__snapshots__/sign-in-future-resource-methods-email-link.mdx b/.typedoc/__tests__/__snapshots__/sign-in-future-resource-methods-email-link.mdx index b2f588fd6fb..6da4d83340c 100644 --- a/.typedoc/__tests__/__snapshots__/sign-in-future-resource-methods-email-link.mdx +++ b/.typedoc/__tests__/__snapshots__/sign-in-future-resource-methods-email-link.mdx @@ -4,3 +4,6 @@ | Property | Type | Description | | ------ | ------ | ------ | | `verification` | null \| \{ createdSessionId: string; status: "expired" \| "failed" \| "verified" \| "client_mismatch"; verifiedFromTheSameClient: boolean; \} | The verification status of the email link. This property is populated by reading query parameters from the URL after the user visits the email link. Returns `null` if no verification status is available. | +| `verification.createdSessionId` | `string` | The ID of the session that was created upon completion of the current sign-in. | +| `verification.status` | "expired" \| "failed" \| "verified" \| "client_mismatch" | The verification status. | +| `verification.verifiedFromTheSameClient` | `boolean` | Whether the verification was from the same client. | diff --git a/.typedoc/__tests__/file-structure.test.ts b/.typedoc/__tests__/file-structure.test.ts index 5aca0e62a03..af306bbe658 100644 --- a/.typedoc/__tests__/file-structure.test.ts +++ b/.typedoc/__tests__/file-structure.test.ts @@ -48,6 +48,48 @@ describe('Typedoc output', () => { expect(nestedFolders).toMatchInlineSnapshot(` [ + "backend/agent-task-api", + "backend/agent-task-api/methods", + "backend/allowlist-identifier-api", + "backend/allowlist-identifier-api/methods", + "backend/api-keys-api", + "backend/api-keys-api/methods", + "backend/billing-api", + "backend/billing-api/methods", + "backend/client-api", + "backend/client-api/methods", + "backend/domain-api", + "backend/domain-api/methods", + "backend/email-address-api", + "backend/email-address-api/methods", + "backend/enterprise-connection-api", + "backend/enterprise-connection-api/methods", + "backend/instance-api", + "backend/instance-api/methods", + "backend/invitation-api", + "backend/invitation-api/methods", + "backend/m2-m-token-api", + "backend/m2-m-token-api/methods", + "backend/machine-api", + "backend/machine-api/methods", + "backend/o-auth-applications-api", + "backend/o-auth-applications-api/methods", + "backend/organization-api", + "backend/organization-api/methods", + "backend/phone-number-api", + "backend/phone-number-api/methods", + "backend/redirect-url-api", + "backend/redirect-url-api/methods", + "backend/session-api", + "backend/session-api/methods", + "backend/sign-in-token-api", + "backend/sign-in-token-api/methods", + "backend/testing-token-api", + "backend/testing-token-api/methods", + "backend/user-api", + "backend/user-api/methods", + "backend/waitlist-entry-api", + "backend/waitlist-entry-api/methods", "react/legacy", "shared/api-key-resource", "shared/api-key-resource/methods", diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs index 53c3e1609b0..53d3b774ce3 100644 --- a/.typedoc/custom-plugin.mjs +++ b/.typedoc/custom-plugin.mjs @@ -1,5 +1,5 @@ // @ts-check - Enable TypeScript checks for safer MDX post-processing and link rewriting -import { Converter } from 'typedoc'; +import { Converter, DeclarationReflection, ReflectionKind, ReflectionType, RendererEvent } from 'typedoc'; import { MarkdownPageEvent } from 'typedoc-plugin-markdown'; /** @@ -75,6 +75,7 @@ const LINK_REPLACEMENTS = [ ['o-auth-consent-info', '/docs/reference/types/oauth-consent-info'], ['o-auth-consent-scope', '/docs/reference/types/oauth-consent-scope'], ['o-auth-strategy', '/docs/reference/types/sso#o-auth-strategy'], + ['o-auth-provider', '/docs/reference/types/sso#o-auth-provider'], ['session', '/docs/reference/backend/types/backend-session'], ['session-activity', '/docs/reference/backend/types/backend-session-activity'], ['organization', '/docs/reference/backend/types/backend-organization'], @@ -101,6 +102,7 @@ const LINK_REPLACEMENTS = [ ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#parameters'], ['billing-payment-method-resource', '/docs/reference/types/billing-payment-method-resource'], ['billing-payer-resource', '/docs/reference/types/billing-payer-resource'], + ['billing-plan-price', '/docs/reference/types/billing-plan-price'], ['billing-plan-resource', '/docs/reference/types/billing-plan-resource'], ['billing-plan-unit-price', '/docs/reference/types/billing-plan-unit-price'], ['billing-plan-unit-price-tier', '/docs/reference/types/billing-plan-unit-price-tier'], @@ -130,6 +132,10 @@ const LINK_REPLACEMENTS = [ ['session-task', '/docs/reference/types/session-task'], ['public-user-data', '/docs/reference/types/public-user-data'], ['session-status', '/docs/reference/types/session-status'], + [ + 'create-organization-invitation-params', + '/docs/reference/backend/organization/create-organization-invitation#create-organization-invitation-params', + ], ['create-organization-domain-params', '#create-organization-domain-params'], ['organization-domain-verification', '/docs/reference/types/organization-domain-resource'], ]; @@ -215,6 +221,10 @@ function getCatchAllReplacements() { pattern: /(?` instantiation pattern where typedoc otherwise loses the generic parameter at the alias boundary. + * + * @param {import('typedoc').SomeType | undefined} type + * @param {Map} reflectionsByName lookup for cross-package refs whose `.reflection` is not linked + * @returns {import('typedoc').DeclarationReflection[]} + */ +function collectPropertiesFromType(type, reflectionsByName) { + if (!type) return []; + if (type.type === 'reflection') { + return type.declaration?.children ?? []; + } + if (type.type === 'intersection') { + return type.types.flatMap(t => collectPropertiesFromType(t, reflectionsByName)); + } + if (type.type === 'reference') { + const target = type.reflection ?? reflectionsByName.get(type.name); + const targetChildren = target?.children ?? []; + const argChildren = (type.typeArguments ?? []).flatMap(t => collectPropertiesFromType(t, reflectionsByName)); + return [...targetChildren, ...argChildren]; + } + return []; +} + /** * @param {import('typedoc-plugin-markdown').MarkdownApplication} app */ @@ -483,6 +524,49 @@ export function load(app) { } }); + /** + * Flatten the `Foo<{...}>` generic-instantiation pattern into a single merged properties table when `Foo` opts in via `@expandProperties`. typedoc-plugin-markdown would otherwise render an empty page for these aliases because the resolved type is a `ReferenceType` with no inline declaration — see `member.declaration.js` in the plugin, which only walks `IntersectionType` sub-types and has no branch for top-level `ReferenceType`. + * + * Runs at `RendererEvent.BEGIN` rather than `EVENT_RESOLVE_END` because the resolve hook fires per package, and cross-package references (e.g. `@clerk/backend` types referencing `ClerkPaginationRequest` from `@clerk/shared`) only link up after typedoc merges packages. + * + * The opt-in tag lives on the wrapper type so we never accidentally flatten unrelated generic aliases (e.g. `SignInErrors = Errors`). + */ + app.renderer.on(RendererEvent.BEGIN, event => { + const all = Object.values(event.project.reflections); + const reflectionsByName = new Map(); + for (const r of all) { + if (r.name && !reflectionsByName.has(r.name)) reflectionsByName.set(r.name, r); + } + const expandable = new Set(); + for (const r of all) { + if (r.comment?.modifierTags?.has('@expandProperties')) { + expandable.add(r); + r.comment.modifierTags.delete('@expandProperties'); + } + } + for (const reflection of all) { + if ( + reflection.kindOf?.(ReflectionKind.TypeAlias) && + reflection.type?.type === 'reference' && + Array.isArray(reflection.type.typeArguments) && + reflection.type.typeArguments.length > 0 + ) { + const target = reflection.type.reflection ?? reflectionsByName.get(reflection.type.name); + if (!target || !expandable.has(target)) continue; + const merged = collectPropertiesFromType(reflection.type, reflectionsByName); + if (merged.length > 0) { + // typedoc's package-level `sort: 'alphabetical'` is applied during conversion, before + // our synthetic merge runs. Sort here to match the alphabetical ordering used by + // every other table in the docs. + merged.sort((a, b) => a.name.localeCompare(b.name)); + const decl = new DeclarationReflection('__type', ReflectionKind.TypeLiteral, reflection); + decl.children = merged; + reflection.type = new ReflectionType(decl); + } + } + } + }); + app.renderer.on(MarkdownPageEvent.END, output => { const fileName = output.url.split('/').pop(); diff --git a/.typedoc/custom-theme.mjs b/.typedoc/custom-theme.mjs index dc06bc65608..c2c0d1c79c3 100644 --- a/.typedoc/custom-theme.mjs +++ b/.typedoc/custom-theme.mjs @@ -670,6 +670,91 @@ function renderPropertiesFormatTable(args) { : table(args.headers, args.rows, leftAlignHeadings); } +/** + * Resolve a property's type to the `@inline` class/interface declaration it ultimately points at, or `undefined` if the type isn't (or doesn't unwrap to) one. Unwraps `OptionalType`, `ArrayType`, and a union arm — covers `T | null` / `T | undefined` / `T[]`. Used to decide whether to expand nested rows for a property whose type is rendered inline as `\{ … \}`. + * + * Union-arm reflection: when TypeDoc has already inlined a `@inline` reference inside a union (`PublicOrganizationDataJSON | null` → `ReflectionType | null`), the arm shows up as a `ReflectionType` carrying the synthesized `TypeLiteral` declaration. Match those too so the children expand the same way a bare `ReferenceType` arm would. + * + * Array element: `errors: Foo[]` where `Foo` is `@inline` should expand the same as `errors: Foo` — readers want to see the element shape per row. Unwrap `ArrayType.elementType` (which, like the union arm, may have already been collapsed by TypeDoc to a `ReflectionType`) before the reference/reflection checks. + * + * Direct (non-array, non-union) `ReflectionType` is intentionally NOT handled here — typedoc-plugin-markdown's `getFlattenedDeclarations` already flattens that case in `propertiesTable`, and double-handling would produce duplicate child rows. The flag `viaContainer` records whether we passed through an array/union (where `getFlattenedDeclarations` does NOT walk further), so the final `ReflectionType` check only fires in that case. + * + * @param {import('typedoc').Type | undefined} t + */ +function getInlineClassOrInterfaceTarget(t) { + let bare = /** @type {import('typedoc').Type | undefined} */ (unwrapOptional(t)); + let viaContainer = false; + if (bare?.type === 'array') { + bare = /** @type {import('typedoc').ArrayType} */ (bare).elementType; + viaContainer = true; + } + if (bare && bare.type === 'union') { + viaContainer = true; + const u = /** @type {import('typedoc').UnionType} */ (bare); + bare = u.types.find(arm => { + if (arm.type === 'reference') { + const refl = /** @type {import('typedoc').ReferenceType} */ (arm).reflection; + if (!refl || !isInlineModifierWithoutStandalonePage(refl)) return false; + return ( + /** @type {{ kindOf?: (k: number) => boolean }} */ (refl).kindOf?.(ReflectionKind.Class) || + /** @type {{ kindOf?: (k: number) => boolean }} */ (refl).kindOf?.(ReflectionKind.Interface) + ); + } + if (arm.type === 'reflection') { + const d = /** @type {import('typedoc').ReflectionType} */ (arm).declaration; + return Boolean(d?.children?.some(c => c.kindOf(ReflectionKind.Property))); + } + return false; + }); + } + if (viaContainer && bare?.type === 'reflection') { + const d = /** @type {import('typedoc').ReflectionType} */ (bare).declaration; + if (!d?.children?.some(c => c.kindOf(ReflectionKind.Property))) return undefined; + return d; + } + if (!bare || bare.type !== 'reference') return undefined; + const decl = /** @type {import('typedoc').ReferenceType} */ (bare).reflection; + if (!decl) return undefined; + if (!isInlineModifierWithoutStandalonePage(decl)) return undefined; + const d = /** @type {import('typedoc').DeclarationReflection} */ (decl); + if (!d.kindOf(ReflectionKind.Class) && !d.kindOf(ReflectionKind.Interface)) return undefined; + return d; +} + +/** + * Append synthesized `parent.child` rows after each property whose type is an `@inline` class or interface (or `null | InlineClass`). Mirrors {@link appendUnionObjectChildPropertyRows} — the synthesized reflection inherits the child's `flags.isOptional` so the renderer appends `?` on its own, and uses `?.` as the separator when the parent is optional. + * + * @template {import('typedoc').DeclarationReflection} T + * @param {T[]} base + * @returns {T[]} + */ +function appendInlineObjectChildPropertyRows(base) { + /** @type {T[]} */ + const out = []; + for (const prop of base) { + out.push(prop); + if (prop.name.includes('.')) continue; + const target = getInlineClassOrInterfaceTarget(prop.type); + if (!target) continue; + const children = target.children?.filter(c => c.kindOf(ReflectionKind.Property)); + if (!children?.length) continue; + const sep = prop.flags?.isOptional ? '?.' : '.'; + for (const child of children) { + out.push( + /** @type {T} */ ( + /** @type {unknown} */ ({ + ...child, + name: `${prop.name}${sep}${child.name}`, + getFullName: () => prop.getFullName(), + getFriendlyFullName: () => prop.getFriendlyFullName(), + }) + ), + ); + } + } + return out; +} + /** * Same logic as typedoc-plugin-markdown `member.typeDeclarationTable`, but **always** runs `getFlattenedDeclarations` and then {@link appendUnionObjectChildPropertyRows} (union-object arm rows like `telemetry.*`). The default plugin skips flattening in `compact` mode, which hides nested keys like `telemetry.disabled`. * @@ -1105,6 +1190,20 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext { if (decl.kindOf(ReflectionKind.TypeAlias) && decl.type) { return removeLineBreaks(this.partials.someType(decl.type)); } + // Class or interface: there's no RHS to render, but the declaration's children describe the instance shape. Inline as a type-literal `\{ key: type; … \}` so use sites surface the same fields readers would see on the standalone page. Curly braces are escaped because MDX otherwise parses the literal as a JSX expression (and the object-literal bodies we emit aren't valid JS expressions). + if ((decl.kindOf(ReflectionKind.Class) || decl.kindOf(ReflectionKind.Interface)) && decl.children?.length) { + const props = decl.children.filter(c => c.kindOf(ReflectionKind.Property)); + if (props.length) { + const fields = props + .map(p => { + const sep = p.flags?.isOptional ? '?:' : ':'; + const typeMd = p.type ? this.partials.someType(p.type) : '`unknown`'; + return `${p.name}${sep} ${typeMd};`; + }) + .join(' '); + return removeLineBreaks(`\\{ ${fields} \\}`); + } + } return backTicks(decl.name); } return superPartials.referenceType.call(this, model); @@ -1128,7 +1227,8 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext { prop => !isCallableInterfaceProperty(prop, this.helpers) && !prop.comment?.hasModifier('@extractMethods'), ) : model; - return superPartials.propertiesTable(filtered, options); + const expanded = appendInlineObjectChildPropertyRows(filtered); + return superPartials.propertiesTable(expanded, options); }, /** * Parameter tables: same as the stock partial except single-property inline object params are not expanded to nested rows. diff --git a/.typedoc/extract-methods.mjs b/.typedoc/extract-methods.mjs index 138a388fa9d..731606fcd42 100644 --- a/.typedoc/extract-methods.mjs +++ b/.typedoc/extract-methods.mjs @@ -35,7 +35,20 @@ import { } from './custom-plugin.mjs'; import { isCallableInterfaceProperty } from './custom-theme.mjs'; import { removeLineBreaks } from './markdown-helpers.mjs'; -import { REFERENCE_OBJECT_CONFIG } from './reference-objects.mjs'; +import { BACKEND_API_CONFIG, REFERENCE_OBJECT_CONFIG } from './reference-objects.mjs'; + +/** + * `'reference'` (default): each `methods/.mdx` opens with `### foo()` and uses an H4 `#### Parameters` heading — matches the reference-object pages that aggregate many methods. + * `'page'`: skip the method-name title and use an H2 `## Parameters` heading — for one-method-per-docs-page surfaces, like the backend API endpoints. + * @typedef {'reference' | 'page'} MethodFormat + */ + +/** @param {string} pageUrl */ +function methodFormatForPageUrl(pageUrl) { + return pageUrl in BACKEND_API_CONFIG + ? /** @type {MethodFormat} */ ('page') + : /** @type {MethodFormat} */ ('reference'); +} import { toFileSlug } from './slug.mjs'; import { isInlineModifierWithoutStandalonePage } from './standalone-page-tag.mjs'; import { unwrapOptional } from './type-utils.mjs'; @@ -87,6 +100,21 @@ function codeDisplayPartToMarkdown(text) { return `\`${text}\``; } +/** + * Build the description cell for a nested `param.field` row: summary text plus a leading `**Deprecated.**` marker (with the `@deprecated` tag's body) when that tag is present. Matches what typedoc-plugin-markdown's `parseParams` emits for inline `{ … }` params — fields documented only via `@deprecated` (no summary) otherwise rendered as `—` here, hiding important guidance. + * Returns `'—'` when both summary and `@deprecated` are empty. + * + * @param {import('typedoc').Comment | undefined} comment + */ +function renderNestedRowDescription(comment) { + const summaryText = comment?.summary?.length ? displayPartsToString(comment.summary).trim() : ''; + const deprecatedTag = comment?.blockTags?.find(t => t.tag === '@deprecated'); + const deprecatedText = deprecatedTag ? displayPartsToString(deprecatedTag.content).trim() : ''; + const deprecatedMd = deprecatedTag ? `**Deprecated.**${deprecatedText ? ` ${deprecatedText}` : ''}` : ''; + const combined = [summaryText, deprecatedMd].filter(Boolean).join(' '); + return combined || '—'; +} + /** * @param {import('typedoc').CommentDisplayPart[] | undefined} parts */ @@ -220,13 +248,52 @@ function getCallSignatureFromType(t, visitedReflectionIds) { return undefined; } +/** + * @param {import('typedoc').SignatureReflection} sig + */ +function signatureIsDeprecated(sig) { + const c = sig.comment; + if (!c) return false; + if (typeof c.hasModifier === 'function' && c.hasModifier('@deprecated')) return true; + return c.blockTags?.some(t => t.tag === '@deprecated') ?? false; +} + +/** + * typedoc maps `@param paramName description` to `parameter.comment` during conversion of the + * signature that physically owns the JSDoc. With overloads + an implementation, the impl's `@param` + * tags don't transfer to overload parameters — even when typedoc copies the impl's comment onto + * each overload's `sig.comment.blockTags`. Without descriptions on `param.comment`, typedoc-plugin-markdown + * drops the Description column from the parameters table. + * + * Overlay missing parameter comments from any matching `@param` block tag on the signature comment + * so the rendered table shows the descriptions the author wrote on the implementation's JSDoc. + * + * @param {import('typedoc').SignatureReflection} sig + */ +function overlayParamCommentsFromSignatureBlockTags(sig) { + const params = sig.parameters; + if (!params?.length) return; + const blockTags = sig.comment?.blockTags; + if (!blockTags?.length) return; + for (const p of params) { + if (p.comment?.summary?.length) continue; + const tag = blockTags.find(t => t.tag === '@param' && t.name === p.name); + if (!tag?.content?.length) continue; + p.comment = new Comment(tag.content); + } +} + /** * @param {import('typedoc').DeclarationReflection} decl * @returns {import('typedoc').SignatureReflection | undefined} */ function getPrimaryCallSignature(decl) { if (decl.signatures?.length) { - return decl.signatures[0]; + // Prefer the first non-`@deprecated` overload. typedoc treats each overload as a separate + // signature, and selecting a deprecated one usually means rendering the form users shouldn't + // use — and (often) one whose JSDoc isn't where the canonical `@param` descriptions live. + const firstActive = decl.signatures.find(s => !signatureIsDeprecated(s)); + return firstActive ?? decl.signatures[0]; } const t = decl.type; if (t && 'declaration' in t && t.declaration?.signatures?.length) { @@ -328,6 +395,49 @@ function substituteGenericParamRefsInType(t, map) { return t; } +/** + * Resolve a property's type to its declared default when it references a `TypeParameter` reflection. + * Used when a generic alias is inlined into an intersection (e.g. `CreateParams = { … } & MetadataParams` where the `& MetadataParams` arm gets inlined as a reflection, losing the named reference) so the property table surfaces the resolved default type instead of the open type-parameter name (e.g. `TPublic` → `OrganizationPublicMetadata`). + * + * @param {import('typedoc').Type | undefined} t + * @returns {import('typedoc').Type | undefined} + */ +function substituteTypeParameterDefaultsInType(t) { + if (!t) { + return t; + } + if (/** @type {{ type?: string }} */ (t).type === 'optional' && 'elementType' in t) { + const el = /** @type {{ elementType: import('typedoc').Type }} */ (t).elementType; + const next = substituteTypeParameterDefaultsInType(el); + if (next && next !== el) { + return new OptionalType(/** @type {import('typedoc').SomeType} */ (/** @type {unknown} */ (next))); + } + return t; + } + if (t instanceof ReferenceType) { + const tp = /** @type {{ kindOf?: (k: number) => boolean, default?: import('typedoc').Type }} */ (t.reflection); + if (tp?.kindOf?.(ReflectionKind.TypeParameter) && tp.default) { + return tp.default; + } + } + return t; +} + +/** + * Clone each property and apply `substituteTypeParameterDefaultsInType` to its type — see comment on `substituteTypeParameterDefaultsInType` for the motivating case. + * + * @param {import('typedoc').DeclarationReflection[]} children + */ +function substituteTypeParameterDefaultsInChildren(children) { + return children.map(child => { + const next = substituteTypeParameterDefaultsInType(child.type); + if (next === child.type) { + return child; + } + return Object.assign(Object.create(Object.getPrototypeOf(child)), child, { type: next }); + }); +} + /** * @param {import('typedoc').SignatureReflection} sig * @param {Map | undefined} instantiationMap @@ -683,6 +793,35 @@ function pickBetterUnionPropertyCandidate(existing, candidate) { return candidateDoc > existingDoc ? candidate : existing; } +/** + * Collect the set of string-literal keys from a type used as the second argument to `Omit` or `Pick` — a single literal (`'organizationId'`) or a union of literals (`'a' | 'b'`). Returns `undefined` if the type isn't a literal/literal-union (e.g. a `keyof` reference we can't resolve here), in which case callers should fall through to the generic-instantiation path. + * + * @param {import('typedoc').Type | undefined} t + * @returns {Set | undefined} + */ +function collectLiteralStringKeys(t) { + if (!t) { + return undefined; + } + if (t.type === 'literal' && typeof (/** @type {{ value: unknown }} */ (t).value) === 'string') { + return new Set([/** @type {{ value: string }} */ (t).value]); + } + if (t.type === 'union') { + const u = /** @type {import('typedoc').UnionType} */ (t); + /** @type {Set} */ + const keys = new Set(); + for (const inner of u.types) { + const got = collectLiteralStringKeys(inner); + if (!got) { + return undefined; + } + for (const k of got) keys.add(k); + } + return keys.size ? keys : undefined; + } + return undefined; +} + /** * Filter each arm to `Property` reflections and dedupe by name, returning a single sorted list * (or `undefined` if every arm was empty). Used for intersection / union / generic-instantiation @@ -722,7 +861,8 @@ function mergePropertyArms(arms, options) { if (byName.size === 0) { return undefined; } - return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name)); + const merged = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name)); + return substituteTypeParameterDefaultsInChildren(merged); } /** @@ -754,12 +894,26 @@ function resolveDeclarationWithObjectMembers(t, project) { if (t.type === 'optional') { return resolveDeclarationWithObjectMembers(/** @type {import('typedoc').OptionalType} */ (t).elementType, project); } + if (t.type === 'array') { + return resolveDeclarationWithObjectMembers(/** @type {import('typedoc').ArrayType} */ (t).elementType, project); + } if (t.type === 'reflection') { const children = t.declaration?.children; return children?.length ? children : undefined; } if (t.type === 'reference') { const ref = /** @type {import('typedoc').ReferenceType} */ (t); + /** + * `Omit` / `Pick` — TypeScript built-in utilities. They have no project reflection to look up, and falling through to the generic-instantiation path below would merge K's properties (zero, since K is a literal type) without applying the filter — Omit/Pick would silently behave like an identity. Resolve `X` to its property list, then keep/drop by the literal-string keys in `K`. Without this, `Array>` shows no nested rows because `decl` is undefined. + */ + if ((ref.name === 'Omit' || ref.name === 'Pick') && (ref.typeArguments?.length ?? 0) === 2) { + const baseChildren = resolveDeclarationWithObjectMembers(ref.typeArguments[0], project); + const keys = collectLiteralStringKeys(ref.typeArguments[1]); + if (baseChildren?.length && keys) { + const keep = ref.name === 'Pick' ? c => keys.has(c.name) : c => !keys.has(c.name); + return baseChildren.filter(keep); + } + } let decl = ref.reflection && 'kind' in ref.reflection ? /** @type {import('typedoc').DeclarationReflection} */ (ref.reflection) @@ -784,7 +938,7 @@ function resolveDeclarationWithObjectMembers(t, project) { return mergePropertyArms([base, ...argArms]); } if (decl.children?.length) { - return decl.children; + return substituteTypeParameterDefaultsInChildren(decl.children); } if (decl.type) { return resolveDeclarationWithObjectMembers(decl.type, project); @@ -806,14 +960,15 @@ function resolveDeclarationWithObjectMembers(t, project) { } /** - * Build the name cell for a nominal-nested row. Uses `?.` when the parent param is optional (so `options?.foo` mirrors how it would be accessed at runtime) and `.` when required — same rule as `clerkParametersTable.flattenParams` in `custom-theme.mjs`. + * Build the name cell for a nominal-nested row. Uses `?.` when the parent param is optional (so `options?.foo` mirrors how it would be accessed at runtime) and `.` when required — same rule as `clerkParametersTable.flattenParams` in `custom-theme.mjs`. Appends `?` to the child name when the child property itself is optional, matching how the inline-flatten path renders `params.field?` via the standard parametersTable. * * @param {import('typedoc').ParameterReflection} parentParam - * @param {string} childName + * @param {import('typedoc').DeclarationReflection} child */ -function formatNestedParamNameColumn(parentParam, childName) { +function formatNestedParamNameColumn(parentParam, child) { const sep = parentParam.flags?.isOptional ? '?.' : '.'; - return `\`${parentParam.name}${sep}${childName}\``; + const childOptional = child.flags?.isOptional ? '?' : ''; + return `\`${parentParam.name}${sep}${child.name}${childOptional}\``; } /** @@ -828,6 +983,11 @@ function parameterTypeLinksToStandaloneMdxPage(t, ctx) { if (!bare) { return false; } + // `Array`: the standalone page documents the element shape, not the array signature. + // Surface both — the Type column links to the element page, and nested `params.` rows flatten the element so readers don't have to navigate just to see field names. + if (bare.type === 'array') { + return false; + } if (bare.type === 'reference') { const ref = /** @type {import('typedoc').ReferenceType} */ (bare); if (isInlineModifierWithoutStandalonePage(ref.reflection)) { @@ -869,10 +1029,12 @@ function nestedParameterRowsFromDocumentedProperties(param, ctx) { /** @type {string[]} */ const rows = []; for (const child of props) { - const summary = child.comment?.summary; const typeCell = child.type ? removeLineBreaksForTableCell(ctx.partials.someType(child.type)) : '`unknown`'; - const nestedNameCol = formatNestedParamNameColumn(param, child.name); - const nestedDesc = summary?.length ? displayPartsToString(summary).trim() || '—' : '—'; + const nestedNameCol = formatNestedParamNameColumn(param, child); + const nestedDescRaw = renderNestedRowDescription(child.comment); + // Strip line breaks so multi-line `
    ` / paragraph descriptions don't shatter the markdown + // table row (which must be a single line). Matches the treatment already applied to typeCell. + const nestedDesc = removeLineBreaksForTableCell(nestedDescRaw) ?? '—'; rows.push(`| ${nestedNameCol} | ${typeCell} | ${nestedDesc} |`); } return rows; @@ -981,7 +1143,12 @@ function isNominalParamTypeDocumented(typeDecl, props) { * @param {import('typedoc-plugin-markdown').MarkdownThemeContext} ctx * @returns {string | undefined} */ -function trySingleNominalParameterTypeSection(sig, ctx) { +/** + * @param {import('typedoc').SignatureReflection} sig + * @param {import('typedoc-plugin-markdown').MarkdownThemeContext} ctx + * @param {number} [headingLevel] Defaults to 4 (reference-object format); pass 2 for page format. + */ +function trySingleNominalParameterTypeSection(sig, ctx, headingLevel = 4) { const params = sig.parameters ?? []; if (params.length !== 1) { return undefined; @@ -1013,22 +1180,23 @@ function trySingleNominalParameterTypeSection(sig, ctx) { if (!tableMd?.trim()) { return undefined; } - return [markdownHeadingInlineCode(4, nominal.sectionTitle), '', tableMd, ''].join('\n'); + return [markdownHeadingInlineCode(headingLevel, nominal.sectionTitle), '', tableMd, ''].join('\n'); } /** * @param {import('typedoc').SignatureReflection} sig * @param {import('typedoc-plugin-markdown').MarkdownThemeContext} ctx * @param {Map | undefined} instantiationMap + * @param {number} [headingLevel] Defaults to 4 (reference-object format); pass 2 for page format. */ -function parametersMarkdownTable(sig, ctx, instantiationMap) { +function parametersMarkdownTable(sig, ctx, instantiationMap, headingLevel = 4) { const sigForDisplay = signatureWithInstantiation(sig, instantiationMap); const params = sigForDisplay.parameters ?? []; if (params.length === 0) { return ''; } - const singleNominal = trySingleNominalParameterTypeSection(sigForDisplay, ctx); + const singleNominal = trySingleNominalParameterTypeSection(sigForDisplay, ctx, headingLevel); if (singleNominal) { return singleNominal; } @@ -1043,21 +1211,26 @@ function parametersMarkdownTable(sig, ctx, instantiationMap) { tableMd = `${tableMd.trimEnd()}\n${nested.join('\n')}\n`; } - return [markdownHeading(4, ReflectionKind.pluralString(ReflectionKind.Parameter)), '', tableMd, ''].join('\n'); + return [markdownHeading(headingLevel, ReflectionKind.pluralString(ReflectionKind.Parameter)), '', tableMd, ''].join( + '\n', + ); } /** * @param {import('typedoc').DeclarationReflection} decl * @param {import('typedoc-plugin-markdown').MarkdownThemeContext} ctx - * @param {{ qualifiedName?: string }} [options] Nested namespace methods use `parent.child` for headings / signatures. + * @param {{ qualifiedName?: string, methodFormat?: MethodFormat }} [options] Nested namespace methods use `parent.child` for headings / signatures. */ function buildMethodMdx(decl, ctx, options = {}) { const name = options.qualifiedName ?? decl.name; + const methodFormat = options.methodFormat ?? 'reference'; const sig = getPrimaryCallSignature(decl); if (!sig) { return ''; } - const title = `### \`${name}()\``; + // `'page'` format renders one method per docs page, so the page is anchored by a containing file/heading upstream — no in-page `### foo()` title needed. `'reference'` format aggregates many methods on one page and uses `### foo()` to disambiguate them. + const title = methodFormat === 'page' ? '' : `### \`${name}()\``; + const paramsHeadingLevel = methodFormat === 'page' ? 2 : 4; /** Prefer the declaration comment (property-style methods document `addListener` on the property, not the signature). */ const comment = decl.comment ?? sig.comment; let description = commentSummaryAndBody(comment); @@ -1070,13 +1243,17 @@ function buildMethodMdx(decl, ctx, options = {}) { const skipParametersSection = Boolean(decl.comment?.hasModifier('@skipParametersSection')) || Boolean(sig.comment?.hasModifier('@skipParametersSection')); - const paramsMd = skipParametersSection ? '' : parametersMarkdownTable(sig, ctx, instantiationMap); + if (!skipParametersSection) { + overlayParamCommentsFromSignatureBlockTags(sig); + } + const paramsMd = skipParametersSection ? '' : parametersMarkdownTable(sig, ctx, instantiationMap, paramsHeadingLevel); // Same post-process as `custom-plugin.mjs` `MarkdownPageEvent.END`: relative `.mdx` links, then catch-alls. // Skip the ```typescript``` fence so signatures stay plain code. - const head = applyCatchAllMdReplacements(applyRelativeLinkReplacements([title, '', description].join('\n'))); + const headSource = title ? [title, '', description].join('\n') : description; + const head = applyCatchAllMdReplacements(applyRelativeLinkReplacements(headSource)); const paramsProcessed = paramsMd ? applyCatchAllMdReplacements(applyRelativeLinkReplacements(paramsMd)) : ''; - const chunks = [head, ts]; + const chunks = head ? [head, ts] : [ts]; if (paramsProcessed) { chunks.push(paramsProcessed); } @@ -1156,9 +1333,10 @@ function processExtractMethodsNamespace(parentDecl, ctx, outDir) { * @param {import('typedoc').DeclarationReflection} decl * @param {import('typedoc-plugin-markdown').MarkdownThemeContext} ctx * @param {string} outDir + * @param {MethodFormat} [methodFormat] * @returns {ExtractedFile[]} */ -function extractCallableMembersFromDeclaration(decl, ctx, outDir) { +function extractCallableMembersFromDeclaration(decl, ctx, outDir, methodFormat = 'reference') { if (!decl.children) { return []; } @@ -1176,7 +1354,7 @@ function extractCallableMembersFromDeclaration(decl, ctx, outDir) { } if (shouldExtractCallableMember(childDecl, ctx)) { - const mdx = buildMethodMdx(childDecl, ctx); + const mdx = buildMethodMdx(childDecl, ctx, { methodFormat }); if (mdx) { const fileName = `${toFileSlug(child.name)}.mdx`; const filePath = path.join(outDir, fileName); @@ -1189,16 +1367,24 @@ function extractCallableMembersFromDeclaration(decl, ctx, outDir) { /** * @param {import('typedoc-plugin-markdown').MarkdownPageEvent} output - * @returns {keyof typeof REFERENCE_OBJECT_CONFIG | undefined} + * @returns {string | undefined} */ function matchReferenceObjectPageUrl(output) { if (!output.url) { return undefined; } const normalized = output.url.replace(/\\/g, '/'); - return normalized in REFERENCE_OBJECT_CONFIG - ? /** @type {keyof typeof REFERENCE_OBJECT_CONFIG} */ (normalized) - : undefined; + if (normalized in REFERENCE_OBJECT_CONFIG) return normalized; + if (normalized in BACKEND_API_CONFIG) return normalized; + return undefined; +} + +/** @param {string} pageUrl */ +function configEntryForPageUrl(pageUrl) { + return /** @type {import('./reference-objects.mjs').REFERENCE_OBJECT_CONFIG[keyof typeof REFERENCE_OBJECT_CONFIG]} */ ( + REFERENCE_OBJECT_CONFIG[/** @type {keyof typeof REFERENCE_OBJECT_CONFIG} */ (pageUrl)] ?? + BACKEND_API_CONFIG[/** @type {keyof typeof BACKEND_API_CONFIG} */ (pageUrl)] + ); } /** @@ -1216,7 +1402,8 @@ export function load(app) { if (!pageUrl) { return; } - const entry = REFERENCE_OBJECT_CONFIG[pageUrl]; + const entry = configEntryForPageUrl(pageUrl); + const methodFormat = methodFormatForPageUrl(pageUrl); const decl = /** @type {import('typedoc').DeclarationReflection | undefined} */ (output.model); if (!decl?.children) { console.warn(`[extract-methods] No children on reflection for ${pageUrl}, skipping`); @@ -1240,7 +1427,7 @@ export function load(app) { const outDir = path.join(objectDir, 'methods'); /** @type {ExtractedFile[]} */ - const methodFiles = extractCallableMembersFromDeclaration(decl, ctx, outDir); + const methodFiles = extractCallableMembersFromDeclaration(decl, ctx, outDir, methodFormat); const extraMethodInterfaces = 'extraMethodInterfaces' in entry ? entry.extraMethodInterfaces : undefined; if (Array.isArray(extraMethodInterfaces)) { for (const extra of extraMethodInterfaces) { @@ -1249,7 +1436,7 @@ export function load(app) { console.warn(`[extract-methods] extraMethodInterfaces: could not find "${extra.symbol}" for ${pageUrl}`); continue; } - methodFiles.push(...extractCallableMembersFromDeclaration(extraDecl, ctx, outDir)); + methodFiles.push(...extractCallableMembersFromDeclaration(extraDecl, ctx, outDir, methodFormat)); } } diff --git a/.typedoc/reference-objects.mjs b/.typedoc/reference-objects.mjs index 424ca40172f..d2e83e7e45d 100644 --- a/.typedoc/reference-objects.mjs +++ b/.typedoc/reference-objects.mjs @@ -56,13 +56,106 @@ export const REFERENCE_OBJECT_CONFIG = { }, }; -/** Stable iteration order matches key order in {@link REFERENCE_OBJECT_CONFIG}. */ -export const REFERENCE_OBJECTS_LIST = Object.keys(REFERENCE_OBJECT_CONFIG); +/** + * Backend API endpoint pages: identical extraction machinery as {@link REFERENCE_OBJECT_CONFIG}, but each `methods/.mdx` is written in **page format** — no `### foo()` title at the top, and the `Parameters` section uses an `## H2` heading. The reference-object format uses an H3 title + H4 parameters, which suits pages that aggregate many methods on a single resource. Backend API method files are consumed standalone (one method per docs page), so the heading levels need to shift accordingly. + */ +export const BACKEND_API_CONFIG = { + 'backend/user-api/user-api.mdx': { + symbol: 'UserAPI', + declarationHint: 'api/endpoints/UserApi', + }, + 'backend/organization-api/organization-api.mdx': { + symbol: 'OrganizationAPI', + declarationHint: 'api/endpoints/OrganizationApi', + }, + 'backend/billing-api/billing-api.mdx': { + symbol: 'BillingAPI', + declarationHint: 'api/endpoints/BillingApi', + }, + 'backend/allowlist-identifier-api/allowlist-identifier-api.mdx': { + symbol: 'AllowlistIdentifierAPI', + declarationHint: 'api/endpoints/AllowlistIdentifierApi', + }, + 'backend/domain-api/domain-api.mdx': { + symbol: 'DomainAPI', + declarationHint: 'api/endpoints/DomainApi', + }, + 'backend/session-api/session-api.mdx': { + symbol: 'SessionAPI', + declarationHint: 'api/endpoints/SessionApi', + }, + 'backend/client-api/client-api.mdx': { + symbol: 'ClientAPI', + declarationHint: 'api/endpoints/ClientApi', + }, + 'backend/invitation-api/invitation-api.mdx': { + symbol: 'InvitationAPI', + declarationHint: 'api/endpoints/InvitationApi', + }, + 'backend/redirect-url-api/redirect-url-api.mdx': { + symbol: 'RedirectUrlAPI', + declarationHint: 'api/endpoints/RedirectUrlApi', + }, + 'backend/email-address-api/email-address-api.mdx': { + symbol: 'EmailAddressAPI', + declarationHint: 'api/endpoints/EmailAddressApi', + }, + 'backend/phone-number-api/phone-number-api.mdx': { + symbol: 'PhoneNumberAPI', + declarationHint: 'api/endpoints/PhoneNumberApi', + }, + 'backend/agent-task-api/agent-task-api.mdx': { + symbol: 'AgentTaskAPI', + declarationHint: 'api/endpoints/AgentTaskApi', + }, + 'backend/sign-in-token-api/sign-in-token-api.mdx': { + symbol: 'SignInTokenAPI', + declarationHint: 'api/endpoints/SignInTokenApi', + }, + 'backend/enterprise-connection-api/enterprise-connection-api.mdx': { + symbol: 'EnterpriseConnectionAPI', + declarationHint: 'api/endpoints/EnterpriseConnectionApi', + }, + 'backend/testing-token-api/testing-token-api.mdx': { + symbol: 'TestingTokenAPI', + declarationHint: 'api/endpoints/TestingTokenApi', + }, + 'backend/waitlist-entry-api/waitlist-entry-api.mdx': { + symbol: 'WaitlistEntryAPI', + declarationHint: 'api/endpoints/WaitlistEntryApi', + }, + 'backend/machine-api/machine-api.mdx': { + symbol: 'MachineApi', + declarationHint: 'api/endpoints/MachineApi', + }, + 'backend/m2-m-token-api/m2-m-token-api.mdx': { + symbol: 'M2MTokenApi', + declarationHint: 'api/endpoints/M2MTokenApi', + }, + 'backend/o-auth-applications-api/o-auth-applications-api.mdx': { + symbol: 'OAuthApplicationsApi', + declarationHint: 'api/endpoints/OAuthApplicationsApi', + }, + 'backend/api-keys-api/api-keys-api.mdx': { + symbol: 'APIKeysAPI', + declarationHint: 'api/endpoints/APIKeysApi', + }, + 'backend/instance-api/instance-api.mdx': { + symbol: 'InstanceAPI', + declarationHint: 'api/endpoints/InstanceApi', + }, +}; + +/** Stable iteration order matches key order in {@link REFERENCE_OBJECT_CONFIG} then {@link BACKEND_API_CONFIG}. */ +export const REFERENCE_OBJECTS_LIST = [...Object.keys(REFERENCE_OBJECT_CONFIG), ...Object.keys(BACKEND_API_CONFIG)]; /** * Primary interface/class documented on each reference object page (used to resolve TypeDoc reflections). - * Derived from {@link REFERENCE_OBJECT_CONFIG}; kept for callers that only need `pageUrl → symbol`. + * Includes both {@link REFERENCE_OBJECT_CONFIG} and {@link BACKEND_API_CONFIG} so the router applies the same folder-nesting rule to backend API pages. */ export const REFERENCE_OBJECT_PAGE_SYMBOLS = Object.fromEntries( - Object.entries(REFERENCE_OBJECT_CONFIG).map(([url, { symbol }]) => [url, symbol]), + [...Object.entries(REFERENCE_OBJECT_CONFIG), ...Object.entries(BACKEND_API_CONFIG)].map(([url, { symbol }]) => [ + url, + symbol, + ]), ); diff --git a/packages/backend/src/api/endpoints/APIKeysApi.ts b/packages/backend/src/api/endpoints/APIKeysApi.ts index d00c79c3977..e3243784659 100644 --- a/packages/backend/src/api/endpoints/APIKeysApi.ts +++ b/packages/backend/src/api/endpoints/APIKeysApi.ts @@ -8,68 +8,62 @@ import { AbstractAPI } from './AbstractApi'; const basePath = '/api_keys'; -type GetAPIKeyListParams = ClerkPaginationRequest<{ - /** - * The user or Organization ID to query API keys by - */ +/** @generateWithEmptyComment */ +export type GetAPIKeyListParams = ClerkPaginationRequest<{ + /** The user or Organization ID to query API keys by. */ subject: string; - /** - * Whether to include invalid API keys. - * - * @default false - */ + /** Whether to include invalid API keys (revoked or expired). Defaults to `false`. */ includeInvalid?: boolean; }>; -type CreateAPIKeyParams = { - /** - * API key name - */ +/** @generateWithEmptyComment */ +export type CreateAPIKeyParams = { + /** A descriptive name for the API key (e.g., "Production API Key", "Development Key"). */ name: string; - /** - * The user or Organization ID to associate the API key with - */ + /** The user or Organization ID to associate the API key with. */ subject: string; - /** - * API key description - */ + /** The description of the API key. */ description?: string | null; + /** Custom claims to store additional information about the API key. */ claims?: Record | null; + /** Scopes to limit the API key's access to specific resources. */ scopes?: string[]; + /** The user ID of the user who created the API key. */ createdBy?: string | null; + /** The number of seconds until the API key expires. Defaults to `null` (never expires). */ secondsUntilExpiration?: number | null; }; -type RevokeAPIKeyParams = { - /** - * API key ID - */ +/** @generateWithEmptyComment */ +export type RevokeAPIKeyParams = { + /** The ID of the API key to revoke. */ apiKeyId: string; - /** - * Reason for revocation - */ + /** The reason for revoking the API key. Useful for your records. */ revocationReason?: string | null; }; -type UpdateAPIKeyParams = { - /** - * API key ID - */ +/** @generateWithEmptyComment */ +export type UpdateAPIKeyParams = { + /** The ID of the API key to update. */ apiKeyId: string; - /** - * The user or Organization ID to associate the API key with - */ + /** The user or Organization ID to associate the API key with. */ subject: string; - /** - * API key description - */ + /** The description of the API key. */ description?: string | null; + /** Custom claims to store additional information about the API key. */ claims?: Record | null; + /** Scopes to limit the API key's access to specific resources. */ scopes?: string[]; + /** The number of seconds until the API key expires. Defaults to `null` (never expires). */ secondsUntilExpiration?: number | null; }; +/** @generateWithEmptyComment */ export class APIKeysAPI extends AbstractAPI { + /** + * Gets a list of API keys for the given user or Organization. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`APIKey`](https://clerk.com/docs/reference/backend/types/backend-api-key) objects and a `totalCount` property containing the total number of API keys for the user or Organization. + */ async list(queryParams: GetAPIKeyListParams) { return this.request>({ method: 'GET', @@ -78,6 +72,10 @@ export class APIKeysAPI extends AbstractAPI { }); } + /** + * Creates a new API key for the given user or Organization. + * @returns The created [`APIKey`](https://clerk.com/docs/reference/backend/types/backend-api-key) object. + */ async create(params: CreateAPIKeyParams) { return this.request({ method: 'POST', @@ -86,6 +84,10 @@ export class APIKeysAPI extends AbstractAPI { }); } + /** + * Gets the given [`APIKey`](https://clerk.com/docs/reference/backend/types/backend-api-key) object. + * @param apiKeyId - The ID of the API key to get. + */ async get(apiKeyId: string) { this.requireId(apiKeyId); @@ -95,6 +97,10 @@ export class APIKeysAPI extends AbstractAPI { }); } + /** + * Updates the given API key. + * @returns The updated [`APIKey`](https://clerk.com/docs/reference/backend/types/backend-api-key) object. + */ async update(params: UpdateAPIKeyParams) { const { apiKeyId, ...bodyParams } = params; @@ -107,6 +113,11 @@ export class APIKeysAPI extends AbstractAPI { }); } + /** + * Deletes the given API key. + * @param apiKeyId - The ID of the API key to delete. + * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object) object. + */ async delete(apiKeyId: string) { this.requireId(apiKeyId); @@ -116,6 +127,10 @@ export class APIKeysAPI extends AbstractAPI { }); } + /** + * Revokes the given API key. This will immediately invalidate the API key and prevent it from being used to authenticate any future requests. + * @returns The revoked [`APIKey`](https://clerk.com/docs/reference/backend/types/backend-api-key) object. + */ async revoke(params: RevokeAPIKeyParams) { const { apiKeyId, revocationReason = null } = params; @@ -128,6 +143,10 @@ export class APIKeysAPI extends AbstractAPI { }); } + /** + * Gets the secret of the given API key. + * @param apiKeyId - The ID of the API key to get the secret of. + */ async getSecret(apiKeyId: string) { this.requireId(apiKeyId); @@ -137,6 +156,13 @@ export class APIKeysAPI extends AbstractAPI { }); } + /** + * Verifies the given API key. + * - If the API key is valid, the method returns the API key object with its properties. + * - If the API key is invalid, revoked, or expired, the method will throw an error. + * @param secret - The secret of the API key to verify. + * @returns The verified [`APIKey`](https://clerk.com/docs/reference/backend/types/backend-api-key) object. + */ async verify(secret: string) { return this.request({ method: 'POST', diff --git a/packages/backend/src/api/endpoints/AgentTaskApi.ts b/packages/backend/src/api/endpoints/AgentTaskApi.ts index 17dcacbe41a..2df65bf5b1a 100644 --- a/packages/backend/src/api/endpoints/AgentTaskApi.ts +++ b/packages/backend/src/api/endpoints/AgentTaskApi.ts @@ -2,52 +2,40 @@ import { joinPaths } from '../../util/path'; import type { AgentTask } from '../resources/AgentTask'; import { AbstractAPI } from './AbstractApi'; -type CreateAgentTaskParams = { - /** - * The user to create an agent task for. - */ +/** @generateWithEmptyComment */ +export type CreateAgentTaskParams = { + /** The user to create an Agent Task for. Provide either a `userId` or an `identifier` (e.g. an email address, phone number, or username). */ onBehalfOf: | { - /** - * The identifier of the user to create an agent task for. - */ + /** The identifier of the user to create an Agent Task for. */ identifier: string; userId?: never; } | { - /** - * The ID of the user to create an agent task for. - */ + /** The ID of the user to create an Agent Task for. */ userId: string; identifier?: never; }; - /** - * The permissions the agent task will have. - */ + /** The permissions the Agent Task will have. Currently, `'*'` is the only supported value, which grants all permissions. */ permissions: string; - /** - * The name of the agent to create an agent task for. - */ + /** The name of the agent creating the task. Used to derive a stable `agent_id` for the Agent Task. */ agentName: string; - /** - * The description of the agent task to create. - */ + /** The description of the Agent Task to create. */ taskDescription: string; - /** - * The URL to redirect to after the agent task is consumed. - */ + /** The URL the user lands on after the Agent Task is accepted. In production instances, must be a valid absolute URL with an `https` scheme. In development instances, `http` is also permitted. The URL's domain must belong to one of the instance's associated domains (primary or satellite); otherwise, the redirect will be rejected when the task ticket is consumed. */ redirectUrl: string; - - /** - * The maximum duration that the session which will be created by the generated agent task should last. - * By default, the duration is 30 minutes. - */ + /** The maximum duration that the session created by the Agent Task should last. By default, the duration is `1800` (30 minutes). */ sessionMaxDurationInSeconds?: number; }; const basePath = '/agents/tasks'; +/** @generateWithEmptyComment */ export class AgentTaskAPI extends AbstractAPI { + /** + * Creates an Agent Task that generates a URL which, when visited, creates a session for the specified user. This is useful for automated testing or agent-driven flows where full authentication isn't practical. + * @returns The created [`AgentTask`](https://clerk.com/docs/reference/backend/types/backend-agent-task) object. + */ public async create(params: CreateAgentTaskParams) { return this.request({ method: 'POST', @@ -59,6 +47,11 @@ export class AgentTaskAPI extends AbstractAPI { }); } + /** + * Revokes the given Agent Task. + * @param agentTaskId - The ID of the Agent Task to revoke. + * @returns The revoked [`AgentTask`](https://clerk.com/docs/reference/backend/types/backend-agent-task) object. + */ public async revoke(agentTaskId: string) { this.requireId(agentTaskId); return this.request>({ diff --git a/packages/backend/src/api/endpoints/AllowlistIdentifierApi.ts b/packages/backend/src/api/endpoints/AllowlistIdentifierApi.ts index 62611e92e8e..a3bca9c28d9 100644 --- a/packages/backend/src/api/endpoints/AllowlistIdentifierApi.ts +++ b/packages/backend/src/api/endpoints/AllowlistIdentifierApi.ts @@ -8,12 +8,20 @@ import { AbstractAPI } from './AbstractApi'; const basePath = '/allowlist_identifiers'; -type AllowlistIdentifierCreateParams = { +/** @generateWithEmptyComment */ +export type AllowlistIdentifierCreateParams = { + /** The identifier to add to the allowlist. Can be an email address, a domain in wildcard email format (e.g. `*@example.com`), a phone number in international E.164 format (e.g. `+15555555555`), or a Web3 wallet address. */ identifier: string; + /** Whether to notify the user that their identifier has been added to the allowlist. Notifies the user if the `identifier` is an email address or phone number. */ notify: boolean; }; +/** @generateWithEmptyComment */ export class AllowlistIdentifierAPI extends AbstractAPI { + /** + * Gets the list of allowlist identifiers for the instance. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`AllowlistIdentifier`](https://clerk.com/docs/reference/backend/types/backend-allowlist-identifier) objects and a `totalCount` property containing the total number of allowlist identifiers for the instance. + */ public async getAllowlistIdentifierList(params: ClerkPaginationRequest = {}) { return this.request>({ method: 'GET', @@ -22,6 +30,10 @@ export class AllowlistIdentifierAPI extends AbstractAPI { }); } + /** + * Creates a new allowlist identifier. + * @returns The created [`AllowlistIdentifier`](https://clerk.com/docs/reference/backend/types/backend-allowlist-identifier) object. + */ public async createAllowlistIdentifier(params: AllowlistIdentifierCreateParams) { return this.request({ method: 'POST', @@ -30,6 +42,11 @@ export class AllowlistIdentifierAPI extends AbstractAPI { }); } + /** + * Deletes an allowlist identifier. + * @param allowlistIdentifierId - The ID of the allowlist identifier to delete. + * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object) object. + */ public async deleteAllowlistIdentifier(allowlistIdentifierId: string) { this.requireId(allowlistIdentifierId); return this.request({ diff --git a/packages/backend/src/api/endpoints/BillingApi.ts b/packages/backend/src/api/endpoints/BillingApi.ts index 3561a7cc9f3..6011d0c9a26 100644 --- a/packages/backend/src/api/endpoints/BillingApi.ts +++ b/packages/backend/src/api/endpoints/BillingApi.ts @@ -11,31 +11,38 @@ const basePath = '/billing'; const organizationBasePath = '/organizations'; const userBasePath = '/users'; -type GetOrganizationListParams = ClerkPaginationRequest<{ +/** @generateWithEmptyComment */ +export type GetPlanListParams = ClerkPaginationRequest<{ + /** + * Filters plans by the type of payer. + */ payerType: 'org' | 'user'; }>; -type CancelSubscriptionItemParams = { +/** @inline */ +export type CancelSubscriptionItemParams = { /** - * If true, the subscription item will be canceled immediately. If false or undefined, the subscription item will be canceled at the end of the current billing period. - * @default undefined + * Whether the Subscription Item should be canceled immediately. If `false`, the Subscription Item will be canceled at the end of the current billing period. */ endNow?: boolean; }; -type ExtendSubscriptionItemFreeTrialParams = { +/** @inline */ +export type ExtendSubscriptionItemFreeTrialParams = { /** - * RFC3339 timestamp to extend the free trial to. - * Must be in the future and not more than 365 days from the current trial end. + * The date to extend the free trial to. Must be in the future and not more than 365 days from the current trial end date. */ extendTo: Date; }; +/** @generateWithEmptyComment */ export class BillingAPI extends AbstractAPI { /** + * Gets the list of Billing Plans for the instance. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`BillingPlan`](https://clerk.com/docs/reference/backend/types/billing-plan) objects and a `totalCount` property containing the total number of Billing Plans for the instance. * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. */ - public async getPlanList(params?: GetOrganizationListParams) { + public async getPlanList(params?: GetPlanListParams) { return this.request>({ method: 'GET', path: joinPaths(basePath, 'plans'), @@ -44,6 +51,10 @@ export class BillingAPI extends AbstractAPI { } /** + * Cancels the given Subscription Item. + * @param subscriptionItemId - The ID of the Subscription Item to cancel. + * @param params - The parameters for the request. + * @returns The cancelled [`BillingSubscriptionItem`](https://clerk.com/docs/reference/backend/types/billing-subscription-item) object. * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. */ public async cancelSubscriptionItem(subscriptionItemId: string, params?: CancelSubscriptionItemParams) { @@ -56,6 +67,10 @@ export class BillingAPI extends AbstractAPI { } /** + * Extends the free trial for the given Subscription Item. + * @param subscriptionItemId - The ID of the Subscription Item to extend the free trial for. + * @param params - The parameters for the request. + * @returns The updated [`BillingSubscriptionItem`](https://clerk.com/docs/reference/backend/types/billing-subscription-item) object. * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. */ public async extendSubscriptionItemFreeTrial( @@ -71,6 +86,8 @@ export class BillingAPI extends AbstractAPI { } /** + * Gets the [`BillingSubscription`](https://clerk.com/docs/reference/backend/types/billing-subscription) for the given Organization. + * @param organizationId - The ID of the Organization to get the Billing Subscription for. * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. */ public async getOrganizationBillingSubscription(organizationId: string) { @@ -82,6 +99,8 @@ export class BillingAPI extends AbstractAPI { } /** + * Gets the [`BillingSubscription`](https://clerk.com/docs/reference/backend/types/billing-subscription) for the given User. + * @param userId - The ID of the User to get the Billing Subscription for. * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. */ public async getUserBillingSubscription(userId: string) { diff --git a/packages/backend/src/api/endpoints/ClientApi.ts b/packages/backend/src/api/endpoints/ClientApi.ts index 13d313cf449..e1ef63be247 100644 --- a/packages/backend/src/api/endpoints/ClientApi.ts +++ b/packages/backend/src/api/endpoints/ClientApi.ts @@ -12,7 +12,11 @@ type GetHandshakePayloadParams = { nonce: string; }; +/** @generateWithEmptyComment */ export class ClientAPI extends AbstractAPI { + /** + * @deprecated This method is deprecated and will be removed in a future version. + */ public async getClientList(params: ClerkPaginationRequest = {}) { return this.request>({ method: 'GET', @@ -21,6 +25,10 @@ export class ClientAPI extends AbstractAPI { }); } + /** + * Gets the given [`Client`](https://clerk.com/docs/reference/backend/types/backend-client). + * @param clientId - The ID of the client to get. + */ public async getClient(clientId: string) { this.requireId(clientId); return this.request({ @@ -29,6 +37,11 @@ export class ClientAPI extends AbstractAPI { }); } + /** + * Verifies the client in the given token. + * @param token - The token to verify. + * @returns The verified [`Client`](https://clerk.com/docs/reference/backend/types/backend-client). + */ public verifyClient(token: string) { return this.request({ method: 'POST', @@ -37,6 +50,12 @@ export class ClientAPI extends AbstractAPI { }); } + /** + * Retrieves the handshake payload for a given nonce. Used internally by Clerk's SDKs to resolve + * session cookies during the handshake flow. + * + * @internal + */ public async getHandshakePayload(queryParams: GetHandshakePayloadParams) { return this.request({ method: 'GET', diff --git a/packages/backend/src/api/endpoints/DomainApi.ts b/packages/backend/src/api/endpoints/DomainApi.ts index 12872c6335d..865b881ba07 100644 --- a/packages/backend/src/api/endpoints/DomainApi.ts +++ b/packages/backend/src/api/endpoints/DomainApi.ts @@ -6,35 +6,32 @@ import { AbstractAPI } from './AbstractApi'; const basePath = '/domains'; -type AddDomainParams = { +/** @generateWithEmptyComment */ +export type AddDomainParams = { /** - * The new domain name. For development instances, can contain the port, i.e myhostname:3000. For production instances, must be a valid FQDN, i.e mysite.com. Cannot contain protocol scheme. + * The new domain name. For development instances, can contain the port, e.g. `myhostname:3000`. For production instances, must be a valid FQDN, e.g. `mysite.com`. Cannot contain protocol scheme. */ name: string; - /** - * Marks the new domain as satellite. Only true is accepted at the moment. - */ + /** Whether the new domain is a satellite domain. Only `true` is accepted at the moment. */ is_satellite: boolean; - /** - * The full URL of the proxy which will forward requests to the Clerk Frontend API for this domain. Applicable only to production instances. - */ + /** The proxy URL for the domain. Applicable only to production instances. */ proxy_url?: string | null; }; -type UpdateDomainParams = Partial> & { - /** - * The ID of the domain that will be updated. - */ +/** @generateWithEmptyComment */ +export type UpdateDomainParams = Partial> & { + /** The ID of the domain that will be updated. */ domainId: string; - /** - * Whether this is a domain for a secondary app, meaning that any subdomain provided is significant - * and will be stored as part of the domain. This is useful for supporting multiple apps - * (one primary and multiple secondaries) on the same root domain (eTLD+1). - */ + /** Whether this is a domain for a secondary app, meaning that any subdomain provided is significant and will be stored as part of the domain. This is useful for supporting multiple apps (one primary and multiple secondaries) on the same root domain (eTLD+1). */ is_secondary?: boolean | null; }; +/** @generateWithEmptyComment */ export class DomainAPI extends AbstractAPI { + /** + * Gets the list of domains for the instance. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`Domain`](https://clerk.com/docs/reference/backend/types/domain) objects and a `totalCount` property containing the total number of domains for the instance. + */ public async list() { return this.request>({ method: 'GET', @@ -42,6 +39,10 @@ export class DomainAPI extends AbstractAPI { }); } + /** + * Adds a new domain to the instance. Useful in the case of multi-domain instances, allows adding [satellite domains](https://clerk.com/docs/guides/dashboard/dns-domains/satellite-domains) to an instance. + * @returns The created [`Domain`](https://clerk.com/docs/reference/backend/types/domain) object. + */ public async add(params: AddDomainParams) { return this.request({ method: 'POST', @@ -50,6 +51,12 @@ export class DomainAPI extends AbstractAPI { }); } + /** + * Updates a domain for the instance. Both primary and satellite domains can be updated. If you choose to use Clerk via proxy, use this endpoint to specify the `proxy_url`. Whenever you decide you'd rather switch to DNS setup for Clerk, simply set `proxy_url` to `null` for the domain. + * + * When you update a production instance's primary domain name, you have to make sure that you've completed all the necessary setup steps for DNS and emails to work. Expect downtime otherwise. Updating a primary domain's name will also update the instance's home origin, affecting the default application paths. + * @returns The updated [`Domain`](https://clerk.com/docs/reference/backend/types/domain) object. + */ public async update(params: UpdateDomainParams) { const { domainId, ...bodyParams } = params; @@ -63,15 +70,19 @@ export class DomainAPI extends AbstractAPI { } /** - * Deletes a satellite domain for the instance. - * It is currently not possible to delete the instance's primary domain. + * Deletes a satellite domain for the instance. It is currently not possible to delete the instance's primary domain. + * @param satelliteDomainId - The ID of the satellite domain to delete. + * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object). */ public async delete(satelliteDomainId: string) { return this.deleteDomain(satelliteDomainId); } /** - * @deprecated Use `delete` instead + * Deletes a satellite domain for the instance. + * @param satelliteDomainId - The ID of the satellite domain to delete. + * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object). + * @deprecated Use `delete()` instead. */ public async deleteDomain(satelliteDomainId: string) { this.requireId(satelliteDomainId); diff --git a/packages/backend/src/api/endpoints/EmailAddressApi.ts b/packages/backend/src/api/endpoints/EmailAddressApi.ts index cffd8943936..667b5e79bbe 100644 --- a/packages/backend/src/api/endpoints/EmailAddressApi.ts +++ b/packages/backend/src/api/endpoints/EmailAddressApi.ts @@ -4,19 +4,32 @@ import { AbstractAPI } from './AbstractApi'; const basePath = '/email_addresses'; -type CreateEmailAddressParams = { +/** @generateWithEmptyComment */ +export type CreateEmailAddressParams = { + /** The ID of the user to create the email address for. */ userId: string; + /** The email address to create. */ emailAddress: string; + /** Whether the email address should be verified. Defaults to `false`. */ verified?: boolean; + /** Whether the email address should be the primary email address. Defaults to `false`, unless it is the first email address added to the user. */ primary?: boolean; }; -type UpdateEmailAddressParams = { +/** @inline */ +export type UpdateEmailAddressParams = { + /** Whether the email address should be verified. Defaults to `false`. */ verified?: boolean; + /** Whether the email address should be the primary email address. Defaults to `false`, unless it is the first email address added to the user. */ primary?: boolean; }; +/** @generateWithEmptyComment */ export class EmailAddressAPI extends AbstractAPI { + /** + * Gets the given [`EmailAddress`](https://clerk.com/docs/reference/backend/types/backend-email-address). + * @param emailAddressId - The ID of the email address to get. + */ public async getEmailAddress(emailAddressId: string) { this.requireId(emailAddressId); @@ -26,6 +39,10 @@ export class EmailAddressAPI extends AbstractAPI { }); } + /** + * Creates a new email address for the given user. + * @returns The created [`EmailAddress`](https://clerk.com/docs/reference/backend/types/backend-email-address) object. + */ public async createEmailAddress(params: CreateEmailAddressParams) { return this.request({ method: 'POST', @@ -34,6 +51,12 @@ export class EmailAddressAPI extends AbstractAPI { }); } + /** + * Updates the given email address. + * @param emailAddressId - The ID of the email address to update. + * @param params - The parameters to update the email address. + * @returns The updated [`EmailAddress`](https://clerk.com/docs/reference/backend/types/backend-email-address) object. + */ public async updateEmailAddress(emailAddressId: string, params: UpdateEmailAddressParams = {}) { this.requireId(emailAddressId); @@ -44,6 +67,11 @@ export class EmailAddressAPI extends AbstractAPI { }); } + /** + * Deletes the given email address. + * @param emailAddressId - The ID of the email address to delete. + * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object) object. + */ public async deleteEmailAddress(emailAddressId: string) { this.requireId(emailAddressId); diff --git a/packages/backend/src/api/endpoints/EnterpriseConnectionApi.ts b/packages/backend/src/api/endpoints/EnterpriseConnectionApi.ts index f49bb800298..ccbcc15d0d1 100644 --- a/packages/backend/src/api/endpoints/EnterpriseConnectionApi.ts +++ b/packages/backend/src/api/endpoints/EnterpriseConnectionApi.ts @@ -7,62 +7,114 @@ import { AbstractAPI } from './AbstractApi'; const basePath = '/enterprise_connections'; -type EnterpriseConnectionListParams = ClerkPaginationRequest<{ +/** @generateWithEmptyComment */ +export type EnterpriseConnectionListParams = ClerkPaginationRequest<{ + /** + * Filters enterprise connections by Organization ID. + */ organizationId?: string; + /** + * Filters enterprise connections by active status. If `true`, only active connections are returned. If `false`, only inactive connections are returned. If omitted, all connections are returned. + */ active?: boolean; }>; +/** @inline */ export interface EnterpriseConnectionOidcParams { + /** The OAuth (OIDC) authorization URL. */ authUrl?: string; + /** The OAuth (OIDC) client ID. */ clientId?: string; + /** The OAuth (OIDC) client secret. */ clientSecret?: string; + /** The OAuth (OIDC) discovery URL. */ discoveryUrl?: string; + /** Whether the OAuth (OIDC) requires PKCE. Must be `true` for public clients with no client secret. */ requiresPkce?: boolean; + /** The OAuth (OIDC) token URL. */ tokenUrl?: string; + /** The OAuth (OIDC) user info URL. */ userInfoUrl?: string; } +/** @inline */ export interface EnterpriseConnectionSamlAttributeMappingParams { + /** The attribute mapping for the user ID. */ userId?: string | null; + /** The attribute mapping for the email address. */ emailAddress?: string | null; + /** The attribute mapping for the first name. */ firstName?: string | null; + /** The attribute mapping for the last name. */ lastName?: string | null; } +/** @inline */ export interface EnterpriseConnectionSamlParams { + /** Whether the SAML connection allows Identity Provider (IdP) initiated flows. */ allowIdpInitiated?: boolean; + /** Whether the SAML connection allows users with an email address subdomain to use it. */ allowSubdomains?: boolean; + /** The attribute mapping for the SAML connection. */ attributeMapping?: EnterpriseConnectionSamlAttributeMappingParams; + /** Whether the SAML connection requires force authentication. */ forceAuthn?: boolean; + /** The IdP certificate (PEM) for the SAML connection. */ idpCertificate?: string; + /** The IdP Entity ID for the SAML connection. */ idpEntityId?: string; + /** The raw IdP metadata XML for the SAML connection. */ idpMetadata?: string; + /** The IdP metadata URL for the SAML connection. */ idpMetadataUrl?: string; + /** The IdP Single-Sign On URL for the SAML connection. */ idpSsoUrl?: string; } -type CreateEnterpriseConnectionParams = { +/** @generateWithEmptyComment */ +export type CreateEnterpriseConnectionParams = { + /** The name of the enterprise connection. */ name?: string; + /** The [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains) of the enterprise connection. */ domains?: string[]; + /** The organization ID of the enterprise connection. */ organizationId?: string; + /** Whether the enterprise connection should be active. */ active?: boolean; + /** Whether the enterprise connection should sync user attributes between the IdP and Clerk. */ syncUserAttributes?: boolean; + /** Configuration for if the enterprise connection uses OAuth (OIDC). */ oidc?: EnterpriseConnectionOidcParams; + /** Configuration for if the enterprise connection uses SAML. */ saml?: EnterpriseConnectionSamlParams; }; -type UpdateEnterpriseConnectionParams = { +/** @inline */ +export type UpdateEnterpriseConnectionParams = { + /** The name of the enterprise connection. */ name?: string; + /** The [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains) of the enterprise connection. */ domains?: string[]; + /** The organization ID of the enterprise connection. */ organizationId?: string; + /** Whether the enterprise connection should be active. */ active?: boolean; + /** Whether the enterprise connection should sync user attributes between the IdP and Clerk. */ syncUserAttributes?: boolean; + /** The identity provider (IdP) of the enterprise connection. For example, `'saml_custom'` or `'oidc_custom'`. */ provider?: string; + /** Configuration for if the enterprise connection uses OAuth (OIDC). */ oidc?: EnterpriseConnectionOidcParams; + /** Configuration for if the enterprise connection uses SAML. */ saml?: EnterpriseConnectionSamlParams; }; +/** @generateWithEmptyComment */ export class EnterpriseConnectionAPI extends AbstractAPI { + /** + * Creates a new enterprise connection. + * @returns The created [`EnterpriseConnection`](https://clerk.com/docs/reference/backend/types/backend-enterprise-connection) object. + */ public async createEnterpriseConnection(params: CreateEnterpriseConnectionParams) { return this.request({ method: 'POST', @@ -74,6 +126,12 @@ export class EnterpriseConnectionAPI extends AbstractAPI { }); } + /** + * Updates the given enterprise connection. + * @param enterpriseConnectionId - The ID of the enterprise connection to update. + * @param params - The parameters to update the enterprise connection. + * @returns The updated [`EnterpriseConnection`](https://clerk.com/docs/reference/backend/types/backend-enterprise-connection) object. + */ public async updateEnterpriseConnection(enterpriseConnectionId: string, params: UpdateEnterpriseConnectionParams) { this.requireId(enterpriseConnectionId); return this.request({ @@ -86,6 +144,10 @@ export class EnterpriseConnectionAPI extends AbstractAPI { }); } + /** + * Gets the list of enterprise connections for the instance. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`EnterpriseConnection`](https://clerk.com/docs/reference/backend/types/backend-enterprise-connection) objects and a `totalCount` property containing the total number of enterprise connections for the instance. + */ public async getEnterpriseConnectionList(params: EnterpriseConnectionListParams = {}) { return this.request>({ method: 'GET', @@ -94,6 +156,11 @@ export class EnterpriseConnectionAPI extends AbstractAPI { }); } + /** + * Gets the given enterprise connection. + * @param enterpriseConnectionId - The ID of the enterprise connection to get. + * @returns The [`EnterpriseConnection`](https://clerk.com/docs/reference/backend/types/backend-enterprise-connection) object. + */ public async getEnterpriseConnection(enterpriseConnectionId: string) { this.requireId(enterpriseConnectionId); return this.request({ @@ -102,6 +169,11 @@ export class EnterpriseConnectionAPI extends AbstractAPI { }); } + /** + * Deletes the given enterprise connection. + * @param enterpriseConnectionId - The ID of the enterprise connection to delete. + * @returns The deleted [`EnterpriseConnection`](https://clerk.com/docs/reference/backend/types/backend-enterprise-connection) object. + */ public async deleteEnterpriseConnection(enterpriseConnectionId: string) { this.requireId(enterpriseConnectionId); return this.request({ diff --git a/packages/backend/src/api/endpoints/InstanceApi.ts b/packages/backend/src/api/endpoints/InstanceApi.ts index 1e98a974db9..d725f98883d 100644 --- a/packages/backend/src/api/endpoints/InstanceApi.ts +++ b/packages/backend/src/api/endpoints/InstanceApi.ts @@ -6,74 +6,65 @@ import { AbstractAPI } from './AbstractApi'; const basePath = '/instance'; -type UpdateParams = { - /** - * Toggles test mode for this instance, allowing the use of test email addresses and phone numbers. - * - * @remarks Defaults to true for development instances. - */ +/** @generateWithEmptyComment */ +export type UpdateParams = { + /** Toggles [test mode](https://clerk.com/docs/guides/development/testing/test-emails-and-phones#set-up-test-mode) for this instance, allowing the use of test email addresses and phone numbers. Defaults to `true` for development instances. */ testMode?: boolean | null | undefined; - /** - * Whether the instance should be using the HIBP service to check passwords for breaches - */ + /** Whether the instance should be using the Have I Been Pwned (HIBP) service to check passwords for breaches. */ hibp?: boolean | null | undefined; - /** - * The "enhanced_email_deliverability" feature will send emails from "verifications@clerk.dev" instead of your domain. - * - * @remarks This can be helpful if you do not have a high domain reputation. - */ + /** Whether the instance should send emails from "verifications@clerk.dev" instead of your domain. This can be helpful if you do not have a high domain reputation. */ enhancedEmailDeliverability?: boolean | null | undefined; + /** The support email for the instance. */ supportEmail?: string | null | undefined; + /** The npm version for `@clerk/clerk-js`. */ clerkJsVersion?: string | null | undefined; + /** The development origin for the instance. */ developmentOrigin?: string | null | undefined; - /** - * For browser-like stacks such as browser extensions, Electron, or Capacitor.js the instance allowed origins need to be updated with the request origin value. - * - * @remarks For Chrome extensions popup, background, or service worker pages the origin is chrome-extension://extension_uiid. For Electron apps the default origin is http://localhost:3000. For Capacitor, the origin is capacitor://localhost. - */ + /** For browser-like stacks such as browser extensions, Electron, or Capacitor.js, the instance allowed origins need to be updated with the request origin value. For Chrome extensions popup, background, or service worker pages the origin is `chrome-extension://extension_uiid`. For Electron apps the default origin is `http://localhost:3000`. For Capacitor.js, the origin is `capacitor://localhost`. */ allowedOrigins?: Array | undefined; - /** - * Whether the instance should use URL-based session syncing in development mode (i.e. without third-party cookies). - */ + /** Whether the instance should use URL-based session syncing in development mode (i.e. without third-party cookies). */ urlBasedSessionSyncing?: boolean | null | undefined; - /** - * Overrides the sign-in strategy that is preferred when a password is required. - * - * @remarks Accepts `'password'` or `'otp'`. Pass an empty string to clear the override. Passing `null` or `undefined` leaves the current value unchanged. The value is only consulted when a password is required, and is dormant otherwise. - */ + /** Overrides the sign-in strategy that is preferred when a password is required. The value is only consulted when a password is required, and is dormant otherwise. Pass an empty string to clear the override. Passing `null` or `undefined` leaves the current value unchanged. */ preferredSignInStrategyWhenPasswordRequired?: 'password' | 'otp' | '' | null | undefined; }; -type UpdateRestrictionsParams = { +/** @generateWithEmptyComment */ +export type UpdateRestrictionsParams = { + /** Whether the instance should have [**Allowlist**](https://clerk.com/docs/guides/secure/restricting-access#allowlist) enabled. */ allowlist?: boolean | null | undefined; + /** Whether the instance should have [**Blocklist**](https://clerk.com/docs/guides/secure/restricting-access#blocklist) enabled. */ blocklist?: boolean | null | undefined; + /** Whether the instance should have [**Block email subaddresses**](https://clerk.com/docs/guides/secure/restricting-access#block-email-subaddresses) enabled. */ blockEmailSubaddresses?: boolean | null | undefined; + /** Whether the instance should have [**Block sign-ups that use disposable email domains**](https://clerk.com/docs/guides/secure/restricting-access#block-sign-ups-that-use-disposable-email-addresses) enabled. */ blockDisposableEmailDomains?: boolean | null | undefined; + /** Whether the instance should [ignore dots for Gmail addresses](https://clerk.com/docs/guides/secure/restricting-access#block-email-subaddresses). */ ignoreDotsForGmailAddresses?: boolean | null | undefined; }; -type UpdateOrganizationSettingsParams = { +/** @generateWithEmptyComment */ +export type UpdateOrganizationSettingsParams = { + /** Whether the instance should enable [Organizations](https://clerk.com/docs/guides/organizations/overview). */ enabled?: boolean | null | undefined; + /** The maximum number of [memberships allowed](https://clerk.com/docs/guides/organizations/configure#membership-limits) per Organization. */ maxAllowedMemberships?: number | null | undefined; + /** Whether [Organization admins](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions#default-roles) are allowed to delete Organizations. */ adminDeleteEnabled?: boolean | null | undefined; + /** Whether [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains) are enabled for Organizations. */ domainsEnabled?: boolean | null | undefined; - /** - * Specifies which [enrollment modes](https://clerk.com/docs/guides/organizations/add-members/verified-domains#enable-verified-domains) to enable for your Organization Domains. - * - * @remarks Supported modes are 'automatic_invitation' & 'automatic_suggestion'. - */ + /** Specifies which [enrollment modes](https://clerk.com/docs/guides/organizations/add-members/verified-domains#enable-verified-domains) to enable for your Organization's [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains). Supported modes are `'automatic_invitation'` & `'automatic_suggestion'`. */ domainsEnrollmentModes?: Array | undefined; - /** - * Specifies what the default Organization Role is for an Organization creator. - */ + /** Specifies what the default Organization [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) is for an Organization creator. */ creatorRoleId?: string | null | undefined; - /** - * Specifies what the default Organization Role is for the Organization Domains. - */ + /** Specifies what the default Organization [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) is for the Organization's [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains). */ domainsDefaultRoleId?: string | null | undefined; }; +/** @generateWithEmptyComment */ export class InstanceAPI extends AbstractAPI { + /** + * Gets the current [`Instance`](https://clerk.com/docs/reference/backend/types/backend-instance). + */ public async get() { return this.request({ method: 'GET', @@ -81,6 +72,9 @@ export class InstanceAPI extends AbstractAPI { }); } + /** + * Updates the current instance. + */ public async update(params: UpdateParams) { return this.request({ method: 'PATCH', @@ -89,6 +83,10 @@ export class InstanceAPI extends AbstractAPI { }); } + /** + * Updates the [restriction](https://clerk.com/docs/guides/secure/restricting-access) settings for the current instance. + * @returns The updated [`InstanceRestrictions`](https://clerk.com/docs/reference/backend/types/backend-instance-restrictions) object. + */ public async updateRestrictions(params: UpdateRestrictionsParams) { return this.request({ method: 'PATCH', @@ -97,6 +95,10 @@ export class InstanceAPI extends AbstractAPI { }); } + /** + * Gets the [Organization-related settings](https://clerk.com/docs/guides/organizations/configure) for the current instance. + * @returns The [`OrganizationSettings`](https://clerk.com/docs/reference/backend/types/backend-organization-settings) object. + */ public async getOrganizationSettings() { return this.request({ method: 'GET', @@ -104,6 +106,10 @@ export class InstanceAPI extends AbstractAPI { }); } + /** + * Updates the [Organization-related settings](https://clerk.com/docs/guides/organizations/configure) for the current instance. + * @returns The updated [`OrganizationSettings`](https://clerk.com/docs/reference/backend/types/backend-organization-settings) object. + */ public async updateOrganizationSettings(params: UpdateOrganizationSettingsParams) { return this.request({ method: 'PATCH', diff --git a/packages/backend/src/api/endpoints/InvitationApi.ts b/packages/backend/src/api/endpoints/InvitationApi.ts index ade0e5b6671..64f2f6221fc 100644 --- a/packages/backend/src/api/endpoints/InvitationApi.ts +++ b/packages/backend/src/api/endpoints/InvitationApi.ts @@ -9,30 +9,34 @@ import type { WithSign } from './util-types'; const basePath = '/invitations'; -type TemplateSlug = 'invitation' | 'waitlist_invitation'; +/** @inline */ +export type TemplateSlug = 'invitation' | 'waitlist_invitation'; -type CreateParams = { +/** @generateWithEmptyComment */ +export type CreateParams = { + /** The email address of the user to invite. */ emailAddress: string; + /** The number of days until the invitation expires. Defaults to `30`. */ expiresInDays?: number; + /** Whether an invitation should be created if there is already an existing invitation for this email address, or if the email address already exists in the application. Defaults to `false`. */ ignoreExisting?: boolean; + /** Whether an email invitation should be sent to the given email address. Defaults to `true`. */ notify?: boolean; + /** Metadata that can be read and set only from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}. Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata ([`User.publicMetadata`](https://clerk.com/docs/reference/backend/types/backend-user)). */ publicMetadata?: UserPublicMetadata; + /** The full URL or path where the user will land after accepting the invitation. See the [custom flow guide for handling application invitations](https://clerk.com/docs/guides/development/custom-flows/authentication/application-invitations). */ redirectUrl?: string; + /** The template slug to use for the invitation. Defaults to `invitation`. */ templateSlug?: TemplateSlug; }; -type CreateBulkParams = Array; +/** @generateWithEmptyComment */ +export type CreateBulkParams = Array; -type GetInvitationListParams = ClerkPaginationRequest<{ +/** @generateWithEmptyComment */ +export type GetInvitationListParams = ClerkPaginationRequest<{ /** - * Orders the returned invitations by a specific field and direction. - * - * Use a leading '-' for descending order, or no sign/'+' for ascending. - * - * Supported fields: - * - 'created_at' — when the invitation was created - * - 'email_address' — recipient email address - * - 'expires_at' — when the invitation expires + * Filters the invitations in a particular order. Prefix a value with `+` to sort in ascending order, or `-` to sort in descending order. Defaults to `-created_at`. * * @example * ```ts @@ -70,7 +74,12 @@ type GetInvitationListParams = ClerkPaginationRequest<{ query?: string; }>; +/** @generateWithEmptyComment */ export class InvitationAPI extends AbstractAPI { + /** + * Gets a list of non-revoked invitations for the instance, sorted by descending creation date. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`Invitation`](https://clerk.com/docs/reference/backend/types/backend-invitation) objects and a `totalCount` property containing the total number of invitations. + */ public async getInvitationList(params: GetInvitationListParams = {}) { return this.request>({ method: 'GET', @@ -79,6 +88,12 @@ export class InvitationAPI extends AbstractAPI { }); } + /** + * Creates a new invitation for the given email address, and sends the invitation email. + * + * If an email address has already been invited or already exists in your application, trying to create a new invitation will return an error. To bypass this error and create a new invitation anyways, set `ignoreExisting` to `true`. + * @returns The newly created [`Invitation`](https://clerk.com/docs/reference/backend/types/backend-invitation). + */ public async createInvitation(params: CreateParams) { return this.request({ method: 'POST', @@ -87,6 +102,12 @@ export class InvitationAPI extends AbstractAPI { }); } + /** + * Creates multiple invitations for the given email addresses, and sends the invitation emails. + * + * If an email address has already been invited or already exists in your application, trying to create a new invitation will return an error. To bypass this error and create a new invitation anyways, set `ignoreExisting` to `true`. + * @returns An array of each created [`Invitation`](https://clerk.com/docs/reference/backend/types/backend-invitation) object. + */ public async createInvitationBulk(params: CreateBulkParams) { return this.request({ method: 'POST', @@ -95,6 +116,15 @@ export class InvitationAPI extends AbstractAPI { }); } + /** + * Revokes the given invitation. + * + * Revoking an invitation makes the invitation email link unusable. However, it doesn't prevent the user from signing up if they follow the sign up flow. + * + * Only active (i.e. non-revoked) invitations can be revoked. + * @param invitationId - The ID of the invitation to revoke. + * @returns The revoked [`Invitation`](https://clerk.com/docs/reference/backend/types/backend-invitation). + */ public async revokeInvitation(invitationId: string) { this.requireId(invitationId); return this.request({ diff --git a/packages/backend/src/api/endpoints/M2MTokenApi.ts b/packages/backend/src/api/endpoints/M2MTokenApi.ts index 198179b7c3f..4bdb5d8a85b 100644 --- a/packages/backend/src/api/endpoints/M2MTokenApi.ts +++ b/packages/backend/src/api/endpoints/M2MTokenApi.ts @@ -13,82 +13,62 @@ import { AbstractAPI } from './AbstractApi'; const basePath = '/m2m_tokens'; -/** - * Format of the M2M token to create. - * - 'opaque': Opaque token with mt_ prefix - * - 'jwt': JWT signed with instance keys - */ +/** @inline */ export type M2MTokenFormat = 'opaque' | 'jwt'; -type GetM2MTokenListParams = ClerkPaginationRequest<{ - /** - * Custom machine secret key for authentication. - */ +/** @generateWithEmptyComment */ +export type GetM2MTokenListParams = ClerkPaginationRequest<{ + /** The custom machine secret key for authentication. If not provided, the SDK will use the value from the environment variables. */ machineSecretKey?: string; - /** - * The machine ID to query machine-to-machine tokens by - */ + /** The machine ID to query M2M tokens by. */ subject: string; - /** - * Whether to include revoked machine-to-machine tokens. - * - * @default false - */ + /** Whether to include revoked M2M tokens. Defaults to `false`. */ revoked?: boolean; - /** - * Whether to include expired machine-to-machine tokens. - * - * @default false - */ + /** Whether to include expired M2M tokens. Defaults to `false`. */ expired?: boolean; }>; -type CreateM2MTokenParams = { - /** - * Custom machine secret key for authentication. - */ +/** @generateWithEmptyComment */ +export type CreateM2MTokenParams = { + /** The custom machine secret key for authentication. If not provided, the SDK will use the value from the environment variables. */ machineSecretKey?: string; - /** - * Number of seconds until the token expires. - * - * @default null - Token does not expire - */ + /** The number of seconds until the token expires. Defaults to `null`, meaning the token does not expire. */ secondsUntilExpiration?: number | null; + /** Custom claims to include in the M2M token payload. */ claims?: Record | null; /** - * Enables server-side token reuse for opaque tokens when an existing token - * with matching claims/scopes still has at least this many seconds remaining. + * Enables server-side token reuse for opaque tokens. Only applies to opaque tokens (`token_format: 'opaque'`). JWT tokens (`token_format: 'jwt'`) are stateless and are never deduplicated. When set, if a non-revoked, non-expired M2M token already exists for this machine with identical `claims` and `scopes` and at least this many seconds of remaining lifetime, that existing token is returned and no new token is minted. + * + * Use this when caching tokens in application memory across requests is impractical — for example, in serverless functions, short-lived job workers, or autoscaling containers that churn faster than the token TTL. Pooling at the server collapses many redundant create calls into reuse of a single live token, which is the recommended pattern for high-volume M2M traffic. + * + * Must be strictly less than the effective token lifetime — that is, `seconds_until_expiration` when provided, or the machine's default TTL otherwise. A value greater than or equal to the lifetime is rejected with a `400` error, since no freshly-minted token would ever satisfy the requirement. */ minRemainingTtlSeconds?: number; /** - * @default 'opaque' + * The format of the M2M token to create. Defaults to `'opaque'`. Set to `'jwt'` to create a [JSON Web Token](/docs/guides/how-clerk-works/tokens-and-signatures#json-web-tokens-jwts) that can be verified locally without a network request. For a detailed comparison of the two formats, see [Token formats](/docs/guides/development/machine-auth/token-formats). */ tokenFormat?: M2MTokenFormat; }; -type RevokeM2MTokenParams = { - /** - * Custom machine secret key for authentication. - */ +/** @generateWithEmptyComment */ +export type RevokeM2MTokenParams = { + /** The custom machine secret key for authentication. If not provided, the SDK will use the value from the environment variables. */ machineSecretKey?: string; - /** - * Machine-to-machine token ID to revoke. - */ + /** The ID of the M2M token to revoke. */ m2mTokenId: string; + /** The reason for revoking the M2M token. Useful for your records. */ revocationReason?: string | null; }; -type VerifyM2MTokenParams = { - /** - * Custom machine secret key for authentication. - */ +/** @generateWithEmptyComment */ +export type VerifyM2MTokenParams = { + /** The custom machine secret key for authentication. If not provided, the SDK will use the value from the environment variables. */ machineSecretKey?: string; - /** - * Machine-to-machine token to verify. - */ + /** The M2M token to verify. */ token: string; }; +/** @generateWithEmptyComment */ export class M2MTokenApi extends AbstractAPI { #verifyOptions: JwtMachineVerifyOptions; @@ -116,6 +96,12 @@ export class M2MTokenApi extends AbstractAPI { return options; } + /** + * Gets a list of M2M tokens for the given machine. By default, the list is returned in descending order by creation date (newest first). This endpoint can be authenticated by either a Machine Secret Key or by a Clerk [Secret Key](!secret-key). + * - When fetching M2M tokens with a Machine Secret Key, only tokens associated with the authenticated machine can be retrieved. + * - When fetching M2M tokens with a Clerk Secret Key, tokens for any machine in the instance can be retrieved. + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`M2MToken`](https://clerk.com/docs/reference/backend/types/backend-m2m-token) objects and a `totalCount` property containing the total number of M2M tokens for the machine. + */ async list(queryParams: GetM2MTokenListParams) { const { machineSecretKey, ...params } = queryParams; @@ -131,6 +117,10 @@ export class M2MTokenApi extends AbstractAPI { return this.request>(requestOptions); } + /** + * Creates a new [M2M token](https://clerk.com/docs/guides/development/machine-auth/m2m-tokens) for the given machine. Must be authenticated by a Machine Secret Key. + * @returns The created [`M2MToken`](https://clerk.com/docs/reference/backend/types/backend-m2m-token) object. + */ async createToken(params?: CreateM2MTokenParams) { const { claims = null, @@ -157,6 +147,12 @@ export class M2MTokenApi extends AbstractAPI { return this.request(requestOptions); } + /** + * Revokes an [M2M token](https://clerk.com/docs/guides/development/machine-auth/m2m-tokens). This endpoint can be authenticated by either a Machine Secret Key or by a Clerk [Secret Key](!secret-key). + * - When revoking M2M tokens with a Machine Secret Key, the token will be revoked using the machine secret key. + * - When revoking M2M tokens with a Clerk Secret Key, the token will be revoked using the instance secret key. + * @returns The revoked [`M2MToken`](https://clerk.com/docs/reference/backend/types/backend-m2m-token) object. + */ async revokeToken(params: RevokeM2MTokenParams) { const { m2mTokenId, revocationReason = null, machineSecretKey } = params; @@ -198,6 +194,10 @@ export class M2MTokenApi extends AbstractAPI { return result.data; } + /** + * Verifies a [M2M token](https://clerk.com/docs/guides/development/machine-auth/m2m-tokens). Must be authenticated by a Machine Secret Key. + * @returns The verified [`M2MToken`](https://clerk.com/docs/reference/backend/types/backend-m2m-token) object. + */ async verify(params: VerifyM2MTokenParams) { const { token, machineSecretKey } = params; diff --git a/packages/backend/src/api/endpoints/MachineApi.ts b/packages/backend/src/api/endpoints/MachineApi.ts index 21bb4ff133a..14c573e5828 100644 --- a/packages/backend/src/api/endpoints/MachineApi.ts +++ b/packages/backend/src/api/endpoints/MachineApi.ts @@ -10,60 +10,49 @@ import type { WithSign } from './util-types'; const basePath = '/machines'; -type CreateMachineParams = { - /** - * The name of the machine. - */ +/** @generateWithEmptyComment */ +export type CreateMachineParams = { + /** The name of the machine. */ name: string; - /** - * Array of machine IDs that this machine will have access to. - */ + /** An array of machine IDs that the new machine will have access to. Maximum of 150 scopes per machine. */ scopedMachines?: string[]; - /** - * The default time-to-live (TTL) in seconds for tokens created by this machine. - */ + /** The default time-to-live (TTL) in seconds for tokens created by this machine. Must be at least 1 second. */ defaultTokenTtl?: number; }; -type UpdateMachineParams = { - /** - * The ID of the machine to update. - */ +/** @generateWithEmptyComment */ +export type UpdateMachineParams = { + /** The ID of the machine to update. */ machineId: string; - /** - * The name of the machine. - */ + /** The name of the machine. */ name?: string; - /** - * The default time-to-live (TTL) in seconds for tokens created by this machine. - */ + /** The default time-to-live (TTL) in seconds for tokens created by this machine. Must be at least 1 second. */ defaultTokenTtl?: number; }; -type GetMachineListParams = ClerkPaginationRequest<{ - /** - * Sorts machines by name or created_at. - * By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order. - */ +/** @generateWithEmptyComment */ +export type GetMachineListParams = ClerkPaginationRequest<{ + /** Filters machines in a particular order. Prefix a value with `+` to sort in ascending order, or `-` to sort in descending order. Defaults to `-created_at`. */ orderBy?: WithSign<'name' | 'created_at'>; - /** - * Returns machines that have a ID or name that matches the given query. - */ + /** Filters machines by ID or name. */ query?: string; }>; -type RotateMachineSecretKeyParams = { - /** - * The ID of the machine to rotate the secret key for. - */ +/** @generateWithEmptyComment */ +export type RotateMachineSecretKeyParams = { + /** The ID of the machine to rotate the secret key for. */ machineId: string; - /** - * The time in seconds that the previous secret key will remain valid after rotation. - */ + /** The time in seconds that the previous secret key will remain valid after rotation. This ensures a graceful transition period for updating applications with the new secret key. Set to `0` to immediately expire the previous key. Maximum value is `28800` seconds (8 hours). */ previousTokenTtl: number; }; +/** @generateWithEmptyComment */ export class MachineApi extends AbstractAPI { + /** + * Gets the given machine. + * @param machineId - The ID of the machine to get. + * @returns The [`Machine`](https://clerk.com/docs/reference/backend/types/backend-machine) object. + */ async get(machineId: string) { this.requireId(machineId); return this.request({ @@ -72,6 +61,10 @@ export class MachineApi extends AbstractAPI { }); } + /** + * Gets a list of machines for the instance. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`Machine`](https://clerk.com/docs/reference/backend/types/backend-machine) objects and a `totalCount` property containing the total number of machines for the instance. + */ async list(queryParams: GetMachineListParams = {}) { return this.request>({ method: 'GET', @@ -80,6 +73,10 @@ export class MachineApi extends AbstractAPI { }); } + /** + * Creates a new machine. + * @returns The created [`Machine`](https://clerk.com/docs/reference/backend/types/backend-machine) object. + */ async create(bodyParams: CreateMachineParams) { return this.request({ method: 'POST', @@ -88,6 +85,10 @@ export class MachineApi extends AbstractAPI { }); } + /** + * Updates the given machine. + * @returns The updated [`Machine`](https://clerk.com/docs/reference/backend/types/backend-machine) object. + */ async update(params: UpdateMachineParams) { const { machineId, ...bodyParams } = params; this.requireId(machineId); @@ -98,6 +99,11 @@ export class MachineApi extends AbstractAPI { }); } + /** + * Deletes the given machine. + * @param machineId - The ID of the machine to delete. + * @returns The [`Machine`](https://clerk.com/docs/reference/backend/types/backend-machine) object. + */ async delete(machineId: string) { this.requireId(machineId); return this.request({ @@ -106,6 +112,11 @@ export class MachineApi extends AbstractAPI { }); } + /** + * Gets the secret key for the given machine. + * @param machineId - The ID of the machine to get the secret key for. + * @returns The machine's secret key. + */ async getSecretKey(machineId: string) { this.requireId(machineId); return this.request({ @@ -114,6 +125,10 @@ export class MachineApi extends AbstractAPI { }); } + /** + * Rotates the secret key for the given machine. + * @returns The new secret key. + */ async rotateSecretKey(params: RotateMachineSecretKeyParams) { const { machineId, previousTokenTtl } = params; this.requireId(machineId); @@ -127,10 +142,11 @@ export class MachineApi extends AbstractAPI { } /** - * Creates a new machine scope, allowing the specified machine to access another machine. + * Creates a new machine scope, allowing the specified machine to access another machine. Maximum of 150 scopes per machine. * - * @param machineId - The ID of the machine that will have access to another machine. - * @param toMachineId - The ID of the machine that will be scoped to the current machine. + * @param machineId - The ID of the machine that will have access to the target machine. + * @param toMachineId - The ID of the machine that will be accessible by the source machine. + * @returns The created [`MachineScope`](https://clerk.com/docs/reference/backend/types/backend-machine-scope) object. */ async createScope(machineId: string, toMachineId: string) { this.requireId(machineId); @@ -144,10 +160,11 @@ export class MachineApi extends AbstractAPI { } /** - * Deletes a machine scope, removing access from one machine to another. + * Deletes the given machine scope, removing access from one machine to another. * - * @param machineId - The ID of the machine that has access to another machine. - * @param otherMachineId - The ID of the machine that is being accessed. + * @param machineId - The ID of the machine that has access to the target machine. + * @param otherMachineId - The ID of the machine that will no longer be accessible by the source machine. + * @returns The deleted [`MachineScope`](https://clerk.com/docs/reference/backend/types/backend-machine-scope) object. */ async deleteScope(machineId: string, otherMachineId: string) { this.requireId(machineId); diff --git a/packages/backend/src/api/endpoints/OAuthApplicationsApi.ts b/packages/backend/src/api/endpoints/OAuthApplicationsApi.ts index 62594cf0339..bc998aa8628 100644 --- a/packages/backend/src/api/endpoints/OAuthApplicationsApi.ts +++ b/packages/backend/src/api/endpoints/OAuthApplicationsApi.ts @@ -9,54 +9,49 @@ import type { WithSign } from './util-types'; const basePath = '/oauth_applications'; -type CreateOAuthApplicationParams = { +/** @generateWithEmptyComment */ +export type CreateOAuthApplicationParams = { /** - * The name of the new OAuth application. - * - * @remarks Max length: 256 + * A descriptive name for the OAuth application (e.g., "My Web App", "My Mobile App"). Maximum length: 256 characters. */ name: string; - /** - * An array of redirect URIs of the new OAuth application - */ + /** An array of redirect URIs for the OAuth application. */ redirectUris?: Array | null | undefined; - /** - * Define the allowed scopes for the new OAuth applications that dictate the user payload of the OAuth user info endpoint. Available scopes are `profile`, `email`, `public_metadata`, `private_metadata`. Provide the requested scopes as a string, separated by spaces. - */ + /** Scopes for the OAuth application that dictate the user payload of the OAuth user info endpoint. Available scopes are `profile`, `email`, `public_metadata`, `private_metadata`. Provide the requested scopes as a string, separated by spaces. */ scopes?: string | null | undefined; - /** - * If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow. - */ + /** Whether the OAuth application is public. If `true`, the Proof Key of Code Exchange (PKCE) flow can be used. */ public?: boolean | null | undefined; }; -type UpdateOAuthApplicationParams = CreateOAuthApplicationParams & { - /** - * The ID of the OAuth application to update - */ +/** @generateWithEmptyComment */ +export type UpdateOAuthApplicationParams = CreateOAuthApplicationParams & { + /** The ID of the OAuth application to update. */ oauthApplicationId: string; }; -type RevokeOAuthApplicationTokenParams = { - /** - * The ID of the OAuth application for which to revoke the token. - */ +/** @generateWithEmptyComment */ +export type RevokeOAuthApplicationTokenParams = { + /** The ID of the OAuth application for which to revoke the token. */ oauthApplicationId: string; - /** - * The opaque OAuth access token or refresh token to revoke. - */ + /** The opaque OAuth access token or refresh token to revoke. */ token: string; }; -type GetOAuthApplicationListParams = ClerkPaginationRequest<{ +/** @generateWithEmptyComment */ +export type GetOAuthApplicationListParams = ClerkPaginationRequest<{ /** - * Sorts OAuth applications by name or created_at. - * By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order. + * Returns OAuth applications in a particular order. Prefix a value with `+` to sort in ascending order, or `-` to sort in descending order. Defaults to `-created_at`. */ orderBy?: WithSign<'name' | 'created_at'>; }>; +/** @generateWithEmptyComment */ export class OAuthApplicationsApi extends AbstractAPI { + /** + * Gets a list of OAuth applications for the instance. By default, the list is returned in descending order by creation date (newest first). + * @param params - The parameters to get the OAuth applications with. + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`OAuthApplication`](https://clerk.com/docs/reference/backend/types/backend-oauth-application) objects and a `totalCount` property containing the total number of OAuth applications. + */ public async list(params: GetOAuthApplicationListParams = {}) { return this.request>({ method: 'GET', @@ -65,6 +60,11 @@ export class OAuthApplicationsApi extends AbstractAPI { }); } + /** + * Gets the given OAuth application. + * @param oauthApplicationId - The ID of the OAuth application to get. + * @returns The [`OAuthApplication`](https://clerk.com/docs/reference/backend/types/backend-oauth-application) object. + */ public async get(oauthApplicationId: string) { this.requireId(oauthApplicationId); @@ -74,6 +74,11 @@ export class OAuthApplicationsApi extends AbstractAPI { }); } + /** + * Creates a new OAuth application. + * @param params - The parameters to create the OAuth application with. + * @returns The created [`OAuthApplication`](https://clerk.com/docs/reference/backend/types/backend-oauth-application) object. + */ public async create(params: CreateOAuthApplicationParams) { return this.request({ method: 'POST', @@ -82,6 +87,10 @@ export class OAuthApplicationsApi extends AbstractAPI { }); } + /** + * Updates the given OAuth application. + * @returns The updated [`OAuthApplication`](https://clerk.com/docs/reference/backend/types/backend-oauth-application) object. + */ public async update(params: UpdateOAuthApplicationParams) { const { oauthApplicationId, ...bodyParams } = params; @@ -94,6 +103,11 @@ export class OAuthApplicationsApi extends AbstractAPI { }); } + /** + * Deletes the given OAuth application. + * @param oauthApplicationId - The ID of the OAuth application to delete. + * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object) object. + */ public async delete(oauthApplicationId: string) { this.requireId(oauthApplicationId); @@ -103,6 +117,11 @@ export class OAuthApplicationsApi extends AbstractAPI { }); } + /** + * Rotates the secret of the given OAuth application. When the client secret is rotated, ensure that you update it in your authorized OAuth clients. + * @param oauthApplicationId - The ID of the OAuth application to rotate the secret of. + * @returns The [`OAuthApplication`](https://clerk.com/docs/reference/backend/types/backend-oauth-application) object. + */ public async rotateSecret(oauthApplicationId: string) { this.requireId(oauthApplicationId); @@ -112,6 +131,9 @@ export class OAuthApplicationsApi extends AbstractAPI { }); } + /** + * Revokes both the OAuth access token and refresh token for the associated grant for the given [`OAuthApplication`](/docs/reference/backend/types/backend-oauth-application). The request may specify either token. + */ public async revokeToken(params: RevokeOAuthApplicationTokenParams) { const { oauthApplicationId, ...bodyParams } = params; diff --git a/packages/backend/src/api/endpoints/OrganizationApi.ts b/packages/backend/src/api/endpoints/OrganizationApi.ts index fa3396871cf..7c571e0c035 100644 --- a/packages/backend/src/api/endpoints/OrganizationApi.ts +++ b/packages/backend/src/api/endpoints/OrganizationApi.ts @@ -17,232 +17,280 @@ import type { WithSign } from './util-types'; const basePath = '/organizations'; -type MetadataParams = { +/** @inline */ +export type MetadataParams = { + /** Metadata that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}, but can be set only from the Backend API. */ publicMetadata?: TPublic; + /** Metadata that can be read and set only from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}. */ privateMetadata?: TPrivate; }; -type GetOrganizationListParams = ClerkPaginationRequest<{ +/** @generateWithEmptyComment */ +export type GetOrganizationListParams = ClerkPaginationRequest<{ + /** Whether to include the number of members in the Organization. */ includeMembersCount?: boolean; + /** Filters Organizations by ID, name, or slug. Uses exact match for ID and partial match for name and slug. */ query?: string; + /** Filters Organizations in a particular order. Prefix a value with `+` to sort in ascending order, or `-` to sort in descending order. Defaults to `-created_at`. */ orderBy?: WithSign<'name' | 'created_at' | 'members_count'>; + /** Filters Organizations by ID. Accepts up to 100 Organization IDs. */ organizationId?: string[]; }>; -type CreateParams = { +/** @generateWithEmptyComment */ +export type CreateParams = { + /** The name of the Organization. */ name: string; + /** The slug of the Organization. */ slug?: string; - /* The User id for the user creating the organization. The user will become an administrator for the organization. */ + /** The ID of the user creating the Organization. The user will become an [admin](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions#default-roles) for the Organization. */ createdBy?: string; + /** The maximum number of memberships allowed in the Organization. `0` means unlimited. */ maxAllowedMemberships?: number; } & MetadataParams; -type GetOrganizationParams = ({ organizationId: string } | { slug: string }) & { +/** @generateWithEmptyComment */ +export type GetOrganizationParams = ( + | { + /** The ID of the Organization to get. */ + organizationId: string; + } + | { + /** The slug of the Organization to get. */ + slug: string; + } +) & { + /** Whether to include the number of members in the Organization. */ includeMembersCount?: boolean; }; -type UpdateParams = { +/** @inline */ +export type UpdateParams = { + /** The name to update the Organization with. */ name?: string; + /** The slug to update the Organization with. */ slug?: string; + /** Whether the Organization allows admins to delete users. */ adminDeleteEnabled?: boolean; + /** The maximum number of memberships allowed in the Organization. `0` means unlimited. */ maxAllowedMemberships?: number; - /** - * Metadata visible to your Frontend and Backend APIs. - * - * @deprecated Updating metadata via `updateOrganization` is deprecated. Use - * `updateOrganizationMetadata` for partial updates (deep merge) or - * `replaceOrganizationMetadata` for full replacement. + * @deprecated Updating metadata via [`updateOrganization()`](https://clerk.com/docs/reference/backend/organization/update-organization) is deprecated. Use [`updateOrganizationMetadata()`](https://clerk.com/docs/reference/backend/organization/update-organization-metadata) for partial updates (deep merge) or [`replaceOrganizationMetadata()`](https://clerk.com/docs/reference/backend/organization/replace-organization-metadata) for full replacement. */ publicMetadata?: OrganizationPublicMetadata; - /** - * Metadata visible only to your Backend API. - * - * @deprecated Updating metadata via `updateOrganization` is deprecated. Use - * `updateOrganizationMetadata` for partial updates (deep merge) or - * `replaceOrganizationMetadata` for full replacement. + * @deprecated Updating metadata via [`updateOrganization()`](https://clerk.com/docs/reference/backend/organization/update-organization) is deprecated. Use [`updateOrganizationMetadata()`](https://clerk.com/docs/reference/backend/organization/update-organization-metadata) for partial updates (deep merge) or [`replaceOrganizationMetadata()`](https://clerk.com/docs/reference/backend/organization/replace-organization-metadata) for full replacement. */ privateMetadata?: OrganizationPrivateMetadata; }; -type UpdateLogoParams = { +/** @inline */ +export type UpdateLogoParams = { + /** The file to upload as the logo. */ file: Blob | File; + /** The ID of the user uploading the logo. */ uploaderUserId?: string; }; -type UpdateMetadataParams = MetadataParams; +/** @inline */ +export type UpdateMetadataParams = MetadataParams; -type GetOrganizationMembershipListParams = ClerkPaginationRequest<{ +/** @generateWithEmptyComment */ +export type GetOrganizationMembershipListParams = ClerkPaginationRequest<{ + /** The ID of the Organization to get the list of memberships for. */ organizationId: string; - /** - * Sorts Organization memberships by phone_number, email_address, created_at, first_name, last_name or username. - * By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order. + * Filters Organization memberships in a particular order. Prefix a value with `+` to sort in ascending order, or `-` to sort in descending order. Defaults to `-created_at`. */ orderBy?: WithSign<'phone_number' | 'email_address' | 'created_at' | 'first_name' | 'last_name' | 'username'>; - /** - * Returns users with the user ids specified. For each user id, the `+` and `-` can be - * prepended to the id, which denote whether the respective user id should be included or - * excluded from the result set. Accepts up to 100 user ids. Any user ids not found are ignored. + * Filters Organization memberships by user ID. Accepts up to 100 user IDs. */ userId?: string[]; - - /* Returns users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored. */ + /** Filters Organization memberships by email address. Accepts up to 100 email addresses. */ emailAddress?: string[]; - - /* Returns users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored. */ + /** Filters Organization memberships by phone number. Accepts up to 100 phone numbers. */ phoneNumber?: string[]; - - /* Returns users with the specified usernames. Accepts up to 100 usernames. Any usernames not found are ignored. */ + /** Filters Organization memberships by username. Accepts up to 100 usernames. */ username?: string[]; - - /* Returns users with the specified web3 wallet addresses. Accepts up to 100 web3 wallet addresses. Any web3 wallet addressed not found are ignored. */ + /** Filters Organization memberships by web3 wallet address. Accepts up to 100 web3 wallet addresses. */ web3Wallet?: string[]; - - /* Returns users with the specified Roles. Accepts up to 100 Roles. Any Roles not found are ignored. */ + /** Filters Organization memberships by Role. Accepts up to 100 Roles. */ role?: OrganizationMembershipRole[]; - /** - * Returns users that match the given query. - * For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names. - * The query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well. + * Filters Organization memberships matching the given query across email addresses, phone numbers, usernames, Web3 wallet addresses, user IDs, first names, and last names. Partial matches supported. For example, `query=hello` will match a user with the email `HELLO@example.com`. */ query?: string; - /** - * Returns users with emails that match the given query, via case-insensitive partial match. - * For example, `email_address_query=ello` will match a user with the email `HELLO@example.com`. + * Filters Organization memberships by email address. Accepts up to 100 email addresses. Partial matches supported. For example, `emailAddressQuery=ello` will match a user with the email `HELLO@example.com`. */ emailAddressQuery?: string; /** - * Returns users with phone numbers that match the given query, via case-insensitive partial match. - * For example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`. + * Filters Organization memberships by phone number. Accepts up to 100 phone numbers. Partial matches supported. For example, `phoneNumberQuery=555` will match a user with the phone number `+1555xxxxxxx`. */ phoneNumberQuery?: string; - /** - * Returns users with usernames that match the given query, via case-insensitive partial match. - * For example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`. + * Filters Organization memberships by username. Accepts up to 100 usernames. Partial matches supported. For example, `usernameQuery=CoolUser` will match a user with the username `SomeCoolUser`. */ usernameQuery?: string; - - /* Returns users with names that match the given query, via case-insensitive partial match. */ + /** Filters Organization memberships by name. Accepts up to 100 names. Partial matches supported. For example, `nameQuery=John Doe` will match a user with the name `John Doe`. */ nameQuery?: string; - /** - * Returns users whose last session activity was before the given date (with millisecond precision). - * Example: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23. + * Filters Organization memberships by last session activity before the given date (with millisecond precision). For example, use `1700690400000` to get users whose last session activity was before 2023-11-23. */ lastActiveAtBefore?: number; /** - * Returns users whose last session activity was after the given date (with millisecond precision). - * Example: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23. + * Filters Organization memberships by last session activity after the given date (with millisecond precision). For example, use `1700690400000` to get users whose last session activity was after 2023-11-23. */ lastActiveAtAfter?: number; - /** - * Returns users who have been created before the given date (with millisecond precision). - * Example: use 1730160000000 to retrieve users who have been created before 2024-10-29. + * Filters Organization memberships by creation date before the given date (with millisecond precision). For example, use `1730160000000` to get users who have been created before 2024-10-29. */ createdAtBefore?: number; - /** - * Returns users who have been created after the given date (with millisecond precision). - * Example: use 1730160000000 to retrieve users who have been created after 2024-10-29. + * Filters Organization memberships by creation date after the given date (with millisecond precision). For example, use `1730160000000` to get users who have been created after 2024-10-29. */ createdAtAfter?: number; }>; -type GetInstanceOrganizationMembershipListParams = ClerkPaginationRequest<{ +/** @generateWithEmptyComment */ +export type GetInstanceOrganizationMembershipListParams = ClerkPaginationRequest<{ /** - * Sorts Organization memberships by phone_number, email_address, created_at, first_name, last_name or username. - * By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order. + * Filters Organization memberships in a particular order. Prefix a value with `+` to sort in ascending order, or `-` to sort in descending order. Defaults to `-created_at`. */ orderBy?: WithSign<'phone_number' | 'email_address' | 'created_at' | 'first_name' | 'last_name' | 'username'>; }>; -type CreateOrganizationMembershipParams = { +/** @generateWithEmptyComment */ +export type CreateOrganizationMembershipParams = { + /** The ID of the Organization the user is being added to. */ organizationId: string; + /** The ID of the user to be added to the Organization. */ userId: string; + /** The [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) to assign to the user. */ role: OrganizationMembershipRole; }; -type UpdateOrganizationMembershipParams = CreateOrganizationMembershipParams; +/** @generateWithEmptyComment */ +export type UpdateOrganizationMembershipParams = CreateOrganizationMembershipParams; -type UpdateOrganizationMembershipMetadataParams = { +/** @generateWithEmptyComment */ +export type UpdateOrganizationMembershipMetadataParams = { + /** The ID of the Organization the membership belongs to. */ organizationId: string; + /** The ID of the user the membership belongs to. */ userId: string; } & MetadataParams; -type DeleteOrganizationMembershipParams = { +/** @generateWithEmptyComment */ +export type DeleteOrganizationMembershipParams = { + /** The ID of the Organization to remove the user from. */ organizationId: string; + /** The ID of the user to remove from the Organization. */ userId: string; }; -type CreateOrganizationInvitationParams = { +/** @generateWithEmptyComment */ +export type CreateOrganizationInvitationParams = { + /** The ID of the Organization the user is being invited to. */ organizationId: string; + /** The email address of the user being invited. */ emailAddress: string; + /** The [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) to assign to the user. */ role: OrganizationMembershipRole; + /** The number of days until the invitation expires. Defaults to `30`. */ expiresInDays?: number; + /** The ID of the user creating the invitation. */ inviterUserId?: string; + /** Metadata that can be read and set only from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}. */ privateMetadata?: OrganizationInvitationPrivateMetadata; + /** Metadata that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}, but can be set only from the Backend API. */ publicMetadata?: OrganizationInvitationPublicMetadata; + /** The full URL or path where the user will land after accepting the invitation. */ redirectUrl?: string; }; -type CreateBulkOrganizationInvitationParams = Array<{ - emailAddress: string; - role: OrganizationMembershipRole; - expiresInDays?: number; - inviterUserId?: string; - privateMetadata?: OrganizationInvitationPrivateMetadata; - publicMetadata?: OrganizationInvitationPublicMetadata; - redirectUrl?: string; -}>; +/** @inline */ +export type CreateBulkOrganizationInvitationParams = Array>; -type GetOrganizationInvitationListParams = ClerkPaginationRequest<{ +/** @generateWithEmptyComment */ +export type GetOrganizationInvitationListParams = ClerkPaginationRequest<{ + /** The ID of the Organization to get the list of invitations for. */ organizationId: string; + /** Filters Organization invitations by status. Accepts up to 100 statuses. */ status?: OrganizationInvitationStatus[]; }>; -type GetOrganizationInvitationParams = { +/** @generateWithEmptyComment */ +export type GetOrganizationInvitationParams = { + /** The ID of the Organization to get the invitation for. */ organizationId: string; + /** The ID of the Organization invitation to get. */ invitationId: string; }; -type RevokeOrganizationInvitationParams = { +/** @generateWithEmptyComment */ +export type RevokeOrganizationInvitationParams = { + /** The ID of the Organization to revoke the invitation from. */ organizationId: string; + /** The ID of the Organization invitation to revoke. */ invitationId: string; + /** The ID of the user revoking the invitation. */ requestingUserId?: string; }; -type GetOrganizationDomainListParams = { +/** @generateWithEmptyComment */ +export type GetOrganizationDomainListParams = { + /** The ID of the Organization to get the list of domains for. */ organizationId: string; + /** Maximum number of items returned per request. Must be an integer greater than zero and less than `501`. Can be used for paginating the results together with offset. Defaults to `10`. */ limit?: number; + /** Skip the first `offset` items when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`. Defaults to `0`. */ offset?: number; }; -type CreateOrganizationDomainParams = { +/** @generateWithEmptyComment */ +export type CreateOrganizationDomainParams = { + /** The ID of the Organization to create the domain for. */ organizationId: string; + /** The name of the domain. */ name: string; + /** The enrollment mode that determines how matching users are added to the Organization. + * + *
      + *
    • `manual_invitation`: No automatic enrollment. Users with a matching email domain are not given any [invitation](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-invitations) or [suggestion](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-suggestions); an [admin](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions#default-roles) must invite them manually.
      • + *
    • `automatic_invitation`: Users with a matching email domain automatically receive a pending [invitation](https://clerk.com/docs/reference/types/organization-invitation) (assigned the Organization's default role) which they can accept to join.
      • + *
    • `automatic_suggestion`: Users with a matching email domain automatically receive a [suggestion](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-suggestions) to join, which they can request.
      • + *
    + */ enrollmentMode: OrganizationEnrollmentMode; + /** Whether the domain is verified. Defaults to `true`. */ verified?: boolean; }; -type UpdateOrganizationDomainParams = { +/** @generateWithEmptyComment */ +export type UpdateOrganizationDomainParams = { + /** The ID of the Organization to update the domain for. */ organizationId: string; + /** The ID of the domain to update. */ domainId: string; } & Partial; -type DeleteOrganizationDomainParams = { +/** @generateWithEmptyComment */ +export type DeleteOrganizationDomainParams = { + /** The ID of the Organization to delete the domain for. */ organizationId: string; + /** The ID of the domain to delete. */ domainId: string; }; +/** @generateWithEmptyComment */ export class OrganizationAPI extends AbstractAPI { + /** + * Gets the list of Organizations for the instance. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`Organization`](https://clerk.com/docs/reference/backend/types/backend-organization) objects and a `totalCount` property containing the total number of Organizations for the instance. + */ public async getOrganizationList(params?: GetOrganizationListParams) { return this.request>({ method: 'GET', @@ -251,6 +299,7 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** Creates an [`Organization`](https://clerk.com/docs/reference/backend/types/backend-organization). */ public async createOrganization(params: CreateParams) { return this.request({ method: 'POST', @@ -259,6 +308,7 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** Gets an [Organization](https://clerk.com/docs/reference/backend/types/backend-organization). */ public async getOrganization(params: GetOrganizationParams) { const { includeMembersCount } = params; const organizationIdOrSlug = 'organizationId' in params ? params.organizationId : params.slug; @@ -273,6 +323,12 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Updates an [Organization](https://clerk.com/docs/reference/backend/types/backend-organization). + * @param organizationId - The ID of the Organization to update. + * @param params - The parameters to update the Organization with. + * @returns The updated [Organization](https://clerk.com/docs/reference/backend/types/backend-organization). + */ public async updateOrganization(organizationId: string, params: UpdateParams) { this.requireId(organizationId); @@ -310,6 +366,12 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Updates the logo of the given Organization. + * @param organizationId - The ID of the Organization to update the logo for. + * @param params - The parameters to update the logo with. + * @returns The updated [`Organization`](https://clerk.com/docs/reference/backend/types/backend-organization). + */ public async updateOrganizationLogo(organizationId: string, params: UpdateLogoParams) { this.requireId(organizationId); @@ -326,6 +388,11 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Deletes the logo of the given Organization. + * @param organizationId - The ID of the Organization to delete the logo for. + * @returns The deleted [`Organization`](https://clerk.com/docs/reference/backend/types/backend-organization). + */ public async deleteOrganizationLogo(organizationId: string) { this.requireId(organizationId); @@ -335,6 +402,18 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Updates the metadata for the given Organization, by merging existing values with the provided parameters. + * + * A "deep" merge will be performed - "deep" means that any nested JSON objects will be merged as well. You can remove metadata keys at any level by setting their value to `null`. + * + * @param organizationId - The ID of the Organization to update the metadata for. + * @param params - The parameters to update the metadata with. + * @returns The updated [`Organization`](https://clerk.com/docs/reference/backend/types/backend-organization). + * + * > [!TIP] + * > If you want to fully replace the existing metadata instead of merging, use [`replaceOrganizationMetadata()`](https://clerk.com/docs/reference/backend/organization/replace-organization-metadata). + */ public async updateOrganizationMetadata(organizationId: string, params: UpdateMetadataParams) { this.requireId(organizationId); @@ -346,9 +425,18 @@ export class OrganizationAPI extends AbstractAPI { } /** - * Replace an organization's metadata. Supplied fields are overwritten in full; - * fields omitted from `params` are left unchanged. Prefer - * `updateOrganizationMetadata` for partial updates with deep-merge semantics. + * Replaces the metadata associated with the specified Organization. Unlike [`updateOrganizationMetadata()`](/docs/reference/backend/organization/update-organization-metadata), which deep-merges into the existing metadata, this method uses replace semantics: when a metadata field is provided, its previous value is overwritten in full with no merging at any level. + * + * The distinction is at two layers: + * - **Top-level field omission preserves the existing value.** Each top-level field (`publicMetadata`, `privateMetadata`) is handled independently. If you don't include a field in the request, the stored value for that field is left untouched. + * - **The value inside a provided field is replaced in full.** When you do include a field, its previous content is discarded — any nested keys present before but absent in the new value are dropped. There is no merge. + * + * For the provided field, you can also send: + * - `{}` (empty object) to clear the field. + * - `null` to overwrite the field with a JSON `null` value. Prefer `{}` unless you specifically need a stored `null`. + * @param organizationId - The ID of the Organization to replace the metadata for. + * @param params - The metadata to replace. + * @returns The updated [`Organization`](https://clerk.com/docs/reference/backend/types/backend-organization). */ public async replaceOrganizationMetadata(organizationId: string, params: MetadataParams) { this.requireId(organizationId); @@ -360,6 +448,11 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Deletes the given Organization. + * @param organizationId - The ID of the Organization to delete. + * @returns The deleted [`Organization`](https://clerk.com/docs/reference/backend/types/backend-organization). + */ public async deleteOrganization(organizationId: string) { this.requireId(organizationId); @@ -369,6 +462,14 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Gets the list of Organization memberships for the specified Organization. By default, the list is returned in descending order by creation date (newest first). + * + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`OrganizationMembership`](https://clerk.com/docs/reference/backend/types/backend-organization-membership) objects and a `totalCount` property containing the total number of Organization memberships for the Organization. + * + * > [!TIP] + * > To get the list of Organization memberships **for your instance**, use [`getInstanceOrganizationMembershipList()`](/docs/reference/backend/organization/get-instance-organization-membership-list). + */ public async getOrganizationMembershipList(params: GetOrganizationMembershipListParams) { const { organizationId, ...queryParams } = params; this.requireId(organizationId); @@ -380,6 +481,14 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Gets the list of Organization memberships for the instance. By default, the list is returned in descending order by creation date (newest first). + * + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`OrganizationMembership`](https://clerk.com/docs/reference/backend/types/backend-organization-membership) objects and a `totalCount` property containing the total number of Organization memberships for the instance. + * + * > [!TIP] + * > To get the list of Organization memberships **for a specific Organization**, use [`getOrganizationMembershipList()`](/docs/reference/backend/organization/get-organization-membership-list). + */ public async getInstanceOrganizationMembershipList(params: GetInstanceOrganizationMembershipListParams) { return this.request>({ method: 'GET', @@ -388,6 +497,10 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Creates a membership to an Organization for a user directly (circumventing the need for an invitation). + * @returns The newly created [`OrganizationMembership`](https://clerk.com/docs/reference/backend/types/backend-organization-membership) object. + */ public async createOrganizationMembership(params: CreateOrganizationMembershipParams) { const { organizationId, ...bodyParams } = params; this.requireId(organizationId); @@ -399,6 +512,10 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Updates a user's [`OrganizationMembership`](https://clerk.com/docs/reference/backend/types/backend-organization-membership). + * @returns The updated [`OrganizationMembership`](https://clerk.com/docs/reference/backend/types/backend-organization-membership) object. + */ public async updateOrganizationMembership(params: UpdateOrganizationMembershipParams) { const { organizationId, userId, ...bodyParams } = params; this.requireId(organizationId); @@ -410,6 +527,13 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Updates the metadata for the given Organization membership, by merging existing values with the provided parameters. + * + * A "deep" merge will be performed - "deep" means that any nested JSON objects will be merged as well. You can remove metadata keys at any level by setting their value to `null`. + * + * @returns The updated [`OrganizationMembership`](https://clerk.com/docs/reference/backend/types/backend-organization-membership). + */ public async updateOrganizationMembershipMetadata(params: UpdateOrganizationMembershipMetadataParams) { const { organizationId, userId, ...bodyParams } = params; @@ -420,6 +544,12 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Removes a user from the given Organization. + * @param organizationId - The ID of the Organization to remove the user from. + * @param userId - The ID of the user to remove from the Organization. + * @returns The deleted [`OrganizationMembership`](https://clerk.com/docs/reference/backend/types/backend-organization-membership). + */ public async deleteOrganizationMembership(params: DeleteOrganizationMembershipParams) { const { organizationId, userId } = params; this.requireId(organizationId); @@ -430,6 +560,10 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Gets the list of Organization invitations for the specified Organization. + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`OrganizationInvitation`](https://clerk.com/docs/reference/backend/types/backend-organization-invitation) objects and a `totalCount` property containing the total number of Organization invitations for the Organization. + */ public async getOrganizationInvitationList(params: GetOrganizationInvitationListParams) { const { organizationId, ...queryParams } = params; this.requireId(organizationId); @@ -441,6 +575,10 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Creates an invitation for a user to join an Organization. + * @returns The newly created [`OrganizationInvitation`](https://clerk.com/docs/reference/backend/types/backend-organization-invitation) object. + */ public async createOrganizationInvitation(params: CreateOrganizationInvitationParams) { const { organizationId, ...bodyParams } = params; this.requireId(organizationId); @@ -452,6 +590,11 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** Creates multiple invitations for users to join an Organization. + * @param organizationId - The ID of the Organization to create the invitations for. + * @param params - The parameters to create the invitations with. + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`OrganizationInvitation`](https://clerk.com/docs/reference/backend/types/backend-organization-invitation) objects and a `totalCount` property containing the total number of Organization invitations. + */ public async createOrganizationInvitationBulk( organizationId: string, params: CreateBulkOrganizationInvitationParams, @@ -465,6 +608,7 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** Gets an [`OrganizationInvitation`](https://clerk.com/docs/reference/backend/types/backend-organization-invitation). */ public async getOrganizationInvitation(params: GetOrganizationInvitationParams) { const { organizationId, invitationId } = params; this.requireId(organizationId); @@ -476,6 +620,10 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Revokes an invitation from a user for the given Organization. + * @returns The revoked [`OrganizationInvitation`](https://clerk.com/docs/reference/backend/types/backend-organization-invitation). + */ public async revokeOrganizationInvitation(params: RevokeOrganizationInvitationParams) { const { organizationId, invitationId, ...bodyParams } = params; this.requireId(organizationId); @@ -487,6 +635,10 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Gets the list of [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains) for the given Organization. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`OrganizationDomain`](https://clerk.com/docs/reference/backend/types/backend-organization-domain) objects and a `totalCount` property containing the total number of Verified Domains for the Organization. + */ public async getOrganizationDomainList(params: GetOrganizationDomainListParams) { const { organizationId, ...queryParams } = params; this.requireId(organizationId); @@ -498,6 +650,10 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Creates a new [Verified Domain](https://clerk.com/docs/guides/organizations/add-members/verified-domains) for the given Organization. By default, the domain is verified, but can be optionally set to unverified. + * @returns The newly created [`OrganizationDomain`](https://clerk.com/docs/reference/backend/types/backend-organization-domain) object. + */ public async createOrganizationDomain(params: CreateOrganizationDomainParams) { const { organizationId, ...bodyParams } = params; this.requireId(organizationId); @@ -512,6 +668,10 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Updates a [Verified Domain](https://clerk.com/docs/guides/organizations/add-members/verified-domains) for the given Organization. + * @returns The updated [`OrganizationDomain`](https://clerk.com/docs/reference/backend/types/backend-organization-domain) object. + */ public async updateOrganizationDomain(params: UpdateOrganizationDomainParams) { const { organizationId, domainId, ...bodyParams } = params; this.requireId(organizationId); @@ -524,6 +684,10 @@ export class OrganizationAPI extends AbstractAPI { }); } + /** + * Deletes a [Verified Domain](https://clerk.com/docs/guides/organizations/add-members/verified-domains) for the given Organization. + * @returns The deleted [`OrganizationDomain`](https://clerk.com/docs/reference/backend/types/backend-organization-domain) object. + */ public async deleteOrganizationDomain(params: DeleteOrganizationDomainParams) { const { organizationId, domainId } = params; this.requireId(organizationId); diff --git a/packages/backend/src/api/endpoints/PhoneNumberApi.ts b/packages/backend/src/api/endpoints/PhoneNumberApi.ts index 300077a4275..93c8be2d6bb 100644 --- a/packages/backend/src/api/endpoints/PhoneNumberApi.ts +++ b/packages/backend/src/api/endpoints/PhoneNumberApi.ts @@ -4,21 +4,36 @@ import { AbstractAPI } from './AbstractApi'; const basePath = '/phone_numbers'; -type CreatePhoneNumberParams = { +/** @generateWithEmptyComment */ +export type CreatePhoneNumberParams = { + /** The ID of the user to create the phone number for. */ userId: string; + /** The phone number to assign to the specified user. Must be in [E.164 format](https://en.wikipedia.org/wiki/E.164). */ phoneNumber: string; + /** Whether the phone number should be verified. Defaults to `false`. */ verified?: boolean; + /** Whether the phone number should be the primary phone number. Defaults to `false`, unless it is the first phone number added to the user. */ primary?: boolean; + /** Whether the phone number should be reserved for [multi-factor authentication](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options#multi-factor-authentication). The phone number must also be verified. If there are no other reserved [second factors](!second-factor-verification), the phone number will be set as the default second factor. Defaults to `false`. */ reservedForSecondFactor?: boolean; }; -type UpdatePhoneNumberParams = { +/** @inline */ +export type UpdatePhoneNumberParams = { + /** Whether the phone number should be verified. Defaults to `false`. */ verified?: boolean; + /** Whether the phone number should be the primary phone number. Defaults to `false`, unless it is the first phone number added to the user. */ primary?: boolean; + /** Whether the phone number should be reserved for [multi-factor authentication](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options#multi-factor-authentication). The phone number must also be verified. If there are no other reserved [second factors](!second-factor-verification), the phone number will be set as the default second factor. Defaults to `false`. */ reservedForSecondFactor?: boolean; }; +/** @generateWithEmptyComment */ export class PhoneNumberAPI extends AbstractAPI { + /** + * Gets the given [`PhoneNumber`](https://clerk.com/docs/reference/backend/types/backend-phone-number). + * @param phoneNumberId - The ID of the phone number to get. + */ public async getPhoneNumber(phoneNumberId: string) { this.requireId(phoneNumberId); @@ -28,6 +43,10 @@ export class PhoneNumberAPI extends AbstractAPI { }); } + /** + * Creates a new phone number for the given user. + * @returns The created [`PhoneNumber`](https://clerk.com/docs/reference/backend/types/backend-phone-number) object. + */ public async createPhoneNumber(params: CreatePhoneNumberParams) { return this.request({ method: 'POST', @@ -36,6 +55,12 @@ export class PhoneNumberAPI extends AbstractAPI { }); } + /** + * Updates the given phone number. + * @param phoneNumberId - The ID of the phone number to update. + * @param params - The parameters to update the phone number. + * @returns The updated [`PhoneNumber`](https://clerk.com/docs/reference/backend/types/backend-phone-number) object. + */ public async updatePhoneNumber(phoneNumberId: string, params: UpdatePhoneNumberParams = {}) { this.requireId(phoneNumberId); @@ -46,6 +71,11 @@ export class PhoneNumberAPI extends AbstractAPI { }); } + /** + * Deletes the given phone number. + * @param phoneNumberId - The ID of the phone number to delete. + * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object) object. + */ public async deletePhoneNumber(phoneNumberId: string) { this.requireId(phoneNumberId); diff --git a/packages/backend/src/api/endpoints/RedirectUrlApi.ts b/packages/backend/src/api/endpoints/RedirectUrlApi.ts index 5f0c72165ed..218d1685f46 100644 --- a/packages/backend/src/api/endpoints/RedirectUrlApi.ts +++ b/packages/backend/src/api/endpoints/RedirectUrlApi.ts @@ -5,11 +5,18 @@ import { AbstractAPI } from './AbstractApi'; const basePath = '/redirect_urls'; -type CreateRedirectUrlParams = { +/** @generateWithEmptyComment */ +export type CreateRedirectUrlParams = { + /** The full URL value prefixed with `https://` or a custom scheme. For example, `https://my-app.com/oauth-callback` or `my-app://oauth-callback`. */ url: string; }; +/** @generateWithEmptyComment */ export class RedirectUrlAPI extends AbstractAPI { + /** + * Gets a list of whitelisted redirect URLs for the instance. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`RedirectUrl`](https://clerk.com/docs/reference/backend/types/backend-redirect-url) objects and a `totalCount` property containing the total number of redirect URLs. + */ public async getRedirectUrlList() { return this.request>({ method: 'GET', @@ -18,6 +25,10 @@ export class RedirectUrlAPI extends AbstractAPI { }); } + /** + * Gets the given [`RedirectUrl`](https://clerk.com/docs/reference/backend/types/backend-redirect-url). + * @param redirectUrlId - The ID of the redirect URL to get. + */ public async getRedirectUrl(redirectUrlId: string) { this.requireId(redirectUrlId); return this.request({ @@ -26,6 +37,10 @@ export class RedirectUrlAPI extends AbstractAPI { }); } + /** + * Creates a new redirect URL for the instance. + * @returns The created [`RedirectUrl`](https://clerk.com/docs/reference/backend/types/backend-redirect-url) object. + */ public async createRedirectUrl(params: CreateRedirectUrlParams) { return this.request({ method: 'POST', @@ -34,6 +49,11 @@ export class RedirectUrlAPI extends AbstractAPI { }); } + /** + * Deletes the given redirect URL. + * @param redirectUrlId - The ID of the redirect URL to delete. + * @returns The deleted [`RedirectUrl`](https://clerk.com/docs/reference/backend/types/backend-redirect-url) object. + */ public async deleteRedirectUrl(redirectUrlId: string) { this.requireId(redirectUrlId); return this.request({ diff --git a/packages/backend/src/api/endpoints/SessionApi.ts b/packages/backend/src/api/endpoints/SessionApi.ts index 170408ea5ac..cc46fcef3b1 100644 --- a/packages/backend/src/api/endpoints/SessionApi.ts +++ b/packages/backend/src/api/endpoints/SessionApi.ts @@ -9,27 +9,46 @@ import { AbstractAPI } from './AbstractApi'; const basePath = '/sessions'; -type SessionListParams = ClerkPaginationRequest<{ +/** @generateWithEmptyComment */ +export type SessionListParams = ClerkPaginationRequest<{ + /** The ID of the client to get sessions for. */ clientId?: string; + /** The ID of the user to get sessions for. */ userId?: string; + /** The status of the sessions to get. */ status?: SessionStatus; }>; -type RefreshTokenParams = { +/** @inline */ +export type RefreshTokenParams = { + /** The expired token to refresh. */ expired_token: string; + /** The refresh token to refresh. */ refresh_token: string; + /** The origin of the request. */ request_origin: string; + /** The originating IP address of the request. */ request_originating_ip?: string; + /** The headers of the request. */ request_headers?: Record; + /** Whether to use suffixed cookies. */ suffixed_cookies?: boolean; + /** The format of the token to refresh. */ format?: 'token' | 'cookie'; }; -type CreateSessionParams = { +/** @generateWithEmptyComment */ +export type CreateSessionParams = { + /** The ID of the user to create a session for. */ userId: string; }; +/** @generateWithEmptyComment */ export class SessionAPI extends AbstractAPI { + /** + * Gets a list of sessions for either the specified client or user. Requires either `clientId` or `userId` to be provided. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`Session`](https://clerk.com/docs/reference/backend/types/backend-session) objects and a `totalCount` property containing the total number of sessions. + */ public async getSessionList(params: SessionListParams = {}) { return this.request>({ method: 'GET', @@ -38,6 +57,10 @@ export class SessionAPI extends AbstractAPI { }); } + /** + * Gets the given [`Session`](https://clerk.com/docs/reference/backend/types/backend-session). + * @param sessionId - The ID of the session to get. + */ public async getSession(sessionId: string) { this.requireId(sessionId); return this.request({ @@ -46,6 +69,10 @@ export class SessionAPI extends AbstractAPI { }); } + /** + * Creates a new session for the given user. + * @returns The created [`Session`](https://clerk.com/docs/reference/backend/types/backend-session). + */ public async createSession(params: CreateSessionParams) { return this.request({ method: 'POST', @@ -54,6 +81,11 @@ export class SessionAPI extends AbstractAPI { }); } + /** + * Revokes the given session. The user will be signed out from the client the session is associated with. + * @param sessionId - The ID of the session to revoke. + * @returns The revoked [`Session`](https://clerk.com/docs/reference/backend/types/backend-session). + */ public async revokeSession(sessionId: string) { this.requireId(sessionId); return this.request({ @@ -72,16 +104,13 @@ export class SessionAPI extends AbstractAPI { } /** - * Gets a session token or generates a JWT using a specified template. - * - * @param sessionId - The ID of the session for which to generate the token - * @param template - The name of the JWT template configured in the Clerk Dashboard. - * @param expiresInSeconds - The expiration time for the token in seconds. - * If not provided, uses the default expiration. + * Gets a session token or generates a JWT using a specified template that is defined in the [**JWT templates**](https://dashboard.clerk.com/~/jwt-templates) page in the Clerk Dashboard. * - * @returns A promise that resolves to the generated token + * @param sessionId - The ID of the session to get the token for. + * @param template - The name of the JWT template configured in the Clerk Dashboard to generate a new token from. + * @param expiresInSeconds - The expiration time for the token in seconds. If not provided, uses the default expiration. * - * @throws {Error} When sessionId is invalid or empty + * @returns The generated token. */ public async getToken(sessionId: string, template?: string, expiresInSeconds?: number) { this.requireId(sessionId); @@ -102,7 +131,19 @@ export class SessionAPI extends AbstractAPI { return this.request(requestOptions); } - public async refreshSession(sessionId: string, params: RefreshTokenParams & { format: 'token' }): Promise; + /** + * Refreshes the given session. + * @param sessionId - The ID of the session to refresh. + * @param params - The parameters to refresh the session. + * @returns The refreshed token. + */ + public async refreshSession( + sessionId: string, + params: RefreshTokenParams & { + /** The format of the token to refresh. */ + format: 'token'; + }, + ): Promise; public async refreshSession(sessionId: string, params: RefreshTokenParams & { format: 'cookie' }): Promise; public async refreshSession(sessionId: string, params: RefreshTokenParams): Promise; public async refreshSession(sessionId: string, params: RefreshTokenParams): Promise { diff --git a/packages/backend/src/api/endpoints/SignInTokenApi.ts b/packages/backend/src/api/endpoints/SignInTokenApi.ts index 21209b794ae..0635e97e635 100644 --- a/packages/backend/src/api/endpoints/SignInTokenApi.ts +++ b/packages/backend/src/api/endpoints/SignInTokenApi.ts @@ -2,14 +2,22 @@ import { joinPaths } from '../../util/path'; import type { SignInToken } from '../resources/SignInTokens'; import { AbstractAPI } from './AbstractApi'; -type CreateSignInTokensParams = { +/** @generateWithEmptyComment */ +export type CreateSignInTokensParams = { + /** The ID of the user to create the sign-in token for. */ userId: string; + /** The number of seconds until the sign-in token expires. By default, the duration is `2592000` (30 days). */ expiresInSeconds: number; }; const basePath = '/sign_in_tokens'; +/** @generateWithEmptyComment */ export class SignInTokenAPI extends AbstractAPI { + /** + * Creates a new sign-in token for the given user. By default, sign-in tokens expire in 30 days. You can optionally specify a custom expiration time in seconds using the `expiresInSeconds` parameter. + * @returns The created [`SignInToken`](https://clerk.com/docs/reference/backend/types/backend-sign-in-token) object. + */ public async createSignInToken(params: CreateSignInTokensParams) { return this.request({ method: 'POST', @@ -18,6 +26,11 @@ export class SignInTokenAPI extends AbstractAPI { }); } + /** + * Revokes the given sign-in token. + * @param signInTokenId - The ID of the sign-in token to revoke. + * @returns The revoked [`SignInToken`](https://clerk.com/docs/reference/backend/types/backend-sign-in-token) object. + */ public async revokeSignInToken(signInTokenId: string) { this.requireId(signInTokenId); return this.request({ diff --git a/packages/backend/src/api/endpoints/TestingTokenApi.ts b/packages/backend/src/api/endpoints/TestingTokenApi.ts index b6fa9d266e7..d5a9cf0035d 100644 --- a/packages/backend/src/api/endpoints/TestingTokenApi.ts +++ b/packages/backend/src/api/endpoints/TestingTokenApi.ts @@ -3,7 +3,12 @@ import { AbstractAPI } from './AbstractApi'; const basePath = '/testing_tokens'; +/** @generateWithEmptyComment */ export class TestingTokenAPI extends AbstractAPI { + /** + * Creates a [Testing Token](https://clerk.com/docs/guides/development/testing/overview#testing-tokens) for the instance. + * @returns The created [`TestingToken`](https://clerk.com/docs/reference/backend/types/backend-testing-token) object. + */ public async createTestingToken() { return this.request({ method: 'POST', diff --git a/packages/backend/src/api/endpoints/UserApi.ts b/packages/backend/src/api/endpoints/UserApi.ts index ef64db32dac..d3053261556 100644 --- a/packages/backend/src/api/endpoints/UserApi.ts +++ b/packages/backend/src/api/endpoints/UserApi.ts @@ -18,51 +18,85 @@ import type { WithSign } from './util-types'; const basePath = '/users'; -type UserCountParams = { +/** @generateWithEmptyComment */ +export type UserCountParams = { + /** Counts users with emails that match the given query, via case-insensitive partial match. For example, `emailAddress=hello` will match a user with the email `HELLO@example.com`. Accepts up to 100 email addresses. */ emailAddress?: string[]; + /** Counts users with phone numbers that match the given query, via case-insensitive partial match. For example, `phoneNumber=555` will match a user with the phone number `+1555xxxxxxx`. Accepts up to 100 phone numbers. */ phoneNumber?: string[]; + /** Counts users with usernames that match the given query, via case-insensitive partial match. For example, `username=CoolUser` will match a user with the username `SomeCoolUser`. Accepts up to 100 usernames. */ username?: string[]; + /** Counts users with Web3 wallet addresses that match the given query, via case-insensitive partial match. For example, `web3Wallet=0x1234567890` will match a user with the Web3 wallet address `0x1234567890`. Accepts up to 100 Web3 wallet addresses. */ web3Wallet?: string[]; + /** Counts users matching the given query across email addresses, phone numbers, usernames, Web3 wallet addresses, user IDs, first names, and last names. Partial matches supported. For example, `query=hello` will match a user with the email `HELLO@example.com`. */ query?: string; + /** Counts users with the specified user IDs. Accepts up to 100 user IDs. */ userId?: string[]; + /** Counts users with the specified external IDs. Accepts up to 100 external IDs. */ externalId?: string[]; }; -type UserListParams = ClerkPaginationRequest< - UserCountParams & { - orderBy?: WithSign< - | 'created_at' - | 'updated_at' - | 'email_address' - | 'web3wallet' - | 'first_name' - | 'last_name' - | 'phone_number' - | 'username' - | 'last_active_at' - | 'last_sign_in_at' - >; - /** - * @deprecated Use `lastActiveAtAfter` instead. This parameter will be removed in a future version. - */ - last_active_at_since?: number; - lastActiveAtBefore?: number; - lastActiveAtAfter?: number; - createdAtBefore?: number; - createdAtAfter?: number; - lastSignInAtAfter?: number; - lastSignInAtBefore?: number; - organizationId?: string[]; - } ->; +/** @generateWithEmptyComment */ +export type UserListParams = ClerkPaginationRequest<{ + /** Filters users with the specified email addresses. Accepts up to 100 email addresses. */ + emailAddress?: string[]; + /** Filters users with the specified phone numbers. Accepts up to 100 phone numbers. */ + phoneNumber?: string[]; + /** Filters users with the specified usernames. Accepts up to 100 usernames. */ + username?: string[]; + /** Filters users with the specified Web3 wallet addresses. Accepts up to 100 Web3 wallet addresses. */ + web3Wallet?: string[]; + /** Filters users matching the given query across email addresses, phone numbers, usernames, Web3 wallet addresses, user IDs, first names, and last names. Partial matches supported. */ + query?: string; + /** Filters users with the specified user IDs. Accepts up to 100 user IDs. */ + userId?: string[]; + /** Filters users with the specified external IDs. Accepts up to 100 external IDs. */ + externalId?: string[]; + /** Filters users in a particular order. Prefix a value with `+` to sort in ascending order, or `-` to sort in descending order. Defaults to `-created_at`.*/ + orderBy?: WithSign< + | 'created_at' + | 'updated_at' + | 'email_address' + | 'web3wallet' + | 'first_name' + | 'last_name' + | 'phone_number' + | 'username' + | 'last_active_at' + | 'last_sign_in_at' + >; + /** + * @deprecated Use `lastActiveAtAfter` instead. This parameter will be removed in a future version. + */ + last_active_at_since?: number; + /** Filters users who were last active before the given date (with millisecond precision). */ + lastActiveAtBefore?: number; + /** Filters users who were last active after the given date (with millisecond precision). */ + lastActiveAtAfter?: number; + /** Filters users who were created before the given date (with millisecond precision). */ + createdAtBefore?: number; + /** Filters users who were created after the given date (with millisecond precision). */ + createdAtAfter?: number; + /** Filters users who were last signed in after the given date (with millisecond precision). */ + lastSignInAtAfter?: number; + /** Filters users who were last signed in before the given date (with millisecond precision). */ + lastSignInAtBefore?: number; + /** Filters users who are members of the specified Organizations. Accepts up to 100 Organization IDs. */ + organizationId?: string[]; +}>; -type UserMetadataParams = { +/** @inline */ +export type UserMetadataParams = { + /** Metadata that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. */ publicMetadata?: UserPublicMetadata; + /** Metadata that can be read and set only from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}. */ privateMetadata?: UserPrivateMetadata; + /** Metadata that can be read and set from the Frontend API. It's considered unsafe because it can be modified from the Frontend API. */ unsafeMetadata?: UserUnsafeMetadata; }; -type PasswordHasher = +/** @inline */ +export type PasswordHasher = | 'argon2i' | 'argon2id' | 'awscognito' @@ -79,168 +113,290 @@ type PasswordHasher = | 'md5_phpass' | 'ldap_ssha'; -type UserPasswordHashingParams = { +/** @inline */ +export type UserPasswordHashingParams = { + /** In case you already have the password digests and not the passwords, you can use them for the newly created user via this property. The digests should be generated with one of the supported algorithms. The hashing algorithm can be specified using the `password_hasher` property. */ passwordDigest: string; + /** + * The hashing algorithm that was used to generate the password digest. Must be one of the supported algorithms. For password hashers considered insecure (currently, `md5`, `md5_salted`, `sha256`, `sha256_salted`, `sha512_symfony`), the corresponding user password hashes will be transparently migrated to `bcrypt` (a secure hasher) upon the user's first successful password sign in. Insecure schemes are marked with `(insecure)` in the list below. + * + *
      + *
    • `awscognito`
      • + *
        + *
      • When set, `password_digest` must be in the format of `awscognito###`.
        • + *
      • Upon a successful migration, `password_hasher` will be updated to `bcrypt`, and `password_digest` will be updated to a `bcrypt` hash.
        • + *
      • See the [migration guide](/docs/guides/development/migrating/cognito) for usage details.
        • + *
      + *
    • [`bcrypt`](https://en.wikipedia.org/wiki/Bcrypt)
      • + *
        + *
      • When set, `password_digest` must be in the format of `$$$`.
        • + *
      + *
    • [`bcrypt_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/)
      • + *
        + *
      • This is the Django-specific variant of Bcrypt, using SHA256 hashing function. When set, `password_digest` must be in the format of (as exported from Django): `bcrypt_sha256$$$$`.
        • + *
      + *
    • [`bcrypt_peppered`](https://github.com/heartcombo/devise)
      • + *
        + *
      • Used in implementations such as Devise for Ruby on Rails applications. Identical to `bcrypt` except that a `pepper` string is appended to the input before hashing. When set, `password_digest` must be in the format of `$$$$`.
        • + *
      + *
    • [`md5` (insecure)](https://en.wikipedia.org/wiki/MD5)
      • + *
        + *
      • When set, `password_digest` must be in the format of `5f4dcc3b5aa765d61d8327deb882cf99`.
        • + *
      + *
    • [`md5_salted` (insecure)](https://en.wikipedia.org/wiki/MD5)
      • + *
        + *
      • When set, `password_digest` must be in the format of `salt$hash`.
        • + *
      • _salt:_ The salt used to generate the above hash.
        • + *
      • _hash:_ A 32-length hex string.
        • + *
      + *
    • [`pbkdf2_sha1`](https://en.wikipedia.org/wiki/PBKDF2)
      • + *
        + *
      • When set, `password_digest` must be in the format of `pbkdf2_sha1$$$` or `pbkdf2_sha1$$$$`.
        • + *
      • Accepts the salt as a hex-encoded string. If the salt is not a valid hex string, the raw bytes will be used instead. Accepts the hash as a hex-encoded string. Optionally accepts the key length as the last parameter (defaults to 32).
        • + *
      + *
    • [`pbkdf2_sha256`](https://en.wikipedia.org/wiki/PBKDF2)
      • + *
        + *
      • This is the PBKDF2 algorithm using the SHA256 hashing function. When set, `password_digest` must be in the format of `pbkdf2_sha256$$$`.
        • + *
      • Both the salt and the hash are expected to be base64-encoded.
        • + *
      + *
    • [`pbkdf2_sha512`](https://en.wikipedia.org/wiki/PBKDF2)
      • + *
        + *
      • This is the PBKDF2 algorithm using the SHA512 hashing function. When set, `password_digest` must be in the format of `pbkdf2_sha512$$$`.
        • + *
      • The salt is expected to be an unencoded string literal, and the hash should be hex-encoded.
        • + *
      + *
    • [`pbkdf2_sha512_hex`](https://en.wikipedia.org/wiki/PBKDF2)
      • + *
        + *
      • This is the PBKDF2 algorithm using the SHA512 hashing function. When set, `password_digest` must be in the format of `pbkdf2_sha512_hex$$$`.
        • + *
      • Both the salt and the hash are expected to be hex-encoded.
        • + *
      + *
    • [`pbkdf2_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/)
      • + *
        + *
      • This is the Django-specific variant of PBKDF2. When set, `password_digest` must be in the format of (as exported from Django): `pbkdf2_sha256$$$`.
        • + *
      • The salt is expected to be un-encoded, the hash is expected base64-encoded.
        • + *
      + *
    • [`phpass`](https://www.openwall.com/phpass/)
      • + *
        + *
      • Portable public domain password hashing framework for use in PHP applications. When set, `password_digest` must be in the format of `$P$`.
        • + *
      • `$P$` is the prefix used to identify `phpass` hashes.
        • + *
      • _rounds:_ A single character encoding a 6-bit integer representing the number of rounds used.
        • + *
      • _salt:_ Eight characters drawn from `[./0-9A-Za-z]`, providing a 48-bit salt.
        • + *
      • _encoded-checksum:_ 22 characters drawn from the same set, encoding the 128-bit checksum with MD5.
        • + *
      + *
    • [`scrypt_firebase`](https://firebaseopensource.com/projects/firebase/scrypt/)
      • + *
        + *
      • The Firebase-specific variant of scrypt. When set, `password_digest` must be in the format of `$$$$$`.
        • + *
      • _hash:_ The actual Base64 hash. This can be retrieved when exporting the user from Firebase.
        • + *
      • _salt:_ The salt used to generate the above hash. Again, this is given when exporting the user from Firebase.
        • + *
      • _signer key:_ The base64 encoded signer key.
        • + *
      • _salt separator:_ The base64 encoded salt separator.
        • + *
      • _rounds:_ The number of rounds the algorithm needs to run.
        • + *
      • _memory cost:_ The cost of the algorithm run.
        • + *
      + *
    • [`scrypt_werkzeug`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.security.generate_password_hash)
      • + *
        + *
      • The Werkzeug-specific variant of scrypt. When set, `password_digest` must be in the format of `$$$`.
        • + *
      • _algorithm args:_ The algorithm used to generate the hash.
        • + *
      • _salt:_ The salt used to generate the above hash.
        • + *
      • _hash:_ The actual Base64 hash.
        • + *
      + *
    • [`sha256` (insecure)](https://en.wikipedia.org/wiki/SHA-2)
      • + *
        + *
      • When set, `password_digest` must be a 64-length hex string. For example: `9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08`.
        • + *
      + *
    • [`sha256_salted` (insecure)](https://en.wikipedia.org/wiki/SHA-2)
      • + *
        + *
      • When set, `password_digest` must be in the format of `salt$hash`.
        • + *
      • _salt:_ The salt used to generate the above hash.
        • + *
      • _hash:_ A 64-length hex string.
        • + *
      + *
    • [`argon2`](https://argon2.online/) variants: `argon2i` and `argon2id`.
      • + *
        + *
      • Parts are demarcated by the `$` character, with the first part identifying the algorithm variant The middle part is a comma-separated list of the encoding options (memory, iterations, parallelism). The final part is the actual digest.
        • + *
      • When set, `password_digest` must be in the format of `$argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc`.
        • + *
      • For the argon2id case, the value of the algorithm in the first part of the digest is `argon2id`: `$argon2id$v=19$m=64,t=4,p=8$Z2liZXJyaXNo$iGXEpMBTDYQ8G/71tF0qGjxRHEmR3gpGULcE93zUJVU`.
        • + *
      + *
    • [`sha512_symfony` (insecure)](https://symfony.com/doc/current/security/passwords.html)
      • + *
        + *
      • The legacy Symfony `MessageDigestPasswordEncoder` algorithm. We currently only support the SHA512 variant. When set, `password_digest` must be in the format of `sha512_symfony$iterations$salt$hash`.
        • + *
      • _iterations:_ A number greater than 0.
        • + *
      • _salt:_ The salt used to generate the above hash.
        • + *
      • _hash:_ The actual Base64 hash.
        • + *
      + *
    + * + * If you need support for any particular hashing algorithm, [contact support](https://clerk.com/contact/support). + */ passwordHasher: PasswordHasher; }; -type CreateUserParams = { +/** @generateWithEmptyComment */ +export type CreateUserParams = { + /** The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance. */ externalId?: string; + /** The email address(es) to assign to the user. Must be unique across your instance. The first email address will be set as the users primary email address. */ emailAddress?: string[]; + /** The phone number(s) to assign to the user. Must be unique across your instance. The first phone number will be set as the users primary phone number. */ phoneNumber?: string[]; + /** The username to assign to the user. Must be unique across your instance. */ username?: string; + /** The plaintext password to give the user. Must be at least 8 characters long, and can't be in any list of hacked passwords. */ password?: string; + /** The first name to assign to the user. */ firstName?: string; + /** The last name to assign to the user. */ lastName?: string; - /** The locale of the user in BCP-47 format. */ + /** The locale of the user in BCP-47 format (e.g. `'en-US'`, `'fr-FR'`). */ locale?: string; + /** When set to `true`, all password checks are skipped. It is recommended to use this method only when migrating plaintext passwords to Clerk. Upon migration the user base should be prompted to pick stronger password. */ skipPasswordChecks?: boolean; + /** When set to `true`, password is not required anymore when creating the user and can be omitted. This is useful when you are trying to create a user that doesn't have a password, in an instance that is using passwords. **You cannot use this flag if password is the only way for a user to sign into your instance.** */ skipPasswordRequirement?: boolean; + /** When set to `true`, all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk. */ skipLegalChecks?: boolean; + /** A custom timestamp denoting when the user accepted legal requirements, specified in RFC3339 format (e.g. `'2012-10-20T07:15:20.902Z'`). */ legalAcceptedAt?: Date; + /** + * If TOTP is enabled on the instance, you can provide the secret to enable it on the newly created user without the need to reset it. Currently, the supported options are: + *
      + *
    • Period: 30 seconds
      • + *
    • Code length: 6 digits
      • + *
    • Algorithm: SHA1
      • + *
    + */ totpSecret?: string; + /** If backup codes are enabled on the instance, you can provide them to enable it on the newly created user without the need to reset them. You must provide the backup codes in plain format or the corresponding bcrypt digest. */ backupCodes?: string[]; + /** A custom timestamp denoting when the user signed up to the application, specified in RFC3339 format (e.g. `'2012-10-20T07:15:20.902Z'`). */ createdAt?: Date; - /** When set to `true`, the user is created already banned and cannot sign in. Requires the same plan support as the ban user endpoint. */ + /** When set to `true`, the user is created already banned and cannot sign in. */ banned?: boolean; - /** When set to `true`, the user is created already locked. Requires the user lockout feature to be enabled on the instance. */ + /** When set to `true`, the user is created already locked. Requires the [user lockout feature](https://clerk.com/docs/guides/secure/user-lockout#lock-a-user-programmatically) to be enabled on the instance. */ locked?: boolean; } & UserMetadataParams & (UserPasswordHashingParams | object); -type UpdateUserParams = { +/** @inline */ +export type UpdateUserParams = { /** The first name to assign to the user. */ firstName?: string; - - /** The last name of the user. */ + /** The last name to assign to the user. */ lastName?: string; - - /** The username to give to the user. It must be unique across your instance. */ + /** The username to assign to the user. Must be unique across your instance. */ username?: string; - - /** The plaintext password to give the user. Must be at least 8 characters long, and can not be in any list of hacked passwords. */ + /** The plaintext password to assign to the user. Must be at least 8 characters long, and can not be in any list of hacked passwords. */ password?: string; - - /** Set it to true if you're updating the user's password and want to skip any password policy settings check. This parameter can only be used when providing a password. */ + /** When set to `true`, all password checks are skipped. It is recommended to use this method only when migrating plaintext passwords to Clerk. Upon migration the user base should be prompted to pick stronger password. */ skipPasswordChecks?: boolean; - - /** Set to true to sign out the user from all their active sessions once their password is updated. This parameter can only be used when providing a password. */ + /** When set to `true`, the user is signed out from all their active sessions once their password is updated. */ signOutOfOtherSessions?: boolean; - - /** The ID of the email address to set as primary. It must be verified, and present on the current user. */ + /** The ID of the email address to set as primary. Must be verified and present on the given user. */ primaryEmailAddressID?: string; - - /** If set to true, the user will be notified that their primary email address has changed. By default, no notification is sent. */ + /** When set to `true`, the user is notified that their primary email address has changed. */ notifyPrimaryEmailAddressChanged?: boolean; - - /** The ID of the phone number to set as primary. It must be verified, and present on the current user. */ + /** The ID of the phone number to set as primary. Must be verified and present on the given user. */ primaryPhoneNumberID?: string; - - /** The ID of the web3 wallets to set as primary. It must be verified, and present on the current user. */ + /** The ID of the web3 wallets to set as primary. Must be verified and present on the given user. */ primaryWeb3WalletID?: string; - - /** The ID of the image to set as the user's profile image */ + /** The ID of the image to set as the user's profile image. */ profileImageID?: string; - /** - * In case TOTP is configured on the instance, you can provide the secret to enable it on the specific user without the need to reset it. - * Please note that currently the supported options are: - * - Period: 30 seconds - * - Code length: 6 digits - * - Algorithm: SHA1 + * In case TOTP is configured on the instance, you can provide the secret to enable it on the specific user without the need to reset it. Currently, the supported options are: + *
      + *
    • Period: 30 seconds
      • + *
    • Code length: 6 digits
      • + *
    • Algorithm: SHA1
      • + *
    */ totpSecret?: string; - - /** If Backup Codes are configured on the instance, you can provide them to enable it on the specific user without the need to reset them. You must provide the backup codes in plain format or the corresponding bcrypt digest. */ + /** If backup codes are configured on the instance, you can provide them to enable it on the specific user without the need to reset them. You must provide the backup codes in plain format or the corresponding bcrypt digest. */ backupCodes?: string[]; - - /** The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance. */ + /** The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your entire instance. */ externalId?: string; - - /** A custom timestamp denoting when the user signed up to the application, specified in RFC3339 format (e.g. 2012-10-20T07:15:20.902Z). */ + /** A custom timestamp denoting when the user signed up to the application, specified in RFC3339 format (e.g. `'2012-10-20T07:15:20.902Z'`). */ createdAt?: Date; - - /** When set to true all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk. */ + /** When set to `true`, all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk. */ skipLegalChecks?: boolean; - - /** A custom timestamp denoting when the user accepted legal requirements, specified in RFC3339 format (e.g. 2012-10-20T07:15:20.902Z). */ + /** A custom timestamp denoting when the user accepted legal requirements, specified in RFC3339 format (e.g. `'2012-10-20T07:15:20.902Z'`). */ legalAcceptedAt?: Date; - - /** The locale of the user in BCP-47 format. */ + /** The locale of the user in BCP-47 format (e.g. `'en-US'`). */ locale?: string; - - /** If true, the user can delete themselves with the Frontend API. */ + /** If `true`, the user can delete themselves with the Frontend API. */ deleteSelfEnabled?: boolean; - - /** If true, the user can create Organizations with the Frontend API. */ + /** If `true`, the user can create Organizations with the Frontend API. */ createOrganizationEnabled?: boolean; - - /** The maximum number of Organizations the user can create. 0 means unlimited. */ + /** The maximum number of Organizations the user can create. `0` means unlimited. */ createOrganizationsLimit?: number; - /** - * Metadata visible to your Frontend and Backend APIs. - * - * @deprecated Updating metadata via `updateUser` is deprecated. Use - * `updateUserMetadata` for partial updates (deep merge) or - * `replaceUserMetadata` for full replacement. + * @deprecated Updating metadata via `updateUser()` is deprecated. Use [`updateUserMetadata()`](https://clerk.com/docs/reference/backend/user/update-user-metadata) for partial updates (deep merge) or [`replaceUserMetadata()`](https://clerk.com/docs/reference/backend/user/replace-user-metadata) for full replacement. */ publicMetadata?: UserPublicMetadata; - /** - * Metadata visible only to your Backend API. - * - * @deprecated Updating metadata via `updateUser` is deprecated. Use - * `updateUserMetadata` for partial updates (deep merge) or - * `replaceUserMetadata` for full replacement. + * @deprecated Updating metadata via `updateUser()` is deprecated. Use [`updateUserMetadata()`](https://clerk.com/docs/reference/backend/user/update-user-metadata) for partial updates (deep merge) or [`replaceUserMetadata()`](https://clerk.com/docs/reference/backend/user/replace-user-metadata) for full replacement. */ privateMetadata?: UserPrivateMetadata; - /** - * Metadata writeable from both the Frontend and Backend APIs. - * - * @deprecated Updating metadata via `updateUser` is deprecated. Use - * `updateUserMetadata` for partial updates (deep merge) or - * `replaceUserMetadata` for full replacement. + * @deprecated Updating metadata via `updateUser()` is deprecated. Use [`updateUserMetadata()`](https://clerk.com/docs/reference/backend/user/update-user-metadata) for partial updates (deep merge) or [`replaceUserMetadata()`](https://clerk.com/docs/reference/backend/user/replace-user-metadata) for full replacement. */ unsafeMetadata?: UserUnsafeMetadata; } & (UserPasswordHashingParams | object); -type GetOrganizationMembershipListParams = ClerkPaginationRequest<{ +/** @generateWithEmptyComment */ +export type GetOrganizationMembershipListParams = ClerkPaginationRequest<{ + /** The ID of the user to get the list of Organization memberships for. */ userId: string; }>; -type GetOrganizationInvitationListParams = ClerkPaginationRequest<{ +/** @generateWithEmptyComment */ +export type GetOrganizationInvitationListParams = ClerkPaginationRequest<{ + /** The ID of the user to get the list of Organization invitations for. */ userId: string; + /** Filters the invitations by the provided status. */ status?: OrganizationInvitationStatus; }>; -type VerifyPasswordParams = { +/** @generateWithEmptyComment */ +export type VerifyPasswordParams = { + /** The ID of the user to verify the password for. */ userId: string; + /** The password to verify. */ password: string; }; -type VerifyTOTPParams = { +/** @generateWithEmptyComment */ +export type VerifyTOTPParams = { + /** The ID of the user to verify the TOTP for. */ userId: string; + /** The TOTP or backup code to verify. */ code: string; }; -type DeleteUserPasskeyParams = { +/** @generateWithEmptyComment */ +export type DeleteUserPasskeyParams = { + /** The ID of the user to delete the passkey for. */ userId: string; + /** The ID of the passkey identification to delete. */ passkeyIdentificationId: string; }; -type DeleteWeb3WalletParams = { +/** @generateWithEmptyComment */ +export type DeleteWeb3WalletParams = { + /** The ID of the user to delete the Web3 wallet for. */ userId: string; + /** The ID of the Web3 wallet identification to delete. */ web3WalletIdentificationId: string; }; -type DeleteUserExternalAccountParams = { +/** @generateWithEmptyComment */ +export type DeleteUserExternalAccountParams = { + /** The ID of the user to delete the external account for. */ userId: string; + /** The ID of the external account to delete. */ externalAccountId: string; }; -type SetPasswordCompromisedParams = { +/** @inline */ +export type SetPasswordCompromisedParams = { + /** Whether to revoke all sessions of the user. Defaults to `false`. */ revokeAllSessions?: boolean; }; @@ -258,7 +414,12 @@ type UserID = { userId: string; }; +/** @generateWithEmptyComment */ export class UserAPI extends AbstractAPI { + /** + * Retrieves the list of users in your instance. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property that contains an array of [`User`](https://clerk.com/docs/reference/backend/types/backend-user) objects, and a `totalCount` property that indicates the total number of users in your instance. + */ public async getUserList(params: UserListParams = {}) { const { limit, offset, orderBy, ...userCountParams } = params; // TODO(dimkl): Temporary change to populate totalCount using a 2nd BAPI call to /users/count endpoint @@ -275,6 +436,10 @@ export class UserAPI extends AbstractAPI { return { data, totalCount } as PaginatedResourceResponse; } + /** + * Gets a [`User`](https://clerk.com/docs/reference/backend/types/backend-user) for the specified user ID. + * @param userId - The ID of the user to retrieve. + */ public async getUser(userId: string) { this.requireId(userId); return this.request({ @@ -283,6 +448,18 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Creates a [`User`](https://clerk.com/docs/reference/backend/types/backend-user) in your instance. + * + * Your settings in the [Clerk Dashboard](https://dashboard.clerk.com) determine how you should setup your user model. Anything **Required** will need to be provided when creating a user. Trying to add a field that isn't enabled will result in an error. + * + * Any email address and phone number created using this method will be automatically verified. + * + * > [!CAUTION] + * > + * > This endpoint is [rate limited](/docs/guides/how-clerk-works/system-limits). For development instances, a rate limit rule of **100 requests per 10 seconds** is applied. + * > For production instances, that limit goes up to **1000 requests per 10 seconds**. + */ public async createUser(params: CreateUserParams) { return this.request({ method: 'POST', @@ -291,6 +468,10 @@ export class UserAPI extends AbstractAPI { }); } + /** Updates the given [`User`](https://clerk.com/docs/reference/backend/types/backend-user). + * @param userId - The ID of the user to update. + * @param params - The user attributes to update. + */ public async updateUser(userId: string, params: UpdateUserParams = {}) { this.requireId(userId); @@ -349,6 +530,12 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Updates the profile image for the given user. To remove the profile image, see [`deleteUserProfileImage()`](https://clerk.com/docs/reference/backend/user/delete-user-profile-image). + * @param userId - The ID of the user to update the profile image for. + * @param params - The file to set as the user's profile image. + * @returns The updated [`User`](https://clerk.com/docs/reference/backend/types/backend-user). + */ public async updateUserProfileImage(userId: string, params: { file: Blob | File }) { this.requireId(userId); @@ -362,6 +549,17 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Updates the metadata for the given user, by merging existing values with the provided parameters. + * + * A "deep" merge will be performed - "deep" means that any nested JSON objects will be merged as well. You can remove metadata keys at any level by setting their value to `null`. + * + * > [!TIP] + * > If you want to fully replace the existing metadata instead of merging, use [`replaceUserMetadata()`](/docs/reference/backend/user/replace-user-metadata). + * @param userId - The ID of the user to update. + * @param params - The metadata to update. + * @returns The updated [`User`](https://clerk.com/docs/reference/backend/types/backend-user). + */ public async updateUserMetadata(userId: string, params: UserMetadataParams) { this.requireId(userId); @@ -373,9 +571,18 @@ export class UserAPI extends AbstractAPI { } /** - * Replace a user's metadata. Supplied fields are overwritten in full; fields - * omitted from `params` are left unchanged. Prefer `updateUserMetadata` for - * partial updates with deep-merge semantics. + * Replaces the metadata associated with the specified user. Unlike [`updateUserMetadata()`](/docs/reference/backend/user/update-user-metadata), which deep-merges into the existing metadata, this method uses replace semantics: when a metadata field is provided, its previous value is overwritten in full with no merging at any level. + * + * The distinction is at two layers: + * - **Top-level field omission preserves the existing value.** Each top-level field (`publicMetadata`, `privateMetadata`, `unsafeMetadata`) is handled independently. If you don't include a field in the request, the stored value for that field is left untouched. + * - **The value inside a provided field is replaced in full.** When you do include a field, its previous content is discarded — any nested keys present before but absent in the new value are dropped. There is no merge. + * + * For the provided field, you can also send: + * - `{}` (empty object) to clear the field. + * - `null` to overwrite the field with a JSON `null` value. Prefer `{}` unless you specifically need a stored `null`. + * @param userId - The ID of the user to replace the metadata for. + * @param params - The metadata to replace. + * @returns The updated [`User`](https://clerk.com/docs/reference/backend/types/backend-user). */ public async replaceUserMetadata(userId: string, params: UserMetadataParams) { this.requireId(userId); @@ -387,6 +594,10 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Deletes the given [`User`](https://clerk.com/docs/reference/backend/types/backend-user). + * @param userId - The ID of the user to delete. + */ public async deleteUser(userId: string) { this.requireId(userId); return this.request({ @@ -395,6 +606,9 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Gets the total number of users in your instance. + */ public async getCount(params: UserCountParams = {}) { return this.request({ method: 'GET', @@ -403,14 +617,20 @@ export class UserAPI extends AbstractAPI { }); } - /** @deprecated Use `getUserOauthAccessToken` without the `oauth_` provider prefix . */ + /** + * Gets the corresponding [OAuth access token](!oauth-access-token) for a user that has previously authenticated with the given OAuth provider. + * @param userId - The ID of the user to get the OAuth access tokens for. + * @param provider - The OAuth provider to get the access tokens for. If using a custom OAuth provider, prefix the provider name with `custom_` (e.g. `oauth_custom_google`). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property that contains an array of [`OauthAccessToken`](https://clerk.com/docs/reference/backend/types/backend-oauth-access-token) objects, and a `totalCount` property that indicates the total number of OAuth access tokens for the specified user and provider. + */ public async getUserOauthAccessToken( userId: string, - provider: `oauth_${OAuthProvider}`, + provider: OAuthProvider, ): Promise>; + /** @deprecated Use `getUserOauthAccessToken` without the `oauth_` provider prefix . */ public async getUserOauthAccessToken( userId: string, - provider: OAuthProvider, + provider: `oauth_${OAuthProvider}`, ): Promise>; public async getUserOauthAccessToken(userId: string, provider: `oauth_${OAuthProvider}` | OAuthProvider) { this.requireId(userId); @@ -431,6 +651,10 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Disable all of a user's MFA methods (e.g. [OTP](!otp) sent via SMS, TOTP on their authenticator app) at once. + * @param userId - The ID of the user to disable MFA for. + */ public async disableUserMFA(userId: string) { this.requireId(userId); return this.request({ @@ -439,6 +663,10 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Gets a list of the given user's Organization memberships. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property that contains an array of [`OrganizationMembership`](https://clerk.com/docs/reference/backend/types/backend-organization-membership) objects, and a `totalCount` property that indicates the total number of Organization memberships for the user. + */ public async getOrganizationMembershipList(params: GetOrganizationMembershipListParams) { const { userId, limit, offset } = params; this.requireId(userId); @@ -450,6 +678,10 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Gets a list of the given user's Organization invitations. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property that contains an array of [`OrganizationInvitation`](https://clerk.com/docs/reference/backend/types/backend-organization-invitation) objects, and a `totalCount` property that indicates the total number of Organization invitations for the user. + */ public async getOrganizationInvitationList(params: GetOrganizationInvitationListParams) { const { userId, ...queryParams } = params; this.requireId(userId); @@ -461,6 +693,7 @@ export class UserAPI extends AbstractAPI { }); } + /** Check that the user's password matches the supplied input. Useful for custom auth flows and re-verification. */ public async verifyPassword(params: VerifyPasswordParams) { const { userId, password } = params; this.requireId(userId); @@ -472,6 +705,7 @@ export class UserAPI extends AbstractAPI { }); } + /** Verify that the provided TOTP or backup code is valid for the user. Verifying a backup code will result it in being consumed (i.e. it will become invalid). Useful for custom auth flows and re-verification. */ public async verifyTOTP(params: VerifyTOTPParams) { const { userId, code } = params; this.requireId(userId); @@ -483,6 +717,10 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Marks the given [`User`](https://clerk.com/docs/reference/backend/types/backend-user) as banned, which means that all their sessions are revoked and they are not allowed to sign in again. + * @param userId - The ID of the user to ban. + */ public async banUser(userId: string) { this.requireId(userId); return this.request({ @@ -491,6 +729,10 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Removes the ban mark from the given [`User`](https://clerk.com/docs/reference/backend/types/backend-user), allowing them to sign in again. + * @param userId - The ID of the user to unban. + */ public async unbanUser(userId: string) { this.requireId(userId); return this.request({ @@ -499,6 +741,10 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Locks the given [`User`](https://clerk.com/docs/reference/backend/types/backend-user), which means that they are not allowed to sign in again until the lock expires or is manually unlocked. By default, lockout duration is 1 hour, but it can be configured in the application's [**Attack protection**](https://dashboard.clerk.com/~/protect/attack-protection) settings. See the [guide on user locks](https://clerk.com/docs/guides/secure/user-lockout). + * @param userId - The ID of the user to lock. + */ public async lockUser(userId: string) { this.requireId(userId); return this.request({ @@ -507,6 +753,9 @@ export class UserAPI extends AbstractAPI { }); } + /** Removes a sign-in lock from the given [`User`](https://clerk.com/docs/reference/backend/types/backend-user), allowing them to sign in again. See the [guide on user locks](https://clerk.com/docs/guides/secure/user-lockout). + * @param userId - The ID of the user to unlock. + */ public async unlockUser(userId: string) { this.requireId(userId); return this.request({ @@ -515,6 +764,11 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Deletes a user's profile image. + * @param userId - The ID of the user to delete the profile image for. + * @returns The updated [`User`](https://clerk.com/docs/reference/backend/types/backend-user). + */ public async deleteUserProfileImage(userId: string) { this.requireId(userId); return this.request({ @@ -523,6 +777,10 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Deletes the passkey identification for a given user and notifies them through email. + * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object) object. + */ public async deleteUserPasskey(params: DeleteUserPasskeyParams) { this.requireId(params.userId); this.requireId(params.passkeyIdentificationId); @@ -532,6 +790,10 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Deletes a Web3 wallet identification for the given user. + * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object) object. + */ public async deleteUserWeb3Wallet(params: DeleteWeb3WalletParams) { this.requireId(params.userId); this.requireId(params.web3WalletIdentificationId); @@ -541,6 +803,10 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Deletes an external account for the given user. + * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object) object. + */ public async deleteUserExternalAccount(params: DeleteUserExternalAccountParams) { this.requireId(params.userId); this.requireId(params.externalAccountId); @@ -550,6 +816,10 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Deletes all backup codes for the given user. + * @param userId - The ID of the user to delete backup codes for. + */ public async deleteUserBackupCodes(userId: string) { this.requireId(userId); return this.request({ @@ -558,6 +828,10 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Deletes all of the TOTP secrets for the given user. + * @param userId - The ID of the user to delete the TOTP secrets for. + */ public async deleteUserTOTP(userId: string) { this.requireId(userId); return this.request({ @@ -566,6 +840,12 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Sets the given user's password as compromised. The user will be prompted to reset their password on their next sign-in. See the [guide on password protection and rules](/docs/guides/secure/password-protection-and-rules#reject-compromised-passwords) for more information. + * @param userId - The ID of the user to set the password as compromised for. + * @param params - Other parameters for the request. + * @returns The updated [`User`](https://clerk.com/docs/reference/backend/types/backend-user). + */ public async setPasswordCompromised( userId: string, params: SetPasswordCompromisedParams = { @@ -580,6 +860,11 @@ export class UserAPI extends AbstractAPI { }); } + /** + * Unsets the given user's password as compromised. The user will no longer be prompted to reset their password on their next sign-in. See the [guide on password protection and rules](/docs/guides/secure/password-protection-and-rules#reject-compromised-passwords) for more information. + * @param userId - The ID of the user to unset the password as compromised for. + * @returns The updated [`User`](https://clerk.com/docs/reference/backend/types/backend-user). + */ public async unsetPasswordCompromised(userId: string) { this.requireId(userId); return this.request({ diff --git a/packages/backend/src/api/endpoints/WaitlistEntryApi.ts b/packages/backend/src/api/endpoints/WaitlistEntryApi.ts index fee3d0fb1f3..ab371945b86 100644 --- a/packages/backend/src/api/endpoints/WaitlistEntryApi.ts +++ b/packages/backend/src/api/endpoints/WaitlistEntryApi.ts @@ -10,33 +10,38 @@ import type { WithSign } from './util-types'; const basePath = '/waitlist_entries'; -type WaitlistEntryListParams = ClerkPaginationRequest<{ - /** - * Filter waitlist entries by `email_address` or `id` - */ +/** @generateWithEmptyComment */ +export type WaitlistEntryListParams = ClerkPaginationRequest<{ + /** Filters waitlist entries by `email_address` or `id`. */ query?: string; + /** Filters waitlist entries by status. */ status?: WaitlistEntryStatus; + /** Filters waitlist entries in a particular order. Prefix a value with `+` to sort in ascending order, or `-` to sort in descending order. Defaults to `-created_at`. */ orderBy?: WithSign<'created_at' | 'invited_at' | 'email_address'>; }>; -type WaitlistEntryCreateParams = { +/** @generateWithEmptyComment */ +export type WaitlistEntryCreateParams = { + /** The email address to add to the waitlist. */ emailAddress: string; + /** Whether to notify the user that their email address has been added to the waitlist. Notifies the user if the `emailAddress` is an email address. Defaults to `true`. */ notify?: boolean; }; -type WaitlistEntryBulkCreateParams = Array; +/** @generateWithEmptyComment */ +export type WaitlistEntryBulkCreateParams = Array; -type WaitlistEntryInviteParams = { - /** - * When true, do not error if an invitation already exists. Default: false. - */ +/** @inline */ +export type WaitlistEntryInviteParams = { + /** Whether to ignore an existing invitation. Defaults to `false`. */ ignoreExisting?: boolean; }; +/** @generateWithEmptyComment */ export class WaitlistEntryAPI extends AbstractAPI { /** - * List waitlist entries. - * @param params Optional parameters (e.g., `query`, `status`, `orderBy`). + * Gets a list of waitlist entries for the instance. By default, the list is returned in descending order by creation date (newest first). + * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property containing an array of [`WaitlistEntry`](https://clerk.com/docs/reference/backend/types/backend-waitlist-entry) objects and a `totalCount` property containing the total number of waitlist entries for the instance. */ public async list(params: WaitlistEntryListParams = {}) { return this.request>({ @@ -47,8 +52,8 @@ export class WaitlistEntryAPI extends AbstractAPI { } /** - * Create a waitlist entry. - * @param params The parameters for creating a waitlist entry. + * Create a waitlist entry for the given email address. If the email address is already on the waitlist, no new entry will be created and the existing waitlist entry will be returned. + * @returns The created or existing [`WaitlistEntry`](https://clerk.com/docs/reference/backend/types/backend-waitlist-entry) object. */ public async create(params: WaitlistEntryCreateParams) { return this.request({ @@ -59,8 +64,8 @@ export class WaitlistEntryAPI extends AbstractAPI { } /** - * Bulk create waitlist entries. - * @param params An array of parameters for creating waitlist entries. + * Creates multiple waitlist entries for the given email addresses. If an email address is already on the waitlist, no new entry will be created and the existing waitlist entry will be returned. + * @returns An array of created or existing [`WaitlistEntry`](https://clerk.com/docs/reference/backend/types/backend-waitlist-entry) objects. */ public async createBulk(params: WaitlistEntryBulkCreateParams) { return this.request({ @@ -71,9 +76,10 @@ export class WaitlistEntryAPI extends AbstractAPI { } /** - * Invite a waitlist entry. - * @param id The waitlist entry ID. - * @param params Optional parameters (e.g., `ignoreExisting`). + * Invites the given waitlist entry. + * @param id - The waitlist entry ID. + * @param params - Optional parameters for inviting the waitlist entry. + * @returns The invited [`WaitlistEntry`](https://clerk.com/docs/reference/backend/types/backend-waitlist-entry) object. */ public async invite(id: string, params: WaitlistEntryInviteParams = {}) { this.requireId(id); @@ -86,8 +92,9 @@ export class WaitlistEntryAPI extends AbstractAPI { } /** - * Reject a waitlist entry. - * @param id The waitlist entry ID. + * Rejects the given waitlist entry. + * @param id - The ID of the waitlist entry to reject. + * @returns The rejected [`WaitlistEntry`](https://clerk.com/docs/reference/backend/types/backend-waitlist-entry) object. */ public async reject(id: string) { this.requireId(id); @@ -99,8 +106,9 @@ export class WaitlistEntryAPI extends AbstractAPI { } /** - * Delete a waitlist entry. - * @param id The waitlist entry ID. + * Deletes the given pending waitlist entry. + * @param id - The ID of the waitlist entry to delete. + * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object) object. */ public async delete(id: string) { this.requireId(id); diff --git a/packages/backend/src/api/endpoints/index.ts b/packages/backend/src/api/endpoints/index.ts index ebbd1990b56..f0f04ff2baa 100644 --- a/packages/backend/src/api/endpoints/index.ts +++ b/packages/backend/src/api/endpoints/index.ts @@ -17,7 +17,37 @@ export * from './MachineApi'; export * from './M2MTokenApi'; export * from './JwksApi'; export * from './JwtTemplatesApi'; -export * from './OrganizationApi'; +// `GetOrganizationMembershipListParams` and `GetOrganizationInvitationListParams` are defined on +// both `UserApi` (user-scoped) and `OrganizationApi` (org-scoped) with different shapes. +// UserApi's variants remain the canonical public exports through this barrel; OrganizationApi's +// variants are reachable via direct import from `./OrganizationApi`, and typedoc still resolves +// them locally on the class methods. +// Similarly, `CreateParams` is defined on both `InvitationApi` and `OrganizationApi`, and +// `UpdateParams` is defined on both `InstanceApi` and `OrganizationApi`. The InvitationApi / +// InstanceApi variants remain the canonical public exports through this barrel (via their +// `export * from` lines); OrganizationApi's `CreateParams` and `UpdateParams` are reachable via +// direct import from `./OrganizationApi`. +export { OrganizationAPI } from './OrganizationApi'; +export type { + CreateBulkOrganizationInvitationParams, + CreateOrganizationDomainParams, + CreateOrganizationInvitationParams, + CreateOrganizationMembershipParams, + DeleteOrganizationDomainParams, + DeleteOrganizationMembershipParams, + GetInstanceOrganizationMembershipListParams, + GetOrganizationDomainListParams, + GetOrganizationInvitationParams, + GetOrganizationListParams, + GetOrganizationParams, + MetadataParams, + RevokeOrganizationInvitationParams, + UpdateLogoParams, + UpdateMetadataParams, + UpdateOrganizationDomainParams, + UpdateOrganizationMembershipMetadataParams, + UpdateOrganizationMembershipParams, +} from './OrganizationApi'; export * from './OrganizationPermissionApi'; export * from './OrganizationRoleApi'; export * from './OAuthApplicationsApi'; diff --git a/packages/backend/src/api/resources/APIKey.ts b/packages/backend/src/api/resources/APIKey.ts index 5add117abc6..09f67479b26 100644 --- a/packages/backend/src/api/resources/APIKey.ts +++ b/packages/backend/src/api/resources/APIKey.ts @@ -5,69 +5,37 @@ import type { APIKeyJSON } from './JSON'; */ export class APIKey { constructor( - /** - * A unique ID for the API key. - */ + /** The unique identifier for the API key. */ readonly id: string, - /** - * The type of the API key. Currently always `'api_key'`. - */ + /** The type of the API key. Currently always `'api_key'`. */ readonly type: string, - /** - * The API key's name. - */ + /** The API key's name. */ readonly name: string, - /** - * The user or organization ID that the API key is associated with. - */ + /** The user or organization ID that the API key is associated with. */ readonly subject: string, - /** - * An array of scopes that define what the API key can access. - */ + /** An array of scopes that define what the API key can access. */ readonly scopes: string[], - /** - * Custom claims associated with the API key. - */ + /** Custom claims associated with the API key. */ readonly claims: Record | null, - /** - * A boolean indicating whether the API key has been revoked. - */ + /** Whether the API key has been revoked. */ readonly revoked: boolean, - /** - * The reason for revoking the API key, if it has been revoked. - */ + /** The reason for revoking the API key, if it has been revoked. */ readonly revocationReason: string | null, - /** - * A boolean indicating whether the API key has expired. - */ + /** Whether the API key has expired. */ readonly expired: boolean, - /** - * The expiration date and time of the API key. `null` if the API key never expires. - */ + /** The Unix timestamp when the API key expires. `null` if the API key never expires. */ readonly expiration: number | null, - /** - * The user ID for the user creating the API key. - */ + /** The user ID for the user creating the API key. */ readonly createdBy: string | null, - /** - * A description for the API key. - */ + /** A description for the API key. */ readonly description: string | null, - /** - * The date and time when the API key was last used to authenticate a request. - */ + /** The Unix timestamp when the API key was last used to authenticate a request. */ readonly lastUsedAt: number | null, - /** - * The date when the API key was created. - */ + /** The Unix timestamp when the API key was created. */ readonly createdAt: number, - /** - * The date when the API key was last updated. - */ + /** The Unix timestamp when the API key was last updated. */ readonly updatedAt: number, - /** - * The API key secret. **This property is only present in the response from [`create()`](/docs/reference/objects/api-keys#create) and cannot be retrieved later.** - */ + /** The API key secret. */ readonly secret?: string, ) {} diff --git a/packages/backend/src/api/resources/AgentTask.ts b/packages/backend/src/api/resources/AgentTask.ts index 5053f0a828b..95017849655 100644 --- a/packages/backend/src/api/resources/AgentTask.ts +++ b/packages/backend/src/api/resources/AgentTask.ts @@ -1,36 +1,24 @@ import type { AgentTaskJSON } from './JSON'; /** - * Represents a agent token resource. - * - * Agent tokens are used for testing purposes and allow creating sessions - * for users without requiring full authentication flows. + * The Backend `AgentTask` object represents an Agent Task resource. Agent Tasks are used for testing purposes and allow creating sessions for users without requiring full authentication flows. */ export class AgentTask { constructor( - /** - * A stable identifier for the agent, unique per agent_name within an instance. - */ + /** The identifier for the agent, unique per `agent_name` within an instance. */ readonly agentId: string, - /** - * A unique identifier for this agent task. - * @deprecated Use agentTaskId instead. - */ + /** @deprecated Use `agentTaskId` instead. */ readonly taskId: string, - /** - * A unique identifier for this agent task. - */ + /** The unique identifier for this Agent Task. */ readonly agentTaskId: string, - /** - * The FAPI URL that, when visited, creates a session for the user. - */ + /** The Frontend API URL that, when visited, creates a session for the user. Only returned by [`create()`](https://clerk.com/docs/reference/backend/agent-tasks/create); omitted from [`revoke()`](https://clerk.com/docs/reference/backend/agent-tasks/revoke). */ readonly url: string, ) {} /** - * Creates a AgentTask instance from a JSON object. + * Creates an AgentTask instance from a JSON object. * - * @param data - The JSON object containing agent task data + * @param data - The JSON object containing Agent Task data * @returns A new AgentTask instance */ static fromJSON(data: AgentTaskJSON): AgentTask { diff --git a/packages/backend/src/api/resources/AllowlistIdentifier.ts b/packages/backend/src/api/resources/AllowlistIdentifier.ts index 1b3bb00d704..49af5a6344b 100644 --- a/packages/backend/src/api/resources/AllowlistIdentifier.ts +++ b/packages/backend/src/api/resources/AllowlistIdentifier.ts @@ -2,37 +2,25 @@ import type { AllowlistIdentifierType } from './Enums'; import type { AllowlistIdentifierJSON } from './JSON'; /** - * The Backend `AllowlistIdentifier` object represents an identifier that has been added to the allowlist of your application. The Backend `AllowlistIdentifier` object is used in the [Backend API](https://clerk.com/docs/reference/backend-api/model/AllowlistIdentifier) and is not directly accessible from the Frontend API. + * The Backend `AllowlistIdentifier` object represents an identifier that has been added to the allowlist of your application. The Backend `AllowlistIdentifier` object is used in the [Backend API](https://clerk.com/docs/reference/backend-api/model/AllowlistIdentifier){{ target: '_blank' }} and is not directly accessible from the Frontend API. */ export class AllowlistIdentifier { constructor( /** - * A unique ID for the allowlist identifier. + * The unique identifier for the allowlist identifier. */ readonly id: string, - /** - * The identifier that was added to the allowlist. - */ + /** The identifier that was added to the allowlist. */ readonly identifier: string, - /** - * The type of the allowlist identifier. - */ + /** The type of the allowlist identifier. */ readonly identifierType: AllowlistIdentifierType, - /** - * The date when the allowlist identifier was first created. - */ + /** The Unix timestamp when the allowlist identifier was first created. */ readonly createdAt: number, - /** - * The date when the allowlist identifier was last updated. - */ + /** The Unix timestamp when the allowlist identifier was last updated. */ readonly updatedAt: number, - /** - * The ID of the instance that this allowlist identifier belongs to. - */ + /** The ID of the instance that this allowlist identifier belongs to. */ readonly instanceId?: string, - /** - * The ID of the invitation sent to the identifier. - */ + /** The ID of the invitation sent to the identifier. */ readonly invitationId?: string, ) {} diff --git a/packages/backend/src/api/resources/Client.ts b/packages/backend/src/api/resources/Client.ts index 4a67fa5ada8..18e11b3f538 100644 --- a/packages/backend/src/api/resources/Client.ts +++ b/packages/backend/src/api/resources/Client.ts @@ -4,45 +4,27 @@ import type { ClientJSON } from './JSON'; import { Session } from './Session'; /** - * The Backend `Client` object is similar to the [`Client`](https://clerk.com/docs/reference/objects/client) object as it holds information about the authenticated sessions in the current device. However, the Backend `Client` object is different from the `Client` object in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/model/Client) and is not directly accessible from the Frontend API. + * The Backend `Client` object is similar to the [`Client`](https://clerk.com/docs/reference/objects/client) object as it holds information about the authenticated sessions in the current device. However, the Backend `Client` object is different from the `Client` object in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/model/Client){{ target: '_blank' }} and is not directly accessible from the Frontend API. */ export class Client { constructor( - /** - * The unique identifier for the `Client`. - */ + /** The unique identifier for the `Client`. */ readonly id: string, - /** - * An array of [Session](https://clerk.com/docs/reference/backend/types/backend-session){{ target: '_blank' }} IDs associated with the `Client`. - */ + /** An array of [Session](https://clerk.com/docs/reference/backend/types/backend-session) IDs associated with the `Client`. */ readonly sessionIds: string[], - /** - * An array of [Session](https://clerk.com/docs/reference/backend/types/backend-session){{ target: '_blank' }} objects associated with the `Client`. - */ + /** An array of [`Session`](https://clerk.com/docs/reference/backend/types/backend-session) objects associated with the `Client`. */ readonly sessions: Session[], - /** - * The ID of the [`SignIn`](https://clerk.com/docs/reference/objects/sign-in). - */ + /** The ID of the associated [`SignIn`](https://clerk.com/docs/reference/objects/sign-in). */ readonly signInId: string | null, - /** - * The ID of the [`SignUp`](https://clerk.com/docs/reference/objects/sign-up). - */ + /** The ID of the associated [`SignUp`](https://clerk.com/docs/reference/objects/sign-up). */ readonly signUpId: string | null, - /** - * The ID of the last active [Session](https://clerk.com/docs/reference/backend/types/backend-session). - */ + /** The ID of the last active [`Session`](https://clerk.com/docs/reference/backend/types/backend-session). */ readonly lastActiveSessionId: string | null, - /** - * The last authentication strategy used by the `Client`. - */ + /** The last authentication strategy used by the `Client`. */ readonly lastAuthenticationStrategy: LastAuthenticationStrategy | null, - /** - * The date when the `Client` was first created. - */ + /** The Unix timestamp when the `Client` was first created. */ readonly createdAt: number, - /** - * The date when the `Client` was last updated. - */ + /** The Unix timestamp when the `Client` was last updated. */ readonly updatedAt: number, ) {} diff --git a/packages/backend/src/api/resources/CommercePlan.ts b/packages/backend/src/api/resources/CommercePlan.ts index acfef8cf71b..c8f0534bce9 100644 --- a/packages/backend/src/api/resources/CommercePlan.ts +++ b/packages/backend/src/api/resources/CommercePlan.ts @@ -4,75 +4,43 @@ import { Feature } from './Feature'; import type { BillingPlanJSON } from './JSON'; /** - * The `BillingPlan` object is similar to the [`BillingPlanResource`](/docs/reference/types/billing-plan-resource) object as it holds information about a Plan, as well as methods for managing it. However, the `BillingPlan` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/GET/billing/plans) and is not directly accessible from the Frontend API. + * The `BillingPlan` object is similar to the [`BillingPlanResource`](https://clerk.com/docs/reference/types/billing-plan-resource) object as it holds information about a Plan, as well as methods for managing it. However, the `BillingPlan` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/GET/billing/plans){{ target: '_blank' }} and is not directly accessible from the Frontend API. * * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. */ export class BillingPlan { constructor( - /** - * The unique identifier for the Plan. - */ + /** The unique identifier for the Plan. */ readonly id: string, - /** - * The name of the Plan. - */ + /** The name of the Plan. */ readonly name: string, - /** - * The URL-friendly identifier of the Plan. - */ + /** The URL-friendly identifier of the Plan. */ readonly slug: string, - /** - * The description of the Plan. - */ + /** The description of the Plan. */ readonly description: string | null, - /** - * Whether the Plan is the default Plan. - */ + /** Whether the Plan is the default Plan. */ readonly isDefault: boolean, - /** - * Whether the Plan is recurring. - */ + /** Whether the Plan is recurring. */ readonly isRecurring: boolean, - /** - * Whether the Plan has a base fee. - */ + /** Whether the Plan has a base fee. */ readonly hasBaseFee: boolean, - /** - * Whether the Plan is displayed in the `` component. - */ + /** Whether the Plan is displayed in the [``](https://clerk.com/docs/nextjs/reference/components/billing/pricing-table) component. */ readonly publiclyVisible: boolean, - /** - * The monthly fee of the Plan. - */ + /** The monthly fee of the Plan. */ readonly fee: BillingMoneyAmount | null, - /** - * The annual fee of the Plan. - */ + /** The annual fee of the Plan. */ readonly annualFee: BillingMoneyAmount | null, - /** - * The annual fee of the Plan on a monthly basis. - */ + /** The annual fee of the Plan on a monthly basis. */ readonly annualMonthlyFee: BillingMoneyAmount | null, - /** - * The type of payer for the Plan. - */ + /** The type of payer for the Plan. */ readonly forPayerType: 'org' | 'user', - /** - * The features the Plan offers. - */ + /** The [Features](https://clerk.com/docs/reference/backend/types/feature) the Plan offers. */ readonly features: Feature[], - /** - * The URL of the Plan's avatar image. - */ + /** The URL of the Plan's avatar image. */ readonly avatarUrl: string | null, - /** - * Number of free trial days for this plan. - */ + /** The number of free trial days for this plan. */ readonly freeTrialDays: number | null, - /** - * Whether free trial is enabled for this plan. - */ + /** Whether free trial is enabled for this plan. */ readonly freeTrialEnabled: boolean, ) {} diff --git a/packages/backend/src/api/resources/CommerceSubscription.ts b/packages/backend/src/api/resources/CommerceSubscription.ts index 29758f165d8..e1332307b0b 100644 --- a/packages/backend/src/api/resources/CommerceSubscription.ts +++ b/packages/backend/src/api/resources/CommerceSubscription.ts @@ -4,51 +4,36 @@ import { BillingSubscriptionItem } from './CommerceSubscriptionItem'; import type { BillingSubscriptionJSON } from './JSON'; /** - * The `BillingSubscription` object is similar to the [`BillingSubscriptionResource`](/docs/reference/types/billing-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `BillingSubscription` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/GET/organizations/%7Borganization_id%7D/billing/subscription) and is not directly accessible from the Frontend API. + * The `BillingSubscription` object is similar to the [`BillingSubscriptionResource`](https://clerk.com/docs/reference/types/billing-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `BillingSubscription` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/GET/organizations/%7Borganization_id%7D/billing/subscription){{ target: '_blank' }} and is not directly accessible from the Frontend API. * * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. */ export class BillingSubscription { constructor( - /** - * The unique identifier for the billing subscription. - */ + /** The unique identifier for the Subscription. */ readonly id: string, - /** - * The current status of the subscription. - */ + /** The current status of the Subscription. */ readonly status: BillingSubscriptionJSON['status'], - /** - * The ID of the payer for this subscription. - */ + /** The ID of the payer for this Subscription. */ readonly payerId: string, - /** - * Unix timestamp (milliseconds) of when the subscription was created. - */ + /** The Unix timestamp (milliseconds) of when the Subscription was created. */ readonly createdAt: number, - /** - * Unix timestamp (milliseconds) of when the subscription was last updated. - */ + /** The Unix timestamp (milliseconds) of when the Subscription was last updated. */ readonly updatedAt: number, - /** - * Unix timestamp (milliseconds) of when the subscription became active. - */ + /** The Unix timestamp (milliseconds) of when the Subscription became active. */ readonly activeAt: number | null, - /** - * Unix timestamp (milliseconds) of when the subscription became past due. - */ + /** The Unix timestamp (milliseconds) of when the Subscription became past due. */ readonly pastDueAt: number | null, - /** - * Array of subscription items in this subscription. - */ + /** All of the Subscription Items in this Subscription. */ readonly subscriptionItems: BillingSubscriptionItem[], - /** - * Information about the next scheduled payment. - */ - readonly nextPayment: { date: number; amount: BillingMoneyAmount } | null, - /** - * Whether the payer is eligible for a free trial. - */ + /** Information about the next scheduled payment for this Subscription. */ + readonly nextPayment: { + /** The Unix timestamp (milliseconds) of when the next payment is scheduled. */ + date: number; + /** The amount of the next payment. */ + amount: BillingMoneyAmount; + } | null, + /** Whether the payer is eligible for a free trial. */ readonly eligibleForFreeTrial: boolean, ) {} diff --git a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts index 1864bc73f9d..79b0d8991bd 100644 --- a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts +++ b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts @@ -4,91 +4,53 @@ import { BillingPlan } from './CommercePlan'; import type { BillingSubscriptionItemJSON } from './JSON'; /** - * The `BillingSubscriptionItem` object is similar to the [`BillingSubscriptionItemResource`](/docs/reference/types/billing-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `BillingSubscriptionItem` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/GET/billing/subscription_items) and is not directly accessible from the Frontend API. + * The `BillingSubscriptionItem` object is similar to the [`BillingSubscriptionItemResource`](https://clerk.com/docs/reference/types/billing-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `BillingSubscriptionItem` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/GET/billing/subscription_items){{ target: '_blank' }} and is not directly accessible from the Frontend API. * * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. */ export class BillingSubscriptionItem { constructor( - /** - * The unique identifier for the subscription item. - */ + /** The unique identifier for the Subscription Item. */ readonly id: string, - /** - * The status of the subscription item. - */ + /** The status of the Subscription Item. */ readonly status: BillingSubscriptionItemJSON['status'], - /** - * The Plan period for the subscription item. - */ + /** The period of the Plan associated with this Subscription Item. */ readonly planPeriod: 'month' | 'annual', - /** - * Unix timestamp (milliseconds) of when the current period starts. - */ + /** The Unix timestamp (milliseconds) of when the current period starts. */ readonly periodStart: number, - /** - * The next payment information. - */ + /** Information about the next scheduled payment for this Subscription Item. */ readonly nextPayment: | { - /** - * The amount of the next payment. - */ + /** The amount of the next payment. */ amount: number; - /** - * Unix timestamp (milliseconds) of when the next payment is scheduled. - */ + /** The Unix timestamp (milliseconds) of when the next payment is scheduled. */ date: number; } | null | undefined, - /** - * The current amount for the subscription item. - */ + /** The current amount for the Subscription Item. */ readonly amount: BillingMoneyAmount | undefined, - /** - * The Plan associated with this subscription item. - */ + /** The Plan associated with this Subscription Item. */ readonly plan: BillingPlan | null, - /** - * The Plan ID. - */ + /** The ID of the Plan associated with this Subscription Item. */ readonly planId: string | null, - /** - * Unix timestamp (milliseconds) of when the subscription item was created. - */ + /** The Unix timestamp (milliseconds) of when the Subscription Item was created. */ readonly createdAt: number, - /** - * Unix timestamp (milliseconds) of when the subscription item was last updated. - */ + /** The Unix timestamp (milliseconds) of when the Subscription Item was last updated. */ readonly updatedAt: number, - /** - * Unix timestamp (milliseconds) of when the current period ends. - */ + /** The Unix timestamp (milliseconds) of when the current period ends. */ readonly periodEnd: number | null, - /** - * Unix timestamp (milliseconds) of when the subscription item was canceled. - */ + /** The Unix timestamp (milliseconds) of when the Subscription Item was canceled. */ readonly canceledAt: number | null, - /** - * Unix timestamp (milliseconds) of when the subscription item became past due. - */ + /** The Unix timestamp (milliseconds) of when the Subscription Item became past due. */ readonly pastDueAt: number | null, - /** - * Unix timestamp (milliseconds) of when the subscription item ended. - */ + /** The Unix timestamp (milliseconds) of when the Subscription Item ended. */ readonly endedAt: number | null, - /** - * The payer ID. - */ + /** The ID of the payer for this Subscription Item. */ readonly payerId: string | undefined, - /** - * Whether this subscription item is currently in a free trial period. - */ + /** Whether this Subscription Item is currently in a free trial period. */ readonly isFreeTrial?: boolean, - /** - * The lifetime amount paid for this subscription item. - */ + /** The lifetime amount paid for this Subscription Item. */ readonly lifetimePaid?: BillingMoneyAmount, ) {} diff --git a/packages/backend/src/api/resources/DeletedObject.ts b/packages/backend/src/api/resources/DeletedObject.ts index b89b8d85ec5..54858a97ee4 100644 --- a/packages/backend/src/api/resources/DeletedObject.ts +++ b/packages/backend/src/api/resources/DeletedObject.ts @@ -1,10 +1,17 @@ import type { DeletedObjectJSON } from './JSON'; +/** + * The `DeletedObject` object represents an item that has been deleted from the database. It is used to represent the result of a delete operation. + */ export class DeletedObject { constructor( + /** The type of object that has been deleted. */ readonly object: string, + /** The unique identifier for the deleted object. */ readonly id: string | null, + /** The URL-friendly identifier for the deleted object. */ readonly slug: string | null, + /** Whether the object has been deleted. */ readonly deleted: boolean, ) {} diff --git a/packages/backend/src/api/resources/Domain.ts b/packages/backend/src/api/resources/Domain.ts index 684300c839b..e6a2dc78de5 100644 --- a/packages/backend/src/api/resources/Domain.ts +++ b/packages/backend/src/api/resources/Domain.ts @@ -1,15 +1,24 @@ import { CnameTarget } from './CnameTarget'; import type { DomainJSON } from './JSON'; +/** The `Domain` object represents a domain that is managed by the instance. */ export class Domain { constructor( + /** The unique identifier of the domain. */ readonly id: string, + /** The name of the domain. */ readonly name: string, + /** Whether the domain is a satellite domain. */ readonly isSatellite: boolean, + /** The Frontend API URL for the domain. */ readonly frontendApiUrl: string, + /** The development origin for the domain. */ readonly developmentOrigin: string, + /** The CNAME targets for the domain. */ readonly cnameTargets: CnameTarget[], + /** The [Account Portal](https://clerk.com/docs/guides/account-portal/overview) URL for the domain. */ readonly accountsPortalUrl?: string | null, + /** The [proxy URL](https://clerk.com/docs/guides/dashboard/dns-domains/proxy-fapi) for the domain. */ readonly proxyUrl?: string | null, ) {} diff --git a/packages/backend/src/api/resources/EmailAddress.ts b/packages/backend/src/api/resources/EmailAddress.ts index 4921403ecb3..ea72da9eb6a 100644 --- a/packages/backend/src/api/resources/EmailAddress.ts +++ b/packages/backend/src/api/resources/EmailAddress.ts @@ -11,21 +11,13 @@ import { Verification } from './Verification'; */ export class EmailAddress { constructor( - /** - * The unique identifier for the email address. - */ + /** The unique identifier for the email address. */ readonly id: string, - /** - * The value of the email address. - */ + /** The value of the email address. */ readonly emailAddress: string, - /** - * An object holding information on the verification of the email address. - */ + /** An object holding information on the verification of the email address. */ readonly verification: Verification | null, - /** - * An array of objects containing information about any identifications that might be linked to the email address. - */ + /** An array of objects containing information about any identifications that might be linked to the email address. */ readonly linkedTo: IdentificationLink[], ) {} diff --git a/packages/backend/src/api/resources/EnterpriseAccount.ts b/packages/backend/src/api/resources/EnterpriseAccount.ts index 06608da84b4..212e5185418 100644 --- a/packages/backend/src/api/resources/EnterpriseAccount.ts +++ b/packages/backend/src/api/resources/EnterpriseAccount.ts @@ -6,57 +6,31 @@ import { Verification } from './Verification'; */ export class EnterpriseAccountConnection { constructor( - /** - * The unique identifier for this enterprise connection. - */ + /** The unique identifier for this enterprise connection. */ readonly id: string, - /** - * Whether the connection is currently active. - */ + /** Whether the connection is currently active. */ readonly active: boolean, - /** - * Whether IdP-initiated SSO is allowed. - */ + /** Whether IdP-initiated SSO is allowed. */ readonly allowIdpInitiated: boolean, - /** - * Whether subdomains are allowed for this connection. - */ + /** Whether subdomains are allowed for this connection. */ readonly allowSubdomains: boolean, - /** - * Whether additional identifications are disabled for users authenticating via this connection. - */ + /** Whether additional identifications are disabled for users authenticating via this connection. */ readonly disableAdditionalIdentifications: boolean, - /** - * The domain associated with this connection. - */ + /** The domain associated with this connection. */ readonly domain: string, - /** - * The public URL of the connection's logo, if available. - */ + /** The public URL of the connection's logo, if available. */ readonly logoPublicUrl: string | null, - /** - * The name of the enterprise connection. - */ + /** The name of the enterprise connection. */ readonly name: string, - /** - * The SSO protocol used (e.g., `saml` or `oauth`). - */ + /** The SSO protocol used (e.g., `saml` or `oauth`). */ readonly protocol: string, - /** - * The SSO provider (e.g., `saml_custom`, `saml_okta`). - */ + /** The SSO provider (e.g., `saml_custom`, `saml_okta`). */ readonly provider: string, - /** - * Whether user attributes are synced from the IdP. - */ + /** Whether user attributes are synced from the IdP. */ readonly syncUserAttributes: boolean, - /** - * The date when this connection was created. - */ + /** The Unix timestamp when this connection was created. */ readonly createdAt: number, - /** - * The date when this connection was last updated. - */ + /** The Unix timestamp when this connection was last updated. */ readonly updatedAt: number, ) {} diff --git a/packages/backend/src/api/resources/EnterpriseConnection.ts b/packages/backend/src/api/resources/EnterpriseConnection.ts index 9a63afa49e4..5eaf37e8beb 100644 --- a/packages/backend/src/api/resources/EnterpriseConnection.ts +++ b/packages/backend/src/api/resources/EnterpriseConnection.ts @@ -9,57 +9,31 @@ import type { */ export class EnterpriseConnectionSamlConnection { constructor( - /** - * The unique identifier for the SAML connection. - */ + /** The unique identifier for the SAML connection. */ readonly id: string, - /** - * The name to use as a label for the connection. - */ + /** The name to use as a label for the connection. */ readonly name: string, - /** - * The Entity ID as provided by the Identity Provider (IdP). - */ + /** The Entity ID as provided by the Identity Provider (IdP). */ readonly idpEntityId: string, - /** - * The Single-Sign On URL as provided by the Identity Provider (IdP). - */ + /** The Single-Sign On URL as provided by the Identity Provider (IdP). */ readonly idpSsoUrl: string, - /** - * The X.509 certificate as provided by the Identity Provider (IdP). - */ + /** The X.509 certificate as provided by the Identity Provider (IdP). */ readonly idpCertificate: string, - /** - * The URL which serves the Identity Provider (IdP) metadata. - */ + /** The URL which serves the Identity Provider (IdP) metadata. */ readonly idpMetadataUrl: string, - /** - * The XML content of the Identity Provider (IdP) metadata file. - */ + /** The XML content of the Identity Provider (IdP) metadata file. */ readonly idpMetadata: string, - /** - * The Assertion Consumer Service (ACS) URL of the connection. - */ + /** The Assertion Consumer Service (ACS) URL of the connection. */ readonly acsUrl: string, - /** - * The Entity ID as provided by the Service Provider (Clerk). - */ + /** The Entity ID as provided by the Service Provider (Clerk). */ readonly spEntityId: string, - /** - * The metadata URL as provided by the Service Provider (Clerk). - */ + /** The metadata URL as provided by the Service Provider (Clerk). */ readonly spMetadataUrl: string, - /** - * Indicates whether the connection syncs user attributes between the IdP and Clerk. - */ + /** Whether the connection syncs user attributes between the IdP and Clerk. */ readonly syncUserAttributes: boolean, - /** - * Indicates whether users with an email address subdomain are allowed to use this connection. - */ + /** Whether users with an email address subdomain are allowed to use this connection. */ readonly allowSubdomains: boolean, - /** - * Indicates whether Identity Provider (IdP) initiated flows are allowed. - */ + /** Whether IdP-initiated SSO is allowed. */ readonly allowIdpInitiated: boolean, ) {} @@ -152,19 +126,19 @@ export class EnterpriseConnection { */ readonly organizationId: string | null, /** - * Indicates whether the connection is active or not. + * Whether the connection is active or not. */ readonly active: boolean, /** - * Indicates whether the connection syncs user attributes between the IdP and Clerk or not. + * Whether the connection syncs user attributes between the IdP and Clerk or not. */ readonly syncUserAttributes: boolean, /** - * Indicates whether users with an email address subdomain are allowed to use this connection or not. + * Whether users with an email address subdomain are allowed to use this connection or not. */ readonly allowSubdomains: boolean, /** - * Indicates whether additional identifications are disabled for this connection. + * Whether additional identifications are disabled for this connection. */ readonly disableAdditionalIdentifications: boolean, /** diff --git a/packages/backend/src/api/resources/Enums.ts b/packages/backend/src/api/resources/Enums.ts index b2b60590cd3..019bc3458a7 100644 --- a/packages/backend/src/api/resources/Enums.ts +++ b/packages/backend/src/api/resources/Enums.ts @@ -21,26 +21,26 @@ export type OAuthProvider = export type OAuthStrategy = `oauth_${OAuthProvider}`; -/** - * @inline - */ +/** @inline */ export type OrganizationInvitationStatus = 'pending' | 'accepted' | 'revoked' | 'expired'; +/** @inline */ export type OrganizationDomainVerificationStatus = 'unverified' | 'verified'; +/** @inline */ export type OrganizationDomainVerificationStrategy = 'email_code'; // only available value for now +/** @inline */ export type OrganizationEnrollmentMode = 'manual_invitation' | 'automatic_invitation' | 'automatic_suggestion'; +/** @inline */ export type OrganizationMembershipRole = OrganizationCustomRoleKey; export type SignInStatus = 'needs_identifier' | 'needs_factor_one' | 'needs_factor_two' | 'complete'; export type SignUpVerificationNextAction = 'needs_prepare' | 'needs_attempt' | ''; -/** - * @inline - */ +/** @inline */ export type InvitationStatus = 'pending' | 'accepted' | 'revoked' | 'expired'; export const DomainsEnrollmentModes = { @@ -57,17 +57,11 @@ export const ActorTokenStatus = { } as const; export type ActorTokenStatus = (typeof ActorTokenStatus)[keyof typeof ActorTokenStatus]; -/** - * @inline - */ +/** @inline */ export type AllowlistIdentifierType = 'email_address' | 'phone_number' | 'web3_wallet'; -/** - * @inline - */ +/** @inline */ export type BlocklistIdentifierType = AllowlistIdentifierType; -/** - * @inline - */ +/** @inline */ export type WaitlistEntryStatus = 'pending' | 'invited' | 'completed' | 'rejected'; diff --git a/packages/backend/src/api/resources/ExternalAccount.ts b/packages/backend/src/api/resources/ExternalAccount.ts index 70e01583206..8c745da1590 100644 --- a/packages/backend/src/api/resources/ExternalAccount.ts +++ b/packages/backend/src/api/resources/ExternalAccount.ts @@ -8,66 +8,35 @@ import { Verification } from './Verification'; */ export class ExternalAccount { constructor( - /** - * The unique identifier for this external account. - */ + /** The unique identifier for this external account. */ readonly id: string, - /** - * The provider name (e.g., `google`). - */ + /** The provider name (e.g., `google`). */ readonly provider: string, - /** - * The unique ID of the user in the provider. - */ + /** The unique ID of the user in the provider. */ readonly providerUserId: string, - /** - * The identification with which this external account is associated. - */ + /** The identification with which this external account is associated. */ readonly identificationId: string, - /** - * The unique ID of the user in the provider. - * @deprecated Use providerUserId instead - */ + /** @deprecated Use `identificationId` instead. */ readonly externalId: string, - /** - * The scopes that the user has granted access to. - */ + /** The scopes that the user has granted access to. */ readonly approvedScopes: string, - /** - * The user's email address. - */ + /** The user's email address. */ readonly emailAddress: string, - /** - * The user's first name. - */ + /** The user's first name. */ readonly firstName: string, - /** - * The user's last name. - */ + /** The user's last name. */ readonly lastName: string, - /** - * The user's image URL. - */ + /** The user's image URL. */ readonly imageUrl: string, - /** - * The user's username. - */ + /** The user's username. */ readonly username: string | null, - /** - * The phone number related to this specific external account. - */ + /** The phone number related to this specific external account. */ readonly phoneNumber: string | null, - /** - * Metadata that can be read from the Frontend API and Backend API and can be set only from the Backend API. - */ + /** Metadata that can be read from the Frontend API and Backend API and can be set only from the [Backend API](https://clerk.com/docs/reference/backend-api). */ readonly publicMetadata: Record | null = {}, - /** - * A descriptive label to differentiate multiple external accounts of the same user for the same provider. - */ + /** A descriptive label to differentiate multiple external accounts of the same user for the same provider. */ readonly label: string | null, - /** - * An object holding information on the verification of this external account. - */ + /** An object holding information on the verification of this external account. */ readonly verification: Verification | null, /** * The `eac_`-prefixed id of the external account resource, which is the id diff --git a/packages/backend/src/api/resources/Feature.ts b/packages/backend/src/api/resources/Feature.ts index 51d20c694b3..871750c140d 100644 --- a/packages/backend/src/api/resources/Feature.ts +++ b/packages/backend/src/api/resources/Feature.ts @@ -7,25 +7,15 @@ import type { FeatureJSON } from './JSON'; */ export class Feature { constructor( - /** - * The unique identifier for the Feature. - */ + /** The unique identifier for the Feature. */ readonly id: string, - /** - * The name of the Feature. - */ + /** The name of the Feature. */ readonly name: string, - /** - * The description of the Feature. - */ + /** The description of the Feature. */ readonly description: string | null, - /** - * The URL-friendly identifier of the Feature. - */ + /** The URL-friendly identifier of the Feature. */ readonly slug: string, - /** - * The URL of the Feature's avatar image. - */ + /** The URL of the Feature's avatar image. */ readonly avatarUrl: string | null, ) {} diff --git a/packages/backend/src/api/resources/IdentificationLink.ts b/packages/backend/src/api/resources/IdentificationLink.ts index 897ff3304b0..b27cb0d2e79 100644 --- a/packages/backend/src/api/resources/IdentificationLink.ts +++ b/packages/backend/src/api/resources/IdentificationLink.ts @@ -1,17 +1,13 @@ import type { IdentificationLinkJSON } from './JSON'; /** - * Contains information about any identifications that might be linked to the email address. + * The `IdentificationLink` object contains information about any identifications that might be linked to the identifier (email address, phone number, etc.). */ export class IdentificationLink { constructor( - /** - * The unique identifier for the identification link. - */ + /** The unique identifier for the identification link. */ readonly id: string, - /** - * The type of the identification link, e.g., `"email_address"`, `"phone_number"`, etc. - */ + /** The type of the identification link, e.g., `"email_address"`, `"phone_number"`, etc. */ readonly type: string, ) {} diff --git a/packages/backend/src/api/resources/Instance.ts b/packages/backend/src/api/resources/Instance.ts index d90cec3d7cb..5a12b4d4dfe 100644 --- a/packages/backend/src/api/resources/Instance.ts +++ b/packages/backend/src/api/resources/Instance.ts @@ -1,9 +1,13 @@ import type { InstanceJSON } from './JSON'; +/** @generateWithEmptyComment */ export class Instance { constructor( + /** The unique identifier for the instance. */ readonly id: string, + /** The type of instance environment, either `'production'` or `'development'`. */ readonly environmentType: string, + /** For browser-like stacks such as browser extensions, Electron, or Capacitor.js, the instance allowed origins need to be updated with the request origin value. For Chrome extensions popup, background, or service worker pages the origin is `chrome-extension://extension_uiid`. For Electron apps the default origin is `http://localhost:3000`. For Capacitor.js, the origin is `capacitor://localhost`. */ readonly allowedOrigins: Array | null, ) {} diff --git a/packages/backend/src/api/resources/InstanceRestrictions.ts b/packages/backend/src/api/resources/InstanceRestrictions.ts index b9aa234d35e..679f50539ec 100644 --- a/packages/backend/src/api/resources/InstanceRestrictions.ts +++ b/packages/backend/src/api/resources/InstanceRestrictions.ts @@ -1,11 +1,17 @@ import type { InstanceRestrictionsJSON } from './JSON'; +/** The `InstanceRestrictions` object represents the [restrictions](https://clerk.com/docs/guides/secure/restricting-access) settings for the current instance. */ export class InstanceRestrictions { constructor( + /** Whether the instance has [**Allowlist**](https://clerk.com/docs/guides/secure/restricting-access#allowlist) enabled. */ readonly allowlist: boolean, + /** Whether the instance has [**Blocklist**](https://clerk.com/docs/guides/secure/restricting-access#blocklist) enabled. */ readonly blocklist: boolean, + /** Whether the instance has [**Block email subaddresses**](https://clerk.com/docs/guides/secure/restricting-access#block-email-subaddresses) enabled. */ readonly blockEmailSubaddresses: boolean, + /** Whether the instance has [**Block sign-ups that use disposable email domains**](https://clerk.com/docs/guides/secure/restricting-access#block-sign-ups-that-use-disposable-email-addresses) enabled. */ readonly blockDisposableEmailDomains: boolean, + /** Whether the instance has [**Ignore dots for Gmail addresses**](https://clerk.com/docs/guides/secure/restricting-access#block-email-subaddresses) enabled. */ readonly ignoreDotsForGmailAddresses: boolean, ) {} diff --git a/packages/backend/src/api/resources/Invitation.ts b/packages/backend/src/api/resources/Invitation.ts index 0d7223770e2..fdb4dce1094 100644 --- a/packages/backend/src/api/resources/Invitation.ts +++ b/packages/backend/src/api/resources/Invitation.ts @@ -12,37 +12,21 @@ export class Invitation { } constructor( - /** - * The unique identifier for the `Invitation`. - */ + /** The unique identifier for the `Invitation`. */ readonly id: string, - /** - * The email address that the invitation was sent to. - */ + /** The email address that the invitation was sent to. */ readonly emailAddress: string, - /** - * [Metadata](https://clerk.com/docs/reference/types/metadata#user-public-metadata){{ target: '_blank' }} that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata. - */ + /** [Metadata](https://clerk.com/docs/reference/types/metadata#user-public-metadata){{ target: '_blank' }} that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata. */ readonly publicMetadata: Record | null, - /** - * The date when the `Invitation` was first created. - */ + /** The Unix timestamp when the `Invitation` was first created. */ readonly createdAt: number, - /** - * The date when the `Invitation` was last updated. - */ + /** The Unix timestamp when the `Invitation` was last updated. */ readonly updatedAt: number, - /** - * The status of the `Invitation`. - */ + /** The status of the `Invitation`. */ readonly status: InvitationStatus, - /** - * The URL that the user can use to accept the invitation. - */ + /** The URL that the user can use to accept the invitation. */ readonly url?: string, - /** - * Whether the `Invitation` has been revoked. - */ + /** Whether the `Invitation` has been revoked. */ readonly revoked?: boolean, ) {} diff --git a/packages/backend/src/api/resources/JSON.ts b/packages/backend/src/api/resources/JSON.ts index 65fc8b3a9ac..27989fd3036 100644 --- a/packages/backend/src/api/resources/JSON.ts +++ b/packages/backend/src/api/resources/JSON.ts @@ -474,25 +474,15 @@ export interface OrganizationInvitationAcceptedJSON extends OrganizationInvitati user_id: string; } -/** - * @interface - */ +/** @inline */ export interface PublicOrganizationDataJSON extends ClerkResourceJSON { - /** - * The name of the Organization. - */ + /** The name of the Organization. */ name: string; - /** - * The slug of the Organization. - */ + /** The slug of the Organization. */ slug: string; - /** - * Holds the default Organization profile image. Compatible with Clerk's [Image Optimization](https://clerk.com/docs/guides/development/image-optimization). - */ + /** Holds the default Organization profile image. Compatible with Clerk's [Image Optimization](https://clerk.com/docs/guides/development/image-optimization). */ image_url?: string; - /** - * Whether the Organization has a profile image. - */ + /** Whether the Organization has a profile image. */ has_image: boolean; } diff --git a/packages/backend/src/api/resources/M2MToken.ts b/packages/backend/src/api/resources/M2MToken.ts index a9ad2b1d2e4..95ec6c41b81 100644 --- a/packages/backend/src/api/resources/M2MToken.ts +++ b/packages/backend/src/api/resources/M2MToken.ts @@ -37,20 +37,31 @@ function extractCustomClaims(payload: M2MJwtPayload): Record | null } /** - * The Backend `M2MToken` object holds information about a machine-to-machine token. + * The Backend `M2MToken` object holds information about a [machine-to-machine token](https://clerk.com/docs/guides/development/machine-auth/m2m-tokens). */ export class M2MToken { constructor( + /** The ID of the M2M token. */ readonly id: string, + /** The subject of the M2M token. */ readonly subject: string, + /** The scopes of the M2M token. */ readonly scopes: string[], + /** The claims of the M2M token. */ readonly claims: Record | null, + /** Whether the M2M token has been revoked. */ readonly revoked: boolean, + /** The reason for revoking the M2M token. */ readonly revocationReason: string | null, + /** Whether the M2M token has expired. */ readonly expired: boolean, + /** The Unix timestamp when the M2M token expires. */ readonly expiration: number | null, + /** The Unix timestamp when the M2M token was created. */ readonly createdAt: number, + /** The Unix timestamp when the M2M token was last updated. */ readonly updatedAt: number, + /** The token string. */ readonly token?: string, ) {} diff --git a/packages/backend/src/api/resources/Machine.ts b/packages/backend/src/api/resources/Machine.ts index 8f01f96570b..34f9175c215 100644 --- a/packages/backend/src/api/resources/Machine.ts +++ b/packages/backend/src/api/resources/Machine.ts @@ -5,13 +5,21 @@ import type { MachineJSON } from './JSON'; */ export class Machine { constructor( + /** The unique identifier for the machine. */ readonly id: string, + /** The name of the machine. */ readonly name: string, + /** The ID of the instance the machine belongs to. */ readonly instanceId: string, + /** The Unix timestamp when the machine was created. */ readonly createdAt: number, + /** The Unix timestamp when the machine was last updated. */ readonly updatedAt: number, + /** The machines that the current machine has access to. */ readonly scopedMachines: Machine[], + /** The default time-to-live (TTL) in seconds for tokens created by this machine. */ readonly defaultTokenTtl: number, + /** The secret key for the machine. */ readonly secretKey?: string, ) {} diff --git a/packages/backend/src/api/resources/MachineScope.ts b/packages/backend/src/api/resources/MachineScope.ts index 1cfc1392435..dfccfd7464e 100644 --- a/packages/backend/src/api/resources/MachineScope.ts +++ b/packages/backend/src/api/resources/MachineScope.ts @@ -5,9 +5,13 @@ import type { MachineScopeJSON } from './JSON'; */ export class MachineScope { constructor( + /** The ID of the machine that has access to the target machine. */ readonly fromMachineId: string, + /** The ID of the machine that is being accessed. */ readonly toMachineId: string, + /** The Unix timestamp when the machine scope was created. */ readonly createdAt?: number, + /** Whether the machine scope has been deleted. */ readonly deleted?: boolean, ) {} diff --git a/packages/backend/src/api/resources/MachineSecretKey.ts b/packages/backend/src/api/resources/MachineSecretKey.ts index b2afe99d1d7..ba6245efe55 100644 --- a/packages/backend/src/api/resources/MachineSecretKey.ts +++ b/packages/backend/src/api/resources/MachineSecretKey.ts @@ -1,8 +1,5 @@ import type { MachineSecretKeyJSON } from './JSON'; -/** - * The Backend `MachineSecretKey` object holds information about a machine secret key. - */ export class MachineSecretKey { constructor(readonly secret: string) {} diff --git a/packages/backend/src/api/resources/OAuthApplication.ts b/packages/backend/src/api/resources/OAuthApplication.ts index 9061904b387..bb871cdf559 100644 --- a/packages/backend/src/api/resources/OAuthApplication.ts +++ b/packages/backend/src/api/resources/OAuthApplication.ts @@ -5,85 +5,45 @@ import type { OAuthApplicationJSON } from './JSON'; */ export class OAuthApplication { constructor( - /** - * The unique identifier for the OAuth application. - */ + /** The unique identifier for the OAuth application. */ readonly id: string, - /** - * The ID of the instance that this OAuth application belongs to. - */ + /** The ID of the instance that this OAuth application belongs to. */ readonly instanceId: string, - /** - * The name of the new OAuth application. - */ + /** The name of the new OAuth application. */ readonly name: string, - /** - * The ID of the client associated with the OAuth application. - */ + /** The ID of the client associated with the OAuth application. */ readonly clientId: string, - /** - * The public-facing URL of the OAuth application, often shown on consent screens. - */ + /** The public-facing URL of the OAuth application, often shown on consent screens. */ readonly clientUri: string | null, - /** - * The URL of the image or logo representing the OAuth application. - */ + /** The URL of the image or logo representing the OAuth application. */ readonly clientImageUrl: string | null, - /** - * Specifies whether the OAuth application is dynamically registered. - */ + /** Whether the OAuth application is dynamically registered. */ readonly dynamicallyRegistered: boolean, - /** - * Specifies whether the consent screen should be displayed in the authentication flow. Cannot be disabled for dynamically registered OAuth applications. - */ + /** Whether the consent screen should be displayed in the authentication flow. Cannot be disabled for dynamically registered OAuth applications. */ readonly consentScreenEnabled: boolean, - /** - * Specifies whether the Proof Key of Code Exchange (PKCE) flow should be required in the authentication flow. - */ + /** Whether the Proof Key of Code Exchange (PKCE) flow should be required in the authentication flow. */ readonly pkceRequired: boolean, - /** - * Indicates whether the client is public. If true, the Proof Key of Code Exchange (PKCE) flow can be used. - */ + /** Whether the client is public. If true, the Proof Key of Code Exchange (PKCE) flow can be used. */ readonly isPublic: boolean, // NOTE: `public` is reserved - /** - * Scopes for the new OAuth application. - */ + /** Scopes for the new OAuth application. */ readonly scopes: string, - /** - * An array of redirect URIs of the new OAuth application. - */ + /** An array of redirect URIs of the new OAuth application. */ readonly redirectUris: Array, - /** - * The URL used to authorize the user and obtain an authorization code. - */ + /** The URL used to authorize the user and obtain an authorization code. */ readonly authorizeUrl: string, - /** - * The URL used by the client to exchange an authorization code for an access token. - */ + /** The URL used by the client to exchange an authorization code for an access token. */ readonly tokenFetchUrl: string, - /** - * The URL where the client can retrieve user information using an access token. - */ + /** The URL where the client can retrieve user information using an access token. */ readonly userInfoUrl: string, - /** - * The OpenID Connect discovery endpoint URL for this OAuth application. - */ + /** The OpenID Connect discovery endpoint URL for this OAuth application. */ readonly discoveryUrl: string, - /** - * The URL used to introspect and validate issued access tokens. - */ + /** The URL used to introspect and validate issued access tokens. */ readonly tokenIntrospectionUrl: string, - /** - * The date when the OAuth application was first created. - */ + /** The Unix timestamp when the OAuth application was first created. */ readonly createdAt: number, - /** - * The date when the OAuth application was last updated. - */ + /** The Unix timestamp when the OAuth application was last updated. */ readonly updatedAt: number, - /** - * The client secret associated with the OAuth application. Empty if public client. - */ + /** The client secret associated with the OAuth application. Empty if public client. */ readonly clientSecret?: string, ) {} diff --git a/packages/backend/src/api/resources/OauthAccessToken.ts b/packages/backend/src/api/resources/OauthAccessToken.ts index 45ec8d056b4..58277e3001d 100644 --- a/packages/backend/src/api/resources/OauthAccessToken.ts +++ b/packages/backend/src/api/resources/OauthAccessToken.ts @@ -5,42 +5,23 @@ import type { OauthAccessTokenJSON } from './JSON'; */ export class OauthAccessToken { constructor( - /** - * The ID of the external account associated with this token. - */ + /** The ID of the external account associated with this token. */ readonly externalAccountId: string, - /** - * The OAuth provider (e.g., `google`, `github`). - */ + /** The OAuth provider (e.g., `google`, `github`). */ readonly provider: string, - /** - * The OAuth access token. - */ + /** The OAuth access token. */ readonly token: string, - /** - * Metadata that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. - */ + /** Metadata that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. */ readonly publicMetadata: Record = {}, - /** - * A descriptive label to differentiate multiple access tokens of the same user for the same provider. - */ + /** A descriptive label to differentiate multiple access tokens of the same user for the same provider. */ readonly label: string, - /** - * The scopes granted for this access token. - */ + /** The scopes granted for this access token. */ readonly scopes?: string[], - /** - * The token secret, if applicable (e.g., for OAuth 1.0 providers). - */ + /** The token secret, if applicable (e.g., for OAuth 1.0 providers). */ readonly tokenSecret?: string, - /** - * The date when the access token expires. - */ + /** The Unix timestamp when the access token expires. */ readonly expiresAt?: number, - /** - * The user's OIDC ID Token, if available. - * This token contains user identity information as a JWT and is returned when the provider supports [OpenID Connect (OIDC)](/docs/guides/configure/auth-strategies/oauth/overview). Not all OAuth providers implement OIDC, so this field may be `undefined` for some providers. - */ + /** The user's OIDC ID Token, if available. This token contains user identity information as a JWT and is returned when the provider supports [OpenID Connect (OIDC)](/docs/guides/configure/auth-strategies/oauth/overview). Not all OAuth providers implement OIDC, so this field may be `undefined` for some providers. */ readonly idToken?: string, ) {} diff --git a/packages/backend/src/api/resources/Organization.ts b/packages/backend/src/api/resources/Organization.ts index 81875474e77..1c5854ce4d7 100644 --- a/packages/backend/src/api/resources/Organization.ts +++ b/packages/backend/src/api/resources/Organization.ts @@ -11,57 +11,31 @@ export class Organization { } constructor( - /** - * The unique identifier for the Organization. - */ + /** The unique identifier for the Organization. */ readonly id: string, - /** - * The name of the Organization. - */ + /** The name of the Organization. */ readonly name: string, - /** - * The URL-friendly identifier of the user's active Organization. If supplied, it must be unique for the instance. - */ + /** The URL-friendly identifier of the user's active Organization. If supplied, it must be unique for the instance. */ readonly slug: string, - /** - * Holds the Organization's logo. Compatible with Clerk's [Image Optimization](https://clerk.com/docs/guides/development/image-optimization). - */ + /** Holds the Organization's logo. Compatible with Clerk's [Image Optimization](https://clerk.com/docs/guides/development/image-optimization). */ readonly imageUrl: string, - /** - * Whether the Organization has an image. - */ + /** Whether the Organization has an image. */ readonly hasImage: boolean, - /** - * The date when the Organization was first created. - */ + /** The Unix timestamp when the Organization was first created. */ readonly createdAt: number, - /** - * The date when the Organization was last updated. - */ + /** The Unix timestamp when the Organization was last updated. */ readonly updatedAt: number, - /** - * Metadata that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. - */ + /** Metadata that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. */ readonly publicMetadata: OrganizationPublicMetadata | null = {}, - /** - * Metadata that can be read and set only from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}. - */ + /** Metadata that can be read and set only from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}. */ readonly privateMetadata: OrganizationPrivateMetadata = {}, - /** - * The maximum number of memberships allowed in the Organization. - */ + /** The maximum number of memberships allowed in the Organization. */ readonly maxAllowedMemberships: number, - /** - * Whether the Organization allows admins to delete users. - */ + /** Whether the Organization allows admins to delete users. */ readonly adminDeleteEnabled: boolean, - /** - * The number of members in the Organization. - */ + /** The number of members in the Organization. */ readonly membersCount?: number, - /** - * The ID of the user who created the Organization. - */ + /** The ID of the user who created the Organization. */ readonly createdBy?: string, ) {} diff --git a/packages/backend/src/api/resources/OrganizationDomain.ts b/packages/backend/src/api/resources/OrganizationDomain.ts index ee672a6926b..31a63a8e750 100644 --- a/packages/backend/src/api/resources/OrganizationDomain.ts +++ b/packages/backend/src/api/resources/OrganizationDomain.ts @@ -2,17 +2,36 @@ import type { OrganizationEnrollmentMode } from './Enums'; import type { OrganizationDomainJSON } from './JSON'; import { OrganizationDomainVerification } from './Verification'; +/** The `OrganizationDomain` object is the model around an Organization's [Verified Domain](https://clerk.com/docs/guides/organizations/add-members/verified-domains). */ export class OrganizationDomain { constructor( + /** The unique identifier of the domain. */ readonly id: string, + /** The ID of the Organization that the domain belongs to. */ readonly organizationId: string, + /** The name of the domain. */ readonly name: string, + /** + * The enrollment mode that determines how matching users are added to the Organization. + * + *
      + *
    • `manual_invitation`: No automatic enrollment. Users with a matching email domain are not given any [invitation](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-invitations) or [suggestion](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-suggestions); an [admin](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions#default-roles) must invite them manually.
      • + *
    • `automatic_invitation`: Users with a matching email domain automatically receive a pending [invitation](https://clerk.com/docs/reference/types/organization-invitation) (assigned the Organization's default role) which they can accept to join.
      • + *
    • `automatic_suggestion`: Users with a matching email domain automatically receive a [suggestion](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-suggestions) to join, which they can request.
      • + *
    + */ readonly enrollmentMode: OrganizationEnrollmentMode, + /** The verification details of the domain. */ readonly verification: OrganizationDomainVerification | null, + /** The total number of pending invitations for the domain. */ readonly totalPendingInvitations: number, + /** The total number of pending suggestions for the domain. */ readonly totalPendingSuggestions: number, + /** The Unix timestamp when the domain was created. */ readonly createdAt: number, + /** The Unix timestamp when the domain was last updated. */ readonly updatedAt: number, + /** The email address used to verify the domain. */ readonly affiliationEmailAddress: string | null, ) {} diff --git a/packages/backend/src/api/resources/OrganizationInvitation.ts b/packages/backend/src/api/resources/OrganizationInvitation.ts index ae41a1ebbcd..e58603bf8c8 100644 --- a/packages/backend/src/api/resources/OrganizationInvitation.ts +++ b/packages/backend/src/api/resources/OrganizationInvitation.ts @@ -12,57 +12,31 @@ export class OrganizationInvitation { } constructor( - /** - * The unique identifier for the `OrganizationInvitation`. - */ + /** The unique identifier for the `OrganizationInvitation`. */ readonly id: string, - /** - * The email address of the user who is invited to the [`Organization`](https://clerk.com/docs/reference/backend/types/backend-organization). - */ + /** The email address of the user who is invited to the [`Organization`](https://clerk.com/docs/reference/backend/types/backend-organization). */ readonly emailAddress: string, - /** - * The Role of the invited user. - */ + /** The [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) of the invited user. */ readonly role: OrganizationMembershipRole, - /** - * The name of the Role of the invited user. - */ + /** The name of the [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) of the invited user. */ readonly roleName: string, - /** - * The ID of the [`Organization`](https://clerk.com/docs/reference/backend/types/backend-organization) that the user is invited to. - */ + /** The ID of the [`Organization`](https://clerk.com/docs/reference/backend/types/backend-organization) that the user is invited to. */ readonly organizationId: string, - /** - * The date when the invitation was first created. - */ + /** The Unix timestamp when the invitation was first created. */ readonly createdAt: number, - /** - * The date when the invitation was last updated. - */ + /** The Unix timestamp when the invitation was last updated. */ readonly updatedAt: number, - /** - * The date when the invitation expires. - */ + /** The Unix timestamp when the invitation expires. */ readonly expiresAt: number, - /** - * The URL that the user can use to accept the invitation. - */ + /** The URL that the user can use to accept the invitation. */ readonly url: string | null, - /** - * The status of the invitation. - */ + /** The status of the invitation. */ readonly status?: OrganizationInvitationStatus, - /** - * Metadata that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. - */ + /** Metadata that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. */ readonly publicMetadata: OrganizationInvitationPublicMetadata = {}, - /** - * Metadata that can be read and set only from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}. - */ + /** Metadata that can be read and set only from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}. */ readonly privateMetadata: OrganizationInvitationPrivateMetadata = {}, - /** - * Public data about the Organization that the user is invited to. - */ + /** Public data about the Organization that the user is invited to. */ readonly publicOrganizationData?: PublicOrganizationDataJSON | null, ) {} diff --git a/packages/backend/src/api/resources/OrganizationMembership.ts b/packages/backend/src/api/resources/OrganizationMembership.ts index 83abc7b6d07..774bfa4d0b1 100644 --- a/packages/backend/src/api/resources/OrganizationMembership.ts +++ b/packages/backend/src/api/resources/OrganizationMembership.ts @@ -13,41 +13,23 @@ export class OrganizationMembership { } constructor( - /** - * The unique identifier for the membership. - */ + /** The unique identifier for the membership. */ readonly id: string, - /** - * The Role of the user. - */ + /** The [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) of the user. */ readonly role: OrganizationMembershipRole, - /** - * The Permissions granted to the user in the Organization. - */ + /** The [Permissions](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) granted to the user in the Organization. */ readonly permissions: string[], - /** - * Metadata that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. - */ + /** Metadata that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. */ readonly publicMetadata: OrganizationMembershipPublicMetadata = {}, - /** - * Metadata that can be read and set only from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}. - */ + /** Metadata that can be read and set only from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}. */ readonly privateMetadata: OrganizationMembershipPrivateMetadata = {}, - /** - * The date when the membership was first created. - */ + /** The Unix timestamp when the membership was first created. */ readonly createdAt: number, - /** - * The date when the membership was last updated. - */ + /** The Unix timestamp when the membership was last updated. */ readonly updatedAt: number, - /** - * The Organization that the user is a member of. - */ + /** The Organization that the user is a member of. */ readonly organization: Organization, - /** - * Public information about the user that this membership belongs to. - */ + /** Public information about the user that this membership belongs to. */ readonly publicUserData?: OrganizationMembershipPublicUserData | null, ) {} diff --git a/packages/backend/src/api/resources/OrganizationSettings.ts b/packages/backend/src/api/resources/OrganizationSettings.ts index 22bbedeb28c..e7ebc97f185 100644 --- a/packages/backend/src/api/resources/OrganizationSettings.ts +++ b/packages/backend/src/api/resources/OrganizationSettings.ts @@ -1,17 +1,36 @@ import type { DomainsEnrollmentModes } from './Enums'; import type { OrganizationSettingsJSON } from './JSON'; +/** The `OrganizationSettings` object represents the [Organization-related settings](https://clerk.com/docs/guides/organizations/configure) for the current instance. */ export class OrganizationSettings { constructor( + /** Whether the instance has [Organizations](https://clerk.com/docs/guides/organizations/overview) enabled. */ readonly enabled: boolean, + /** The maximum number of [memberships allowed](https://clerk.com/docs/guides/organizations/configure#membership-limits) per Organization. */ readonly maxAllowedMemberships: number, + /** The maximum number of Roles allowed per Organization. */ readonly maxAllowedRoles: number, + /** The maximum number of Permissions allowed per Organization. */ readonly maxAllowedPermissions: number, + /** The default [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) for an Organization creator. */ readonly creatorRole: string, + /** Whether [admins](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions#default-roles) are allowed to delete Organizations. */ readonly adminDeleteEnabled: boolean, + /** Whether the instance has [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains) enabled. */ readonly domainsEnabled: boolean, + /** Whether the instance has [Organization slugs](https://clerk.com/docs/guides/organizations/configure#organization-slugs) disabled. */ readonly slugDisabled: boolean, + /** + * The [enrollment modes](https://clerk.com/docs/guides/organizations/add-members/verified-domains#enable-verified-domains) available for Verified Domains. + * + *
      + *
    • `manual_invitation`: No automatic enrollment. Users with a matching email domain are not given any [invitation](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-invitations) or [suggestion](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-suggestions); an [admin](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions#default-roles) must invite them manually.
      • + *
    • `automatic_invitation`: Users with a matching email domain automatically receive a pending [invitation](https://clerk.com/docs/reference/types/organization-invitation) (assigned the Organization's default Role) which they can accept to join.
      • + *
    • `automatic_suggestion`: Users with a matching email domain automatically receive a [suggestion](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-suggestions) to join, which they can request.
      • + *
    + */ readonly domainsEnrollmentModes: Array, + /** The default [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) for the Organization's [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains). */ readonly domainsDefaultRole: string, ) {} diff --git a/packages/backend/src/api/resources/Permission.ts b/packages/backend/src/api/resources/Permission.ts index 2b1b76174c9..a6faf3bba0a 100644 --- a/packages/backend/src/api/resources/Permission.ts +++ b/packages/backend/src/api/resources/Permission.ts @@ -5,29 +5,17 @@ import type { PermissionJSON } from './JSON'; */ export class Permission { constructor( - /** - * The unique identifier for the permission. - */ + /** The unique identifier for the permission. */ readonly id: string, - /** - * The name of the permission. - */ + /** The name of the permission. */ readonly name: string, - /** - * The unique key of the permission, in the format `org:feature:action`. - */ + /** The unique key of the permission, in the format `org:feature:action`. */ readonly key: string, - /** - * A description of the permission. - */ + /** A description of the permission. */ readonly description: string, - /** - * The date when the permission was first created. - */ + /** The Unix timestamp when the permission was first created. */ readonly createdAt: number, - /** - * The date when the permission was last updated. - */ + /** The Unix timestamp when the permission was last updated. */ readonly updatedAt: number, ) {} diff --git a/packages/backend/src/api/resources/PhoneNumber.ts b/packages/backend/src/api/resources/PhoneNumber.ts index ce60077c727..70ff86c4238 100644 --- a/packages/backend/src/api/resources/PhoneNumber.ts +++ b/packages/backend/src/api/resources/PhoneNumber.ts @@ -11,29 +11,17 @@ import { Verification } from './Verification'; */ export class PhoneNumber { constructor( - /** - * The unique identifier for this phone number. - */ + /** The unique identifier for this phone number. */ readonly id: string, - /** - * The value of this phone number, in [E.164 format](https://en.wikipedia.org/wiki/E.164). - */ + /** The value of this phone number, in [E.164 format](https://en.wikipedia.org/wiki/E.164). */ readonly phoneNumber: string, - /** - * Set to `true` if this phone number is reserved for multi-factor authentication (2FA). Set to `false` otherwise. - */ + /** Whether the phone number is reserved for multi-factor authentication (2FA). */ readonly reservedForSecondFactor: boolean, - /** - * Set to `true` if this phone number is the default second factor. Set to `false` otherwise. A user must have exactly one default second factor, if multi-factor authentication (2FA) is enabled. - */ + /** Whether the phone number is the default second factor. A user must have exactly one default second factor, if multi-factor authentication (2FA) is enabled. */ readonly defaultSecondFactor: boolean, - /** - * An object holding information on the verification of this phone number. - */ + /** An object holding information on the verification of this phone number. */ readonly verification: Verification | null, - /** - * An object containing information about any other identification that might be linked to this phone number. - */ + /** An object containing information about any other identification that might be linked to this phone number. */ readonly linkedTo: IdentificationLink[], ) {} diff --git a/packages/backend/src/api/resources/RedirectUrl.ts b/packages/backend/src/api/resources/RedirectUrl.ts index fd2982875cd..4cabc07bb8e 100644 --- a/packages/backend/src/api/resources/RedirectUrl.ts +++ b/packages/backend/src/api/resources/RedirectUrl.ts @@ -7,9 +7,7 @@ The Backend `RedirectUrl` object represents a redirect URL in your application. */ export class RedirectUrl { constructor( - /** - * The unique identifier for the redirect URL. - */ + /** The unique identifier for the redirect URL. */ readonly id: string, /** * The full URL value prefixed with `https://` or a custom scheme. @@ -17,13 +15,9 @@ export class RedirectUrl { * @example my-app://oauth-callback */ readonly url: string, - /** - * The date when the redirect URL was first created. - */ + /** The Unix timestamp when the redirect URL was first created. */ readonly createdAt: number, - /** - * The date when the redirect URL was last updated. - */ + /** The Unix timestamp when the redirect URL was last updated. */ readonly updatedAt: number, ) {} diff --git a/packages/backend/src/api/resources/Role.ts b/packages/backend/src/api/resources/Role.ts index d390e197c7a..2ac03e79872 100644 --- a/packages/backend/src/api/resources/Role.ts +++ b/packages/backend/src/api/resources/Role.ts @@ -2,41 +2,25 @@ import type { RoleJSON } from './JSON'; import { Permission } from './Permission'; /** - * The Backend `Role` object represents an organization role that can be assigned to organization members. + * The Backend `Role` object represents an Organization [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) that can be assigned to Organization members. */ export class Role { constructor( - /** - * The unique identifier for the role. - */ + /** The unique identifier for the Role. */ readonly id: string, - /** - * The name of the role. - */ + /** The name of the Role. */ readonly name: string, - /** - * The unique key of the role, in the format `org:role`. - */ + /** The unique key of the Role, in the format `org:role`. */ readonly key: string, - /** - * A description of the role. - */ + /** A description of the Role. */ readonly description: string | null, - /** - * The permissions assigned to the role. - */ + /** The [Permissions](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) assigned to the Role. */ readonly permissions: Permission[], - /** - * Whether this role is eligible to be an organization creator role. - */ + /** Whether this Role is eligible to be an Organization creator Role. */ readonly isCreatorEligible: boolean, - /** - * The date when the role was first created. - */ + /** The Unix timestamp when the Role was first created. */ readonly createdAt: number, - /** - * The date when the role was last updated. - */ + /** The Unix timestamp when the Role was last updated. */ readonly updatedAt: number, ) {} diff --git a/packages/backend/src/api/resources/RoleSet.ts b/packages/backend/src/api/resources/RoleSet.ts index 732cd28bd20..685e54fcf72 100644 --- a/packages/backend/src/api/resources/RoleSet.ts +++ b/packages/backend/src/api/resources/RoleSet.ts @@ -1,41 +1,25 @@ import type { RoleSetItemJSON, RoleSetJSON, RoleSetMigrationJSON } from './JSON'; /** - * The Backend `RoleSetItem` object represents a role that belongs to a {@link RoleSet}. + * The Backend `RoleSetItem` object represents a [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) that belongs to a {@link RoleSet}. */ export class RoleSetItem { constructor( - /** - * The unique identifier for the role. - */ + /** The unique identifier for the Role. */ readonly id: string, - /** - * The name of the role. - */ + /** The name of the Role. */ readonly name: string, - /** - * The unique key of the role. - */ + /** The unique key of the Role. */ readonly key: string, - /** - * A description of the role. - */ + /** A description of the Role. */ readonly description: string | null, - /** - * The date when the role was first created. - */ + /** The Unix timestamp when the Role was first created. */ readonly createdAt: number, - /** - * The date when the role was last updated. - */ + /** The Unix timestamp when the Role was last updated. */ readonly updatedAt: number, - /** - * The number of organization members that have this role. - */ + /** The number of Organization members that have this Role. */ readonly membersCount?: number | null, - /** - * Whether any organization members have this role. - */ + /** Whether any Organization members have this Role. */ readonly hasMembers?: boolean | null, ) {} diff --git a/packages/backend/src/api/resources/SamlConnection.ts b/packages/backend/src/api/resources/SamlConnection.ts index f5c277f0dba..5f58b9210a0 100644 --- a/packages/backend/src/api/resources/SamlConnection.ts +++ b/packages/backend/src/api/resources/SamlConnection.ts @@ -2,93 +2,51 @@ import type { AttributeMappingJSON, SamlConnectionJSON } from './JSON'; /** * The Backend `SamlConnection` object holds information about a SAML connection for an organization. - * @deprecated Use `EnterpriseConnection` instead. + * @deprecated Use [`EnterpriseConnection`](https://clerk.com/docs/reference/backend/types/backend-enterprise-connection) instead. */ export class SamlConnection { constructor( - /** - * The unique identifier for the connection. - */ + /** The unique identifier for the connection. */ readonly id: string, - /** - * The name to use as a label for the connection. - */ + /** The name to use as a label for the connection. */ readonly name: string, - /** - * The domain of your Organization. Sign in flows using an email with this domain will use the connection. - */ + /** The domain of your Organization. Sign in flows using an email with this domain will use the connection. */ readonly domain: string, - /** - * The Organization ID of the Organization. - */ + /** The Organization ID of the Organization. */ readonly organizationId: string | null, - /** - * The Entity ID as provided by the Identity Provider (IdP). - */ + /** The Entity ID as provided by the Identity Provider (IdP). */ readonly idpEntityId: string | null, - /** - * The Single-Sign On URL as provided by the Identity Provider (IdP). - */ + /** The Single-Sign On URL as provided by the Identity Provider (IdP). */ readonly idpSsoUrl: string | null, - /** - * The X.509 certificate as provided by the Identity Provider (IdP). - */ + /** The X.509 certificate as provided by the Identity Provider (IdP). */ readonly idpCertificate: string | null, - /** - * The URL which serves the Identity Provider (IdP) metadata. If present, it takes priority over the corresponding individual properties. - */ + /** The URL which serves the Identity Provider (IdP) metadata. If present, it takes priority over the corresponding individual properties. */ readonly idpMetadataUrl: string | null, - /** - * The XML content of the Identity Provider (IdP) metadata file. If present, it takes priority over the corresponding individual properties. - */ + /** The XML content of the Identity Provider (IdP) metadata file. If present, it takes priority over the corresponding individual properties. */ readonly idpMetadata: string | null, - /** - * The Assertion Consumer Service (ACS) URL of the connection. - */ + /** The Assertion Consumer Service (ACS) URL of the connection. */ readonly acsUrl: string, - /** - * The Entity ID as provided by the Service Provider (Clerk). - */ + /** The Entity ID as provided by the Service Provider (Clerk). */ readonly spEntityId: string, - /** - * The metadata URL as provided by the Service Provider (Clerk). - */ + /** The metadata URL as provided by the Service Provider (Clerk). */ readonly spMetadataUrl: string, - /** - * Indicates whether the connection is active or not. - */ + /** Whether the connection is active or not. */ readonly active: boolean, - /** - * The Identity Provider (IdP) of the connection. - */ + /** The Identity Provider (IdP) of the connection. */ readonly provider: string, - /** - * The number of users associated with the connection. - */ + /** The number of users associated with the connection. */ readonly userCount: number, - /** - * Indicates whether the connection syncs user attributes between the Service Provider (SP) and Identity Provider (IdP) or not. - */ + /** Whether the connection syncs user attributes between the Service Provider (SP) and Identity Provider (IdP) or not. */ readonly syncUserAttributes: boolean, - /** - * Indicates whether users with an email address subdomain are allowed to use this connection in order to authenticate or not. - */ + /** Whether users with an email address subdomain are allowed to use this connection in order to authenticate or not. */ readonly allowSubdomains: boolean, - /** - * Indicates whether the connection allows Identity Provider (IdP) initiated flows or not. - */ + /** Whether the connection allows Identity Provider (IdP) initiated flows or not. */ readonly allowIdpInitiated: boolean, - /** - * The date when the connection was first created. - */ + /** The Unix timestamp when the connection was first created. */ readonly createdAt: number, - /** - * The date when the SAML connection was last updated. - */ + /** The Unix timestamp when the connection was last updated. */ readonly updatedAt: number, - /** - * Defines the attribute name mapping between the Identity Provider (IdP) and Clerk's [`User`](https://clerk.com/docs/reference/objects/user) properties. - */ + /** Defines the attribute name mapping between the Identity Provider (IdP) and Clerk's [`User`](https://clerk.com/docs/reference/objects/user) properties. */ readonly attributeMapping: AttributeMapping, ) {} static fromJSON(data: SamlConnectionJSON): SamlConnection { diff --git a/packages/backend/src/api/resources/Session.ts b/packages/backend/src/api/resources/Session.ts index 55a152d5f53..968be156748 100644 --- a/packages/backend/src/api/resources/Session.ts +++ b/packages/backend/src/api/resources/Session.ts @@ -5,37 +5,21 @@ import type { SessionActivityJSON, SessionJSON } from './JSON'; */ export class SessionActivity { constructor( - /** - * The unique identifier for the session activity record. - */ + /** The unique identifier for the session activity record. */ readonly id: string, - /** - * Will be set to `true` if the session activity came from a mobile device. Set to `false` otherwise. - */ + /** Whether the session activity came from a mobile device. */ readonly isMobile: boolean, - /** - * The IP address from which this session activity originated. - */ + /** The IP address from which this session activity originated. */ readonly ipAddress?: string, - /** - * The city from which this session activity occurred. Resolved by IP address geo-location. - */ + /** The city from which this session activity occurred. Resolved by IP address geo-location. */ readonly city?: string, - /** - * The country from which this session activity occurred. Resolved by IP address geo-location. - */ + /** The country from which this session activity occurred. Resolved by IP address geo-location. */ readonly country?: string, - /** - * The version of the browser from which this session activity occurred. - */ + /** The version of the browser from which this session activity occurred. */ readonly browserVersion?: string, - /** - * The name of the browser from which this session activity occurred. - */ + /** The name of the browser from which this session activity occurred. */ readonly browserName?: string, - /** - * The type of the device which was used in this session activity. - */ + /** The type of the device which was used in this session activity. */ readonly deviceType?: string, ) {} @@ -54,57 +38,33 @@ export class SessionActivity { } /** - * The Backend `Session` object is similar to the [`Session`](https://clerk.com/docs/reference/objects/session) object as it is an abstraction over an HTTP session and models the period of information exchange between a user and the server. However, the Backend `Session` object is different as it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/model/Session) and is not directly accessible from the Frontend API. + * The Backend `Session` object is similar to the [`Session`](https://clerk.com/docs/reference/objects/session) object as it is an abstraction over an HTTP session and models the period of information exchange between a user and the server. However, the Backend `Session` object is different as it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/model/Session){{ target: '_blank' }} and is not directly accessible from the Frontend API. */ export class Session { constructor( - /** - * The unique identifier for the `Session`. - */ + /** The unique identifier for the `Session`. */ readonly id: string, - /** - * The ID of the client associated with the `Session`. - */ + /** The ID of the client associated with the `Session`. */ readonly clientId: string, - /** - * The ID of the user associated with the `Session`. - */ + /** The ID of the user associated with the `Session`. */ readonly userId: string, - /** - * The current state of the `Session`. - */ + /** The current state of the `Session`. */ readonly status: string, - /** - * The time the session was last active on the [`Client`](https://clerk.com/docs/reference/backend/types/backend-client). - */ + /** The time the session was last active on the [`Client`](https://clerk.com/docs/reference/backend/types/backend-client). */ readonly lastActiveAt: number, - /** - * The date when the `Session` will expire. - */ + /** The Unix timestamp when the `Session` will expire. */ readonly expireAt: number, - /** - * The date when the `Session` will be abandoned. - */ + /** The Unix timestamp when the `Session` will be abandoned. */ readonly abandonAt: number, - /** - * The date when the `Session` was first created. - */ + /** The Unix timestamp when the `Session` was first created. */ readonly createdAt: number, - /** - * The date when the `Session` was last updated. - */ + /** The Unix timestamp when the `Session` was last updated. */ readonly updatedAt: number, - /** - * The ID of the last active Organization. - */ + /** The ID of the last [Active Organization](!active-organization). */ readonly lastActiveOrganizationId?: string, - /** - * An object that provides additional information about this session, focused around user activity data. - */ + /** An object that provides additional information about this session, focused around user activity data. */ readonly latestActivity?: SessionActivity, - /** - * The JWT actor for the session. Holds identifier for the user that is impersonating the current user. Read more about [impersonation](https://clerk.com/docs/guides/users/impersonation). - */ + /** The JWT actor for the session. Holds identifier for the user that is impersonating the current user. Read more about [impersonation](https://clerk.com/docs/guides/users/impersonation). */ readonly actor: Record | null = null, ) {} diff --git a/packages/backend/src/api/resources/SignInTokens.ts b/packages/backend/src/api/resources/SignInTokens.ts index 218a2dc9018..665e932ad2e 100644 --- a/packages/backend/src/api/resources/SignInTokens.ts +++ b/packages/backend/src/api/resources/SignInTokens.ts @@ -1,13 +1,23 @@ import type { SignInTokenJSON } from './JSON'; +/** + * The Backend `SignInToken` object holds information about a sign-in token. + */ export class SignInToken { constructor( + /** The unique identifier for the token. */ readonly id: string, + /** The ID of the user the token is for. */ readonly userId: string, + /** The token itself. */ readonly token: string, + /** The status of the token. */ readonly status: string, + /** The URL the token is for. */ readonly url: string, + /** The Unix timestamp when the token was created. */ readonly createdAt: number, + /** The Unix timestamp when the token was last updated. */ readonly updatedAt: number, ) {} diff --git a/packages/backend/src/api/resources/TestingToken.ts b/packages/backend/src/api/resources/TestingToken.ts index 1c2bd3e6f08..3509a27a431 100644 --- a/packages/backend/src/api/resources/TestingToken.ts +++ b/packages/backend/src/api/resources/TestingToken.ts @@ -1,8 +1,11 @@ import type { TestingTokenJSON } from './JSON'; +/** The Backend `TestingToken` object holds information about a [Testing Token](https://clerk.com/docs/guides/development/testing/overview#testing-tokens). */ export class TestingToken { constructor( + /** The token string. */ readonly token: string, + /** The Unix timestamp when the token expires. */ readonly expiresAt: number, ) {} diff --git a/packages/backend/src/api/resources/User.ts b/packages/backend/src/api/resources/User.ts index d4042841a52..acfcff22858 100644 --- a/packages/backend/src/api/resources/User.ts +++ b/packages/backend/src/api/resources/User.ts @@ -16,138 +16,72 @@ export class User { } constructor( - /** - * The unique identifier for the user. - */ + /** The unique identifier for the user. */ readonly id: string, - /** - * A boolean indicating whether the user has a password on their account. - */ + /** Whether the user has a password on their account. */ readonly passwordEnabled: boolean, - /** - * A boolean indicating whether the user has enabled TOTP by generating a TOTP secret and verifying it via an authenticator app. - */ + /** Whether the user has enabled TOTP by generating a TOTP secret and verifying it via an authenticator app. */ readonly totpEnabled: boolean, - /** - * A boolean indicating whether the user has enabled Backup codes. - */ + /** Whether the user has enabled Backup codes. */ readonly backupCodeEnabled: boolean, - /** - * A boolean indicating whether the user has enabled two-factor authentication. - */ + /** Whether the user has enabled two-factor authentication. */ readonly twoFactorEnabled: boolean, - /** - * A boolean indicating whether the user is banned or not. - */ + /** Whether the user is banned or not. */ readonly banned: boolean, - /** - * A boolean indicating whether the user is banned or not. - */ + /** Whether the user is [locked](https://clerk.com/docs/guides/secure/user-lockout) or not. */ readonly locked: boolean, - /** - * The date when the user was first created. - */ + /** The Unix timestamp when the user was first created. */ readonly createdAt: number, - /** - * The date when the user was last updated. - */ + /** The Unix timestamp when the user was last updated. */ readonly updatedAt: number, - /** - * The URL of the user's profile image. - */ + /** The URL of the user's profile image. */ readonly imageUrl: string, - /** - * A getter boolean to check if the user has uploaded an image or one was copied from OAuth. Returns `false` if Clerk is displaying an avatar for the user. - */ + /** Whether the user has uploaded an image or one was copied from OAuth. Returns `false` if Clerk is displaying an avatar for the user. */ readonly hasImage: boolean, - /** - * The ID for the `EmailAddress` that the user has set as primary. - */ + /** The ID for the `EmailAddress` that the user has set as primary. */ readonly primaryEmailAddressId: string | null, - /** - * The ID for the `PhoneNumber` that the user has set as primary. - */ + /** The ID for the `PhoneNumber` that the user has set as primary. */ readonly primaryPhoneNumberId: string | null, - /** - * The ID for the [`Web3Wallet`](https://clerk.com/docs/reference/backend/types/backend-web3-wallet) that the user signed up with. - */ + /** The ID for the [`Web3Wallet`](https://clerk.com/docs/reference/backend/types/backend-web3-wallet) that the user signed up with. */ readonly primaryWeb3WalletId: string | null, - /** - * The date when the user last signed in. May be empty if the user has never signed in. - */ + /** The Unix timestamp when the user last signed in. May be empty if the user has never signed in. */ readonly lastSignInAt: number | null, - /** - * The ID of the user as used in your external systems. Must be unique across your instance. - */ + /** The ID of the user as used in your external systems. Must be unique across your instance. */ readonly externalId: string | null, - /** - * The user's username. - */ + /** The user's username. */ readonly username: string | null, - /** - * The user's first name. - */ + /** The user's first name. */ readonly firstName: string | null, - /** - * The user's last name. - */ + /** The user's last name. */ readonly lastName: string | null, - /** - * Metadata that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. - */ + /** Metadata that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. */ readonly publicMetadata: UserPublicMetadata = {}, - /** - * Metadata that can be read and set only from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}. - */ + /** Metadata that can be read and set only from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}. */ readonly privateMetadata: UserPrivateMetadata = {}, - /** - * Metadata that can be read and set from the Frontend API. It's considered unsafe because it can be modified from the frontend. - */ + /** Metadata that can be read and set from the Frontend API. It's considered unsafe because it can be modified from the frontend. */ readonly unsafeMetadata: UserUnsafeMetadata = {}, - /** - * An array of all the `EmailAddress` objects associated with the user. Includes the primary. - */ + /** An array of all the `EmailAddress` objects associated with the user. Includes the primary. */ readonly emailAddresses: EmailAddress[] = [], - /** - * An array of all the `PhoneNumber` objects associated with the user. Includes the primary. - */ + /** An array of all the `PhoneNumber` objects associated with the user. Includes the primary. */ readonly phoneNumbers: PhoneNumber[] = [], - /** - * An array of all the `Web3Wallet` objects associated with the user. Includes the primary. - */ + /** An array of all the `Web3Wallet` objects associated with the user. Includes the primary. */ readonly web3Wallets: Web3Wallet[] = [], - /** - * An array of all the `ExternalAccount` objects associated with the user via OAuth. **Note**: This includes both verified & unverified external accounts. - */ + /** An array of all the `ExternalAccount` objects associated with the user via OAuth. **Note**: This includes both verified & unverified external accounts. */ readonly externalAccounts: ExternalAccount[] = [], - /** - * An array of all the `EnterpriseAccount` objects associated with the user via enterprise SSO. - */ + /** An array of all the `EnterpriseAccount` objects associated with the user via enterprise SSO. */ readonly enterpriseAccounts: EnterpriseAccount[] = [], - /** - * Date when the user was last active. - */ + /** The Unix timestamp when the user was last active. */ readonly lastActiveAt: number | null, - /** - * A boolean indicating whether the Organization creation is enabled for the user or not. - */ + /** Whether the Organization creation is enabled for the user or not. */ readonly createOrganizationEnabled: boolean, - /** - * An integer indicating the number of Organizations that can be created by the user. If the value is `0`, then the user can create unlimited Organizations. Default is `null`. - */ + /** The number of Organizations that can be created by the user. If the value is `0`, then the user can create unlimited Organizations. Default is `null`. */ readonly createOrganizationsLimit: number | null = null, - /** - * A boolean indicating whether the user can delete their own account. - */ + /** Whether the user can delete their own account. */ readonly deleteSelfEnabled: boolean, - /** - * The unix timestamp of when the user accepted the legal requirements. `null` if [**Require express consent to legal documents**](https://clerk.com/docs/guides/secure/legal-compliance) is not enabled. - */ + /** The Unix timestamp when the user accepted the legal requirements. `null` if [**Require express consent to legal documents**](https://clerk.com/docs/guides/secure/legal-compliance) is not enabled. */ readonly legalAcceptedAt: number | null, - /** - * The locale of the user in BCP-47 format. - */ + /** The locale of the user in BCP-47 format. */ readonly locale: string | null, ) {} diff --git a/packages/backend/src/api/resources/Verification.ts b/packages/backend/src/api/resources/Verification.ts index 4da2489071e..7d5782d5f01 100644 --- a/packages/backend/src/api/resources/Verification.ts +++ b/packages/backend/src/api/resources/Verification.ts @@ -19,29 +19,17 @@ export class Verification { *
*/ readonly status: VerificationStatus, - /** - * The strategy pertaining to the parent sign-up or sign-in attempt. - */ + /** The strategy pertaining to the parent sign-up or sign-in attempt. */ readonly strategy: string, - /** - * The redirect URL for an external verification. - */ + /** The redirect URL for an external verification. */ readonly externalVerificationRedirectURL: URL | null = null, - /** - * The number of attempts related to the verification. - */ + /** The number of attempts related to the verification. */ readonly attempts: number | null = null, - /** - * The time the verification will expire at. - */ + /** The Unix timestamp when the verification will expire. */ readonly expireAt: number | null = null, - /** - * The [nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce) pertaining to the verification. - */ + /** The [nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce) pertaining to the verification. */ readonly nonce: string | null = null, - /** - * The message that will be presented to the user's Web3 wallet for signing during authentication. This follows the [Sign-In with Ethereum (SIWE) protocol format](https://docs.login.xyz/general-information/siwe-overview/eip-4361#example-message-to-be-signed), which typically includes details like the requesting service, wallet address, terms acceptance, nonce, timestamp, and any additional resources. - */ + /** The message that will be presented to the user's Web3 wallet for signing during authentication. This follows the [Sign-In with Ethereum (SIWE) protocol format](https://docs.login.xyz/general-information/siwe-overview/eip-4361#example-message-to-be-signed), which typically includes details like the requesting service, wallet address, terms acceptance, nonce, timestamp, and any additional resources. */ readonly message: string | null = null, ) {} @@ -57,11 +45,16 @@ export class Verification { } } +/** @inline */ export class OrganizationDomainVerification { constructor( + /** The current status of the verification. */ readonly status: string, + /** The strategy used to verify the domain. */ readonly strategy: string, + /** The number of verification attempts that have been made. */ readonly attempts: number | null = null, + /** The Unix timestamp when the current verification attempt expires. */ readonly expireAt: number | null = null, ) {} diff --git a/packages/backend/src/api/resources/WaitlistEntry.ts b/packages/backend/src/api/resources/WaitlistEntry.ts index e3b3557b38e..963f8d02400 100644 --- a/packages/backend/src/api/resources/WaitlistEntry.ts +++ b/packages/backend/src/api/resources/WaitlistEntry.ts @@ -3,37 +3,23 @@ import { Invitation } from './Invitation'; import type { WaitlistEntryJSON } from './JSON'; /** - * The Backend `WaitlistEntry` object holds information about a waitlist entry for a given email address. + * The Backend `WaitlistEntry` object holds information about a [waitlist entry](https://clerk.com/docs/guides/secure/restricting-access#waitlist). */ export class WaitlistEntry { constructor( - /** - * The unique identifier for this waitlist entry. - */ + /** The unique identifier for the waitlist entry. */ readonly id: string, - /** - * The email address to add to the waitlist. - */ + /** The email address to add to the waitlist. */ readonly emailAddress: string, - /** - * The status of the waitlist entry. - */ + /** The status of the waitlist entry. */ readonly status: WaitlistEntryStatus, - /** - * The invitation associated with this waitlist entry. - */ + /** The invitation associated with the waitlist entry. */ readonly invitation: Invitation | null, - /** - * The date when the waitlist entry was first created. - */ + /** The Unix timestamp when the waitlist entry was created. */ readonly createdAt: number, - /** - * The date when the waitlist entry was last updated. - */ + /** The Unix timestamp when the waitlist entry was last updated. */ readonly updatedAt: number, - /** - * Whether the waitlist entry is locked or not. - */ + /** Whether the waitlist entry is locked. */ readonly isLocked?: boolean, ) {} diff --git a/packages/backend/src/api/resources/Web3Wallet.ts b/packages/backend/src/api/resources/Web3Wallet.ts index 8811f623a2d..1052a80314d 100644 --- a/packages/backend/src/api/resources/Web3Wallet.ts +++ b/packages/backend/src/api/resources/Web3Wallet.ts @@ -8,17 +8,11 @@ import { Verification } from './Verification'; */ export class Web3Wallet { constructor( - /** - * The unique ID for the Web3 wallet. - */ + /** The unique ID for the Web3 wallet. */ readonly id: string, - /** - * The Web3 wallet address, made up of 0x + 40 hexadecimal characters. - */ + /** The Web3 wallet address, made up of 0x + 40 hexadecimal characters. */ readonly web3Wallet: string, - /** - * An object holding information on the verification of this Web3 wallet. - */ + /** An object holding information on the verification of this Web3 wallet. */ readonly verification: Verification | null, ) {} diff --git a/packages/backend/src/api/resources/index.ts b/packages/backend/src/api/resources/index.ts index e1359fe1c89..128882ba241 100644 --- a/packages/backend/src/api/resources/index.ts +++ b/packages/backend/src/api/resources/index.ts @@ -19,6 +19,7 @@ export type { OrganizationInvitationStatus, OrganizationMembershipRole, SignInStatus, + WaitlistEntryStatus, } from './Enums'; export type { SignUpStatus } from '@clerk/shared/types'; diff --git a/packages/backend/typedoc.json b/packages/backend/typedoc.json index 904b837abec..e93760481a6 100644 --- a/packages/backend/typedoc.json +++ b/packages/backend/typedoc.json @@ -8,6 +8,44 @@ "./src/tokens/types.ts", "./src/tokens/authObjects.ts", "./src/api/resources/index.ts", - "./src/api/resources/Deserializer.ts" + "./src/api/resources/Deserializer.ts", + "./src/api/endpoints/AbstractApi.ts", + "./src/api/endpoints/AccountlessApplicationsAPI.ts", + "./src/api/endpoints/ActorTokenApi.ts", + "./src/api/endpoints/AgentTaskApi.ts", + "./src/api/endpoints/AllowlistIdentifierApi.ts", + "./src/api/endpoints/APIKeysApi.ts", + "./src/api/endpoints/BetaFeaturesApi.ts", + "./src/api/endpoints/BillingApi.ts", + "./src/api/endpoints/BlocklistIdentifierApi.ts", + "./src/api/endpoints/ClientApi.ts", + "./src/api/endpoints/DomainApi.ts", + "./src/api/endpoints/EmailAddressApi.ts", + "./src/api/endpoints/EnterpriseConnectionApi.ts", + "./src/api/endpoints/IdPOAuthAccessTokenApi.ts", + "./src/api/endpoints/InstanceApi.ts", + "./src/api/endpoints/InvitationApi.ts", + "./src/api/endpoints/JwksApi.ts", + "./src/api/endpoints/JwtTemplatesApi.ts", + "./src/api/endpoints/M2MTokenApi.ts", + "./src/api/endpoints/MachineApi.ts", + "./src/api/endpoints/OAuthApplicationsApi.ts", + "./src/api/endpoints/OrganizationApi.ts", + "./src/api/endpoints/OrganizationPermissionApi.ts", + "./src/api/endpoints/OrganizationRoleApi.ts", + "./src/api/endpoints/PhoneNumberApi.ts", + "./src/api/endpoints/ProxyCheckApi.ts", + "./src/api/endpoints/RedirectUrlApi.ts", + "./src/api/endpoints/RoleSetApi.ts", + "./src/api/endpoints/SamlConnectionApi.ts", + "./src/api/endpoints/SessionApi.ts", + "./src/api/endpoints/SignInTokenApi.ts", + "./src/api/endpoints/SignUpApi.ts", + "./src/api/endpoints/TestingTokenApi.ts", + "./src/api/endpoints/UserApi.ts", + "./src/api/endpoints/WaitlistEntryApi.ts", + "./src/api/endpoints/WebhookApi.ts", + "./src/api/endpoints/index.ts", + "./src/api/endpoints/util-types.ts" ] } diff --git a/packages/shared/src/react/billing/payment-element.tsx b/packages/shared/src/react/billing/payment-element.tsx index 0a988347583..ea63015df5c 100644 --- a/packages/shared/src/react/billing/payment-element.tsx +++ b/packages/shared/src/react/billing/payment-element.tsx @@ -303,6 +303,7 @@ export type UsePaymentElementReturn = { * An object containing information about the initialized payment provider. It is `undefined` until `isProviderReady` is `true`. */ provider: { + /** The name of the payment provider. */ name: 'stripe'; }; /** diff --git a/packages/shared/src/types/billing.ts b/packages/shared/src/types/billing.ts index bffe04f0d0b..724fa60286f 100644 --- a/packages/shared/src/types/billing.ts +++ b/packages/shared/src/types/billing.ts @@ -7,6 +7,8 @@ import type { ForceNull, RemoveFunctions, Simplify } from './utils'; /** * Intersects `T` with an optional organization scope (`orgId`) for billing and related requests. + * + * @interface */ export type WithOptionalOrgType = T & { /** @@ -329,25 +331,15 @@ export interface BillingPlanUnitPrice { * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. */ export interface BillingPlanPrice { - /** - * The ID of the price - */ + /** The unique identifier of the price */ id: string; - /** - * The monthly price or `null` if the price is not monthly. - */ + /** The monthly price or `null` if the price is not monthly. */ fee: BillingMoneyAmount | null; - /** - * The effective monthly price when billed annually or `null` if the price is not annual. - */ + /** The effective monthly price when billed annually or `null` if the price is not annual. */ annualMonthlyFee: BillingMoneyAmount | null; - /** - * Whether this price is the default price for the plan it's associated with. - */ + /** Whether this price is the default price for the plan it's associated with. */ isDefault: boolean; - /** - * The individual unit prices applicable to this price. - */ + /** The individual unit prices applicable to this price. */ unitPrices?: BillingPlanUnitPrice[]; } @@ -357,17 +349,11 @@ export interface BillingPlanPrice { * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. */ export interface BillingPerUnitTotalTier { - /** - * The quantity billed within this tier. `null` means unlimited. - */ + /** The quantity billed within this tier. `null` means unlimited. */ quantity: number | null; - /** - * The fee charged per block for this tier. - */ + /** The fee charged per block for this tier. */ feePerBlock: BillingMoneyAmount; - /** - * The total billed amount for this tier. - */ + /** The total billed amount for this tier. */ total: BillingMoneyAmount; } @@ -377,17 +363,11 @@ export interface BillingPerUnitTotalTier { * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. */ export interface BillingPerUnitTotal { - /** - * The unit name, for example `seats`. - */ + /** The unit name, for example `seats`. */ name: string; - /** - * Number of units represented by one billable block. - */ + /** The number of units represented by one billable block. */ blockSize: number; - /** - * Detailed tier breakdown for this unit total. - */ + /** The tiers breakdown for this unit total. */ tiers: BillingPerUnitTotalTier[]; } @@ -397,25 +377,15 @@ export interface BillingPerUnitTotal { * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. */ export interface FeatureResource extends ClerkResource { - /** - * The unique identifier for the Feature. - */ + /** The unique identifier for the Feature. */ id: string; - /** - * The display name of the Feature. - */ + /** The display name of the Feature. */ name: string; - /** - * A short description of what the Feature provides, or `null` if not provided. - */ + /** A short description of what the Feature provides, or `null` if not provided. */ description: string | null; - /** - * A unique, URL-friendly identifier for the Feature. - */ + /** A unique, URL-friendly identifier for the Feature. */ slug: string; - /** - * The URL of the Feature's avatar image, or `null` if not set. - */ + /** The URL of the Feature's avatar image, or `null` if not set. */ avatarUrl: string | null; } diff --git a/packages/shared/src/types/clerk.ts b/packages/shared/src/types/clerk.ts index 3f0ce71e96b..a81d46bcd00 100644 --- a/packages/shared/src/types/clerk.ts +++ b/packages/shared/src/types/clerk.ts @@ -1434,19 +1434,11 @@ export type ClerkOptions = ClerkOptionsNavigation & telemetry?: | false | { - /** - * If `true`, telemetry will not be collected. - */ + /** Whether telemetry will be collected. */ disabled?: boolean; - /** - * If `true`, telemetry events are only logged to the console and not sent to Clerk - */ + /** Whether telemetry events are only logged to the console and not sent to Clerk. */ debug?: boolean; - /** - * If false, the sampling rates provided per telemetry event will be ignored and all events will be sent. - * - * @default true - */ + /** Whether the sampling rates provided per telemetry event will be ignored and all events will be sent. Defaults to `true`. */ perEventSampling?: boolean; }; diff --git a/packages/shared/src/types/organization.ts b/packages/shared/src/types/organization.ts index 07246cb78e3..53ec35142e1 100644 --- a/packages/shared/src/types/organization.ts +++ b/packages/shared/src/types/organization.ts @@ -27,18 +27,14 @@ import type { GetEnterpriseConnectionsParams } from './user'; declare global { /** - * If you want to provide custom types for the organization.publicMetadata object, - * simply redeclare this rule in the global namespace. - * Every Organization object will use the provided type. + * If you want to provide custom types for the `organization.publicMetadata` object, simply redeclare this rule in the global namespace. Every `Organization` object will use the provided type. */ interface OrganizationPublicMetadata { [k: string]: unknown; } /** - * If you want to provide custom types for the organization.privateMetadata object, - * simply redeclare this rule in the global namespace. - * Every Organization object will use the provided type. + * If you want to provide custom types for the `organization.privateMetadata` object, simply redeclare this rule in the global namespace. Every `Organization` object will use the provided type. */ interface OrganizationPrivateMetadata { [k: string]: unknown; @@ -195,7 +191,7 @@ export interface OrganizationResource extends ClerkResource, BillingPayerMethods */ prepareOwnershipVerification: (domainIds: string[]) => Promise; /** - * Completes the verification process started by [`prepareOwnershipVerification()`](https://clerk.com/docs/reference/types/organization-resource#prepare-ownership-verification), by resolving the published TXT record for each of the given domains in a single request. A single bad domain does not fail the batch; it lands in the returned [`OrganizationDomainsBulkOwnershipVerificationResource`](https://clerk.com/docs/reference/types/organization-domains-bulk-ownership-verification-resource) object's `errors` array. + * Completes the verification process started by [`prepareOwnershipVerification()`](https://clerk.com/docs/reference/objects/organization#prepare-ownership-verification), by resolving the published TXT record for each of the given domains in a single request. A single bad domain does not fail the batch; it lands in the returned [`OrganizationDomainsBulkOwnershipVerificationResource`](https://clerk.com/docs/reference/types/organization-domains-bulk-ownership-verification-resource) object's `errors` array. * @returns An [`OrganizationDomainsBulkOwnershipVerificationResource`](https://clerk.com/docs/reference/types/organization-domains-bulk-ownership-verification-resource) object. * @param domainIds - The unique identifiers of the domains to attempt. */ diff --git a/packages/shared/src/types/organizationDomain.ts b/packages/shared/src/types/organizationDomain.ts index 25e3b87a598..eeca290333e 100644 --- a/packages/shared/src/types/organizationDomain.ts +++ b/packages/shared/src/types/organizationDomain.ts @@ -1,9 +1,7 @@ import type { ClerkResource } from './resource'; /** - * The `OrganizationDomainVerification` object holds the affiliation verification details of an Organization's [Verified Domain](https://clerk.com/docs/guides/organizations/add-members/verified-domains). Affiliation proves that the current user controls an email address that belongs to the domain. - * - * This is the object referenced by both `affiliationVerification` and the deprecated `verification` property of the `OrganizationDomainResource` object. + * The `OrganizationDomainVerification` object holds the affiliation verification details of an Organization's [Verified Domain](/docs/guides/organizations/add-members/verified-domains). Affiliation proves that the current user controls an email address that belongs to the domain. */ export interface OrganizationDomainVerification { /** @@ -228,9 +226,7 @@ export type CreateOrganizationDomainParams = { enrollmentMode?: OrganizationEnrollmentMode; }; -/** - * The `OrganizationDomainBulkOwnershipVerificationError` object is a single [Verified Domain](https://clerk.com/docs/guides/organizations/add-members/verified-domains) that could not be processed during a bulk ownership verification flow. A failed domain is reported here instead of causing the entire batch to fail. - */ +/** @inline */ export interface OrganizationDomainBulkOwnershipVerificationError { /** * The unique identifier of the domain that could not be processed. @@ -243,11 +239,11 @@ export interface OrganizationDomainBulkOwnershipVerificationError { } /** - * The `OrganizationDomainsBulkOwnershipVerificationResource` object is the result of a bulk ownership verification flow, such as [`prepareOwnershipVerification()`](https://clerk.com/docs/reference/types/organization-resource#prepare-ownership-verification) or [`attemptOwnershipVerification()`](https://clerk.com/docs/reference/types/organization-resource#attempt-ownership-verification), where ownership is verified for several of an Organization's [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains) at once. Because the operation can partially succeed, each requested domain is reported in either `data` or `errors`. + * The `OrganizationDomainsBulkOwnershipVerificationResource` object is the result of a bulk ownership verification flow, such as [`prepareOwnershipVerification()`](https://clerk.com/docs/reference/objects/organization#prepare-ownership-verification) or [`attemptOwnershipVerification()`](https://clerk.com/docs/reference/objects/organization#attempt-ownership-verification), where ownership is verified for several of an Organization's [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains) at once. Because the operation can partially succeed, each requested domain is reported in either `data` or `errors`. */ export interface OrganizationDomainsBulkOwnershipVerificationResource { /** - * The domains that were processed successfully. After [`prepareOwnershipVerification()`](https://clerk.com/docs/reference/types/organization-resource#prepare-ownership-verification), each domain's `ownershipVerification` carries the `txtRecordName` and `txtRecordValue` that must be published to a DNS TXT record. + * The domains that were processed successfully. After [`prepareOwnershipVerification()`](https://clerk.com/docs/reference/objects/organization#prepare-ownership-verification), each domain's `ownershipVerification` carries the `txtRecordName` and `txtRecordValue` that must be published to a DNS TXT record. */ data: OrganizationDomainResource[]; /** diff --git a/packages/shared/src/types/pagination.ts b/packages/shared/src/types/pagination.ts index b47d585d9ae..eb955ba836d 100644 --- a/packages/shared/src/types/pagination.ts +++ b/packages/shared/src/types/pagination.ts @@ -2,14 +2,15 @@ * Pagination params in request * * @interface + * @expandProperties */ export type ClerkPaginationRequest = { /** - * Maximum number of items returned per request. + * Maximum number of items returned per request. Must be an integer greater than zero and less than `501`. Can be used for paginating the results together with offset. Defaults to `10`. */ limit?: number; /** - * This is the starting point for your fetched results. + * Skip the first `offset` items when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`. Defaults to `0`. */ offset?: number; } & T; @@ -33,6 +34,7 @@ export interface ClerkPaginatedResponse { /** * @interface + * @expandProperties */ export type ClerkPaginationParams = { /** diff --git a/typedoc.config.mjs b/typedoc.config.mjs index 77a8e44470d..0f3353cb398 100644 --- a/typedoc.config.mjs +++ b/typedoc.config.mjs @@ -122,6 +122,11 @@ const config = { '@standalonePage', /** Self-documenting placeholder for declarations intentionally left without a description. */ '@generateWithEmptyComment', + /** + * On a generic wrapper type (e.g. `ClerkPaginationRequest`), opts every alias of the form `Foo<{...}>` into a single merged properties table that includes the wrapper's own properties. Without this, typedoc-plugin-markdown renders such aliases as empty pages because the resolved type is a ReferenceType with no inline declaration. + * Handled by `.typedoc/custom-plugin.mjs`. + */ + '@expandProperties', ], /** * Keep `@inline` / `@inlineType` / `@standalonePage` in the model so the custom router and theme can read them.