@automattic/jetpack-ai-client 0.1.0 → 0.1.2

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

@@ -0,0 +1,127 @@
+# useAiSuggestions
+
+This is a custom React hook that obtains suggestions from an AI by hitting a specific query endpoint.
+
+## Usage
+
+```jsx
+import { useAiSuggestions } from '@automattic/jetpack-ai-client';
+
+// Inside your component...
+
+const { suggestion, ...other } = useAiSuggestions( { options } );
+```
+
+## API
+
+### `useAiSuggestions( { options } )`
+
+Invokes the custom hook with the provided options.
+
+#### Options
+
+- `prompt: PromptItemProps[]` (optional): An array of request prompts.
+- `autoRequest: boolean` (optional, defaults to `false`): Determines whether to request suggestions automatically.
+- `askQuestionOptions: AskQuestionOptionsArgProps` (optional): [Options for the askQuestion](../../ask-question/Readme.md#ask-question-parameters) function.
+- `onSuggestion: ( suggestion: string ) => void` (optional): A callback function that gets triggered when a suggestion is received.
+- `onDone: ( content: string ) => void` (optional): A callback function that gets triggered when the process is complete.
+- `onError: ( error: RequestingErrorProps ) => void` (optional): A callback function that gets triggered when an error occurs.
+
+#### Returns
+
+An object with the following properties:
+
+- `suggestion: string`: The obtained suggestion.
+- `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 >, options: AskQuestionOptionsArgProps ) => Promise< void >`: The request handler.
+
+### `PromptItemProps`
+
+An object containing the following properties:
+
+- `role: 'system' | 'user' | 'assistant'`: The role of the item in the prompt.
+- `content: string`: The content of the prompt.
+
+### `RequestingErrorProps`
+
+An object containing the following properties:
+
+- `code: SuggestionErrorCode`: A string code to refer to the error.
+- `message: string`: The user-friendly error message.
+- `severity: 'info' | 'error'`: The severity of the error.
+
+## Examples
+
+### Rendering `suggestion` or `error`, based on `requestingState`.
+
+In this example, the state of the request and any returned `suggestion` or `error` are displayed in the rendered output based on the `requestingState`. It sets `autoRequest` to true to trigger the request automatically.
+
+```jsx
+import { useAiSuggestions } from '@automattic/jetpack-ai-client';
+
+function ExampleComponent() {
+	const { suggestion, error, requestingState } = useAiSuggestions( {
+		prompt: [ { role: 'user', content: 'Hello AI!' } ],
+		autoRequest: true,
+	} );
+
+	return (
+		<div>
+			{ requestingState === 'requesting' && <p>Requesting...</p> }
+			{ requestingState === 'error' && <p>Error: { error?.message }</p> }
+			{ requestingState === 'done' && <p>Suggestion: { suggestion }</p> }
+		</div>
+	);
+}
+```
+### Listening events by using callback functions
+
+The following example invokes `useAiSuggestions` with a single prompt and two callback functions for when a suggestion is received or when an error occurs.
+
+```jsx
+import { useAiSuggestions } from '@automattic/jetpack-ai-client';
+
+function ExampleComponent() {
+	useAiSuggestions( {
+		autoRequest: true,
+		prompt: [ { role: 'user', content: 'Hello AI!' } ],
+		onSuggestion: suggestion => console.log( 'Suggestion: ', suggestion ),
+		onError: error => console.log( 'Error: ', error ),
+	} );
+
+	// Your component logic...
+}
+```
+
+### Handle requests programmatically
+
+In example below the request is manually triggered by a button click (`autoRequest` is false by default).
+The handleClick function calls the `request` function, which in turn invokes the AI with a new prompt.
+
+```jsx
+import { useAiSuggestions } from '@automattic/jetpack-ai-client';
+
+function ExampleComponent() {
+	const { request } = useAiSuggestions( {
+		prompt: [ { role: 'user', content: 'Hello AI!' } ],
+		onSuggestion: suggestion => console.log( 'Suggestion: ', suggestion ),
+		onError: error => console.log( 'Error: ', error ),
+	} );
+
+	// Trigger the request manually.
+	const handleClick = async () => {
+		await request( [ { role: 'user', content: 'What is the weather like?' } ] );
+	}
+
+	// Your component logic...
+
+	return (
+		<div>
+			{ /* Your component UI... */ }
+			<button onClick={ handleClick }>Get AI Suggestions</button>
+		</div>
+	);
+}
+```

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

@@ -0,0 +1,358 @@
+/**
+ * External dependencies
+ */
+import { useCallback, useEffect, useRef, useState } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import debugFactory from 'debug';
+/**
+ * Internal dependencies
+ */
+import askQuestion from '../../ask-question';
+import {
+	ERROR_MODERATION,
+	ERROR_NETWORK,
+	ERROR_QUOTA_EXCEEDED,
+	ERROR_SERVICE_UNAVAILABLE,
+	ERROR_UNCLEAR_PROMPT,
+} from '../../types';
+/**
+ * Types & constants
+ */
+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 = {
+	/*
+	 * A string code to refer to the error.
+	 */
+	code: SuggestionErrorCode;
+
+	/*
+	 * The user-friendly error message.
+	 */
+	message: string;
+
+	/*
+	 * The severity of the error.
+	 */
+	severity: 'info' | 'error';
+};
+
+type useAiSuggestionsOptions = {
+	/*
+	 * Request prompt.
+	 */
+	prompt?: PromptProp;
+
+	/*
+	 * Whether to request suggestions automatically.
+	 */
+	autoRequest?: boolean;
+
+	/**
+	 * AskQuestion options.
+	 */
+	askQuestionOptions?: AskQuestionOptionsArgProps;
+
+	/*
+	 * onSuggestion callback.
+	 */
+	onSuggestion?: ( suggestion: string ) => void;
+
+	/*
+	 * onDone callback.
+	 */
+	onDone?: ( content: string ) => void;
+
+	/*
+	 * onError callback.
+	 */
+	onError?: ( error: RequestingErrorProps ) => void;
+};
+
+type useAiSuggestionsProps = {
+	/*
+	 * The suggestion.
+	 */
+	suggestion: string;
+
+	/*
+	 * The error.
+	 */
+	error: RequestingErrorProps | undefined;
+
+	/*
+	 * Whether the request is in progress.
+	 */
+	requestingState: RequestingStateProp;
+
+	/*
+	 * The event source.
+	 */
+	eventSource: SuggestionsEventSource | undefined;
+
+	/*
+	 * The request handler.
+	 */
+	request: ( prompt: PromptProp, options?: AskQuestionOptionsArgProps ) => Promise< void >;
+};
+
+const debug = debugFactory( 'jetpack-ai-client:use-suggestion' );
+
+/**
+ * Get the error data for a given error code.
+ *
+ * @param {SuggestionErrorCode} errorCode - The error code.
+ * @returns {RequestingErrorProps}          The error data.
+ */
+export function getErrorData( errorCode: SuggestionErrorCode ): RequestingErrorProps {
+	switch ( errorCode ) {
+		case ERROR_QUOTA_EXCEEDED:
+			return {
+				code: ERROR_QUOTA_EXCEEDED,
+				message: __( 'You have reached the limit of requests for this site.', 'jetpack-ai-client' ),
+				severity: 'info',
+			};
+		case ERROR_UNCLEAR_PROMPT:
+			return {
+				code: ERROR_UNCLEAR_PROMPT,
+				message: __( 'Your request was unclear. Mind trying again?', 'jetpack-ai-client' ),
+				severity: 'info',
+			};
+		case ERROR_SERVICE_UNAVAILABLE:
+			return {
+				code: ERROR_SERVICE_UNAVAILABLE,
+				message: __(
+					'Jetpack AI services are currently unavailable. Sorry for the inconvenience.',
+					'jetpack-ai-client'
+				),
+				severity: 'info',
+			};
+		case ERROR_MODERATION:
+			return {
+				code: ERROR_MODERATION,
+				message: __(
+					'This request has been flagged by our moderation system. Please try to rephrase it and try again.',
+					'jetpack-ai-client'
+				),
+				severity: 'info',
+			};
+		case ERROR_NETWORK:
+			return {
+				code: ERROR_NETWORK,
+				message: __(
+					'It was not possible to process your request. Mind trying again?',
+					'jetpack-ai-client'
+				),
+				severity: 'info',
+			};
+		default:
+			return {
+				code: ERROR_NETWORK,
+				message: __(
+					'It was not possible to process your request. Mind trying again?',
+					'jetpack-ai-client'
+				),
+				severity: 'info',
+			};
+	}
+}
+
+/**
+ * React custom hook to get suggestions from AI,
+ * by hitting the query endpoint.
+ *
+ * @param {useAiSuggestionsOptions} options - The options for the hook.
+ * @returns {useAiSuggestionsProps}           The props for the hook.
+ */
+export default function useAiSuggestions( {
+	prompt,
+	autoRequest = false,
+	askQuestionOptions = {},
+	onSuggestion,
+	onDone,
+	onError,
+}: useAiSuggestionsOptions = {} ): useAiSuggestionsProps {
+	const [ requestingState, setRequestingState ] = useState< RequestingStateProp >( 'init' );
+	const [ suggestion, setSuggestion ] = useState< string >( '' );
+	const [ error, setError ] = useState< RequestingErrorProps >();
+
+	// Store the event source in a ref, so we can handle it if needed.
+	const eventSourceRef = useRef< SuggestionsEventSource | undefined >( undefined );
+
+	/**
+	 * onSuggestion function handler.
+	 *
+	 * @param {string} suggestion - The suggestion.
+	 * @returns {void}
+	 */
+	const handleSuggestion = useCallback(
+		( event: CustomEvent ) => {
+			setSuggestion( event?.detail );
+			onSuggestion?.( event?.detail );
+		},
+		[ onSuggestion ]
+	);
+
+	/**
+	 * onDone function handler.
+	 *
+	 * @param {string} content - The content.
+	 * @returns {void}
+	 */
+	const handleDone = useCallback(
+		( event: CustomEvent ) => {
+			onDone?.( event?.detail );
+			setRequestingState( 'done' );
+		},
+		[ onDone ]
+	);
+
+	const handleError = useCallback(
+		( errorCode: SuggestionErrorCode ) => {
+			eventSourceRef?.current?.close();
+			setRequestingState( 'error' );
+			setError( getErrorData( errorCode ) );
+			onError?.( getErrorData( errorCode ) );
+		},
+		[ onError ]
+	);
+
+	const handleErrorQuotaExceededError = useCallback(
+		() => handleError( ERROR_QUOTA_EXCEEDED ),
+		[]
+	);
+
+	const handleUnclearPromptError = useCallback( () => handleError( ERROR_UNCLEAR_PROMPT ), [] );
+
+	const handleServiceUnavailableError = useCallback(
+		() => handleError( ERROR_SERVICE_UNAVAILABLE ),
+		[]
+	);
+
+	const handleModerationError = useCallback( () => handleError( ERROR_MODERATION ), [] );
+
+	const handleNetwotkError = useCallback( () => handleError( ERROR_NETWORK ), [] );
+
+	/**
+	 * 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,
+			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 )
+				);
+			} else {
+				debug( '%o', promptArg );
+			}
+
+			// Set the request status.
+			setRequestingState( 'requesting' );
+
+			try {
+				eventSourceRef.current = await askQuestion( promptArg, options );
+
+				if ( ! eventSourceRef?.current ) {
+					return;
+				}
+
+				// Alias
+				const eventSource = eventSourceRef.current;
+
+				// Set the request status.
+				setRequestingState( 'suggesting' );
+
+				eventSource.addEventListener( 'suggestion', handleSuggestion );
+
+				eventSource.addEventListener( ERROR_QUOTA_EXCEEDED, handleErrorQuotaExceededError );
+				eventSource.addEventListener( ERROR_UNCLEAR_PROMPT, handleUnclearPromptError );
+				eventSource.addEventListener( ERROR_SERVICE_UNAVAILABLE, handleServiceUnavailableError );
+				eventSource.addEventListener( ERROR_MODERATION, handleModerationError );
+				eventSource.addEventListener( ERROR_NETWORK, handleNetwotkError );
+
+				eventSource.addEventListener( 'done', handleDone );
+			} catch ( e ) {
+				// eslint-disable-next-line no-console
+				console.error( e );
+			}
+		},
+		[
+			handleDone,
+			handleErrorQuotaExceededError,
+			handleUnclearPromptError,
+			handleServiceUnavailableError,
+			handleModerationError,
+			handleNetwotkError,
+			handleSuggestion,
+		]
+	);
+
+	// Request suggestions automatically when ready.
+	useEffect( () => {
+		// Check if there is a prompt to request.
+		if ( ! prompt?.length ) {
+			return;
+		}
+
+		// Trigger the request.
+		if ( autoRequest ) {
+			request( prompt, askQuestionOptions );
+		}
+
+		return () => {
+			if ( ! eventSourceRef?.current ) {
+				return;
+			}
+
+			// Alias
+			const eventSource = eventSourceRef.current;
+
+			// Close the connection.
+			eventSource.close();
+
+			// Clean up the event listeners.
+			eventSource.removeEventListener( 'suggestion', handleSuggestion );
+
+			eventSource.removeEventListener( ERROR_QUOTA_EXCEEDED, handleErrorQuotaExceededError );
+			eventSource.removeEventListener( ERROR_UNCLEAR_PROMPT, handleUnclearPromptError );
+			eventSource.removeEventListener( ERROR_SERVICE_UNAVAILABLE, handleServiceUnavailableError );
+			eventSource.removeEventListener( ERROR_MODERATION, handleModerationError );
+			eventSource.removeEventListener( ERROR_NETWORK, handleNetwotkError );
+
+			eventSource.removeEventListener( 'done', handleDone );
+		};
+	}, [
+		autoRequest,
+		handleDone,
+		handleErrorQuotaExceededError,
+		handleModerationError,
+		handleServiceUnavailableError,
+		handleSuggestion,
+		handleUnclearPromptError,
+		prompt,
+		request,
+	] );
+
+	return {
+		// Data
+		suggestion,
+		error,
+		requestingState,
+
+		// Request handler
+		request,
+
+		// SuggestionsEventSource
+		eventSource: eventSourceRef.current,
+	};
+}

package/src/icons/Readme.md

@@ -0,0 +1,22 @@
+# Icons
+
+This library provides you with a selection of icons to use in your Gutenberg applications.
+
+- aiAssistantIcon
+- origamiPlane
+- speakTone
+
+```jsx
+import { Icon } from '@wordpress/components';
+import { aiAssistantIcon } from '@automattic/jetpack-ai-client';
+
+function YourComponent() {
+  // ...
+  return (
+    <div>
+      // Your code here...
+      <Icon icon={ aiAssistantIcon } />
+    </div>
+  );
+}
+```

package/src/icons/ai-assistant.tsx

@@ -0,0 +1,31 @@
+/**
+ * WordPress dependencies
+ */
+import { SVG, Path } from '@wordpress/components';
+import React from 'react';
+
+const aiAssistant = (
+	<SVG
+		viewBox="0 0 32 32"
+		width="32"
+		height="32"
+		fill="currentColor"
+		xmlns="http://www.w3.org/2000/svg"
+		className="ai-assistant-icon"
+	>
+		<Path
+			className="spark-first"
+			d="M9.33301 5.33325L10.4644 8.20188L13.333 9.33325L10.4644 10.4646L9.33301 13.3333L8.20164 10.4646L5.33301 9.33325L8.20164 8.20188L9.33301 5.33325Z"
+		/>
+		<Path
+			className="spark-second"
+			d="M21.3333 5.33333L22.8418 9.15817L26.6667 10.6667L22.8418 12.1752L21.3333 16L19.8248 12.1752L16 10.6667L19.8248 9.15817L21.3333 5.33333Z"
+		/>
+		<Path
+			className="spark-third"
+			d="M14.6667 13.3333L16.5523 18.1144L21.3333 20L16.5523 21.8856L14.6667 26.6667L12.781 21.8856L8 20L12.781 18.1144L14.6667 13.3333Z"
+		/>
+	</SVG>
+);
+
+export default aiAssistant;

package/src/icons/index.ts

@@ -0,0 +1,3 @@
+export { default as aiAssistantIcon } from './ai-assistant';
+export { default as origamiPlaneIcon } from './origami-plane';
+export { default as speakToneIcon } from './speak-tone';

package/src/icons/origami-plane.tsx

@@ -0,0 +1,20 @@
+/**
+ * External dependencies
+ */
+import { SVG, Path } from '@wordpress/components';
+import React from 'react';
+
+const origamiPlane = (
+	<SVG
+		width="24"
+		height="24"
+		viewBox="0 0 24 24"
+		fill="currentColor"
+		xmlns="http://www.w3.org/2000/SVG"
+	>
+		<Path d="M13.5142 18.5098C14.1227 19.6569 14.5367 20.5899 14.5367 20.5899L18.7588 3.84402L4.05433 12.901C4.05433 12.901 5.10588 12.9894 6.41062 13.2114C7.97628 13.4777 9.90652 13.9362 10.8219 14.6646C11.7434 15.3979 12.7731 17.1127 13.5142 18.5098ZM14.0468 16.3975C13.8238 16.0255 13.5879 15.6537 13.3445 15.3013C12.8931 14.6478 12.3509 13.9643 11.7559 13.4909C11.1195 12.9844 10.2767 12.6409 9.51316 12.3968C9.11301 12.2689 8.69633 12.1567 8.28231 12.0585L16.4016 7.05758L14.0468 16.3975Z" />
+		<Path d="M18 5L11 14" stroke="currentColor" />
+	</SVG>
+);
+
+export default origamiPlane;

package/src/icons/speak-tone.tsx

@@ -0,0 +1,24 @@
+/**
+ * WordPress dependencies
+ */
+import { SVG, Path } from '@wordpress/components';
+import React from 'react';
+
+const speakTone = (
+	<SVG width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+		<Path
+			fillRule="evenodd"
+			clipRule="evenodd"
+			d="M12.5 10C12.5 11.3807 11.3807 12.5 10 12.5C8.61929 12.5 7.5 11.3807 7.5 10C7.5 8.61929 8.61929 7.5 10 7.5C11.3807 7.5 12.5 8.61929 12.5 10ZM14 10C14 12.2091 12.2091 14 10 14C7.79086 14 6 12.2091 6 10C6 7.79086 7.79086 6 10 6C12.2091 6 14 7.79086 14 10ZM16.75 21V19C16.75 17.4812 15.5188 16.25 14 16.25L6 16.25C4.48122 16.25 3.25 17.4812 3.25 19V21H4.75L4.75 19C4.75 18.3096 5.30964 17.75 6 17.75L14 17.75C14.6904 17.75 15.25 18.3096 15.25 19V21H16.75Z"
+			fill="currentColor"
+		/>
+		<Path
+			fillRule="evenodd"
+			clipRule="evenodd"
+			d="M19.976 16.3599C21.2507 14.5642 22.0001 12.3695 22.0001 9.99969C22.0001 7.63128 21.2515 5.43769 19.9782 3.64258L18.754 4.50967C19.8537 6.05996 20.5001 7.95434 20.5001 9.99969C20.5001 12.0464 19.8528 13.9419 18.7519 15.4928L19.976 16.3599ZM17.3357 14.4897C18.2357 13.222 18.7648 11.6727 18.7648 9.99969C18.7648 8.32808 18.2365 6.77984 17.3379 5.51279L16.1137 6.37988C16.8387 7.4021 17.2648 8.65114 17.2648 9.99969C17.2648 11.3496 16.8378 12.5998 16.1116 13.6226L17.3357 14.4897Z"
+			fill="currentColor"
+		/>
+	</SVG>
+);
+
+export default speakTone;

package/src/icons/stories/index.stories.tsx

@@ -0,0 +1,46 @@
+/**
+ * External dependencies
+ */
+import { Icon } from '@wordpress/components';
+import React from 'react';
+/**
+ * Internal dependencies
+ */
+import * as allIcons from '../index';
+import styles from './style.module.scss';
+/**
+ * Types
+ */
+import type { Meta } from '@storybook/react';
+
+export default {
+	title: 'JS Packages/AI Client/Icons',
+	component: allIcons,
+	parameters: {},
+} as Meta< typeof allIcons >;
+
+/**
+ * Icons story components.
+ *
+ * @returns {object} - story component
+ */
+function IconsStory() {
+	return (
+		<div className={ styles[ 'icons-container' ] }>
+			{ Object.entries( allIcons ).map( ( [ name, icon ] ) => {
+				return (
+					<div key={ name } className={ styles[ 'icon-container' ] }>
+						<Icon icon={ icon } size={ 32 } />
+						<div className={ styles[ 'icon-name' ] }>{ name }</div>
+					</div>
+				);
+			} ) }
+		</div>
+	);
+}
+
+const Template = args => <IconsStory { ...args } />;
+
+const DefaultArgs = {};
+export const Default = Template.bind( {} );
+Default.args = DefaultArgs;

package/src/icons/stories/style.module.scss

@@ -0,0 +1,21 @@
+.icons-container {
+	display: flex;
+	flex-wrap: wrap;
+	margin-bottom: 20px;
+	flex-direction: column;
+}
+
+.icon-container {
+	padding: 10px;
+	box-shadow: 0 0 1px inset rgba(0, 0, 0 , 0.5 );
+	background-color: white;
+	border-radius: 5px;
+	margin: 2px;
+	display: flex;
+	gap: 8px;
+	align-items: center;
+}
+
+.icon-name {
+	font-size: 14px;
+}