diff --git a/.changeset/thick-singers-pick.md b/.changeset/thick-singers-pick.md new file mode 100644 index 00000000000..a845151cc84 --- /dev/null +++ b/.changeset/thick-singers-pick.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/.typedoc/__tests__/__snapshots__/organization-resource-methods-create-domain.mdx b/.typedoc/__tests__/__snapshots__/organization-resource-methods-create-domain.mdx new file mode 100644 index 00000000000..8271dc358a2 --- /dev/null +++ b/.typedoc/__tests__/__snapshots__/organization-resource-methods-create-domain.mdx @@ -0,0 +1,21 @@ +### `createDomain()` + +Creates a new domain. + +Returns an [`OrganizationDomainResource`](/docs/reference/types/organization-domain-resource) object. + +> [!WARNING] +> You must have [**Verified domains**](/docs/guides/organizations/add-members/verified-domains) enabled in your app's settings in the Clerk Dashboard. + +```typescript +function createDomain(domainName: string, params?: Pick): Promise +``` + +#### Parameters + + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `domainName` | `string` | The name of the domain to create. | +| `params?` | `Pick`\<[`CreateOrganizationDomainParams`](#create-organization-domain-params), `"enrollmentMode"`\> | Optional parameters, including the `enrollmentMode` to assign to the new domain. | +| `params?.enrollmentMode?` | "manual_invitation" \| "automatic_invitation" \| "automatic_suggestion" \| "enterprise_sso" | The enrollment mode that determines how matching users are added to the Organization. Defaults to `manual_invitation`. | diff --git a/.typedoc/__tests__/extract-methods.test.ts b/.typedoc/__tests__/extract-methods.test.ts index d62f715d917..941021557c4 100644 --- a/.typedoc/__tests__/extract-methods.test.ts +++ b/.typedoc/__tests__/extract-methods.test.ts @@ -13,6 +13,7 @@ import { describe, expect, it } from 'vitest'; * - `methods/sign-out.mdx` – simple zero-arg callable * - `methods/handle-redirect-callback.mdx` – multi-param `parametersTable` with nested rows * - `methods/handle-email-link-verification.mdx` – required parent (`params`) flattened to `.` + * - `methods/create-domain.mdx` – `Pick` parameter flattened to only the selected property * - `methods/join-waitlist.mdx` – single nominal-param section (`JoinWaitlistParams`) * - `methods/create.mdx` (api-key) – another single-nominal-param case + warning callout * - `methods/check-authorization.mdx` – generic instantiation (`CheckAuthorization`) @@ -45,6 +46,11 @@ describe('extract-methods snapshots', () => { await expect(content).toMatchFileSnapshot('./__snapshots__/clerk-methods-handle-email-link-verification.mdx'); }); + it('Pick parameter includes only selected properties: organization.createDomain()', async () => { + const content = await readGenerated('shared/organization-resource/methods/create-domain.mdx'); + await expect(content).toMatchFileSnapshot('./__snapshots__/organization-resource-methods-create-domain.mdx'); + }); + it('single nominal-param section: clerk.joinWaitlist()', async () => { const content = await readGenerated('shared/clerk/methods/join-waitlist.mdx'); await expect(content).toMatchFileSnapshot('./__snapshots__/clerk-methods-join-waitlist.mdx'); diff --git a/.typedoc/custom-theme.mjs b/.typedoc/custom-theme.mjs index c2c0d1c79c3..d78e55136b4 100644 --- a/.typedoc/custom-theme.mjs +++ b/.typedoc/custom-theme.mjs @@ -446,7 +446,40 @@ function hasDefaultValuesForParameters(parameters) { } /** - * Object shape for a parameter: inline `{ … }`, optional-wrapped, or reference to a type alias / interface. + * Collects string literal members from a type used as `Pick`'s key argument. + * + * @param {import('typedoc').Type | undefined} t + * @returns {string[] | undefined} + */ +function getPickPropertyNames(t) { + const unwrapped = unwrapOptional(t); + if (!unwrapped || typeof unwrapped !== 'object') { + return undefined; + } + if (unwrapped.type === 'literal') { + const literal = /** @type {import('typedoc').LiteralType} */ (unwrapped); + if (typeof literal.value === 'string') { + return [literal.value]; + } + return undefined; + } + if (!isUnionTypeDoc(unwrapped)) { + return undefined; + } + const names = []; + const union = /** @type {import('typedoc').UnionType} */ (unwrapped); + for (const type of union.types) { + const nestedNames = getPickPropertyNames(type); + if (!nestedNames) { + return undefined; + } + names.push(...nestedNames); + } + return names; +} + +/** + * Object shape for a parameter: inline `{ … }`, optional-wrapped, reference to a type alias / interface, or `Pick` with literal keys. * * @param {import('typedoc').Type | undefined} t * @returns {import('typedoc').DeclarationReflection | undefined} @@ -470,6 +503,33 @@ function getParameterObjectShapeDeclaration(t) { } if (o.type === 'reference') { const ref = /** @type {import('typedoc').ReferenceType} */ (t); + if (ref.name === 'Pick' && ref.package === 'typescript' && ref.typeArguments?.length === 2) { + const [sourceType, keysType] = ref.typeArguments; + const propertyNames = getPickPropertyNames(keysType); + if (!propertyNames?.length) { + return undefined; + } + const sourceDecl = getParameterObjectShapeDeclaration(sourceType); + const sourceRef = sourceType.type === 'reference' ? sourceType.reflection : undefined; + const sourceWithChildren = + sourceDecl ?? + (sourceRef && 'children' in sourceRef + ? /** @type {import('typedoc').DeclarationReflection} */ (sourceRef) + : undefined); + if (!sourceWithChildren?.children?.length) { + return undefined; + } + const selected = new Set(propertyNames); + const children = sourceWithChildren.children.filter(child => selected.has(child.name)); + if (children.length !== selected.size) { + return undefined; + } + return /** @type {import('typedoc').DeclarationReflection} */ ({ + ...sourceWithChildren, + kind: ReflectionKind.TypeLiteral, + children, + }); + } const sym = ref.reflection; if (!sym) { return undefined;