diff --git a/backend/auth-object.mdx b/backend/auth-object.mdx index eb50849..075bfb6 100644 --- a/backend/auth-object.mdx +++ b/backend/auth-object.mdx @@ -1,8 +1,8 @@ ## Properties -| Property | Type | Description | -| ---------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `debug` | () => \{ [key: string]: any; \} | Used to help debug issues when using Clerk in development. | -| `getToken` | ServerGetToken \| () => Promise\ \| () => Promise\ | A function that gets the current user's [session token](/docs/backend-requests/resources/session-tokens) or a [custom JWT template](/docs/backend-requests/jwt-templates). | -| `has` | [`CheckAuthorizationFromSessionClaims`](../types/check-authorization-from-session-claims.mdx) | A function that checks if the user has an organization role or custom permission. | -| `tokenType` | "session_token" \| "api_key" \| "machine_token" \| "oauth_token" | The allowed token type. | +| Property | Type | Description | +| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `debug` | () => \{ [key: string]: any; \} | Used to help debug issues when using Clerk in development. | +| `getToken` | () => Promise\ \| () => Promise\ \| [ServerGetToken](../types/server-get-token.mdx) \| () => Promise\ | A function that gets the current user's [session token](/docs/backend-requests/resources/session-tokens) or a [custom JWT template](/docs/backend-requests/jwt-templates). | +| `has` | [CheckAuthorizationFromSessionClaims](../types/check-authorization-from-session-claims.mdx) \| () => false | A function that checks if the user has an organization role or custom permission. | +| `tokenType` | null \| "api_key" \| "session_token" \| "machine_token" \| "oauth_token" | The allowed token type. | diff --git a/backend/get-auth-fn.mdx b/backend/get-auth-fn.mdx new file mode 100644 index 0000000..2884596 --- /dev/null +++ b/backend/get-auth-fn.mdx @@ -0,0 +1,101 @@ +Shared generic overload type for getAuth() helpers across SDKs. + +- Parameterized by the request type (RequestType). +- Handles different accepted token types and their corresponding return types. + +## Call Signature + +Shared generic overload type for getAuth() helpers across SDKs. + +- Parameterized by the request type (RequestType). +- Handles different accepted token types and their corresponding return types. + +### Parameters + +| Parameter | Type | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `req` | `RequestType` | +| `options` | \{ treatPendingAsSignedOut?: boolean; \} & \{ acceptsToken?: "api_key" \| "session_token" \| "machine_token" \| "oauth_token" \| ("api_key" \| "session_token" \| "machine_token" \| "oauth_token")[] \| "any"; \} & \{ acceptsToken: T; \} | + +### Returns + +`MaybePromise`\<InvalidTokenAuthObject \| [InferAuthObjectFromTokenArray](infer-auth-object-from-token-array.mdx)\\>\>, `ReturnsPromise`\> + +### Example + +```ts +const auth = await getAuth(req, { acceptsToken: ["session_token", "api_key"] }); +``` + +## Call Signature + +Shared generic overload type for getAuth() helpers across SDKs. + +- Parameterized by the request type (RequestType). +- Handles different accepted token types and their corresponding return types. + +### Parameters + +| Parameter | Type | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `req` | `RequestType` | +| `options` | \{ treatPendingAsSignedOut?: boolean; \} & \{ acceptsToken?: "api_key" \| "session_token" \| "machine_token" \| "oauth_token" \| ("api_key" \| "session_token" \| "machine_token" \| "oauth_token")[] \| "any"; \} & \{ acceptsToken: T; \} | + +### Returns + +`MaybePromise`\<[`InferAuthObjectFromToken`](infer-auth-object-from-token.mdx)\<`T`, `SessionAuthObject`, `MachineAuthObject`\<`Exclude`\<`T`, `"session_token"`\>\>\>, `ReturnsPromise`\> + +### Example + +```ts +const auth = await getAuth(req, { acceptsToken: "session_token" }); +``` + +## Call Signature + +Shared generic overload type for getAuth() helpers across SDKs. + +- Parameterized by the request type (RequestType). +- Handles different accepted token types and their corresponding return types. + +### Parameters + +| Parameter | Type | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `req` | `RequestType` | +| `options` | \{ treatPendingAsSignedOut?: boolean; \} & \{ acceptsToken?: "api_key" \| "session_token" \| "machine_token" \| "oauth_token" \| ("api_key" \| "session_token" \| "machine_token" \| "oauth_token")[] \| "any"; \} & \{ acceptsToken: "any"; \} | + +### Returns + +`MaybePromise`\<[`AuthObject`](auth-object.mdx), `ReturnsPromise`\> + +### Example + +```ts +const auth = await getAuth(req, { acceptsToken: "any" }); +``` + +## Call Signature + +Shared generic overload type for getAuth() helpers across SDKs. + +- Parameterized by the request type (RequestType). +- Handles different accepted token types and their corresponding return types. + +### Parameters + +| Parameter | Type | Description | +| ---------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| `req` | `RequestType` | - | +| `options?` | \{ treatPendingAsSignedOut?: boolean; \} | - | +| `options.treatPendingAsSignedOut?` | `boolean` | A boolean that indicates whether pending sessions are considered as signed out or not. Defaults to `true`. | + +### Returns + +`MaybePromise`\<`SessionAuthObject`, `ReturnsPromise`\> + +### Example + +```ts +const auth = await getAuth(req); +``` diff --git a/backend/infer-auth-object-from-token-array.mdx b/backend/infer-auth-object-from-token-array.mdx new file mode 100644 index 0000000..a7421ad --- /dev/null +++ b/backend/infer-auth-object-from-token-array.mdx @@ -0,0 +1,5 @@ +Infers auth object type from an array of token types. + +- Session token only -> SessionType +- Mixed tokens -> SessionType | MachineType +- Machine tokens only -> MachineType diff --git a/backend/infer-auth-object-from-token.mdx b/backend/infer-auth-object-from-token.mdx new file mode 100644 index 0000000..09a78f3 --- /dev/null +++ b/backend/infer-auth-object-from-token.mdx @@ -0,0 +1,2 @@ +Infers auth object type from a single token type. +Returns SessionType for session tokens, or MachineType for machine tokens. diff --git a/backend/user.mdx b/backend/user.mdx index 17bd7ba..85d4eaf 100644 --- a/backend/user.mdx +++ b/backend/user.mdx @@ -36,3 +36,67 @@ The Backend `User` object is similar to the `User` object as it holds informatio | `updatedAt` | `number` | The date when the user was last updated. | | `username` | null \| string | The user's username. | | `web3Wallets` | [Web3Wallet](/docs/references/backend/types/backend-web3-wallet)[] | An array of all the `Web3Wallet` objects associated with the user. Includes the primary. | + +## Accessors + +### fullName + +#### Get Signature + +```ts +get fullName(): null | string +``` + +The full name of the user. + +##### Returns + +null \| string + +--- + +### primaryEmailAddress + +#### Get Signature + +```ts +get primaryEmailAddress(): null | EmailAddress +``` + +The primary email address of the user. + +##### Returns + +null \| [EmailAddress](/docs/references/backend/types/backend-email-address) + +--- + +### primaryPhoneNumber + +#### Get Signature + +```ts +get primaryPhoneNumber(): null | PhoneNumber +``` + +The primary phone number of the user. + +##### Returns + +null \| [PhoneNumber](/docs/references/backend/types/backend-phone-number) + +--- + +### primaryWeb3Wallet + +#### Get Signature + +```ts +get primaryWeb3Wallet(): null | Web3Wallet +``` + +The primary web3 wallet of the user. + +##### Returns + +null \| [Web3Wallet](/docs/references/backend/types/backend-web3-wallet) diff --git a/backend/verification.mdx b/backend/verification.mdx index a28f719..0abc533 100644 --- a/backend/verification.mdx +++ b/backend/verification.mdx @@ -9,5 +9,5 @@ The Backend `Verification` object describes the state of the verification proces | `externalVerificationRedirectURL` | null \| URL | The redirect URL for an external verification. | | `message` | null \| string | 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. | | `nonce` | null \| string | The [nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce) pertaining to the verification. | -| `status` | `string` | The state of the verification. | +| `status` | `VerificationStatus` | The state of the verification. | | `strategy` | `string` | The strategy pertaining to the parent sign-up or sign-in attempt. | diff --git a/clerk-react/api-keys.mdx b/clerk-react/api-keys.mdx new file mode 100644 index 0000000..4147bc5 --- /dev/null +++ b/clerk-react/api-keys.mdx @@ -0,0 +1,19 @@ +**`Experimental`** + +This component is in early access and may change in future releases. + +## Type declaration + +## Parameters + +| Parameter | Type | +| --------- | --------------------------------------------------- | +| `props` | [`Without`](../types/without.mdx)\<`P`, `"clerk"`\> | + +## Returns + +null \| Element + +| Name | Type | +| -------------------------------------- | -------- | +| `displayName` | `string` | diff --git a/clerk-react/clerk-provider-props.mdx b/clerk-react/clerk-provider-props.mdx index 9c9f330..c6e0beb 100644 --- a/clerk-react/clerk-provider-props.mdx +++ b/clerk-react/clerk-provider-props.mdx @@ -16,7 +16,7 @@ | `experimental?` | `Autocomplete`\<\{ commerce: boolean; persistClient: boolean; rethrowOfflineNetworkErrors: boolean; \}, `Record`\<`string`, `any`\>\> | Enable experimental flags to gain access to new features. These flags are not guaranteed to be stable and may change drastically in between patch or minor versions. | | `initialState?` | `Serializable`\<\{ actor: undefined \| \{ [x: string]: unknown; sub: string; \}; factorVerificationAge: \[number, number\]; organization: undefined \| [OrganizationResource](/docs/references/javascript/organization); orgId: undefined \| string; orgPermissions: undefined \| string[]; orgRole: undefined \| string; orgSlug: undefined \| string; session: undefined \| [SessionResource](/docs/references/javascript/session); sessionClaims: JwtPayload; sessionId: undefined \| string; sessionStatus: [SessionStatusClaim](/docs/references/javascript/types/session-status); user: undefined \| [UserResource](/docs/references/javascript/user); userId: undefined \| string; \}\> | Provide an initial state of the Clerk client during server-side rendering. You don't need to set this value yourself unless you're [developing an SDK](/docs/references/sdk/overview). | | `isSatellite?` | boolean \| (url) => boolean | A boolean that indicates whether the application is a satellite application. | -| `localization?` | `DeepPartial`\<[Localization](/docs/customization/localization)\> | Optional object to localize your components. Will only affect [Clerk Components](/docs/components/overview) and not [Account Portal](/docs/account-portal/overview) pages. | +| `localization?` | `DeepPartial`\<`DeepLocalizationWithoutObjects`\<`__internal_LocalizationResource`\>\> | Optional object to localize your components. Will only affect [Clerk Components](/docs/components/overview) and not [Account Portal](/docs/account-portal/overview) pages. | | `newSubscriptionRedirectUrl?` | null \| string | The URL to navigate to after the user completes the checkout and clicks the "Continue" button. | | `nonce?` | `string` | This nonce value will be passed through to the `@clerk/clerk-js` script tag. Use it to implement a [strict-dynamic CSP](/docs/security/clerk-csp#implementing-a-strict-dynamic-csp). Requires the `dynamic` prop to also be set. | | `proxyUrl?` | string \| (url) => string \| (url) => string | **Required for applications that run behind a reverse proxy**. The URL that Clerk will proxy requests to. Can be either a relative path (`/__clerk`) or a full URL (`https:///__clerk`). | diff --git a/shared/pages-or-infinite-options.mdx b/shared/pages-or-infinite-options.mdx index c2a7ab7..69ee82d 100644 --- a/shared/pages-or-infinite-options.mdx +++ b/shared/pages-or-infinite-options.mdx @@ -1,4 +1,5 @@ -| Property | Type | Description | -| --------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `initialPage?` | `number` | A number that specifies which page to fetch. For example, if `initialPage` is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to `1`. | -| `pageSize?` | `number` | A number that specifies the maximum number of results to return per page. Defaults to `10`. | +| Property | Type | Description | +| ------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `__experimental_mode?` | `"cache"` | **`Experimental`** On `cache` mode, no request will be triggered when the hook is mounted and the data will be fetched from the cache. Defaults to `undefined`. | +| `initialPage?` | `number` | A number that specifies which page to fetch. For example, if `initialPage` is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to `1`. | +| `pageSize?` | `number` | A number that specifies the maximum number of results to return per page. Defaults to `10`. | diff --git a/types/clerk-api-error.mdx b/types/clerk-api-error.mdx index 89c3d20..072e4b9 100644 --- a/types/clerk-api-error.mdx +++ b/types/clerk-api-error.mdx @@ -2,16 +2,22 @@ An interface that represents an error returned by the Clerk API. ## Properties -| Property | Type | Description | -| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| `code` | `string` | A string code that represents the error, such as `username_exists_code`. | -| `longMessage?` | `string` | A more detailed message that describes the error. | -| `message` | `string` | A message that describes the error. | -| `meta?` | \{ emailAddresses?: string[]; identifiers?: string[]; paramName?: string; permissions?: string[]; sessionId?: string; zxcvbn?: \{ suggestions: \{ code: string; message: string; \}[]; \}; \} | Additional information about the error. | -| `meta.emailAddresses?` | string[] | - | -| `meta.identifiers?` | string[] | - | -| `meta.paramName?` | `string` | - | -| `meta.permissions?` | string[] | - | -| `meta.sessionId?` | `string` | - | -| `meta.zxcvbn?` | \{ suggestions: \{ code: string; message: string; \}[]; \} | - | -| `meta.zxcvbn.suggestions` | \{ code: string; message: string; \}[] | - | +| Property | Type | Description | +| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| `code` | `string` | A string code that represents the error, such as `username_exists_code`. | +| `longMessage?` | `string` | A more detailed message that describes the error. | +| `message` | `string` | A message that describes the error. | +| `meta?` | \{ emailAddresses?: string[]; identifiers?: string[]; paramName?: string; permissions?: string[]; plan?: \{ amount_formatted: string; annual_monthly_amount_formatted: string; currency_symbol: string; id: string; name: string; \}; sessionId?: string; zxcvbn?: \{ suggestions: \{ code: string; message: string; \}[]; \}; \} | Additional information about the error. | +| `meta.emailAddresses?` | string[] | - | +| `meta.identifiers?` | string[] | - | +| `meta.paramName?` | `string` | - | +| `meta.permissions?` | string[] | - | +| `meta.plan?` | \{ amount_formatted: string; annual_monthly_amount_formatted: string; currency_symbol: string; id: string; name: string; \} | - | +| `meta.plan.amount_formatted` | `string` | - | +| `meta.plan.annual_monthly_amount_formatted` | `string` | - | +| `meta.plan.currency_symbol` | `string` | - | +| `meta.plan.id` | `string` | - | +| `meta.plan.name` | `string` | - | +| `meta.sessionId?` | `string` | - | +| `meta.zxcvbn?` | \{ suggestions: \{ code: string; message: string; \}[]; \} | - | +| `meta.zxcvbn.suggestions` | \{ code: string; message: string; \}[] | - | diff --git a/types/clerk.mdx b/types/clerk.mdx index d33c714..4288022 100644 --- a/types/clerk.mdx +++ b/types/clerk.mdx @@ -16,6 +16,7 @@ Main Clerk SDK object. | `__internal_setActiveInProgress` | `boolean` | Internal flag indicating whether a `setActive` call is in progress. Used to prevent navigations from being initiated outside of the Clerk class. | | `__internal_unmountOAuthConsent` | (targetNode) => void | Unmounts a OAuth consent component from the target element. | | `addListener` | (callback) => UnsubscribeCallback | Register a listener that triggers a callback each time important Clerk resources are changed. Allows to hook up at different steps in the sign up, sign in processes. Some important checkpoints: When there is an active session, user === session.user. When there is no active session, user and session will both be null. When a session is loading, user and session will be undefined. | +| `apiKeys` | `APIKeysNamespace` | **`Experimental`** API Keys Object This API is in early access and may change in future releases. | | `authenticateWithCoinbaseWallet` | (params?) => Promise\ | Authenticates user using their Coinbase Smart Wallet and browser extension | | `authenticateWithGoogleOneTap` | (params) => Promise\<[SignInResource](sign-in-resource.mdx) \| [SignUpResource](/docs/references/javascript/sign-up)\> | Authenticates user using a Google token generated from Google identity services. | | `authenticateWithMetamask` | (params?) => Promise\ | Authenticates user using their Metamask browser extension | @@ -42,6 +43,7 @@ Main Clerk SDK object. | `isSignedIn` | `boolean` | Indicates whether the current user has a valid signed-in client session | | `isStandardBrowser` | undefined \| boolean | Clerk flag for loading Clerk in a standard browser setup | | `loaded` | `boolean` | If true the bootstrapping of Clerk.load() has completed successfully. | +| `mountApiKeys` | (targetNode, props?) => void | **`Experimental`** This API is in early access and may change in future releases. Mount a api keys component at the target element. | | `mountCreateOrganization` | (targetNode, props?) => void | Mount a CreateOrganization component at the target element. | | `mountOrganizationList` | (targetNode, props?) => void | Mount an organization list component at the target element. | | `mountOrganizationProfile` | (targetNode, props?) => void | Mount an organization profile component at the target element. | @@ -77,6 +79,7 @@ Main Clerk SDK object. | `setActive` | ([setActiveParams](/docs/references/javascript/types/set-active-params)) => Promise\ | Set the active session and organization explicitly. If the session param is `null`, the active session is deleted. In a similar fashion, if the organization param is `null`, the current organization is removed as active. | | `signOut` | \{ (options?): Promise\; (signOutCallback?, options?): Promise\; \} | Signs out the current user on single-session instances, or all users on multi-session instances **Param** Optional A callback that runs after sign out completes. **Param** Optional Configuration options, see SignOutOptions | | `status` | "error" \| "loading" \| "ready" \| "degraded" | Describes the state the clerk singleton operates in: - `"error"`: Clerk failed to initialize. - `"loading"`: Clerk is still attempting to load. - `"ready"`: Clerk singleton is fully operational. - `"degraded"`: Clerk singleton is partially operational. | +| `unmountApiKeys` | (targetNode) => void | **`Experimental`** This API is in early access and may change in future releases. Unmount a api keys component from the target element. If there is no component mounted at the target node, results in a noop. | | `unmountCreateOrganization` | (targetNode) => void | Unmount the CreateOrganization component from the target node. | | `unmountOrganizationList` | (targetNode) => void | Unmount the organization list component from the target node.\* | | `unmountOrganizationProfile` | (targetNode) => void | Unmount the organization profile component from the target node. | diff --git a/types/protect-props.mdx b/types/protect-props.mdx new file mode 100644 index 0000000..caa5998 --- /dev/null +++ b/types/protect-props.mdx @@ -0,0 +1,22 @@ +Props for the `` component, which restricts access to its children based on authentication and authorization. + +Use `ProtectProps` to specify the required role, permission, feature, or plan for access. + +## Example + +```tsx +// Require a specific permission + + +// Require a specific role + + +// Use a custom condition callback + has({ permission: "a_permission_key" })} /> + +// Require a specific feature + + +// Require a specific plan + +``` diff --git a/types/server-get-token-options.mdx b/types/server-get-token-options.mdx new file mode 100644 index 0000000..a63b221 --- /dev/null +++ b/types/server-get-token-options.mdx @@ -0,0 +1,10 @@ +> **ServerGetTokenOptions** = \{ expiresInSeconds?: number; template?: string; \} + +Options for retrieving a session token. + +## Properties + +| Property | Type | Description | +| ------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `expiresInSeconds?` | `number` | The expiration time for the token in seconds. If provided, the token will expire after the specified number of seconds. Must be a positive integer. | +| `template?` | `string` | The name of a JWT template configured in the Clerk Dashboard. If provided, a JWT will be generated using the specified template. If not provided, the raw session token will be returned. | diff --git a/types/server-get-token.mdx b/types/server-get-token.mdx new file mode 100644 index 0000000..b0e14e5 --- /dev/null +++ b/types/server-get-token.mdx @@ -0,0 +1,11 @@ +A function that retrieves a session token or JWT template. + +## Parameters + +| Parameter | Type | Description | +| ---------- | ------------------------------------------------------- | ----------------------------------------- | +| `options?` | [`ServerGetTokenOptions`](server-get-token-options.mdx) | Configuration options for token retrieval | + +## Returns + +`Promise`\<string \| null\> — A promise that resolves to the token string, or null if no session exists