convertkit / includes / mcp / abilities / resources / class-convertkit-mcp-ability-resource.php

class-convertkit-mcp-ability-resource.php in Kit (formerly ConvertKit) – Email Newsletter, Email Marketing, Membership, Subscribers and Landing Pages 3.4.3, at includes/mcp/abilities/resources/class-convertkit-mcp-ability-resource.php

250 lines 5.7 KB

Raw Download Zip

1	<?php
2	/**
3	* Kit MCP Ability: Resource list base class.
4	*
5	* @package ConvertKit
6	* @author ConvertKit
7	*/
8
9	/**
10	* Base class for abilities to list resources (Forms, Tags, Landing Pages, Products).
11	*
12	* Each subclass represents a single resouce type.
13	*
14	* @package ConvertKit
15	* @author ConvertKit
16	*/
17	abstract class ConvertKit_MCP_Ability_Resource extends ConvertKit_MCP_Ability {
18
19	/**
20	* Sets whether the ability is readonly.
21	*
22	* @since 3.4.0
23	*
24	* @var bool
25	*/
26	private $readonly = true; // @phpstan-ignore-line
27
28	/**
29	* Sets whether the ability is idempotent.
30	*
31	* @since 3.4.0
32	*
33	* @var bool
34	*/
35	private $idempotent = true; // @phpstan-ignore-line
36
37	/**
38	* Returns the ability name, derived from the resource slug.
39	*
40	* For example, the Forms list ability is named `kit/forms-list`.
41	*
42	* @since 3.4.0
43	*
44	* @return string
45	*/
46	public function get_name() {
47
48	return 'kit/' . $this->get_resource() . '-list';
49
50	}
51
52	/**
53	* Returns the resource slug for this ability, used in the ability name
54	* and as a hint for clients (e.g. `forms`, `tags`, `landing-pages`,
55	* `products`).
56	*
57	* @since 3.4.0
58	*
59	* @return string
60	*/
61	abstract protected function get_resource();
62
63	/**
64	* Returns the fully-qualified class name of the ConvertKit_Resource_*
65	* implementation backing this ability.
66	*
67	* @since 3.4.0
68	*
69	* @return string
70	*/
71	abstract protected function get_resource_class();
72
73	/**
74	* Maps a single raw resource item from the resource class' get() method
75	* into the shape exposed in this ability's output.
76	*
77	* The default implementation returns just id and name. Subclasses may
78	* override to expose additional per-item fields (e.g. Forms includes
79	* `format`) — output_schema() should be overridden to match.
80	*
81	* @since 3.4.0
82	*
83	* @param array $item Raw item from the resource class' get() method.
84	* @return array
85	*/
86	protected function map_item( $item ) {
87
88	return array(
89	'id' => (int) ( $item['id'] ?? 0 ),
90	'name' => (string) ( $item['name'] ?? '' ),
91	);
92
93	}
94
95	/**
96	* Returns the JSON Schema describing a single item in the output `items`
97	* array.
98	*
99	* Subclasses may override to add per-resource fields. Keep in sync with
100	* map_item() — both describe the same shape, one in schema form and one
101	* in PHP.
102	*
103	* @since 3.4.0
104	*
105	* @return array
106	*/
107	protected function get_item_schema() {
108
109	return array(
110	'type' => 'object',
111	'required' => array( 'id', 'name' ),
112	'properties' => array(
113	'id' => array(
114	'type' => 'integer',
115	'description' => __( 'Numeric ID of the resource item.', 'convertkit' ),
116	),
117	'name' => array(
118	'type' => 'string',
119	'description' => __( 'Human-readable name of the resource item.', 'convertkit' ),
120	),
121	),
122	);
123
124	}
125
126	/**
127	* Permission callback for resource-list abilities.
128	*
129	* Listing available Kit resources is permitted for anyone who can edit
130	* posts — the same capability gate that allows placing a Kit element on
131	* a post, where these lists are typically used as a lookup.
132	*
133	* @since 3.4.0
134	*
135	* @param array $input Ability input (unused).
136	* @return bool\|WP_Error
137	*/
138	public function permission_callback( $input ) {
139
140	if ( ! current_user_can( 'edit_posts' ) ) {
141	return new WP_Error(
142	'convertkit_mcp_cannot_list_resources',
143	__( 'You do not have permission to list Kit resources.', 'convertkit' )
144	);
145	}
146
147	return true;
148
149	}
150
151	/**
152	* Returns the ability's input JSON Schema.
153	*
154	* Resource-list abilities take no input.
155	*
156	* @since 3.4.0
157	*
158	* @return array
159	*/
160	public function get_input_schema() {
161
162	return array(
163	'type' => 'object',
164	'properties' => new stdClass(),
165	);
166
167	}
168
169	/**
170	* Returns the ability's output JSON Schema.
171	*
172	* @since 3.4.0
173	*
174	* @return array
175	*/
176	public function get_output_schema() {
177
178	return array(
179	'type' => 'object',
180	'required' => array( 'count', 'items' ),
181	'properties' => array(
182	'count' => array(
183	'type' => 'integer',
184	'minimum' => 0,
185	'description' => __( 'The number of items returned.', 'convertkit' ),
186	),
187	'items' => array(
188	'type' => 'array',
189	'description' => __( 'The resource items.', 'convertkit' ),
190	'items' => $this->get_item_schema(),
191	),
192	),
193	);
194
195	}
196
197	/**
198	* Executes the ability: instantiate the backing resource class, fetch
199	* its cached items, and return them mapped to this ability's output
200	* shape.
201	*
202	* A "no items" result (e.g. the Plugin has not yet cached this resource
203	* from the Kit API) is returned as a successful empty list rather than
204	* an error, so the model can explain the absence to the user.
205	*
206	* @since 3.4.0
207	*
208	* @param array $input Ability input (unused).
209	* @return array\|WP_Error
210	*/
211	public function execute_callback( $input ) {
212
213	// Instantiate the backing resource class.
214	$resource_class = $this->get_resource_class();
215	if ( ! class_exists( $resource_class ) ) {
216	return new WP_Error(
217	'convertkit_mcp_resource_class_missing',
218	sprintf(
219	/* translators: %s: Resource class name */
220	__( 'The resource class "%s" does not exist.', 'convertkit' ),
221	$resource_class
222	)
223	);
224	}
225
226	$resource = new $resource_class();
227
228	// Fetch the items from the resource cache. ConvertKit_Resource::get()
229	// returns false when nothing has been cached; normalise that to an
230	// empty array so the output shape is always consistent.
231	$items = $resource->get();
232	if ( ! is_array( $items ) ) {
233	$items = array();
234	}
235
236	// Map each raw item to the ability's output shape.
237	$mapped = array();
238	foreach ( $items as $item ) {
239	$mapped[] = $this->map_item( $item );
240	}
241
242	return array(
243	'count' => count( $mapped ),
244	'items' => $mapped,
245	);
246
247	}
248
249	}
250