src/services/suggestions-api/class-suggestions-api-service.php (1)

101-116: New get_check_auth method follows service class patterns.

The method implementation and documentation follow the established patterns of the service class. Consider adding a PHPStan import-type annotation for the options parameter to improve type safety, similar to other methods in this class.

 * @since 3.19.0
 *
+ * @phpstan-import-type Endpoint_Check_Auth_Options from Endpoints\Endpoint_Check_Auth
 * @param array<mixed> $options The options to pass to the API request.

src/js/admin-settings.ts (4)

1-14: Add @SInCE tags to imports section.

According to WordPress coding standards and the project guidelines, every JSDoc comment should include a @SInCE tag indicating the version when the code was added.

 /**
  * WordPress dependencies
+ *
+ * @since 3.19.0
  */
 import { __ } from '@wordpress/i18n';

 /**
  * Internal dependencies
+ *
+ * @since 3.19.0
  */
 import {
 	ContentHelperError,
 	ContentHelperErrorCode,
 } from '../content-helper/common/content-helper-error';
 import { CheckAuthProvider } from '../content-helper/common/providers/check-auth-provider';

---

253-267: Simplify concurrent API requests with more descriptive variable names.

The Promise.all implementation is correct, but the variable naming could be improved for better readability. Also, consider adding error handling specifically for network failures.

 	try {
 		const [ apiAuth, trafficBoostAuth ] = await Promise.all( [
 			CheckAuthProvider.getInstance().getAuthorizationResponse(
-				{ auth_scope: 'suggestions_api' }
+				{ auth_scope: 'suggestions_api' } // Main API authorization
 			),
 			CheckAuthProvider.getInstance().getAuthorizationResponse(
-				{ auth_scope: 'traffic_boost' }
+				{ auth_scope: 'traffic_boost' } // Traffic Boost feature authorization
 			),
 		] );

 		authResponse = {
-			api: apiAuth,
-			traffic_boost: trafficBoostAuth,
+			api: apiAuth, // Main Suggestions API authorization result
+			traffic_boost: trafficBoostAuth, // Traffic Boost feature authorization result
 		};

---

268-274: Add specific handling for network errors.

The error handling could be improved by adding specific cases for network errors, which would provide more helpful feedback to users.

 	} catch ( err: unknown ) {
 		console.error( err ); // eslint-disable-line no-console
 		if ( err instanceof ContentHelperError ) {
 			if ( ContentHelperErrorCode.PluginSettingsApiSecretNotSet === err.code ) {
 				message = __( '<p>All Content Helper AI functionality is disabled because An API Secret has not been set.</p>', 'wp-parsely' );
 			}
+		} else if (err instanceof Error) {
+			// Handle network errors or other unexpected issues
+			message = __( '<p>Unable to verify Content Helper authorization status due to a network error. Please refresh the page to try again.</p>', 'wp-parsely' );
 		}

---

271-271: Fix grammatical error in error message.

There's a grammatical error in the API Secret not set message - "because An API Secret" should be "because an API Secret".

-				message = __( '<p>All Content Helper AI functionality is disabled because An API Secret has not been set.</p>', 'wp-parsely' );
+				message = __( '<p>All Content Helper AI functionality is disabled because an API Secret has not been set.</p>', 'wp-parsely' );

src/rest-api/content-helper/class-endpoint-check-auth.php (2)

72-94: Verify route registration parameters.

The route registration parameters appear correct, but there's a potential improvement in documentation clarity.

The route comment on line 79-81 describes the endpoint's purpose, but it would be more explicit to include that this endpoint expects a POST request with a required 'auth_scope' parameter. Also, consider mentioning the expected values for 'auth_scope' in the parameter description.

-				'auth_scope' => array(
-					'description' => __( 'The scope for which to authorize.', 'wp-parsely' ),
-					'type'        => 'string',
-					'required'    => true,
-				),
+				'auth_scope' => array(
+					'description' => __( 'The scope for which to authorize (e.g., "suggestions_api" or "traffic_boost").', 'wp-parsely' ),
+					'type'        => 'string',
+					'required'    => true,
+				),

---

108-119: Ensure error handling is comprehensive.

Your error handling approach is correct by directly returning WP_Error objects from the service. However, consider adding more specific error handling for different scenarios.

Consider enhancing the error handling by checking for specific error codes or messages from the suggestions API service and augmenting them with more user-friendly explanations. This would help frontend developers better understand and communicate errors to users.

 	public function get_check_auth( WP_REST_Request $request ) {
 		$auth_scope = $request->get_param( 'auth_scope' );
 
 		$response = $this->suggestions_api->get_check_auth(
 			array( 'auth_scope' => $auth_scope )
 		);
 
 		if ( is_wp_error( $response ) ) {
+			// Add more context to common error scenarios
+			$error_code = $response->get_error_code();
+			if ( 'parsely_api_key_missing' === $error_code ) {
+				$response->add_data( array( 'status' => 400 ) );
+			} elseif ( 'parsely_api_request_failed' === $error_code ) {
+				$response->add_data( array( 'status' => 502 ) );
+			}
 			return $response;
 		}
 
 		return new WP_REST_Response( array( 'data' => $response ), 200 );
 	}

src/content-helper/common/providers/check-auth-provider.ts (1)

16-24: Correct JSDoc comment description.

There's an issue with the JSDoc comment description for AuthResponse.

The comment description for AuthResponse incorrectly states it's for "Authorization request parameters" when it should be describing an authorization response.

- * Type definition for the Authorization request parameters.
+ * Type definition for the Authorization response.

src/services/suggestions-api/endpoints/class-endpoint-check-auth.php (1)

93-103: Consider adding response validation.

The call method is a simple wrapper around get_check_auth_result, but it might benefit from additional validation of the input arguments.

Consider validating the auth_scope parameter to ensure it matches expected values:

 public function call( array $args = array() ) {
+	// Validate auth_scope if present
+	if ( isset( $args['auth_scope'] ) ) {
+		$valid_scopes = array( 'suggestions_api', 'traffic_boost' );
+		if ( ! in_array( $args['auth_scope'], $valid_scopes, true ) ) {
+			return new WP_Error(
+				'parsely_invalid_auth_scope',
+				sprintf(
+					/* translators: %s is the invalid scope value */
+					__( 'Invalid auth_scope value: %s. Expected one of: suggestions_api, traffic_boost.', 'wp-parsely' ),
+					$args['auth_scope']
+				)
+			);
+		}
+	}
+
 	return $this->get_check_auth_result( $args );
 }

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting

tests/Integration/RestAPI/ContentHelper/ContentHelperControllerTest.php (1)

77-97: Update PHPDoc with new @uses tag.

The PHPDoc for test_init_registers_endpoints should include @uses tags for the Endpoint_Check_Auth class methods since they're now being tested. This would maintain consistency with the existing documentation pattern.

 * @uses \Parsely\REST_API\Base_Endpoint::__construct
 * @uses \Parsely\REST_API\Base_Endpoint::init
+* @uses \Parsely\REST_API\Content_Helper\Endpoint_Check_Auth::__construct
+* @uses \Parsely\REST_API\Content_Helper\Endpoint_Check_Auth::get_endpoint_name
 * @uses \Parsely\REST_API\Content_Helper\Endpoint_Excerpt_Generator::__construct
 * @uses \Parsely\REST_API\Content_Helper\Endpoint_Excerpt_Generator::get_endpoint_name

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting

src/content-helper/common/providers/check-auth-provider.ts (1)

43-47: Using 'this' in static methods is flagged by linters.

Static analysis flagged using this in a static context, which can be confusing. However, as noted in previous reviews, this pattern is consistently used across the codebase for singleton implementations.

🧰 Tools

🪛 Biome (1.9.4)

[error] 43-43: Using this in a static context can be confusing.

this refers to the class.
Unsafe fix: Use the class name instead.

(lint/complexity/noThisInStatic)

---

[error] 44-44: Using this in a static context can be confusing.

this refers to the class.
Unsafe fix: Use the class name instead.

(lint/complexity/noThisInStatic)

---

[error] 47-47: Using this in a static context can be confusing.

this refers to the class.
Unsafe fix: Use the class name instead.

(lint/complexity/noThisInStatic)

src/content-helper/common/providers/check-auth-provider.ts (4)

17-21: Fix incorrect JSDoc comment description.

The JSDoc comment incorrectly states "Type definition for the Authorization request parameters" when it's actually describing the AuthResponse interface for the response.

/**
- * Type definition for the Authorization request parameters.
+ * Type definition for the Authorization response.
 *
 * @since 3.19.0
 */

---

22-25: Consider documenting response codes and their meanings.

The AuthResponse interface defines a code property but doesn't document what different code values mean. Adding this documentation would help consumers understand how to interpret the responses.

export interface AuthResponse {
	code: number;
	message: string;
+	/**
+	 * Response codes:
+	 * 200 - Authorized
+	 * 401 - Not authenticated
+	 * 403 - Not authorized
+	 * 500 - Server error
+	 */
}

---

50-53: Improve JSDoc description accuracy.

The method description mentions both "Suggestions API" and "Suggestions API feature" which seems redundant or confusing.

/**
- * Returns whether the Site ID is authorized to use the Suggestions API or
- * Suggestions API feature.
+ * Returns whether the Site ID is authorized to use the Suggestions API or
+ * Traffic Boost feature.
 *

---

61-83: Provide better default response and add retry handling.

The method initializes a default response with a code of 0, which isn't a standard HTTP status code. Consider using a more meaningful default value and adding configuration for retry attempts on failure.

public async getAuthorizationResponse( args: AuthRequestParams ): Promise<AuthResponse> {
-	let response: AuthResponse = { code: 0, message: '' };
+	let response: AuthResponse = { code: 500, message: 'Request not completed' };

	try {
		response = await this.fetch<AuthResponse>( {
			method: 'POST',
			path: addQueryArgs(
				'/wp-parsely/v2/content-helper/check-auth', {
					...args,
				} ),
+			retryAttempts: 2, // Add retry configuration if supported by BaseProvider
		} );
	} catch ( error: unknown ) {
		if ( error instanceof ContentHelperError ) {
			throw error;
		}

		if ( error instanceof Error ) {
			throw new ContentHelperError(
				error.message,
				ContentHelperErrorCode.UnknownError
			);
		}
+		
+		// Handle non-Error objects
+		throw new ContentHelperError(
+			'Unknown error occurred',
+			ContentHelperErrorCode.UnknownError
+		);
	}

	return response;
}

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting

src/content-helper/common/providers/check-auth-provider.ts (2)

17-21: Fix incorrect JSDoc description.

The JSDoc comment incorrectly describes this as "Type definition for the Authorization request parameters" when it's actually defining the response interface.

/**
- * Type definition for the Authorization request parameters.
+ * Type definition for the Authorization response.
 *
 *
 * @since 3.19.0
 */

---

50-53: Fix inaccurate method description.

The JSDoc comment mentions "Returns whether the Site ID is authorized" but it actually returns a response object with a code and message, not just a boolean.

/**
- * Returns whether the Site ID is authorized to use the Suggestions API or
- * Suggestions API feature.
+ * Returns authorization status information for the Site ID to use the Suggestions API or
+ * Traffic Boost feature.
 *

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting