<?php
namespace WPForms\Integrations\AI\API;
use WPForms\Integrations\AI\API\Http\Response;
/**
* AI Chat middleware client.
*
* POSTs the assembled context to the universal `/api/v1/ai-chat` endpoint.
* Receives either a final `message` envelope or a `tool_calls` directive —
* the caller (AJAX handler) drives the round loop.
*
* @since 2.0.0
*/
class Chat extends API {
/**
* Universal chat endpoint path. Leading slash is required — `Request::get_request_url()`
* concatenates `self::URL . $endpoint`.
*
* @since 2.0.0
*/
private const ENDPOINT = '/ai-chat';
/**
* POST a chat request and return the decoded response.
*
* The middleware dispatches on a required `mode` field: `'classify'` picks
* the minimum scope set needed for the user's question, `'answer'` (with
* possible `tool_calls` sub-rounds) produces the final reply. Callers run
* classify once per user turn, then answer rounds until a terminal `message`.
*
* @since 2.0.0
*
* @param array $context Assembled context payload.
* @param string $user_prompt The user's prompt for this exchange.
* @param string $session_id Per-page-load session identifier.
* @param array $history Conversation history (role/content pairs).
* @param string $batch_id Empty on the first call; echoed back on follow-ups to claim rate-limit exemption.
* @param string $mode Round discriminator — `'classify'` or `'answer'`.
* @param string $reclassify_hint Scope hint from a prior reclassify tool call. Only meaningful for classify mode.
*
* @return array
*/
public function chat(
array $context,
string $user_prompt,
string $session_id,
array $history,
string $batch_id = '',
string $mode = 'answer',
string $reclassify_hint = ''
): array {
$body = [
'mode' => $mode,
'userPrompt' => $user_prompt,
'scopes' => $context['scopes'] ?? [],
'availableScopes' => $context['availableScopes'] ?? [],
'context' => $context,
'history' => $history,
'sessionId' => $session_id,
];
if ( $reclassify_hint !== '' ) {
$body['reclassifyHint'] = $reclassify_hint;
}
$response = $this->request->post( self::ENDPOINT, $body, $this->build_request_headers( $batch_id ) );
if ( $response->has_errors() ) {
return $this->build_error_response( $response );
}
return wp_parse_args( $response->get_body(), $this->response_defaults() );
}
/**
* Build the request headers for a chat request.
*
* Batch ID propagates the classify round's `responseId` to the answer round
* via the `x-wpforms-batch-id` request header — middleware uses it to claim
* the rate-limit exemption granted by the prior classify.
*
* @since 2.0.0
*
* @param string $batch_id Batch ID from the prior classify round; empty to omit the header.
*
* @return array Request headers.
*/
private function build_request_headers( string $batch_id ): array {
$headers = [];
if ( $batch_id !== '' ) {
$headers['x-wpforms-batch-id'] = $batch_id;
}
return $headers;
}
/**
* Build the error response envelope from a failed request.
*
* @since 2.0.0
*
* @param Response $response Failed API response.
*
* @return array
*/
private function build_error_response( Response $response ): array {
$error_data = $response->get_error_data();
return array_merge(
$this->response_defaults(),
[
'error' => (string) ( $error_data['error'] ?? '' ),
'error_code' => (int) ( $error_data['code'] ?? 0 ),
]
);
}
/**
* The canonical chat response shape, with every field defaulting to null.
*
* Shared by the success path (as `wp_parse_args` defaults) and the error path
* so both return the same key set.
*
* @since 2.0.0
*
* @return array
*/
private function response_defaults(): array {
return [
'message' => null,
'tool_calls' => null,
'error' => null,
'sessionId' => null,
'responseId' => null,
'selectedScopes' => null,
];
}
}