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

class-convertkit-mcp-ability-resource-forms.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-forms.php

134 lines 3.4 KB

Raw Download Zip

1	<?php
2	/**
3	* Kit MCP Ability: List Forms.
4	*
5	* @package ConvertKit
6	* @author ConvertKit
7	*/
8
9	/**
10	* Ability that lists every Kit Form cached from the connected Kit account,
11	* returning each form's ID, name and format (inline / modal / slide in /
12	* sticky bar).
13	*
14	* Produces an ability named `kit/forms-list`.
15	*
16	* @package ConvertKit
17	* @author ConvertKit
18	*/
19	class ConvertKit_MCP_Ability_Resource_Forms extends ConvertKit_MCP_Ability_Resource {
20
21	/**
22	* Returns the resource slug for this ability.
23	*
24	* @since 3.4.0
25	*
26	* @return string
27	*/
28	protected function get_resource() {
29
30	return 'forms';
31
32	}
33
34	/**
35	* Returns the class name of the ConvertKit_Resource_* implementation
36	* backing this ability.
37	*
38	* @since 3.4.0
39	*
40	* @return string
41	*/
42	protected function get_resource_class() {
43
44	return 'ConvertKit_Resource_Forms';
45
46	}
47
48	/**
49	* Returns the ability's human-readable label.
50	*
51	* @since 3.4.0
52	*
53	* @return string
54	*/
55	public function get_label() {
56
57	return __( 'List Kit Forms', 'convertkit' );
58
59	}
60
61	/**
62	* Returns the ability's human-readable description.
63	*
64	* Phrased as guidance to the model: state what the ability returns and
65	* (importantly) when to chain it ahead of insert / update / settings
66	* abilities so a user can refer to a Form by name rather than ID.
67	*
68	* @since 3.4.0
69	*
70	* @return string
71	*/
72	public function get_description() {
73
74	return __( 'Lists every Kit Form configured on the connected Kit account, returning each form\'s numeric ID, name and format (inline, modal, slide in or sticky bar). Use this before kit/form-insert, kit/form-update, kit/post-settings-update or kit/settings-update when the user refers to a Form by name rather than ID, to look up the corresponding numeric Form ID.', 'convertkit' );
75
76	}
77
78	/**
79	* Maps a single raw Form item from the resource cache into the output
80	* shape, adding `format` so the model can distinguish inline forms (which
81	* render in-place) from non-inline forms (modal / slide in / sticky bar,
82	* which trigger from elsewhere). Legacy forms omit the `format` key in
83	* the cached data; they are treated as inline to match the rest of the
84	* Plugin\'s behaviour.
85	*
86	* @since 3.4.0
87	*
88	* @param array $item Raw Form item.
89	* @return array
90	*/
91	protected function map_item( $item ) {
92
93	return array(
94	'id' => (int) ( $item['id'] ?? 0 ),
95	'name' => (string) ( $item['name'] ?? '' ),
96	'format' => isset( $item['format'] ) && $item['format'] !== '' ? (string) $item['format'] : 'inline',
97	);
98
99	}
100
101	/**
102	* Returns the JSON Schema for a single Form item, including the `format`
103	* field added by map_item().
104	*
105	* @since 3.4.0
106	*
107	* @return array
108	*/
109	protected function get_item_schema() {
110
111	return array(
112	'type' => 'object',
113	'required' => array( 'id', 'name', 'format' ),
114	'properties' => array(
115	'id' => array(
116	'type' => 'integer',
117	'description' => __( 'Numeric ID of the Kit Form.', 'convertkit' ),
118	),
119	'name' => array(
120	'type' => 'string',
121	'description' => __( 'Human-readable name of the Kit Form.', 'convertkit' ),
122	),
123	'format' => array(
124	'type' => 'string',
125	'enum' => array( 'inline', 'modal', 'slide in', 'sticky bar' ),
126	'description' => __( 'Where and how the Form is displayed. Inline forms render in post content; modal / slide in / sticky bar forms are site-wide overlays triggered elsewhere.', 'convertkit' ),
127	),
128	),
129	);
130
131	}
132
133	}
134