cartflows / .abilities-audit / modules / flow / mining.md

mining.md in CartFlows – Funnel Builder & Checkout Plugin for WooCommerce 3.0.1, at .abilities-audit/modules/flow/mining.md

691 lines 19.0 KB

Raw Download Zip

1	# Phase 1: Ability Mining — Flow (Funnel) Module
2
3	Module: Flow / Funnel
4	Source files:
5	- `admin-core/ajax/flows.php`
6	- `admin-core/api/flows.php` (REST: list flows)
7	- `admin-core/api/flow-data.php` (REST: get single flow)
8
9	---
10
11	## Mining Checklist
12
13	- [x] Setup/Install: Activation creates CPTs, flushes rewrite rules
14	- [x] CRUD: list, get, create (via importer), update, delete for flows and steps
15	- [x] Lifecycle: trash, restore, clone, publish/draft toggle
16	- [x] Output/Embedding: export as JSON, get permalink
17	- [x] Analytics/Stats: See analytics module
18	- [x] Relationships: steps belong to flows (reorder, add, remove)
19	- [x] Bulk Operations: bulk trash, bulk status update, bulk delete, bulk export
20	- [x] Configuration: flow meta settings (title, slug, testing mode, layout)
21
22	---
23
24	## Ability Candidates
25
26	### CF-F-01: cartflows/list-flows
27
28	- Label: List funnels
29	- Description: Returns a paginated list of CartFlows funnels with optional status, search, and date filters. Excludes the store checkout flow. Useful for browsing or selecting funnels.
30	- Category: cartflows
31	- Ability category type: CRUD (Read)
32	- Input schema:
33	```json
34	{
35	"type": "object",
36	"properties": {
37	"status": {"type": "string", "enum": ["publish","draft","trash","any"], "default": "publish", "description": "Filter by post status."},
38	"search": {"type": "string", "description": "Search term to filter funnels by title."},
39	"paged": {"type": "integer", "description": "Page number.", "default": 1},
40	"per_page": {"type": "integer", "description": "Funnels per page (max 100).", "default": 10}
41	}
42	}
43	```
44	- Output schema:
45	```json
46	{
47	"type": "object",
48	"properties": {
49	"items": {"type": "array", "items": {"type": "object", "properties": {
50	"ID": {"type": "integer", "description": "Funnel ID."},
51	"post_title": {"type": "string", "description": "Funnel title."},
52	"post_status": {"type": "string", "description": "Funnel status."},
53	"post_date": {"type": "string", "description": "Creation date."},
54	"flow_test_mode": {"type": "boolean", "description": "Whether funnel is in test mode."}
55	}}},
56	"found_posts": {"type": "integer", "description": "Total matching funnels."},
57	"active_flows_count": {"type": "integer", "description": "Total published funnels."},
58	"draft_flows_count": {"type": "integer", "description": "Total draft funnels."},
59	"pagination": {"type": "object", "properties": {
60	"max_pages": {"type": "integer"},
61	"paged": {"type": "integer"},
62	"found_posts": {"type": "integer"}
63	}}
64	}
65	}
66	```
67	- Permission: `cartflows_manage_flows_steps`
68	- Meta annotations:
69	- priority: 1.0
70	- readOnlyHint: true
71	- destructiveHint: false
72	- idempotentHint: true
73	- openWorldHint: false
74	- mcp.type: resource
75
76	---
77
78	### CF-F-02: cartflows/get-flow
79
80	- Label: Get funnel
81	- Description: Returns full data for a single CartFlows funnel by ID, including its ordered steps, settings, and permalink.
82	- Category: cartflows
83	- Ability category type: CRUD (Read)
84	- Input schema:
85	```json
86	{
87	"type": "object",
88	"required": ["id"],
89	"properties": {
90	"id": {"type": "integer", "description": "The funnel (flow) ID."}
91	}
92	}
93	```
94	- Output schema:
95	```json
96	{
97	"type": "object",
98	"properties": {
99	"id": {"type": "integer"},
100	"title": {"type": "string"},
101	"slug": {"type": "string"},
102	"link": {"type": "string", "format": "uri"},
103	"status": {"type": "string"},
104	"steps": {"type": "array", "items": {"type": "object", "properties": {
105	"id": {"type": "integer"},
106	"title": {"type": "string"},
107	"type": {"type": "string", "description": "Step type: checkout, thankyou, optin, landing."},
108	"link": {"type": "string", "format": "uri"}
109	}}},
110	"options": {"type": "object", "description": "Funnel meta options."},
111	"settings_data": {"type": "object", "description": "Funnel settings panel data."}
112	}
113	}
114	```
115	- Permission: `cartflows_manage_flows_steps`
116	- Meta annotations:
117	- priority: 1.0
118	- readOnlyHint: true
119	- destructiveHint: false
120	- idempotentHint: true
121	- openWorldHint: false
122	- mcp.type: resource
123
124	---
125
126	### CF-F-03: cartflows/update-flow
127
128	- Label: Update funnel
129	- Description: Updates a CartFlows funnel's title and/or slug. Use for renaming funnels.
130	- Category: cartflows
131	- Ability category type: CRUD (Update)
132	- Input schema:
133	```json
134	{
135	"type": "object",
136	"required": ["id", "title"],
137	"properties": {
138	"id": {"type": "integer", "description": "The funnel ID."},
139	"title": {"type": "string", "description": "New funnel title."},
140	"slug": {"type": "string", "description": "New funnel URL slug (optional)."}
141	}
142	}
143	```
144	- Output schema:
145	```json
146	{
147	"type": "object",
148	"properties": {
149	"success": {"type": "boolean"},
150	"message": {"type": "string"}
151	}
152	}
153	```
154	- Permission: `cartflows_manage_flows_steps`
155	- Meta annotations:
156	- priority: 2.0
157	- readOnlyHint: false
158	- destructiveHint: false
159	- idempotentHint: true
160	- openWorldHint: false
161	- mcp.type: tool
162
163	---
164
165	### CF-F-04: cartflows/publish-flow
166
167	- Label: Publish funnel
168	- Description: Sets a CartFlows funnel's status to published (active). Also publishes all its steps. Use to activate a funnel so visitors can see it.
169	- Category: cartflows
170	- Ability category type: Lifecycle
171	- Input schema:
172	```json
173	{
174	"type": "object",
175	"required": ["id"],
176	"properties": {
177	"id": {"type": "integer", "description": "The funnel ID."}
178	}
179	}
180	```
181	- Output schema:
182	```json
183	{
184	"type": "object",
185	"properties": {
186	"success": {"type": "boolean"},
187	"message": {"type": "string"}
188	}
189	}
190	```
191	- Permission: `cartflows_manage_flows_steps`
192	- Meta annotations:
193	- priority: 2.0
194	- readOnlyHint: false
195	- destructiveHint: false
196	- idempotentHint: true
197	- openWorldHint: false
198	- mcp.type: tool
199
200	---
201
202	### CF-F-05: cartflows/unpublish-flow
203
204	- Label: Unpublish funnel
205	- Description: Sets a CartFlows funnel's status to draft (inactive). Also drafts all its steps. Use to temporarily disable a funnel.
206	- Category: cartflows
207	- Ability category type: Lifecycle
208	- Input schema:
209	```json
210	{
211	"type": "object",
212	"required": ["id"],
213	"properties": {
214	"id": {"type": "integer", "description": "The funnel ID."}
215	}
216	}
217	```
218	- Output schema:
219	```json
220	{
221	"type": "object",
222	"properties": {
223	"success": {"type": "boolean"},
224	"message": {"type": "string"}
225	}
226	}
227	```
228	- Permission: `cartflows_manage_flows_steps`
229	- Meta annotations:
230	- priority: 2.0
231	- readOnlyHint: false
232	- destructiveHint: false
233	- idempotentHint: true
234	- openWorldHint: false
235	- mcp.type: tool
236
237	---
238
239	### CF-F-06: cartflows/clone-flow
240
241	- Label: Clone funnel
242	- Description: Creates a full duplicate of a CartFlows funnel, including all steps and their settings. The new funnel is titled "[Original Title] Clone".
243	- Category: cartflows
244	- Ability category type: Lifecycle
245	- Input schema:
246	```json
247	{
248	"type": "object",
249	"required": ["id"],
250	"properties": {
251	"id": {"type": "integer", "description": "The funnel ID to clone."}
252	}
253	}
254	```
255	- Output schema:
256	```json
257	{
258	"type": "object",
259	"properties": {
260	"success": {"type": "boolean"},
261	"message": {"type": "string"},
262	"new_flow_id": {"type": "integer", "description": "ID of the newly created funnel."},
263	"edit_url": {"type": "string", "format": "uri", "description": "Admin edit URL for the new funnel."}
264	}
265	}
266	```
267	- Permission: `cartflows_manage_flows_steps`
268	- Meta annotations:
269	- priority: 2.0
270	- readOnlyHint: false
271	- destructiveHint: false
272	- idempotentHint: false
273	- openWorldHint: false
274	- mcp.type: tool
275
276	---
277
278	### CF-F-07: cartflows/trash-flow
279
280	- Label: Trash funnel
281	- Description: Moves a CartFlows funnel and all its steps to trash. Use to soft-delete a funnel while allowing recovery.
282	- Category: cartflows
283	- Ability category type: Lifecycle
284	- Input schema:
285	```json
286	{
287	"type": "object",
288	"required": ["id"],
289	"properties": {
290	"id": {"type": "integer", "description": "The funnel ID to trash."}
291	}
292	}
293	```
294	- Output schema:
295	```json
296	{
297	"type": "object",
298	"properties": {
299	"success": {"type": "boolean"},
300	"message": {"type": "string"}
301	}
302	}
303	```
304	- Permission: `cartflows_manage_flows_steps`
305	- Meta annotations:
306	- priority: 2.0
307	- readOnlyHint: false
308	- destructiveHint: false
309	- idempotentHint: true
310	- openWorldHint: false
311	- mcp.type: tool
312
313	---
314
315	### CF-F-08: cartflows/restore-flow
316
317	- Label: Restore funnel from trash
318	- Description: Restores a trashed CartFlows funnel and all its steps. Use to undo a trash operation.
319	- Category: cartflows
320	- Ability category type: Lifecycle
321	- Input schema:
322	```json
323	{
324	"type": "object",
325	"required": ["id"],
326	"properties": {
327	"id": {"type": "integer", "description": "The funnel ID to restore."}
328	}
329	}
330	```
331	- Output schema:
332	```json
333	{
334	"type": "object",
335	"properties": {
336	"success": {"type": "boolean"},
337	"message": {"type": "string"}
338	}
339	}
340	```
341	- Permission: `cartflows_manage_flows_steps`
342	- Meta annotations:
343	- priority: 2.0
344	- readOnlyHint: false
345	- destructiveHint: false
346	- idempotentHint: true
347	- openWorldHint: false
348	- mcp.type: tool
349
350	---
351
352	### CF-F-09: cartflows/delete-flow
353
354	- Label: Permanently delete funnel
355	- Description: Permanently deletes a CartFlows funnel and all its steps. This action CANNOT be undone. Prefer trash-flow unless permanent deletion is explicitly needed.
356	- Category: cartflows
357	- Ability category type: CRUD (Delete)
358	- Input schema:
359	```json
360	{
361	"type": "object",
362	"required": ["id"],
363	"properties": {
364	"id": {"type": "integer", "description": "The funnel ID to permanently delete."}
365	}
366	}
367	```
368	- Output schema:
369	```json
370	{
371	"type": "object",
372	"properties": {
373	"success": {"type": "boolean"},
374	"message": {"type": "string"}
375	}
376	}
377	```
378	- Permission: `cartflows_manage_flows_steps` + option gate
379	- Meta annotations:
380	- priority: 3.0
381	- readOnlyHint: false
382	- destructiveHint: true
383	- idempotentHint: false
384	- openWorldHint: false
385	- mcp.type: tool
386
387	---
388
389	### CF-F-10: cartflows/reorder-flow-steps
390
391	- Label: Reorder funnel steps
392	- Description: Changes the order of steps within a CartFlows funnel. Provide the full ordered list of step IDs.
393	- Category: cartflows
394	- Ability category type: Relationships
395	- Input schema:
396	```json
397	{
398	"type": "object",
399	"required": ["flow_id", "step_ids"],
400	"properties": {
401	"flow_id": {"type": "integer", "description": "The funnel ID."},
402	"step_ids": {"type": "array", "items": {"type": "integer"}, "description": "Ordered array of step IDs."}
403	}
404	}
405	```
406	- Output schema:
407	```json
408	{
409	"type": "object",
410	"properties": {
411	"success": {"type": "boolean"},
412	"steps": {"type": "array", "description": "Updated steps in new order."}
413	}
414	}
415	```
416	- Permission: `cartflows_manage_flows_steps`
417	- Meta annotations:
418	- priority: 2.0
419	- readOnlyHint: false
420	- destructiveHint: false
421	- idempotentHint: true
422	- openWorldHint: false
423	- mcp.type: tool
424
425	---
426
427	### CF-F-11: cartflows/export-flow
428
429	- Label: Export funnel data
430	- Description: Exports one or more CartFlows funnels as a JSON payload, including all steps and settings. Used for migration or backup.
431	- Category: cartflows
432	- Ability category type: Output/Embedding
433	- Input schema:
434	```json
435	{
436	"type": "object",
437	"required": ["flow_ids"],
438	"properties": {
439	"flow_ids": {"type": "array", "items": {"type": "integer"}, "description": "Array of funnel IDs to export."}
440	}
441	}
442	```
443	- Output schema:
444	```json
445	{
446	"type": "object",
447	"properties": {
448	"success": {"type": "boolean"},
449	"flows": {"type": "string", "description": "JSON-encoded array of funnel export data."}
450	}
451	}
452	```
453	- Permission: `cartflows_manage_flows_steps`
454	- Meta annotations:
455	- priority: 1.0
456	- readOnlyHint: true
457	- destructiveHint: false
458	- idempotentHint: true
459	- openWorldHint: false
460	- mcp.type: tool
461
462	---
463
464	## Step Module Abilities (mined from admin-core/ajax/steps.php and admin-core/api/step-data.php)
465
466	### CF-S-01: cartflows/get-step
467
468	- Label: Get step
469	- Description: Returns full data for a single CartFlows step by ID, including type, settings, options, and page builder edit link.
470	- Category: cartflows
471	- Ability category type: CRUD (Read)
472	- Input schema:
473	```json
474	{
475	"type": "object",
476	"required": ["id"],
477	"properties": {
478	"id": {"type": "integer", "description": "The step ID."}
479	}
480	}
481	```
482	- Output schema:
483	```json
484	{
485	"type": "object",
486	"properties": {
487	"id": {"type": "integer"},
488	"title": {"type": "string"},
489	"type": {"type": "string", "enum": ["checkout","thankyou","optin","landing"], "description": "Step type."},
490	"flow_title": {"type": "string"},
491	"view": {"type": "string", "format": "uri", "description": "Frontend permalink."},
492	"edit": {"type": "string", "format": "uri", "description": "WP admin edit link."},
493	"page_builder_edit": {"type": "string", "format": "uri", "description": "Page builder edit link."},
494	"options": {"type": "object", "description": "Step meta options."},
495	"settings_data": {"type": "object", "description": "Step settings."}
496	}
497	}
498	```
499	- Permission: `cartflows_manage_flows_steps`
500	- Meta annotations:
501	- priority: 1.0
502	- readOnlyHint: true
503	- destructiveHint: false
504	- idempotentHint: true
505	- openWorldHint: false
506	- mcp.type: resource
507
508	---
509
510	### CF-S-02: cartflows/clone-step
511
512	- Label: Clone step
513	- Description: Creates a duplicate of a CartFlows step within the same funnel, copying all settings and content.
514	- Category: cartflows
515	- Ability category type: Lifecycle
516	- Input schema:
517	```json
518	{
519	"type": "object",
520	"required": ["flow_id", "step_id"],
521	"properties": {
522	"flow_id": {"type": "integer", "description": "The funnel ID."},
523	"step_id": {"type": "integer", "description": "The step ID to clone."}
524	}
525	}
526	```
527	- Output schema:
528	```json
529	{
530	"type": "object",
531	"properties": {
532	"success": {"type": "boolean"},
533	"message": {"type": "string"},
534	"new_step_id": {"type": "integer", "description": "ID of the cloned step."}
535	}
536	}
537	```
538	- Permission: `cartflows_manage_flows_steps`
539	- Meta annotations:
540	- priority: 2.0
541	- readOnlyHint: false
542	- destructiveHint: false
543	- idempotentHint: false
544	- openWorldHint: false
545	- mcp.type: tool
546
547	---
548
549	### CF-S-03: cartflows/delete-step
550
551	- Label: Permanently delete step
552	- Description: Permanently deletes a step from a CartFlows funnel. Cannot be undone.
553	- Category: cartflows
554	- Ability category type: CRUD (Delete)
555	- Input schema:
556	```json
557	{
558	"type": "object",
559	"required": ["flow_id", "step_id"],
560	"properties": {
561	"flow_id": {"type": "integer", "description": "The funnel ID."},
562	"step_id": {"type": "integer", "description": "The step ID to delete."}
563	}
564	}
565	```
566	- Output schema:
567	```json
568	{
569	"type": "object",
570	"properties": {
571	"success": {"type": "boolean"},
572	"message": {"type": "string"}
573	}
574	}
575	```
576	- Permission: `cartflows_manage_flows_steps` + option gate
577	- Meta annotations:
578	- priority: 3.0
579	- readOnlyHint: false
580	- destructiveHint: true
581	- idempotentHint: false
582	- openWorldHint: false
583	- mcp.type: tool
584
585	---
586
587	### CF-S-04: cartflows/update-step-title
588
589	- Label: Update step title
590	- Description: Renames a CartFlows step.
591	- Category: cartflows
592	- Ability category type: CRUD (Update)
593	- Input schema:
594	```json
595	{
596	"type": "object",
597	"required": ["step_id", "title"],
598	"properties": {
599	"step_id": {"type": "integer", "description": "The step ID."},
600	"title": {"type": "string", "description": "New step title."}
601	}
602	}
603	```
604	- Output schema:
605	```json
606	{
607	"type": "object",
608	"properties": {
609	"success": {"type": "boolean"},
610	"message": {"type": "string"}
611	}
612	}
613	```
614	- Permission: `cartflows_manage_flows_steps`
615	- Meta annotations:
616	- priority: 2.0
617	- readOnlyHint: false
618	- destructiveHint: false
619	- idempotentHint: true
620	- openWorldHint: false
621	- mcp.type: tool
622
623	---
624
625	## Analytics Module Abilities (from admin-core/ajax/flows-stats.php)
626
627	### CF-A-01: cartflows/get-flow-stats
628
629	- Label: Get funnel analytics
630	- Description: Returns revenue and order analytics for CartFlows funnels within a date range. Optionally filter by a specific funnel. Requires WooCommerce. Returns totals, orders by date, revenue by date, and recent orders.
631	- Category: cartflows
632	- Ability category type: Analytics/Stats
633	- Input schema:
634	```json
635	{
636	"type": "object",
637	"properties": {
638	"date_from": {"type": "string", "format": "date", "description": "Start date (YYYY-MM-DD)."},
639	"date_to": {"type": "string", "format": "date", "description": "End date (YYYY-MM-DD)."},
640	"flow_id": {"type": "integer", "description": "Filter by funnel ID. 0 = all funnels.", "default": 0}
641	}
642	}
643	```
644	- Output schema:
645	```json
646	{
647	"type": "object",
648	"properties": {
649	"flow_stats": {"type": "object", "description": "Earnings totals, orders by date, revenue by date."},
650	"recent_orders": {"type": "array", "items": {"type": "object", "properties": {
651	"order_id": {"type": "integer"},
652	"customer_name": {"type": "string"},
653	"customer_email": {"type": "string", "format": "email"},
654	"order_total": {"type": "string"},
655	"order_status": {"type": "string"},
656	"order_date": {"type": "string"}
657	}}}
658	}
659	}
660	```
661	- Permission: `cartflows_manage_flows_steps`
662	- Meta annotations:
663	- priority: 1.0
664	- readOnlyHint: true
665	- destructiveHint: false
666	- idempotentHint: true
667	- openWorldHint: false
668	- mcp.type: resource
669
670	---
671
672	## Abilities NOT Mined (excluded rationale)
673
674	\| Operation \| Reason excluded \|
675	\|-----------\|----------------\|
676	\| `save_flow_meta_settings` \| Too complex/broad input (serialized form fields); scope too wide for a clean ability \|
677	\| `save_meta_settings` (step) \| Same — broad serialized form post data; not AI-constructible cleanly \|
678	\| `trash_flows_in_bulk` \| Covered by `trash-flow` with a loop; separate bulk ability has limited AI utility \|
679	\| `update_flow_post_status` (bulk) \| Similar to bulk trash \|
680	\| `delete_flows_permanently` (bulk) \| Destructive bulk; high risk, low incremental value over single delete \|
681	\| `export_flows_in_bulk` \| Folded into `export-flow` which accepts array of IDs \|
682	\| `hide_instant_checkout_notice` \| UI-only operation, not useful for AI agents \|
683	\| `update_store_checkout_status` \| Pro-adjacent, settings-level toggle \|
684	\| `json_search_products` \| Too narrow; covered by WooCommerce abilities \|
685	\| `json_search_coupons` \| Same \|
686	\| `save_global_settings` \| Too broad; serialized form data \|
687
688	---
689
690	## Phase 1 Status: COMPLETE
691