false, 'error' => 'WooCommerce is not active.', ]; } if ( ! $product_id ) { return [ 'ok' => false, 'error' => 'No product_id was provided. Call wc-product-search first to get a valid product id, then retry with it.', ]; } // \Throwable, not \Exception: a bad WC call can raise a PHP Error that would otherwise crash the agent turn. try { // JSON string in the schema (Gemini rejects dynamic key/value maps); also accept a raw array. $variation_attrs = $this->normalize_variation_attrs( $variation_attrs ); // Clamp to a sane range and tell the model when it was clamped, rather than silently coercing. $requested_qty = $quantity ?? 1; $qty = max( 1, min( 99, $requested_qty ) ); $qty_note = ( $requested_qty > 99 || $requested_qty < 1 ) ? sprintf( 'Requested quantity %d was clamped to %d.', $requested_qty, $qty ) : ''; $parent = wc_get_product( $product_id ); if ( ! $parent ) { return [ 'ok' => false, 'error' => 'Product #' . $product_id . ' not found or is no longer published. Call wc-product-search again to get a valid product id.', ]; } // The parent still passes is_purchasable()/is_in_stock() with no variation resolved; force one first. if ( $parent->is_type( 'variable' ) && ! $variation_id && empty( $variation_attrs ) ) { return [ 'ok' => false, 'error' => 'This is a variable product with multiple options (e.g. color, size). The shopper must choose a specific variation before it can be added to cart. Ask the shopper which option they prefer.', ]; } if ( $variation_id || ! empty( $variation_attrs ) ) { if ( ! $parent->is_type( 'variable' ) ) { return [ 'ok' => false, 'error' => 'Variation does not belong to a variable product.', ]; } if ( ! $variation_id && ! empty( $variation_attrs ) ) { $variation_id = $parent->find_matching_product_variation( $variation_attrs ); if ( ! $variation_id ) { return [ 'ok' => false, 'error' => 'No matching variation found for the provided attributes. Ask the shopper which option they want (e.g. color, size), or call wc-product-search to see the available variations, or pass variation_id directly.', ]; } } $variation = wc_get_product( $variation_id ); if ( ! $variation || ! $variation->is_type( 'variation' ) ) { return [ 'ok' => false, 'error' => 'Invalid variation.', ]; } if ( (int) $variation->get_parent_id() !== (int) $product_id ) { return [ 'ok' => false, 'error' => 'Variation does not belong to this product.', ]; } $product = $variation; } else { $product = $parent; } if ( ! $product->is_purchasable() ) { return [ 'ok' => false, 'error' => 'Product is not purchasable.', ]; } if ( ! $product->is_in_stock() ) { return [ 'ok' => false, 'error' => 'Product is out of stock.', ]; } if ( $product->managing_stock() && $product->get_stock_quantity() !== null && $product->get_stock_quantity() < $qty ) { return [ 'ok' => false, 'error' => 'Insufficient stock. Available: ' . $product->get_stock_quantity() . ', requested: ' . $qty . '. Ask the shopper if they would like a smaller quantity.', ]; } $image_id = $product->get_image_id(); $image_url = $image_id ? wp_get_attachment_image_url( $image_id, 'woocommerce_thumbnail' ) : ''; $response = [ 'ok' => true, 'action_card' => 'add_to_cart', 'cart_action_payload' => [ 'product_id' => $product_id, 'quantity' => $qty, 'variation_id' => $variation_id, ], 'product_summary' => [ 'id' => $product->get_id(), 'name' => $product->get_title(), 'price_html' => $product->get_price_html(), 'image_url' => $image_url, 'stock_status' => $product->get_stock_status(), 'in_stock' => $product->is_in_stock(), ], 'reason' => $reason, ]; if ( '' !== $qty_note ) { $response['note'] = $qty_note; } return $response; } catch ( \Throwable $e ) { return [ 'ok' => false, 'error' => 'Cart validation failed: ' . $e->getMessage() . '. Try again or suggest the shopper add the product from the product page.', ]; } } /** * Normalize the variation_attrs input to a key/value array WooCommerce accepts. * * find_matching_product_variation() requires `attribute_`-prefixed, slug-cased keys/values, unlike the unprefixed names from Wc_Product_Search_Tool::format_variations. * * @param mixed $raw JSON object string or associative array. * @return array */ private function normalize_variation_attrs( $raw ): array { $decoded = []; if ( is_array( $raw ) ) { $decoded = $raw; } elseif ( is_string( $raw ) && '' !== trim( $raw ) ) { $maybe = json_decode( $raw, true ); if ( is_array( $maybe ) ) { $decoded = $maybe; } } $remapped = []; foreach ( $decoded as $key => $value ) { if ( ! is_string( $key ) ) { continue; } // Strip any pre-existing prefix first so we never build `attribute_attribute_`. $clean_key = preg_replace( '/^attribute_/', '', $key ); $remapped[ 'attribute_' . sanitize_title( $clean_key ) ] = sanitize_title( (string) $value ); } return $remapped; } }