@automattic/jetpack-ai-client 0.12.0 → 0.12.2

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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.12.2] - 2024-04-22
+### Added
+- AI Client: Add Markdown and HTML conversions. [#36906]
+
+## [0.12.1] - 2024-04-15
+### Added
+- AI Client: Add callbacks, initial requesting state and change error handling. [#36869]
+
 ## [0.12.0] - 2024-04-08
 ### Added
 - Add error rejection in image generation. [#36709]
@@ -282,6 +290,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated package dependencies. [#31659]
 - Updated package dependencies. [#31785]
 
+[0.12.2]: https://github.com/Automattic/jetpack-ai-client/compare/v0.12.1...v0.12.2
+[0.12.1]: https://github.com/Automattic/jetpack-ai-client/compare/v0.12.0...v0.12.1
 [0.12.0]: https://github.com/Automattic/jetpack-ai-client/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/Automattic/jetpack-ai-client/compare/v0.10.1...v0.11.0
 [0.10.1]: https://github.com/Automattic/jetpack-ai-client/compare/v0.10.0...v0.10.1

package/build/hooks/use-ai-suggestions/index.d.ts

@@ -17,9 +17,12 @@ type useAiSuggestionsOptions = {
      * AskQuestion options.
      */
     askQuestionOptions?: AskQuestionOptionsArgProps;
+    initialRequestingState?: RequestingStateProp;
     onSuggestion?: (suggestion: string) => void;
     onDone?: (content: string) => void;
+    onStop?: () => void;
     onError?: (error: RequestingErrorProps) => void;
+    onAllErrors?: (error: RequestingErrorProps) => void;
 };
 type useAiSuggestionsProps = {
     suggestion: string;
@@ -29,6 +32,7 @@ type useAiSuggestionsProps = {
     request: (prompt: PromptProp, options?: AskQuestionOptionsArgProps) => Promise<void>;
     reset: () => void;
     stopSuggestion: () => void;
+    handleErrorQuotaExceededError: () => void;
 };
 /**
  * Get the error data for a given error code.
@@ -44,5 +48,5 @@ export declare function getErrorData(errorCode: SuggestionErrorCode): Requesting
  * @param {useAiSuggestionsOptions} options - The options for the hook.
  * @returns {useAiSuggestionsProps}           The props for the hook.
  */
-export default function useAiSuggestions({ prompt, autoRequest, askQuestionOptions, onSuggestion, onDone, onError, }?: useAiSuggestionsOptions): useAiSuggestionsProps;
+export default function useAiSuggestions({ prompt, autoRequest, askQuestionOptions, initialRequestingState, onSuggestion, onDone, onStop, onError, onAllErrors, }?: useAiSuggestionsOptions): useAiSuggestionsProps;
 export {};

package/build/hooks/use-ai-suggestions/index.js

@@ -3,13 +3,11 @@
  */
 import { useCallback, useEffect, useRef, useState } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
-import debugFactory from 'debug';
 /**
  * Internal dependencies
  */
 import askQuestion from '../../ask-question/index.js';
-import { ERROR_MODERATION, ERROR_NETWORK, ERROR_QUOTA_EXCEEDED, ERROR_SERVICE_UNAVAILABLE, ERROR_UNCLEAR_PROMPT, } from '../../types.js';
-const debug = debugFactory('jetpack-ai-client:use-suggestion');
+import { ERROR_CONTEXT_TOO_LARGE, ERROR_MODERATION, ERROR_NETWORK, ERROR_QUOTA_EXCEEDED, ERROR_SERVICE_UNAVAILABLE, ERROR_UNCLEAR_PROMPT, ERROR_RESPONSE, } from '../../types.js';
 /**
  * Get the error data for a given error code.
  *
@@ -42,6 +40,12 @@ export function getErrorData(errorCode) {
                 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_CONTEXT_TOO_LARGE:
+            return {
+                code: ERROR_CONTEXT_TOO_LARGE,
+                message: __('The content is too large to be processed all at once. Please try to shorten it or divide it into smaller parts.', 'jetpack-ai-client'),
+                severity: 'info',
+            };
         case ERROR_NETWORK:
         default:
             return {
@@ -58,8 +62,8 @@ export function getErrorData(errorCode) {
  * @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, } = {}) {
-    const [requestingState, setRequestingState] = useState('init');
+export default function useAiSuggestions({ prompt, autoRequest = false, askQuestionOptions = {}, initialRequestingState = 'init', onSuggestion, onDone, onStop, onError, onAllErrors, } = {}) {
+    const [requestingState, setRequestingState] = useState(initialRequestingState);
     const [suggestion, setSuggestion] = useState('');
     const [error, setError] = useState();
     // Store the event source in a ref, so we can handle it if needed.
@@ -81,9 +85,13 @@ export default function useAiSuggestions({ prompt, autoRequest = false, askQuest
      * @returns {void}
      */
     const handleDone = useCallback((event) => {
+        closeEventSource();
         onDone?.(event?.detail);
         setRequestingState('done');
     }, [onDone]);
+    const handleAnyError = useCallback((event) => {
+        onAllErrors?.(event?.detail);
+    }, [onAllErrors]);
     const handleError = useCallback((errorCode) => {
         eventSourceRef?.current?.close();
         setRequestingState('error');
@@ -103,35 +111,26 @@ export default function useAiSuggestions({ prompt, autoRequest = false, askQuest
      * @returns {Promise<void>} The promise.
      */
     const request = useCallback(async (promptArg, options = { ...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);
-        }
+        // Clear any error.
+        setError(undefined);
         // 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, handleNetworkError);
-            eventSource.addEventListener('done', handleDone);
-        }
-        catch (e) {
-            // eslint-disable-next-line no-console
-            console.error(e);
+        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, handleNetworkError);
+        eventSource.addEventListener(ERROR_RESPONSE, handleAnyError);
+        eventSource.addEventListener('done', handleDone);
     }, [
         handleDone,
         handleErrorQuotaExceededError,
@@ -152,11 +151,11 @@ export default function useAiSuggestions({ prompt, autoRequest = false, askQuest
         setError(undefined);
     }, []);
     /**
-     * Stop suggestion handler.
+     * Close the event source connection.
      *
      * @returns {void}
      */
-    const stopSuggestion = useCallback(() => {
+    const closeEventSource = useCallback(() => {
         if (!eventSourceRef?.current) {
             return;
         }
@@ -172,8 +171,6 @@ export default function useAiSuggestions({ prompt, autoRequest = false, askQuest
         eventSource.removeEventListener(ERROR_MODERATION, handleModerationError);
         eventSource.removeEventListener(ERROR_NETWORK, handleNetworkError);
         eventSource.removeEventListener('done', handleDone);
-        // Set requesting state to done since the suggestion stopped.
-        setRequestingState('done');
     }, [
         eventSourceRef,
         handleSuggestion,
@@ -184,6 +181,16 @@ export default function useAiSuggestions({ prompt, autoRequest = false, askQuest
         handleNetworkError,
         handleDone,
     ]);
+    /**
+     * Stop suggestion handler.
+     *
+     * @returns {void}
+     */
+    const stopSuggestion = useCallback(() => {
+        closeEventSource();
+        onStop?.();
+        setRequestingState('done');
+    }, [onStop]);
     // Request suggestions automatically when ready.
     useEffect(() => {
         // Check if there is a prompt to request.
@@ -208,6 +215,8 @@ export default function useAiSuggestions({ prompt, autoRequest = false, askQuest
         request,
         stopSuggestion,
         reset,
+        // Error handlers
+        handleErrorQuotaExceededError,
         // SuggestionsEventSource
         eventSource: eventSourceRef.current,
     };

package/build/hooks/use-transcription-post-processing/index.js

@@ -39,7 +39,6 @@ export default function useTranscriptionPostProcessing({ feature, onReady, onErr
         onError?.(errorData.message);
     }, [setPostProcessingError, onError]);
     const { request, stopSuggestion } = useAiSuggestions({
-        autoRequest: false,
         onSuggestion: handleOnSuggestion,
         onDone: handleOnDone,
         onError: handleOnError,

package/build/index.d.ts

@@ -2,7 +2,7 @@ export { default as requestJwt } from './jwt/index.js';
 export { default as SuggestionsEventSource } from './suggestions-event-source/index.js';
 export { default as askQuestion } from './ask-question/index.js';
 export { default as transcribeAudio } from './audio-transcription/index.js';
-export { default as useAiSuggestions } from './hooks/use-ai-suggestions/index.js';
+export { default as useAiSuggestions, getErrorData } from './hooks/use-ai-suggestions/index.js';
 export { default as useMediaRecording } from './hooks/use-media-recording/index.js';
 export { default as useAudioTranscription } from './hooks/use-audio-transcription/index.js';
 export { default as useTranscriptionPostProcessing } from './hooks/use-transcription-post-processing/index.js';
@@ -12,3 +12,4 @@ export * from './icons/index.js';
 export * from './components/index.js';
 export * from './data-flow/index.js';
 export * from './types.js';
+export * from './libs/index.js';

package/build/index.js

@@ -8,7 +8,7 @@ export { default as transcribeAudio } from './audio-transcription/index.js';
 /*
  * Hooks
  */
-export { default as useAiSuggestions } from './hooks/use-ai-suggestions/index.js';
+export { default as useAiSuggestions, getErrorData } from './hooks/use-ai-suggestions/index.js';
 export { default as useMediaRecording } from './hooks/use-media-recording/index.js';
 export { default as useAudioTranscription } from './hooks/use-audio-transcription/index.js';
 export { default as useTranscriptionPostProcessing } from './hooks/use-transcription-post-processing/index.js';
@@ -30,3 +30,7 @@ export * from './data-flow/index.js';
  * Types
  */
 export * from './types.js';
+/*
+ * Libs
+ */
+export * from './libs/index.js';

package/build/libs/index.d.ts

@@ -0,0 +1 @@
+export { MarkdownToHTML, HTMLToMarkdown, renderHTMLFromMarkdown, renderMarkdownFromHTML, } from './markdown/index.js';

package/build/libs/index.js

@@ -0,0 +1 @@
+export { MarkdownToHTML, HTMLToMarkdown, renderHTMLFromMarkdown, renderMarkdownFromHTML, } from './markdown/index.js';

package/build/libs/markdown/html-to-markdown.d.ts

@@ -0,0 +1,23 @@
+/**
+ * External dependencies
+ */
+import TurndownService from 'turndown';
+/**
+ * Types
+ */
+import type { Options, Rule } from 'turndown';
+export default class HTMLToMarkdown {
+    turndownService: TurndownService;
+    constructor(options?: Options, rules?: {
+        [key: string]: Rule;
+    });
+    /**
+     * Renders HTML from Markdown content with specified processing rules.
+     * @param {object} options         - The options to use when rendering the Markdown content
+     * @param {string} options.content - The HTML content to render
+     * @returns {string}                 The rendered Markdown content
+     */
+    render({ content }: {
+        content: string;
+    }): string;
+}

package/build/libs/markdown/html-to-markdown.js

@@ -0,0 +1,31 @@
+/**
+ * External dependencies
+ */
+import TurndownService from 'turndown';
+const defaultTurndownOptions = { emDelimiter: '_', headingStyle: 'atx' };
+const defaultTurndownRules = {
+    strikethrough: {
+        filter: ['del', 's'],
+        replacement: function (content) {
+            return '~~' + content + '~~';
+        },
+    },
+};
+export default class HTMLToMarkdown {
+    turndownService;
+    constructor(options = defaultTurndownOptions, rules = defaultTurndownRules) {
+        this.turndownService = new TurndownService(options);
+        for (const rule in rules) {
+            this.turndownService.addRule(rule, rules[rule]);
+        }
+    }
+    /**
+     * Renders HTML from Markdown content with specified processing rules.
+     * @param {object} options         - The options to use when rendering the Markdown content
+     * @param {string} options.content - The HTML content to render
+     * @returns {string}                 The rendered Markdown content
+     */
+    render({ content }) {
+        return this.turndownService.turndown(content);
+    }
+}

package/build/libs/markdown/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Internal dependencies
+ */
+import HTMLToMarkdown from './html-to-markdown.js';
+import MarkdownToHTML from './markdown-to-html.js';
+/**
+ * Types
+ */
+import type { Fix as HTMLFix } from './markdown-to-html.js';
+declare const renderHTMLFromMarkdown: ({ content, rules, }: {
+    content: string;
+    rules?: Array<HTMLFix> | 'all';
+}) => string;
+declare const renderMarkdownFromHTML: ({ content }: {
+    content: string;
+}) => string;
+export { MarkdownToHTML, HTMLToMarkdown, renderHTMLFromMarkdown, renderMarkdownFromHTML };

package/build/libs/markdown/index.js

@@ -0,0 +1,14 @@
+/**
+ * Internal dependencies
+ */
+import HTMLToMarkdown from './html-to-markdown.js';
+import MarkdownToHTML from './markdown-to-html.js';
+const defaultMarkdownConverter = new MarkdownToHTML();
+const defaultHTMLConverter = new HTMLToMarkdown();
+const renderHTMLFromMarkdown = ({ content, rules = 'all', }) => {
+    return defaultMarkdownConverter.render({ content, rules });
+};
+const renderMarkdownFromHTML = ({ content }) => {
+    return defaultHTMLConverter.render({ content });
+};
+export { MarkdownToHTML, HTMLToMarkdown, renderHTMLFromMarkdown, renderMarkdownFromHTML };

package/build/libs/markdown/markdown-to-html.d.ts

@@ -0,0 +1,24 @@
+/**
+ * External dependencies
+ */
+import MarkdownIt from 'markdown-it';
+/**
+ * Types
+ */
+import type { Options } from 'markdown-it';
+export type Fix = 'list';
+export default class MarkdownToHTML {
+    markdownConverter: MarkdownIt;
+    constructor(options?: Options);
+    /**
+     * Renders HTML from Markdown content with specified processing rules.
+     * @param {object} options         - The options to use when rendering the HTML content
+     * @param {string} options.content - The Markdown content to render
+     * @param {string} options.rules   - The rules to apply to the rendered content
+     * @returns {string}                 The rendered HTML content
+     */
+    render({ content, rules }: {
+        content: string;
+        rules: Array<Fix> | 'all';
+    }): string;
+}

package/build/libs/markdown/markdown-to-html.js

@@ -0,0 +1,33 @@
+/**
+ * External dependencies
+ */
+import MarkdownIt from 'markdown-it';
+const fixes = {
+    list: (content) => {
+        // Fix list indentation
+        return content.replace(/<li>\s+<p>/g, '<li>').replace(/<\/p>\s+<\/li>/g, '</li>');
+    },
+};
+const defaultMarkdownItOptions = {
+    breaks: true,
+};
+export default class MarkdownToHTML {
+    markdownConverter;
+    constructor(options = defaultMarkdownItOptions) {
+        this.markdownConverter = new MarkdownIt(options);
+    }
+    /**
+     * Renders HTML from Markdown content with specified processing rules.
+     * @param {object} options         - The options to use when rendering the HTML content
+     * @param {string} options.content - The Markdown content to render
+     * @param {string} options.rules   - The rules to apply to the rendered content
+     * @returns {string}                 The rendered HTML content
+     */
+    render({ content, rules = 'all' }) {
+        const rendered = this.markdownConverter.render(content);
+        const rulesToApply = rules === 'all' ? Object.keys(fixes) : rules;
+        return rulesToApply.reduce((renderedContent, rule) => {
+            return fixes[rule](renderedContent);
+        }, rendered);
+    }
+}

package/build/suggestions-event-source/index.d.ts

@@ -49,7 +49,6 @@ export default class SuggestionsEventSource extends EventTarget {
     checkForUnclearPrompt(): void;
     close(): void;
     processEvent(e: EventSourceMessage): void;
-    processConnectionError(response: any): void;
     processErrorEvent(e: any): void;
 }
 export {};

package/build/suggestions-event-source/index.js

@@ -128,7 +128,9 @@ export default class SuggestionsEventSource extends EventTarget {
                 if (response.status >= 400 &&
                     response.status <= 500 &&
                     ![413, 422, 429].includes(response.status)) {
-                    this.processConnectionError(response);
+                    debug('Connection error: %o', response);
+                    errorCode = ERROR_NETWORK;
+                    this.dispatchEvent(new CustomEvent(ERROR_NETWORK, { detail: response }));
                 }
                 /*
                  * error code 503
@@ -264,13 +266,6 @@ export default class SuggestionsEventSource extends EventTarget {
             this.dispatchEvent(new CustomEvent('functionCallChunk', { detail: this.fullFunctionCall }));
         }
     }
-    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) {
         debug('onerror: %o', e);
         // Dispatch a generic network error event

package/build/types.d.ts

@@ -28,4 +28,14 @@ export type { RecordingState } from './hooks/use-media-recording/index.js';
 export type CancelablePromise<T = void> = Promise<T> & {
     canceled?: boolean;
 };
+export type Block = {
+    attributes?: {
+        [key: string]: unknown;
+    };
+    clientId?: string;
+    innerBlocks?: Block[];
+    isValid?: boolean;
+    name?: string;
+    originalContent?: string;
+};
 export type TranscriptionState = RecordingState | 'validating' | 'processing' | 'error';

package/package.json

@@ -1,7 +1,7 @@
 {
 	"private": false,
 	"name": "@automattic/jetpack-ai-client",
-	"version": "0.12.0",
+	"version": "0.12.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": {
@@ -26,6 +26,8 @@
 		"@storybook/addon-actions": "8.0.6",
 		"@storybook/blocks": "8.0.6",
 		"@storybook/react": "8.0.6",
+		"@types/markdown-it": "14.0.0",
+		"@types/turndown": "5.0.4",
 		"jest": "^29.6.2",
 		"jest-environment-jsdom": "29.7.0",
 		"typescript": "5.0.4"
@@ -39,9 +41,9 @@
 	"main": "./build/index.js",
 	"types": "./build/index.d.ts",
 	"dependencies": {
-		"@automattic/jetpack-base-styles": "^0.6.21",
-		"@automattic/jetpack-connection": "^0.33.7",
-		"@automattic/jetpack-shared-extension-utils": "^0.14.9",
+		"@automattic/jetpack-base-styles": "^0.6.22",
+		"@automattic/jetpack-connection": "^0.33.8",
+		"@automattic/jetpack-shared-extension-utils": "^0.14.10",
 		"@microsoft/fetch-event-source": "2.0.1",
 		"@types/react": "18.2.74",
 		"@wordpress/api-fetch": "6.52.0",
@@ -54,7 +56,9 @@
 		"@wordpress/icons": "9.46.0",
 		"classnames": "2.3.2",
 		"debug": "4.3.4",
+		"markdown-it": "14.0.0",
 		"react": "18.2.0",
-		"react-dom": "18.2.0"
+		"react-dom": "18.2.0",
+		"turndown": "7.1.2"
 	}
 }

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

@@ -3,17 +3,18 @@
  */
 import { useCallback, useEffect, useRef, useState } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
-import debugFactory from 'debug';
 /**
  * Internal dependencies
  */
 import askQuestion from '../../ask-question/index.js';
 import {
+	ERROR_CONTEXT_TOO_LARGE,
 	ERROR_MODERATION,
 	ERROR_NETWORK,
 	ERROR_QUOTA_EXCEEDED,
 	ERROR_SERVICE_UNAVAILABLE,
 	ERROR_UNCLEAR_PROMPT,
+	ERROR_RESPONSE,
 } from '../../types.js';
 /**
  * Types & constants
@@ -56,6 +57,11 @@ type useAiSuggestionsOptions = {
 	 */
 	askQuestionOptions?: AskQuestionOptionsArgProps;
 
+	/*
+	 * Initial requesting state.
+	 */
+	initialRequestingState?: RequestingStateProp;
+
 	/*
 	 * onSuggestion callback.
 	 */
@@ -66,10 +72,20 @@ type useAiSuggestionsOptions = {
 	 */
 	onDone?: ( content: string ) => void;
 
+	/*
+	 * onStop callback.
+	 */
+	onStop?: () => void;
+
 	/*
 	 * onError callback.
 	 */
 	onError?: ( error: RequestingErrorProps ) => void;
+
+	/*
+	 * Error callback common for all errors.
+	 */
+	onAllErrors?: ( error: RequestingErrorProps ) => void;
 };
 
 type useAiSuggestionsProps = {
@@ -107,9 +123,12 @@ type useAiSuggestionsProps = {
 	 * The handler to stop a suggestion.
 	 */
 	stopSuggestion: () => void;
-};
 
-const debug = debugFactory( 'jetpack-ai-client:use-suggestion' );
+	/*
+	 * The handler to handle the quota exceeded error.
+	 */
+	handleErrorQuotaExceededError: () => void;
+};
 
 /**
  * Get the error data for a given error code.
@@ -149,6 +168,15 @@ export function getErrorData( errorCode: SuggestionErrorCode ): RequestingErrorP
 				),
 				severity: 'info',
 			};
+		case ERROR_CONTEXT_TOO_LARGE:
+			return {
+				code: ERROR_CONTEXT_TOO_LARGE,
+				message: __(
+					'The content is too large to be processed all at once. Please try to shorten it or divide it into smaller parts.',
+					'jetpack-ai-client'
+				),
+				severity: 'info',
+			};
 		case ERROR_NETWORK:
 		default:
 			return {
@@ -173,11 +201,15 @@ export default function useAiSuggestions( {
 	prompt,
 	autoRequest = false,
 	askQuestionOptions = {},
+	initialRequestingState = 'init',
 	onSuggestion,
 	onDone,
+	onStop,
 	onError,
+	onAllErrors,
 }: useAiSuggestionsOptions = {} ): useAiSuggestionsProps {
-	const [ requestingState, setRequestingState ] = useState< RequestingStateProp >( 'init' );
+	const [ requestingState, setRequestingState ] =
+		useState< RequestingStateProp >( initialRequestingState );
 	const [ suggestion, setSuggestion ] = useState< string >( '' );
 	const [ error, setError ] = useState< RequestingErrorProps >();
 
@@ -206,12 +238,20 @@ export default function useAiSuggestions( {
 	 */
 	const handleDone = useCallback(
 		( event: CustomEvent ) => {
+			closeEventSource();
 			onDone?.( event?.detail );
 			setRequestingState( 'done' );
 		},
 		[ onDone ]
 	);
 
+	const handleAnyError = useCallback(
+		( event: CustomEvent ) => {
+			onAllErrors?.( event?.detail );
+		},
+		[ onAllErrors ]
+	);
+
 	const handleError = useCallback(
 		( errorCode: SuggestionErrorCode ) => {
 			eventSourceRef?.current?.close();
@@ -250,43 +290,34 @@ export default function useAiSuggestions( {
 			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 );
-			}
+			// Clear any error.
+			setError( undefined );
 
 			// Set the request status.
 			setRequestingState( 'requesting' );
 
-			try {
-				eventSourceRef.current = await askQuestion( promptArg, options );
+			eventSourceRef.current = await askQuestion( promptArg, options );
 
-				if ( ! eventSourceRef?.current ) {
-					return;
-				}
+			if ( ! eventSourceRef?.current ) {
+				return;
+			}
 
-				// Alias
-				const eventSource = eventSourceRef.current;
+			// Alias
+			const eventSource = eventSourceRef.current;
 
-				// Set the request status.
-				setRequestingState( 'suggesting' );
+			// Set the request status.
+			setRequestingState( 'suggesting' );
 
-				eventSource.addEventListener( 'suggestion', handleSuggestion );
+			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, handleNetworkError );
+			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, handleNetworkError );
+			eventSource.addEventListener( ERROR_RESPONSE, handleAnyError );
 
-				eventSource.addEventListener( 'done', handleDone );
-			} catch ( e ) {
-				// eslint-disable-next-line no-console
-				console.error( e );
-			}
+			eventSource.addEventListener( 'done', handleDone );
 		},
 		[
 			handleDone,
@@ -311,11 +342,11 @@ export default function useAiSuggestions( {
 	}, [] );
 
 	/**
-	 * Stop suggestion handler.
+	 * Close the event source connection.
 	 *
 	 * @returns {void}
 	 */
-	const stopSuggestion = useCallback( () => {
+	const closeEventSource = useCallback( () => {
 		if ( ! eventSourceRef?.current ) {
 			return;
 		}
@@ -336,9 +367,6 @@ export default function useAiSuggestions( {
 		eventSource.removeEventListener( ERROR_NETWORK, handleNetworkError );
 
 		eventSource.removeEventListener( 'done', handleDone );
-
-		// Set requesting state to done since the suggestion stopped.
-		setRequestingState( 'done' );
 	}, [
 		eventSourceRef,
 		handleSuggestion,
@@ -350,6 +378,17 @@ export default function useAiSuggestions( {
 		handleDone,
 	] );
 
+	/**
+	 * Stop suggestion handler.
+	 *
+	 * @returns {void}
+	 */
+	const stopSuggestion = useCallback( () => {
+		closeEventSource();
+		onStop?.();
+		setRequestingState( 'done' );
+	}, [ onStop ] );
+
 	// Request suggestions automatically when ready.
 	useEffect( () => {
 		// Check if there is a prompt to request.
@@ -379,6 +418,9 @@ export default function useAiSuggestions( {
 		stopSuggestion,
 		reset,
 
+		// Error handlers
+		handleErrorQuotaExceededError,
+
 		// SuggestionsEventSource
 		eventSource: eventSourceRef.current,
 	};

package/src/hooks/use-transcription-post-processing/index.ts

@@ -83,7 +83,6 @@ export default function useTranscriptionPostProcessing( {
 	);
 
 	const { request, stopSuggestion } = useAiSuggestions( {
-		autoRequest: false,
 		onSuggestion: handleOnSuggestion,
 		onDone: handleOnDone,
 		onError: handleOnError,

package/src/index.ts

@@ -9,7 +9,7 @@ export { default as transcribeAudio } from './audio-transcription/index.js';
 /*
  * Hooks
  */
-export { default as useAiSuggestions } from './hooks/use-ai-suggestions/index.js';
+export { default as useAiSuggestions, getErrorData } from './hooks/use-ai-suggestions/index.js';
 export { default as useMediaRecording } from './hooks/use-media-recording/index.js';
 export { default as useAudioTranscription } from './hooks/use-audio-transcription/index.js';
 export { default as useTranscriptionPostProcessing } from './hooks/use-transcription-post-processing/index.js';
@@ -35,3 +35,8 @@ export * from './data-flow/index.js';
  * Types
  */
 export * from './types.js';
+
+/*
+ * Libs
+ */
+export * from './libs/index.js';

package/src/libs/index.ts

@@ -0,0 +1,6 @@
+export {
+	MarkdownToHTML,
+	HTMLToMarkdown,
+	renderHTMLFromMarkdown,
+	renderMarkdownFromHTML,
+} from './markdown/index.js';

package/src/libs/markdown/README.md

@@ -0,0 +1,74 @@
+# Markdown converters
+
+Typescript functions and classes to convert Markdown to and from HTML.
+
+## HTML to Markdown
+
+The HTML to Markdown conversion uses the [Turndown](https://github.com/mixmark-io/turndown) library and supports Turndown's options and rules.
+
+Example:
+```typescript
+/**
+ * External dependencies
+ */
+import { renderMarkdownFromHTML } from '@automattic/jetpack-ai-client';
+
+const htmlContent = '<strong>Hello world</strong>';
+const markdownContent = renderMarkdownFromHTML( { content: htmlContent } );
+// **Hello world**
+```
+
+To use custom options and rules:
+```typescript
+/**
+ * External dependencies
+ */
+import { HTMLToMarkdown } from '@automattic/jetpack-ai-client';
+
+const htmlContent = '<strong>Hello world</strong>';
+const options = { headingStyle: 'setext' };
+const rules = {
+	customStrong: {
+		filter: [ 'strong' ],
+		replacement: function( content: string ) {
+				return '***' + content + '***';
+		}
+ 	}
+};
+const renderer = new HTMLToMarkdown( options, rules );
+const markdownContent = renderer.render( { content: htmlContent } );
+// ***Hello world***
+```
+
+## Markdown to HTML
+
+The Markdown to HTML conversion uses the [markdown-it](https://github.com/markdown-it/markdown-it) library and supports markdown-it's options. It also adds access to common fixes.
+
+Example:
+```typescript
+/**
+ * External dependencies
+ */
+import { renderHTMLFromMarkdown } from '@automattic/jetpack-ai-client';
+
+const markdownContent = '**Hello world**';
+const htmlContent = renderHTMLFromMarkdown( { content: markdownContent, rules: 'all' } ); // 'all' is a default value
+// <p><strong>Hello world</strong></p>\n
+```
+
+To use custom options and fixes:
+```typescript
+/**
+ * External dependencies
+ */
+import { MarkdownToHTML } from '@automattic/jetpack-ai-client';
+
+const markdownContent = '**Hello world**';
+const options = { breaks: 'false' };
+const rules = [ 'list' ];
+const renderer = new MarkdownToHTML( options );
+const htmlContent = renderer.render( { content: markdownContent, rules } );
+// <p><strong>Hello world</strong></p>\n
+```
+
+Currently `rules` only supports `'all'` and `['list']`. Further specific fixes can be added when necessary.

package/src/libs/markdown/html-to-markdown.ts

@@ -0,0 +1,42 @@
+/**
+ * External dependencies
+ */
+import TurndownService from 'turndown';
+/**
+ * Types
+ */
+import type { Options, Rule } from 'turndown';
+
+const defaultTurndownOptions: Options = { emDelimiter: '_', headingStyle: 'atx' };
+const defaultTurndownRules: { [ key: string ]: Rule } = {
+	strikethrough: {
+		filter: [ 'del', 's' ],
+		replacement: function ( content: string ) {
+			return '~~' + content + '~~';
+		},
+	},
+};
+
+export default class HTMLToMarkdown {
+	turndownService: TurndownService;
+
+	constructor(
+		options: Options = defaultTurndownOptions,
+		rules: { [ key: string ]: Rule } = defaultTurndownRules
+	) {
+		this.turndownService = new TurndownService( options );
+		for ( const rule in rules ) {
+			this.turndownService.addRule( rule, rules[ rule ] );
+		}
+	}
+
+	/**
+	 * Renders HTML from Markdown content with specified processing rules.
+	 * @param {object} options         - The options to use when rendering the Markdown content
+	 * @param {string} options.content - The HTML content to render
+	 * @returns {string}                 The rendered Markdown content
+	 */
+	render( { content }: { content: string } ): string {
+		return this.turndownService.turndown( content );
+	}
+}

package/src/libs/markdown/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Internal dependencies
+ */
+import HTMLToMarkdown from './html-to-markdown.js';
+import MarkdownToHTML from './markdown-to-html.js';
+/**
+ * Types
+ */
+import type { Fix as HTMLFix } from './markdown-to-html.js';
+
+const defaultMarkdownConverter = new MarkdownToHTML();
+const defaultHTMLConverter = new HTMLToMarkdown();
+
+const renderHTMLFromMarkdown = ( {
+	content,
+	rules = 'all',
+}: {
+	content: string;
+	rules?: Array< HTMLFix > | 'all';
+} ) => {
+	return defaultMarkdownConverter.render( { content, rules } );
+};
+
+const renderMarkdownFromHTML = ( { content }: { content: string } ) => {
+	return defaultHTMLConverter.render( { content } );
+};
+
+export { MarkdownToHTML, HTMLToMarkdown, renderHTMLFromMarkdown, renderMarkdownFromHTML };

package/src/libs/markdown/markdown-to-html.ts

@@ -0,0 +1,48 @@
+/**
+ * External dependencies
+ */
+import MarkdownIt from 'markdown-it';
+/**
+ * Types
+ */
+import type { Options } from 'markdown-it';
+
+export type Fix = 'list';
+type Fixes = {
+	[ key in Fix ]: ( content: string ) => string;
+};
+
+const fixes: Fixes = {
+	list: ( content: string ) => {
+		// Fix list indentation
+		return content.replace( /<li>\s+<p>/g, '<li>' ).replace( /<\/p>\s+<\/li>/g, '</li>' );
+	},
+};
+
+const defaultMarkdownItOptions: Options = {
+	breaks: true,
+};
+
+export default class MarkdownToHTML {
+	markdownConverter: MarkdownIt;
+
+	constructor( options: Options = defaultMarkdownItOptions ) {
+		this.markdownConverter = new MarkdownIt( options );
+	}
+
+	/**
+	 * Renders HTML from Markdown content with specified processing rules.
+	 * @param {object} options         - The options to use when rendering the HTML content
+	 * @param {string} options.content - The Markdown content to render
+	 * @param {string} options.rules   - The rules to apply to the rendered content
+	 * @returns {string}                 The rendered HTML content
+	 */
+	render( { content, rules = 'all' }: { content: string; rules: Array< Fix > | 'all' } ): string {
+		const rendered = this.markdownConverter.render( content );
+		const rulesToApply = rules === 'all' ? Object.keys( fixes ) : rules;
+
+		return rulesToApply.reduce( ( renderedContent, rule ) => {
+			return fixes[ rule ]( renderedContent );
+		}, rendered );
+	}
+}

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

@@ -197,7 +197,9 @@ export default class SuggestionsEventSource extends EventTarget {
 					response.status <= 500 &&
 					! [ 413, 422, 429 ].includes( response.status )
 				) {
-					this.processConnectionError( response );
+					debug( 'Connection error: %o', response );
+					errorCode = ERROR_NETWORK;
+					this.dispatchEvent( new CustomEvent( ERROR_NETWORK, { detail: response } ) );
 				}
 
 				/*
@@ -358,16 +360,6 @@ 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 ) {
 		debug( 'onerror: %o', e );
 

package/src/types.ts

@@ -93,6 +93,17 @@ export type { RecordingState } from './hooks/use-media-recording/index.js';
  */
 export type CancelablePromise< T = void > = Promise< T > & { canceled?: boolean };
 
+export type Block = {
+	attributes?: {
+		[ key: string ]: unknown;
+	};
+	clientId?: string;
+	innerBlocks?: Block[];
+	isValid?: boolean;
+	name?: string;
+	originalContent?: string;
+};
+
 /*
  * Transcription types
  */