wp-parsely / src / services / suggestions-api / class-suggestions-api-service.php

class-suggestions-api-service.php in Parse.ly 3.24.3, at src/services/suggestions-api/class-suggestions-api-service.php

170 lines 6.4 KB

Raw Download Zip

1	<?php
2	/**
3	* Parse.ly Suggestions API service class.
4	*
5	* @package Parsely
6	* @since 3.17.0
7	*/
8
9	declare(strict_types=1);
10
11	namespace Parsely\Services\Suggestions_API;
12
13	use Parsely\Models\Smart_Link;
14	use Parsely\Services\Base_API_Service;
15	use WP_Error;
16
17	/**
18	* The service for the Suggestions API.
19	*
20	* @since 3.17.0
21	*
22	* @phpstan-import-type Endpoint_Suggest_Brief_Options from Endpoints\Endpoint_Suggest_Brief
23	* @phpstan-import-type Endpoint_Suggest_Headline_Options from Endpoints\Endpoint_Suggest_Headline
24	* @phpstan-import-type Endpoint_Suggest_Linked_Reference_Options from Endpoints\Endpoint_Suggest_Linked_Reference
25	* @phpstan-import-type Endpoint_Suggest_Inbound_Links_Options from Endpoints\Endpoint_Suggest_Inbound_Links
26	* @phpstan-import-type Endpoint_Suggest_Inbound_Link_Positions_Options from Endpoints\Endpoint_Suggest_Inbound_Link_Positions
27	*/
28	class Suggestions_API_Service extends Base_API_Service {
29	/**
30	* Returns the base URL for the API service.
31	*
32	* @since 3.17.0
33	*
34	* @return string
35	*/
36	public static function get_base_url(): string {
37	return 'https://suggestions-api.parsely.com';
38	}
39
40	/**
41	* Registers the endpoints for the service.
42	*
43	* @since 3.17.0
44	*/
45	protected function register_endpoints(): void {
46	$endpoints = array(
47	new Endpoints\Endpoint_Check_Auth( $this ),
48	new Endpoints\Endpoint_Suggest_Brief( $this ),
49	new Endpoints\Endpoint_Suggest_Headline( $this ),
50	new Endpoints\Endpoint_Suggest_Linked_Reference( $this ),
51	new Endpoints\Endpoint_Suggest_Inbound_Links( $this ),
52	new Endpoints\Endpoint_Suggest_Inbound_Link_Positions( $this ),
53	);
54
55	foreach ( $endpoints as $endpoint ) {
56	$this->register_endpoint( $endpoint );
57	}
58	}
59
60	/**
61	* Gets the first brief (meta description) for a given content using the
62	* Parse.ly Content Suggestion API.
63	*
64	* @since 3.13.0
65	* @since 3.17.0 Updated to use the new API service.
66	*
67	* @param string $title The title of the content.
68	* @param string $content The query arguments to send to the remote API.
69	* @param Endpoint_Suggest_Brief_Options $options The options to pass to the API request.
70	* @return array<string>\|WP_Error The response from the remote API, or a WP_Error
71	* object if the response is an error.
72	*/
73	public function get_brief_suggestions( string $title, string $content, $options = array() ) {
74	/** @var Endpoints\Endpoint_Suggest_Brief $endpoint */
75	$endpoint = $this->get_endpoint( '/suggest-brief' );
76
77	return $endpoint->get_suggestion( $title, $content, $options );
78	}
79
80	/**
81	* Gets titles (headlines) for a given content using the Parse.ly Content
82	* Suggestion API.
83	*
84	* @since 3.13.0
85	* @since 3.17.0 Updated to use the new API service.
86	*
87	* @param string $content The query arguments to send to the remote API.
88	* @param Endpoint_Suggest_Headline_Options $options The options to pass to the API request.
89	* @return array<string>\|WP_Error The response from the remote API, or a WP_Error
90	* object if the response is an error.
91	*/
92	public function get_title_suggestions( string $content, $options = array() ) {
93	/** @var Endpoints\Endpoint_Suggest_Headline $endpoint */
94	$endpoint = $this->get_endpoint( '/suggest-headline' );
95
96	return $endpoint->get_headlines( $content, $options );
97	}
98
99	/**
100	* Gets the Site ID's authorization status for the Suggestions API or
101	* Suggestions API feature.
102	*
103	* @since 3.19.0
104	*
105	* @param array<mixed> $options The options to pass to the API request.
106	* @return array<mixed>\|WP_Error The response from the remote API, or a WP_Error
107	* object if the response is an error.
108	*/
109	public function get_check_auth( array $options ) {
110	/** @var Endpoints\Endpoint_Check_Auth $endpoint */
111	$endpoint = $this->get_endpoint( '/check-auth' );
112
113	return $endpoint->get_check_auth_result( $options );
114	}
115
116	/**
117	* Gets suggested smart links for the given content.
118	*
119	* @since 3.14.0
120	* @since 3.17.0 Updated to use the new API service.
121	*
122	* @param string $content The content to generate links for.
123	* @param Endpoint_Suggest_Linked_Reference_Options $options The options to pass to the API request.
124	*
125	* @return array<Smart_Link>\|WP_Error The response from the remote API, or a WP_Error
126	* object if the response is an error.
127	*/
128	public function get_smart_links( string $content, $options = array() ) {
129	/** @var Endpoints\Endpoint_Suggest_Linked_Reference $endpoint */
130	$endpoint = $this->get_endpoint( '/suggest-linked-reference' );
131
132	return $endpoint->get_links( $content, $options );
133	}
134
135	/**
136	* Gets suggested inbound links for the given URL.
137	*
138	* @since 3.19.0
139	*
140	* @param \WP_Post $post The post to get inbound link suggestions for.
141	* @param Endpoint_Suggest_Inbound_Links_Options $options The options to pass to the API request.
142	* @return array<\Parsely\Models\Inbound_Smart_Link>\|WP_Error The response from the remote API, or a WP_Error
143	* object if the response is an error.
144	*/
145	public function get_inbound_links( \WP_Post $post, $options = array() ) {
146	/** @var Endpoints\Endpoint_Suggest_Inbound_Links $endpoint */
147	$endpoint = $this->get_endpoint( '/suggest-inbound-links' );
148
149	return $endpoint->get_inbound_links( $post, $options );
150	}
151
152	/**
153	* Gets suggested inbound link positions for the given source and destination posts.
154	*
155	* @since 3.19.0
156	*
157	* @param \WP_Post $source_post The source post to get inbound link positions for.
158	* @param \WP_Post $destination_post The destination post to get inbound link positions for.
159	* @param Endpoint_Suggest_Inbound_Link_Positions_Options $options The options to pass to the API request.
160	* @return \Parsely\Models\Inbound_Smart_Link[]\|WP_Error The response from the remote API, or a WP_Error
161	* object if the response is an error.
162	*/
163	public function get_inbound_link_positions( \WP_Post $source_post, \WP_Post $destination_post, $options = array() ) {
164	/** @var Endpoints\Endpoint_Suggest_Inbound_Link_Positions $endpoint */
165	$endpoint = $this->get_endpoint( '/suggest-inbound-link-positions' );
166
167	return $endpoint->get_inbound_link_positions( $source_post, $destination_post, $options );
168	}
169	}
170