@automattic/jetpack-ai-client 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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]
+- AI Assistant: add function calling feature. [#32161]
+- AI Client: add AI Assistant data context. [#32129]
+- AI Client: add useAiContext() react hook. [#32145]
+- AI Client: add useAiSuggestions() react custom hook. [#32022]
+- AI Client: introduce AI Control component. [#32163]
+- AI Client: introduce withAiDataProvider HOC. [#32142]
+
+### Changed
+- AI Client: add Icon suffix to icon components. [#32173]
+- AI Client: handle properly passing the post_id parameter to endpoint. [#32104]
+- AI Client: replace using CSS modules with the regular way. [#32171]
+
+### Removed
+- AI Client: remove unused image library [#32127]
+
 ## 0.1.0 - 2023-07-25
 ### Added
 - Add Jetpack AI Client [#30855]
@@ -17,3 +53,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated package dependencies. [#31468]
 - 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

@@ -1,4 +1,31 @@
+/*
+ * Core library exports
+ */
 export { default as requestJwt } from './src/jwt';
 export { default as SuggestionsEventSource } from './src/suggestions-event-source';
 export { default as askQuestion } from './src/ask-question';
-export * from './src/index.js';
+
+/*
+ * Hooks
+ */
+export { default as useAiSuggestions } from './src/hooks/use-ai-suggestions';
+
+/*
+ * Components: Icons
+ */
+export * from './src/icons';
+
+/*
+ * Components
+ */
+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.0",
+	"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,7 +21,10 @@
 	},
 	"type": "module",
 	"devDependencies": {
-		"jest": "*",
+		"@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",
 		"typescript": "5.0.4"
 	},
@@ -30,9 +33,19 @@
 	},
 	"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",
-		"debug": "4.3.4"
+		"@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",
+		"@wordpress/icons": "9.28.0",
+		"classnames": "2.3.2",
+		"debug": "4.3.4",
+		"react": "18.2.0",
+		"react-dom": "18.2.0"
 	}
 }

package/src/ask-question/Readme.md

@@ -11,7 +11,7 @@ function askQuestion(
 ): Promise< SuggestionsEventSource >
 ```
 
-## Parameters
+<h2 id="ask-question-parameters">Parameters</h2>
 
 - `question` (**string** | **PromptItemProps[]**):
     - The question to ask. 

package/src/ask-question/index.ts

@@ -7,9 +7,9 @@ import SuggestionsEventSource from '../suggestions-event-source';
 /*
  * Types & constants
  */
-import type { PromptItemProps } from '../types';
+import type { PromptProp } from '../types';
 
-type AskQuestionOptionsArgProps = {
+export type AskQuestionOptionsArgProps = {
 	/*
 	 * ID of the post where the question is asked.
 	 */
@@ -24,6 +24,16 @@ type AskQuestionOptionsArgProps = {
 	 * Allows to use a specific AI assistant feature. Default value is undefined.
 	 */
 	feature?: 'ai-assistant-experimental' | string | undefined;
+
+	/*
+	 * Allows the use of function calling. Default value is undefined.
+	 */
+	functions?: Array< {
+		name?: string;
+		arguments?: string;
+		// eslint-disable-next-line @typescript-eslint/ban-types
+		implementation?: Function;
+	} >;
 };
 
 const debug = debugFactory( 'jetpack-ai-client:ask-question' );
@@ -32,7 +42,7 @@ const debug = debugFactory( 'jetpack-ai-client:ask-question' );
  * An asynchronous function that asks a question
  * and returns an event source with suggestions.
  *
- * @param {string|PromptItemProps[]} question - The question to ask. It can be a simple string or an array of PromptItemProps objects.
+ * @param {PromptProp} question - The question to ask. It can be a simple string or an array of PromptMessageItemProps objects.
  * @param {AskQuestionOptionsArgProps} options - An optional object for additional configuration:
  * @returns {Promise<SuggestionsEventSource>}    A promise that resolves to an instance of the SuggestionsEventSource
  * @example
@@ -47,12 +57,16 @@ const debug = debugFactory( 'jetpack-ai-client:ask-question' );
  *  } );
  */
 export default async function askQuestion(
-	question: string | PromptItemProps[],
-	{ postId = null, fromCache = false, feature }: AskQuestionOptionsArgProps = {}
+	question: PromptProp,
+	{ postId = null, fromCache = false, feature, functions }: AskQuestionOptionsArgProps = {}
 ): Promise< SuggestionsEventSource > {
-	debug( 'Asking question: %o. options: %o', question, { postId, fromCache, feature } );
+	debug( 'Asking question: %o. options: %o', question, { postId, fromCache, feature, functions } );
 
 	const { token } = await requestJwt();
 
-	return new SuggestionsEventSource( { question, token, options: { postId, feature, fromCache } } );
+	return new SuggestionsEventSource( {
+		question,
+		token,
+		options: { postId, feature, fromCache, functions },
+	} );
 }

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

@@ -0,0 +1,165 @@
+/**
+ * External dependencies
+ */
+import { PlainText } from '@wordpress/block-editor';
+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';
+import classNames from 'classnames';
+/**
+ * Internal dependencies
+ */
+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 = () => {};
+
+/**
+ * AI Control component.
+ *
+ * @param {object} props - component props
+ * @param {boolean} props.loading - loading state
+ * @param {string} props.value - input value
+ * @param {string} props.placeholder - input placeholder
+ * @param {boolean} props.showAccept - show accept button
+ * @param {string} props.acceptLabel - accept button label
+ * @param {boolean} props.showButtonsLabel - show buttons label
+ * @param {boolean} props.isOpaque - is opaque
+ * @param {Function} props.onChange - input change handler
+ * @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( {
+	loading = false,
+	value = '',
+	placeholder = '',
+	showAccept = false,
+	acceptLabel = __( 'Accept', 'jetpack-ai-client' ),
+	showButtonsLabel = true,
+	isOpaque = false,
+	requestingState = 'init',
+	onChange = noop,
+	onSend = noop,
+	onStop = noop,
+	onAccept = noop,
+}: {
+	loading?: boolean;
+	value: string;
+	placeholder?: string;
+	showAccept?: boolean;
+	acceptLabel?: string;
+	showButtonsLabel?: boolean;
+	isOpaque?: boolean;
+	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
+				className={ classNames( 'jetpack-components-ai-control__wrapper', {
+					'is-opaque': isOpaque,
+				} ) }
+			>
+				<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>
+
+				<div className="jetpack-components-ai-control__controls">
+					<div className="jetpack-components-ai-control__controls-prompt_button_wrapper">
+						{ ! loading ? (
+							<Button
+								className="jetpack-components-ai-control__controls-prompt_button"
+								onClick={ () => onSend( value ) }
+								isSmall={ true }
+								disabled={ ! value?.length }
+								label={ __( 'Send request', 'jetpack-ai-client' ) }
+							>
+								<Icon icon={ arrowUp } />
+								{ showButtonsLabel && __( 'Send', 'jetpack-ai-client' ) }
+							</Button>
+						) : (
+							<Button
+								className="jetpack-components-ai-control__controls-prompt_button"
+								onClick={ onStop }
+								isSmall={ true }
+								label={ __( 'Stop request', 'jetpack-ai-client' ) }
+							>
+								<Icon icon={ closeSmall } />
+								{ showButtonsLabel && __( 'Stop', 'jetpack-ai-client' ) }
+							</Button>
+						) }
+					</div>
+
+					{ showAccept && (
+						<div className="jetpack-components-ai-control__controls-prompt_button_wrapper">
+							<Button
+								className="jetpack-components-ai-control__controls-prompt_button"
+								onClick={ onAccept }
+								isSmall={ true }
+								label={ acceptLabel }
+							>
+								<Icon icon={ check } />
+								{ acceptLabel }
+							</Button>
+						</div>
+					) }
+				</div>
+			</div>
+		</div>
+	);
+}

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

@@ -0,0 +1,68 @@
+/**
+ * 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
+ */
+import type { Meta } from '@storybook/react';
+
+export default {
+	title: 'JS Packages/AI Client/AI Control',
+	component: AIControl,
+	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 => {
+	const [ value, setValue ] = useState( '' );
+
+	const handleChange = ( newValue: string ) => {
+		setValue( newValue );
+		args?.onChange?.( newValue );
+	};
+
+	return <AIControl { ...args } onChange={ handleChange } value={ args?.value ?? value } />;
+};
+
+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( {} );
+Default.args = DefaultArgs;