@automattic/jetpack-ai-client 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.2] - 2023-08-07
+### Added
+- AI Assistant: add options parameter to request function on useAiSuggestions hook [#32198]
+- AI Client: add @wordpress/compose dependency [#32228]
+- AI Client: add clear button in AI Control component [#32274]
+- AI Client: add keyboard shortcut to AIControl [#32239]
+- AI Client: add onError() response support [#32223]
+- AI Client: export types [#32209]
+- AI Client: start supporting request options on requestSuggestion callback. [#32303]
+- AI Control: introduce AiStatusIndicator component [#32258]
+
+### Changed
+- AI Client: complete/update/improve doc [#32311]
+- AI Client: rename the prop name of the requesting state of the AiStatusIndicator component [#32279]
+
+### Fixed
+- AI Client: Fix wrong disabled state condition. [#32210]
+
 ## [0.1.1] - 2023-08-01
 ### Added
 - Add AI Client icon components [#32079]
@@ -36,4 +54,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated package dependencies. [#31659]
 - Updated package dependencies. [#31785]
 
+[0.1.2]: https://github.com/Automattic/jetpack-ai-client/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/Automattic/jetpack-ai-client/compare/v0.1.0...v0.1.1

package/README.md

@@ -10,118 +10,40 @@ To install the Jetpack AI Client, clone the repository to your local machine and
 npm install @automattic/jetpack-ai-client
 ```
 
-## Usage
+## Libraries & Components
 
-### Example
+### Requesting
 
-```
-import { requestCompletion } from '@automattic/jetpack-ai-client';
-
-const MyComp = ( props ) => {
-  const [ completion, setCompletion ] = useState( '' );
-
-  const newHaiku = async () => {
-    const eventSource = await requestCompletion( 'Write a haiku about WordPress' );
-      eventSource.addEventListener( 'suggestion',  answer => setCompletion( answer.detail ) );
-      eventSource.addEventListener( 'done', event => {
-        console.log( "Full completion", event.detail );
-      } );
-
-      eventSource.addEventListener( 'suggestion', event => {
-        console.log( "Received so far", event.detail );
-      } );
-
-      eventSource.addEventListener( 'error_quota_exceeded', event => {
-        console.log( "You reached the AI query quota for your current plan.", event.detail );
-      } );
-  };
-
-  return (
-    <div>
-      <div> { completion } </div>
-      <button onClick={ newHaiku }>Get new Haiku</button>
-    </div>
-  )
-};
-```
-
-### Requesting a Completion from the Jetpack AI API
-
-You can request a completion from the Jetpack AI API using the `requestCompletion` function. This function takes a prompt and optionally a post ID as parameters and returns an instance of `SuggestionsEventSource`.
-
-```
-import { requestCompletion } from '@automattic/jetpack-ai-client';
-
-// postId is the post where the request is being triggered
-// It's only used for loggin purposes and can be omitted.
-const postId = 123;
-const eventSource = requestCompletion( 'A haiku', postId ))
-
-eventSource.addEventListener('done', event => {
-  console.log( "Full completion", event.detail );
-} );
-
-eventSource.addEventListener('suggestion', event => {
-  console.log( "Received so far", event.detail );
-} );
-```
+#### [askQuestion](./src/ask-question/Readme.md) helper
+Async function that sends a question and optional configurations, retrieves a JWT token, and returns a [SuggestionsEventSource](./src/suggestions-event-source/Readme.md) instance.
 
-### Requesting Images from the Jetpack AI API
+#### [SuggestionsEventSouce](./src/suggestions-event-source/Readme.md) Class
 
-You can fetch images from Jetpack AI using the `requestImages` function. This function takes a prompt and a post ID as parameters and returns a promise that resolves to an array of base64 encoded images.
+Class that connects to an AI model to receive and emit suggestion streams, using EventTarget for handling data chunks.
 
-```
-import { requestImages } from '@automattic/jetpack-ai-client';
-
-requestImages( 'a flower', postId )
-  .then( images => {
-    document.getElementById("imgid").src= image[0]
-  } )
-  .catch( error => {
-    // Handle the error
-  } );
-```
-
-### Using the SuggestionsEventSource Class
-
-The `SuggestionsEventSource` class is a wrapper around `EventSource` that emits events for each chunk of data received, when the stream is closed, and when a full suggestion has been received.
-
-You shouldn't need to instantiate this class. You get one of these by calling `requestCompletion()`.
+#### [useAiSuggestions](./src/hooks/use-ai-suggestions/Readme.md) hook
 
-```
-import { requestCompletion } from '@automattic/jetpack-ai-client';
+A custom React hook that obtains suggestions from an AI by hitting a specific query endpoint.
 
-const eventSource = new SuggestionsEventSource( url );
+#### [JWT](./src/jwt/Readme.md) helper
 
-eventSource.addEventListener( 'done', event => {
-  console.log( "Full completion", event.detail );
-} );
+Library to manage JWT tokens for Jetpack AI across various site types, handling acquisition, caching in localStorage, expiration, and customization of request options.
 
-eventSource.addEventListener( 'suggestion', event => {
-  console.log( "Received so far", event.detail );
-} );
-```
+#### [Data Flow](./src/data-flow/Readme.md) implementation
 
-### Requesting a Token from the Jetpack Site
+Data Flow offers a streamlined way to manage an AI Assistant's state and functionality within a React app, using React context, HOCs, and custom hooks to handle suggestions, errors, and requests.
 
-You can request a token from the Jetpack site using the `requestCompletionAuthToken` function. This function returns a promise that resolves to an object containing the token and the blogId.
+### [Components](./src/components/)
 
-This function behaves properly whether it's called from a Jetpack environment or a WordPress.com one.
+#### [AIControl](./src/components/ai-control/Readme.md)
 
-```
-import { requestCompletionAuthToken } from '@automattic/jetpack-ai-client';
-
-requestCompletionAuthToken()
-  .then(tokenData => {
-    // Do something with the token data
-  })
-  .catch(error => {
-    // Handle the error
-  });
-```
+#### [AiStatusIndicator](./src/components/ai-status-indicator/)
 
+### [Icons](./src/icons/Readme.md)
 ## Contribute
 
+React components useful for when you need to create some UI implementations.
+
 We welcome contributions from the community. Please submit your pull requests on the GitHub repository.
 
 ## Get Help

package/index.ts

@@ -24,3 +24,8 @@ export { default as AIControl } from './src/components/ai-control';
  * Contexts
  */
 export * from './src/data-flow';
+
+/*
+ * Types
+ */
+export * from './src/types';

package/package.json

@@ -1,7 +1,7 @@
 {
 	"private": false,
 	"name": "@automattic/jetpack-ai-client",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"description": "A JS client for consuming Jetpack AI services",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/ai-client/#readme",
 	"bugs": {
@@ -21,6 +21,8 @@
 	},
 	"type": "module",
 	"devDependencies": {
+		"@storybook/addon-actions": "7.1.0",
+		"@storybook/blocks": "7.1.0",
 		"@storybook/react": "7.1.0",
 		"jest": "^29.6.2",
 		"jest-environment-jsdom": "29.5.0",
@@ -31,11 +33,12 @@
 	},
 	"dependencies": {
 		"@automattic/jetpack-connection": "workspace:*",
-		"@automattic/jetpack-shared-extension-utils": "^0.10.9",
+		"@automattic/jetpack-shared-extension-utils": "^0.11.0",
 		"@microsoft/fetch-event-source": "2.0.1",
 		"@wordpress/api-fetch": "6.34.0",
 		"@wordpress/block-editor": "12.5.0",
 		"@wordpress/components": "25.3.0",
+		"@wordpress/compose": "6.14.0",
 		"@wordpress/data": "9.7.0",
 		"@wordpress/element": "5.14.0",
 		"@wordpress/i18n": "4.37.0",

package/src/components/ai-control/Readme.md

@@ -0,0 +1,29 @@
+### AIControl
+
+#### Properties
+
+- `loading` (**boolean**) (Optional): Determines the loading state. Default value is `false`.
+- `value` (**string**): Current input value. Default value is `''`.
+- `placeholder` (**string**) (Optional): Placeholder text for the input field. Default value is `''`.
+- `showAccept` (**boolean**) (Optional): Determines if the accept button is shown. Default value is `false`.
+- `acceptLabel` (**string**) (Optional): Label text for the accept button. Default value is `'Accept'`.
+- `showButtonsLabel` (**boolean**) (Optional): Determines if button labels are shown. Default value is `true`.
+- `isOpaque` (**boolean**) (Optional): Controls the opacity of the component. Default value is `false`.
+- `requestingState` (**RequestingStateProp**) (Optional): Determines the state of the request. Default value is `'init'`.
+- `onChange` (**Function**) (Optional): Handler for input change. Default action is no operation.
+- `onSend` (**Function**) (Optional): Handler to send a request. Default action is no operation.
+- `onStop` (**Function**) (Optional): Handler to stop a request. Default action is no operation.
+- `onAccept` (**Function**) (Optional): Handler to accept the input. Default action is no operation.
+
+#### Example Usage
+
+```jsx
+<AIControl
+  value="Type here"
+  placeholder="Placeholder text"
+  onChange={ handleChange }
+  onSend={ handleSend }
+  onStop={ handleStop }
+  onAccept={ handleAccept }
+/>
+```

package/src/components/ai-control/index.tsx

@@ -2,7 +2,8 @@
  * External dependencies
  */
 import { PlainText } from '@wordpress/block-editor';
-import { Button, Spinner } from '@wordpress/components';
+import { Button } from '@wordpress/components';
+import { useKeyboardShortcut } from '@wordpress/compose';
 import { useRef } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 import { Icon, closeSmall, check, arrowUp } from '@wordpress/icons';
@@ -10,8 +11,12 @@ import classNames from 'classnames';
 /**
  * Internal dependencies
  */
-import { aiAssistantIcon } from '../../icons';
 import './style.scss';
+import AiStatusIndicator from '../ai-status-indicator';
+/**
+ * Types
+ */
+import type { RequestingStateProp } from '../../types';
 
 // eslint-disable-next-line @typescript-eslint/no-empty-function
 const noop = () => {};
@@ -31,6 +36,7 @@ const noop = () => {};
  * @param {Function} props.onSend - send request handler
  * @param {Function} props.onStop - stop request handler
  * @param {Function} props.onAccept - accept handler
+ * @param {string} props.requestingState - requesting state
  * @returns {object} - AI Control component
  */
 export default function AIControl( {
@@ -41,6 +47,7 @@ export default function AIControl( {
 	acceptLabel = __( 'Accept', 'jetpack-ai-client' ),
 	showButtonsLabel = true,
 	isOpaque = false,
+	requestingState = 'init',
 	onChange = noop,
 	onSend = noop,
 	onStop = noop,
@@ -53,13 +60,37 @@ export default function AIControl( {
 	acceptLabel?: string;
 	showButtonsLabel?: boolean;
 	isOpaque?: boolean;
-	onChange: ( newValue: string ) => void;
-	onSend: ( currentValue: string ) => void;
-	onStop: () => void;
-	onAccept: () => void;
+	requestingState?: RequestingStateProp;
+	onChange?: ( newValue: string ) => void;
+	onSend?: ( currentValue: string ) => void;
+	onStop?: () => void;
+	onAccept?: () => void;
 } ) {
 	const promptUserInputRef = useRef( null );
 
+	useKeyboardShortcut(
+		'mod+enter',
+		() => {
+			if ( showAccept ) {
+				onAccept?.();
+			}
+		},
+		{
+			target: promptUserInputRef,
+		}
+	);
+
+	useKeyboardShortcut(
+		'enter',
+		e => {
+			e.preventDefault();
+			onSend?.( value );
+		},
+		{
+			target: promptUserInputRef,
+		}
+	);
+
 	return (
 		<div className="jetpack-components-ai-control__container">
 			<div
@@ -67,23 +98,27 @@ export default function AIControl( {
 					'is-opaque': isOpaque,
 				} ) }
 			>
-				<div className="jetpack-components-ai-controlton__icon">
-					{ loading ? (
-						<Spinner className="input-spinner" />
-					) : (
-						<Icon className="input-icon" icon={ aiAssistantIcon } size={ 24 } />
+				<AiStatusIndicator state={ requestingState } />
+
+				<div className="jetpack-components-ai-control__input-wrapper">
+					<PlainText
+						value={ value }
+						onChange={ onChange }
+						placeholder={ placeholder }
+						className="jetpack-components-ai-control__input"
+						disabled={ loading }
+						ref={ promptUserInputRef }
+					/>
+
+					{ value?.length > 0 && (
+						<Icon
+							icon={ closeSmall }
+							className="jetpack-components-ai-control__clear"
+							onClick={ () => onChange( '' ) }
+						/>
 					) }
 				</div>
 
-				<PlainText
-					value={ value }
-					onChange={ onChange }
-					placeholder={ placeholder }
-					className="jetpack-components-ai-control__input"
-					disabled={ loading }
-					ref={ promptUserInputRef }
-				/>
-
 				<div className="jetpack-components-ai-control__controls">
 					<div className="jetpack-components-ai-control__controls-prompt_button_wrapper">
 						{ ! loading ? (
@@ -91,7 +126,7 @@ export default function AIControl( {
 								className="jetpack-components-ai-control__controls-prompt_button"
 								onClick={ () => onSend( value ) }
 								isSmall={ true }
-								disabled={ value?.length }
+								disabled={ ! value?.length }
 								label={ __( 'Send request', 'jetpack-ai-client' ) }
 							>
 								<Icon icon={ arrowUp } />

package/src/components/ai-control/stories/index.stories.tsx

@@ -1,11 +1,13 @@
 /**
  * External dependencies
  */
+import { action } from '@storybook/addon-actions';
 import { useState } from '@wordpress/element';
 import React from 'react';
 /**
  * Internal dependencies
  */
+import { REQUESTING_STATES } from '../../../types';
 import AIControl from '../index';
 /**
  * Types
@@ -15,7 +17,26 @@ import type { Meta } from '@storybook/react';
 export default {
 	title: 'JS Packages/AI Client/AI Control',
 	component: AIControl,
-	parameters: {},
+	decorators: [
+		Story => (
+			<div style={ { backgroundColor: 'white' } }>
+				<Story />
+			</div>
+		),
+	],
+	argTypes: {
+		requestingState: {
+			control: {
+				type: 'select',
+			},
+			options: REQUESTING_STATES,
+		},
+	},
+	parameters: {
+		controls: {
+			exclude: /on[A-Z].*/,
+		},
+	},
 } as Meta< typeof AIControl >;
 
 const Template = args => {
@@ -33,9 +54,14 @@ const DefaultArgs = {
 	loading: false,
 	isOpaque: false,
 	placeholder: '',
+	requestingState: 'init',
 	showButtonsLabel: true,
 	showAccept: false,
 	acceptLabel: 'Accept',
+	onChange: action( 'onChange' ),
+	onSend: action( 'onSend' ),
+	onStop: action( 'onStop' ),
+	onAccept: action( 'onAccept' ),
 };
 
 export const Default = Template.bind( {} );

package/src/components/ai-control/style.scss

@@ -3,23 +3,46 @@
 	background-color: var( --jp-white );
 	box-shadow: var( --wp--preset--color--cyan-bluish-gray ) 0px 0px 0px 1px, var( --wp--preset--color--cyan-bluish-gray ) 0px 0px 8px;
 	font-family: "SF Pro Text", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
+	width: 100%;
 }
 
 .jetpack-components-ai-control__wrapper {
 	display: flex;
 	padding: 12px 14px;
 	gap: 8px;
+	align-items: center;
 
 	&.is-opaque {
 		opacity: 0.4;
 	}
+}
+
+.jetpack-components-ai-control__input-wrapper {
+	position: relative;
+	display: flex;
+	flex-grow: 1;
+	width: 100%;
+
+	.jetpack-components-ai-control__clear {
+		position: absolute;
+		right: 8px;
+		top: calc( 50% - 12px );
+		border-radius: 50%;
+		background-color: black;
+		opacity: 0.2;
+		fill: white;
+		cursor: pointer;
+
+		&:hover {
+			opacity: 0.4;
+		}
+	}
 
 	textarea.jetpack-components-ai-control__input {
 		width: 100%;
-        min-height: 20px;
-		flex-grow: 1;
+		min-height: 20px;
 		border-radius: 2px;
-		padding: 6px 8px;
+		padding: 6px 38px 6px 8px;
 
 		resize: none !important;
 		border: none;

package/src/components/ai-status-indicator/Readme.md

@@ -0,0 +1,11 @@
+### AiStatusIndicator
+
+#### Properties
+
+- `state` (**RequestingStateProp**) (Optional): Determines the appearance of the icon.
+- `size` (**AiStatusIndicatorIconSize** 24 | 32 | 48 | 64 pixels) (Optional): Defines the size of the icon. Default value is `24`.
+
+#### Example Usage
+```jsx
+<AiStatusIndicator state="requesting" size={ 32 } />
+```

package/src/components/ai-status-indicator/index.tsx

@@ -0,0 +1,43 @@
+/**
+ * External dependencies
+ */
+import { Icon } from '@wordpress/components';
+import classNames from 'classnames';
+/*
+ * Internal dependencies
+ */
+import { aiAssistantIcon } from '../../icons';
+/*
+ * Types
+ */
+import type { RequestingStateProp } from '../../types';
+export type AiStatusIndicatorIconSize = 24 | 32 | 48 | 64;
+import type React from 'react';
+
+import './style.scss';
+
+export type AiStatusIndicatorProps = {
+	state?: RequestingStateProp;
+	size?: AiStatusIndicatorIconSize;
+};
+
+/**
+ * AiStatusIndicator component.
+ *
+ * @param {AiStatusIndicatorProps} props - component props.
+ * @returns {React.ReactElement} - rendered component.
+ */
+export default function AiStatusIndicator( {
+	state,
+	size = 24,
+}: AiStatusIndicatorProps ): React.ReactElement {
+	return (
+		<div
+			className={ classNames( 'jetpack-ai-status-indicator__icon-wrapper', {
+				[ `is-${ state }` ]: true,
+			} ) }
+		>
+			<Icon icon={ aiAssistantIcon } size={ size } />
+		</div>
+	);
+}

package/src/components/ai-status-indicator/stories/index.mdx

@@ -0,0 +1,25 @@
+import { Meta, Story, Canvas } from '@storybook/blocks';
+import AiStatusIndicator from '../index';
+import * as AiStatusIndicatorStory from './index.stories';
+
+<Meta of={AiStatusIndicatorStory} />
+
+# AiStatusIndicator
+
+## Requesting states
+
+### Init
+<Story id="js-packages-ai-client-aistatusindicator--init" />
+
+### Requesting
+<Story id="js-packages-ai-client-aistatusindicator--requesting" />
+
+### Suggesting
+<Story id="js-packages-ai-client-aistatusindicator--suggesting" />
+
+### Done
+<Story id="js-packages-ai-client-aistatusindicator--done" />
+
+### Error
+<Story id="js-packages-ai-client-aistatusindicator--error" />
+

package/src/components/ai-status-indicator/stories/index.stories.tsx

@@ -0,0 +1,84 @@
+/*
+ * External Dependencies
+ */
+import React from 'react';
+/*
+ * Internal Dependencies
+ */
+import AiStatusIndicator, { AiStatusIndicatorProps } from '..';
+import { REQUESTING_STATES } from '../../../types';
+
+type AiStatusIndicatoryStoryProps = AiStatusIndicatorProps & {
+	icon: string;
+	children?: React.ReactNode;
+};
+
+export default {
+	title: 'JS Packages/AI Client/AiStatusIndicator',
+	component: AiStatusIndicator,
+	argTypes: {
+		state: {
+			control: {
+				type: 'select',
+			},
+			options: REQUESTING_STATES,
+		},
+		size: {
+			control: {
+				type: 'select',
+			},
+			options: [ 24, 32, 48, 64 ],
+		},
+
+		action: {
+			table: {
+				disable: true,
+			},
+		},
+	},
+};
+
+const DefaultTemplate = ( args: AiStatusIndicatoryStoryProps ) => {
+	const props: AiStatusIndicatorProps = {
+		state: args.state,
+		size: args.size,
+	};
+
+	return <AiStatusIndicator { ...props } />;
+};
+
+export const _default = DefaultTemplate.bind( {} );
+_default.args = {
+	state: 'init',
+	size: 24,
+};
+
+export const Init = DefaultTemplate.bind( {} );
+Init.args = {
+	state: 'init',
+	size: 48,
+};
+
+export const Requesting = DefaultTemplate.bind( {} );
+Requesting.args = {
+	state: 'requesting',
+	size: 48,
+};
+
+export const Suggesting = DefaultTemplate.bind( {} );
+Suggesting.args = {
+	state: 'suggesting',
+	size: 48,
+};
+
+export const Error = DefaultTemplate.bind( {} );
+Error.args = {
+	state: 'error',
+	size: 48,
+};
+
+export const Done = DefaultTemplate.bind( {} );
+Done.args = {
+	state: 'done',
+	size: 48,
+};

package/src/components/ai-status-indicator/style.scss

@@ -0,0 +1,50 @@
+.jetpack-ai-status-indicator__icon-wrapper {
+	color: var( --jp-green-60 );
+	height: 24px;
+
+	&.is-init {
+		color: var( --jp-green-60 );
+	}
+
+	&.is-requesting {
+		color: var( --jp-green-40 );
+		animation: fade 800ms linear infinite;
+	}
+
+	&.is-suggesting {
+		color: var( --jp-green-30 );
+		.ai-assistant-icon > path {
+			animation: fadingSpark 300ms ease-in-out alternate infinite;
+	
+			&.spark-first {
+				animation-delay: 0.2s;
+			}
+			
+			&.spark-second {
+				animation-delay: 0.6s;
+			}
+		}
+	}
+
+	&.is-done {
+		color: var( --jp-green-40 );
+	}
+
+	&.is-error {
+		color: var( --jp-yellow-30 );
+	}
+}
+
+
+@keyframes fadingSpark {
+	to {
+		opacity: 0.3;
+	}
+}
+
+@keyframes fade {
+	0% { opacity: 1; }
+	50% { opacity: 0.4; }
+	100% { opacity: 1; }
+  }
+  

package/src/data-flow/Readme.md

@@ -1,6 +1,8 @@
 
 # AI Assistant Data Flow
 
+Data Flow is a seamless and robust implementation designed to manage the state and functionality of an AI Assistant within a React application. By leveraging a React context, Higher Order Components (HOCs), and custom hooks, this implementation streamlines the interaction with the AI, handles suggestions, manages error states, and efficiently controls request functionality.
+
 ```jsx
 import { withAiAssistantData, useAiContext } from '@automattic/jetpack-ai-client';
 

package/src/data-flow/context.tsx

@@ -7,8 +7,10 @@ import React from 'react';
  * Types & Constants
  */
 import SuggestionsEventSource from '../suggestions-event-source';
-import type { RequestingStateProp, RequestingErrorProps } from '../hooks/use-ai-suggestions';
+import type { AskQuestionOptionsArgProps } from '../ask-question';
+import type { RequestingErrorProps } from '../hooks/use-ai-suggestions';
 import type { PromptProp } from '../types';
+import type { RequestingStateProp } from '../types';
 
 export type AiDataContextProps = {
 	/*
@@ -29,7 +31,7 @@ export type AiDataContextProps = {
 	/*
 	 * Request suggestion function
 	 */
-	requestSuggestion: ( prompt: PromptProp ) => void;
+	requestSuggestion: ( prompt: PromptProp, options?: AskQuestionOptionsArgProps ) => void;
 
 	/*
 	 * The Suggestions Event Source instance

package/src/data-flow/use-ai-context.ts

@@ -5,6 +5,7 @@ import { useCallback, useContext, useEffect } from '@wordpress/element';
 /**
  * Internal dependencies
  */
+import { ERROR_RESPONSE } from '../types';
 import { AiDataContext } from '.';
 /**
  * Types & constants
@@ -12,7 +13,7 @@ import { AiDataContext } from '.';
 import type { AiDataContextProps } from './context';
 import type { AskQuestionOptionsArgProps } from '../ask-question';
 
-type useAiContextOptions = {
+export type UseAiContextOptions = {
 	/*
 	 * Ask question options.
 	 */
@@ -27,6 +28,11 @@ type useAiContextOptions = {
 	 * onSuggestion callback.
 	 */
 	onSuggestion?: ( suggestion: string ) => void;
+
+	/*
+	 * onError callback.
+	 */
+	onError?: ( error: Error ) => void;
 };
 
 /**
@@ -34,13 +40,14 @@ type useAiContextOptions = {
  * the AI Assistant data (from context),
  * and to subscribe to the request events (onDone, onSuggestion).
  *
- * @param {useAiContextOptions} options - the hook options.
+ * @param {UseAiContextOptions} options - the hook options.
  * @returns {AiDataContextProps}          the AI Assistant data context.
  */
 export default function useAiContext( {
 	onDone,
 	onSuggestion,
-}: useAiContextOptions = {} ): AiDataContextProps {
+	onError,
+}: UseAiContextOptions = {} ): AiDataContextProps {
 	const context = useContext( AiDataContext );
 	const { eventSource } = context;
 
@@ -49,6 +56,9 @@ export default function useAiContext( {
 		( event: CustomEvent ) => onSuggestion?.( event?.detail ),
 		[ onSuggestion ]
 	);
+	const error = useCallback( ( event: CustomEvent ) => {
+		onError?.( event?.detail );
+	}, [] );
 
 	useEffect( () => {
 		if ( ! eventSource ) {
@@ -63,9 +73,14 @@ export default function useAiContext( {
 			eventSource.addEventListener( 'suggestion', suggestion );
 		}
 
+		if ( onError ) {
+			eventSource.addEventListener( ERROR_RESPONSE, error );
+		}
+
 		return () => {
 			eventSource.removeEventListener( 'done', done );
 			eventSource.removeEventListener( 'suggestion', suggestion );
+			eventSource.removeEventListener( ERROR_RESPONSE, error );
 		};
 	}, [ eventSource ] );
 

package/src/hooks/use-ai-suggestions/Readme.md

@@ -35,7 +35,7 @@ An object with the following properties:
 - `error: RequestingErrorProps | undefined`: An error object if an error occurs.
 - `requestingState: RequestingStateProp`: The state of the request.
 - `eventSource: SuggestionsEventSource | undefined`: The event source of the request.
-- `request: ( prompt: Array< PromptItemProps > ) => Promise< void >`: The request handler.
+- `request: ( prompt: Array< PromptItemProps >, options: AskQuestionOptionsArgProps ) => Promise< void >`: The request handler.
 
 ### `PromptItemProps`
 

package/src/hooks/use-ai-suggestions/index.ts

@@ -21,6 +21,7 @@ import {
 import type { AskQuestionOptionsArgProps } from '../../ask-question';
 import type SuggestionsEventSource from '../../suggestions-event-source';
 import type { PromptProp, SuggestionErrorCode } from '../../types';
+import type { RequestingStateProp } from '../../types';
 
 export type RequestingErrorProps = {
 	/*
@@ -71,8 +72,6 @@ type useAiSuggestionsOptions = {
 	onError?: ( error: RequestingErrorProps ) => void;
 };
 
-export type RequestingStateProp = 'init' | 'requesting' | 'suggesting' | 'done' | 'error';
-
 type useAiSuggestionsProps = {
 	/*
 	 * The suggestion.
@@ -97,7 +96,7 @@ type useAiSuggestionsProps = {
 	/*
 	 * The request handler.
 	 */
-	request: ( prompt: PromptProp ) => Promise< void >;
+	request: ( prompt: PromptProp, options?: AskQuestionOptionsArgProps ) => Promise< void >;
 };
 
 const debug = debugFactory( 'jetpack-ai-client:use-suggestion' );
@@ -108,7 +107,7 @@ const debug = debugFactory( 'jetpack-ai-client:use-suggestion' );
  * @param {SuggestionErrorCode} errorCode - The error code.
  * @returns {RequestingErrorProps}          The error data.
  */
-function getErrorData( errorCode: SuggestionErrorCode ): RequestingErrorProps {
+export function getErrorData( errorCode: SuggestionErrorCode ): RequestingErrorProps {
 	switch ( errorCode ) {
 		case ERROR_QUOTA_EXCEEDED:
 			return {
@@ -240,10 +239,15 @@ export default function useAiSuggestions( {
 	/**
 	 * Request handler.
 	 *
+	 * @param {PromptProp} promptArg               - The messages array of the prompt.
+	 * @param {AskQuestionOptionsArgProps} options - The options for the askQuestion request. Uses the hook's askQuestionOptions by default.
 	 * @returns {Promise<void>} The promise.
 	 */
 	const request = useCallback(
-		async ( promptArg: PromptProp ) => {
+		async (
+			promptArg: PromptProp,
+			options: AskQuestionOptionsArgProps = { ...askQuestionOptions }
+		) => {
 			if ( Array.isArray( promptArg ) && promptArg?.length ) {
 				promptArg.forEach( ( { role, content: promptContent }, i ) =>
 					debug( '(%s/%s) %o\n%s', i + 1, promptArg.length, `[${ role }]`, promptContent )
@@ -256,7 +260,7 @@ export default function useAiSuggestions( {
 			setRequestingState( 'requesting' );
 
 			try {
-				eventSourceRef.current = await askQuestion( promptArg, askQuestionOptions );
+				eventSourceRef.current = await askQuestion( promptArg, options );
 
 				if ( ! eventSourceRef?.current ) {
 					return;
@@ -302,7 +306,7 @@ export default function useAiSuggestions( {
 
 		// Trigger the request.
 		if ( autoRequest ) {
-			request( prompt );
+			request( prompt, askQuestionOptions );
 		}
 
 		return () => {

package/src/suggestions-event-source/index.ts

@@ -6,14 +6,16 @@ import debugFactory from 'debug';
 /*
  * Types & constants
  */
+import { getErrorData } from '../hooks/use-ai-suggestions';
 import {
 	ERROR_MODERATION,
 	ERROR_NETWORK,
 	ERROR_QUOTA_EXCEEDED,
+	ERROR_RESPONSE,
 	ERROR_SERVICE_UNAVAILABLE,
 	ERROR_UNCLEAR_PROMPT,
 } from '../types';
-import type { PromptMessagesProp, PromptProp } from '../types';
+import type { PromptMessagesProp, PromptProp, SuggestionErrorCode } from '../types';
 
 type SuggestionsEventSourceConstructorArgs = {
 	url?: string;
@@ -150,6 +152,9 @@ export default class SuggestionsEventSource extends EventTarget {
 				if ( response.ok ) {
 					return;
 				}
+
+				let errorCode: SuggestionErrorCode;
+
 				if (
 					response.status >= 400 &&
 					response.status <= 500 &&
@@ -163,6 +168,7 @@ export default class SuggestionsEventSource extends EventTarget {
 				 * service unavailable
 				 */
 				if ( response.status === 503 ) {
+					errorCode = ERROR_SERVICE_UNAVAILABLE;
 					this.dispatchEvent( new CustomEvent( ERROR_SERVICE_UNAVAILABLE ) );
 				}
 
@@ -171,6 +177,7 @@ export default class SuggestionsEventSource extends EventTarget {
 				 * you exceeded your current quota please check your plan and billing details
 				 */
 				if ( response.status === 429 ) {
+					errorCode = ERROR_QUOTA_EXCEEDED;
 					this.dispatchEvent( new CustomEvent( ERROR_QUOTA_EXCEEDED ) );
 				}
 
@@ -179,9 +186,17 @@ export default class SuggestionsEventSource extends EventTarget {
 				 * request flagged by moderation system
 				 */
 				if ( response.status === 422 ) {
+					errorCode = ERROR_MODERATION;
 					this.dispatchEvent( new CustomEvent( ERROR_MODERATION ) );
 				}
 
+				// Always dispatch a global ERROR_RESPONSE event
+				this.dispatchEvent(
+					new CustomEvent( ERROR_RESPONSE, {
+						detail: getErrorData( errorCode ),
+					} )
+				);
+
 				throw new Error();
 			},
 
@@ -204,6 +219,11 @@ export default class SuggestionsEventSource extends EventTarget {
 		if ( replacedMessage.startsWith( 'JETPACK_AI_ERROR' ) ) {
 			// The unclear prompt marker was found, so we dispatch an error event
 			this.dispatchEvent( new CustomEvent( ERROR_UNCLEAR_PROMPT ) );
+			this.dispatchEvent(
+				new CustomEvent( ERROR_RESPONSE, {
+					detail: getErrorData( ERROR_UNCLEAR_PROMPT ),
+				} )
+			);
 		} else if ( 'JETPACK_AI_ERROR'.startsWith( replacedMessage ) ) {
 			// Partial unclear prompt marker was found, so we wait for more data and print a debug message without dispatching an event
 			debug( this.fullMessage );
@@ -276,6 +296,11 @@ export default class SuggestionsEventSource extends EventTarget {
 	processConnectionError( response ) {
 		debug( 'Connection error: %o', response );
 		this.dispatchEvent( new CustomEvent( ERROR_NETWORK, { detail: response } ) );
+		this.dispatchEvent(
+			new CustomEvent( ERROR_RESPONSE, {
+				detail: getErrorData( ERROR_NETWORK ),
+			} )
+		);
 	}
 
 	processErrorEvent( e ) {
@@ -283,5 +308,10 @@ export default class SuggestionsEventSource extends EventTarget {
 
 		// Dispatch a generic network error event
 		this.dispatchEvent( new CustomEvent( ERROR_NETWORK, { detail: e } ) );
+		this.dispatchEvent(
+			new CustomEvent( ERROR_RESPONSE, {
+				detail: getErrorData( ERROR_NETWORK ),
+			} )
+		);
 	}
 }

package/src/types.ts

@@ -3,13 +3,15 @@ export const ERROR_QUOTA_EXCEEDED = 'error_quota_exceeded' as const;
 export const ERROR_MODERATION = 'error_moderation' as const;
 export const ERROR_NETWORK = 'error_network' as const;
 export const ERROR_UNCLEAR_PROMPT = 'error_unclear_prompt' as const;
+export const ERROR_RESPONSE = 'error_response' as const;
 
 export type SuggestionErrorCode =
 	| typeof ERROR_SERVICE_UNAVAILABLE
 	| typeof ERROR_QUOTA_EXCEEDED
 	| typeof ERROR_MODERATION
 	| typeof ERROR_NETWORK
-	| typeof ERROR_UNCLEAR_PROMPT;
+	| typeof ERROR_UNCLEAR_PROMPT
+	| typeof ERROR_RESPONSE;
 
 /*
  * Prompt types
@@ -22,3 +24,29 @@ export type PromptItemProps = {
 export type PromptMessagesProp = Array< PromptItemProps >;
 
 export type PromptProp = PromptMessagesProp | string;
+
+/*
+ * Data Flow types
+ */
+export type { UseAiContextOptions } from './data-flow/use-ai-context';
+export type { RequestingErrorProps } from './hooks/use-ai-suggestions';
+
+/*
+ * Requests types
+ */
+
+const REQUESTING_STATE_INIT = 'init' as const;
+const REQUESTING_STATE_REQUESTING = 'requesting' as const;
+const REQUESTING_STATE_SUGGESTING = 'suggesting' as const;
+const REQUESTING_STATE_DONE = 'done' as const;
+const REQUESTING_STATE_ERROR = 'error' as const;
+
+export const REQUESTING_STATES = [
+	REQUESTING_STATE_INIT,
+	REQUESTING_STATE_REQUESTING,
+	REQUESTING_STATE_SUGGESTING,
+	REQUESTING_STATE_DONE,
+	REQUESTING_STATE_ERROR,
+] as const;
+
+export type RequestingStateProp = ( typeof REQUESTING_STATES )[ number ];