Merge branch 'main' into jacek/fix-core3-oauth-retry

Author: jacekradko

.changeset/dry-mice-begin.md

@@ -0,0 +1,6 @@
+---
+"@clerk/backend": patch
+"@clerk/shared": patch
+---
+
+Fix OAuth consent component and hook related types.

.typedoc/custom-plugin.mjs

@@ -36,6 +36,8 @@ const FILES_WITHOUT_HEADINGS = [
   'payment-element-props.mdx',
   'use-organization-creation-defaults-return.mdx',
   'use-organization-creation-defaults-params.mdx',
+  'use-o-auth-consent-params.mdx',
+  'use-o-auth-consent-return.mdx',
 ];
 
 /**
@@ -66,6 +68,8 @@ const LINK_REPLACEMENTS = [
   ['organization-domain-resource', '/docs/reference/types/organization-domain-resource'],
   ['organization-invitation-resource', '/docs/reference/types/organization-invitation'],
   ['organization-membership-request-resource', '/docs/reference/types/organization-membership-request'],
+  ['o-auth-consent-info', '/docs/reference/types/oauth-consent-info'],
+  ['o-auth-consent-scope', '/docs/reference/types/oauth-consent-scope'],
   ['session', '/docs/reference/backend/types/backend-session'],
   ['session-activity', '/docs/reference/backend/types/backend-session-activity'],
   ['organization', '/docs/reference/backend/types/backend-organization'],
@@ -76,6 +80,9 @@ const LINK_REPLACEMENTS = [
   ['email-address', '/docs/reference/backend/types/backend-email-address'],
   ['enterprise-account', '/docs/reference/backend/types/backend-enterprise-account'],
   ['enterprise-account-connection', '/docs/reference/backend/types/backend-enterprise-account-connection'],
+  ['enterprise-connection', '/docs/reference/backend/types/backend-enterprise-connection'],
+  ['enterprise-connection-oauth-config', '/docs/reference/backend/types/backend-enterprise-connection-oauth-config'],
+  ['enterprise-connection-saml-connection', '/docs/reference/backend/types/backend-enterprise-connection-saml-connection'],
   ['external-account', '/docs/reference/backend/types/backend-external-account'],
   ['phone-number', '/docs/reference/backend/types/backend-phone-number'],
   ['saml-account', '/docs/reference/backend/types/backend-saml-account'],
@@ -101,6 +108,7 @@ const LINK_REPLACEMENTS = [
   ['billing-statement-resource', '/docs/reference/types/billing-statement-resource'],
   ['billing-subscription-resource', '/docs/reference/types/billing-subscription-resource'],
   ['clerk-api-response-error', '/docs/reference/types/clerk-api-response-error'],
+  ['clerk-api-error', '/docs/reference/types/clerk-api-error'],
   ['billing-statement-totals', '/docs/reference/types/billing-statement-totals'],
   ['billing-payment-resource', '/docs/reference/types/billing-payment-resource'],
   ['deleted-object-resource', '/docs/reference/types/deleted-object-resource'],
@@ -134,6 +142,10 @@ function getRelativeLinkReplacements() {
 
 function getCatchAllReplacements() {
   return [
+    {
+      pattern: /(?<![`[\]])\bClerkAPIResponseError\b(?![\]\(])/g,
+      replace: '[ClerkAPIResponseError](/docs/reference/types/clerk-api-response-error)',
+    },
     {
       pattern: /(?<![\[\w`])`Appearance`\\<`Theme`\\>/g,
       replace: '[`Appearance<Theme>`](/docs/guides/customizing-clerk/appearance-prop/overview)',

packages/backend/src/api/resources/EnterpriseAccount.ts

@@ -2,7 +2,7 @@ import type { EnterpriseAccountConnectionJSON, EnterpriseAccountJSON } from './J
 import { Verification } from './Verification';
 
 /**
- * Represents an enterprise SSO connection associated with an enterprise account.
+ * The Backend `EnterpriseAccountConnection` object represents an enterprise SSO connection associated with an enterprise account.
  */
 export class EnterpriseAccountConnection {
   constructor(

packages/backend/src/api/resources/EnterpriseConnection.ts

@@ -4,6 +4,9 @@ import type {
   EnterpriseConnectionSamlConnectionJSON,
 } from './JSON';
 
+/**
+ * The Backend `EnterpriseConnectionSamlConnection` object holds information about a SAML enterprise connection for an instance or organization.
+ */
 export class EnterpriseConnectionSamlConnection {
   constructor(
     /**

packages/shared/src/react/hooks/useOAuthConsent.tsx

@@ -14,12 +14,6 @@ const HOOK_NAME = 'useOAuthConsent';
  * (`GET /me/oauth/consent/{oauthClientId}`). Ensure the user is authenticated before relying on this hook
  * (for example, redirect to sign-in on your custom consent route).
  *
- * The hook is a pure data fetcher: it takes an explicit `oauthClientId` and optional `scope` and
- * issues the fetch when both the user is signed in and `oauthClientId` is non-empty. The query is
- * disabled when `oauthClientId` is empty or omitted.
- *
- * @internal
- *
  * @example
  * ```tsx
  * import { useOAuthConsent } from '@clerk/react/internal'
@@ -30,7 +24,7 @@ const HOOK_NAME = 'useOAuthConsent';
  * })
  * ```
  */
-export function useOAuthConsent(params: UseOAuthConsentParams = {}): UseOAuthConsentReturn {
+export function useOAuthConsent(params: UseOAuthConsentParams): UseOAuthConsentReturn {
   useAssertWrappedByClerkProvider(HOOK_NAME);
 
   const { oauthClientId: oauthClientIdParam, scope, keepPreviousData = true, enabled = true } = params;

packages/shared/src/react/hooks/useOAuthConsent.types.ts

@@ -2,16 +2,9 @@ import type { ClerkAPIResponseError } from '../../errors/clerkApiResponseError';
 import type { GetOAuthConsentInfoParams, OAuthConsentInfo } from '../../types';
 
 /**
- * Options for {@link useOAuthConsent}.
- *
- * Pass `oauthClientId` and `scope` explicitly. The hook does not read from `window.location` or
- * any other ambient source. The hook is disabled when `oauthClientId` is empty or omitted.
- *
- * @internal
- *
  * @interface
  */
-export type UseOAuthConsentParams = Partial<Pick<GetOAuthConsentInfoParams, 'oauthClientId' | 'scope'>> & {
+export type UseOAuthConsentParams = Pick<GetOAuthConsentInfoParams, 'oauthClientId' | 'scope'> & {
   /**
    * If `true`, the previous data will be kept in the cache until new data is fetched.
    *
@@ -27,14 +20,11 @@ export type UseOAuthConsentParams = Partial<Pick<GetOAuthConsentInfoParams, 'oau
 };
 
 /**
- * @internal
- *
  * @interface
  */
 export type UseOAuthConsentReturn = {
   /**
-   * OAuth consent screen metadata from Clerk, or `undefined` before the first successful fetch.
-   * Additional fields (e.g. submission helpers) may be added in the future without renaming this hook.
+   * The OAuth consent screen metadata returned by Clerk, or `undefined` before the first successful fetch.
    */
   data: OAuthConsentInfo | undefined;
   /**

packages/shared/src/types/oauthApplication.ts

@@ -24,30 +24,60 @@ export interface OAuthConsentInfoJSON extends ClerkResourceJSON {
 
 /**
  * A single OAuth scope with its description and whether it requires consent.
+ *
+ * @interface
  */
 export type OAuthConsentScope = {
+  /**
+   * The name of the scope, as defined by the OAuth application.
+   */
   scope: string;
+  /**
+   * The description of the scope, which can be shown to users on the consent screen. This may be `null` if no description is available.
+   */
   description: string | null;
+  /**
+   * Whether or not this scope requires explicit user consent. If `false`, the scope is considered "safe" and can be granted without showing the consent screen to the user.
+   */
   requiresConsent: boolean;
 };
 
 /**
- * OAuth consent screen metadata from `GET /v1/me/oauth/consent/{oauthClientId}`.
- * Includes information needed to populate the consent dialog.
+ * An interface representing OAuth consent information, including application details and requested scopes.
+ *
+ * @interface
  */
 export type OAuthConsentInfo = {
+  /**
+   * The display name of the OAuth application requesting access.
+   */
   oauthApplicationName: string;
+  /**
+   * The URL of the OAuth application's logo image.
+   */
   oauthApplicationLogoUrl: string;
+  /**
+   * The homepage URL of the OAuth application.
+   */
   oauthApplicationUrl: string;
+  /**
+   * The OAuth `client_id` identifying the application.
+   */
   clientId: string;
+  /**
+   * The `state` parameter from the original authorize request.
+   */
   state: string;
+  /**
+   * A list of scopes the application is requesting, with descriptions and consent requirements.
+   */
   scopes: OAuthConsentScope[];
 };
 
 export type GetOAuthConsentInfoParams = {
-  /** OAuth `client_id` from the authorize request. */
+  /** The OAuth `client_id` from the authorize request. The hook is disabled when this value is empty or omitted. */
   oauthClientId: string;
-  /** Optional space-delimited scope string from the authorize request. */
+  /** A space-delimited scope string from the authorize request. */
   scope?: string;
 };