'; - printf( - esc_html( 'Data Machine requires PHP %2$s or higher. You are running PHP %1$s.' ), - esc_html( PHP_VERSION ), - '8.0' - ); - echo '
'; - printf( - esc_html( 'Data Machine requires WordPress %2$s or higher. You are running WordPress %1$s.' ), - esc_html( $current_wp_version ), - '6.9' - ); - echo '
'; - echo esc_html( 'Data Machine: Composer dependencies are missing. Please run "composer install" or contact Chubes to report a bug.' ); - echo '
'; + printf( + esc_html( 'Data Machine requires PHP %2$s or higher. You are running PHP %1$s.' ), + esc_html( PHP_VERSION ), + '8.0' + ); + echo '
'; + printf( + esc_html( 'Data Machine requires WordPress %2$s or higher. You are running WordPress %1$s.' ), + esc_html( $current_wp_version ), + '6.9' + ); + echo '
'; + echo esc_html( 'Data Machine: Composer dependencies are missing. Please run "composer install" or contact Chubes to report a bug.' ); + echo '
" . wp_kses_post( $content ) . "
\n"; $insertion_point = ''; - $block_index = count( $current_blocks ); + $block_index = count( $current_blocks ); - switch ( $position ) { - case 'beginning': - $new_content = $block_content . "\n\n" . $current_content; - $insertion_point = 'at the beginning of the post'; - $block_index = 0; - break; + switch ( $position ) { + case 'beginning': + $new_content = $block_content . "\n\n" . $current_content; + $insertion_point = 'at the beginning of the post'; + $block_index = 0; + break; - case 'end': - $new_content = $current_content . $block_content; - $insertion_point = 'at the end of the post'; - $block_index = count( $current_blocks ); - break; + case 'end': + $new_content = $current_content . $block_content; + $insertion_point = 'at the end of the post'; + $block_index = count( $current_blocks ); + break; case 'after_paragraph': $result = self::insert_after_paragraph( $current_content, $block_content, $target_paragraph_text ); if ( ! $result['success'] ) { return $result; - } + } $new_content = $result['content']; $insertion_point = $result['insertion_point']; $block_index = (int) ( $result['block_index'] ?? count( $current_blocks ) ); - break; + break; default: return array( @@ -241,12 +241,12 @@ public static function execute( array $input ): array { } return array( - 'success' => true, - 'post_id' => $post_id, - 'post_url' => get_permalink( $post_id ), - 'position' => $position, - 'insertion_point'=> $insertion_point, - 'new_content' => $new_content, + 'success' => true, + 'post_id' => $post_id, + 'post_url' => get_permalink( $post_id ), + 'position' => $position, + 'insertion_point' => $insertion_point, + 'new_content' => $new_content, ); } @@ -268,14 +268,14 @@ public static function execute( array $input ): array { ), ), 'editor' => array( - 'toolCallId' => $input['_original_call_id'] ?? '', - 'editType' => 'content', - 'searchPattern' => '', - 'caseSensitive' => false, - 'isPreview' => true, - 'previewBlockContent'=> $block_content, + 'toolCallId' => $input['_original_call_id'] ?? '', + 'editType' => 'content', + 'searchPattern' => '', + 'caseSensitive' => false, + 'isPreview' => true, + 'previewBlockContent' => $block_content, 'originalBlockContent' => '', - 'originalBlockType' => 'core/paragraph', + 'originalBlockType' => 'core/paragraph', ), ) ); diff --git a/inc/Abilities/Content/ReplacePostBlocksAbility.php b/inc/Abilities/Content/ReplacePostBlocksAbility.php index 1e0fb75cd..0631703ab 100644 --- a/inc/Abilities/Content/ReplacePostBlocksAbility.php +++ b/inc/Abilities/Content/ReplacePostBlocksAbility.php @@ -46,27 +46,27 @@ private function registerAbility(): void { 'description' => __( 'Post ID to edit', 'data-machine' ), ), 'replacements' => array( - 'type' => 'array', - 'description' => __( 'Array of block replacement operations', 'data-machine' ), - 'items' => array( - 'type' => 'object', - 'required' => array( 'block_index', 'new_content' ), - 'properties' => array( - 'block_index' => array( - 'type' => 'integer', - 'description' => __( 'Zero-based block index to replace', 'data-machine' ), - ), - 'new_content' => array( - 'type' => 'string', - 'description' => __( 'New innerHTML for the block', 'data-machine' ), + 'type' => 'array', + 'description' => __( 'Array of block replacement operations', 'data-machine' ), + 'items' => array( + 'type' => 'object', + 'required' => array( 'block_index', 'new_content' ), + 'properties' => array( + 'block_index' => array( + 'type' => 'integer', + 'description' => __( 'Zero-based block index to replace', 'data-machine' ), + ), + 'new_content' => array( + 'type' => 'string', + 'description' => __( 'New innerHTML for the block', 'data-machine' ), + ), ), ), ), - ), - 'preview' => array( - 'type' => 'boolean', - 'description' => __( 'When true, return diff preview without applying changes', 'data-machine' ), - ), + 'preview' => array( + 'type' => 'boolean', + 'description' => __( 'When true, return diff preview without applying changes', 'data-machine' ), + ), ), ), 'output_schema' => array( diff --git a/inc/Abilities/Email/EmailAbilities.php b/inc/Abilities/Email/EmailAbilities.php index 3cb952d89..281fcac6b 100644 --- a/inc/Abilities/Email/EmailAbilities.php +++ b/inc/Abilities/Email/EmailAbilities.php @@ -20,1271 +20,4 @@ class EmailAbilities { private static bool $registered = false; - - public function __construct() { - if ( ! class_exists( 'WP_Ability' ) ) { - return; - } - - if ( self::$registered ) { - return; - } - - $this->registerAbilities(); - self::$registered = true; - } - - private function registerAbilities(): void { - $register_callback = function () { - // Reply to an email. - wp_register_ability( - 'datamachine/email-reply', - array( - 'label' => __( 'Reply to Email', 'data-machine' ), - 'description' => __( 'Send a reply to an email, maintaining thread headers', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'to', 'subject', 'body', 'in_reply_to' ), - 'properties' => array( - 'to' => array( - 'type' => 'string', - 'description' => __( 'Recipient email address', 'data-machine' ), - ), - 'subject' => array( - 'type' => 'string', - 'description' => __( 'Reply subject (typically Re: original subject)', 'data-machine' ), - ), - 'body' => array( - 'type' => 'string', - 'description' => __( 'Reply body content', 'data-machine' ), - ), - 'in_reply_to' => array( - 'type' => 'string', - 'description' => __( 'Message-ID of the email being replied to', 'data-machine' ), - ), - 'references' => array( - 'type' => 'string', - 'default' => '', - 'description' => __( 'References header chain for threading', 'data-machine' ), - ), - 'cc' => array( - 'type' => 'string', - 'default' => '', - ), - 'content_type' => array( - 'type' => 'string', - 'default' => 'text/html', - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'message' => array( 'type' => 'string' ), - 'error' => array( 'type' => 'string' ), - 'logs' => array( 'type' => 'array' ), - ), - ), - 'execute_callback' => array( $this, 'executeReply' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - - // Delete an email via IMAP. - wp_register_ability( - 'datamachine/email-delete', - array( - 'label' => __( 'Delete Email', 'data-machine' ), - 'description' => __( 'Delete (expunge) an email by UID from the IMAP server', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'uid' ), - 'properties' => array( - 'uid' => array( - 'type' => 'integer', - 'description' => __( 'Message UID to delete', 'data-machine' ), - ), - 'folder' => array( - 'type' => 'string', - 'default' => 'INBOX', - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'message' => array( 'type' => 'string' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeDelete' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - - // Move an email to a different folder. - wp_register_ability( - 'datamachine/email-move', - array( - 'label' => __( 'Move Email', 'data-machine' ), - 'description' => __( 'Move an email to a different IMAP folder', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'uid', 'destination' ), - 'properties' => array( - 'uid' => array( - 'type' => 'integer', - 'description' => __( 'Message UID to move', 'data-machine' ), - ), - 'destination' => array( - 'type' => 'string', - 'description' => __( 'Target folder (e.g., Archive, Trash, [Gmail]/All Mail)', 'data-machine' ), - ), - 'folder' => array( - 'type' => 'string', - 'default' => 'INBOX', - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'message' => array( 'type' => 'string' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeMove' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - - // Flag/unflag an email. - wp_register_ability( - 'datamachine/email-flag', - array( - 'label' => __( 'Flag Email', 'data-machine' ), - 'description' => __( 'Set or clear IMAP flags on an email (Seen, Flagged, etc.)', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'uid', 'flag' ), - 'properties' => array( - 'uid' => array( - 'type' => 'integer', - 'description' => __( 'Message UID', 'data-machine' ), - ), - 'flag' => array( - 'type' => 'string', - 'description' => __( 'IMAP flag: Seen, Flagged, Answered, Deleted, Draft', 'data-machine' ), - ), - 'action' => array( - 'type' => 'string', - 'default' => 'set', - 'description' => __( 'set or clear the flag', 'data-machine' ), - ), - 'folder' => array( - 'type' => 'string', - 'default' => 'INBOX', - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'message' => array( 'type' => 'string' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeFlag' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - - // Batch move: search → move all matches. - wp_register_ability( - 'datamachine/email-batch-move', - array( - 'label' => __( 'Batch Move Emails', 'data-machine' ), - 'description' => __( 'Move all emails matching a search to a destination folder', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'search', 'destination' ), - 'properties' => array( - 'search' => array( - 'type' => 'string', - 'description' => __( 'IMAP search criteria (e.g., FROM "github.com")', 'data-machine' ), - ), - 'destination' => array( - 'type' => 'string', - 'description' => __( 'Target folder (e.g., [Gmail]/GitHub, Archive)', 'data-machine' ), - ), - 'folder' => array( - 'type' => 'string', - 'default' => 'INBOX', - ), - 'max' => array( - 'type' => 'integer', - 'default' => 500, - 'description' => __( 'Maximum messages to move (safety limit)', 'data-machine' ), - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'message' => array( 'type' => 'string' ), - 'moved_count' => array( 'type' => 'integer' ), - 'total_matches' => array( 'type' => 'integer' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeBatchMove' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - - // Batch flag: search → flag/unflag all matches. - wp_register_ability( - 'datamachine/email-batch-flag', - array( - 'label' => __( 'Batch Flag Emails', 'data-machine' ), - 'description' => __( 'Set or clear a flag on all emails matching a search', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'search', 'flag' ), - 'properties' => array( - 'search' => array( - 'type' => 'string', - 'description' => __( 'IMAP search criteria', 'data-machine' ), - ), - 'flag' => array( - 'type' => 'string', - 'description' => __( 'Flag: Seen, Flagged, Answered, Deleted, Draft', 'data-machine' ), - ), - 'action' => array( - 'type' => 'string', - 'default' => 'set', - 'description' => __( 'set or clear', 'data-machine' ), - ), - 'folder' => array( - 'type' => 'string', - 'default' => 'INBOX', - ), - 'max' => array( - 'type' => 'integer', - 'default' => 500, - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'message' => array( 'type' => 'string' ), - 'flagged_count' => array( 'type' => 'integer' ), - 'total_matches' => array( 'type' => 'integer' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeBatchFlag' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - - // Batch delete: search → delete all matches. - wp_register_ability( - 'datamachine/email-batch-delete', - array( - 'label' => __( 'Batch Delete Emails', 'data-machine' ), - 'description' => __( 'Delete all emails matching a search', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'search' ), - 'properties' => array( - 'search' => array( - 'type' => 'string', - 'description' => __( 'IMAP search criteria', 'data-machine' ), - ), - 'folder' => array( - 'type' => 'string', - 'default' => 'INBOX', - ), - 'max' => array( - 'type' => 'integer', - 'default' => 100, - 'description' => __( 'Maximum messages to delete (safety limit, lower default)', 'data-machine' ), - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'message' => array( 'type' => 'string' ), - 'deleted_count' => array( 'type' => 'integer' ), - 'total_matches' => array( 'type' => 'integer' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeBatchDelete' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - - // Unsubscribe from a mailing list. - wp_register_ability( - 'datamachine/email-unsubscribe', - array( - 'label' => __( 'Unsubscribe from Email', 'data-machine' ), - 'description' => __( 'Unsubscribe from a mailing list using List-Unsubscribe headers', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'uid' ), - 'properties' => array( - 'uid' => array( - 'type' => 'integer', - 'description' => __( 'Message UID to unsubscribe from', 'data-machine' ), - ), - 'folder' => array( - 'type' => 'string', - 'default' => 'INBOX', - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'message' => array( 'type' => 'string' ), - 'method' => array( 'type' => 'string' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeUnsubscribe' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - - // Batch unsubscribe from all matching senders. - wp_register_ability( - 'datamachine/email-batch-unsubscribe', - array( - 'label' => __( 'Batch Unsubscribe', 'data-machine' ), - 'description' => __( 'Unsubscribe from all mailing lists matching a search', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'search' ), - 'properties' => array( - 'search' => array( - 'type' => 'string', - 'description' => __( 'IMAP search criteria', 'data-machine' ), - ), - 'folder' => array( - 'type' => 'string', - 'default' => 'INBOX', - ), - 'max' => array( - 'type' => 'integer', - 'default' => 20, - 'description' => __( 'Max unique senders to unsubscribe from (deduped by sender)', 'data-machine' ), - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'message' => array( 'type' => 'string' ), - 'results' => array( 'type' => 'array' ), - 'unsubscribed' => array( 'type' => 'integer' ), - 'failed' => array( 'type' => 'integer' ), - 'no_header' => array( 'type' => 'integer' ), - ), - ), - 'execute_callback' => array( $this, 'executeBatchUnsubscribe' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - - // Test IMAP connection. - wp_register_ability( - 'datamachine/email-test-connection', - array( - 'label' => __( 'Test Email Connection', 'data-machine' ), - 'description' => __( 'Test IMAP connection with stored credentials', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'properties' => new \stdClass(), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'message' => array( 'type' => 'string' ), - 'mailbox_info' => array( 'type' => 'object' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeTestConnection' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - }; - - if ( doing_action( 'wp_abilities_api_init' ) ) { - $register_callback(); - } elseif ( ! did_action( 'wp_abilities_api_init' ) ) { - add_action( 'wp_abilities_api_init', $register_callback ); - } - } - - public function checkPermission(): bool { - return PermissionHelper::can_manage(); - } - - /** - * Reply to an email with threading headers. - */ - public function executeReply( array $input ): array { - $headers = array(); - - $content_type = $input['content_type'] ?? 'text/html'; - $headers[] = "Content-Type: {$content_type}; charset=UTF-8"; - - // Threading headers. - if ( ! empty( $input['in_reply_to'] ) ) { - $headers[] = 'In-Reply-To: ' . $input['in_reply_to']; - } - - $references = $input['references'] ?? ''; - if ( ! empty( $input['in_reply_to'] ) ) { - $references = trim( $references . ' ' . $input['in_reply_to'] ); - } - if ( ! empty( $references ) ) { - $headers[] = 'References: ' . $references; - } - - if ( ! empty( $input['cc'] ) ) { - $cc_list = array_map( 'trim', explode( ',', $input['cc'] ) ); - foreach ( $cc_list as $cc ) { - if ( is_email( $cc ) ) { - $headers[] = 'Cc: ' . $cc; - } - } - } - - $to = array_map( 'trim', explode( ',', $input['to'] ) ); - $to = array_filter( $to, 'is_email' ); - - if ( empty( $to ) ) { - return array( - 'success' => false, - 'error' => 'No valid recipient address', - ); - } - - $sent = wp_mail( $to, $input['subject'], $input['body'], $headers ); - - if ( $sent ) { - return array( - 'success' => true, - 'message' => 'Reply sent to ' . implode( ', ', $to ), - 'logs' => array(), - ); - } - - global $phpmailer; - $error = 'wp_mail() returned false'; - if ( isset( $phpmailer ) && $phpmailer instanceof \PHPMailer\PHPMailer\PHPMailer ) { - $error = $phpmailer->ErrorInfo ?: $error; - } - - return array( - 'success' => false, - 'error' => $error, - ); - } - - /** - * Delete an email from the IMAP server. - */ - public function executeDelete( array $input ): array { - $connection = $this->connect( $input['folder'] ?? 'INBOX' ); - if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { - return $connection; - } - - $uid = (int) $input['uid']; - imap_delete( $connection, (string) $uid, FT_UID ); - imap_expunge( $connection ); - imap_close( $connection ); - - return array( - 'success' => true, - 'message' => sprintf( 'Message UID %d deleted', $uid ), - ); - } - - /** - * Move an email to a different folder. - */ - public function executeMove( array $input ): array { - $connection = $this->connect( $input['folder'] ?? 'INBOX' ); - if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { - return $connection; - } - - $uid = (int) $input['uid']; - $destination = $input['destination']; - - $moved = imap_mail_move( $connection, (string) $uid, $destination, CP_UID ); - if ( ! $moved ) { - $error = imap_last_error(); - imap_close( $connection ); - return array( - 'success' => false, - 'error' => 'Move failed: ' . $error, - ); - } - - imap_expunge( $connection ); - imap_close( $connection ); - - return array( - 'success' => true, - 'message' => sprintf( 'Message UID %d moved to %s', $uid, $destination ), - ); - } - - /** - * Set or clear a flag on an email. - */ - public function executeFlag( array $input ): array { - $connection = $this->connect( $input['folder'] ?? 'INBOX' ); - if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { - return $connection; - } - - $uid = (int) $input['uid']; - $flag = '\\' . ucfirst( strtolower( $input['flag'] ) ); - - $valid_flags = array( '\\Seen', '\\Flagged', '\\Answered', '\\Deleted', '\\Draft' ); - if ( ! in_array( $flag, $valid_flags, true ) ) { - imap_close( $connection ); - return array( - 'success' => false, - 'error' => 'Invalid flag. Valid flags: Seen, Flagged, Answered, Deleted, Draft', - ); - } - - $action = $input['action'] ?? 'set'; - if ( 'clear' === $action ) { - $result = imap_clearflag_full( $connection, (string) $uid, $flag, ST_UID ); - } else { - $result = imap_setflag_full( $connection, (string) $uid, $flag, ST_UID ); - } - - imap_close( $connection ); - - if ( ! $result ) { - return array( - 'success' => false, - 'error' => 'Failed to ' . $action . ' flag ' . $flag, - ); - } - - return array( - 'success' => true, - 'message' => sprintf( 'Flag %s %s on UID %d', $flag, $action === 'clear' ? 'cleared' : 'set', $uid ), - ); - } - - /** - * Test the IMAP connection with stored credentials. - */ - public function executeTestConnection( array $input ): array { - if ( ! function_exists( 'imap_open' ) ) { - return array( - 'success' => false, - 'error' => 'PHP IMAP extension is not installed', - ); - } - - $auth = $this->getAuthProvider(); - if ( ! $auth || ! $auth->is_authenticated() ) { - return array( - 'success' => false, - 'error' => 'IMAP credentials not configured', - ); - } - - $mailbox = $this->buildMailboxString( - $auth->getHost(), - $auth->getPort(), - $auth->getEncryption(), - 'INBOX' - ); - - // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged - $connection = @imap_open( $mailbox, $auth->getUser(), $auth->getPassword() ); - - if ( false === $connection ) { - return array( - 'success' => false, - 'error' => 'Connection failed: ' . imap_last_error(), - ); - } - - $check = imap_check( $connection ); - $info = array( - 'mailbox' => $check->Mailbox ?? '', - 'messages' => $check->Nmsgs ?? 0, - 'recent' => $check->Recent ?? 0, - 'connected' => true, - ); - - // List available folders. - $folders = imap_list( $connection, $this->buildMailboxString( $auth->getHost(), $auth->getPort(), $auth->getEncryption(), '' ), '*' ); - $folder_list = array(); - if ( is_array( $folders ) ) { - $prefix = $this->buildMailboxString( $auth->getHost(), $auth->getPort(), $auth->getEncryption(), '' ); - foreach ( $folders as $folder ) { - $folder_list[] = str_replace( $prefix, '', imap_utf7_decode( $folder ) ); - } - } - $info['folders'] = $folder_list; - - imap_close( $connection ); - - return array( - 'success' => true, - 'message' => sprintf( 'Connected to %s — %d messages in INBOX', $auth->getHost(), $info['messages'] ), - 'mailbox_info' => $info, - ); - } - - /** - * Unsubscribe from a mailing list using List-Unsubscribe headers. - * - * Priority order: - * 1. List-Unsubscribe-Post + URL → HTTP POST (RFC 8058 one-click) - * 2. URL without Post header → HTTP POST attempt, fall back to GET - * 3. mailto: → send email via wp_mail() - */ - public function executeUnsubscribe( array $input ): array { - $connection = $this->connect( $input['folder'] ?? 'INBOX' ); - if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { - return $connection; - } - - $uid = (int) $input['uid']; - - // Fetch raw headers. - $raw_headers = imap_fetchheader( $connection, $uid, FT_UID ); - if ( empty( $raw_headers ) ) { - imap_close( $connection ); - return array( - 'success' => false, - 'error' => 'Could not fetch message headers', - ); - } - - $parsed = $this->parseUnsubscribeHeaders( $raw_headers ); - imap_close( $connection ); - - if ( empty( $parsed['urls'] ) && empty( $parsed['mailto'] ) ) { - return array( - 'success' => false, - 'error' => 'No List-Unsubscribe header found in this message', - ); - } - - // Try One-Click POST first (RFC 8058). - if ( $parsed['has_one_click'] && ! empty( $parsed['urls'] ) ) { - $url = $parsed['urls'][0]; - $result = $this->executeOneClickUnsubscribe( $url ); - if ( $result['success'] ) { - return $result; - } - // Fall through to other methods if POST failed. - } - - // Try URL GET/POST. - if ( ! empty( $parsed['urls'] ) ) { - foreach ( $parsed['urls'] as $url ) { - $result = $this->executeUrlUnsubscribe( $url ); - if ( $result['success'] ) { - return $result; - } - } - } - - // Try mailto. - if ( ! empty( $parsed['mailto'] ) ) { - $result = $this->executeMailtoUnsubscribe( $parsed['mailto'] ); - if ( $result['success'] ) { - return $result; - } - } - - return array( - 'success' => false, - 'error' => 'All unsubscribe methods failed', - ); - } - - /** - * Batch unsubscribe: search → unsubscribe from unique senders. - * - * Deduplicates by sender — if you have 100 emails from linkedin.com, - * it only unsubscribes once using the most recent message's headers. - */ - public function executeBatchUnsubscribe( array $input ): array { - $connection = $this->connect( $input['folder'] ?? 'INBOX' ); - if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { - return $connection; - } - - $search = $input['search']; - $max = (int) ( $input['max'] ?? 20 ); - - $uids = imap_search( $connection, $search, SE_UID ); - if ( false === $uids || empty( $uids ) ) { - imap_close( $connection ); - return array( - 'success' => true, - 'message' => 'No messages matching search criteria', - 'results' => array(), - 'unsubscribed' => 0, - 'failed' => 0, - 'no_header' => 0, - ); - } - - // Most recent first — we want the newest unsubscribe link per sender. - $uids = array_reverse( $uids ); - - // Deduplicate by sender — one unsubscribe per unique From address. - $seen_senders = array(); - $to_process = array(); - - foreach ( $uids as $uid ) { - if ( count( $to_process ) >= $max ) { - break; - } - - $msgno = imap_msgno( $connection, $uid ); - if ( 0 === $msgno ) { - continue; - } - - $header = imap_headerinfo( $connection, $msgno ); - if ( false === $header || empty( $header->from ) ) { - continue; - } - - $from = $header->from[0]; - $sender = $from->mailbox . '@' . $from->host; - - if ( isset( $seen_senders[ $sender ] ) ) { - continue; - } - - $seen_senders[ $sender ] = true; - - // Fetch unsubscribe headers. - $raw = imap_fetchheader( $connection, $uid, FT_UID ); - $parsed = $this->parseUnsubscribeHeaders( $raw ); - - $to_process[] = array( - 'uid' => $uid, - 'sender' => $sender, - 'parsed' => $parsed, - ); - } - - imap_close( $connection ); - - // Now execute unsubscribes (connection closed — these are HTTP/mailto). - $results = array(); - $unsubscribed = 0; - $failed = 0; - $no_header = 0; - - foreach ( $to_process as $item ) { - $parsed = $item['parsed']; - - if ( empty( $parsed['urls'] ) && empty( $parsed['mailto'] ) ) { - $results[] = array( - 'sender' => $item['sender'], - 'success' => false, - 'reason' => 'no List-Unsubscribe header', - ); - ++$no_header; - continue; - } - - $result = null; - - // Try One-Click POST first. - if ( $parsed['has_one_click'] && ! empty( $parsed['urls'] ) ) { - $result = $this->executeOneClickUnsubscribe( $parsed['urls'][0] ); - } - - // Fall back to URL. - if ( ( ! $result || ! $result['success'] ) && ! empty( $parsed['urls'] ) ) { - $result = $this->executeUrlUnsubscribe( $parsed['urls'][0] ); - } - - // Fall back to mailto. - if ( ( ! $result || ! $result['success'] ) && ! empty( $parsed['mailto'] ) ) { - $result = $this->executeMailtoUnsubscribe( $parsed['mailto'] ); - } - - if ( $result && $result['success'] ) { - $results[] = array( - 'sender' => $item['sender'], - 'success' => true, - 'method' => $result['method'] ?? 'unknown', - ); - ++$unsubscribed; - } else { - $results[] = array( - 'sender' => $item['sender'], - 'success' => false, - 'reason' => $result['error'] ?? 'all methods failed', - ); - ++$failed; - } - } - - return array( - 'success' => true, - 'message' => sprintf( - 'Processed %d senders: %d unsubscribed, %d failed, %d had no header', - count( $to_process ), - $unsubscribed, - $failed, - $no_header - ), - 'results' => $results, - 'unsubscribed' => $unsubscribed, - 'failed' => $failed, - 'no_header' => $no_header, - ); - } - - /** - * Parse List-Unsubscribe and List-Unsubscribe-Post headers. - * - * @param string $raw_headers Raw email headers. - * @return array Parsed data with urls, mailto, has_one_click. - */ - private function parseUnsubscribeHeaders( string $raw_headers ): array { - $unsub_header = ''; - $post_header = ''; - $collecting = ''; - - foreach ( explode( "\n", $raw_headers ) as $line ) { - // Continuation line. - if ( $collecting && preg_match( '/^\s/', $line ) ) { - if ( 'unsub' === $collecting ) { - $unsub_header .= ' ' . trim( $line ); - } - if ( 'post' === $collecting ) { - $post_header .= ' ' . trim( $line ); - } - continue; - } - $collecting = ''; - - if ( stripos( $line, 'List-Unsubscribe:' ) === 0 ) { - $unsub_header = trim( substr( $line, 17 ) ); - $collecting = 'unsub'; - } - if ( stripos( $line, 'List-Unsubscribe-Post:' ) === 0 ) { - $post_header = trim( substr( $line, 22 ) ); - $collecting = 'post'; - } - } - - // Decode MIME-encoded headers. - if ( ! empty( $unsub_header ) ) { - $unsub_header = imap_utf8( $unsub_header ); - } - - // Extract URLs and mailto from angle brackets. - $urls = array(); - $mailto = ''; - - if ( preg_match_all( '/<([^>]+)>/', $unsub_header, $matches ) ) { - foreach ( $matches[1] as $value ) { - if ( strpos( $value, 'mailto:' ) === 0 ) { - $mailto = $value; - } elseif ( filter_var( $value, FILTER_VALIDATE_URL ) ) { - $urls[] = $value; - } - } - } - - $has_one_click = stripos( $post_header, 'List-Unsubscribe=One-Click' ) !== false; - - return array( - 'urls' => $urls, - 'mailto' => $mailto, - 'has_one_click' => $has_one_click, - 'raw' => $unsub_header, - ); - } - - /** - * RFC 8058 One-Click unsubscribe via HTTP POST. - */ - private function executeOneClickUnsubscribe( string $url ): array { - $response = wp_remote_post( $url, array( - 'body' => 'List-Unsubscribe=One-Click', - 'headers' => array( 'Content-Type' => 'application/x-www-form-urlencoded' ), - 'timeout' => 15, - ) ); - - if ( is_wp_error( $response ) ) { - return array( - 'success' => false, - 'error' => 'POST failed: ' . $response->get_error_message(), - ); - } - - $code = wp_remote_retrieve_response_code( $response ); - - // 2xx = success. Some return 200, others 204. - if ( $code >= 200 && $code < 300 ) { - return array( - 'success' => true, - 'message' => 'Unsubscribed via One-Click POST (HTTP ' . $code . ')', - 'method' => 'one-click-post', - ); - } - - return array( - 'success' => false, - 'error' => 'One-Click POST returned HTTP ' . $code, - ); - } - - /** - * Unsubscribe via URL (GET request). - */ - private function executeUrlUnsubscribe( string $url ): array { - $response = wp_remote_get( $url, array( - 'timeout' => 15, - 'sslverify' => true, - ) ); - - if ( is_wp_error( $response ) ) { - return array( - 'success' => false, - 'error' => 'GET failed: ' . $response->get_error_message(), - ); - } - - $code = wp_remote_retrieve_response_code( $response ); - - if ( $code >= 200 && $code < 400 ) { - return array( - 'success' => true, - 'message' => 'Unsubscribe request sent (HTTP ' . $code . ')', - 'method' => 'url-get', - ); - } - - return array( - 'success' => false, - 'error' => 'URL request returned HTTP ' . $code, - ); - } - - /** - * Unsubscribe via mailto: — send an email. - */ - private function executeMailtoUnsubscribe( string $mailto_uri ): array { - // Parse mailto:address?subject=... - $parts = wp_parse_url( $mailto_uri ); - $address = str_replace( 'mailto:', '', $parts['path'] ?? '' ); - - if ( empty( $address ) || ! is_email( $address ) ) { - return array( - 'success' => false, - 'error' => 'Invalid mailto address: ' . $mailto_uri, - ); - } - - $subject = ''; - if ( ! empty( $parts['query'] ) ) { - parse_str( $parts['query'], $query ); - $subject = $query['subject'] ?? 'unsubscribe'; - } - if ( empty( $subject ) ) { - $subject = 'unsubscribe'; - } - - $sent = wp_mail( $address, $subject, 'unsubscribe' ); - - if ( $sent ) { - return array( - 'success' => true, - 'message' => 'Unsubscribe email sent to ' . $address, - 'method' => 'mailto', - ); - } - - return array( - 'success' => false, - 'error' => 'Failed to send unsubscribe email', - ); - } - - /** - * Batch move: search → move all matches to destination. - */ - public function executeBatchMove( array $input ): array { - $connection = $this->connect( $input['folder'] ?? 'INBOX' ); - if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { - return $connection; - } - - $search = $input['search']; - $destination = $input['destination']; - $max = (int) ( $input['max'] ?? 500 ); - - $uids = imap_search( $connection, $search, SE_UID ); - if ( false === $uids || empty( $uids ) ) { - imap_close( $connection ); - return array( - 'success' => true, - 'message' => 'No messages matching search criteria', - 'moved_count' => 0, - 'total_matches' => 0, - ); - } - - $total = count( $uids ); - $to_move = array_slice( $uids, 0, $max ); - $moved = 0; - - // Use comma-separated UID range for batch operation (much faster than per-message). - $uid_set = implode( ',', $to_move ); - $result = imap_mail_move( $connection, $uid_set, $destination, CP_UID ); - - if ( $result ) { - $moved = count( $to_move ); - imap_expunge( $connection ); - } - - imap_close( $connection ); - - $message = sprintf( 'Moved %d messages to %s', $moved, $destination ); - if ( $total > $max ) { - $message .= sprintf( ' (%d more remain — run again to continue)', $total - $max ); - } - - return array( - 'success' => true, - 'message' => $message, - 'moved_count' => $moved, - 'total_matches' => $total, - ); - } - - /** - * Batch flag: search → set/clear flag on all matches. - */ - public function executeBatchFlag( array $input ): array { - $connection = $this->connect( $input['folder'] ?? 'INBOX' ); - if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { - return $connection; - } - - $search = $input['search']; - $flag = '\\' . ucfirst( strtolower( $input['flag'] ) ); - $action = $input['action'] ?? 'set'; - $max = (int) ( $input['max'] ?? 500 ); - - $valid_flags = array( '\\Seen', '\\Flagged', '\\Answered', '\\Deleted', '\\Draft' ); - if ( ! in_array( $flag, $valid_flags, true ) ) { - imap_close( $connection ); - return array( - 'success' => false, - 'error' => 'Invalid flag. Valid: Seen, Flagged, Answered, Deleted, Draft', - ); - } - - $uids = imap_search( $connection, $search, SE_UID ); - if ( false === $uids || empty( $uids ) ) { - imap_close( $connection ); - return array( - 'success' => true, - 'message' => 'No messages matching search criteria', - 'flagged_count' => 0, - 'total_matches' => 0, - ); - } - - $total = count( $uids ); - $to_flag = array_slice( $uids, 0, $max ); - $uid_set = implode( ',', $to_flag ); - - if ( 'clear' === $action ) { - imap_clearflag_full( $connection, $uid_set, $flag, ST_UID ); - } else { - imap_setflag_full( $connection, $uid_set, $flag, ST_UID ); - } - - imap_close( $connection ); - - $verb = 'clear' === $action ? 'cleared' : 'set'; - $message = sprintf( '%s %s on %d messages', ucfirst( $verb ), $flag, count( $to_flag ) ); - if ( $total > $max ) { - $message .= sprintf( ' (%d more remain)', $total - $max ); - } - - return array( - 'success' => true, - 'message' => $message, - 'flagged_count' => count( $to_flag ), - 'total_matches' => $total, - ); - } - - /** - * Batch delete: search → delete all matches. - */ - public function executeBatchDelete( array $input ): array { - $connection = $this->connect( $input['folder'] ?? 'INBOX' ); - if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { - return $connection; - } - - $search = $input['search']; - $max = (int) ( $input['max'] ?? 100 ); - - $uids = imap_search( $connection, $search, SE_UID ); - if ( false === $uids || empty( $uids ) ) { - imap_close( $connection ); - return array( - 'success' => true, - 'message' => 'No messages matching search criteria', - 'deleted_count' => 0, - 'total_matches' => 0, - ); - } - - $total = count( $uids ); - $to_delete = array_slice( $uids, 0, $max ); - $uid_set = implode( ',', $to_delete ); - - imap_delete( $connection, $uid_set, FT_UID ); - imap_expunge( $connection ); - imap_close( $connection ); - - $message = sprintf( 'Deleted %d messages', count( $to_delete ) ); - if ( $total > $max ) { - $message .= sprintf( ' (%d more remain — run again to continue)', $total - $max ); - } - - return array( - 'success' => true, - 'message' => $message, - 'deleted_count' => count( $to_delete ), - 'total_matches' => $total, - ); - } - - /** - * Open an IMAP connection using stored credentials. - * - * @param string $folder Mail folder. - * @return resource|array IMAP connection or error array. - */ - private function connect( string $folder = 'INBOX' ) { - if ( ! function_exists( 'imap_open' ) ) { - return array( - 'success' => false, - 'error' => 'PHP IMAP extension is not installed', - ); - } - - $auth = $this->getAuthProvider(); - if ( ! $auth || ! $auth->is_authenticated() ) { - return array( - 'success' => false, - 'error' => 'IMAP credentials not configured', - ); - } - - $mailbox = $this->buildMailboxString( - $auth->getHost(), - $auth->getPort(), - $auth->getEncryption(), - $folder - ); - - // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged - $connection = @imap_open( $mailbox, $auth->getUser(), $auth->getPassword() ); - - if ( false === $connection ) { - return array( - 'success' => false, - 'error' => 'IMAP connection failed: ' . imap_last_error(), - ); - } - - return $connection; - } - - /** - * Get the IMAP auth provider. - * - * @return \DataMachine\Core\Steps\Fetch\Handlers\Email\EmailAuth|null - */ - private function getAuthProvider(): ?object { - $providers = apply_filters( 'datamachine_auth_providers', array() ); - return $providers['email_imap'] ?? null; - } - - /** - * Build IMAP mailbox connection string. - */ - private function buildMailboxString( string $host, int $port, string $encryption, string $folder ): string { - $flags = match ( $encryption ) { - 'ssl' => '/imap/ssl/validate-cert', - 'tls' => '/imap/tls/validate-cert', - default => '/imap/notls', - }; - - return sprintf( '{%s:%d%s}%s', $host, $port, $flags, $folder ); - } } diff --git a/inc/Abilities/Email/EmailAbilities/connect.php b/inc/Abilities/Email/EmailAbilities/connect.php new file mode 100644 index 000000000..551a7ffdc --- /dev/null +++ b/inc/Abilities/Email/EmailAbilities/connect.php @@ -0,0 +1,381 @@ +//! connect — extracted from EmailAbilities.php. + + + /** + * Delete an email from the IMAP server. + */ + public function executeDelete( array $input ): array { + $connection = $this->connect( $input['folder'] ?? 'INBOX' ); + if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { + return $connection; + } + + $uid = (int) $input['uid']; + imap_delete( $connection, (string) $uid, FT_UID ); + imap_expunge( $connection ); + imap_close( $connection ); + + return array( + 'success' => true, + 'message' => sprintf( 'Message UID %d deleted', $uid ), + ); + } + + /** + * Move an email to a different folder. + */ + public function executeMove( array $input ): array { + $connection = $this->connect( $input['folder'] ?? 'INBOX' ); + if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { + return $connection; + } + + $uid = (int) $input['uid']; + $destination = $input['destination']; + + $moved = imap_mail_move( $connection, (string) $uid, $destination, CP_UID ); + if ( ! $moved ) { + $error = imap_last_error(); + imap_close( $connection ); + return array( + 'success' => false, + 'error' => 'Move failed: ' . $error, + ); + } + + imap_expunge( $connection ); + imap_close( $connection ); + + return array( + 'success' => true, + 'message' => sprintf( 'Message UID %d moved to %s', $uid, $destination ), + ); + } + + /** + * Set or clear a flag on an email. + */ + public function executeFlag( array $input ): array { + $connection = $this->connect( $input['folder'] ?? 'INBOX' ); + if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { + return $connection; + } + + $uid = (int) $input['uid']; + $flag = '\\' . ucfirst( strtolower( $input['flag'] ) ); + + $valid_flags = array( '\\Seen', '\\Flagged', '\\Answered', '\\Deleted', '\\Draft' ); + if ( ! in_array( $flag, $valid_flags, true ) ) { + imap_close( $connection ); + return array( + 'success' => false, + 'error' => 'Invalid flag. Valid flags: Seen, Flagged, Answered, Deleted, Draft', + ); + } + + $action = $input['action'] ?? 'set'; + if ( 'clear' === $action ) { + $result = imap_clearflag_full( $connection, (string) $uid, $flag, ST_UID ); + } else { + $result = imap_setflag_full( $connection, (string) $uid, $flag, ST_UID ); + } + + imap_close( $connection ); + + if ( ! $result ) { + return array( + 'success' => false, + 'error' => 'Failed to ' . $action . ' flag ' . $flag, + ); + } + + return array( + 'success' => true, + 'message' => sprintf( 'Flag %s %s on UID %d', $flag, $action === 'clear' ? 'cleared' : 'set', $uid ), + ); + } + + /** + * Test the IMAP connection with stored credentials. + */ + public function executeTestConnection( array $input ): array { + if ( ! function_exists( 'imap_open' ) ) { + return array( + 'success' => false, + 'error' => 'PHP IMAP extension is not installed', + ); + } + + $auth = $this->getAuthProvider(); + if ( ! $auth || ! $auth->is_authenticated() ) { + return array( + 'success' => false, + 'error' => 'IMAP credentials not configured', + ); + } + + $mailbox = $this->buildMailboxString( + $auth->getHost(), + $auth->getPort(), + $auth->getEncryption(), + 'INBOX' + ); + + // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged + $connection = @imap_open( $mailbox, $auth->getUser(), $auth->getPassword() ); + + if ( false === $connection ) { + return array( + 'success' => false, + 'error' => 'Connection failed: ' . imap_last_error(), + ); + } + + $check = imap_check( $connection ); + $info = array( + 'mailbox' => $check->Mailbox ?? '', + 'messages' => $check->Nmsgs ?? 0, + 'recent' => $check->Recent ?? 0, + 'connected' => true, + ); + + // List available folders. + $folders = imap_list( $connection, $this->buildMailboxString( $auth->getHost(), $auth->getPort(), $auth->getEncryption(), '' ), '*' ); + $folder_list = array(); + if ( is_array( $folders ) ) { + $prefix = $this->buildMailboxString( $auth->getHost(), $auth->getPort(), $auth->getEncryption(), '' ); + foreach ( $folders as $folder ) { + $folder_list[] = str_replace( $prefix, '', imap_utf7_decode( $folder ) ); + } + } + $info['folders'] = $folder_list; + + imap_close( $connection ); + + return array( + 'success' => true, + 'message' => sprintf( 'Connected to %s — %d messages in INBOX', $auth->getHost(), $info['messages'] ), + 'mailbox_info' => $info, + ); + } + + /** + * Batch move: search → move all matches to destination. + */ + public function executeBatchMove( array $input ): array { + $connection = $this->connect( $input['folder'] ?? 'INBOX' ); + if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { + return $connection; + } + + $search = $input['search']; + $destination = $input['destination']; + $max = (int) ( $input['max'] ?? 500 ); + + $uids = imap_search( $connection, $search, SE_UID ); + if ( false === $uids || empty( $uids ) ) { + imap_close( $connection ); + return array( + 'success' => true, + 'message' => 'No messages matching search criteria', + 'moved_count' => 0, + 'total_matches' => 0, + ); + } + + $total = count( $uids ); + $to_move = array_slice( $uids, 0, $max ); + $moved = 0; + + // Use comma-separated UID range for batch operation (much faster than per-message). + $uid_set = implode( ',', $to_move ); + $result = imap_mail_move( $connection, $uid_set, $destination, CP_UID ); + + if ( $result ) { + $moved = count( $to_move ); + imap_expunge( $connection ); + } + + imap_close( $connection ); + + $message = sprintf( 'Moved %d messages to %s', $moved, $destination ); + if ( $total > $max ) { + $message .= sprintf( ' (%d more remain — run again to continue)', $total - $max ); + } + + return array( + 'success' => true, + 'message' => $message, + 'moved_count' => $moved, + 'total_matches' => $total, + ); + } + + /** + * Batch flag: search → set/clear flag on all matches. + */ + public function executeBatchFlag( array $input ): array { + $connection = $this->connect( $input['folder'] ?? 'INBOX' ); + if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { + return $connection; + } + + $search = $input['search']; + $flag = '\\' . ucfirst( strtolower( $input['flag'] ) ); + $action = $input['action'] ?? 'set'; + $max = (int) ( $input['max'] ?? 500 ); + + $valid_flags = array( '\\Seen', '\\Flagged', '\\Answered', '\\Deleted', '\\Draft' ); + if ( ! in_array( $flag, $valid_flags, true ) ) { + imap_close( $connection ); + return array( + 'success' => false, + 'error' => 'Invalid flag. Valid: Seen, Flagged, Answered, Deleted, Draft', + ); + } + + $uids = imap_search( $connection, $search, SE_UID ); + if ( false === $uids || empty( $uids ) ) { + imap_close( $connection ); + return array( + 'success' => true, + 'message' => 'No messages matching search criteria', + 'flagged_count' => 0, + 'total_matches' => 0, + ); + } + + $total = count( $uids ); + $to_flag = array_slice( $uids, 0, $max ); + $uid_set = implode( ',', $to_flag ); + + if ( 'clear' === $action ) { + imap_clearflag_full( $connection, $uid_set, $flag, ST_UID ); + } else { + imap_setflag_full( $connection, $uid_set, $flag, ST_UID ); + } + + imap_close( $connection ); + + $verb = 'clear' === $action ? 'cleared' : 'set'; + $message = sprintf( '%s %s on %d messages', ucfirst( $verb ), $flag, count( $to_flag ) ); + if ( $total > $max ) { + $message .= sprintf( ' (%d more remain)', $total - $max ); + } + + return array( + 'success' => true, + 'message' => $message, + 'flagged_count' => count( $to_flag ), + 'total_matches' => $total, + ); + } + + /** + * Batch delete: search → delete all matches. + */ + public function executeBatchDelete( array $input ): array { + $connection = $this->connect( $input['folder'] ?? 'INBOX' ); + if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { + return $connection; + } + + $search = $input['search']; + $max = (int) ( $input['max'] ?? 100 ); + + $uids = imap_search( $connection, $search, SE_UID ); + if ( false === $uids || empty( $uids ) ) { + imap_close( $connection ); + return array( + 'success' => true, + 'message' => 'No messages matching search criteria', + 'deleted_count' => 0, + 'total_matches' => 0, + ); + } + + $total = count( $uids ); + $to_delete = array_slice( $uids, 0, $max ); + $uid_set = implode( ',', $to_delete ); + + imap_delete( $connection, $uid_set, FT_UID ); + imap_expunge( $connection ); + imap_close( $connection ); + + $message = sprintf( 'Deleted %d messages', count( $to_delete ) ); + if ( $total > $max ) { + $message .= sprintf( ' (%d more remain — run again to continue)', $total - $max ); + } + + return array( + 'success' => true, + 'message' => $message, + 'deleted_count' => count( $to_delete ), + 'total_matches' => $total, + ); + } + + /** + * Open an IMAP connection using stored credentials. + * + * @param string $folder Mail folder. + * @return resource|array IMAP connection or error array. + */ + private function connect( string $folder = 'INBOX' ) { + if ( ! function_exists( 'imap_open' ) ) { + return array( + 'success' => false, + 'error' => 'PHP IMAP extension is not installed', + ); + } + + $auth = $this->getAuthProvider(); + if ( ! $auth || ! $auth->is_authenticated() ) { + return array( + 'success' => false, + 'error' => 'IMAP credentials not configured', + ); + } + + $mailbox = $this->buildMailboxString( + $auth->getHost(), + $auth->getPort(), + $auth->getEncryption(), + $folder + ); + + // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged + $connection = @imap_open( $mailbox, $auth->getUser(), $auth->getPassword() ); + + if ( false === $connection ) { + return array( + 'success' => false, + 'error' => 'IMAP connection failed: ' . imap_last_error(), + ); + } + + return $connection; + } + + /** + * Get the IMAP auth provider. + * + * @return \DataMachine\Core\Steps\Fetch\Handlers\Email\EmailAuth|null + */ + private function getAuthProvider(): ?object { + $providers = apply_filters( 'datamachine_auth_providers', array() ); + return $providers['email_imap'] ?? null; + } + + /** + * Build IMAP mailbox connection string. + */ + private function buildMailboxString( string $host, int $port, string $encryption, string $folder ): string { + $flags = match ( $encryption ) { + 'ssl' => '/imap/ssl/validate-cert', + 'tls' => '/imap/tls/validate-cert', + default => '/imap/notls', + }; + + return sprintf( '{%s:%d%s}%s', $host, $port, $flags, $folder ); + } diff --git a/inc/Abilities/Email/EmailAbilities/helpers.php b/inc/Abilities/Email/EmailAbilities/helpers.php new file mode 100644 index 000000000..2a82744fc --- /dev/null +++ b/inc/Abilities/Email/EmailAbilities/helpers.php @@ -0,0 +1,890 @@ +//! helpers — extracted from EmailAbilities.php. + + + public function __construct() { + if ( ! class_exists( 'WP_Ability' ) ) { + return; + } + + if ( self::$registered ) { + return; + } + + $this->registerAbilities(); + self::$registered = true; + } + + private function registerAbilities(): void { + $register_callback = function () { + // Reply to an email. + wp_register_ability( + 'datamachine/email-reply', + array( + 'label' => __( 'Reply to Email', 'data-machine' ), + 'description' => __( 'Send a reply to an email, maintaining thread headers', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'to', 'subject', 'body', 'in_reply_to' ), + 'properties' => array( + 'to' => array( + 'type' => 'string', + 'description' => __( 'Recipient email address', 'data-machine' ), + ), + 'subject' => array( + 'type' => 'string', + 'description' => __( 'Reply subject (typically Re: original subject)', 'data-machine' ), + ), + 'body' => array( + 'type' => 'string', + 'description' => __( 'Reply body content', 'data-machine' ), + ), + 'in_reply_to' => array( + 'type' => 'string', + 'description' => __( 'Message-ID of the email being replied to', 'data-machine' ), + ), + 'references' => array( + 'type' => 'string', + 'default' => '', + 'description' => __( 'References header chain for threading', 'data-machine' ), + ), + 'cc' => array( + 'type' => 'string', + 'default' => '', + ), + 'content_type' => array( + 'type' => 'string', + 'default' => 'text/html', + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'message' => array( 'type' => 'string' ), + 'error' => array( 'type' => 'string' ), + 'logs' => array( 'type' => 'array' ), + ), + ), + 'execute_callback' => array( $this, 'executeReply' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + + // Delete an email via IMAP. + wp_register_ability( + 'datamachine/email-delete', + array( + 'label' => __( 'Delete Email', 'data-machine' ), + 'description' => __( 'Delete (expunge) an email by UID from the IMAP server', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'uid' ), + 'properties' => array( + 'uid' => array( + 'type' => 'integer', + 'description' => __( 'Message UID to delete', 'data-machine' ), + ), + 'folder' => array( + 'type' => 'string', + 'default' => 'INBOX', + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'message' => array( 'type' => 'string' ), + 'error' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeDelete' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + + // Move an email to a different folder. + wp_register_ability( + 'datamachine/email-move', + array( + 'label' => __( 'Move Email', 'data-machine' ), + 'description' => __( 'Move an email to a different IMAP folder', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'uid', 'destination' ), + 'properties' => array( + 'uid' => array( + 'type' => 'integer', + 'description' => __( 'Message UID to move', 'data-machine' ), + ), + 'destination' => array( + 'type' => 'string', + 'description' => __( 'Target folder (e.g., Archive, Trash, [Gmail]/All Mail)', 'data-machine' ), + ), + 'folder' => array( + 'type' => 'string', + 'default' => 'INBOX', + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'message' => array( 'type' => 'string' ), + 'error' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeMove' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + + // Flag/unflag an email. + wp_register_ability( + 'datamachine/email-flag', + array( + 'label' => __( 'Flag Email', 'data-machine' ), + 'description' => __( 'Set or clear IMAP flags on an email (Seen, Flagged, etc.)', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'uid', 'flag' ), + 'properties' => array( + 'uid' => array( + 'type' => 'integer', + 'description' => __( 'Message UID', 'data-machine' ), + ), + 'flag' => array( + 'type' => 'string', + 'description' => __( 'IMAP flag: Seen, Flagged, Answered, Deleted, Draft', 'data-machine' ), + ), + 'action' => array( + 'type' => 'string', + 'default' => 'set', + 'description' => __( 'set or clear the flag', 'data-machine' ), + ), + 'folder' => array( + 'type' => 'string', + 'default' => 'INBOX', + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'message' => array( 'type' => 'string' ), + 'error' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeFlag' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + + // Batch move: search → move all matches. + wp_register_ability( + 'datamachine/email-batch-move', + array( + 'label' => __( 'Batch Move Emails', 'data-machine' ), + 'description' => __( 'Move all emails matching a search to a destination folder', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'search', 'destination' ), + 'properties' => array( + 'search' => array( + 'type' => 'string', + 'description' => __( 'IMAP search criteria (e.g., FROM "github.com")', 'data-machine' ), + ), + 'destination' => array( + 'type' => 'string', + 'description' => __( 'Target folder (e.g., [Gmail]/GitHub, Archive)', 'data-machine' ), + ), + 'folder' => array( + 'type' => 'string', + 'default' => 'INBOX', + ), + 'max' => array( + 'type' => 'integer', + 'default' => 500, + 'description' => __( 'Maximum messages to move (safety limit)', 'data-machine' ), + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'message' => array( 'type' => 'string' ), + 'moved_count' => array( 'type' => 'integer' ), + 'total_matches' => array( 'type' => 'integer' ), + 'error' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeBatchMove' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + + // Batch flag: search → flag/unflag all matches. + wp_register_ability( + 'datamachine/email-batch-flag', + array( + 'label' => __( 'Batch Flag Emails', 'data-machine' ), + 'description' => __( 'Set or clear a flag on all emails matching a search', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'search', 'flag' ), + 'properties' => array( + 'search' => array( + 'type' => 'string', + 'description' => __( 'IMAP search criteria', 'data-machine' ), + ), + 'flag' => array( + 'type' => 'string', + 'description' => __( 'Flag: Seen, Flagged, Answered, Deleted, Draft', 'data-machine' ), + ), + 'action' => array( + 'type' => 'string', + 'default' => 'set', + 'description' => __( 'set or clear', 'data-machine' ), + ), + 'folder' => array( + 'type' => 'string', + 'default' => 'INBOX', + ), + 'max' => array( + 'type' => 'integer', + 'default' => 500, + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'message' => array( 'type' => 'string' ), + 'flagged_count' => array( 'type' => 'integer' ), + 'total_matches' => array( 'type' => 'integer' ), + 'error' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeBatchFlag' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + + // Batch delete: search → delete all matches. + wp_register_ability( + 'datamachine/email-batch-delete', + array( + 'label' => __( 'Batch Delete Emails', 'data-machine' ), + 'description' => __( 'Delete all emails matching a search', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'search' ), + 'properties' => array( + 'search' => array( + 'type' => 'string', + 'description' => __( 'IMAP search criteria', 'data-machine' ), + ), + 'folder' => array( + 'type' => 'string', + 'default' => 'INBOX', + ), + 'max' => array( + 'type' => 'integer', + 'default' => 100, + 'description' => __( 'Maximum messages to delete (safety limit, lower default)', 'data-machine' ), + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'message' => array( 'type' => 'string' ), + 'deleted_count' => array( 'type' => 'integer' ), + 'total_matches' => array( 'type' => 'integer' ), + 'error' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeBatchDelete' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + + // Unsubscribe from a mailing list. + wp_register_ability( + 'datamachine/email-unsubscribe', + array( + 'label' => __( 'Unsubscribe from Email', 'data-machine' ), + 'description' => __( 'Unsubscribe from a mailing list using List-Unsubscribe headers', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'uid' ), + 'properties' => array( + 'uid' => array( + 'type' => 'integer', + 'description' => __( 'Message UID to unsubscribe from', 'data-machine' ), + ), + 'folder' => array( + 'type' => 'string', + 'default' => 'INBOX', + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'message' => array( 'type' => 'string' ), + 'method' => array( 'type' => 'string' ), + 'error' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeUnsubscribe' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + + // Batch unsubscribe from all matching senders. + wp_register_ability( + 'datamachine/email-batch-unsubscribe', + array( + 'label' => __( 'Batch Unsubscribe', 'data-machine' ), + 'description' => __( 'Unsubscribe from all mailing lists matching a search', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'search' ), + 'properties' => array( + 'search' => array( + 'type' => 'string', + 'description' => __( 'IMAP search criteria', 'data-machine' ), + ), + 'folder' => array( + 'type' => 'string', + 'default' => 'INBOX', + ), + 'max' => array( + 'type' => 'integer', + 'default' => 20, + 'description' => __( 'Max unique senders to unsubscribe from (deduped by sender)', 'data-machine' ), + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'message' => array( 'type' => 'string' ), + 'results' => array( 'type' => 'array' ), + 'unsubscribed' => array( 'type' => 'integer' ), + 'failed' => array( 'type' => 'integer' ), + 'no_header' => array( 'type' => 'integer' ), + ), + ), + 'execute_callback' => array( $this, 'executeBatchUnsubscribe' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + + // Test IMAP connection. + wp_register_ability( + 'datamachine/email-test-connection', + array( + 'label' => __( 'Test Email Connection', 'data-machine' ), + 'description' => __( 'Test IMAP connection with stored credentials', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'properties' => new \stdClass(), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'message' => array( 'type' => 'string' ), + 'mailbox_info' => array( 'type' => 'object' ), + 'error' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeTestConnection' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + }; + + if ( doing_action( 'wp_abilities_api_init' ) ) { + $register_callback(); + } elseif ( ! did_action( 'wp_abilities_api_init' ) ) { + add_action( 'wp_abilities_api_init', $register_callback ); + } + } + + public function checkPermission(): bool { + return PermissionHelper::can_manage(); + } + + /** + * Reply to an email with threading headers. + */ + public function executeReply( array $input ): array { + $headers = array(); + + $content_type = $input['content_type'] ?? 'text/html'; + $headers[] = "Content-Type: {$content_type}; charset=UTF-8"; + + // Threading headers. + if ( ! empty( $input['in_reply_to'] ) ) { + $headers[] = 'In-Reply-To: ' . $input['in_reply_to']; + } + + $references = $input['references'] ?? ''; + if ( ! empty( $input['in_reply_to'] ) ) { + $references = trim( $references . ' ' . $input['in_reply_to'] ); + } + if ( ! empty( $references ) ) { + $headers[] = 'References: ' . $references; + } + + if ( ! empty( $input['cc'] ) ) { + $cc_list = array_map( 'trim', explode( ',', $input['cc'] ) ); + foreach ( $cc_list as $cc ) { + if ( is_email( $cc ) ) { + $headers[] = 'Cc: ' . $cc; + } + } + } + + $to = array_map( 'trim', explode( ',', $input['to'] ) ); + $to = array_filter( $to, 'is_email' ); + + if ( empty( $to ) ) { + return array( + 'success' => false, + 'error' => 'No valid recipient address', + ); + } + + $sent = wp_mail( $to, $input['subject'], $input['body'], $headers ); + + if ( $sent ) { + return array( + 'success' => true, + 'message' => 'Reply sent to ' . implode( ', ', $to ), + 'logs' => array(), + ); + } + + global $phpmailer; + $error = 'wp_mail() returned false'; + if ( isset( $phpmailer ) && $phpmailer instanceof \PHPMailer\PHPMailer\PHPMailer ) { + $error = $phpmailer->ErrorInfo ?: $error; + } + + return array( + 'success' => false, + 'error' => $error, + ); + } + + /** + * Unsubscribe from a mailing list using List-Unsubscribe headers. + * + * Priority order: + * 1. List-Unsubscribe-Post + URL → HTTP POST (RFC 8058 one-click) + * 2. URL without Post header → HTTP POST attempt, fall back to GET + * 3. mailto: → send email via wp_mail() + */ + public function executeUnsubscribe( array $input ): array { + $connection = $this->connect( $input['folder'] ?? 'INBOX' ); + if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { + return $connection; + } + + $uid = (int) $input['uid']; + + // Fetch raw headers. + $raw_headers = imap_fetchheader( $connection, $uid, FT_UID ); + if ( empty( $raw_headers ) ) { + imap_close( $connection ); + return array( + 'success' => false, + 'error' => 'Could not fetch message headers', + ); + } + + $parsed = $this->parseUnsubscribeHeaders( $raw_headers ); + imap_close( $connection ); + + if ( empty( $parsed['urls'] ) && empty( $parsed['mailto'] ) ) { + return array( + 'success' => false, + 'error' => 'No List-Unsubscribe header found in this message', + ); + } + + // Try One-Click POST first (RFC 8058). + if ( $parsed['has_one_click'] && ! empty( $parsed['urls'] ) ) { + $url = $parsed['urls'][0]; + $result = $this->executeOneClickUnsubscribe( $url ); + if ( $result['success'] ) { + return $result; + } + // Fall through to other methods if POST failed. + } + + // Try URL GET/POST. + if ( ! empty( $parsed['urls'] ) ) { + foreach ( $parsed['urls'] as $url ) { + $result = $this->executeUrlUnsubscribe( $url ); + if ( $result['success'] ) { + return $result; + } + } + } + + // Try mailto. + if ( ! empty( $parsed['mailto'] ) ) { + $result = $this->executeMailtoUnsubscribe( $parsed['mailto'] ); + if ( $result['success'] ) { + return $result; + } + } + + return array( + 'success' => false, + 'error' => 'All unsubscribe methods failed', + ); + } + + /** + * Batch unsubscribe: search → unsubscribe from unique senders. + * + * Deduplicates by sender — if you have 100 emails from linkedin.com, + * it only unsubscribes once using the most recent message's headers. + */ + public function executeBatchUnsubscribe( array $input ): array { + $connection = $this->connect( $input['folder'] ?? 'INBOX' ); + if ( is_array( $connection ) && ! ( $connection['success'] ?? true ) ) { + return $connection; + } + + $search = $input['search']; + $max = (int) ( $input['max'] ?? 20 ); + + $uids = imap_search( $connection, $search, SE_UID ); + if ( false === $uids || empty( $uids ) ) { + imap_close( $connection ); + return array( + 'success' => true, + 'message' => 'No messages matching search criteria', + 'results' => array(), + 'unsubscribed' => 0, + 'failed' => 0, + 'no_header' => 0, + ); + } + + // Most recent first — we want the newest unsubscribe link per sender. + $uids = array_reverse( $uids ); + + // Deduplicate by sender — one unsubscribe per unique From address. + $seen_senders = array(); + $to_process = array(); + + foreach ( $uids as $uid ) { + if ( count( $to_process ) >= $max ) { + break; + } + + $msgno = imap_msgno( $connection, $uid ); + if ( 0 === $msgno ) { + continue; + } + + $header = imap_headerinfo( $connection, $msgno ); + if ( false === $header || empty( $header->from ) ) { + continue; + } + + $from = $header->from[0]; + $sender = $from->mailbox . '@' . $from->host; + + if ( isset( $seen_senders[ $sender ] ) ) { + continue; + } + + $seen_senders[ $sender ] = true; + + // Fetch unsubscribe headers. + $raw = imap_fetchheader( $connection, $uid, FT_UID ); + $parsed = $this->parseUnsubscribeHeaders( $raw ); + + $to_process[] = array( + 'uid' => $uid, + 'sender' => $sender, + 'parsed' => $parsed, + ); + } + + imap_close( $connection ); + + // Now execute unsubscribes (connection closed — these are HTTP/mailto). + $results = array(); + $unsubscribed = 0; + $failed = 0; + $no_header = 0; + + foreach ( $to_process as $item ) { + $parsed = $item['parsed']; + + if ( empty( $parsed['urls'] ) && empty( $parsed['mailto'] ) ) { + $results[] = array( + 'sender' => $item['sender'], + 'success' => false, + 'reason' => 'no List-Unsubscribe header', + ); + ++$no_header; + continue; + } + + $result = null; + + // Try One-Click POST first. + if ( $parsed['has_one_click'] && ! empty( $parsed['urls'] ) ) { + $result = $this->executeOneClickUnsubscribe( $parsed['urls'][0] ); + } + + // Fall back to URL. + if ( ( ! $result || ! $result['success'] ) && ! empty( $parsed['urls'] ) ) { + $result = $this->executeUrlUnsubscribe( $parsed['urls'][0] ); + } + + // Fall back to mailto. + if ( ( ! $result || ! $result['success'] ) && ! empty( $parsed['mailto'] ) ) { + $result = $this->executeMailtoUnsubscribe( $parsed['mailto'] ); + } + + if ( $result && $result['success'] ) { + $results[] = array( + 'sender' => $item['sender'], + 'success' => true, + 'method' => $result['method'] ?? 'unknown', + ); + ++$unsubscribed; + } else { + $results[] = array( + 'sender' => $item['sender'], + 'success' => false, + 'reason' => $result['error'] ?? 'all methods failed', + ); + ++$failed; + } + } + + return array( + 'success' => true, + 'message' => sprintf( + 'Processed %d senders: %d unsubscribed, %d failed, %d had no header', + count( $to_process ), + $unsubscribed, + $failed, + $no_header + ), + 'results' => $results, + 'unsubscribed' => $unsubscribed, + 'failed' => $failed, + 'no_header' => $no_header, + ); + } + + /** + * Parse List-Unsubscribe and List-Unsubscribe-Post headers. + * + * @param string $raw_headers Raw email headers. + * @return array Parsed data with urls, mailto, has_one_click. + */ + private function parseUnsubscribeHeaders( string $raw_headers ): array { + $unsub_header = ''; + $post_header = ''; + $collecting = ''; + + foreach ( explode( "\n", $raw_headers ) as $line ) { + // Continuation line. + if ( $collecting && preg_match( '/^\s/', $line ) ) { + if ( 'unsub' === $collecting ) { + $unsub_header .= ' ' . trim( $line ); + } + if ( 'post' === $collecting ) { + $post_header .= ' ' . trim( $line ); + } + continue; + } + $collecting = ''; + + if ( stripos( $line, 'List-Unsubscribe:' ) === 0 ) { + $unsub_header = trim( substr( $line, 17 ) ); + $collecting = 'unsub'; + } + if ( stripos( $line, 'List-Unsubscribe-Post:' ) === 0 ) { + $post_header = trim( substr( $line, 22 ) ); + $collecting = 'post'; + } + } + + // Decode MIME-encoded headers. + if ( ! empty( $unsub_header ) ) { + $unsub_header = imap_utf8( $unsub_header ); + } + + // Extract URLs and mailto from angle brackets. + $urls = array(); + $mailto = ''; + + if ( preg_match_all( '/<([^>]+)>/', $unsub_header, $matches ) ) { + foreach ( $matches[1] as $value ) { + if ( strpos( $value, 'mailto:' ) === 0 ) { + $mailto = $value; + } elseif ( filter_var( $value, FILTER_VALIDATE_URL ) ) { + $urls[] = $value; + } + } + } + + $has_one_click = stripos( $post_header, 'List-Unsubscribe=One-Click' ) !== false; + + return array( + 'urls' => $urls, + 'mailto' => $mailto, + 'has_one_click' => $has_one_click, + 'raw' => $unsub_header, + ); + } + + /** + * RFC 8058 One-Click unsubscribe via HTTP POST. + */ + private function executeOneClickUnsubscribe( string $url ): array { + $response = wp_remote_post( $url, array( + 'body' => 'List-Unsubscribe=One-Click', + 'headers' => array( 'Content-Type' => 'application/x-www-form-urlencoded' ), + 'timeout' => 15, + ) ); + + if ( is_wp_error( $response ) ) { + return array( + 'success' => false, + 'error' => 'POST failed: ' . $response->get_error_message(), + ); + } + + $code = wp_remote_retrieve_response_code( $response ); + + // 2xx = success. Some return 200, others 204. + if ( $code >= 200 && $code < 300 ) { + return array( + 'success' => true, + 'message' => 'Unsubscribed via One-Click POST (HTTP ' . $code . ')', + 'method' => 'one-click-post', + ); + } + + return array( + 'success' => false, + 'error' => 'One-Click POST returned HTTP ' . $code, + ); + } + + /** + * Unsubscribe via URL (GET request). + */ + private function executeUrlUnsubscribe( string $url ): array { + $response = wp_remote_get( $url, array( + 'timeout' => 15, + 'sslverify' => true, + ) ); + + if ( is_wp_error( $response ) ) { + return array( + 'success' => false, + 'error' => 'GET failed: ' . $response->get_error_message(), + ); + } + + $code = wp_remote_retrieve_response_code( $response ); + + if ( $code >= 200 && $code < 400 ) { + return array( + 'success' => true, + 'message' => 'Unsubscribe request sent (HTTP ' . $code . ')', + 'method' => 'url-get', + ); + } + + return array( + 'success' => false, + 'error' => 'URL request returned HTTP ' . $code, + ); + } + + /** + * Unsubscribe via mailto: — send an email. + */ + private function executeMailtoUnsubscribe( string $mailto_uri ): array { + // Parse mailto:address?subject=... + $parts = wp_parse_url( $mailto_uri ); + $address = str_replace( 'mailto:', '', $parts['path'] ?? '' ); + + if ( empty( $address ) || ! is_email( $address ) ) { + return array( + 'success' => false, + 'error' => 'Invalid mailto address: ' . $mailto_uri, + ); + } + + $subject = ''; + if ( ! empty( $parts['query'] ) ) { + parse_str( $parts['query'], $query ); + $subject = $query['subject'] ?? 'unsubscribe'; + } + if ( empty( $subject ) ) { + $subject = 'unsubscribe'; + } + + $sent = wp_mail( $address, $subject, 'unsubscribe' ); + + if ( $sent ) { + return array( + 'success' => true, + 'message' => 'Unsubscribe email sent to ' . $address, + 'method' => 'mailto', + ); + } + + return array( + 'success' => false, + 'error' => 'Failed to send unsubscribe email', + ); + } diff --git a/inc/Abilities/Engine/ExecuteStepAbility.php b/inc/Abilities/Engine/ExecuteStepAbility.php index 37767fd0d..b1112e28c 100644 --- a/inc/Abilities/Engine/ExecuteStepAbility.php +++ b/inc/Abilities/Engine/ExecuteStepAbility.php @@ -681,7 +681,7 @@ private function markCompletedItemProcessed( int $job_id ): void { 'Deferred mark-as-processed on pipeline completion', array( 'job_id' => $job_id, - 'item_identifier' => $item_identifier, + 'item_identifier' => $item_identifier, 'source_type' => $source_type, 'fetch_flow_step_id' => $fetch_flow_step_id, ) diff --git a/inc/Abilities/Engine/PipelineBatchScheduler.php b/inc/Abilities/Engine/PipelineBatchScheduler.php index 34103a103..eafe2ec40 100644 --- a/inc/Abilities/Engine/PipelineBatchScheduler.php +++ b/inc/Abilities/Engine/PipelineBatchScheduler.php @@ -318,8 +318,8 @@ private function createChildJob( // its last step, ExecuteStepAbility reads these to mark the item as // processed. Previously set by FetchHandler::onItemProcessed() on the // parent, but now the fetch step no longer marks items eagerly. - $item_identifier = $single_packet['metadata']['item_identifier'] ?? null; - $source_type = $single_packet['metadata']['source_type'] ?? null; + $item_identifier = $single_packet['metadata']['item_identifier'] ?? null; + $source_type = $single_packet['metadata']['source_type'] ?? null; if ( ! empty( $item_identifier ) ) { $child_engine['item_identifier'] = $item_identifier; } diff --git a/inc/Abilities/EngineAbilities.php b/inc/Abilities/EngineAbilities.php index 5bd39c997..db004fc82 100644 --- a/inc/Abilities/EngineAbilities.php +++ b/inc/Abilities/EngineAbilities.php @@ -29,6 +29,7 @@ class EngineAbilities { private ScheduleFlowAbility $schedule_flow; public function __construct() { + add_action('wp_abilities_api_init', array( $this, 'abilities_api_init' )); if ( ! class_exists( 'WP_Ability' ) || self::$registered ) { return; } diff --git a/inc/Abilities/Fetch/FetchEmailAbility.php b/inc/Abilities/Fetch/FetchEmailAbility.php index 800e90b23..d3d0fdc05 100644 --- a/inc/Abilities/Fetch/FetchEmailAbility.php +++ b/inc/Abilities/Fetch/FetchEmailAbility.php @@ -19,6 +19,7 @@ namespace DataMachine\Abilities\Fetch; use DataMachine\Abilities\PermissionHelper; +use DataMachine\Abilities\Traits\HasCheckPermission; defined( 'ABSPATH' ) || exit; @@ -118,8 +119,8 @@ private function registerAbilities(): void { 'output_schema' => array( 'type' => 'object', 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'data' => array( + 'success' => array( 'type' => 'boolean' ), + 'data' => array( 'type' => 'object', 'properties' => array( 'items' => array( 'type' => 'array' ), @@ -129,8 +130,8 @@ private function registerAbilities(): void { 'has_more' => array( 'type' => 'boolean' ), ), ), - 'error' => array( 'type' => 'string' ), - 'logs' => array( 'type' => 'array' ), + 'error' => array( 'type' => 'string' ), + 'logs' => array( 'type' => 'array' ), ), ), 'execute_callback' => array( $this, 'execute' ), @@ -225,7 +226,7 @@ public function execute( array $input ): array { 'offset' => 0, 'has_more' => false, ), - 'logs' => $logs, + 'logs' => $logs, ); } @@ -243,7 +244,7 @@ public function execute( array $input ): array { 'offset' => 0, 'has_more' => false, ), - 'logs' => $logs, + 'logs' => $logs, ); } @@ -312,7 +313,7 @@ public function execute( array $input ): array { 'offset' => $offset, 'has_more' => $has_more, ), - 'logs' => $logs, + 'logs' => $logs, ); } @@ -365,7 +366,7 @@ private function fetchHeaders( $connection, int $uid ): ?array { 'metadata' => array( 'uid' => $uid, 'message_id' => $message_id, - 'item_identifier' => $message_id, + 'item_identifier' => $message_id, 'from' => $from_email, 'from_name' => $from_name, 'to' => $to_address, @@ -439,7 +440,7 @@ private function fetchMessage( $connection, int $uid, array $config ): ?array { 'metadata' => array( 'uid' => $uid, 'message_id' => $message_id, - 'item_identifier' => $message_id, + 'item_identifier' => $message_id, 'from' => $from_email, 'from_name' => $from_name, 'to' => $to_address, @@ -536,7 +537,7 @@ private function fetchBody( $connection, int $uid ): string { private function decodeBody( string $body, int $encoding ): string { switch ( $encoding ) { case 3: // BASE64. - return base64_decode( $body, true ) ?: $body; + return base64_decode( $body, true ) ? base64_decode( $body, true ) : $body; case 4: // QUOTED-PRINTABLE. return quoted_printable_decode( $body ); case 1: // 8BIT. diff --git a/inc/Abilities/Fetch/FetchFilesAbility.php b/inc/Abilities/Fetch/FetchFilesAbility.php index d947f4cd5..f78cf4981 100644 --- a/inc/Abilities/Fetch/FetchFilesAbility.php +++ b/inc/Abilities/Fetch/FetchFilesAbility.php @@ -12,6 +12,7 @@ namespace DataMachine\Abilities\Fetch; use DataMachine\Abilities\PermissionHelper; +use DataMachine\Abilities\Traits\HasCheckPermission; defined( 'ABSPATH' ) || exit; @@ -172,12 +173,12 @@ public function execute( array $input ): array { ); $metadata = array( - 'source_type' => 'files', - 'item_identifier' => $file_identifier, - 'original_id' => $file_identifier, - 'original_title' => $file['original_name'], - 'original_date_gmt' => $file['uploaded_at'] ?? gmdate( 'Y-m-d H:i:s' ), - 'source_url' => '', + 'source_type' => 'files', + 'item_identifier' => $file_identifier, + 'original_id' => $file_identifier, + 'original_title' => $file['original_name'], + 'original_date_gmt' => $file['uploaded_at'] ?? gmdate( 'Y-m-d H:i:s' ), + 'source_url' => '', ); if ( $is_image ) { diff --git a/inc/Abilities/Fetch/FetchRssAbility.php b/inc/Abilities/Fetch/FetchRssAbility.php index 13c51f895..dec80cb62 100644 --- a/inc/Abilities/Fetch/FetchRssAbility.php +++ b/inc/Abilities/Fetch/FetchRssAbility.php @@ -11,6 +11,8 @@ namespace DataMachine\Abilities\Fetch; use DataMachine\Abilities\PermissionHelper; +use DataMachine\Abilities\Fetch\Traits\HasApplyKeywordSearch; +use DataMachine\Abilities\Traits\HasCheckPermission; defined( 'ABSPATH' ) || exit; @@ -254,15 +256,15 @@ function ( $error ) { $enclosure_url = $this->extractItemEnclosure( $item ); $metadata = array( - 'source_type' => 'rss', - 'item_identifier' => $guid, - 'original_id' => $guid, - 'original_title' => $title, - 'original_date_gmt' => $pub_date ? gmdate( 'Y-m-d\TH:i:s\Z', strtotime( $pub_date ) ) : null, - 'author' => $author, - 'categories' => $categories, - 'guid' => $guid, - 'source_url' => $link ? $link : '', + 'source_type' => 'rss', + 'item_identifier' => $guid, + 'original_id' => $guid, + 'original_title' => $title, + 'original_date_gmt' => $pub_date ? gmdate( 'Y-m-d\TH:i:s\Z', strtotime( $pub_date ) ) : null, + 'author' => $author, + 'categories' => $categories, + 'guid' => $guid, + 'source_url' => $link ? $link : '', ); $file_info = null; diff --git a/inc/Abilities/Fetch/FetchWordPressApiAbility.php b/inc/Abilities/Fetch/FetchWordPressApiAbility.php index 4feae750f..f1dc25d0a 100644 --- a/inc/Abilities/Fetch/FetchWordPressApiAbility.php +++ b/inc/Abilities/Fetch/FetchWordPressApiAbility.php @@ -12,6 +12,10 @@ namespace DataMachine\Abilities\Fetch; use DataMachine\Abilities\PermissionHelper; +use DataMachine\Abilities\Fetch\Traits\HasApplyKeywordSearch; +use DataMachine\Abilities\Fetch\FetchRssAbility; +use DataMachine\Abilities\Traits\HasCheckPermission; +use DataMachine\Abilities\Fetch\FetchRssAbility; defined( 'ABSPATH' ) || exit; @@ -280,13 +284,13 @@ public function execute( array $input ): array { 'title' => $title, 'content' => wp_strip_all_tags( $content ), 'metadata' => array( - 'source_type' => 'rest_api', - 'item_identifier' => $unique_id, - 'original_id' => $item_id, - 'original_title' => $title, - 'original_date_gmt' => $item_date, - 'site_name' => $site_name, - 'source_url' => $source_link, + 'source_type' => 'rest_api', + 'item_identifier' => $unique_id, + 'original_id' => $item_id, + 'original_title' => $title, + 'original_date_gmt' => $item_date, + 'site_name' => $site_name, + 'source_url' => $source_link, ), ); diff --git a/inc/Abilities/Fetch/FetchWordPressMediaAbility.php b/inc/Abilities/Fetch/FetchWordPressMediaAbility.php index bc430fddd..922cfdd5a 100644 --- a/inc/Abilities/Fetch/FetchWordPressMediaAbility.php +++ b/inc/Abilities/Fetch/FetchWordPressMediaAbility.php @@ -11,6 +11,8 @@ namespace DataMachine\Abilities\Fetch; use DataMachine\Abilities\PermissionHelper; +use DataMachine\Abilities\Fetch\Traits\HasApplyKeywordSearch; +use DataMachine\Abilities\Traits\HasCheckPermission; defined( 'ABSPATH' ) || exit; @@ -262,18 +264,18 @@ public function execute( array $input ): array { 'title' => $content_data['title'] ?? '', 'content' => $content_data['content'] ?? '', 'metadata' => array( - 'source_type' => 'wordpress_media', - 'item_identifier' => $post->ID, - 'original_id' => $post->ID, - 'parent_post_id' => $post->post_parent, - 'original_title' => $title, - 'original_date_gmt' => $post->post_date_gmt, - 'mime_type' => $file_type, - 'file_size' => $file_size, - 'site_name' => $site_name, - 'source_url' => $source_url, - 'image_file_path' => strpos( $file_type, 'video/' ) !== 0 ? $file_path : '', - '_engine_data' => $engine_data, + 'source_type' => 'wordpress_media', + 'item_identifier' => $post->ID, + 'original_id' => $post->ID, + 'parent_post_id' => $post->post_parent, + 'original_title' => $title, + 'original_date_gmt' => $post->post_date_gmt, + 'mime_type' => $file_type, + 'file_size' => $file_size, + 'site_name' => $site_name, + 'source_url' => $source_url, + 'image_file_path' => strpos( $file_type, 'video/' ) !== 0 ? $file_path : '', + '_engine_data' => $engine_data, ), 'file_info' => $file_info, ); diff --git a/inc/Abilities/Fetch/GetWordPressPostAbility.php b/inc/Abilities/Fetch/GetWordPressPostAbility.php index 85f4474a9..268d9b143 100644 --- a/inc/Abilities/Fetch/GetWordPressPostAbility.php +++ b/inc/Abilities/Fetch/GetWordPressPostAbility.php @@ -11,6 +11,7 @@ namespace DataMachine\Abilities\Fetch; use DataMachine\Abilities\PermissionHelper; +use DataMachine\Abilities\Traits\HasCheckPermission; defined( 'ABSPATH' ) || exit; diff --git a/inc/Abilities/Fetch/QueryWordPressPostsAbility.php b/inc/Abilities/Fetch/QueryWordPressPostsAbility.php index 5e2cb6deb..e8a8a14a1 100644 --- a/inc/Abilities/Fetch/QueryWordPressPostsAbility.php +++ b/inc/Abilities/Fetch/QueryWordPressPostsAbility.php @@ -11,6 +11,8 @@ namespace DataMachine\Abilities\Fetch; use DataMachine\Abilities\PermissionHelper; +use DataMachine\Abilities\Fetch\Traits\HasApplyKeywordSearch; +use DataMachine\Abilities\Traits\HasCheckPermission; defined( 'ABSPATH' ) || exit; @@ -273,17 +275,17 @@ public function execute( array $input ): array { 'title' => $title, 'content' => $content, 'metadata' => array( - 'source_type' => 'wordpress_local', - 'item_identifier' => $post_id, - 'original_id' => $post_id, - 'original_title' => $title, - 'original_date_gmt' => $post->post_date_gmt, - 'post_type' => $post->post_type, - 'post_status' => $post->post_status, - 'site_name' => $site_name, - 'permalink' => get_permalink( $post_id ) ?? '', - 'excerpt' => $post->post_excerpt, - 'author' => get_the_author_meta( 'display_name', (int) $post->post_author ), + 'source_type' => 'wordpress_local', + 'item_identifier' => $post_id, + 'original_id' => $post_id, + 'original_title' => $title, + 'original_date_gmt' => $post->post_date_gmt, + 'post_type' => $post->post_type, + 'post_status' => $post->post_status, + 'site_name' => $site_name, + 'permalink' => get_permalink( $post_id ) ?? '', + 'excerpt' => $post->post_excerpt, + 'author' => get_the_author_meta( 'display_name', (int) $post->post_author ), ), ); diff --git a/inc/Abilities/File/AgentFileAbilities.php b/inc/Abilities/File/AgentFileAbilities.php index 135dc5c20..ac3511323 100644 --- a/inc/Abilities/File/AgentFileAbilities.php +++ b/inc/Abilities/File/AgentFileAbilities.php @@ -21,6 +21,8 @@ use DataMachine\Core\FilesRepository\DirectoryManager; use DataMachine\Core\FilesRepository\FilesystemHelper; use DataMachine\Engine\AI\MemoryFileRegistry; +use DataMachine\Abilities\Traits\HasCheckPermission; +use DataMachine\Abilities\File\FlowFileAbilities; defined( 'ABSPATH' ) || exit; @@ -348,23 +350,23 @@ public function executeListAgentFiles( array $input ): array { 'agent_id' => (int) ( $input['agent_id'] ?? 0 ), 'user_id' => $user_id, ); - $contexts_dir = $dm->get_contexts_directory( $agent_context ); + $contexts_dir = $dm->get_contexts_directory( $agent_context ); if ( is_dir( $contexts_dir ) ) { foreach ( glob( trailingslashit( $contexts_dir ) . '*.md' ) as $filepath ) { $filename = basename( $filepath ); $slug = pathinfo( $filename, PATHINFO_FILENAME ); $files[] = array( - 'filename' => $filename, - 'size' => filesize( $filepath ), - 'modified' => gmdate( 'c', filemtime( $filepath ) ), - 'type' => 'context', - 'layer' => 'context', - 'protected' => false, - 'editable' => true, - 'registered' => false, - 'label' => ucfirst( $slug ) . ' Context', - 'description' => "Context-scoped instructions loaded when execution context is '{$slug}'.", + 'filename' => $filename, + 'size' => filesize( $filepath ), + 'modified' => gmdate( 'c', filemtime( $filepath ) ), + 'type' => 'context', + 'layer' => 'context', + 'protected' => false, + 'editable' => true, + 'registered' => false, + 'label' => ucfirst( $slug ) . ' Context', + 'description' => "Context-scoped instructions loaded when execution context is '{$slug}'.", 'context_slug' => $slug, ); } diff --git a/inc/Abilities/File/FlowFileAbilities.php b/inc/Abilities/File/FlowFileAbilities.php index 9f48c4082..a082c782c 100644 --- a/inc/Abilities/File/FlowFileAbilities.php +++ b/inc/Abilities/File/FlowFileAbilities.php @@ -15,6 +15,7 @@ use DataMachine\Core\Database\Flows\Flows; use DataMachine\Core\FilesRepository\FileCleanup; use DataMachine\Core\FilesRepository\FileStorage; +use DataMachine\Abilities\Traits\HasCheckPermission; defined( 'ABSPATH' ) || exit; diff --git a/inc/Abilities/Flow/FlowHelpers.php b/inc/Abilities/Flow/FlowHelpers.php index b06fa871a..47116f10d 100644 --- a/inc/Abilities/Flow/FlowHelpers.php +++ b/inc/Abilities/Flow/FlowHelpers.php @@ -19,6 +19,7 @@ use DataMachine\Core\Database\Flows\Flows; use DataMachine\Core\Database\Jobs\Jobs; use DataMachine\Core\Database\Pipelines\Pipelines; +use DataMachine\Abilities\Traits\HasCheckPermission; defined( 'ABSPATH' ) || exit; diff --git a/inc/Abilities/Flow/PauseFlowAbility.php b/inc/Abilities/Flow/PauseFlowAbility.php index 577ad7149..aeac6d8ba 100644 --- a/inc/Abilities/Flow/PauseFlowAbility.php +++ b/inc/Abilities/Flow/PauseFlowAbility.php @@ -116,8 +116,8 @@ public function execute( array $input ): array { $details = array(); foreach ( $flows as $flow ) { - $fid = (int) $flow['flow_id']; - $scheduling = $flow['scheduling_config'] ?? array(); + $fid = (int) $flow['flow_id']; + $scheduling = $flow['scheduling_config'] ?? array(); // Already paused — skip. if ( isset( $scheduling['enabled'] ) && false === $scheduling['enabled'] ) { diff --git a/inc/Abilities/Flow/QueueAbility.php b/inc/Abilities/Flow/QueueAbility.php index bab09fee6..5d66b7fd3 100644 --- a/inc/Abilities/Flow/QueueAbility.php +++ b/inc/Abilities/Flow/QueueAbility.php @@ -19,1182 +19,4 @@ class QueueAbility { use FlowHelpers; - - public function __construct() { - $this->initDatabases(); - - if ( ! class_exists( 'WP_Ability' ) ) { - return; - } - - $this->registerAbilities(); - } - - /** - * Register all queue-related abilities. - */ - private function registerAbilities(): void { - $register_callback = function () { - $this->registerQueueAdd(); - $this->registerQueueList(); - $this->registerQueueClear(); - $this->registerQueueRemove(); - $this->registerQueueUpdate(); - $this->registerQueueMove(); - $this->registerQueueSettings(); - }; - - if ( doing_action( 'wp_abilities_api_init' ) ) { - $register_callback(); - } elseif ( ! did_action( 'wp_abilities_api_init' ) ) { - add_action( 'wp_abilities_api_init', $register_callback ); - } - } - - /** - * Register queue-add ability. - */ - private function registerQueueAdd(): void { - wp_register_ability( - 'datamachine/queue-add', - array( - 'label' => __( 'Add to Queue', 'data-machine' ), - 'description' => __( 'Add a prompt to the flow queue.', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'flow_id', 'flow_step_id', 'prompt' ), - 'properties' => array( - 'flow_id' => array( - 'type' => 'integer', - 'description' => __( 'Flow ID to add prompt to', 'data-machine' ), - ), - 'flow_step_id' => array( - 'type' => 'string', - 'description' => __( 'Flow step ID to add prompt to', 'data-machine' ), - ), - 'prompt' => array( - 'type' => 'string', - 'description' => __( 'Prompt text to queue', 'data-machine' ), - ), - 'skip_validation' => array( - 'type' => 'boolean', - 'description' => __( 'Skip duplicate validation (default: false). Use only when intentionally re-adding a known prompt.', 'data-machine' ), - ), - 'context' => array( - 'type' => 'object', - 'description' => __( 'Domain-specific context for duplicate detection strategies (e.g., venue, startDate for events).', 'data-machine' ), - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'flow_id' => array( 'type' => 'integer' ), - 'flow_step_id' => array( 'type' => 'string' ), - 'queue_length' => array( 'type' => 'integer' ), - 'message' => array( 'type' => 'string' ), - 'error' => array( 'type' => 'string' ), - 'reason' => array( 'type' => 'string' ), - 'match' => array( 'type' => 'object' ), - 'source' => array( 'type' => 'string' ), - 'strategy' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeQueueAdd' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - } - - /** - * Register queue-list ability. - */ - private function registerQueueList(): void { - wp_register_ability( - 'datamachine/queue-list', - array( - 'label' => __( 'List Queue', 'data-machine' ), - 'description' => __( 'List all prompts in the flow queue.', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'flow_id', 'flow_step_id' ), - 'properties' => array( - 'flow_id' => array( - 'type' => 'integer', - 'description' => __( 'Flow ID to list queue for', 'data-machine' ), - ), - 'flow_step_id' => array( - 'type' => 'string', - 'description' => __( 'Flow step ID to list queue for', 'data-machine' ), - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'flow_id' => array( 'type' => 'integer' ), - 'flow_step_id' => array( 'type' => 'string' ), - 'queue' => array( 'type' => 'array' ), - 'count' => array( 'type' => 'integer' ), - 'queue_enabled' => array( 'type' => 'boolean' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeQueueList' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - } - - /** - * Register queue-clear ability. - */ - private function registerQueueClear(): void { - wp_register_ability( - 'datamachine/queue-clear', - array( - 'label' => __( 'Clear Queue', 'data-machine' ), - 'description' => __( 'Clear all prompts from the flow queue.', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'flow_id', 'flow_step_id' ), - 'properties' => array( - 'flow_id' => array( - 'type' => 'integer', - 'description' => __( 'Flow ID to clear queue for', 'data-machine' ), - ), - 'flow_step_id' => array( - 'type' => 'string', - 'description' => __( 'Flow step ID to clear queue for', 'data-machine' ), - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'flow_id' => array( 'type' => 'integer' ), - 'flow_step_id' => array( 'type' => 'string' ), - 'cleared_count' => array( 'type' => 'integer' ), - 'message' => array( 'type' => 'string' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeQueueClear' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - } - - /** - * Register queue-remove ability. - */ - private function registerQueueRemove(): void { - wp_register_ability( - 'datamachine/queue-remove', - array( - 'label' => __( 'Remove from Queue', 'data-machine' ), - 'description' => __( 'Remove a specific prompt from the queue by index.', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'flow_id', 'flow_step_id', 'index' ), - 'properties' => array( - 'flow_id' => array( - 'type' => 'integer', - 'description' => __( 'Flow ID', 'data-machine' ), - ), - 'flow_step_id' => array( - 'type' => 'string', - 'description' => __( 'Flow step ID', 'data-machine' ), - ), - 'index' => array( - 'type' => 'integer', - 'description' => __( 'Queue index to remove (0-based)', 'data-machine' ), - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'flow_id' => array( 'type' => 'integer' ), - 'removed_prompt' => array( 'type' => 'string' ), - 'queue_length' => array( 'type' => 'integer' ), - 'message' => array( 'type' => 'string' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeQueueRemove' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - } - - /** - * Register queue-update ability. - */ - private function registerQueueUpdate(): void { - wp_register_ability( - 'datamachine/queue-update', - array( - 'label' => __( 'Update Queue Item', 'data-machine' ), - 'description' => __( 'Update a prompt at a specific index in the flow queue.', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'flow_id', 'flow_step_id', 'index', 'prompt' ), - 'properties' => array( - 'flow_id' => array( - 'type' => 'integer', - 'description' => __( 'Flow ID', 'data-machine' ), - ), - 'flow_step_id' => array( - 'type' => 'string', - 'description' => __( 'Flow step ID', 'data-machine' ), - ), - 'index' => array( - 'type' => 'integer', - 'description' => __( 'Queue index to update (0-based)', 'data-machine' ), - ), - 'prompt' => array( - 'type' => 'string', - 'description' => __( 'New prompt text', 'data-machine' ), - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'flow_id' => array( 'type' => 'integer' ), - 'flow_step_id' => array( 'type' => 'string' ), - 'index' => array( 'type' => 'integer' ), - 'queue_length' => array( 'type' => 'integer' ), - 'message' => array( 'type' => 'string' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeQueueUpdate' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - } - - /** - * Register queue-move ability. - */ - private function registerQueueMove(): void { - wp_register_ability( - 'datamachine/queue-move', - array( - 'label' => __( 'Move Queue Item', 'data-machine' ), - 'description' => __( 'Move a prompt from one position to another in the queue.', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'flow_id', 'flow_step_id', 'from_index', 'to_index' ), - 'properties' => array( - 'flow_id' => array( - 'type' => 'integer', - 'description' => __( 'Flow ID', 'data-machine' ), - ), - 'flow_step_id' => array( - 'type' => 'string', - 'description' => __( 'Flow step ID', 'data-machine' ), - ), - 'from_index' => array( - 'type' => 'integer', - 'description' => __( 'Current index of item to move (0-based)', 'data-machine' ), - ), - 'to_index' => array( - 'type' => 'integer', - 'description' => __( 'Target index to move item to (0-based)', 'data-machine' ), - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'flow_id' => array( 'type' => 'integer' ), - 'flow_step_id' => array( 'type' => 'string' ), - 'from_index' => array( 'type' => 'integer' ), - 'to_index' => array( 'type' => 'integer' ), - 'queue_length' => array( 'type' => 'integer' ), - 'message' => array( 'type' => 'string' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeQueueMove' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - } - - /** - * Register queue settings ability. - */ - private function registerQueueSettings(): void { - wp_register_ability( - 'datamachine/queue-settings', - array( - 'label' => __( 'Update Queue Settings', 'data-machine' ), - 'description' => __( 'Update queue settings for a flow step.', 'data-machine' ), - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'required' => array( 'flow_id', 'flow_step_id', 'queue_enabled' ), - 'properties' => array( - 'flow_id' => array( - 'type' => 'integer', - 'description' => __( 'Flow ID', 'data-machine' ), - ), - 'flow_step_id' => array( - 'type' => 'string', - 'description' => __( 'Flow step ID', 'data-machine' ), - ), - 'queue_enabled' => array( - 'type' => 'boolean', - 'description' => __( 'Whether queue pop is enabled for this step', 'data-machine' ), - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'flow_id' => array( 'type' => 'integer' ), - 'flow_step_id' => array( 'type' => 'string' ), - 'queue_enabled' => array( 'type' => 'boolean' ), - 'message' => array( 'type' => 'string' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( $this, 'executeQueueSettings' ), - 'permission_callback' => array( $this, 'checkPermission' ), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - } - - /** - * Add a prompt to the flow queue. - * - * @param array $input Input with flow_id and prompt. - * @return array Result. - */ - public function executeQueueAdd( array $input ): array { - $flow_id = $input['flow_id'] ?? null; - $flow_step_id = $input['flow_step_id'] ?? null; - $prompt = $input['prompt'] ?? null; - - if ( ! is_numeric( $flow_id ) || (int) $flow_id <= 0 ) { - return array( - 'success' => false, - 'error' => 'flow_id is required and must be a positive integer', - ); - } - - if ( empty( $flow_step_id ) || ! is_string( $flow_step_id ) ) { - return array( - 'success' => false, - 'error' => 'flow_step_id is required and must be a string', - ); - } - - if ( empty( $prompt ) || ! is_string( $prompt ) ) { - return array( - 'success' => false, - 'error' => 'prompt is required and must be a non-empty string', - ); - } - - $flow_id = (int) $flow_id; - $flow_step_id = sanitize_text_field( $flow_step_id ); - $prompt = sanitize_textarea_field( wp_unslash( $prompt ) ); - - $flow = $this->db_flows->get_flow( $flow_id ); - if ( ! $flow ) { - return array( - 'success' => false, - 'error' => 'Flow not found', - ); - } - - $validation = $this->getStepConfigForQueue( $flow, $flow_step_id ); - if ( ! $validation['success'] ) { - return $validation; - } - - $flow_config = $validation['flow_config']; - $step_config = $validation['step_config']; - $prompt_queue = $step_config['prompt_queue']; - - // Duplicate validation (unless explicitly skipped). - $skip_validation = ! empty( $input['skip_validation'] ); - if ( ! $skip_validation ) { - // Resolve post_type from the flow's publish step handler config. - // Without this, the validator defaults to 'post' and misses duplicates - // for custom post types (quizzes, recipes, events, etc.). - $post_type = $input['post_type'] ?? $this->resolvePublishPostType( $flow_config ); - - $dedup = new DuplicateCheckAbility(); - $result = $dedup->executeCheckDuplicate( array( - 'title' => $prompt, - 'post_type' => $post_type, - 'scope' => 'both', - 'flow_id' => $flow_id, - 'flow_step_id' => $flow_step_id, - 'context' => $input['context'] ?? array(), - ) ); - - if ( 'duplicate' === $result['verdict'] ) { - return array( - 'success' => false, - 'error' => 'duplicate_rejected', - 'reason' => $result['reason'] ?? '', - 'match' => $result['match'] ?? array(), - 'source' => $result['source'] ?? 'unknown', - 'strategy' => $result['strategy'] ?? '', - 'flow_id' => $flow_id, - 'message' => sprintf( 'Rejected: "%s" is a duplicate. %s', $prompt, $result['reason'] ?? '' ), - ); - } - } - - $prompt_queue[] = array( - 'prompt' => $prompt, - 'added_at' => gmdate( 'c' ), - ); - - $flow_config[ $flow_step_id ]['prompt_queue'] = $prompt_queue; - - $success = $this->db_flows->update_flow( - $flow_id, - array( 'flow_config' => $flow_config ) - ); - - if ( ! $success ) { - return array( - 'success' => false, - 'error' => 'Failed to update flow queue', - ); - } - - do_action( - 'datamachine_log', - 'info', - 'Prompt added to queue', - array( - 'flow_id' => $flow_id, - 'queue_length' => count( $prompt_queue ), - ) - ); - - return array( - 'success' => true, - 'flow_id' => $flow_id, - 'flow_step_id' => $flow_step_id, - 'queue_length' => count( $prompt_queue ), - 'message' => sprintf( 'Prompt added to queue. Queue now has %d item(s).', count( $prompt_queue ) ), - ); - } - - /** - * List all prompts in the flow queue. - * - * @param array $input Input with flow_id. - * @return array Result with queue items. - */ - public function executeQueueList( array $input ): array { - $flow_id = $input['flow_id'] ?? null; - $flow_step_id = $input['flow_step_id'] ?? null; - - if ( ! is_numeric( $flow_id ) || (int) $flow_id <= 0 ) { - return array( - 'success' => false, - 'error' => 'flow_id is required and must be a positive integer', - ); - } - - if ( empty( $flow_step_id ) || ! is_string( $flow_step_id ) ) { - return array( - 'success' => false, - 'error' => 'flow_step_id is required and must be a string', - ); - } - - $flow_id = (int) $flow_id; - $flow_step_id = sanitize_text_field( $flow_step_id ); - - $flow = $this->db_flows->get_flow( $flow_id ); - if ( ! $flow ) { - return array( - 'success' => false, - 'error' => 'Flow not found', - ); - } - - $validation = $this->getStepConfigForQueue( $flow, $flow_step_id ); - if ( ! $validation['success'] ) { - return $validation; - } - - $step_config = $validation['step_config']; - $prompt_queue = $step_config['prompt_queue']; - - return array( - 'success' => true, - 'flow_id' => $flow_id, - 'flow_step_id' => $flow_step_id, - 'queue' => $prompt_queue, - 'count' => count( $prompt_queue ), - 'queue_enabled' => $step_config['queue_enabled'], - ); - } - - /** - * Clear all prompts from the flow queue. - * - * @param array $input Input with flow_id. - * @return array Result. - */ - public function executeQueueClear( array $input ): array { - $flow_id = $input['flow_id'] ?? null; - $flow_step_id = $input['flow_step_id'] ?? null; - - if ( ! is_numeric( $flow_id ) || (int) $flow_id <= 0 ) { - return array( - 'success' => false, - 'error' => 'flow_id is required and must be a positive integer', - ); - } - - if ( empty( $flow_step_id ) || ! is_string( $flow_step_id ) ) { - return array( - 'success' => false, - 'error' => 'flow_step_id is required and must be a string', - ); - } - - $flow_id = (int) $flow_id; - $flow_step_id = sanitize_text_field( $flow_step_id ); - - $flow = $this->db_flows->get_flow( $flow_id ); - if ( ! $flow ) { - return array( - 'success' => false, - 'error' => 'Flow not found', - ); - } - - $validation = $this->getStepConfigForQueue( $flow, $flow_step_id ); - if ( ! $validation['success'] ) { - return $validation; - } - - $flow_config = $validation['flow_config']; - $step_config = $validation['step_config']; - $cleared_count = count( $step_config['prompt_queue'] ); - - $flow_config[ $flow_step_id ]['prompt_queue'] = array(); - - $success = $this->db_flows->update_flow( - $flow_id, - array( 'flow_config' => $flow_config ) - ); - - if ( ! $success ) { - return array( - 'success' => false, - 'error' => 'Failed to clear queue', - ); - } - - do_action( - 'datamachine_log', - 'info', - 'Queue cleared', - array( - 'flow_id' => $flow_id, - 'cleared_count' => $cleared_count, - ) - ); - - return array( - 'success' => true, - 'flow_id' => $flow_id, - 'flow_step_id' => $flow_step_id, - 'cleared_count' => $cleared_count, - 'message' => sprintf( 'Cleared %d prompt(s) from queue.', $cleared_count ), - ); - } - - /** - * Remove a specific prompt from the queue by index. - * - * @param array $input Input with flow_id and index. - * @return array Result. - */ - public function executeQueueRemove( array $input ): array { - $flow_id = $input['flow_id'] ?? null; - $flow_step_id = $input['flow_step_id'] ?? null; - $index = $input['index'] ?? null; - - if ( ! is_numeric( $flow_id ) || (int) $flow_id <= 0 ) { - return array( - 'success' => false, - 'error' => 'flow_id is required and must be a positive integer', - ); - } - - if ( empty( $flow_step_id ) || ! is_string( $flow_step_id ) ) { - return array( - 'success' => false, - 'error' => 'flow_step_id is required and must be a string', - ); - } - - if ( ! is_numeric( $index ) || (int) $index < 0 ) { - return array( - 'success' => false, - 'error' => 'index is required and must be a non-negative integer', - ); - } - - $flow_id = (int) $flow_id; - $flow_step_id = sanitize_text_field( $flow_step_id ); - $index = (int) $index; - - $flow = $this->db_flows->get_flow( $flow_id ); - if ( ! $flow ) { - return array( - 'success' => false, - 'error' => 'Flow not found', - ); - } - - $validation = $this->getStepConfigForQueue( $flow, $flow_step_id ); - if ( ! $validation['success'] ) { - return $validation; - } - - $flow_config = $validation['flow_config']; - $step_config = $validation['step_config']; - $prompt_queue = $step_config['prompt_queue']; - - if ( $index >= count( $prompt_queue ) ) { - return array( - 'success' => false, - 'error' => sprintf( 'Index %d is out of range. Queue has %d item(s).', $index, count( $prompt_queue ) ), - ); - } - - $removed_item = $prompt_queue[ $index ]; - $removed_prompt = $removed_item['prompt'] ?? ''; - - array_splice( $prompt_queue, $index, 1 ); - - $flow_config[ $flow_step_id ]['prompt_queue'] = $prompt_queue; - - $success = $this->db_flows->update_flow( - $flow_id, - array( 'flow_config' => $flow_config ) - ); - - if ( ! $success ) { - return array( - 'success' => false, - 'error' => 'Failed to remove prompt from queue', - ); - } - - do_action( - 'datamachine_log', - 'info', - 'Prompt removed from queue', - array( - 'flow_id' => $flow_id, - 'index' => $index, - 'queue_length' => count( $prompt_queue ), - ) - ); - - return array( - 'success' => true, - 'flow_id' => $flow_id, - 'flow_step_id' => $flow_step_id, - 'removed_prompt' => $removed_prompt, - 'queue_length' => count( $prompt_queue ), - 'message' => sprintf( 'Removed prompt at index %d. Queue now has %d item(s).', $index, count( $prompt_queue ) ), - ); - } - - /** - * Update a prompt at a specific index in the queue. - * - * If the index is 0 and the queue is empty, creates a new item. - * - * @param array $input Input with flow_id, index, and prompt. - * @return array Result. - */ - public function executeQueueUpdate( array $input ): array { - $flow_id = $input['flow_id'] ?? null; - $flow_step_id = $input['flow_step_id'] ?? null; - $index = $input['index'] ?? null; - $prompt = $input['prompt'] ?? null; - - if ( ! is_numeric( $flow_id ) || (int) $flow_id <= 0 ) { - return array( - 'success' => false, - 'error' => 'flow_id is required and must be a positive integer', - ); - } - - if ( empty( $flow_step_id ) || ! is_string( $flow_step_id ) ) { - return array( - 'success' => false, - 'error' => 'flow_step_id is required and must be a string', - ); - } - - if ( ! is_numeric( $index ) || (int) $index < 0 ) { - return array( - 'success' => false, - 'error' => 'index is required and must be a non-negative integer', - ); - } - - if ( ! is_string( $prompt ) ) { - return array( - 'success' => false, - 'error' => 'prompt is required and must be a string', - ); - } - - $flow_id = (int) $flow_id; - $flow_step_id = sanitize_text_field( $flow_step_id ); - $index = (int) $index; - $prompt = sanitize_textarea_field( wp_unslash( $prompt ) ); - - $flow = $this->db_flows->get_flow( $flow_id ); - if ( ! $flow ) { - return array( - 'success' => false, - 'error' => 'Flow not found', - ); - } - - $validation = $this->getStepConfigForQueue( $flow, $flow_step_id ); - if ( ! $validation['success'] ) { - return $validation; - } - - $flow_config = $validation['flow_config']; - $step_config = $validation['step_config']; - $prompt_queue = $step_config['prompt_queue']; - - // Special case: if index is 0 and queue is empty, create a new item - if ( 0 === $index && empty( $prompt_queue ) ) { - // If prompt is empty, don't create anything - if ( '' === $prompt ) { - return array( - 'success' => true, - 'flow_id' => $flow_id, - 'index' => $index, - 'queue_length' => 0, - 'message' => 'No changes made (empty prompt, empty queue).', - ); - } - - $prompt_queue[] = array( - 'prompt' => $prompt, - 'added_at' => gmdate( 'c' ), - ); - } elseif ( $index >= count( $prompt_queue ) ) { - return array( - 'success' => false, - 'error' => sprintf( 'Index %d is out of range. Queue has %d item(s).', $index, count( $prompt_queue ) ), - ); - } else { - // Update existing item, preserving added_at - $prompt_queue[ $index ]['prompt'] = $prompt; - } - - $flow_config[ $flow_step_id ]['prompt_queue'] = $prompt_queue; - - $success = $this->db_flows->update_flow( - $flow_id, - array( 'flow_config' => $flow_config ) - ); - - if ( ! $success ) { - return array( - 'success' => false, - 'error' => 'Failed to update queue', - ); - } - - do_action( - 'datamachine_log', - 'info', - 'Queue item updated', - array( - 'flow_id' => $flow_id, - 'index' => $index, - 'queue_length' => count( $prompt_queue ), - ) - ); - - return array( - 'success' => true, - 'flow_id' => $flow_id, - 'flow_step_id' => $flow_step_id, - 'index' => $index, - 'queue_length' => count( $prompt_queue ), - 'message' => sprintf( 'Updated prompt at index %d. Queue has %d item(s).', $index, count( $prompt_queue ) ), - ); - } - - /** - * Move a prompt from one position to another in the queue. - * - * @param array $input Input with flow_id, flow_step_id, from_index, and to_index. - * @return array Result. - */ - public function executeQueueMove( array $input ): array { - $flow_id = $input['flow_id'] ?? null; - $flow_step_id = $input['flow_step_id'] ?? null; - $from_index = $input['from_index'] ?? null; - $to_index = $input['to_index'] ?? null; - - if ( ! is_numeric( $flow_id ) || (int) $flow_id <= 0 ) { - return array( - 'success' => false, - 'error' => 'flow_id is required and must be a positive integer', - ); - } - - if ( empty( $flow_step_id ) || ! is_string( $flow_step_id ) ) { - return array( - 'success' => false, - 'error' => 'flow_step_id is required and must be a string', - ); - } - - if ( ! is_numeric( $from_index ) || (int) $from_index < 0 ) { - return array( - 'success' => false, - 'error' => 'from_index is required and must be a non-negative integer', - ); - } - - if ( ! is_numeric( $to_index ) || (int) $to_index < 0 ) { - return array( - 'success' => false, - 'error' => 'to_index is required and must be a non-negative integer', - ); - } - - $flow_id = (int) $flow_id; - $flow_step_id = sanitize_text_field( $flow_step_id ); - $from_index = (int) $from_index; - $to_index = (int) $to_index; - - if ( $from_index === $to_index ) { - return array( - 'success' => true, - 'flow_id' => $flow_id, - 'flow_step_id' => $flow_step_id, - 'from_index' => $from_index, - 'to_index' => $to_index, - 'queue_length' => 0, - 'message' => 'No move needed (same position).', - ); - } - - $flow = $this->db_flows->get_flow( $flow_id ); - if ( ! $flow ) { - return array( - 'success' => false, - 'error' => 'Flow not found', - ); - } - - $validation = $this->getStepConfigForQueue( $flow, $flow_step_id ); - if ( ! $validation['success'] ) { - return $validation; - } - - $flow_config = $validation['flow_config']; - $step_config = $validation['step_config']; - $prompt_queue = $step_config['prompt_queue']; - $queue_length = count( $prompt_queue ); - - if ( $from_index >= $queue_length ) { - return array( - 'success' => false, - 'error' => sprintf( 'from_index %d is out of range. Queue has %d item(s).', $from_index, $queue_length ), - ); - } - - if ( $to_index >= $queue_length ) { - return array( - 'success' => false, - 'error' => sprintf( 'to_index %d is out of range. Queue has %d item(s).', $to_index, $queue_length ), - ); - } - - // Extract the item and reinsert at new position - $item = $prompt_queue[ $from_index ]; - array_splice( $prompt_queue, $from_index, 1 ); - array_splice( $prompt_queue, $to_index, 0, array( $item ) ); - - $flow_config[ $flow_step_id ]['prompt_queue'] = $prompt_queue; - - $success = $this->db_flows->update_flow( - $flow_id, - array( 'flow_config' => $flow_config ) - ); - - if ( ! $success ) { - return array( - 'success' => false, - 'error' => 'Failed to move queue item', - ); - } - - do_action( - 'datamachine_log', - 'info', - 'Queue item moved', - array( - 'flow_id' => $flow_id, - 'flow_step_id' => $flow_step_id, - 'from_index' => $from_index, - 'to_index' => $to_index, - 'queue_length' => $queue_length, - ) - ); - - return array( - 'success' => true, - 'flow_id' => $flow_id, - 'flow_step_id' => $flow_step_id, - 'from_index' => $from_index, - 'to_index' => $to_index, - 'queue_length' => $queue_length, - 'message' => sprintf( 'Moved item from index %d to %d.', $from_index, $to_index ), - ); - } - - /** - * Update queue settings for a flow step. - * - * @param array $input Input with flow_id, flow_step_id, and queue_enabled. - * @return array Result. - */ - public function executeQueueSettings( array $input ): array { - $flow_id = $input['flow_id'] ?? null; - $flow_step_id = $input['flow_step_id'] ?? null; - $queue_enabled = $input['queue_enabled'] ?? null; - - if ( ! is_numeric( $flow_id ) || (int) $flow_id <= 0 ) { - return array( - 'success' => false, - 'error' => 'flow_id is required and must be a positive integer', - ); - } - - if ( empty( $flow_step_id ) || ! is_string( $flow_step_id ) ) { - return array( - 'success' => false, - 'error' => 'flow_step_id is required and must be a string', - ); - } - - if ( ! is_bool( $queue_enabled ) ) { - return array( - 'success' => false, - 'error' => 'queue_enabled is required and must be a boolean', - ); - } - - $flow_id = (int) $flow_id; - $flow_step_id = sanitize_text_field( $flow_step_id ); - - $flow = $this->db_flows->get_flow( $flow_id ); - if ( ! $flow ) { - return array( - 'success' => false, - 'error' => 'Flow not found', - ); - } - - $validation = $this->getStepConfigForQueue( $flow, $flow_step_id ); - if ( ! $validation['success'] ) { - return $validation; - } - - $flow_config = $validation['flow_config']; - $flow_config[ $flow_step_id ]['queue_enabled'] = $queue_enabled; - - $success = $this->db_flows->update_flow( - $flow_id, - array( 'flow_config' => $flow_config ) - ); - - if ( ! $success ) { - return array( - 'success' => false, - 'error' => 'Failed to update queue settings', - ); - } - - return array( - 'success' => true, - 'flow_id' => $flow_id, - 'flow_step_id' => $flow_step_id, - 'queue_enabled' => $queue_enabled, - 'message' => 'Queue settings updated successfully', - ); - } - - /** - * Pop the first prompt from the queue (for engine use). - * - * @param int $flow_id Flow ID. - * @param DB_Flows $db_flows Database instance (avoids creating new instance each call). - * @return array|null The popped queue item or null if empty. - */ - public static function popFromQueue( int $flow_id, string $flow_step_id, ?DB_Flows $db_flows = null ): ?array { - if ( null === $db_flows ) { - $db_flows = new DB_Flows(); - } - - $flow = $db_flows->get_flow( $flow_id ); - if ( ! $flow ) { - return null; - } - - $flow_config = $flow['flow_config'] ?? array(); - if ( ! isset( $flow_config[ $flow_step_id ] ) ) { - return null; - } - - $step_config = $flow_config[ $flow_step_id ]; - $prompt_queue = $step_config['prompt_queue'] ?? array(); - - if ( empty( $prompt_queue ) ) { - return null; - } - - $popped_item = array_shift( $prompt_queue ); - - $flow_config[ $flow_step_id ]['prompt_queue'] = $prompt_queue; - - $db_flows->update_flow( - $flow_id, - array( 'flow_config' => $flow_config ) - ); - - do_action( - 'datamachine_log', - 'info', - 'Prompt popped from queue', - array( - 'flow_id' => $flow_id, - 'remaining_count' => count( $prompt_queue ), - ) - ); - - return $popped_item; - } - - /** - * Resolve the post_type from the flow's publish step handler config. - * - * Scans all steps in the flow config for a publish step and extracts - * the post_type from its handler config. Falls back to 'post' if no - * publish step is found or no post_type is configured. - * - * @param array $flow_config The flow configuration array keyed by flow_step_id. - * @return string The resolved post type. - */ - private function resolvePublishPostType( array $flow_config ): string { - foreach ( $flow_config as $step_config ) { - if ( ! is_array( $step_config ) ) { - continue; - } - if ( ( $step_config['step_type'] ?? '' ) !== 'publish' ) { - continue; - } - $handler_configs = $step_config['handler_configs'] ?? array(); - foreach ( $handler_configs as $handler_config ) { - if ( ! empty( $handler_config['post_type'] ) ) { - return sanitize_text_field( $handler_config['post_type'] ); - } - } - } - return 'post'; - } - - /** - * Normalize flow step queue config for queue operations. - * - * @param array $flow Flow record. - * @param string $flow_step_id Flow step ID. - * @return array Result with flow_config and step_config or error. - */ - private function getStepConfigForQueue( array $flow, string $flow_step_id ): array { - $flow_id = (int) ( $flow['flow_id'] ?? 0 ); - $parts = apply_filters( 'datamachine_split_flow_step_id', null, $flow_step_id ); - if ( ! $parts || empty( $parts['flow_id'] ) ) { - return array( - 'success' => false, - 'error' => 'Invalid flow_step_id format', - ); - } - if ( (int) $parts['flow_id'] !== $flow_id ) { - return array( - 'success' => false, - 'error' => 'flow_step_id does not belong to this flow', - ); - } - - $flow_config = $flow['flow_config'] ?? array(); - if ( ! isset( $flow_config[ $flow_step_id ] ) ) { - return array( - 'success' => false, - 'error' => 'Flow step not found in flow config', - ); - } - - $step_config = $flow_config[ $flow_step_id ]; - if ( ! isset( $step_config['prompt_queue'] ) || ! is_array( $step_config['prompt_queue'] ) ) { - $step_config['prompt_queue'] = array(); - } - if ( ! isset( $step_config['queue_enabled'] ) || ! is_bool( $step_config['queue_enabled'] ) ) { - $step_config['queue_enabled'] = false; - } - $flow_config[ $flow_step_id ] = $step_config; - - return array( - 'success' => true, - 'flow_config' => $flow_config, - 'step_config' => $step_config, - ); - } } diff --git a/inc/Abilities/Flow/QueueAbility/getStepConfigForQueue.php b/inc/Abilities/Flow/QueueAbility/getStepConfigForQueue.php new file mode 100644 index 000000000..3bda96e05 --- /dev/null +++ b/inc/Abilities/Flow/QueueAbility/getStepConfigForQueue.php @@ -0,0 +1,1098 @@ +//! getStepConfigForQueue — extracted from QueueAbility.php. + + + /** + * Register queue-add ability. + */ + private function registerQueueAdd(): void { + wp_register_ability( + 'datamachine/queue-add', + array( + 'label' => __( 'Add to Queue', 'data-machine' ), + 'description' => __( 'Add a prompt to the flow queue.', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'flow_id', 'flow_step_id', 'prompt' ), + 'properties' => array( + 'flow_id' => array( + 'type' => 'integer', + 'description' => __( 'Flow ID to add prompt to', 'data-machine' ), + ), + 'flow_step_id' => array( + 'type' => 'string', + 'description' => __( 'Flow step ID to add prompt to', 'data-machine' ), + ), + 'prompt' => array( + 'type' => 'string', + 'description' => __( 'Prompt text to queue', 'data-machine' ), + ), + 'skip_validation' => array( + 'type' => 'boolean', + 'description' => __( 'Skip duplicate validation (default: false). Use only when intentionally re-adding a known prompt.', 'data-machine' ), + ), + 'context' => array( + 'type' => 'object', + 'description' => __( 'Domain-specific context for duplicate detection strategies (e.g., venue, startDate for events).', 'data-machine' ), + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'flow_id' => array( 'type' => 'integer' ), + 'flow_step_id' => array( 'type' => 'string' ), + 'queue_length' => array( 'type' => 'integer' ), + 'message' => array( 'type' => 'string' ), + 'error' => array( 'type' => 'string' ), + 'reason' => array( 'type' => 'string' ), + 'match' => array( 'type' => 'object' ), + 'source' => array( 'type' => 'string' ), + 'strategy' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeQueueAdd' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + } + + /** + * Register queue-list ability. + */ + private function registerQueueList(): void { + wp_register_ability( + 'datamachine/queue-list', + array( + 'label' => __( 'List Queue', 'data-machine' ), + 'description' => __( 'List all prompts in the flow queue.', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'flow_id', 'flow_step_id' ), + 'properties' => array( + 'flow_id' => array( + 'type' => 'integer', + 'description' => __( 'Flow ID to list queue for', 'data-machine' ), + ), + 'flow_step_id' => array( + 'type' => 'string', + 'description' => __( 'Flow step ID to list queue for', 'data-machine' ), + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'flow_id' => array( 'type' => 'integer' ), + 'flow_step_id' => array( 'type' => 'string' ), + 'queue' => array( 'type' => 'array' ), + 'count' => array( 'type' => 'integer' ), + 'queue_enabled' => array( 'type' => 'boolean' ), + 'error' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeQueueList' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + } + + /** + * Register queue-clear ability. + */ + private function registerQueueClear(): void { + wp_register_ability( + 'datamachine/queue-clear', + array( + 'label' => __( 'Clear Queue', 'data-machine' ), + 'description' => __( 'Clear all prompts from the flow queue.', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'flow_id', 'flow_step_id' ), + 'properties' => array( + 'flow_id' => array( + 'type' => 'integer', + 'description' => __( 'Flow ID to clear queue for', 'data-machine' ), + ), + 'flow_step_id' => array( + 'type' => 'string', + 'description' => __( 'Flow step ID to clear queue for', 'data-machine' ), + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'flow_id' => array( 'type' => 'integer' ), + 'flow_step_id' => array( 'type' => 'string' ), + 'cleared_count' => array( 'type' => 'integer' ), + 'message' => array( 'type' => 'string' ), + 'error' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeQueueClear' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + } + + /** + * Register queue-remove ability. + */ + private function registerQueueRemove(): void { + wp_register_ability( + 'datamachine/queue-remove', + array( + 'label' => __( 'Remove from Queue', 'data-machine' ), + 'description' => __( 'Remove a specific prompt from the queue by index.', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'flow_id', 'flow_step_id', 'index' ), + 'properties' => array( + 'flow_id' => array( + 'type' => 'integer', + 'description' => __( 'Flow ID', 'data-machine' ), + ), + 'flow_step_id' => array( + 'type' => 'string', + 'description' => __( 'Flow step ID', 'data-machine' ), + ), + 'index' => array( + 'type' => 'integer', + 'description' => __( 'Queue index to remove (0-based)', 'data-machine' ), + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'flow_id' => array( 'type' => 'integer' ), + 'removed_prompt' => array( 'type' => 'string' ), + 'queue_length' => array( 'type' => 'integer' ), + 'message' => array( 'type' => 'string' ), + 'error' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeQueueRemove' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + } + + /** + * Register queue-update ability. + */ + private function registerQueueUpdate(): void { + wp_register_ability( + 'datamachine/queue-update', + array( + 'label' => __( 'Update Queue Item', 'data-machine' ), + 'description' => __( 'Update a prompt at a specific index in the flow queue.', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'flow_id', 'flow_step_id', 'index', 'prompt' ), + 'properties' => array( + 'flow_id' => array( + 'type' => 'integer', + 'description' => __( 'Flow ID', 'data-machine' ), + ), + 'flow_step_id' => array( + 'type' => 'string', + 'description' => __( 'Flow step ID', 'data-machine' ), + ), + 'index' => array( + 'type' => 'integer', + 'description' => __( 'Queue index to update (0-based)', 'data-machine' ), + ), + 'prompt' => array( + 'type' => 'string', + 'description' => __( 'New prompt text', 'data-machine' ), + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'flow_id' => array( 'type' => 'integer' ), + 'flow_step_id' => array( 'type' => 'string' ), + 'index' => array( 'type' => 'integer' ), + 'queue_length' => array( 'type' => 'integer' ), + 'message' => array( 'type' => 'string' ), + 'error' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeQueueUpdate' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + } + + /** + * Register queue-move ability. + */ + private function registerQueueMove(): void { + wp_register_ability( + 'datamachine/queue-move', + array( + 'label' => __( 'Move Queue Item', 'data-machine' ), + 'description' => __( 'Move a prompt from one position to another in the queue.', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'flow_id', 'flow_step_id', 'from_index', 'to_index' ), + 'properties' => array( + 'flow_id' => array( + 'type' => 'integer', + 'description' => __( 'Flow ID', 'data-machine' ), + ), + 'flow_step_id' => array( + 'type' => 'string', + 'description' => __( 'Flow step ID', 'data-machine' ), + ), + 'from_index' => array( + 'type' => 'integer', + 'description' => __( 'Current index of item to move (0-based)', 'data-machine' ), + ), + 'to_index' => array( + 'type' => 'integer', + 'description' => __( 'Target index to move item to (0-based)', 'data-machine' ), + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'flow_id' => array( 'type' => 'integer' ), + 'flow_step_id' => array( 'type' => 'string' ), + 'from_index' => array( 'type' => 'integer' ), + 'to_index' => array( 'type' => 'integer' ), + 'queue_length' => array( 'type' => 'integer' ), + 'message' => array( 'type' => 'string' ), + 'error' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeQueueMove' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + } + + /** + * Register queue settings ability. + */ + private function registerQueueSettings(): void { + wp_register_ability( + 'datamachine/queue-settings', + array( + 'label' => __( 'Update Queue Settings', 'data-machine' ), + 'description' => __( 'Update queue settings for a flow step.', 'data-machine' ), + 'category' => 'datamachine', + 'input_schema' => array( + 'type' => 'object', + 'required' => array( 'flow_id', 'flow_step_id', 'queue_enabled' ), + 'properties' => array( + 'flow_id' => array( + 'type' => 'integer', + 'description' => __( 'Flow ID', 'data-machine' ), + ), + 'flow_step_id' => array( + 'type' => 'string', + 'description' => __( 'Flow step ID', 'data-machine' ), + ), + 'queue_enabled' => array( + 'type' => 'boolean', + 'description' => __( 'Whether queue pop is enabled for this step', 'data-machine' ), + ), + ), + ), + 'output_schema' => array( + 'type' => 'object', + 'properties' => array( + 'success' => array( 'type' => 'boolean' ), + 'flow_id' => array( 'type' => 'integer' ), + 'flow_step_id' => array( 'type' => 'string' ), + 'queue_enabled' => array( 'type' => 'boolean' ), + 'message' => array( 'type' => 'string' ), + 'error' => array( 'type' => 'string' ), + ), + ), + 'execute_callback' => array( $this, 'executeQueueSettings' ), + 'permission_callback' => array( $this, 'checkPermission' ), + 'meta' => array( 'show_in_rest' => true ), + ) + ); + } + + /** + * Add a prompt to the flow queue. + * + * @param array $input Input with flow_id and prompt. + * @return array Result. + */ + public function executeQueueAdd( array $input ): array { + $flow_id = $input['flow_id'] ?? null; + $flow_step_id = $input['flow_step_id'] ?? null; + $prompt = $input['prompt'] ?? null; + + if ( ! is_numeric( $flow_id ) || (int) $flow_id <= 0 ) { + return array( + 'success' => false, + 'error' => 'flow_id is required and must be a positive integer', + ); + } + + if ( empty( $flow_step_id ) || ! is_string( $flow_step_id ) ) { + return array( + 'success' => false, + 'error' => 'flow_step_id is required and must be a string', + ); + } + + if ( empty( $prompt ) || ! is_string( $prompt ) ) { + return array( + 'success' => false, + 'error' => 'prompt is required and must be a non-empty string', + ); + } + + $flow_id = (int) $flow_id; + $flow_step_id = sanitize_text_field( $flow_step_id ); + $prompt = sanitize_textarea_field( wp_unslash( $prompt ) ); + + $flow = $this->db_flows->get_flow( $flow_id ); + if ( ! $flow ) { + return array( + 'success' => false, + 'error' => 'Flow not found', + ); + } + + $validation = $this->getStepConfigForQueue( $flow, $flow_step_id ); + if ( ! $validation['success'] ) { + return $validation; + } + + $flow_config = $validation['flow_config']; + $step_config = $validation['step_config']; + $prompt_queue = $step_config['prompt_queue']; + + // Duplicate validation (unless explicitly skipped). + $skip_validation = ! empty( $input['skip_validation'] ); + if ( ! $skip_validation ) { + // Resolve post_type from the flow's publish step handler config. + // Without this, the validator defaults to 'post' and misses duplicates + // for custom post types (quizzes, recipes, events, etc.). + $post_type = $input['post_type'] ?? $this->resolvePublishPostType( $flow_config ); + + $dedup = new DuplicateCheckAbility(); + $result = $dedup->executeCheckDuplicate( array( + 'title' => $prompt, + 'post_type' => $post_type, + 'scope' => 'both', + 'flow_id' => $flow_id, + 'flow_step_id' => $flow_step_id, + 'context' => $input['context'] ?? array(), + ) ); + + if ( 'duplicate' === $result['verdict'] ) { + return array( + 'success' => false, + 'error' => 'duplicate_rejected', + 'reason' => $result['reason'] ?? '', + 'match' => $result['match'] ?? array(), + 'source' => $result['source'] ?? 'unknown', + 'strategy' => $result['strategy'] ?? '', + 'flow_id' => $flow_id, + 'message' => sprintf( 'Rejected: "%s" is a duplicate. %s', $prompt, $result['reason'] ?? '' ), + ); + } + } + + $prompt_queue[] = array( + 'prompt' => $prompt, + 'added_at' => gmdate( 'c' ), + ); + + $flow_config[ $flow_step_id ]['prompt_queue'] = $prompt_queue; + + $success = $this->db_flows->update_flow( + $flow_id, + array( 'flow_config' => $flow_config ) + ); + + if ( ! $success ) { + return array( + 'success' => false, + 'error' => 'Failed to update flow queue', + ); + } + + do_action( + 'datamachine_log', + 'info', + 'Prompt added to queue', + array( + 'flow_id' => $flow_id, + 'queue_length' => count( $prompt_queue ), + ) + ); + + return array( + 'success' => true, + 'flow_id' => $flow_id, + 'flow_step_id' => $flow_step_id, + 'queue_length' => count( $prompt_queue ), + 'message' => sprintf( 'Prompt added to queue. Queue now has %d item(s).', count( $prompt_queue ) ), + ); + } + + /** + * List all prompts in the flow queue. + * + * @param array $input Input with flow_id. + * @return array Result with queue items. + */ + public function executeQueueList( array $input ): array { + $flow_id = $input['flow_id'] ?? null; + $flow_step_id = $input['flow_step_id'] ?? null; + + if ( ! is_numeric( $flow_id ) || (int) $flow_id <= 0 ) { + return array( + 'success' => false, + 'error' => 'flow_id is required and must be a positive integer', + ); + } + + if ( empty( $flow_step_id ) || ! is_string( $flow_step_id ) ) { + return array( + 'success' => false, + 'error' => 'flow_step_id is required and must be a string', + ); + } + + $flow_id = (int) $flow_id; + $flow_step_id = sanitize_text_field( $flow_step_id ); + + $flow = $this->db_flows->get_flow( $flow_id ); + if ( ! $flow ) { + return array( + 'success' => false, + 'error' => 'Flow not found', + ); + } + + $validation = $this->getStepConfigForQueue( $flow, $flow_step_id ); + if ( ! $validation['success'] ) { + return $validation; + } + + $step_config = $validation['step_config']; + $prompt_queue = $step_config['prompt_queue']; + + return array( + 'success' => true, + 'flow_id' => $flow_id, + 'flow_step_id' => $flow_step_id, + 'queue' => $prompt_queue, + 'count' => count( $prompt_queue ), + 'queue_enabled' => $step_config['queue_enabled'], + ); + } + + /** + * Clear all prompts from the flow queue. + * + * @param array $input Input with flow_id. + * @return array Result. + */ + public function executeQueueClear( array $input ): array { + $flow_id = $input['flow_id'] ?? null; + $flow_step_id = $input['flow_step_id'] ?? null; + + if ( ! is_numeric( $flow_id ) || (int) $flow_id <= 0 ) { + return array( + 'success' => false, + 'error' => 'flow_id is required and must be a positive integer', + ); + } + + if ( empty( $flow_step_id ) || ! is_string( $flow_step_id ) ) { + return array( + 'success' => false, + 'error' => 'flow_step_id is required and must be a string', + ); + } + + $flow_id = (int) $flow_id; + $flow_step_id = sanitize_text_field( $flow_step_id ); + + $flow = $this->db_flows->get_flow( $flow_id ); + if ( ! $flow ) { + return array( + 'success' => false, + 'error' => 'Flow not found', + ); + } + + $validation = $this->getStepConfigForQueue( $flow, $flow_step_id ); + if ( ! $validation['success'] ) { + return $validation; + } + + $flow_config = $validation['flow_config']; + $step_config = $validation['step_config']; + $cleared_count = count( $step_config['prompt_queue'] ); + + $flow_config[ $flow_step_id ]['prompt_queue'] = array(); + + $success = $this->db_flows->update_flow( + $flow_id, + array( 'flow_config' => $flow_config ) + ); + + if ( ! $success ) { + return array( + 'success' => false, + 'error' => 'Failed to clear queue', + ); + } + + do_action( + 'datamachine_log', + 'info', + 'Queue cleared', + array( + 'flow_id' => $flow_id, + 'cleared_count' => $cleared_count, + ) + ); + + return array( + 'success' => true, + 'flow_id' => $flow_id, + 'flow_step_id' => $flow_step_id, + 'cleared_count' => $cleared_count, + 'message' => sprintf( 'Cleared %d prompt(s) from queue.', $cleared_count ), + ); + } + + /** + * Remove a specific prompt from the queue by index. + * + * @param array $input Input with flow_id and index. + * @return array Result. + */ + public function executeQueueRemove( array $input ): array { + $flow_id = $input['flow_id'] ?? null; + $flow_step_id = $input['flow_step_id'] ?? null; + $index = $input['index'] ?? null; + + if ( ! is_numeric( $flow_id ) || (int) $flow_id <= 0 ) { + return array( + 'success' => false, + 'error' => 'flow_id is required and must be a positive integer', + ); + } + + if ( empty( $flow_step_id ) || ! is_string( $flow_step_id ) ) { + return array( + 'success' => false, + 'error' => 'flow_step_id is required and must be a string', + ); + } + + if ( ! is_numeric( $index ) || (int) $index < 0 ) { + return array( + 'success' => false, + 'error' => 'index is required and must be a non-negative integer', + ); + } + + $flow_id = (int) $flow_id; + $flow_step_id = sanitize_text_field( $flow_step_id ); + $index = (int) $index; + + $flow = $this->db_flows->get_flow( $flow_id ); + if ( ! $flow ) { + return array( + 'success' => false, + 'error' => 'Flow not found', + ); + } + + $validation = $this->getStepConfigForQueue( $flow, $flow_step_id ); + if ( ! $validation['success'] ) { + return $validation; + } + + $flow_config = $validation['flow_config']; + $step_config = $validation['step_config']; + $prompt_queue = $step_config['prompt_queue']; + + if ( $index >= count( $prompt_queue ) ) { + return array( + 'success' => false, + 'error' => sprintf( 'Index %d is out of range. Queue has %d item(s).', $index, count( $prompt_queue ) ), + ); + } + + $removed_item = $prompt_queue[ $index ]; + $removed_prompt = $removed_item['prompt'] ?? ''; + + array_splice( $prompt_queue, $index, 1 ); + + $flow_config[ $flow_step_id ]['prompt_queue'] = $prompt_queue; + + $success = $this->db_flows->update_flow( + $flow_id, + array( 'flow_config' => $flow_config ) + ); + + if ( ! $success ) { + return array( + 'success' => false, + 'error' => 'Failed to remove prompt from queue', + ); + } + + do_action( + 'datamachine_log', + 'info', + 'Prompt removed from queue', + array( + 'flow_id' => $flow_id, + 'index' => $index, + 'queue_length' => count( $prompt_queue ), + ) + ); + + return array( + 'success' => true, + 'flow_id' => $flow_id, + 'flow_step_id' => $flow_step_id, + 'removed_prompt' => $removed_prompt, + 'queue_length' => count( $prompt_queue ), + 'message' => sprintf( 'Removed prompt at index %d. Queue now has %d item(s).', $index, count( $prompt_queue ) ), + ); + } + + /** + * Update a prompt at a specific index in the queue. + * + * If the index is 0 and the queue is empty, creates a new item. + * + * @param array $input Input with flow_id, index, and prompt. + * @return array Result. + */ + public function executeQueueUpdate( array $input ): array { + $flow_id = $input['flow_id'] ?? null; + $flow_step_id = $input['flow_step_id'] ?? null; + $index = $input['index'] ?? null; + $prompt = $input['prompt'] ?? null; + + if ( ! is_numeric( $flow_id ) || (int) $flow_id <= 0 ) { + return array( + 'success' => false, + 'error' => 'flow_id is required and must be a positive integer', + ); + } + + if ( empty( $flow_step_id ) || ! is_string( $flow_step_id ) ) { + return array( + 'success' => false, + 'error' => 'flow_step_id is required and must be a string', + ); + } + + if ( ! is_numeric( $index ) || (int) $index < 0 ) { + return array( + 'success' => false, + 'error' => 'index is required and must be a non-negative integer', + ); + } + + if ( ! is_string( $prompt ) ) { + return array( + 'success' => false, + 'error' => 'prompt is required and must be a string', + ); + } + + $flow_id = (int) $flow_id; + $flow_step_id = sanitize_text_field( $flow_step_id ); + $index = (int) $index; + $prompt = sanitize_textarea_field( wp_unslash( $prompt ) ); + + $flow = $this->db_flows->get_flow( $flow_id ); + if ( ! $flow ) { + return array( + 'success' => false, + 'error' => 'Flow not found', + ); + } + + $validation = $this->getStepConfigForQueue( $flow, $flow_step_id ); + if ( ! $validation['success'] ) { + return $validation; + } + + $flow_config = $validation['flow_config']; + $step_config = $validation['step_config']; + $prompt_queue = $step_config['prompt_queue']; + + // Special case: if index is 0 and queue is empty, create a new item + if ( 0 === $index && empty( $prompt_queue ) ) { + // If prompt is empty, don't create anything + if ( '' === $prompt ) { + return array( + 'success' => true, + 'flow_id' => $flow_id, + 'index' => $index, + 'queue_length' => 0, + 'message' => 'No changes made (empty prompt, empty queue).', + ); + } + + $prompt_queue[] = array( + 'prompt' => $prompt, + 'added_at' => gmdate( 'c' ), + ); + } elseif ( $index >= count( $prompt_queue ) ) { + return array( + 'success' => false, + 'error' => sprintf( 'Index %d is out of range. Queue has %d item(s).', $index, count( $prompt_queue ) ), + ); + } else { + // Update existing item, preserving added_at + $prompt_queue[ $index ]['prompt'] = $prompt; + } + + $flow_config[ $flow_step_id ]['prompt_queue'] = $prompt_queue; + + $success = $this->db_flows->update_flow( + $flow_id, + array( 'flow_config' => $flow_config ) + ); + + if ( ! $success ) { + return array( + 'success' => false, + 'error' => 'Failed to update queue', + ); + } + + do_action( + 'datamachine_log', + 'info', + 'Queue item updated', + array( + 'flow_id' => $flow_id, + 'index' => $index, + 'queue_length' => count( $prompt_queue ), + ) + ); + + return array( + 'success' => true, + 'flow_id' => $flow_id, + 'flow_step_id' => $flow_step_id, + 'index' => $index, + 'queue_length' => count( $prompt_queue ), + 'message' => sprintf( 'Updated prompt at index %d. Queue has %d item(s).', $index, count( $prompt_queue ) ), + ); + } + + /** + * Move a prompt from one position to another in the queue. + * + * @param array $input Input with flow_id, flow_step_id, from_index, and to_index. + * @return array Result. + */ + public function executeQueueMove( array $input ): array { + $flow_id = $input['flow_id'] ?? null; + $flow_step_id = $input['flow_step_id'] ?? null; + $from_index = $input['from_index'] ?? null; + $to_index = $input['to_index'] ?? null; + + if ( ! is_numeric( $flow_id ) || (int) $flow_id <= 0 ) { + return array( + 'success' => false, + 'error' => 'flow_id is required and must be a positive integer', + ); + } + + if ( empty( $flow_step_id ) || ! is_string( $flow_step_id ) ) { + return array( + 'success' => false, + 'error' => 'flow_step_id is required and must be a string', + ); + } + + if ( ! is_numeric( $from_index ) || (int) $from_index < 0 ) { + return array( + 'success' => false, + 'error' => 'from_index is required and must be a non-negative integer', + ); + } + + if ( ! is_numeric( $to_index ) || (int) $to_index < 0 ) { + return array( + 'success' => false, + 'error' => 'to_index is required and must be a non-negative integer', + ); + } + + $flow_id = (int) $flow_id; + $flow_step_id = sanitize_text_field( $flow_step_id ); + $from_index = (int) $from_index; + $to_index = (int) $to_index; + + if ( $from_index === $to_index ) { + return array( + 'success' => true, + 'flow_id' => $flow_id, + 'flow_step_id' => $flow_step_id, + 'from_index' => $from_index, + 'to_index' => $to_index, + 'queue_length' => 0, + 'message' => 'No move needed (same position).', + ); + } + + $flow = $this->db_flows->get_flow( $flow_id ); + if ( ! $flow ) { + return array( + 'success' => false, + 'error' => 'Flow not found', + ); + } + + $validation = $this->getStepConfigForQueue( $flow, $flow_step_id ); + if ( ! $validation['success'] ) { + return $validation; + } + + $flow_config = $validation['flow_config']; + $step_config = $validation['step_config']; + $prompt_queue = $step_config['prompt_queue']; + $queue_length = count( $prompt_queue ); + + if ( $from_index >= $queue_length ) { + return array( + 'success' => false, + 'error' => sprintf( 'from_index %d is out of range. Queue has %d item(s).', $from_index, $queue_length ), + ); + } + + if ( $to_index >= $queue_length ) { + return array( + 'success' => false, + 'error' => sprintf( 'to_index %d is out of range. Queue has %d item(s).', $to_index, $queue_length ), + ); + } + + // Extract the item and reinsert at new position + $item = $prompt_queue[ $from_index ]; + array_splice( $prompt_queue, $from_index, 1 ); + array_splice( $prompt_queue, $to_index, 0, array( $item ) ); + + $flow_config[ $flow_step_id ]['prompt_queue'] = $prompt_queue; + + $success = $this->db_flows->update_flow( + $flow_id, + array( 'flow_config' => $flow_config ) + ); + + if ( ! $success ) { + return array( + 'success' => false, + 'error' => 'Failed to move queue item', + ); + } + + do_action( + 'datamachine_log', + 'info', + 'Queue item moved', + array( + 'flow_id' => $flow_id, + 'flow_step_id' => $flow_step_id, + 'from_index' => $from_index, + 'to_index' => $to_index, + 'queue_length' => $queue_length, + ) + ); + + return array( + 'success' => true, + 'flow_id' => $flow_id, + 'flow_step_id' => $flow_step_id, + 'from_index' => $from_index, + 'to_index' => $to_index, + 'queue_length' => $queue_length, + 'message' => sprintf( 'Moved item from index %d to %d.', $from_index, $to_index ), + ); + } + + /** + * Update queue settings for a flow step. + * + * @param array $input Input with flow_id, flow_step_id, and queue_enabled. + * @return array Result. + */ + public function executeQueueSettings( array $input ): array { + $flow_id = $input['flow_id'] ?? null; + $flow_step_id = $input['flow_step_id'] ?? null; + $queue_enabled = $input['queue_enabled'] ?? null; + + if ( ! is_numeric( $flow_id ) || (int) $flow_id <= 0 ) { + return array( + 'success' => false, + 'error' => 'flow_id is required and must be a positive integer', + ); + } + + if ( empty( $flow_step_id ) || ! is_string( $flow_step_id ) ) { + return array( + 'success' => false, + 'error' => 'flow_step_id is required and must be a string', + ); + } + + if ( ! is_bool( $queue_enabled ) ) { + return array( + 'success' => false, + 'error' => 'queue_enabled is required and must be a boolean', + ); + } + + $flow_id = (int) $flow_id; + $flow_step_id = sanitize_text_field( $flow_step_id ); + + $flow = $this->db_flows->get_flow( $flow_id ); + if ( ! $flow ) { + return array( + 'success' => false, + 'error' => 'Flow not found', + ); + } + + $validation = $this->getStepConfigForQueue( $flow, $flow_step_id ); + if ( ! $validation['success'] ) { + return $validation; + } + + $flow_config = $validation['flow_config']; + $flow_config[ $flow_step_id ]['queue_enabled'] = $queue_enabled; + + $success = $this->db_flows->update_flow( + $flow_id, + array( 'flow_config' => $flow_config ) + ); + + if ( ! $success ) { + return array( + 'success' => false, + 'error' => 'Failed to update queue settings', + ); + } + + return array( + 'success' => true, + 'flow_id' => $flow_id, + 'flow_step_id' => $flow_step_id, + 'queue_enabled' => $queue_enabled, + 'message' => 'Queue settings updated successfully', + ); + } + + /** + * Resolve the post_type from the flow's publish step handler config. + * + * Scans all steps in the flow config for a publish step and extracts + * the post_type from its handler config. Falls back to 'post' if no + * publish step is found or no post_type is configured. + * + * @param array $flow_config The flow configuration array keyed by flow_step_id. + * @return string The resolved post type. + */ + private function resolvePublishPostType( array $flow_config ): string { + foreach ( $flow_config as $step_config ) { + if ( ! is_array( $step_config ) ) { + continue; + } + if ( ( $step_config['step_type'] ?? '' ) !== 'publish' ) { + continue; + } + $handler_configs = $step_config['handler_configs'] ?? array(); + foreach ( $handler_configs as $handler_config ) { + if ( ! empty( $handler_config['post_type'] ) ) { + return sanitize_text_field( $handler_config['post_type'] ); + } + } + } + return 'post'; + } + + /** + * Normalize flow step queue config for queue operations. + * + * @param array $flow Flow record. + * @param string $flow_step_id Flow step ID. + * @return array Result with flow_config and step_config or error. + */ + private function getStepConfigForQueue( array $flow, string $flow_step_id ): array { + $flow_id = (int) ( $flow['flow_id'] ?? 0 ); + $parts = apply_filters( 'datamachine_split_flow_step_id', null, $flow_step_id ); + if ( ! $parts || empty( $parts['flow_id'] ) ) { + return array( + 'success' => false, + 'error' => 'Invalid flow_step_id format', + ); + } + if ( (int) $parts['flow_id'] !== $flow_id ) { + return array( + 'success' => false, + 'error' => 'flow_step_id does not belong to this flow', + ); + } + + $flow_config = $flow['flow_config'] ?? array(); + if ( ! isset( $flow_config[ $flow_step_id ] ) ) { + return array( + 'success' => false, + 'error' => 'Flow step not found in flow config', + ); + } + + $step_config = $flow_config[ $flow_step_id ]; + if ( ! isset( $step_config['prompt_queue'] ) || ! is_array( $step_config['prompt_queue'] ) ) { + $step_config['prompt_queue'] = array(); + } + if ( ! isset( $step_config['queue_enabled'] ) || ! is_bool( $step_config['queue_enabled'] ) ) { + $step_config['queue_enabled'] = false; + } + $flow_config[ $flow_step_id ] = $step_config; + + return array( + 'success' => true, + 'flow_config' => $flow_config, + 'step_config' => $step_config, + ); + } diff --git a/inc/Abilities/Flow/QueueAbility/helpers.php b/inc/Abilities/Flow/QueueAbility/helpers.php new file mode 100644 index 000000000..382b68d06 --- /dev/null +++ b/inc/Abilities/Flow/QueueAbility/helpers.php @@ -0,0 +1,84 @@ +//! helpers — extracted from QueueAbility.php. + + + public function __construct() { + $this->initDatabases(); + + if ( ! class_exists( 'WP_Ability' ) ) { + return; + } + + $this->registerAbilities(); + } + + /** + * Register all queue-related abilities. + */ + private function registerAbilities(): void { + $register_callback = function () { + $this->registerQueueAdd(); + $this->registerQueueList(); + $this->registerQueueClear(); + $this->registerQueueRemove(); + $this->registerQueueUpdate(); + $this->registerQueueMove(); + $this->registerQueueSettings(); + }; + + if ( doing_action( 'wp_abilities_api_init' ) ) { + $register_callback(); + } elseif ( ! did_action( 'wp_abilities_api_init' ) ) { + add_action( 'wp_abilities_api_init', $register_callback ); + } + } + + /** + * Pop the first prompt from the queue (for engine use). + * + * @param int $flow_id Flow ID. + * @param DB_Flows $db_flows Database instance (avoids creating new instance each call). + * @return array|null The popped queue item or null if empty. + */ + public static function popFromQueue( int $flow_id, string $flow_step_id, ?DB_Flows $db_flows = null ): ?array { + if ( null === $db_flows ) { + $db_flows = new DB_Flows(); + } + + $flow = $db_flows->get_flow( $flow_id ); + if ( ! $flow ) { + return null; + } + + $flow_config = $flow['flow_config'] ?? array(); + if ( ! isset( $flow_config[ $flow_step_id ] ) ) { + return null; + } + + $step_config = $flow_config[ $flow_step_id ]; + $prompt_queue = $step_config['prompt_queue'] ?? array(); + + if ( empty( $prompt_queue ) ) { + return null; + } + + $popped_item = array_shift( $prompt_queue ); + + $flow_config[ $flow_step_id ]['prompt_queue'] = $prompt_queue; + + $db_flows->update_flow( + $flow_id, + array( 'flow_config' => $flow_config ) + ); + + do_action( + 'datamachine_log', + 'info', + 'Prompt popped from queue', + array( + 'flow_id' => $flow_id, + 'remaining_count' => count( $prompt_queue ), + ) + ); + + return $popped_item; + } diff --git a/inc/Abilities/Flow/ResumeFlowAbility.php b/inc/Abilities/Flow/ResumeFlowAbility.php index b04cfd72a..9905b4cb8 100644 --- a/inc/Abilities/Flow/ResumeFlowAbility.php +++ b/inc/Abilities/Flow/ResumeFlowAbility.php @@ -23,6 +23,7 @@ class ResumeFlowAbility { use FlowHelpers; + use DataMachine\Abilities\Flow\PauseFlowAbility; public function __construct() { $this->initDatabases(); diff --git a/inc/Abilities/FlowAbilities.php b/inc/Abilities/FlowAbilities.php index 87fc7df4e..cb68da1a3 100644 --- a/inc/Abilities/FlowAbilities.php +++ b/inc/Abilities/FlowAbilities.php @@ -22,6 +22,7 @@ use DataMachine\Abilities\Flow\ResumeFlowAbility; use DataMachine\Abilities\Flow\QueueAbility; use DataMachine\Abilities\Flow\WebhookTriggerAbility; +use DataMachine\Abilities\Traits\HasCheckPermission; defined( 'ABSPATH' ) || exit; @@ -40,6 +41,7 @@ class FlowAbilities { private WebhookTriggerAbility $webhook_trigger; public function __construct() { + add_action('wp_abilities_api_init', array( $this, 'abilities_api_init' )); if ( ! class_exists( 'WP_Ability' ) || self::$registered ) { return; } diff --git a/inc/Abilities/FlowStep/FlowStepHelpers.php b/inc/Abilities/FlowStep/FlowStepHelpers.php index 8fe218c07..1327241a5 100644 --- a/inc/Abilities/FlowStep/FlowStepHelpers.php +++ b/inc/Abilities/FlowStep/FlowStepHelpers.php @@ -17,6 +17,7 @@ use DataMachine\Core\Database\Flows\Flows; use DataMachine\Core\Database\Pipelines\Pipelines; use DataMachine\Core\Steps\FlowStepConfig; +use DataMachine\Abilities\Traits\HasCheckPermission; defined( 'ABSPATH' ) || exit; diff --git a/inc/Abilities/FlowStepAbilities.php b/inc/Abilities/FlowStepAbilities.php index 6b6a3e487..6794bcaf8 100644 --- a/inc/Abilities/FlowStepAbilities.php +++ b/inc/Abilities/FlowStepAbilities.php @@ -17,6 +17,7 @@ use DataMachine\Abilities\FlowStep\UpdateFlowStepAbility; use DataMachine\Abilities\FlowStep\ConfigureFlowStepsAbility; use DataMachine\Abilities\FlowStep\ValidateFlowStepsConfigAbility; +use DataMachine\Abilities\Traits\HasCheckPermission; defined( 'ABSPATH' ) || exit; @@ -30,6 +31,7 @@ class FlowStepAbilities { private ValidateFlowStepsConfigAbility $validate_flow_steps_config; public function __construct() { + add_action('wp_abilities_api_init', array( $this, 'abilities_api_init' )); if ( ! class_exists( 'WP_Ability' ) || self::$registered ) { return; } diff --git a/inc/Abilities/Handler/TestHandlerAbility.php b/inc/Abilities/Handler/TestHandlerAbility.php index 97b9a588f..a9e2e7254 100644 --- a/inc/Abilities/Handler/TestHandlerAbility.php +++ b/inc/Abilities/Handler/TestHandlerAbility.php @@ -68,15 +68,15 @@ private function registerAbility(): void { 'output_schema' => array( 'type' => 'object', 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'handler_slug' => array( 'type' => 'string' ), - 'handler_label' => array( 'type' => 'string' ), - 'config_used' => array( 'type' => 'object' ), - 'packets' => array( 'type' => 'array' ), - 'packet_count' => array( 'type' => 'integer' ), - 'warnings' => array( 'type' => 'array' ), - 'execution_time_ms' => array( 'type' => 'number' ), - 'error' => array( 'type' => 'string' ), + 'success' => array( 'type' => 'boolean' ), + 'handler_slug' => array( 'type' => 'string' ), + 'handler_label' => array( 'type' => 'string' ), + 'config_used' => array( 'type' => 'object' ), + 'packets' => array( 'type' => 'array' ), + 'packet_count' => array( 'type' => 'integer' ), + 'warnings' => array( 'type' => 'array' ), + 'execution_time_ms' => array( 'type' => 'number' ), + 'error' => array( 'type' => 'string' ), ), ), 'execute_callback' => array( $this, 'execute' ), diff --git a/inc/Abilities/HandlerAbilities.php b/inc/Abilities/HandlerAbilities.php index 14e895b97..0ecf53784 100644 --- a/inc/Abilities/HandlerAbilities.php +++ b/inc/Abilities/HandlerAbilities.php @@ -12,6 +12,7 @@ namespace DataMachine\Abilities; use DataMachine\Abilities\PermissionHelper; +use DataMachine\Abilities\Traits\HasCheckPermission; defined( 'ABSPATH' ) || exit; diff --git a/inc/Abilities/InternalLinkingAbilities.php b/inc/Abilities/InternalLinkingAbilities.php index 11d819440..00b378cc2 100644 --- a/inc/Abilities/InternalLinkingAbilities.php +++ b/inc/Abilities/InternalLinkingAbilities.php @@ -39,459 +39,6 @@ class InternalLinkingAbilities { private static bool $registered = false; - public function __construct() { - if ( ! class_exists( 'WP_Ability' ) ) { - return; - } - - if ( self::$registered ) { - return; - } - - $this->registerAbilities(); - self::$registered = true; - } - - private function registerAbilities(): void { - $register_callback = function () { - wp_register_ability( - 'datamachine/internal-linking', - array( - 'label' => 'Internal Linking', - 'description' => 'Queue system agent insertion of semantic internal links into posts', - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'properties' => array( - 'post_ids' => array( - 'type' => 'array', - 'items' => array( 'type' => 'integer' ), - 'description' => 'Post IDs to process', - ), - 'category' => array( - 'type' => 'string', - 'description' => 'Category slug to process all posts from', - ), - 'links_per_post' => array( - 'type' => 'integer', - 'description' => 'Maximum internal links to insert per post', - 'default' => 3, - ), - 'dry_run' => array( - 'type' => 'boolean', - 'description' => 'Preview which posts would be queued without processing', - 'default' => false, - ), - 'force' => array( - 'type' => 'boolean', - 'description' => 'Force re-processing even if already linked', - 'default' => false, - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'queued_count' => array( 'type' => 'integer' ), - 'post_ids' => array( - 'type' => 'array', - 'items' => array( 'type' => 'integer' ), - ), - 'message' => array( 'type' => 'string' ), - 'error' => array( 'type' => 'string' ), - ), - ), - 'execute_callback' => array( self::class, 'queueInternalLinking' ), - 'permission_callback' => fn() => PermissionHelper::can_manage(), - 'meta' => array( 'show_in_rest' => false ), - ) - ); - - wp_register_ability( - 'datamachine/diagnose-internal-links', - array( - 'label' => 'Diagnose Internal Links', - 'description' => 'Report internal link coverage across published posts', - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'properties' => array(), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'total_posts' => array( 'type' => 'integer' ), - 'posts_with_links' => array( 'type' => 'integer' ), - 'posts_without_links' => array( 'type' => 'integer' ), - 'avg_links_per_post' => array( 'type' => 'number' ), - 'by_category' => array( - 'type' => 'array', - 'items' => array( 'type' => 'object' ), - ), - ), - ), - 'execute_callback' => array( self::class, 'diagnoseInternalLinks' ), - 'permission_callback' => fn() => PermissionHelper::can_manage(), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - - wp_register_ability( - 'datamachine/audit-internal-links', - array( - 'label' => 'Audit Internal Links', - 'description' => 'Scan post content for internal links, build a link graph, and cache results. Does NOT check for broken links — use datamachine/check-broken-links for that.', - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'properties' => array( - 'post_type' => array( - 'type' => 'string', - 'description' => 'Post type to audit. Default: post.', - 'default' => 'post', - ), - 'category' => array( - 'type' => 'string', - 'description' => 'Category slug to limit audit scope.', - ), - 'post_ids' => array( - 'type' => 'array', - 'items' => array( 'type' => 'integer' ), - 'description' => 'Specific post IDs to audit.', - ), - 'force' => array( - 'type' => 'boolean', - 'description' => 'Force rebuild even if cached graph exists.', - 'default' => false, - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'total_scanned' => array( 'type' => 'integer' ), - 'total_links' => array( 'type' => 'integer' ), - 'orphaned_count' => array( 'type' => 'integer' ), - 'avg_outbound' => array( 'type' => 'number' ), - 'avg_inbound' => array( 'type' => 'number' ), - 'orphaned_posts' => array( - 'type' => 'array', - 'items' => array( 'type' => 'object' ), - ), - 'top_linked' => array( - 'type' => 'array', - 'items' => array( 'type' => 'object' ), - ), - 'cached' => array( 'type' => 'boolean' ), - ), - ), - 'execute_callback' => array( self::class, 'auditInternalLinks' ), - 'permission_callback' => fn() => PermissionHelper::can_manage(), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - - wp_register_ability( - 'datamachine/get-orphaned-posts', - array( - 'label' => 'Get Orphaned Posts', - 'description' => 'Return posts with zero inbound internal links from the cached link graph. Runs audit automatically if no cache exists.', - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'properties' => array( - 'post_type' => array( - 'type' => 'string', - 'description' => 'Post type to check. Default: post.', - 'default' => 'post', - ), - 'limit' => array( - 'type' => 'integer', - 'description' => 'Maximum orphaned posts to return. Default: 50.', - 'default' => 50, - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'orphaned_count' => array( 'type' => 'integer' ), - 'total_scanned' => array( 'type' => 'integer' ), - 'orphaned_posts' => array( - 'type' => 'array', - 'items' => array( 'type' => 'object' ), - ), - 'from_cache' => array( 'type' => 'boolean' ), - ), - ), - 'execute_callback' => array( self::class, 'getOrphanedPosts' ), - 'permission_callback' => fn() => PermissionHelper::can_manage(), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - - wp_register_ability( - 'datamachine/check-broken-links', - array( - 'label' => 'Check Broken Links', - 'description' => 'HTTP HEAD check links from the cached link graph to find broken URLs. Supports internal, external, or all links via scope. External checks include per-domain rate limiting and HEAD→GET fallback.', - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'properties' => array( - 'post_type' => array( - 'type' => 'string', - 'description' => 'Post type scope. Default: post.', - 'default' => 'post', - ), - 'scope' => array( - 'type' => 'string', - 'description' => 'Link scope: internal, external, or all. Default: internal.', - 'enum' => array( 'internal', 'external', 'all' ), - 'default' => 'internal', - ), - 'limit' => array( - 'type' => 'integer', - 'description' => 'Maximum unique URLs to check. Default: 200.', - 'default' => 200, - ), - 'timeout' => array( - 'type' => 'integer', - 'description' => 'HTTP timeout per request in seconds. Default: 5.', - 'default' => 5, - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'scope' => array( 'type' => 'string' ), - 'urls_checked' => array( 'type' => 'integer' ), - 'broken_count' => array( 'type' => 'integer' ), - 'broken_links' => array( - 'type' => 'array', - 'items' => array( 'type' => 'object' ), - ), - 'from_cache' => array( 'type' => 'boolean' ), - ), - ), - 'execute_callback' => array( self::class, 'checkBrokenLinks' ), - 'permission_callback' => fn() => PermissionHelper::can_manage(), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - - wp_register_ability( - 'datamachine/link-opportunities', - array( - 'label' => 'Link Opportunities', - 'description' => 'Rank internal linking opportunities by combining GSC traffic data with the link graph. High-traffic pages with few inbound links score highest.', - 'category' => 'datamachine', - 'input_schema' => array( - 'type' => 'object', - 'properties' => array( - 'limit' => array( - 'type' => 'integer', - 'description' => 'Number of results to return. Default: 20.', - 'default' => 20, - ), - 'category' => array( - 'type' => 'string', - 'description' => 'Category slug to filter by.', - ), - 'min_clicks' => array( - 'type' => 'integer', - 'description' => 'Minimum GSC clicks to include a page. Default: 5.', - 'default' => 5, - ), - 'days' => array( - 'type' => 'integer', - 'description' => 'GSC lookback period in days. Default: 28.', - 'default' => 28, - ), - ), - ), - 'output_schema' => array( - 'type' => 'object', - 'properties' => array( - 'success' => array( 'type' => 'boolean' ), - 'pages_with_traffic' => array( 'type' => 'integer' ), - 'opportunities' => array( - 'type' => 'array', - 'items' => array( - 'type' => 'object', - 'properties' => array( - 'score' => array( 'type' => 'number' ), - 'clicks' => array( 'type' => 'number' ), - 'impressions' => array( 'type' => 'number' ), - 'position' => array( 'type' => 'number' ), - 'inbound_links' => array( 'type' => 'integer' ), - 'outbound_links' => array( 'type' => 'integer' ), - 'post_id' => array( 'type' => 'integer' ), - 'slug' => array( 'type' => 'string' ), - ), - ), - ), - ), - ), - 'execute_callback' => array( self::class, 'getLinkOpportunities' ), - 'permission_callback' => fn() => PermissionHelper::can_manage(), - 'meta' => array( 'show_in_rest' => true ), - ) - ); - - - }; - - if ( doing_action( 'wp_abilities_api_init' ) ) { - $register_callback(); - } elseif ( ! did_action( 'wp_abilities_api_init' ) ) { - add_action( 'wp_abilities_api_init', $register_callback ); - } - } - - /** - * Queue internal linking for posts. - * - * @param array $input Ability input. - * @return array Ability response. - */ - public static function queueInternalLinking( array $input ): array { - $post_ids = array_map( 'absint', $input['post_ids'] ?? array() ); - $category = sanitize_text_field( $input['category'] ?? '' ); - $links_per_post = absint( $input['links_per_post'] ?? 3 ); - $dry_run = ! empty( $input['dry_run'] ); - $force = ! empty( $input['force'] ); - - $user_id = get_current_user_id(); - $agent_id = function_exists( 'datamachine_resolve_or_create_agent_id' ) && $user_id > 0 ? datamachine_resolve_or_create_agent_id( $user_id ) : 0; - $system_defaults = PluginSettings::resolveModelForAgentContext( $agent_id, 'system' ); - $provider = $system_defaults['provider']; - $model = $system_defaults['model']; - - if ( empty( $provider ) || empty( $model ) ) { - return array( - 'success' => false, - 'queued_count' => 0, - 'post_ids' => array(), - 'message' => 'No default AI provider/model configured.', - 'error' => 'Configure default_provider and default_model in Data Machine settings.', - ); - } - - // Resolve category to post IDs. - if ( ! empty( $category ) ) { - $term = get_term_by( 'slug', $category, 'category' ); - if ( ! $term ) { - return array( - 'success' => false, - 'queued_count' => 0, - 'post_ids' => array(), - 'message' => "Category '{$category}' not found.", - 'error' => 'Invalid category slug', - ); - } - - $cat_posts = get_posts( - array( - 'post_type' => 'post', - 'post_status' => 'publish', - 'category' => $term->term_id, - 'fields' => 'ids', - 'numberposts' => -1, - ) - ); - - $post_ids = array_merge( $post_ids, $cat_posts ); - } - - $post_ids = array_values( array_unique( array_filter( $post_ids ) ) ); - - if ( empty( $post_ids ) ) { - return array( - 'success' => false, - 'queued_count' => 0, - 'post_ids' => array(), - 'message' => 'No post IDs provided or resolved.', - 'error' => 'Missing required parameter: post_ids or category', - ); - } - - if ( $dry_run ) { - return array( - 'success' => true, - 'queued_count' => count( $post_ids ), - 'post_ids' => $post_ids, - 'message' => sprintf( 'Dry run: %d post(s) would be queued for internal linking.', count( $post_ids ) ), - ); - } - - // Filter to eligible posts. - $eligible = array(); - foreach ( $post_ids as $pid ) { - $post = get_post( $pid ); - if ( $post && 'publish' === $post->post_status ) { - $eligible[] = $pid; - } - } - - if ( empty( $eligible ) ) { - return array( - 'success' => true, - 'queued_count' => 0, - 'post_ids' => array(), - 'message' => 'No eligible published posts found.', - ); - } - - // Build per-item params for batch scheduling. - $item_params = array(); - foreach ( $eligible as $pid ) { - $item_params[] = array( - 'post_id' => $pid, - 'links_per_post' => $links_per_post, - 'force' => $force, - 'source' => 'ability', - ); - } - - $batch = TaskScheduler::scheduleBatch( - 'internal_linking', - $item_params, - array( - 'user_id' => $user_id, - 'agent_id' => $agent_id, - ) - ); - - if ( false === $batch ) { - return array( - 'success' => false, - 'queued_count' => 0, - 'post_ids' => array(), - 'message' => 'Failed to schedule batch.', - 'error' => 'Task batch scheduling failed.', - ); - } - - return array( - 'success' => true, - 'queued_count' => count( $eligible ), - 'post_ids' => $eligible, - 'batch_id' => $batch['batch_id'] ?? null, - 'message' => sprintf( - 'Internal linking batch scheduled for %d post(s) (chunks of %d).', - count( $eligible ), - $batch['chunk_size'] ?? TaskScheduler::BATCH_CHUNK_SIZE - ), - ); - } - /** * Diagnose internal link coverage across published posts. * @@ -852,60 +399,6 @@ public static function checkBrokenLinks( array $input = array() ): array { ); } - /** - * Check a single URL's HTTP status. - * - * Uses HEAD first for efficiency. For external URLs, falls back to GET - * with a range header when HEAD returns 405 or 403 (some servers block HEAD). - * - * @since 0.42.0 - * - * @param string $url URL to check. - * @param int $timeout Request timeout in seconds. - * @param bool $is_external Whether this is an external URL (enables GET fallback). - * @return int HTTP status code (0 for connection failures/timeouts). - */ - private static function checkUrlStatus( string $url, int $timeout, bool $is_external ): int { - $response = wp_remote_head( - $url, - array( - 'timeout' => $timeout, - 'redirection' => 3, - 'user-agent' => 'DataMachine/LinkChecker (WordPress; +' . home_url() . ')', - ) - ); - - if ( is_wp_error( $response ) ) { - return 0; - } - - $status = wp_remote_retrieve_response_code( $response ); - - // Some external servers block HEAD requests — fall back to GET. - if ( $is_external && ( 405 === $status || 403 === $status ) ) { - $get_response = wp_remote_get( - $url, - array( - 'timeout' => $timeout, - 'redirection' => 3, - 'headers' => array( 'Range' => 'bytes=0-0' ), - 'user-agent' => 'DataMachine/LinkChecker (WordPress; +' . home_url() . ')', - ) - ); - - if ( ! is_wp_error( $get_response ) ) { - $get_status = wp_remote_retrieve_response_code( $get_response ); - // 206 (Partial Content) means the server supports Range and the URL is alive. - if ( 206 === $get_status || ( $get_status >= 200 && $get_status < 400 ) ) { - return $get_status; - } - return $get_status; - } - } - - return $status ? $status : 0; - } - /** * Get ranked internal linking opportunities by combining GSC traffic with link graph. * @@ -1018,7 +511,7 @@ public static function getLinkOpportunities( array $input = array() ): array { 'error' => "Category '{$category}' not found.", ); } - $cat_posts = get_posts( + $cat_posts = get_posts( array( 'post_type' => 'post', 'post_status' => 'publish', @@ -1059,8 +552,8 @@ public static function getLinkOpportunities( array $input = array() ): array { } $traffic_by_post[ $post_id ]['clicks'] += (int) $clicks; - $traffic_by_post[ $post_id ]['impressions'] += (int) ( $row['impressions'] ?? 0 ); - $traffic_by_post[ $post_id ]['position'] += (float) ( $row['position'] ?? 0 ); + $traffic_by_post[ $post_id ]['impressions'] += (int) ( $row['impressions'] ?? 0 ); + $traffic_by_post[ $post_id ]['position'] += (float) ( $row['position'] ?? 0 ); ++$traffic_by_post[ $post_id ]['row_count']; } @@ -1123,343 +616,6 @@ function ( $a, $b ) { ); } - /** - * Build the internal link graph by scanning post content. - * - * Shared logic used by audit, get-orphaned-posts, and check-broken-links. - * Returns the full graph data structure suitable for caching. - * - * @since 0.32.0 - * - * @param string $post_type Post type to scan. - * @param string $category Category slug to filter by. - * @param array $specific_ids Specific post IDs to scan. - * @return array Graph data structure. - */ - private static function buildLinkGraph( string $post_type, string $category, array $specific_ids ): array { - global $wpdb; - - $home_url = home_url(); - $home_host = wp_parse_url( $home_url, PHP_URL_HOST ); - - // Build the query for posts to scan. - if ( ! empty( $specific_ids ) ) { - $id_placeholders = implode( ',', array_fill( 0, count( $specific_ids ), '%d' ) ); - // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.UnfinishedPrepare,WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching - $posts = $wpdb->get_results( - $wpdb->prepare( - // phpcs:disable WordPress.DB.PreparedSQL -- Table name from $wpdb->prefix, not user input. - "SELECT ID, post_title, post_content FROM {$wpdb->posts} - WHERE ID IN ($id_placeholders) AND post_status = %s", - array_merge( $specific_ids, array( 'publish' ) ) - ) - ); - // phpcs:enable WordPress.DB.PreparedSQL - } elseif ( ! empty( $category ) ) { - $term = get_term_by( 'slug', $category, 'category' ); - if ( ! $term ) { - return array( - 'success' => false, - 'error' => "Category '{$category}' not found.", - ); - } - - // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching - $posts = $wpdb->get_results( - $wpdb->prepare( - "SELECT p.ID, p.post_title, p.post_content - FROM {$wpdb->posts} p - INNER JOIN {$wpdb->term_relationships} tr ON p.ID = tr.object_id - INNER JOIN {$wpdb->term_taxonomy} tt ON tr.term_taxonomy_id = tt.term_taxonomy_id - WHERE p.post_type = %s AND p.post_status = %s - AND tt.taxonomy = %s AND tt.term_id = %d", - $post_type, - 'publish', - 'category', - $term->term_id - ) - ); - } else { - // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching - $posts = $wpdb->get_results( - $wpdb->prepare( - "SELECT ID, post_title, post_content FROM {$wpdb->posts} - WHERE post_type = %s AND post_status = %s", - $post_type, - 'publish' - ) - ); - } - - if ( empty( $posts ) ) { - return array( - 'success' => true, - 'post_type' => $post_type, - 'total_scanned' => 0, - 'total_links' => 0, - 'orphaned_count' => 0, - 'avg_outbound' => 0, - 'avg_inbound' => 0, - 'orphaned_posts' => array(), - 'top_linked' => array(), - '_all_links' => array(), - '_id_to_title' => array(), - ); - } - - // Build a lookup of all scanned post URLs -> IDs. - $url_to_id = array(); - $id_to_url = array(); - $id_to_title = array(); - - foreach ( $posts as $post ) { - $permalink = get_permalink( $post->ID ); - if ( $permalink ) { - $url_to_id[ untrailingslashit( $permalink ) ] = $post->ID; - $url_to_id[ trailingslashit( $permalink ) ] = $post->ID; - $id_to_url[ $post->ID ] = $permalink; - } - $id_to_title[ $post->ID ] = $post->post_title; - } - - // Scan each post's content for internal links. - $outbound = array(); // post_id => array of target post_ids. - $inbound = array(); // post_id => count of inbound links. - $all_links = array(); // all discovered internal link entries. - $total_links = 0; - - // Initialize inbound counts. - foreach ( $posts as $post ) { - $inbound[ $post->ID ] = 0; - $outbound[ $post->ID ] = array(); - } - - $all_external_links = array(); - - foreach ( $posts as $post ) { - $content = $post->post_content; - if ( empty( $content ) ) { - continue; - } - - // Internal links. - $links = self::extractInternalLinks( $content, $home_host ); - - foreach ( $links as $link_url ) { - ++$total_links; - $normalized = untrailingslashit( $link_url ); - - // Resolve to a post ID if possible. - $target_id = $url_to_id[ $normalized ] ?? $url_to_id[ trailingslashit( $link_url ) ] ?? null; - - if ( null === $target_id ) { - // Try url_to_postid as fallback for non-standard URLs. - $target_id = url_to_postid( $link_url ); - if ( 0 === $target_id ) { - $target_id = null; - } - } - - if ( null !== $target_id && $target_id !== $post->ID ) { - $outbound[ $post->ID ][] = $target_id; - - if ( isset( $inbound[ $target_id ] ) ) { - ++$inbound[ $target_id ]; - } - } - - $all_links[] = array( - 'source_id' => $post->ID, - 'target_url' => $link_url, - 'target_id' => $target_id, - 'resolved' => null !== $target_id, - ); - } - - // External links. - $external = self::extractExternalLinks( $content, $home_host ); - foreach ( $external as $ext_link ) { - $all_external_links[] = array( - 'source_id' => $post->ID, - 'target_url' => $ext_link['url'], - 'anchor_text' => $ext_link['anchor_text'], - 'domain' => $ext_link['domain'], - ); - } - } - - // Identify orphaned posts (zero inbound links from other scanned posts). - $orphaned = array(); - foreach ( $inbound as $post_id => $count ) { - if ( 0 === $count ) { - $orphaned[] = array( - 'post_id' => $post_id, - 'title' => $id_to_title[ $post_id ] ?? '', - 'permalink' => $id_to_url[ $post_id ] ?? '', - 'outbound' => count( $outbound[ $post_id ] ?? array() ), - ); - } - } - - // Top linked posts (most inbound). - arsort( $inbound ); - $top_linked = array(); - $top_count = 0; - foreach ( $inbound as $post_id => $count ) { - if ( 0 === $count || $top_count >= 20 ) { - break; - } - $top_linked[] = array( - 'post_id' => $post_id, - 'title' => $id_to_title[ $post_id ] ?? '', - 'permalink' => $id_to_url[ $post_id ] ?? '', - 'inbound' => $count, - 'outbound' => count( $outbound[ $post_id ] ?? array() ), - ); - ++$top_count; - } - - $total_scanned = count( $posts ); - $outbound_total = array_sum( array_map( 'count', $outbound ) ); - $inbound_total = array_sum( $inbound ); - - return array( - 'success' => true, - 'post_type' => $post_type, - 'total_scanned' => $total_scanned, - 'total_links' => $total_links, - 'orphaned_count' => count( $orphaned ), - 'avg_outbound' => $total_scanned > 0 ? round( $outbound_total / $total_scanned, 2 ) : 0, - 'avg_inbound' => $total_scanned > 0 ? round( $inbound_total / $total_scanned, 2 ) : 0, - 'orphaned_posts' => $orphaned, - 'top_linked' => $top_linked, - // Internal data for broken link checker (not exposed in REST). - '_all_links' => $all_links, - '_all_external_links' => $all_external_links, - '_id_to_title' => $id_to_title, - ); - } - - /** - * Extract internal link URLs from HTML content. - * - * Uses regex to find all tags where the href points to - * the same host as the site. Ignores anchors, mailto, tel, and external links. - * - * @since 0.32.0 - * - * @param string $html HTML content to parse. - * @param string $home_host Site hostname for comparison. - * @return array Array of internal link URLs. - */ - private static function extractInternalLinks( string $html, string $home_host ): array { - $links = array(); - - // Match all href attributes in anchor tags. - if ( ! preg_match_all( '/