'invalid_response', 'endpoint' => $endpoint, 'method' => $method] ); } $data = is_array($response['data'] ?? null) ? $response['data'] : []; $errors = []; if (isset($data['errors']) && is_array($data['errors'])) { $errors = $data['errors']; } elseif (isset($response['errors']) && is_array($response['errors'])) { $errors = $response['errors']; } if (($response['success'] ?? null) !== true || !empty($errors)) { $first_error = is_array($errors[0] ?? null) ? $errors[0] : []; $error_code = sanitize_key((string) ($first_error['code'] ?? 'catalog_upload_failed')); if ($error_code === '' || strlen($error_code) > 64) { $error_code = 'catalog_upload_failed'; } return vasp_create_error(VASP_ERROR_API_RESPONSE_ERROR, [ 'error_code' => $error_code, 'endpoint' => $endpoint, 'method' => strtoupper($method), ]); } return $response; } function vasp_wc_catalog_store_settings_payload(): array { $currency_code = (string) get_option('woocommerce_currency', ''); if ($currency_code === '' && function_exists('get_woocommerce_currency')) { $currency_code = (string) get_woocommerce_currency(); } return [ 'currencyCode' => strtoupper(trim($currency_code)), 'currencyPosition' => (string) get_option('woocommerce_currency_pos', 'left'), 'decimalSeparator' => (string) get_option('woocommerce_price_decimal_sep', '.'), 'thousandSeparator' => (string) get_option('woocommerce_price_thousand_sep', ','), 'decimalDigits' => (int) get_option('woocommerce_price_num_decimals', 2), 'country' => (string) get_option('woocommerce_default_country', ''), 'addressLine1' => (string) get_option('woocommerce_store_address', ''), 'addressLine2' => (string) get_option('woocommerce_store_address_2', ''), 'city' => (string) get_option('woocommerce_store_city', ''), 'postcode' => (string) get_option('woocommerce_store_postcode', ''), ]; } function vasp_wc_catalog_retry_after_seconds(WP_Error $error, int $default = 15): int { $data = $error->get_error_data(); $seconds = is_array($data) ? (int) ($data['retry_after'] ?? ($data['retryAfterSeconds'] ?? 0)) : 0; return max(1, min(300, $seconds > 0 ? $seconds : $default)); } /** Read the one synchronization snapshot used by both WordPress and the dashboard. */ function vasp_wc_catalog_read_progress() { $response = vasp_wc_catalog_validate_response( vasp_api_request( 'ecommerce_catalog_progress_endpoint', 'GET', [], [], [], 'application/json', 20 ), 'ecommerce_catalog_progress_endpoint', 'GET' ); if (is_wp_error($response)) { return $response; } $data = is_array($response['data'] ?? null) ? $response['data'] : []; $status = sanitize_key((string) ($data['status'] ?? '')); if (!in_array($status, ['in_progress', 'completed', 'failed'], true)) { return vasp_create_error( VASP_ERROR_INVALID_RESPONSE, [ 'error_code' => 'invalid_response', 'endpoint' => 'ecommerce_catalog_progress_endpoint', 'reason' => 'invalid_catalog_progress', ] ); } $data['status'] = $status; return $data; } function vasp_wc_catalog_project_server_progress(array $local, array $server): array { $local_status = (string) ($local['status'] ?? 'not_started'); $server_status = sanitize_key((string) ($server['status'] ?? '')); $server_step = sanitize_key((string) ($server['step'] ?? '')); $server_owned = ($server_status === 'in_progress' && (($server['phase'] ?? '') === 'catalog_enrichment' || get_option(VASP_OPTION_WC_CATALOG_PENDING_MODE, '') !== '')) || !in_array($local_status, ['pending', 'started', 'in_progress'], true); if (!$server_owned || $local_status === 'failed' || $local_status === 'disabled') { return $local; } $projection = $local; $projection['activitySource'] = 'valuespace'; $projection['pipeline'] = sanitize_key((string) ($server['phase'] ?? '')); $projection['stage'] = $server_step; $projection['status'] = $server_status; $ai_execution_mode = sanitize_key((string) ($server['aiExecutionMode'] ?? 'none')); $projection['aiExecutionMode'] = $ai_execution_mode; $projection['isDeterminate'] = in_array($ai_execution_mode, ['direct', 'simulation'], true); $projection['startedAt'] = sanitize_text_field((string) ($server['startedAt'] ?? '')) ?: null; $projection['completedAt'] = sanitize_text_field((string) ($server['lastCompletedAt'] ?? '')) ?: null; if ($server_status === 'failed') { $error = is_array($server['error'] ?? null) ? $server['error'] : []; $projection['error_code'] = sanitize_key((string) ($error['code'] ?? 'catalog_synchronization_failed')); $mapped = function_exists('vasp_map_error_to_user_friendly') ? vasp_map_error_to_user_friendly($projection['error_code'], '', 'catalog_sync') : []; $projection['error'] = (string) ($mapped['description'] ?? __('The catalog update could not be completed.', 'valuespace')); $projection['error_hint'] = (string) ($mapped['hint'] ?? __('Retry the update.', 'valuespace')); $projection['can_retry'] = !empty($mapped['can_retry']); } $processed = $server['processedItems'] ?? null; $total = $server['totalItems'] ?? null; $failed = $server['failedItems'] ?? null; $projection['processed'] = is_numeric($processed) ? max(0, (int) $processed) : null; $projection['total'] = is_numeric($total) ? max(0, (int) $total) : null; $projection['failed'] = is_numeric($failed) ? max(0, (int) $failed) : null; $projection['progress'] = is_numeric($total) && (int) $total > 0 && is_numeric($processed) ? min(100, (int) floor(100 * (int) $processed / (int) $total)) : null; return $projection; } /** Return Gateway's canonical receipt time only for a complete packet acknowledgement. */ function vasp_wc_catalog_received_at($vasp_response, int $vasp_count, string $vasp_endpoint) { $vasp_response = vasp_wc_catalog_validate_response($vasp_response, $vasp_endpoint, 'POST'); if (is_wp_error($vasp_response)) { return $vasp_response; } $vasp_data = is_array($vasp_response['data'] ?? null) ? $vasp_response['data'] : []; $vasp_received = trim((string) ($vasp_data['receivedAt'] ?? '')); if ((int) ($vasp_data['receivedCount'] ?? -1) !== $vasp_count || $vasp_received === '' || strtotime($vasp_received) === false) { return vasp_create_error(VASP_ERROR_INVALID_RESPONSE, [ 'user_message' => __('Receipt of all catalog data could not be confirmed.', 'valuespace'), ]); } return $vasp_received; } /** Retry explicit temporary destination failures; uncertain/source failures stop the feed. */ function vasp_wc_catalog_failure_is_retryable_delivery(WP_Error $vasp_error): bool { $vasp_data = $vasp_error->get_error_data(); if (!is_array($vasp_data)) { return false; } if (array_key_exists('can_retry', $vasp_data)) { return (bool) $vasp_data['can_retry']; } if (array_key_exists('retryable', $vasp_data)) { return (bool) $vasp_data['retryable']; } return in_array((int) ($vasp_data['status'] ?? 0), [429, 503], true); } function vasp_wc_catalog_delivery_waiting(int $vasp_delay): array { return ['pending' => true, 'status' => 'waiting', 'delay' => max(1, $vasp_delay)]; } function vasp_wc_catalog_can_push_delta(): bool { return vasp_wc_catalog_push_enabled() && vasp_woocommerce_sync_is_available(); } /** Report acquisition progress or its bounded terminal outcome. */ function vasp_wc_catalog_signal_phase( string $vasp_stage, ?int $vasp_total_items = null, string $vasp_outcome = '', string $vasp_failure_area = '', bool $vasp_restart = false, ?int $vasp_processed_items = null ) { $vasp_stages = [ 'select_products', 'select_images', 'snapshot_store', 'snapshot_categories', 'snapshot_tags', 'snapshot_attributes', 'snapshot_brands', 'deliver_products', 'deliver_images', ]; if (!in_array($vasp_stage, $vasp_stages, true)) { vasp_log('Catalog acquisition phase signal was rejected locally; delivery continues', 'warning', [ 'stage' => sanitize_key($vasp_stage), 'error_code' => 'invalid_phase', ]); return vasp_wc_catalog_storage_error('invalid_acquisition_phase'); } $vasp_failure_areas = ['store', 'categories', 'tags', 'attributes', 'brands', 'products', 'images']; if (($vasp_outcome !== '' && $vasp_outcome !== 'failed') || ($vasp_failure_area !== '' && !in_array($vasp_failure_area, $vasp_failure_areas, true))) { vasp_log('Catalog acquisition outcome signal was rejected locally', 'warning', [ 'stage' => $vasp_stage, 'error_code' => 'invalid_outcome', ]); return vasp_wc_catalog_storage_error('invalid_acquisition_outcome'); } // A short ordered request prevents later phases overtaking earlier ones. // Failures contain only bounded public classifications; the server owns the run. $vasp_payload = [ 'stage' => $vasp_stage, 'trigger' => function_exists('vasp_wc_catalog_active_trigger') ? vasp_wc_catalog_active_trigger() : 'realtime', ]; if ($vasp_total_items !== null) { $vasp_payload['totalItems'] = max(0, $vasp_total_items); } if ($vasp_processed_items !== null) { $vasp_payload['processedItems'] = max(0, $vasp_processed_items); } if ($vasp_outcome !== '') { $vasp_payload['outcome'] = $vasp_outcome; } if ($vasp_failure_area !== '') { $vasp_payload['failureArea'] = $vasp_failure_area; } if ($vasp_restart) { $vasp_payload['restart'] = true; } vasp_log('WC Catalog Sync: sending acquisition phase', 'debug', [ 'stage' => $vasp_stage, 'total_items' => $vasp_total_items, 'processed_items' => $vasp_processed_items, 'restart' => $vasp_restart, 'trigger' => $vasp_payload['trigger'], 'outcome' => $vasp_outcome === '' ? 'active' : $vasp_outcome, ]); $vasp_result = vasp_wc_catalog_validate_response(vasp_api_request( 'ecommerce_catalog_phase_endpoint', 'POST', $vasp_payload, [], [], 'application/json', 3 ), 'ecommerce_catalog_phase_endpoint', 'POST'); if (is_wp_error($vasp_result)) { vasp_log('Catalog acquisition phase signal failed', 'warning', [ 'stage' => $vasp_stage, 'error_code' => $vasp_result->get_error_code(), ]); return true; } vasp_log('WC Catalog Sync: acquisition phase accepted', 'debug', [ 'stage' => sanitize_key((string) ($vasp_result['data']['stage'] ?? $vasp_stage)), 'status' => sanitize_key((string) ($vasp_result['data']['status'] ?? 'accepted')), ]); return $vasp_result; } /** Best-effort terminal signal; local error handling remains authoritative for WordPress. */ function vasp_wc_catalog_signal_failure(string $vasp_stage, string $vasp_failure_area = ''): void { vasp_wc_catalog_signal_phase($vasp_stage, null, 'failed', $vasp_failure_area); } function vasp_wc_catalog_request_delivery_completion() { $vasp_response = vasp_wc_catalog_validate_response(vasp_api_request( 'ecommerce_catalog_complete_endpoint', 'POST', [], [], [], 'application/json', 30 ), 'ecommerce_catalog_complete_endpoint', 'POST'); if (is_wp_error($vasp_response)) { return $vasp_response; } $vasp_data = is_array($vasp_response['data'] ?? null) ? $vasp_response['data'] : []; $vasp_status = sanitize_key((string) ($vasp_data['status'] ?? '')); if (in_array($vasp_status, ['started', 'up_to_date'], true)) { return ['status' => $vasp_status]; } return vasp_create_error(VASP_ERROR_INVALID_RESPONSE, [ 'endpoint' => 'ecommerce_catalog_complete_endpoint', 'reason' => 'invalid_catalog_completion_status', ]); } /** Commit the local handoff after every catalog object has been acknowledged. */ function vasp_wc_catalog_complete_delivery() { $vasp_complete = vasp_wc_catalog_request_delivery_completion(); if (is_wp_error($vasp_complete)) { return $vasp_complete; } update_option(VASP_OPTION_WC_CATALOG_STATUS, 'completed', false); $vasp_progress = get_option(VASP_OPTION_WC_CATALOG_PROGRESS, []); if (empty($vasp_progress['imageSourceIssueCount'])) { delete_option(VASP_OPTION_WC_CATALOG_LAST_ERROR); } if (($vasp_complete['status'] ?? '') === 'up_to_date') { update_option(VASP_OPTION_WC_CATALOG_SYNC_COMPLETED_TIME, time(), false); } delete_option(VASP_OPTION_WC_CATALOG_STEP); if (get_option(VASP_OPTION_WC_CATALOG_PENDING_MODE, '') !== '' || vasp_wc_catalog_pending_count() > 0) { return vasp_wc_catalog_queue( (string) get_option(VASP_OPTION_WC_CATALOG_PENDING_MODE, 'realtime') ); } return true; }