get_error_data() : $vasp_error; $vasp_data = is_array($vasp_data) ? $vasp_data : []; $vasp_public = function_exists('vasp_error_public_data') ? vasp_error_public_data($vasp_data) : $vasp_data; $vasp_details = array_intersect_key($vasp_public, array_fill_keys([ 'transport_reason', 'timeout_seconds', 'status', 'method', 'validation_field', 'retryable', 'can_retry', 'supported_schema_versions', 'entity_type', 'entity_id', ], true)); if (isset($vasp_details['status']) && ((int) $vasp_details['status'] < 400 || (int) $vasp_details['status'] > 599)) { unset($vasp_details['status']); } if (isset($vasp_details['validation_field'])) { $vasp_details['validation_field'] = substr(sanitize_key((string) $vasp_details['validation_field']), 0, 80); } foreach (['retryable', 'can_retry'] as $vasp_retry_key) { if (array_key_exists($vasp_retry_key, $vasp_details)) { $vasp_details[$vasp_retry_key] = (bool) $vasp_details[$vasp_retry_key]; } } if (isset($vasp_details['supported_schema_versions'])) { $vasp_details['supported_schema_versions'] = array_slice(array_values(array_unique(array_filter( array_map('absint', (array) $vasp_details['supported_schema_versions']) ))), 0, 10); } if (($vasp_details['transport_reason'] ?? '') !== 'timeout') { unset($vasp_details['timeout_seconds']); } if ((is_wp_error($vasp_error) && in_array($vasp_error->get_error_code(), ['vasp_http_invalid_json', VASP_ERROR_INVALID_RESPONSE], true)) || ($vasp_data['reason'] ?? '') === 'invalid_response') { $vasp_details['reason'] = 'invalid_response'; } $vasp_steps = [ 'token_endpoint' => 'authentication', 'wordpress_ingestion_start_endpoint' => 'content_ingestion', 'wordpress_ingestion_progress_endpoint' => 'content_ingestion', 'ecommerce_catalog_products_endpoint' => 'products', 'ecommerce_catalog_product_sync_requests_endpoint' => 'reconciliation', 'ecommerce_catalog_image_sync_requests_endpoint' => 'image_audit', 'ecommerce_catalog_progress_endpoint' => 'catalog_processing', 'ecommerce_catalog_phase_endpoint' => 'acquisition', 'ecommerce_catalog_complete_endpoint' => 'catalog_processing', 'ecommerce_catalog_store_endpoint' => 'store', 'ecommerce_catalog_brands_endpoint' => 'brands', 'ecommerce_catalog_categories_endpoint' => 'categories', 'ecommerce_catalog_tags_endpoint' => 'tags', 'ecommerce_catalog_attributes_endpoint' => 'attributes', 'ecommerce_catalog_object_ids_endpoint' => 'reconciliation', 'ecommerce_catalog_images_endpoint' => 'images', 'events_batch_endpoint' => 'events', ]; $vasp_endpoint = (string) ($vasp_data['endpoint'] ?? ''); $vasp_step = $vasp_steps[$vasp_endpoint] ?? sanitize_key((string) ($vasp_data['step'] ?? '')); if ($vasp_step !== '') { $vasp_details['step'] = substr($vasp_step, 0, 64); } $vasp_files = array_merge( [(string) ($vasp_data['image_file'] ?? '')], is_array($vasp_data['image_files'] ?? null) ? $vasp_data['image_files'] : [] ); $vasp_files = array_values(array_unique(array_filter(array_map(static function ($vasp_file): string { return sanitize_text_field(substr(basename(str_replace('\\', '/', (string) $vasp_file)), 0, 180)); }, array_slice($vasp_files, 0, 10))))); if ($vasp_files && in_array($vasp_details['step'] ?? '', ['catalog_payload', 'image_download', 'images'], true)) { $vasp_details['image_files'] = $vasp_files; } $vasp_image_ids = is_array($vasp_data['image_ids'] ?? null) ? $vasp_data['image_ids'] : []; $vasp_image_ids = array_values(array_unique(array_filter(array_map('absint', array_slice($vasp_image_ids, 0, 10))))); if ($vasp_image_ids && in_array($vasp_details['step'] ?? '', ['catalog_payload', 'image_download', 'images'], true)) { $vasp_details['image_ids'] = $vasp_image_ids; } $vasp_entity_type = sanitize_key((string) ($vasp_data['entity_type'] ?? '')); if ($vasp_entity_type === '' && is_array($vasp_data['product_ids'] ?? null)) { $vasp_entity_type = 'product'; } $vasp_entity_ids = array_merge( [(string) ($vasp_data['entity_id'] ?? '')], is_array($vasp_data['entity_ids'] ?? null) ? $vasp_data['entity_ids'] : [], is_array($vasp_data['product_ids'] ?? null) ? $vasp_data['product_ids'] : [] ); $vasp_entity_ids = array_values(array_unique(array_filter(array_map(static function ($vasp_id): string { return substr(sanitize_text_field((string) $vasp_id), 0, 80); }, array_slice($vasp_entity_ids, 0, 10))))); if ($vasp_entity_ids) { $vasp_details[$vasp_entity_type === 'product' ? 'product_ids' : 'entity_ids'] = $vasp_entity_ids; } unset($vasp_details['entity_type'], $vasp_details['entity_id']); return $vasp_details; } /** Resolve the affected product edit link for an administrator-facing warning. */ function vasp_error_affected_product(array $vasp_details): array { $vasp_product_id = absint($vasp_details['product_ids'][0] ?? 0); if ($vasp_product_id <= 0) { return []; } $vasp_product_name = function_exists('get_the_title') ? trim((string) get_the_title($vasp_product_id)) : ''; $vasp_product_url = function_exists('get_edit_post_link') ? (string) get_edit_post_link($vasp_product_id, '') : ''; if ($vasp_product_url === '') { return []; } return [ 'label' => $vasp_product_name !== '' ? $vasp_product_name : sprintf( /* translators: %d: WooCommerce product ID. */ __('Product %d', 'valuespace'), $vasp_product_id ), 'url' => $vasp_product_url, ]; } /** Build one locale-independent record for the latest integration failure. */ function vasp_build_error_record($technical_error_code, $technical_message, $integration, $step = '', array $technical_details = []): array { $vasp_integration = sanitize_key((string) $integration); if (!in_array($vasp_integration, ['valuespace', 'wordpress', 'woocommerce', 'catalog_sync'], true)) { $vasp_integration = 'valuespace'; } $vasp_code = substr(sanitize_key((string) $technical_error_code), 0, 64); if ($vasp_code === '') { $vasp_code = VASP_USER_ERROR_UNKNOWN; } $vasp_mapped = vasp_map_error_to_user_friendly($vasp_code, $technical_message, $vasp_integration); $vasp_details = vasp_error_safe_details($technical_details); $vasp_step = substr(sanitize_key((string) $step), 0, 64); if ($vasp_step === '' && !empty($vasp_details['step'])) { $vasp_step = $vasp_details['step']; } $vasp_can_retry = !empty($vasp_mapped['can_retry']); if (array_key_exists('retryable', $vasp_details)) { $vasp_can_retry = $vasp_details['retryable']; } if (array_key_exists('can_retry', $vasp_details)) { $vasp_can_retry = $vasp_details['can_retry']; } $vasp_record = [ 'timestamp' => time(), 'integration' => $vasp_integration, 'step' => $vasp_step, 'category' => $vasp_mapped['category'], 'can_retry' => $vasp_can_retry, 'technical_code' => $vasp_code, ]; if ($vasp_details) { $vasp_record['error_details'] = $vasp_details; } return $vasp_record; } /** Persist an already normalized record in the existing integration-owned option. */ function vasp_store_error_record(array $vasp_record): bool { $vasp_options = [ 'valuespace' => VASP_VALUESPACE_LAST_ERROR, 'wordpress' => VASP_WORDPRESS_LAST_ERROR, 'woocommerce' => VASP_WOOCOMMERCE_LAST_ERROR, 'catalog_sync' => VASP_OPTION_WC_CATALOG_LAST_ERROR, ]; $vasp_option = $vasp_options[$vasp_record['integration'] ?? ''] ?? ''; if ($vasp_option === '') { return false; } $vasp_encoded = wp_json_encode($vasp_record); if (get_option($vasp_option, null) === $vasp_encoded) { return true; } $vasp_stored = update_option($vasp_option, $vasp_encoded, false); if (!$vasp_stored) { vasp_log('Integration error state could not be persisted', 'error', [ 'integration' => sanitize_key((string) ($vasp_record['integration'] ?? '')), 'error_code' => sanitize_key((string) ($vasp_record['technical_code'] ?? '')), ]); } return (bool) $vasp_stored; } /** Store safe failure state without creating another log entry. */ function vasp_store_user_friendly_error($technical_error_code, $technical_message, $integration, $step = '', array $technical_details = []): bool { return vasp_store_error_record(vasp_build_error_record( $technical_error_code, $technical_message, $integration, $step, $technical_details )); } /** Classify once, log once, and persist the same record. */ function vasp_record_user_friendly_error($technical_error_code, $technical_message, $integration, $step = '', array $technical_details = []): bool { $vasp_record = vasp_build_error_record( $technical_error_code, $technical_message, $integration, $step, $technical_details ); vasp_log('Integration operation failed', 'error', [ 'integration' => $vasp_record['integration'], 'error_code' => $vasp_record['technical_code'], 'category' => $vasp_record['category'], ]); return vasp_store_error_record($vasp_record); } /** Explain transport facts in human terms without exposing protocol codes. */ function vasp_error_diagnostic_description(string $vasp_code, array $vasp_mapped, array $vasp_details): string { $vasp_status = (int) ($vasp_details['status'] ?? 0); $vasp_step = (string) ($vasp_details['step'] ?? ''); if ($vasp_step === 'image_download' && in_array($vasp_status, [404, 410], true)) { return __('WordPress could not find the product image file selected for synchronization.', 'valuespace'); } if ($vasp_step === 'image_download' && in_array($vasp_status, [401, 403], true)) { return __('WordPress could not access the product image file selected for synchronization.', 'valuespace'); } if ($vasp_step === 'images' && $vasp_status === 413) { return __('WordPress could not prepare a product image within the upload size limit.', 'valuespace'); } switch ($vasp_details['transport_reason'] ?? '') { case 'timeout': return __('The connection to ValueSpace AI timed out during synchronization.', 'valuespace'); case 'dns': return __('WordPress could not find the ValueSpace server.', 'valuespace'); case 'connection': return __('WordPress could not establish a connection to ValueSpace.', 'valuespace'); case 'tls': return __('WordPress could not establish a secure connection to ValueSpace.', 'valuespace'); } $vasp_mapping = vasp_get_error_mapping(); if (isset($vasp_mapping[$vasp_code])) { return (string) ($vasp_mapped['diagnostic'] ?? $vasp_mapped['description']); } if ($vasp_status === 429) { return __('ValueSpace temporarily limited this synchronization request.', 'valuespace'); } if (in_array($vasp_status, [401, 403], true)) { return __('This synchronization operation was not allowed.', 'valuespace'); } if ($vasp_status >= 500) { return __('This synchronization request could not be processed.', 'valuespace'); } return (string) ($vasp_mapped['diagnostic'] ?? $vasp_mapped['description']); } /** Project the stored state for either the concise alert or detailed System Info surface. */ function vasp_format_error_for_display($error_data, string $surface = 'alert') { if (empty($error_data) || !is_array($error_data)) { return null; } $vasp_code = substr(sanitize_key((string) ($error_data['technical_code'] ?? '')), 0, 64); $vasp_integration = sanitize_key((string) ($error_data['integration'] ?? 'valuespace')); $vasp_details = vasp_error_safe_details($error_data['error_details'] ?? []); $vasp_mapped = vasp_map_error_to_user_friendly($vasp_code, '', $vasp_integration); $vasp_description = $surface === 'system_info' ? vasp_error_diagnostic_description($vasp_code, $vasp_mapped, $vasp_details) : (string) $vasp_mapped['description']; $vasp_can_retry = array_key_exists('can_retry', $error_data) ? (bool) $error_data['can_retry'] : !empty($vasp_mapped['can_retry']); if (!array_key_exists('can_retry', $error_data) && array_key_exists('retryable', $vasp_details)) { $vasp_can_retry = (bool) $vasp_details['retryable']; } if (!array_key_exists('can_retry', $error_data) && array_key_exists('can_retry', $vasp_details)) { $vasp_can_retry = (bool) $vasp_details['can_retry']; } $vasp_display = [ 'system' => vasp_get_integration_display_name($vasp_integration), 'outcome' => vasp_get_outcome_label($vasp_mapped['category']), 'category' => $vasp_mapped['category'], 'technical_code' => $vasp_code, 'description' => $vasp_description, 'hint' => (string) $vasp_mapped['hint'], 'can_retry' => $vasp_can_retry, 'timestamp' => max(0, (int) ($error_data['timestamp'] ?? 0)), 'step' => substr(sanitize_key((string) ($error_data['step'] ?? ($vasp_details['step'] ?? ''))), 0, 64), 'details' => $vasp_details, ]; if ($surface === 'alert' && function_exists('vasp_is_catalog_image_source_error') && vasp_is_catalog_image_source_error($vasp_code)) { $vasp_display['affected_product'] = vasp_error_affected_product($vasp_details); } return $vasp_display; }