AbstractAbility.php — SureCart – Ecommerce Made Easy For Selling Physical Products, Digital Downloads, Subscriptions, Donations, & Payments 4.7.1

surecart / app / src / Abilities / Abilities / AbstractAbility.php

surecart / app / src / Abilities / Abilities Last commit date

AbstractAbility.php

328 lines

1	<?php
2
3	namespace SureCart\Abilities\Abilities;
4
5	/**
6	* Base class for all SureCart abilities.
7	*/
8	abstract class AbstractAbility {
9
10	/**
11	* Get the ability name (e.g., 'surecart/list-products').
12	*
13	* @return string
14	*/
15	abstract public function get_name(): string;
16
17	/**
18	* Get the ability label.
19	*
20	* @return string
21	*/
22	abstract public function get_label(): string;
23
24	/**
25	* Get the ability description.
26	*
27	* @return string
28	*/
29	abstract public function get_description(): string;
30
31	/**
32	* Get the ability annotations.
33	*
34	* Returns an array with three boolean keys:
35	* - 'readonly' — true if the ability only reads data (maps to GET).
36	* - 'destructive' — true if the ability deletes or irreversibly modifies data.
37	* - 'idempotent' — true if calling multiple times produces the same result.
38	*
39	* @return array{readonly: bool, destructive: bool, idempotent: bool}
40	*/
41	abstract public function get_annotations(): array;
42
43	/**
44	* Get AI-facing instructions for when and how to use this ability.
45	*
46	* Override in subclasses to provide guidance on edge cases,
47	* confirmation requirements, and usage patterns.
48	*
49	* @return string
50	*/
51	public function get_instructions(): string {
52	return '';
53	}
54
55	/**
56	* Get the JSON Schema for the input.
57	*
58	* @return array
59	*/
60	abstract public function get_input_schema(): array;
61
62	/**
63	* Get the JSON Schema for the output.
64	*
65	* @return array
66	*/
67	abstract public function get_output_schema(): array;
68
69	/**
70	* Execute the ability.
71	*
72	* @param array $input The input data.
73	*
74	* @return array\|\WP_Error The result array on success, or WP_Error on failure.
75	*/
76	abstract public function execute( array $input );
77
78	/**
79	* Check if the current user has permission to execute this ability.
80	*
81	* @return bool
82	*/
83	public function check_permission(): bool {
84	return false;
85	}
86
87	/**
88	* Get the full configuration array for wp_register_ability().
89	*
90	* @return array
91	*/
92	public function get_config(): array {
93	return array(
94	'label' => $this->get_label(),
95	'description' => $this->get_description(),
96	'category' => 'surecart-ecommerce',
97	'permission_callback' => array( $this, 'check_permission' ),
98	'input_schema' => $this->get_input_schema(),
99	'output_schema' => $this->get_output_schema(),
100	'execute_callback' => function ( array $input ) {
101	$result = $this->execute( $input );
102	return is_wp_error( $result ) ? $this->extract_detailed_error( $result ) : $result;
103	},
104	'meta' => array(
105	'public' => true, // Unified exposure flag (WP 7.1+).
106	'show_in_rest' => true,
107	'annotations' => $this->get_annotations(),
108	'instructions' => $this->get_instructions(),
109	'mcp' => array(
110	'public' => true,
111	),
112	),
113	);
114	}
115
116	/**
117	* Return a success response.
118	*
119	* @param array $data The response data.
120	*
121	* @return array
122	*/
123	protected function success( array $data = array() ): array {
124	return array_merge( array( 'success' => true ), $data );
125	}
126
127	/**
128	* Return a WP_Error for a validation or logic error.
129	*
130	* @param string $code The error code.
131	* @param string $message The error message.
132	*
133	* @return \WP_Error
134	*/
135	protected function error( string $code, string $message ): \WP_Error {
136	return new \WP_Error( $code, $message );
137	}
138
139	/**
140	* Extract a detailed error message from a WP_Error, including validation errors.
141	*
142	* The SureCart API often returns a generic top-level message (e.g. "There were some
143	* validation errors") with field-level details in additional error entries. This method
144	* combines all error messages into a single, actionable WP_Error.
145	*
146	* @param \WP_Error $wp_error The WP_Error to process.
147	*
148	* @return \WP_Error A WP_Error with a detailed, combined message.
149	*/
150	private function extract_detailed_error( \WP_Error $wp_error ): \WP_Error {
151	$messages = $wp_error->get_error_messages();
152
153	// If there's only one message, return as-is.
154	if ( count( $messages ) <= 1 ) {
155	return $wp_error;
156	}
157
158	// Combine all messages: skip the generic first message if there are field-level details.
159	// Deduplicate to avoid repeated messages (e.g. "Amount is invalid. Amount is invalid.").
160	$detail_messages = array_unique( array_slice( $messages, 1 ) );
161	$combined = implode( ' ', $detail_messages );
162
163	return new \WP_Error(
164	$wp_error->get_error_code(),
165	$combined,
166	$wp_error->get_error_data()
167	);
168	}
169
170	/**
171	* Normalize ability input that may be a JSON string or an array (e.g. from form fields).
172	*
173	* @param mixed $value Raw input.
174	*
175	* @return array\|null The decoded or original array, or null if not a valid array.
176	*/
177	protected function parse_json_or_array( $value ): ?array {
178	if ( is_string( $value ) ) {
179	$value = json_decode( $value, true );
180	}
181	return is_array( $value ) ? $value : null;
182	}
183
184	/**
185	* Recursively sanitize and structurally validate a filter rule tree.
186	*
187	* Rebuilds a clean tree from known keys only, dropping any unexpected keys,
188	* whitelisting type and combinator, and sanitizing the scalar leaves.
189	*
190	* @param mixed $rules The raw rule tree (condition or group).
191	* @param int $depth Current recursion depth, used to bound deeply nested input.
192	*
193	* @return array\|\WP_Error Clean rule tree, or WP_Error if structurally invalid.
194	*/
195	protected function sanitize_rule_tree( $rules, $depth = 0 ) {
196	if ( $depth > 10 ) {
197	return new \WP_Error( 'invalid_filter', __( 'Filter rule tree is too deeply nested.', 'surecart' ) );
198	}
199
200	if ( ! is_array( $rules ) \|\| empty( $rules ) ) {
201	return new \WP_Error( 'invalid_filter', __( 'The filter must be a condition or group object.', 'surecart' ) );
202	}
203
204	$type = sanitize_text_field( $rules['type'] ?? '' );
205
206	if ( 'group' === $type ) {
207	$combinator = sanitize_text_field( $rules['combinator'] ?? '' );
208	if ( ! in_array( $combinator, array( 'and', 'or' ), true ) ) {
209	return new \WP_Error( 'invalid_filter', __( 'A group combinator must be "and" or "or".', 'surecart' ) );
210	}
211
212	$conditions = $rules['conditions'] ?? array();
213	if ( ! is_array( $conditions ) \|\| empty( $conditions ) ) {
214	return new \WP_Error( 'invalid_filter', __( 'A group must have at least one condition.', 'surecart' ) );
215	}
216
217	if ( count( $conditions ) > 50 ) {
218	return new \WP_Error( 'invalid_filter', __( 'A group has too many conditions (max 50).', 'surecart' ) );
219	}
220
221	$clean = array();
222	foreach ( $conditions as $condition ) {
223	$sanitized = $this->sanitize_rule_tree( $condition, $depth + 1 );
224	if ( is_wp_error( $sanitized ) ) {
225	return $sanitized;
226	}
227	$clean[] = $sanitized;
228	}
229
230	return array(
231	'type' => 'group',
232	'combinator' => $combinator,
233	'conditions' => $clean,
234	);
235	}
236
237	if ( 'condition' === $type ) {
238	$value = $rules['comparison_value'] ?? '';
239	return array(
240	'type' => 'condition',
241	'attribute_name' => sanitize_text_field( $rules['attribute_name'] ?? '' ),
242	'operator_label' => sanitize_text_field( $rules['operator_label'] ?? '' ),
243	'comparison_value' => is_scalar( $value ) ? sanitize_text_field( (string) $value ) : '',
244	);
245	}
246
247	return new \WP_Error( 'invalid_filter', __( 'Each rule must have a type of "condition" or "group".', 'surecart' ) );
248	}
249
250	/**
251	* Validate a date string is in YYYY-MM-DD format.
252	*
253	* @param string $date The date string to validate.
254	*
255	* @return bool
256	*/
257	protected function is_valid_date( string $date ): bool {
258	$d = \DateTime::createFromFormat( 'Y-m-d', $date );
259	return $d && $d->format( 'Y-m-d' ) === $date;
260	}
261
262	/**
263	* Validate and normalize stats query args from ability input.
264	*
265	* Accepts optional YYYY-MM-DD date strings and passes them directly
266	* to the SureCart statistics API.
267	*
268	* @param array $input The raw ability input.
269	*
270	* @return array\|\WP_Error Normalized args array, or WP_Error on validation failure.
271	*/
272	protected function resolve_stats_args( array $input ) {
273	$allowed_intervals = array( 'hour', 'day', 'week', 'month', 'year' );
274	$interval = sanitize_text_field( $input['interval'] ?? 'day' );
275	if ( ! in_array( $interval, $allowed_intervals, true ) ) {
276	return new \WP_Error(
277	'invalid_interval',
278	/* translators: %s: comma-separated list of valid interval values */
279	sprintf( __( 'Invalid interval. Allowed values: %s', 'surecart' ), implode( ', ', $allowed_intervals ) )
280	);
281	}
282
283	$args = array( 'interval' => $interval );
284
285	if ( ! empty( $input['start_date'] ) ) {
286	$start_date = sanitize_text_field( $input['start_date'] );
287	if ( ! $this->is_valid_date( $start_date ) ) {
288	return new \WP_Error( 'invalid_date', __( 'start_date must be in YYYY-MM-DD format.', 'surecart' ) );
289	}
290	$args['start_at'] = $start_date;
291	}
292
293	if ( ! empty( $input['end_date'] ) ) {
294	$end_date = sanitize_text_field( $input['end_date'] );
295	if ( ! $this->is_valid_date( $end_date ) ) {
296	return new \WP_Error( 'invalid_date', __( 'end_date must be in YYYY-MM-DD format.', 'surecart' ) );
297	}
298	$args['end_at'] = $end_date;
299	}
300
301	return $args;
302	}
303
304	/**
305	* Convert a model object to an array, handling nested objects.
306	*
307	* @param mixed $model The model or data to convert.
308	*
309	* @return array
310	*/
311	protected function model_to_array( $model ): array {
312	if ( is_array( $model ) ) {
313	return $model;
314	}
315
316	if ( $model instanceof \JsonSerializable ) {
317	$data = $model->jsonSerialize();
318	return is_array( $data ) ? $data : array();
319	}
320
321	if ( is_object( $model ) ) {
322	return (array) $model;
323	}
324
325	return array();
326	}
327	}
328