convertkit / includes / mcp / abilities / settings / class-convertkit-mcp-ability-settings-update.php

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

183 lines 4.4 KB

Raw Download Zip

1	<?php
2	/**
3	* Kit MCP Ability: Update Settings.
4	*
5	* @package ConvertKit
6	* @author ConvertKit
7	*/
8
9	/**
10	* Ability that updates one or more values in a Kit settings group, scoped to
11	* the keys declared in the settings class's get_schema().
12	*
13	* Produces an ability named `kit/settings-<name>-update` (e.g. `kit/settings-general-update`).
14	*
15	* @package ConvertKit
16	* @author ConvertKit
17	*/
18	class ConvertKit_MCP_Ability_Settings_Update extends ConvertKit_MCP_Ability_Settings {
19
20	/**
21	* Sets whether the ability is idempotent.
22	*
23	* @since 3.4.0
24	*
25	* @var bool
26	*/
27	private $idempotent = true; // @phpstan-ignore-line
28
29	/**
30	* Returns the operation suffix used in the ability name.
31	*
32	* @since 3.4.0
33	*
34	* @return string
35	*/
36	protected function get_operation() {
37
38	return 'update';
39
40	}
41
42	/**
43	* Returns the ability's human-readable label.
44	*
45	* @since 3.4.0
46	*
47	* @return string
48	*/
49	public function get_label() {
50
51	return sprintf(
52	/* translators: %s: Settings Title, e.g. 'General Settings'. */
53	__( 'Update Kit Plugin %s', 'convertkit' ),
54	$this->settings->get_title()
55	);
56
57	}
58
59	/**
60	* Returns the ability's human-readable description.
61	*
62	* @since 3.4.0
63	*
64	* @return string
65	*/
66	public function get_description() {
67
68	return sprintf(
69	/* translators: %s: Settings Title, e.g. 'General Settings'. */
70	__( 'Updates one or more values in the Kit Plugin "%s". Only keys declared in the input schema can be updated; secret values (API keys, OAuth tokens) cannot be set via this ability.', 'convertkit' ),
71	$this->settings->get_title()
72	);
73
74	}
75
76	/**
77	* Returns the ability's input JSON Schema.
78	*
79	* Mirrors the settings class's get_schema() with secret keys removed, so
80	* partial updates are possible (no top-level `required`).
81	*
82	* @since 3.4.0
83	*
84	* @return array
85	*/
86	public function get_input_schema() {
87
88	return $this->get_public_schema();
89
90	}
91
92	/**
93	* Returns the ability's output JSON Schema.
94	*
95	* Returns the same shape as kit/settings-<slug>-get so a caller can chain
96	* update → confirm in one round trip.
97	*
98	* @since 3.4.0
99	*
100	* @return array
101	*/
102	public function get_output_schema() {
103
104	return $this->get_public_schema();
105
106	}
107
108	/**
109	* Executes the ability.
110	*
111	* Validates the input, rejecting unknown and secret keys
112	* and saves via the settings class.
113	*
114	* @since 3.4.0
115	*
116	* @param array $input Ability input.
117	* @return array\|WP_Error
118	*/
119	public function execute_callback( $input ) {
120
121	// Bail if no input is provided.
122	if ( ! count( $input ) ) {
123	return new WP_Error(
124	'convertkit_mcp_settings_invalid_input',
125	__( 'Input must be an object of settings keys and values.', 'convertkit' )
126	);
127	}
128
129	// Get the public schema, allowed and secret keys.
130	$schema = $this->get_public_schema();
131	$allowed_keys = array_keys( $schema['properties'] );
132	$secret_keys = $this->settings->get_secret_keys();
133
134	// Bail if any secret keys are provided in the input.
135	$secret_attempts = array_intersect( array_keys( $input ), $secret_keys );
136	if ( ! empty( $secret_attempts ) ) {
137	return new WP_Error(
138	'convertkit_mcp_settings_secret_write',
139	sprintf(
140	/* translators: %s: Comma-separated list of secret keys. */
141	__( 'The following settings cannot be updated via MCP: %s.', 'convertkit' ),
142	implode( ', ', $secret_attempts )
143	)
144	);
145	}
146
147	// Bail if any unknown keys are provided in the input.
148	$unknown_attempts = array_diff( array_keys( $input ), $allowed_keys );
149	if ( ! empty( $unknown_attempts ) ) {
150	return new WP_Error(
151	'convertkit_mcp_settings_unknown_keys',
152	sprintf(
153	/* translators: %s: Comma-separated list of unknown keys. */
154	__( 'The following settings keys are not recognised: %s.', 'convertkit' ),
155	implode( ', ', $unknown_attempts )
156	)
157	);
158	}
159
160	// Validate each provided value against its declared schema.
161	$validated = array();
162	foreach ( $input as $key => $value ) {
163	$valid = rest_validate_value_from_schema( $value, $schema['properties'][ $key ], $key );
164
165	// Bail if the value is invalid.
166	if ( is_wp_error( $valid ) ) {
167	return $valid;
168	}
169
170	$validated[ $key ] = rest_sanitize_value_from_schema( $value, $schema['properties'][ $key ], $key );
171	}
172
173	// Save via the settings class so its own sanitisation runs.
174	$this->settings->save( $validated );
175
176	// Return the post-save state.
177	$get_ability = new ConvertKit_MCP_Ability_Settings_Get( $this->settings );
178	return $get_ability->execute_callback( array() );
179
180	}
181
182	}
183