From 752ebbdf6be00e2a0763ba9749acd5d964596989 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 2 Feb 2026 16:18:34 +1000 Subject: [PATCH 01/10] DOC-3356: Initial file setup. --- .../examples/live-demos/tinymceai/index.html | 4 ++ .../examples/live-demos/tinymceai/index.js | 6 ++ modules/ROOT/nav.adoc | 36 ++++++++++ modules/ROOT/pages/available-menu-items.adoc | 6 ++ .../ROOT/pages/available-toolbar-buttons.adoc | 6 ++ .../pages/editor-command-identifiers.adoc | 8 +++ modules/ROOT/pages/events.adoc | 8 +++ modules/ROOT/pages/tinymceai-actions.adoc | 6 ++ .../ROOT/pages/tinymceai-conversations.adoc | 6 ++ .../ROOT/pages/tinymceai-data-handling.adoc | 6 ++ modules/ROOT/pages/tinymceai-limits.adoc | 6 ++ modules/ROOT/pages/tinymceai-models.adoc | 6 ++ modules/ROOT/pages/tinymceai-on-premises.adoc | 8 +++ modules/ROOT/pages/tinymceai-permissions.adoc | 6 ++ modules/ROOT/pages/tinymceai-privacy.adoc | 6 ++ modules/ROOT/pages/tinymceai-quick-start.adoc | 10 +++ modules/ROOT/pages/tinymceai-rest-api.adoc | 6 ++ modules/ROOT/pages/tinymceai-reviews.adoc | 6 ++ modules/ROOT/pages/tinymceai-streaming.adoc | 6 ++ ...ymceai-with-jwt-authentication-nodejs.adoc | 6 ++ ...tinymceai-with-jwt-authentication-php.adoc | 6 ++ .../ROOT/pages/tinymceai-without-tinymce.adoc | 6 ++ modules/ROOT/pages/tinymceai.adoc | 68 +++++++++++++++++++ .../partials/commands/tinymceai-cmds.adoc | 1 + .../tinymceai_token_provider.adoc | 20 ++++++ .../partials/events/tinymceai-events.adoc | 1 + .../partials/index-pages/premium-plugins.adoc | 6 ++ .../menu-item-ids/tinymceai-menu-items.adoc | 4 ++ .../partials/plugin-apis/tinymceai-apis.adoc | 1 + .../tinymceai-toolbar-buttons.adoc | 4 ++ 30 files changed, 275 insertions(+) create mode 100644 modules/ROOT/examples/live-demos/tinymceai/index.html create mode 100644 modules/ROOT/examples/live-demos/tinymceai/index.js create mode 100644 modules/ROOT/pages/tinymceai-actions.adoc create mode 100644 modules/ROOT/pages/tinymceai-conversations.adoc create mode 100644 modules/ROOT/pages/tinymceai-data-handling.adoc create mode 100644 modules/ROOT/pages/tinymceai-limits.adoc create mode 100644 modules/ROOT/pages/tinymceai-models.adoc create mode 100644 modules/ROOT/pages/tinymceai-on-premises.adoc create mode 100644 modules/ROOT/pages/tinymceai-permissions.adoc create mode 100644 modules/ROOT/pages/tinymceai-privacy.adoc create mode 100644 modules/ROOT/pages/tinymceai-quick-start.adoc create mode 100644 modules/ROOT/pages/tinymceai-rest-api.adoc create mode 100644 modules/ROOT/pages/tinymceai-reviews.adoc create mode 100644 modules/ROOT/pages/tinymceai-streaming.adoc create mode 100644 modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc create mode 100644 modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc create mode 100644 modules/ROOT/pages/tinymceai-without-tinymce.adoc create mode 100644 modules/ROOT/pages/tinymceai.adoc create mode 100644 modules/ROOT/partials/commands/tinymceai-cmds.adoc create mode 100644 modules/ROOT/partials/configuration/tinymceai_token_provider.adoc create mode 100644 modules/ROOT/partials/events/tinymceai-events.adoc create mode 100644 modules/ROOT/partials/menu-item-ids/tinymceai-menu-items.adoc create mode 100644 modules/ROOT/partials/plugin-apis/tinymceai-apis.adoc create mode 100644 modules/ROOT/partials/toolbar-button-ids/tinymceai-toolbar-buttons.adoc diff --git a/modules/ROOT/examples/live-demos/tinymceai/index.html b/modules/ROOT/examples/live-demos/tinymceai/index.html new file mode 100644 index 0000000000..6310dd02f0 --- /dev/null +++ b/modules/ROOT/examples/live-demos/tinymceai/index.html @@ -0,0 +1,4 @@ + diff --git a/modules/ROOT/examples/live-demos/tinymceai/index.js b/modules/ROOT/examples/live-demos/tinymceai/index.js new file mode 100644 index 0000000000..e979506efb --- /dev/null +++ b/modules/ROOT/examples/live-demos/tinymceai/index.js @@ -0,0 +1,6 @@ +tinymce.init({ + selector: 'textarea#tinymceai', + height: '800px', + plugins: ["tinymceai", "advlist", "anchor", "autolink", "charmap", "code"], + toolbar: "undo redo | tinymceai | styles | bold italic underline strikethrough | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | link image" +}); diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 35fd12a1c3..7a2111f81f 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -260,6 +260,42 @@ **** xref:ai-bedrock.adoc[Amazon Bedrock integration guide] **** xref:ai-gemini.adoc[Google Gemini integration guide] **** xref:ai-proxy.adoc[AI proxy server reference guide] +*** TinyMCE AI +**** xref:tinymceai.adoc[Overview] +***** xref:tinymceai.adoc#what-is-tinymce-ai[What is TinyMCE AI] +***** xref:tinymceai.adoc#plugin-vs-api[Plugin vs API] +***** xref:tinymceai.adoc#architecture-overview[Architecture overview] +***** xref:tinymceai.adoc#interactive-example[Interactive example] +**** xref:tinymceai.adoc#plugin-reference[Plugin reference] +***** xref:tinymceai.adoc#basic-setup[Basic setup] +***** xref:tinymceai.adoc#options[Options] +***** xref:tinymceai.adoc#toolbar-buttons[Toolbar buttons] +***** xref:tinymceai.adoc#menu-items[Menu items] +***** xref:tinymceai.adoc#commands[Commands] +***** xref:tinymceai.adoc#events[Events] +***** xref:tinymceai.adoc#apis[APIs] +**** xref:tinymceai-quick-start.adoc[Quick start] +***** xref:tinymceai-quick-start.adoc#plugin-quick-start[Plugin quick start] +***** xref:tinymceai-quick-start.adoc#api-quick-start[API quick start] +**** Features +***** xref:tinymceai-conversations.adoc[Conversations] +***** xref:tinymceai-reviews.adoc[Reviews] +***** xref:tinymceai-actions.adoc[Actions] +**** Configuration +***** xref:tinymceai-models.adoc[AI models] +***** xref:tinymceai-permissions.adoc[Permissions] +***** xref:tinymceai-limits.adoc[Limits] +***** xref:tinymceai-streaming.adoc[Streaming] +**** Integration +***** xref:tinymceai-with-jwt-authentication-nodejs.adoc[JWT authentication (Node.js)] +***** xref:tinymceai-with-jwt-authentication-php.adoc[JWT authentication (PHP)] +***** xref:tinymceai-without-tinymce.adoc[Using the AI service without TinyMCE] +***** xref:tinymceai-rest-api.adoc[REST API reference] +**** Security +***** xref:tinymceai-data-handling.adoc[Data handling] +***** xref:tinymceai-privacy.adoc[Privacy] +**** xref:tinymceai-on-premises.adoc[On-premises] +***** xref:tinymceai-on-premises.adoc#availability-and-roadmap[Availability and roadmap] *** xref:casechange.adoc[Case Change] *** xref:checklist.adoc[Checklist] *** Comments diff --git a/modules/ROOT/pages/available-menu-items.adoc b/modules/ROOT/pages/available-menu-items.adoc index 65d7edf122..19e1c3d121 100644 --- a/modules/ROOT/pages/available-menu-items.adoc +++ b/modules/ROOT/pages/available-menu-items.adoc @@ -58,6 +58,12 @@ include::partial$misc/plugin-menu-item-id-boilerplate.adoc[] :plugincode: ai include::partial$misc/plugin-menu-item-id-boilerplate.adoc[] +:plugincategory: premium +:pluginname: TinyMCE AI +:plugincode: tinymceai +:pluginpage: tinymceai.adoc +include::partial$misc/plugin-menu-item-id-boilerplate.adoc[] + :plugincategory: opensource :pluginname: Anchor :plugincode: anchor diff --git a/modules/ROOT/pages/available-toolbar-buttons.adoc b/modules/ROOT/pages/available-toolbar-buttons.adoc index 065e97ac95..fa62ebcb2c 100644 --- a/modules/ROOT/pages/available-toolbar-buttons.adoc +++ b/modules/ROOT/pages/available-toolbar-buttons.adoc @@ -35,6 +35,12 @@ include::partial$misc/plugin-toolbar-button-id-boilerplate.adoc[] :plugincode: ai include::partial$misc/plugin-toolbar-button-id-boilerplate.adoc[] +:plugincategory: premium +:pluginname: TinyMCE AI +:plugincode: tinymceai +:pluginpage: tinymceai.adoc +include::partial$misc/plugin-toolbar-button-id-boilerplate.adoc[] + :plugincategory: premium :pluginname: Enhanced Code Editor :plugincode: advcode diff --git a/modules/ROOT/pages/editor-command-identifiers.adoc b/modules/ROOT/pages/editor-command-identifiers.adoc index 134b326630..87ce38f82d 100644 --- a/modules/ROOT/pages/editor-command-identifiers.adoc +++ b/modules/ROOT/pages/editor-command-identifiers.adoc @@ -215,6 +215,7 @@ Commands are available for the following plugins: * xref:advancedlists[Advanced Lists] * xref:Enhanced Tables[Enhanced Tables] * xref:anchor[Anchor] +* xref:tinymceai[TinyMCE AI] * xref:autoresize[Autoresize] * xref:casechange[Case Change] * xref:charactermap[Character Map] @@ -525,6 +526,13 @@ The following commands require the xref:tableofcontents.adoc[Table of Contents ( include::partial$commands/tableofcontents-cmds.adoc[leveloffset=+3] +[[tinymceai]] +==== TinyMCE AI + +The following commands require the xref:tinymceai.adoc[TinyMCE AI (`+tinymceai+`)] plugin. + +include::partial$commands/tinymceai-cmds.adoc[leveloffset=+3] + [[advtemplate]] ==== Templates diff --git a/modules/ROOT/pages/events.adoc b/modules/ROOT/pages/events.adoc index 22f2175abb..82eb741ce1 100644 --- a/modules/ROOT/pages/events.adoc +++ b/modules/ROOT/pages/events.adoc @@ -245,6 +245,7 @@ The following plugins provide events. * xref:a11ychecker-events[Accessibility Checker events] * xref:autosave-events[Autosave events] * xref:character-map-events[Character Map events] +* xref:tinymceai-events[TinyMCE AI events] * xref:comments-events[Comments events] * xref:format-painter-events[Format Painter events] * xref:fullscreen-events[Fullscreen events] @@ -292,6 +293,13 @@ The following event is provided by the xref:charmap.adoc[Character Map plugin]. |InsertCustomChar |`+{ chr: string }+` |Fired before a special character is inserted into the editor. |=== +[[tinymceai-events]] +=== TinyMCE AI events + +The following events are provided by the xref:tinymceai.adoc[TinyMCE AI plugin]. + +include::partial$events/tinymceai-events.adoc[] + [[comments-events]] === Comments events diff --git a/modules/ROOT/pages/tinymceai-actions.adoc b/modules/ROOT/pages/tinymceai-actions.adoc new file mode 100644 index 0000000000..728f2522e8 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-actions.adoc @@ -0,0 +1,6 @@ += TinyMCE AI Quick Actions + +:navtitle: Quick Actions +:description: Quick actions feature for {productname} +:description_short: Quick actions feature +:keywords: AI, quick actions, actions, tinymceai diff --git a/modules/ROOT/pages/tinymceai-conversations.adoc b/modules/ROOT/pages/tinymceai-conversations.adoc new file mode 100644 index 0000000000..fb661c8a5b --- /dev/null +++ b/modules/ROOT/pages/tinymceai-conversations.adoc @@ -0,0 +1,6 @@ += TinyMCE AI Conversations + +:navtitle: Conversations +:description: AI chat feature for {productname} +:description_short: AI chat feature +:keywords: AI, chat, conversations, tinymceai diff --git a/modules/ROOT/pages/tinymceai-data-handling.adoc b/modules/ROOT/pages/tinymceai-data-handling.adoc new file mode 100644 index 0000000000..81635d1d66 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-data-handling.adoc @@ -0,0 +1,6 @@ += TinyMCE AI Data Handling + +:navtitle: Data Handling +:description: Data handling and security for TinyMCE AI +:description_short: Data handling and security +:keywords: AI, data handling, security, tinymceai diff --git a/modules/ROOT/pages/tinymceai-limits.adoc b/modules/ROOT/pages/tinymceai-limits.adoc new file mode 100644 index 0000000000..5c77cdec39 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-limits.adoc @@ -0,0 +1,6 @@ += TinyMCE AI Limits + +:navtitle: Limits +:description: Usage limits configuration for TinyMCE AI +:description_short: Usage limits configuration +:keywords: AI, limits, configuration, tinymceai diff --git a/modules/ROOT/pages/tinymceai-models.adoc b/modules/ROOT/pages/tinymceai-models.adoc new file mode 100644 index 0000000000..ea7b29fad0 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-models.adoc @@ -0,0 +1,6 @@ += TinyMCE AI Models + +:navtitle: AI Models +:description: AI model configuration for TinyMCE AI +:description_short: AI model configuration +:keywords: AI, models, configuration, tinymceai diff --git a/modules/ROOT/pages/tinymceai-on-premises.adoc b/modules/ROOT/pages/tinymceai-on-premises.adoc new file mode 100644 index 0000000000..2f93915a19 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-on-premises.adoc @@ -0,0 +1,8 @@ += TinyMCE AI On-Premises + +:navtitle: On-Premises +:description: On-premises availability and roadmap for TinyMCE AI +:description_short: On-premises availability +:keywords: AI, on-premises, availability, roadmap, tinymceai + +== Availability and roadmap diff --git a/modules/ROOT/pages/tinymceai-permissions.adoc b/modules/ROOT/pages/tinymceai-permissions.adoc new file mode 100644 index 0000000000..494ba1263b --- /dev/null +++ b/modules/ROOT/pages/tinymceai-permissions.adoc @@ -0,0 +1,6 @@ += TinyMCE AI Permissions + +:navtitle: Permissions +:description: Permission configuration for TinyMCE AI +:description_short: Permission configuration +:keywords: AI, permissions, configuration, tinymceai diff --git a/modules/ROOT/pages/tinymceai-privacy.adoc b/modules/ROOT/pages/tinymceai-privacy.adoc new file mode 100644 index 0000000000..d63b40582c --- /dev/null +++ b/modules/ROOT/pages/tinymceai-privacy.adoc @@ -0,0 +1,6 @@ += TinyMCE AI Privacy + +:navtitle: Privacy +:description: Privacy considerations for TinyMCE AI +:description_short: Privacy considerations +:keywords: AI, privacy, data privacy, tinymceai diff --git a/modules/ROOT/pages/tinymceai-quick-start.adoc b/modules/ROOT/pages/tinymceai-quick-start.adoc new file mode 100644 index 0000000000..0581c5f58b --- /dev/null +++ b/modules/ROOT/pages/tinymceai-quick-start.adoc @@ -0,0 +1,10 @@ += TinyMCE AI Quick Start + +:navtitle: Quick Start +:description: Quick start guide for TinyMCE AI plugin and API +:description_short: Quick start guide for TinyMCE AI +:keywords: AI, quick start, tinymceai, setup + +== Plugin quick start + +== API quick start diff --git a/modules/ROOT/pages/tinymceai-rest-api.adoc b/modules/ROOT/pages/tinymceai-rest-api.adoc new file mode 100644 index 0000000000..c35eabe322 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-rest-api.adoc @@ -0,0 +1,6 @@ += TinyMCE AI REST API Reference + +:navtitle: REST API Reference +:description: REST API reference for TinyMCE AI +:description_short: REST API reference +:keywords: AI, REST API, API reference, tinymceai diff --git a/modules/ROOT/pages/tinymceai-reviews.adoc b/modules/ROOT/pages/tinymceai-reviews.adoc new file mode 100644 index 0000000000..8f4c42f927 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-reviews.adoc @@ -0,0 +1,6 @@ += TinyMCE AI Reviews + +:navtitle: Reviews +:description: AI review feature for {productname} +:description_short: AI review feature +:keywords: AI, review, reviews, tinymceai diff --git a/modules/ROOT/pages/tinymceai-streaming.adoc b/modules/ROOT/pages/tinymceai-streaming.adoc new file mode 100644 index 0000000000..22e84a9bb7 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-streaming.adoc @@ -0,0 +1,6 @@ += TinyMCE AI Streaming + +:navtitle: Streaming +:description: Streaming configuration for TinyMCE AI +:description_short: Streaming configuration +:keywords: AI, streaming, configuration, tinymceai diff --git a/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc b/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc new file mode 100644 index 0000000000..78df157bf8 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc @@ -0,0 +1,6 @@ += TinyMCE AI with JWT Authentication (Node.js) + +:navtitle: JWT Authentication (Node.js) +:description: JWT authentication setup for TinyMCE AI using Node.js +:description_short: JWT authentication with Node.js +:keywords: AI, JWT, authentication, Node.js, tinymceai diff --git a/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc b/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc new file mode 100644 index 0000000000..0e7a4027ba --- /dev/null +++ b/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc @@ -0,0 +1,6 @@ += TinyMCE AI with JWT Authentication (PHP) + +:navtitle: JWT Authentication (PHP) +:description: JWT authentication setup for TinyMCE AI using PHP +:description_short: JWT authentication with PHP +:keywords: AI, JWT, authentication, PHP, tinymceai diff --git a/modules/ROOT/pages/tinymceai-without-tinymce.adoc b/modules/ROOT/pages/tinymceai-without-tinymce.adoc new file mode 100644 index 0000000000..5740a134ef --- /dev/null +++ b/modules/ROOT/pages/tinymceai-without-tinymce.adoc @@ -0,0 +1,6 @@ += Using the AI Service without TinyMCE + +:navtitle: Using the AI Service without TinyMCE +:description: How to use the AI service without {productname} +:description_short: Using the AI service standalone +:keywords: AI, AI service, standalone, tinymceai diff --git a/modules/ROOT/pages/tinymceai.adoc b/modules/ROOT/pages/tinymceai.adoc new file mode 100644 index 0000000000..3650747a21 --- /dev/null +++ b/modules/ROOT/pages/tinymceai.adoc @@ -0,0 +1,68 @@ += TinyMCE AI + +:navtitle: TinyMCE AI +:description: AI-powered features for {productname} including AI chat, AI review, and quick actions +:description_short: AI-powered features for {productname} +:keywords: AI, artificial intelligence, chat, review, quick actions, tinymceai +:pluginname: TinyMCE AI +:plugincode: tinymceai +:pluginminimumplan: enterpriseplan +:plugincategory: premium + +[[what-is-tinymce-ai]] +== What is TinyMCE AI + +[[plugin-vs-api]] +== Plugin vs API + +[[architecture-overview]] +== Architecture overview + +[[interactive-example]] +== Interactive example + +liveDemo::{tinymceai}[] + +[[plugin-reference]] +== Plugin reference + +[[basic-setup]] +== Basic setup + +[[options]] +== Options + +The following configuration options affect the behavior of the {pluginname} plugin. + +include::partial$configuration/tinymceai_token_provider.adoc[leveloffset=+1] + +[[toolbar-buttons]] +== Toolbar buttons + +include::partial$misc/plugin-toolbar-button-id-boilerplate.adoc[] + +[[menu-items]] +== Menu items + +include::partial$misc/plugin-menu-item-id-boilerplate.adoc[] + +[[commands]] +== Commands + +The {pluginname} plugin provides the following {productname} commands. + +include::partial$commands/{plugincode}-cmds.adoc[] + +[[events]] +== Events + +The {pluginname} plugin provides the following events. + +include::partial$events/{plugincode}-events.adoc[] + +[[apis]] +== APIs + +The {pluginname} plugin provides the following APIs. + +include::partial$plugin-apis/{plugincode}-apis.adoc[] diff --git a/modules/ROOT/partials/commands/tinymceai-cmds.adoc b/modules/ROOT/partials/commands/tinymceai-cmds.adoc new file mode 100644 index 0000000000..50f73c0a6d --- /dev/null +++ b/modules/ROOT/partials/commands/tinymceai-cmds.adoc @@ -0,0 +1 @@ +== TinyMCE AI Commands diff --git a/modules/ROOT/partials/configuration/tinymceai_token_provider.adoc b/modules/ROOT/partials/configuration/tinymceai_token_provider.adoc new file mode 100644 index 0000000000..569783d92d --- /dev/null +++ b/modules/ROOT/partials/configuration/tinymceai_token_provider.adoc @@ -0,0 +1,20 @@ +[[tinymceai-token-provider]] +== `+tinymceai_token_provider+` + + +*Type:* `+Function+` + +*Default value:* `+undefined+` + +=== Example: using `+tinymceai_token_provider+` + +[source,js] +---- +tinymce.init({ + selector: 'textarea', + plugins: 'tinymceai', + tinymceai_token_provider: function() { + // Token provider implementation + } +}); +---- diff --git a/modules/ROOT/partials/events/tinymceai-events.adoc b/modules/ROOT/partials/events/tinymceai-events.adoc new file mode 100644 index 0000000000..a2c8b6cd30 --- /dev/null +++ b/modules/ROOT/partials/events/tinymceai-events.adoc @@ -0,0 +1 @@ +== TinyMCE AI Events diff --git a/modules/ROOT/partials/index-pages/premium-plugins.adoc b/modules/ROOT/partials/index-pages/premium-plugins.adoc index 8f1777535e..6afb85b3f0 100644 --- a/modules/ROOT/partials/index-pages/premium-plugins.adoc +++ b/modules/ROOT/partials/index-pages/premium-plugins.adoc @@ -200,6 +200,12 @@ xref:tableofcontents.adoc[Table of Contents] Insert a simple Table of Contents into the {productname} editor. +a| +[.lead] +xref:tinymceai.adoc[TinyMCE AI] + +AI-powered features for {productname} including AI chat, AI review, and quick actions. + a| [.lead] xref:tinydrive-introduction.adoc[Tiny Drive] diff --git a/modules/ROOT/partials/menu-item-ids/tinymceai-menu-items.adoc b/modules/ROOT/partials/menu-item-ids/tinymceai-menu-items.adoc new file mode 100644 index 0000000000..1165993cd4 --- /dev/null +++ b/modules/ROOT/partials/menu-item-ids/tinymceai-menu-items.adoc @@ -0,0 +1,4 @@ +[cols="1,1,2",options="header"] +|=== +|Menu item identifier |Default Menu Location |Description +|=== diff --git a/modules/ROOT/partials/plugin-apis/tinymceai-apis.adoc b/modules/ROOT/partials/plugin-apis/tinymceai-apis.adoc new file mode 100644 index 0000000000..0d47644b4c --- /dev/null +++ b/modules/ROOT/partials/plugin-apis/tinymceai-apis.adoc @@ -0,0 +1 @@ +== TinyMCE AI APIs diff --git a/modules/ROOT/partials/toolbar-button-ids/tinymceai-toolbar-buttons.adoc b/modules/ROOT/partials/toolbar-button-ids/tinymceai-toolbar-buttons.adoc new file mode 100644 index 0000000000..f98991c1aa --- /dev/null +++ b/modules/ROOT/partials/toolbar-button-ids/tinymceai-toolbar-buttons.adoc @@ -0,0 +1,4 @@ +[cols="1,3",options="header"] +|=== +|Toolbar button identifier |Description +|=== From 8b01d0499b454cf7bdd7d88d33ada61bd50ab35f Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 9 Feb 2026 14:45:30 +1000 Subject: [PATCH 02/10] DOC-3356: Initial documentation structure and layout content. --- modules/ROOT/nav.adoc | 61 ++--- .../ROOT/pages/tinymceai-actions-plugin.adoc | 178 ++++++++++++ modules/ROOT/pages/tinymceai-actions.adoc | 200 ++++++++++++++ .../ROOT/pages/tinymceai-api-overview.adoc | 76 ++++++ .../ROOT/pages/tinymceai-api-quick-start.adoc | 89 ++++++ modules/ROOT/pages/tinymceai-chat.adoc | 110 ++++++++ .../ROOT/pages/tinymceai-conversations.adoc | 149 ++++++++++ .../ROOT/pages/tinymceai-data-handling.adoc | 6 - .../pages/tinymceai-integration-options.adoc | 25 ++ .../ROOT/pages/tinymceai-introduction.adoc | 142 ++++++++++ modules/ROOT/pages/tinymceai-limits.adoc | 47 ++++ modules/ROOT/pages/tinymceai-models.adoc | 210 +++++++++++++++ modules/ROOT/pages/tinymceai-on-premises.adoc | 8 - modules/ROOT/pages/tinymceai-permissions.adoc | 254 ++++++++++++++++++ modules/ROOT/pages/tinymceai-quick-start.adoc | 10 - .../ROOT/pages/tinymceai-review-plugin.adoc | 91 +++++++ modules/ROOT/pages/tinymceai-reviews.adoc | 163 +++++++++++ modules/ROOT/pages/tinymceai-streaming.adoc | 120 +++++++++ .../ROOT/pages/tinymceai-without-tinymce.adoc | 6 - modules/ROOT/pages/tinymceai.adoc | 45 ++-- 20 files changed, 1908 insertions(+), 82 deletions(-) create mode 100644 modules/ROOT/pages/tinymceai-actions-plugin.adoc create mode 100644 modules/ROOT/pages/tinymceai-api-overview.adoc create mode 100644 modules/ROOT/pages/tinymceai-api-quick-start.adoc create mode 100644 modules/ROOT/pages/tinymceai-chat.adoc delete mode 100644 modules/ROOT/pages/tinymceai-data-handling.adoc create mode 100644 modules/ROOT/pages/tinymceai-integration-options.adoc create mode 100644 modules/ROOT/pages/tinymceai-introduction.adoc delete mode 100644 modules/ROOT/pages/tinymceai-on-premises.adoc delete mode 100644 modules/ROOT/pages/tinymceai-quick-start.adoc create mode 100644 modules/ROOT/pages/tinymceai-review-plugin.adoc delete mode 100644 modules/ROOT/pages/tinymceai-without-tinymce.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 7a2111f81f..19585152d4 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -261,41 +261,32 @@ **** xref:ai-gemini.adoc[Google Gemini integration guide] **** xref:ai-proxy.adoc[AI proxy server reference guide] *** TinyMCE AI -**** xref:tinymceai.adoc[Overview] -***** xref:tinymceai.adoc#what-is-tinymce-ai[What is TinyMCE AI] -***** xref:tinymceai.adoc#plugin-vs-api[Plugin vs API] -***** xref:tinymceai.adoc#architecture-overview[Architecture overview] -***** xref:tinymceai.adoc#interactive-example[Interactive example] -**** xref:tinymceai.adoc#plugin-reference[Plugin reference] -***** xref:tinymceai.adoc#basic-setup[Basic setup] -***** xref:tinymceai.adoc#options[Options] -***** xref:tinymceai.adoc#toolbar-buttons[Toolbar buttons] -***** xref:tinymceai.adoc#menu-items[Menu items] -***** xref:tinymceai.adoc#commands[Commands] -***** xref:tinymceai.adoc#events[Events] -***** xref:tinymceai.adoc#apis[APIs] -**** xref:tinymceai-quick-start.adoc[Quick start] -***** xref:tinymceai-quick-start.adoc#plugin-quick-start[Plugin quick start] -***** xref:tinymceai-quick-start.adoc#api-quick-start[API quick start] -**** Features -***** xref:tinymceai-conversations.adoc[Conversations] -***** xref:tinymceai-reviews.adoc[Reviews] -***** xref:tinymceai-actions.adoc[Actions] -**** Configuration -***** xref:tinymceai-models.adoc[AI models] -***** xref:tinymceai-permissions.adoc[Permissions] -***** xref:tinymceai-limits.adoc[Limits] -***** xref:tinymceai-streaming.adoc[Streaming] -**** Integration -***** xref:tinymceai-with-jwt-authentication-nodejs.adoc[JWT authentication (Node.js)] -***** xref:tinymceai-with-jwt-authentication-php.adoc[JWT authentication (PHP)] -***** xref:tinymceai-without-tinymce.adoc[Using the AI service without TinyMCE] -***** xref:tinymceai-rest-api.adoc[REST API reference] -**** Security -***** xref:tinymceai-data-handling.adoc[Data handling] -***** xref:tinymceai-privacy.adoc[Privacy] -**** xref:tinymceai-on-premises.adoc[On-premises] -***** xref:tinymceai-on-premises.adoc#availability-and-roadmap[Availability and roadmap] +**** xref:tinymceai-introduction.adoc[Introduction] +***** Features +****** xref:tinymceai-chat.adoc[Chat] +****** xref:tinymceai-review-plugin.adoc[Review] +****** xref:tinymceai-actions-plugin.adoc[Actions] +***** xref:tinymceai-integration-options.adoc[Integration Options] +****** xref:tinymceai.adoc[Plugin quick start] +****** REST API +******* xref:tinymceai-api-overview.adoc[API Overview] +******* xref:tinymceai-api-quick-start.adoc[API quick start] +******* Features +******** xref:tinymceai-conversations.adoc[Conversations] +******** xref:tinymceai-reviews.adoc[Reviews] +******** xref:tinymceai-actions.adoc[Actions] +******* Configuration +******** xref:tinymceai-models.adoc[AI models] +******** xref:tinymceai-permissions.adoc[Permissions] +******** xref:tinymceai-limits.adoc[Limits] +******** xref:tinymceai-streaming.adoc[Streaming] +******* Integration +******** xref:tinymceai-api-overview.adoc#data-handling-and-security[Data Handling and Security] +******** xref:tinymceai-api-overview.adoc#on-premises-deployment[On-premises deployment] +******** xref:tinymceai-api-overview.adoc#security-features[Security] +****** JWT Authentication +******* xref:tinymceai-with-jwt-authentication-nodejs.adoc[JWT authentication (Node.js)] +******* xref:tinymceai-with-jwt-authentication-php.adoc[JWT authentication (PHP)] *** xref:casechange.adoc[Case Change] *** xref:checklist.adoc[Checklist] *** Comments diff --git a/modules/ROOT/pages/tinymceai-actions-plugin.adoc b/modules/ROOT/pages/tinymceai-actions-plugin.adoc new file mode 100644 index 0000000000..e174544d7e --- /dev/null +++ b/modules/ROOT/pages/tinymceai-actions-plugin.adoc @@ -0,0 +1,178 @@ += TinyMCE AI Quick Actions + +:navtitle: Quick Actions +:description: quick actions feature for TinyMCE AI plugin +:description_short: quick actions feature +:keywords: AI, quick actions, actions, tinymceai + +quick actions streamline routine content transformations by offering one-click AI-powered suggestions directly within the editor. You can also ask questions about your selected text in the Chat to get instant AI insights and analysis. This feature enhances speed, relevance, and usability, particularly for repeatable or simple tasks, while preserving deeper chat-based functionality when needed. + +[[overview]] +== Overview + +Actions are fast, stateless operations that transform content directly. Unlike Reviews that provide suggestions, Actions immediately modify your content based on the selected operation. + +**When to use Actions vs Reviews:** Use Actions when you need to transform specific text content (fix grammar, translate, adjust tone). Use Reviews when you need to analyze entire documents for quality improvements and get suggestions without automatically changing the content. + +[[integration]] +== Integration + +To start using the quick actions feature, first load the TinyMCE AI plugin in your editor configuration. See xref:tinymceai.adoc[Plugin Reference] for installation and enabling AI features. + +Then, you can add the menu that opens the list of quick actions (`tinymceai-actions`) to your main toolbar and/or balloon toolbar configurations. To learn more about toolbar configuration, refer to the xref:toolbar-configuration-options.adoc[toolbar configuration] guide. + +// image::tinymceai/ai-quick-actions-dropdown.png[AI quick actions dropdown in the toolbar] +// TODO: Add image placeholder + +Finally, you can also add individual quick actions to the toolbar as shortcuts for even easier access. For example, you can add the `ask-ai` button, or the `improve-writing` button. You can add whole categories to the toolbar, too. + +The final example configuration looks as follows: + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + + // Adding quick actions to the main editor toolbar + toolbar: [ + // The main quick actions button + 'tinymceai-actions', + + // Two individual actions + 'ask-ai', + 'improve-writing', + + // Whole action category + 'translate', + + // ... other toolbar items + ], + + // Adding quick actions to the balloon toolbar. Since some of the actions are selection-sensitive, + // accessing them might be easier for users using this kind of toolbar + quickbars_selection_toolbar: 'tinymceai-actions | ask-ai | improve-writing | translate', + + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + } +}); +---- + +[[types-of-actions]] +== Types of actions + +There are two types of actions available in the quick actions feature: + +* Some actions, for instance, "Ask AI" or "Summarize", lead to the xref:tinymceai-chat.adoc[Chat] interface with selected text added as context. The former will just open the Chat and allow you to start typing your message. The latter, however, will not only open the Chat but also start the conversation for your current editor selection right away, and expect a summary of that selection from the AI. + +* Executing other actions like "Continue writing" or "Make shorter" will open the window interface conveniently right next to your selection and present the answers from the AI for you to accept or reject them. + +You can define the behavior of each action when you create custom ones. + +[[default-actions]] +== Default Actions + +By default, the quick actions feature includes several built-in actions that speed up the content editing process. All quick actions can be accessed through the menu button (`tinymceai-actions`) but also individually when handpicked by the integrator in the editor toolbar configuration. You can add the whole action categories to the toolbar too. + +Keep in mind that you can add custom actions to the list and remove defaults. + +Here's the full list of available actions: + +* `ask-ai` +* **Chat commands** category (`chat-commands`) + ** `explain` + ** `summarize` + ** `highlight-key-points` +* `improve-writing` +* `continue` +* `fix-grammar` +* **Adjust length** category (`adjust-length`) + ** `make-shorter` + ** `make-longer` +* **Change tone** category (`change-tone`) + ** `make-tone-casual` + ** `make-tone-direct` + ** `make-tone-friendly` + ** `make-tone-confident` + ** `make-tone-professional` +* **Translate** category (`translate`) + ** `translate-to-english` + ** `translate-to-chinese` + ** `translate-to-french` + ** `translate-to-german` + ** `translate-to-italian` + ** `translate-to-portuguese` + ** `translate-to-russian` + +[[custom-actions]] +== Custom Actions + +The `tinymceai_actions_extraCommands` configuration property allows you to add new commands to the AI quick actions feature. Below, you will find an example of three extra actions added to the user interface: two of them open the quick actions window, but the last one interacts with the Chat. Learn more about types of actions. + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + toolbar: 'tinymceai-actions', + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + }, + tinymceai_actions_extraCommands: [ + { + id: 'add-quote-from-famous-person', + displayedPrompt: 'Add a quote from a famous person', + prompt: 'Add a quote from a known person, which would make sense in the context of the selected text.', + type: 'ACTION', + model: 'agent-1' + }, + { + id: 'summarize-in-bullet-points', + displayedPrompt: 'Summarize in 5 bullet points', + prompt: 'Summarize the selected text in 5 bullet points.', + type: 'CHAT' + }, + { + id: 'include-more-sarcasm', + displayedPrompt: 'Rewrite adding more sarcasm', + prompt: 'Rewrite using a sarcastic tone.', + type: 'ACTION', + model: 'agent-1' + } + + // ... More commands ... + ] +}); +---- + +[[removing-default-actions]] +== Removing default actions + +The `tinymceai_actions_removeCommands` configuration property allows you to remove existing commands from the AI quick actions feature. Here's an example that removes two actions ("Explain" and "Summarize"): + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + toolbar: 'tinymceai-actions', + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + }, + tinymceai_actions_removeCommands: [ + 'explain', + 'summarize' + + // ... More commands to remove ... + ] +}); +---- + +[[related-features]] +== Related Features + +* xref:tinymceai-chat.adoc[AI Chat] – For interactive discussions with document analysis and context. +* xref:tinymceai-review-plugin.adoc[AI Review] – For content quality analysis and improvement suggestions. +* xref:tinymceai-actions.adoc[Actions API] – For API-level action functionality. +* xref:tinymceai-introduction.adoc[Introduction] – Overview of all TinyMCE AI features. diff --git a/modules/ROOT/pages/tinymceai-actions.adoc b/modules/ROOT/pages/tinymceai-actions.adoc index 728f2522e8..994a42d2be 100644 --- a/modules/ROOT/pages/tinymceai-actions.adoc +++ b/modules/ROOT/pages/tinymceai-actions.adoc @@ -4,3 +4,203 @@ :description: Quick actions feature for {productname} :description_short: Quick actions feature :keywords: AI, quick actions, actions, tinymceai + +Actions are fast, stateless operations that transform content directly. Unlike Reviews that provide suggestions, Actions immediately modify your content based on the selected operation. + +**When to use Actions vs Reviews:** Use Actions when you need to transform specific text content (fix grammar, translate, adjust tone). Use Reviews when you need to analyze entire documents for quality improvements and get suggestions without automatically changing the content. + +Unlike conversations, actions do not remember previous interactions. Each action is independent and focused on a single task. + +[[available-actions]] +== Available Actions + +[[system-actions]] +=== System Actions + +TinyMCE AI provides built-in system actions for common content transformations: + +* **Fix Grammar** – Correct grammar, spelling, and punctuation errors. +* **Improve Writing** – Enhance clarity, word choice, and sentence structure. +* **Continue Writing** – Complete unfinished sentences, paragraphs, or entire documents. +* **Make Longer** – Expand content with more detail, examples, and explanations. +* **Make Shorter** – Condense lengthy text while keeping the essential information. +* **Adjust Tone** – Change writing style to casual, professional, friendly, or confident. +* **Translate** – Convert content between languages with proper cultural context. + +[[custom-actions]] +=== Custom Actions + +In addition to system actions, you can create custom actions tailored to your specific use cases. Custom actions allow you to define specialized content transformations using your own prompts to control AI behavior. + +Unlike system actions that use predefined identifiers, custom actions use a unified endpoint where you define the transformation behavior through a prompt parameter. + +[[key-features]] +== Key Features + +Each action is independent and does not require conversation context. Actions use streaming output with Server-Sent Events for real-time feedback as results are generated. + +[[api-examples]] +== API Examples + +[[grammar-fix-example]] +=== Grammar Fix Example + +[source,http] +---- +POST /v1/actions/system/fix-grammar/calls +Content-Type: application/json +Authorization: Bearer + +{ + "content": [ + { + "type": "text", + "content": "

The norhtern lights dence across the polar skies, painting ribbons of green and purple light that ripple like a cosmic curtain.

" + } + ] +} +---- + +[[writing-improvement-example]] +=== Writing Improvement Example + +[source,http] +---- +POST /v1/actions/system/improve-writing/calls +Content-Type: application/json +Authorization: Bearer + +{ + "content": [ + { + "type": "text", + "content": "

The system works by processing data through various algorithms to produce results.

" + } + ] +} +---- + +[[content-expansion]] +=== Content Expansion + +[source,http] +---- +POST /v1/actions/system/make-longer/calls +Content-Type: application/json +Authorization: Bearer + +{ + "content": [ + { + "type": "text", + "content": "

Artificial intelligence is transforming the way we work.

" + } + ] +} +---- + +[[content-condensation-example]] +=== Content Condensation Example + +[source,http] +---- +POST /v1/actions/system/make-shorter/calls +Content-Type: application/json +Authorization: Bearer + +{ + "content": [ + { + "type": "text", + "content": "

Artificial intelligence, which is a rapidly evolving field of computer science that focuses on creating intelligent machines capable of performing tasks that typically require human intelligence, is transforming the way we work across various industries and sectors.

" + } + ] +} +---- + +[[tone-adjustment-example]] +=== Tone Adjustment Example + +[source,http] +---- +POST /v1/actions/system/make-tone-casual/calls +Content-Type: application/json +Authorization: Bearer + +{ + "content": [ + { + "type": "text", + "content": "

We regret to inform you that your request cannot be processed at this time.

" + } + ] +} +---- + +[[translation-example]] +=== Translation Example + +[source,http] +---- +POST /v1/actions/system/translate/calls +Content-Type: application/json +Authorization: Bearer + +{ + "content": [ + { + "type": "text", + "content": "

Hello, how are you today?

" + } + ], + "args": { + "language": "Spanish" + } +} +---- + +[[custom-action-example]] +=== Custom Action Example + +[source,http] +---- +POST /v1/actions/custom/calls +Content-Type: application/json +Authorization: Bearer + +{ + "content": [ + { + "type": "text", + "content": "

The company's Q4 revenue was $2.5M, representing a 15% increase YoY.

" + } + ], + "prompt": "Convert financial abbreviations to full words (e.g., 'YoY' to 'year-over-year', 'Q4' to 'fourth quarter') to make the text more accessible to general audiences.", + "model": "agent-1", + "outputFormat": "html" +} +---- + +Custom actions require the `ai:actions:custom` permission in your JWT token. + +[[streaming-responses]] +== Streaming Responses + +Actions use Server-Sent Events (SSE) for real-time streaming results. See the xref:tinymceai-streaming.adoc[Streaming Responses guide] for detailed implementation information. + +[[api-reference]] +== API Reference + +For complete endpoint documentation, request/response schemas, authentication details, and additional parameters, see: + +* **https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API Reference]** – Full documentation for system and custom actions endpoints. +* **https://tinymceai.api.tiny.cloud/docs[Complete API Documentation]** – Interactive API reference with all TinyMCE AI endpoints. + +[[related-features]] +== Related Features + +* xref:tinymceai-actions-plugin.adoc[AI Quick Actions Plugin] – For plugin integration and UI configuration. +* xref:tinymceai-conversations.adoc[Conversations API] – For interactive discussions with document analysis and context. +* xref:tinymceai-reviews.adoc[Reviews API] – For content quality analysis and improvement suggestions. +* xref:tinymceai-streaming.adoc[Streaming Responses] – For implementing real-time review suggestions. +* xref:tinymceai-api-overview.adoc[API Overview] – Overview of all API features. diff --git a/modules/ROOT/pages/tinymceai-api-overview.adoc b/modules/ROOT/pages/tinymceai-api-overview.adoc new file mode 100644 index 0000000000..09cbd2ed50 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-api-overview.adoc @@ -0,0 +1,76 @@ += TinyMCE AI API Overview + +:navtitle: API Overview +:description: Overview of TinyMCE AI REST API features and capabilities +:description_short: API Overview +:keywords: AI, API, REST API, overview, tinymceai + +TinyMCE AI integrates AI-assisted authoring with rich-text editing. Users can interact through Actions, Reviews, or Conversations that can use relevant context from multiple sources. + +[NOTE] +==== +**REST API Reference**: The complete API documentation with all endpoints, parameters, request/response schemas, and interactive examples is available at link:https://tinymceai.api.tiny.cloud/docs[TinyMCE AI API Documentation] +==== + +[[getting-started]] +== Getting Started + +New to TinyMCE AI? Kick your adventure off with the xref:tinymceai-api-quick-start.adoc[Quick Start] guide to set up your environment, generate access credentials, and make your first API call. + +[[tinymce-ai-features]] +== TinyMCE AI features + +* xref:tinymceai-conversations.adoc[**Conversations**] – Interactive AI chats with history and persistent context. +* xref:tinymceai-reviews.adoc[**Reviews**] – Content analysis and proofreading, optimized for larger content. +* xref:tinymceai-actions.adoc[**Actions**] – Fast, stateless operations for specific tasks. + +[[architecture]] +== Architecture + +The following pages cover the system architecture. + +* xref:tinymceai-models.adoc[**Models**] – AI model selection, capabilities, and configuration. +* xref:tinymceai-streaming.adoc[**Streaming**] – Real-time streaming of AI-generated responses. +* xref:tinymceai-permissions.adoc[**Permissions**] – How to control user access to features. +* xref:tinymceai-limits.adoc[**Limits**] – Rate limits, context size limits, and file restrictions. + +[[data-handling-and-security]] +== Data Handling and Security + +[[regional-data-storage]] +=== Regional Data Storage + +All data stored by TinyMCE AI follows the region settings of your TinyMCE Cloud Services environment, ensuring compliance with data residency requirements and optimal performance for your geographic location. + +[TIP] +==== +**Important**: Data sent to LLM providers for processing is currently processed in the US region, regardless of your Cloud Services environment region. +==== + +[[data-retention-policy]] +=== Data Retention Policy + +Conversation data is automatically deleted after 12 months of inactivity, including: + +* all conversation messages and history, +* attached documents, files, and web resources, +* conversation metadata and settings. + +[[security]] +=== Security + +All data is encrypted in transit and at rest with end-to-end encryption. Conversations and attachments are stored in secure cloud infrastructure with fine-grained access control and comprehensive permission systems. Audit Logs are available through our Customer Portal and the API. + +[[on-premises-deployment]] +== On-Premises Deployment + +[TIP] +==== +**Coming Soon**: On-premises deployment is currently in development. Follow TinyMCE social accounts and our newsletter for updates. +==== + +[[resources-and-support]] +== Resources and Support + +* **REST API Documentation**: link:https://tinymceai.api.tiny.cloud/docs[Complete API reference for TinyMCE AI]. +* **Customer Support**: link:https://www.tiny.cloud/contact/[Contact us] to get help from our support team or speak with sales. diff --git a/modules/ROOT/pages/tinymceai-api-quick-start.adoc b/modules/ROOT/pages/tinymceai-api-quick-start.adoc new file mode 100644 index 0000000000..97d6c5f41e --- /dev/null +++ b/modules/ROOT/pages/tinymceai-api-quick-start.adoc @@ -0,0 +1,89 @@ += TinyMCE AI API Quick Start + +:navtitle: API Quick Start +:description: Quick start guide for TinyMCE AI REST API +:description_short: API quick start guide +:keywords: AI, quick start, API, REST API, tinymceai, setup + +The aim of this article is to get you up and running with the TinyMCE AI REST API. + +[TIP] +==== +You can also sign up for the link:https://www.tiny.cloud/auth/signup/[TinyMCE Premium Features 14-day free trial] if you want to test this feature first. + +The TinyMCE Premium Features free trial allows for testing SaaS services. If you are interested in on-premises solutions, please link:https://www.tiny.cloud/contact/[contact us]. +==== + +== Getting Started + +To start using the TinyMCE AI REST API, follow the steps below: + +* Sign up for one of our link:https://www.tiny.cloud/pricing/[self-service plans], or link:https://www.tiny.cloud/contact/[contact us] to purchase the TinyMCE AI license. +* Generate your access credentials in the link:https://www.tiny.cloud/my-account/[Customer Portal]. +* Write a script that generates one-time tokens for authorizing end users of your application in TinyMCE Cloud Services (using access credentials created earlier). + +All steps are explained in details below. + +[[get-the-tinymce-ai-license]] +== Get the TinyMCE AI license + +You can purchase TinyMCE AI as an add-on to selected tiers of our self-service plans. You can find details on our link:https://www.tiny.cloud/pricing/[pricing page]. + +You can also link:https://www.tiny.cloud/contact/[contact us] directly if you would like to have a custom plan. + +For testing purposes, you can sign up for the link:https://www.tiny.cloud/auth/signup/[free trial]. + +After signing up, you will receive access to the link:https://www.tiny.cloud/my-account/[customer dashboard (Customer Portal)]. + +[[log-in-to-the-customer-portal]] +== Log in to the Customer Portal + +Log in to the link:https://www.tiny.cloud/my-account/[Customer Portal] and navigate to link:https://www.tiny.cloud/my-account/jwt/["JWT Keys"]. + +// image::tinymceai/ai-trial-view.png[TinyMCE AI trial view] +// TODO: Add image placeholder + +[[create-token-endpoint]] +== Create token endpoint + +You now need to create a security token endpoint in your application. This endpoint securely authorizes end users of your application to use TinyMCE AI features based on their permissions and access rights. + +[[writing-your-own-token-endpoint]] +=== Writing your own token endpoint + +To write your own security token endpoint, create access credentials for the selected environment by going to the "Access credentials" tab and clicking the "Create a new access key" button. + +Read more in the Creating access credentials section of the Environments management guide. + +[[cloud-region]] +== Cloud region + +Cloud Services can reside in either US or EU region or in both. The region is set per subscription and cannot be changed for existing environments by the user. For Custom plan with multi-region, you can choose the region during environment creation. This topic is addressed in more detail in the Environment management guide. + +[[api-integration]] +== API Integration + +All features are accessible through the REST API at `https://tinymceai.api.tiny.cloud` with JWT authentication. + +For an overview of all API features, see xref:tinymceai-api-overview.adoc[API Overview]. + +For detailed API examples and implementation guides, see: + +* xref:tinymceai-conversations.adoc[Conversations] – Interactive AI discussions and document analysis. +* xref:tinymceai-reviews.adoc[Reviews] – Content improvement and quality analysis. +* xref:tinymceai-actions.adoc[Actions] – Content transformation and batch processing. +* xref:tinymceai-streaming.adoc[Streaming] – Real-time AI interactions. + +link:https://tinymceai.api.tiny.cloud/docs[Complete API Documentation] – Full API reference for TinyMCE AI + +[[next-steps]] +== Next Steps + +Now that you made your first API call, explore the features: + +* xref:tinymceai-api-overview.adoc[API Overview] – Overview of all API features, data handling, and security. +* xref:tinymceai-conversations.adoc[Conversations] – Start with interactive AI discussions. +* xref:tinymceai-models.adoc[AI Models] – Choose the right model for your use case. +* xref:tinymceai-permissions.adoc[Permissions] – Set up user access control for production. +* xref:tinymceai-reviews.adoc[Reviews] – Add content improvement features. +* xref:tinymceai-actions.adoc[Actions] – Implement content transformation. diff --git a/modules/ROOT/pages/tinymceai-chat.adoc b/modules/ROOT/pages/tinymceai-chat.adoc new file mode 100644 index 0000000000..cfa352e859 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-chat.adoc @@ -0,0 +1,110 @@ += TinyMCE AI Chat + +:navtitle: Chat +:description: AI Chat feature for TinyMCE AI plugin +:description_short: AI Chat feature +:keywords: AI, chat, conversations, tinymceai + +The TinyMCE AI Chat is a conversational AI that can be used to aid content creation and editing. It introduces a dynamic chat interface designed to facilitate rich, multi-turn interactions between users and an AI Assistant. This capability moves beyond single-prompt content generation, enabling a more interactive and collaborative experience within writing workflows. + +[[overview]] +== Overview + +The Chat feature provides context setting and model selection to better suit the needs of specific content and holds chat history for quick reference of previous work. The Chat is also capable of using the web for more up-to-date information and reasoning to think more deeply about the answers and changes it is allowed to make. + +[[integration]] +== Integration + +To start using the Chat feature, first load the TinyMCE AI plugin in your editor configuration. See xref:tinymceai.adoc[Plugin Reference] for installation and enabling AI features. + +The Chat interface can be accessed through the main AI button in the toolbar or by using the `tinymceai-conversations` toolbar button. + +[[context-configuration]] +== Context Configuration + +The `tinymceai_conversations_context` configuration property configures the AI Chat menu for adding resources to the prompt context. + +The example below enables built-in options to add the current document, URLs, and files to the conversation context by the user. + +It also demonstrates a context sources configuration that introduces a menu with external resources fetched from a database or an external API for the user to pick from. + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + toolbar: 'tinymceai', + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + }, + tinymceai_conversations_context: { + document: true, + url: true, + file: true, + sources: [ + { + id: 'knowledge-base', + label: 'Knowledge Base', + fetch: async () => { + const response = await fetch('/api/knowledge-base'); + return response.json(); + } + } + ] + } +}); +---- + +[[working-with-ai-generated-changes]] +== Working with AI-generated changes + +When the AI suggests changes to your content, you can: + +* **Accept** - Accept the suggested changes that are rendered directly in the document +* **Reject** - Discard the suggestion +* **Edit** - Modify the suggestion before applying +* **Suggested Edits** - Convert suggestions to Suggested Edits for review + +// image::tinymceai/ai-chat-suggestions.png[AI Chat suggestions interface] +// TODO: Add image placeholder + +[[chat-history]] +== Chat history + +All your past conversations appear in the Chat history. Click the button to open the list, where you can reopen, rename, or delete any conversation. + +Conversations are grouped by date to help you navigate your project easily. You can filter conversations by name using the search field at the top of the user interface. + +// image::tinymceai/ai-chat-history.png[AI Chat history] +// TODO: Add image placeholder + +[NOTE] +==== +You can continue any conversation from the chat history as long as the AI model used for that conversation is still supported by the feature. Click the conversation in the history to load it in the Chat interface. +==== + +[NOTE] +==== +The ability to apply suggestions to the document or generate Suggested Edits from historical conversations may be restricted in some scenarios: + +After closing the browser and reopening the AI Chat, previous conversations will no longer interact with the document content. To continue working with a conversation, you can reopen it from the chat history. +==== + +[[advanced-features]] +== Advanced Features + +The Chat feature supports advanced capabilities: + +* **Web Search** - Access up-to-date information from the web +* **Reasoning** - Deep thinking about answers and changes +* **Multi-turn conversations** - Maintain context across multiple interactions +* **Model selection** - Choose the appropriate AI model for your task + +For more information about API-level features, see xref:tinymceai-conversations.adoc[Conversations API documentation]. + +[[related-features]] +== Related Features + +* xref:tinymceai-review-plugin.adoc[AI Review] – For content quality analysis and improvement suggestions. +* xref:tinymceai-actions-plugin.adoc[AI Quick Actions] – For fast, stateless content transformations. +* xref:tinymceai-introduction.adoc[Introduction] – Overview of all TinyMCE AI features. diff --git a/modules/ROOT/pages/tinymceai-conversations.adoc b/modules/ROOT/pages/tinymceai-conversations.adoc index fb661c8a5b..301fe0acdb 100644 --- a/modules/ROOT/pages/tinymceai-conversations.adoc +++ b/modules/ROOT/pages/tinymceai-conversations.adoc @@ -4,3 +4,152 @@ :description: AI chat feature for {productname} :description_short: AI chat feature :keywords: AI, chat, conversations, tinymceai + +Conversations allow you to exchange multiple messages with AI that maintains them in its context. Conversations can be extended by external context sources like websites or files, and have the ability to refer to editor content and suggest modifications. + +[[key-features]] +== Key Features + +Upload PDFs, Word docs, and images for the AI to read and understand. Ask questions about specific sections and get intelligent answers. The AI extracts text while preserving structure from PDFs, maintains formatting context from Word documents, parses web content from HTML files, and processes images with OCR and object recognition. + +Each conversation builds on previous messages, so the AI keeps track of your entire discussion and any files you have shared. You can mix documents, images, web links, and text in one conversation, and the AI connects information across all formats. Enable web search for real-time research while keeping your conversation context. + +[[example-product-launch-workflow]] +=== Example: Product Launch Workflow + +. **Upload product spec** → _"What are the key features for marketing?"_ +. **Add competitor analysis** → _"How do we compare to competitors?"_ +. **Reference blog post** → _"Write a press release using this blog post and our competitive advantages"_ +. **Include brand guidelines** → _"Match our brand voice and key messaging"_ + +The AI remembers everything you have shared and builds on it throughout your conversation. + +[[advanced-features]] +== Advanced Features + +[[web-search]] +=== Web Search + +Enable real-time web search to access current information during conversations. The AI searches the web for relevant content, processes and analyzes the results, and integrates findings into responses while maintaining conversation context. Configure via the `webSearch` capability in API requests. + +[[reasoning]] +=== Reasoning + +Enable step-by-step reasoning to see the AI's problem-solving process. The AI breaks down complex queries into logical steps, considers multiple approaches, and can revise conclusions when new information emerges. Configure via the `reasoning` capability in API requests. + +[[api-reference]] +== API Reference + +For complete API documentation including endpoints, parameters, and response schemas, see the https://tinymceai.api.tiny.cloud/docs#tag/Conversations[REST API documentation]. + +[[api-examples]] +== API Examples + +[[create-a-conversation]] +=== Create a Conversation + +[source,http] +---- +POST /v1/conversations +Content-Type: application/json +Authorization: Bearer + +{ + "id": "my-conversation-123", + "title": "Document Analysis Session", + "group": "research" +} +---- + +[[upload-a-document]] +=== Upload a Document + +Before you can reference documents in conversations, you need to upload them first: + +[source,http] +---- +POST /v1/conversations/my-conversation-123/documents +Content-Type: multipart/form-data +Authorization: Bearer + +file: [your-document.pdf] +---- + +Response: + +[source,json] +---- +{ + "id": "doc-123" +} +---- + +You can see how to upload other resources, including web resources and files using https://tinymceai.api.tiny.cloud/docs#tag/Conversations[REST API documentation]. + +[[send-a-message-with-context]] +=== Send a Message with Context + +[source,http] +---- +POST /v1/conversations/my-conversation-123/messages +Content-Type: application/json +Authorization: Bearer + +{ + "prompt": "Analyze the attached document and provide a summary of the key points", + "model": "agent-1", + "content": [ + { + "type": "document", + "id": "doc-123" + } + ], + "capabilities": { + "webSearch": {}, + "reasoning": {} + } +} +---- + +[[send-a-message-with-multiple-context-types]] +=== Send a Message with Multiple Context Types + +[source,http] +---- +POST /v1/conversations/my-conversation-123/messages +Content-Type: application/json +Authorization: Bearer + +{ + "prompt": "Compare the attached document with the information from the web resource", + "model": "agent-1", + "content": [ + { + "type": "document", + "id": "doc-123" + }, + { + "type": "web-resource", + "id": "web-123" + } + ], + "capabilities": { + "webSearch": {} + } +} +---- + +[[streaming-responses]] +== Streaming Responses + +Conversations use Server-Sent Events (SSE) for real-time streaming responses. See the xref:tinymceai-streaming.adoc[Streaming Responses guide] for detailed implementation information and code examples. + +[[related-features]] +== Related Features + +* xref:tinymceai-chat.adoc[AI Chat Plugin] – For plugin integration and UI configuration. +* xref:tinymceai-reviews.adoc[Reviews API] – Content quality analysis and improvement suggestions. +* xref:tinymceai-actions.adoc[Actions API] – Content transformation and batch processing. +* xref:tinymceai-models.adoc[AI Models] – Choosing the right AI model for your conversations. +* xref:tinymceai-streaming.adoc[Streaming Responses] – Implementing real-time conversation features. +* xref:tinymceai-api-overview.adoc[API Overview] – Overview of all API features. diff --git a/modules/ROOT/pages/tinymceai-data-handling.adoc b/modules/ROOT/pages/tinymceai-data-handling.adoc deleted file mode 100644 index 81635d1d66..0000000000 --- a/modules/ROOT/pages/tinymceai-data-handling.adoc +++ /dev/null @@ -1,6 +0,0 @@ -= TinyMCE AI Data Handling - -:navtitle: Data Handling -:description: Data handling and security for TinyMCE AI -:description_short: Data handling and security -:keywords: AI, data handling, security, tinymceai diff --git a/modules/ROOT/pages/tinymceai-integration-options.adoc b/modules/ROOT/pages/tinymceai-integration-options.adoc new file mode 100644 index 0000000000..eb56402cc0 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-integration-options.adoc @@ -0,0 +1,25 @@ += TinyMCE AI Integration Options + +:navtitle: Integration Options +:description: Choose how to integrate TinyMCE AI with your application +:description_short: Integration options for TinyMCE AI +:keywords: AI, integration, plugin, API, REST API, tinymceai + +TinyMCE AI can be integrated with your application through two methods: + +[cols=2*a] +|=== + +| +[.lead] +xref:tinymceai.adoc[**Plugin Quick Start**] + +Integrate AI features directly into the TinyMCE editor interface. Works with CDN or self-hosted TinyMCE installations. The fastest way to add AI capabilities to your editor. + +| +[.lead] +xref:tinymceai-api-overview.adoc[**REST API**] + +Use the REST API to build custom integrations and workflows. Perfect for server-side processing, custom UI implementations, and advanced use cases. Start with the xref:tinymceai-api-quick-start.adoc[API Quick Start] guide. + +|=== diff --git a/modules/ROOT/pages/tinymceai-introduction.adoc b/modules/ROOT/pages/tinymceai-introduction.adoc new file mode 100644 index 0000000000..a252bd9a69 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-introduction.adoc @@ -0,0 +1,142 @@ += TinyMCE AI Introduction + +:navtitle: Introduction +:description: Introduction to TinyMCE AI features and capabilities +:description_short: TinyMCE AI introduction +:keywords: AI, introduction, tinymceai + +By integrating AI writing assistance directly into the editing experience, TinyMCE AI empowers authors with real-time AI writing support, streamlines content creation, and enhances editorial workflows across a wide range of use cases – from productivity boosts and proof-reading to content quality and consistency. + +[[what-is-tinymce-ai]] +== What is TinyMCE AI + +TinyMCE AI is an AI-powered writing assistant that integrates directly into our rich-text editor, {productname}, providing instant text rewriting, summarization, correction, and contextual chat help based on internal style guides. The platform includes automated review tools and enterprise-ready functionality that plugs into existing systems without requiring custom infrastructure. + +Teams can implement a full suite of AI writing tools in weeks rather than months, delivering streamlined, compliant content workflows that maintain brand consistency and integrate seamlessly with existing document management systems. + +The core components of TinyMCE AI are: + +* **{productname}**: A modern rich text editor with dozens of features that improve writing workflows, including collaboration. +* **AI service**: A state-of-the-art backend AI engine that incorporates multiple models and delivers high-quality content. Currently available only in Cloud setup, with on-premises deployment coming soon. The AI service also provides a REST API. + +[[features]] +== TinyMCE AI features + +There are three main features of TinyMCE AI. You can test them all using the free trial. + +* xref:tinymceai-chat.adoc[**Chat**] – Interactive AI chats with history and persistent context. +* xref:tinymceai-review-plugin.adoc[**Review**] – Content analysis and proofreading, optimized for larger content. +* xref:tinymceai-actions-plugin.adoc[**Actions**] – Fast, stateless operations for specific tasks. + +[[integration-options]] +== Integration Options + +TinyMCE AI can be integrated with your application through two methods. See xref:tinymceai-integration-options.adoc[Integration Options] for details. + +[[permissions]] +== Permissions + +Developers can control access to AI features, models, and capabilities based on user roles, subscription tiers, and organizational requirements. Learn more about the xref:tinymceai-permissions.adoc[permissions system]. + +[[privacy-and-data-handling]] +== Privacy and data handling + +You can find detailed information on how TinyMCE AI manages your data in the xref:tinymceai-api-overview.adoc#data-handling-and-security[API Overview] documentation. + +[[known-issues]] +== Known issues and caveats + +The TinyMCE AI plugin has the following known issues and caveats: + +=== General HTML Support + +TinyMCE AI may not work correctly when General HTML Support for block elements is enabled. This issue will be addressed in future updates. In the meantime, we recommend avoiding configurations that may cause problems. + +=== Issues with tables + +We are aware of certain glitches that may occur when the AI modifies complex tables or layout tables. To prevent data loss, please ensure that the content around these structures remains intact when using TinyMCE AI tools, while our team investigates the causes and potential solutions to this issue. + +=== Editor context and multiple editor handling + +While it's possible to use TinyMCE AI with multiple editors in an editor context, only the first editor registered in the context will currently be able to interact with AI tools and benefit from the content suggestions made by the AI. As our team works on resolving this issue, we recommend using standalone editor instances with TinyMCE AI. + +=== Inline image processing issues + +Inline images may not be processed correctly by commands within the AI Review feature. A solution is currently under development. + +=== Quick actions and content markers issues + +Applying quick action responses may result in the loss of Comments and Suggested Edits suggestion markers. This issue will be addressed in a future update. + +=== Limited interactivity in Chat history + +The interactivity of historical AI Chat conversations can become limited over time. + +=== Issues with specific AI models + +Some AI models may occasionally return empty responses. If this occurs, we recommend sending a follow-up message asking the Assistant to complete the previous request, or starting a new conversation. + +NOTE: If you wish to stay informed about updates or discuss TinyMCE AI possibilities, please reach out to us. + +[[common-api]] +== Common API + +The AI features register the following UI components and editor commands. + +[[ui-components]] +=== UI components + +The AI features register the following UI components: + +[cols="1,1"] +|=== +|Component name |Registered by + +|`tinymceai` |Main AI plugin button +|`tinymceai-conversations` |Conversations feature +|`tinymceai-actions` |Quick Actions feature +|`tinymceai-reviews` |Reviews feature +|`ask-ai` |Quick Actions +|`explain` |Quick Actions +|`summarize` |Quick Actions +|`highlight-key-points` |Quick Actions +|`improve-writing` |Quick Actions +|`continue` |Quick Actions +|`fix-grammar` |Quick Actions +|`make-shorter` |Quick Actions +|`make-longer` |Quick Actions +|`make-tone-casual` |Quick Actions +|`make-tone-direct` |Quick Actions +|`make-tone-friendly` |Quick Actions +|`make-tone-confident` |Quick Actions +|`make-tone-professional` |Quick Actions +|`translate-to-english` |Quick Actions +|`translate-to-chinese` |Quick Actions +|`translate-to-french` |Quick Actions +|`translate-to-german` |Quick Actions +|`translate-to-italian` |Quick Actions +|`translate-to-portuguese` |Quick Actions +|`translate-to-russian` |Quick Actions +|=== + +[[editor-commands]] +=== Editor commands + +The TinyMCE AI plugin provides the following {productname} commands: + +[cols="1,1"] +|=== +|Command name |Description + +|`mceTinymceAI` |Toggle AI interface visibility +|`mceTinymceAIConversations` |Open Conversations interface +|`mceTinymceAIActions` |Open Quick Actions interface +|`mceTinymceAIReviews` |Open Reviews interface +|=== + +NOTE: We recommend using the official {productname} inspector for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more. + +[[future-ideas]] +== Future ideas - share your feedback + +Have an idea for future improvements? We'd love to hear from you! Share your thoughts and suggestions with us through our link:https://www.tiny.cloud/contact/[contact form]. diff --git a/modules/ROOT/pages/tinymceai-limits.adoc b/modules/ROOT/pages/tinymceai-limits.adoc index 5c77cdec39..5a2c5c464c 100644 --- a/modules/ROOT/pages/tinymceai-limits.adoc +++ b/modules/ROOT/pages/tinymceai-limits.adoc @@ -4,3 +4,50 @@ :description: Usage limits configuration for TinyMCE AI :description_short: Usage limits configuration :keywords: AI, limits, configuration, tinymceai + +Understand the limits that ensure fair usage, optimal performance, and cost control across all TinyMCE AI features. + +[[overview]] +== Overview + +TinyMCE AI implements various limits to ensure fair usage, optimal performance, and cost control. These include rate limits for API requests, context limits for content size and processing, model-specific constraints, and file restrictions. + +[[rate-limits]] +== Rate Limits + +Rate limits control the frequency of API requests to prevent abuse and ensure service stability. The service implements limits on API requests, token usage, web search, and web scraping requests per minute. All rate limits are applied at both organization level (higher limits) and individual user level (lower limits) to ensure fair usage. + +NOTE: Specific rate limit values are subject to change and may vary based on your subscription tier. Contact support for current rate limit details for your environment. + +[[context-limits]] +== Context Limits + +Context limits control how much content can be attached to conversations to ensure AI models can process all information effectively. These limits vary by model based on their specific capabilities and processing requirements. + +[[file-limits]] +=== File Limits + +Files are limited to 7MB each (PDF, DOCX, PNG, JPEG, Markdown, HTML, Plain text). You can upload up to 100 files per conversation with a total size limit of 30MB. PDF files are limited to 100 pages total across all PDFs in a conversation. + +[[model-specific-file-limits]] +==== Model-specific file limits + +Anthropic and agent models may use files up to 5MB each. + +[[context-optimization-tips]] +=== Context Optimization Tips + +Compress images and split large documents into smaller sections. Use text formats (TXT or MD) over PDF when possible for better processing. Attach only relevant files to conversations and provide document summaries for very large files. + +[[model-specific-limits]] +== Model-Specific Limits + +Different AI models have varying capabilities and limitations that affect context processing. Each model has different context window sizes that determine how much content can be processed. Models have response timeouts, file processing timeouts, web resource timeouts, and streaming response limits. All models include content moderation for inappropriate content, safety checks, and moderation response time limits. + +[[next-steps]] +== Next Steps + +* xref:tinymceai-models.adoc[Learn about AI Models] for model-specific limitations. +* xref:tinymceai-permissions.adoc[Set up Permisssions] to control user access. +* xref:tinymceai-conversations.adoc[Explore Conversations] for context management. +* https://tinymceai.api.tiny.cloud/docs[API Documentation] – Complete API reference for TinyMCE AI. diff --git a/modules/ROOT/pages/tinymceai-models.adoc b/modules/ROOT/pages/tinymceai-models.adoc index ea7b29fad0..8ecfacd6c0 100644 --- a/modules/ROOT/pages/tinymceai-models.adoc +++ b/modules/ROOT/pages/tinymceai-models.adoc @@ -4,3 +4,213 @@ :description: AI model configuration for TinyMCE AI :description_short: AI model configuration :keywords: AI, models, configuration, tinymceai + +[[recommended-agent-models]] +== Recommended: Agent Models + +The `agent-1` model automatically selects the best AI model for your request based on speed, quality, and cost. It's the recommended choice for most use cases as it optimizes performance and cost automatically. + +[[available-models]] +== Available Models + +TinyMCE AI supports multiple AI models from different providers. Each model has unique capabilities, performance characteristics, and cost profiles. + +[[limitations]] +=== Limitations + +Model availability depends on your subscription tier and service compatibility version. Some models may have specific limitations or requirements. + +[[how-model-selection-works]] +== How Model Selection Works + +The agent model (`agent-1`) automatically selects the best underlying model based on: + +* **Request complexity** – Simple queries use faster, cost-effective models +* **Content size** – Larger content uses models with better context windows +* **Required capabilities** – Web search and reasoning require compatible models +* **Cost optimization** – Balances quality with cost efficiency + +You can also specify a model directly in your API requests for more control. + +[[model-compatibility-versions]] +== Model Compatibility Versions + +Models are organized by compatibility versions to ensure API stability. When new models are introduced or existing models are updated, they may be added to a new compatibility version. + +[[how-it-works]] +=== How It Works + +Compatibility versions allow TinyMCE AI to introduce new models and capabilities without breaking existing integrations. Each version maintains a stable set of models and capabilities. + +[[checking-compatibility]] +=== Checking Compatibility + +Check the `/v1/models` endpoint to see available models for your compatibility version. The API response includes model capabilities, limits, and availability. + +[[model-capabilities]] +== Model Capabilities + +Different models support different capabilities. Check the model information endpoint to see which capabilities are available for each model. + +[[web-search]] +=== Web Search + +Enable real-time web search to access current information during conversations. Not all models support web search. Check model capabilities to see which models support this feature. + +[[reasoning]] +=== Reasoning + +Enable step-by-step reasoning to see the AI's problem-solving process. Some models have reasoning always enabled and cannot be turned off. + +**Always-on reasoning models:** + +* Reasoning is always active during inference. +* You cannot turn reasoning off via the API. + +To determine if a model has always-on reasoning, check the API response when listing models. Models with mandatory reasoning will indicate this in their capability structure. + +NOTE: Please observe, that model names such as `gpt-5`, `claude-4-sonnet`, etc. are examples. Actual available models depend on your service's compatibility version. Use the `/v1/models` endpoint to see current available models for your environment. + +[[web-scraping]] +=== Web Scraping + +Extract and process content from web pages for analysis and summarization. + +[[model-limitations]] +== Model Limitations + +[[file-processing-limits]] +=== File Processing Limits + +Files are limited to 7MB each (PDF, DOCX, PNG, JPEG, Markdown, HTML, Plain text). You can upload up to 100 files per conversation with a total size limit of 30MB. PDF files are limited to 100 pages total across all PDFs in a conversation. + +[[model-specific-file-limits]] +==== Model-specific file limits + +Anthropic and agent models may use files up to 5MB each. + +[[content-moderation]] +=== Content Moderation + +All models include moderation for inappropriate content, harmful instructions, personal information, copyrighted material, misinformation, sensitive topics, and security threats. + +[[model-descriptions]] +=== Model Descriptions + +Model descriptions returned by the API are provided in English and may be updated over time to reflect model improvements or capability changes. + +[[translation-and-localization]] +=== Translation and Localization + +NOTE: Backend translation handling for model descriptions is planned in a future release. Until then, use the approach described below. + +If your application requires translated model descriptions, maintain a translation map in your code keyed by `model.id`, with fallback to the English description from the API for unknown models. This allows new models to work immediately while you add translations at your own pace. + +[[model-deprecation]] +=== Model Deprecation + +Models scheduled for removal will include a `removal` field with an ISO 8601 date (e.g., `"removal": "2025-11-17T00:00:00.000Z"`). When a model is removed, API requests will fail with error code `MODEL_NOT_FOUND` and the models endpoint will stop returning that particular model. + +[[api-examples]] +== API Examples + +[[model-selection]] +=== Model Selection + +[source,http] +---- +POST /v1/conversations/my-conversation-123/messages +Content-Type: application/json +Authorization: Bearer + +{ + "prompt": "Analyze this document and provide insights", + "model": "agent-1", + "content": [ + { + "type": "document", + "id": "doc-1234567890123" + } + ] +} +---- + +[[capability-configuration]] +=== Capability Configuration + +[source,http] +---- +POST /v1/conversations/my-conversation-123/messages +Content-Type: application/json +Authorization: Bearer + +{ + "prompt": "Research the latest developments in AI", + "model": "gpt-4o", + "capabilities": { + "webSearch": {}, + "reasoning": {} + } +} +---- + +[[model-information]] +=== Model Information + +Get all available models for compatibility version `1`: + +[source,http] +---- +GET /v1/models/1 +Authorization: Bearer +---- + +Response: + +[source,json] +---- +{ + "items": [ + { + "id": "agent-1", + "name": "Agent", + "provider": "Agent", + "description": "Automatically selects the best model for speed, quality, and cost", + "allowed": true, + "capabilities": { + "webSearch": { + "enabled": true, + "allowed": true + }, + "reasoning": { + "enabled": true, + "allowed": true + } + }, + "limits": { + "maxPromptLength": 30000, + "maxConversationLength": 256000, + "maxFiles": 100, + "maxFileSize": 7000000, + "maxTotalFileSize": 30000000, + "maxTotalPdfFilePages": 100 + } + } + ] +} +---- + +[[api-reference]] +== API Reference + +For complete documentation on model endpoints, compatibility versions, and capability schemas, see: + +* **https://tinymceai.api.tiny.cloud/docs#tag/Models[Models API Reference]** – Full documentation for model listing and configuration. +* **https://tinymceai.api.tiny.cloud/docs[Complete API Documentation]** – Interactive API reference with all TinyMCE AI endpoints. + +[[related-features]] +== Related Features + +* xref:tinymceai-conversations.adoc[Conversations] – Use models in interactive AI discussions. +* xref:tinymceai-reviews.adoc[Reviews] – Apply models to content analysis and improvement. +* xref:tinymceai-actions.adoc[Actions] – Use models for content transformation tasks. diff --git a/modules/ROOT/pages/tinymceai-on-premises.adoc b/modules/ROOT/pages/tinymceai-on-premises.adoc deleted file mode 100644 index 2f93915a19..0000000000 --- a/modules/ROOT/pages/tinymceai-on-premises.adoc +++ /dev/null @@ -1,8 +0,0 @@ -= TinyMCE AI On-Premises - -:navtitle: On-Premises -:description: On-premises availability and roadmap for TinyMCE AI -:description_short: On-premises availability -:keywords: AI, on-premises, availability, roadmap, tinymceai - -== Availability and roadmap diff --git a/modules/ROOT/pages/tinymceai-permissions.adoc b/modules/ROOT/pages/tinymceai-permissions.adoc index 494ba1263b..95db0faaaa 100644 --- a/modules/ROOT/pages/tinymceai-permissions.adoc +++ b/modules/ROOT/pages/tinymceai-permissions.adoc @@ -4,3 +4,257 @@ :description: Permission configuration for TinyMCE AI :description_short: Permission configuration :keywords: AI, permissions, configuration, tinymceai + +[[overview]] +== Overview + +TinyMCE AI uses a permission-based access control system to manage user access to AI features. Permissions are specified in JWT tokens and control which features, models, and capabilities users can access. + +[[use-cases]] +== Use Cases + +* **Role-based access** – Different user roles have different AI capabilities +* **Cost control** – Limit access to expensive models or features +* **Feature gating** – Enable specific AI features for premium users +* **Security** – Restrict access to sensitive AI operations + +[[permission-format]] +== Permission Format + +Permissions follow a hierarchical format: `ai:::` + +[[admin-permissions]] +=== Admin Permissions + +[[aiadmin]] +==== `ai:admin` + +Grants full access to all TinyMCE AI features, models, and capabilities. Use with caution in production environments. + +[[model-permissions]] +=== Model Permissions + +[[aimodels]] +==== `ai:models:*` + +Access to all available AI models. Use with caution as this includes access to new models that may be more expensive. + +[[aimodelsprovider]] +==== `ai:models::*` + +Access to all models from a specific provider (e.g., `ai:models:openai:*`, `ai:models:anthropic:*`). + +[[aimodelsprovidermodel-name]] +==== `ai:models::` + +Access to a specific model (e.g., `ai:models:openai:gpt-4o`, `ai:models:anthropic:claude-3-sonnet`). + +[[aimodelsagent-recommended]] +==== `ai:models:agent` ⭐ Recommended + +Access to the agent model which automatically selects the best model for each request. This is the recommended permission for most use cases. + +[[conversation-permissions]] +=== Conversation Permissions + +[[aiconversations]] +==== `ai:conversations:*` + +Full access to all conversation features including read, write, web search, and reasoning. + +[[aiconversationsread]] +==== `ai:conversations:read` + +Ability to read and list conversations. + +[[aiconversationswrite]] +==== `ai:conversations:write` + +Ability to create and send messages in conversations. + +[[aiconversationswebsearch]] +==== `ai:conversations:websearch` + +Ability to use web search capability in conversations. + +[[aiconversationsreasoning]] +==== `ai:conversations:reasoning` + +Ability to use reasoning capability in conversations. + +[[context-permissions]] +=== Context Permissions + +[[aiconversationscontext]] +==== `ai:conversations:context:*` + +Access to all context types (files and URLs). + +[[aiconversationscontextfiles]] +==== `ai:conversations:context:files:*` + +Access to all file types for context. + +[[aiconversationscontextfilesformat]] +==== `ai:conversations:context:files:` + +Access to specific file formats (e.g., `ai:conversations:context:files:pdf`, `ai:conversations:context:files:docx`). + +[[aiconversationscontexturls]] +==== `ai:conversations:context:urls` + +Ability to use web URLs as context sources. + +[[actions-permissions]] +=== Actions Permissions + +[[aiactions]] +==== `ai:actions:*` + +Access to all action types, including custom and system actions. + +[[aiactionscustom]] +==== `ai:actions:custom` + +Ability to run custom actions with free-form prompts. + +[[aiactionssystem]] +==== `ai:actions:system:*` + +Access to all pre-defined system actions. + +[[aiactionssystemaction-name]] +==== `ai:actions:system:` + +Access to specific system actions. Examples: + +* `ai:actions:system:improve-writing` +* `ai:actions:system:fix-grammar` +* `ai:actions:system:translate` + +[[reviews-permissions]] +=== Reviews Permissions + +[[aireviews]] +==== `ai:reviews:*` + +Access to all review types, including custom and system reviews. + +[[aireviewscustom]] +==== `ai:reviews:custom` + +Ability to run custom reviews with free-form prompts. + +[[aireviewssystem]] +==== `ai:reviews:system:*` + +Access to all pre-defined system reviews. + +[[aireviewssystemreview-name]] +==== `ai:reviews:system:` + +Access to specific system reviews. Examples: + +* `ai:reviews:system:correctness` +* `ai:reviews:system:clarity` +* `ai:reviews:system:make-tone-professional` + +[[permission-examples]] +== Permission Examples + +[[basic-user]] +=== Basic User + +[source,json] +---- +{ + "auth": { + "ai": { + "permissions": [ + "ai:conversations:read", + "ai:conversations:write", + "ai:models:agent", + "ai:conversations:context:files:pdf", + "ai:conversations:context:files:docx" + ] + } + } +} +---- + +[[premium-user]] +=== Premium User + +[source,json] +---- +{ + "auth": { + "ai": { + "permissions": [ + "ai:conversations:*", + "ai:models:*", + "ai:actions:system:*", + "ai:reviews:system:*" + ] + } + } +} +---- + +[[enterprise-admin]] +=== Enterprise Admin + +[source,json] +---- +{ + "auth": { + "ai": { + "permissions": [ + "ai:admin" + ] + } + } +} +---- + +[[restricted-user-review-only]] +=== Restricted User (Review Only) + +[source,json] +---- +{ + "auth": { + "ai": { + "permissions": [ + "ai:reviews:system:correctness", + "ai:reviews:system:clarity", + "ai:models:gpt-4.1-mini" + ] + } + } +} +---- + +[[best-practices]] +== Best Practices + +[[permission-design]] +=== Permission Design + +Begin with minimal, specific permissions based on actual requirements. Use wildcards only for testing environments and power users who need comprehensive access. Gradually expand permissions based on user needs and usage patterns. + +Avoid `ai:models:*` in production to prevent unexpected access to new expensive models. Use provider-specific permissions like `ai:models:openai:*` for better control, or specify exact models for maximum control. Start with common formats (PDF, DOCX, TXT, PNG, JPEG) and add specialized formats only when needed. + +[[error-handling]] +== Error Handling + +When a user lacks required permissions, the API returns a `403 Forbidden` error with the message "No permissions to the resource". Common issues include missing model permissions, file type restrictions, feature access without permission, and action/review access without permission. + +[[next-steps]] +== Next Steps + +* xref:tinymceai-models.adoc[Learn about AI Models] for model selection and capabilities. +* xref:tinymceai-conversations.adoc[Learn about Conversations] for interactive AI discussions. +* xref:tinymceai-reviews.adoc[Explore Reviews] for content improvement. +* xref:tinymceai-actions.adoc[Discover Actions] for content transformation. +* https://tinymceai.api.tiny.cloud/docs[API Documentation] – Complete API reference for TinyMCE AI. diff --git a/modules/ROOT/pages/tinymceai-quick-start.adoc b/modules/ROOT/pages/tinymceai-quick-start.adoc deleted file mode 100644 index 0581c5f58b..0000000000 --- a/modules/ROOT/pages/tinymceai-quick-start.adoc +++ /dev/null @@ -1,10 +0,0 @@ -= TinyMCE AI Quick Start - -:navtitle: Quick Start -:description: Quick start guide for TinyMCE AI plugin and API -:description_short: Quick start guide for TinyMCE AI -:keywords: AI, quick start, tinymceai, setup - -== Plugin quick start - -== API quick start diff --git a/modules/ROOT/pages/tinymceai-review-plugin.adoc b/modules/ROOT/pages/tinymceai-review-plugin.adoc new file mode 100644 index 0000000000..e1ef6cdcfd --- /dev/null +++ b/modules/ROOT/pages/tinymceai-review-plugin.adoc @@ -0,0 +1,91 @@ += TinyMCE AI Review + +:navtitle: Review +:description: AI Review feature for TinyMCE AI plugin +:description_short: AI Review feature +:keywords: AI, review, reviews, tinymceai + +The Review feature provides users with AI-powered quality assurance for their content by running checks for grammar, style, tone, and more. It also introduces an intuitive interface for reviewing and managing AI-suggested edits directly within the document, ensuring content meets professional standards with minimal manual effort. + +[[overview]] +== Overview + +The Review feature analyzes your content and provides specific recommendations for grammar, style, clarity, and tone improvements. Unlike Actions that transform content directly, Reviews analyze your content and provide suggestions without automatically changing the content. + +[[integration]] +== Integration + +To start using the Review feature, first load the TinyMCE AI plugin in your editor configuration. The Review Mode button will appear in the AI user interface. See xref:tinymceai.adoc[Plugin Reference] for installation and enabling AI features. + +After picking one of the available commands in the Review Mode tab, AI will analyze the document and propose a series of suggestions: + +// image::tinymceai/ai-review-sidebar.png[AI Review sidebar with suggestions] +// TODO: Add image placeholder + +While in the Review Mode, the editor remains read-only and allows you to browse suggestions. You can either click suggestions in the sidebar or select them in the editor content (underlined): + +// image::tinymceai/ai-review-suggestion.png[AI Review suggestion in content] +// TODO: Add image placeholder + +You can accept or dismiss review suggestions by clicking the corresponding buttons. You can also accept all suggestions by using the "Accept all" button in the top of the user interface and preview changes similar to chat suggestions. Changes that were accepted or dismissed become greyed out in the interface. You can also abandon the review by hitting the "Exit review" button. + +Once you are done reviewing your document and all changes are accepted or rejected, click "Finish review" (the button state changes automatically) to return to the normal operation of the editor, where typing is possible. + +[[review-commands]] +== Review commands + +The feature comes with several review commands: + +[cols="1,1,1"] +|=== +|Command name |Command description |Additional information + +|**Custom command** |Enter a custom command for a specific review |You can pick one of the available AI models to execute a custom command + +|**Proofread** |Check the text for errors in grammar, spelling and punctuation | + +|**Improve clarity** |Improve the logical structure and precision for clearer message | + +|**Improve readability** |Adjust sentence structure and word choice for an easier read | + +|**Adjust length** |Shorten or lengthen the text as needed |_Longer_ and _Shorter_ options available + +|**Adjust tone and style** |Modify the text to a desired tone and style |Several tone and style options are available: _Casual, Direct, Friendly, Confident, Professional_ + +|**Translate** |Translate the text into another language |Several languages are available out-of-the-box, and the list can be customized: _English, Spanish, French, German, Chinese (Simplified), Japanese, Russian, Portuguese, Korean, Italian_ +|=== + +[[customizing-translation-commands]] +== Customizing translation commands + +The `tinymceai_reviews_translations` configuration property allows you to provide a custom list of translations for the "Translate" check. For instance, the following configuration will add "German" and "French" to the list: + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + toolbar: 'tinymceai', + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + }, + tinymceai_reviews_translations: [ + { + id: 'german', + label: 'German' + }, + { + id: 'french', + label: 'French' + } + ] +}); +---- + +[[related-features]] +== Related Features + +* xref:tinymceai-chat.adoc[AI Chat] – For interactive discussions with document analysis and context. +* xref:tinymceai-actions-plugin.adoc[AI Quick Actions] – For content transformation and batch processing. +* xref:tinymceai-reviews.adoc[Reviews API] – For API-level review functionality. +* xref:tinymceai-introduction.adoc[Introduction] – Overview of all TinyMCE AI features. diff --git a/modules/ROOT/pages/tinymceai-reviews.adoc b/modules/ROOT/pages/tinymceai-reviews.adoc index 8f4c42f927..fc33c952fa 100644 --- a/modules/ROOT/pages/tinymceai-reviews.adoc +++ b/modules/ROOT/pages/tinymceai-reviews.adoc @@ -4,3 +4,166 @@ :description: AI review feature for {productname} :description_short: AI review feature :keywords: AI, review, reviews, tinymceai + +Reviews provide comprehensive content analysis and improvement suggestions. Unlike Actions that transform content directly, Reviews analyze your content and provide specific recommendations for grammar, style, clarity, and tone improvements. + +**When to use Reviews vs Actions:** Use Reviews when you need to analyze entire documents for quality improvements and get suggestions without automatically changing the content. Use Actions when you need to transform specific text content (fix grammar, translate, adjust tone). + +[[available-reviews]] +== Available Reviews + +[[system-reviews]] +=== System Reviews + +TinyMCE AI provides built-in system reviews for comprehensive content analysis: + +* **Correctness** – Fix grammar, spelling, and factual errors. +* **Clarity** – Improve sentence structure, word choice, and logical flow. +* **Readability** – Enhance paragraph structure, transitions, and reading level. +* **Length Optimization** – Expand or condense content while preserving key information. +* **Tone Adjustment** – Modify tone to casual, direct, friendly, confident, or professional styles. +* **Translation** – Translate content between languages with cultural adaptation. + +[[custom-reviews]] +=== Custom Reviews + +In addition to system reviews, you can create custom reviews tailored to your specific content quality standards and editorial guidelines. Custom reviews allow you to define specialized analysis criteria using your own prompts to control the review behavior. + +Unlike system reviews that use predefined identifiers, custom reviews use a unified endpoint where you define the analysis behavior through a prompt parameter. + +[[key-features]] +== Key Features + +Reviews use streaming output with Server-Sent Events for real-time feedback as suggestions are generated. Each review type is optimized for specific improvement tasks, providing consistent, high-quality analysis of text structure, style, and quality. + +Reviews provide specific, actionable recommendations for content improvement. + +[[api-examples]] +== API Examples + +[[basic-grammar-review-example]] +=== Basic Grammar Review Example + +[source,http] +---- +POST /v1/reviews/system/correctness/calls +Content-Type: application/json +Authorization: Bearer + +{ + "content": [ + { + "type": "text", + "content": "

The norhtern lights dence across the polar skies, painting ribbons of green and purple light that ripple like a cosmic curtain.

" + } + ] +} +---- + +[[clarity-improvement-example]] +=== Clarity Improvement Example + +[source,http] +---- +POST /v1/reviews/system/clarity/calls +Content-Type: application/json +Authorization: Bearer + +{ + "content": [ + { + "type": "text", + "content": "

The system works by processing data through various algorithms to produce results.

" + } + ] +} +---- + +[[tone-adjustment-example]] +=== Tone Adjustment Example + +[source,http] +---- +POST /v1/reviews/system/make-tone-casual/calls +Content-Type: application/json +Authorization: Bearer + +{ + "content": [ + { + "type": "text", + "content": "

We regret to inform you that your request cannot be processed at this time.

" + } + ], + "args": { + "language": "casual" + } +} +---- + +[[translation-review]] +=== Translation Review + +[source,http] +---- +POST /v1/reviews/system/translate/calls +Content-Type: application/json +Authorization: Bearer + +{ + "content": [ + { + "type": "text", + "content": "

Hello, how are you today?

" + } + ], + "args": { + "language": "Spanish" + } +} +---- + +[[custom-review-example]] +=== Custom Review Example + +[source,http] +---- +POST /v1/reviews/custom/calls +Content-Type: application/json +Authorization: Bearer + +{ + "content": [ + { + "type": "text", + "content": "

Our product is really good and customers love it because it has many features.

" + } + ], + "prompt": "Review the text for vague language and generic claims. Suggest specific, concrete alternatives that would make the content more credible and informative.", + "model": "agent-1" +} +---- + +Custom reviews require the `ai:reviews:custom` permission in your JWT token. + +[[streaming-responses]] +== Streaming Responses + +Reviews use Server-Sent Events (SSE) for real-time streaming results. See the xref:tinymceai-streaming.adoc[Streaming Responses guide] for detailed implementation information. + +[[api-reference]] +== API Reference + +For complete endpoint documentation, request/response schemas, authentication details, and additional parameters, see: + +* **https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API Reference]** – Full documentation for system and custom reviews endpoints. +* **https://tinymceai.api.tiny.cloud/docs[Complete API Documentation]** – Interactive API reference with all TinyMCE AI endpoints. + +[[related-features]] +== Related Features + +* xref:tinymceai-review-plugin.adoc[AI Review Plugin] – For plugin integration and UI configuration. +* xref:tinymceai-conversations.adoc[Conversations API] – For interactive discussions with document analysis and context. +* xref:tinymceai-actions.adoc[Actions API] – For content transformation and batch processing. +* xref:tinymceai-streaming.adoc[Streaming Responses] – For implementing real-time review suggestions. +* xref:tinymceai-api-overview.adoc[API Overview] – Overview of all API features. diff --git a/modules/ROOT/pages/tinymceai-streaming.adoc b/modules/ROOT/pages/tinymceai-streaming.adoc index 22e84a9bb7..65e5602ba9 100644 --- a/modules/ROOT/pages/tinymceai-streaming.adoc +++ b/modules/ROOT/pages/tinymceai-streaming.adoc @@ -4,3 +4,123 @@ :description: Streaming configuration for TinyMCE AI :description_short: Streaming configuration :keywords: AI, streaming, configuration, tinymceai + +Real-time AI interactions using Server-Sent Events (SSE) for immediate feedback and progressive content generation. + +[[overview]] +== Overview + +TinyMCE AI services use Server-Sent Events (SSE) to provide real-time streaming responses. This allows you to see AI-generated content as it is being created, providing immediate feedback and enabling interactive experiences. + +[[sse-event-types]] +== SSE Event Types + +Different AI services provide different types of streaming events. For service-specific event details, see: + +* xref:tinymceai-conversations.adoc#streaming-responses[Conversations] – Interactive AI discussions with text streaming, web search sources, and reasoning. +* xref:tinymceai-reviews.adoc#streaming-responses[Reviews] – Content improvement suggestions and review progress. +* xref:tinymceai-actions.adoc#streaming-responses[Actions] – Content transformations and action progress. + +[[basic-implementation]] +== Basic Implementation + +Here is the standard pattern for consuming SSE streams: + +[source,javascript] +---- +const response = await fetch('/v1/your-endpoint', { + method: 'POST', + headers: { + 'Authorization': 'Bearer ', + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + // Your request payload + }) +}); + +const reader = response.body.getReader(); +const decoder = new TextDecoder(); + +while (true) { + const { done, value } = await reader.read(); + if (done) break; + + const chunk = decoder.decode(value); + const lines = chunk.split('\n'); + + for (const line of lines) { + if (line.startsWith('data: ')) { + const data = JSON.parse(line.slice(6)); + + // Handle different event types + // See service-specific guides for detailed event handling: + // - Conversations: text-delta, source, reasoning, modification-delta + // - Reviews: review-delta, review-metadata + // - Actions: modification-delta, action-metadata + + switch (data.event) { + case 'error': + // Handle errors + console.error('Error:', data.data.message); + break; + default: + // Handle all other events + console.log('Event:', data.event, data.data); + } + } + } +} +---- + +[[event-handling-patterns]] +== Event Handling Patterns + +For detailed event handling examples specific to each service, see: + +* xref:tinymceai-conversations.adoc#streaming-responses[Conversations] – Text streaming, web search sources, reasoning, and document modifications. +* xref:tinymceai-reviews.adoc#streaming-responses[Reviews] – Review suggestions and progress tracking. +* xref:tinymceai-actions.adoc#streaming-responses[Actions] – Content transformations and action progress. + +[[error-handling]] +== Error Handling + +Always handle errors gracefully: + +[source,javascript] +---- +if (data.event === 'error') { + const error = data.data; + console.error('Streaming error:', error.message); + + // Show user-friendly error message + showErrorMessage(error.message); + + // Optionally retry or fallback + if (error.retryable) { + setTimeout(() => retryRequest(), 1000); + } +} +---- + +[[progress-tracking]] +== Progress Tracking + +Use metadata events to show progress. For service-specific progress tracking examples, see xref:tinymceai-reviews.adoc[Review progress and status information]. + +[[api-reference]] +== API Reference + +For complete documentation on streaming endpoints, event schemas, and error codes, see: + +* **https://tinymceai.api.tiny.cloud/docs[Complete API Documentation]** – Interactive API reference with streaming implementation details. +* **https://tinymceai.api.tiny.cloud/docs#tag/Conversations[Conversations API]** – Streaming events for conversations. +* **https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API]** – Streaming events for reviews. +* **https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API]** – Streaming events for actions. + +[[next-steps]] +== Next Steps + +* xref:tinymceai-conversations.adoc[Learn about Conversations] for interactive AI discussions. +* xref:tinymceai-reviews.adoc[Explore Reviews] for content improvement. +* xref:tinymceai-actions.adoc[Discover Actions] for content transformation. diff --git a/modules/ROOT/pages/tinymceai-without-tinymce.adoc b/modules/ROOT/pages/tinymceai-without-tinymce.adoc deleted file mode 100644 index 5740a134ef..0000000000 --- a/modules/ROOT/pages/tinymceai-without-tinymce.adoc +++ /dev/null @@ -1,6 +0,0 @@ -= Using the AI Service without TinyMCE - -:navtitle: Using the AI Service without TinyMCE -:description: How to use the AI service without {productname} -:description_short: Using the AI service standalone -:keywords: AI, AI service, standalone, tinymceai diff --git a/modules/ROOT/pages/tinymceai.adoc b/modules/ROOT/pages/tinymceai.adoc index 3650747a21..681d72e8e8 100644 --- a/modules/ROOT/pages/tinymceai.adoc +++ b/modules/ROOT/pages/tinymceai.adoc @@ -1,4 +1,4 @@ -= TinyMCE AI += TinyMCE AI Plugin :navtitle: TinyMCE AI :description: AI-powered features for {productname} including AI chat, AI review, and quick actions @@ -9,26 +9,39 @@ :pluginminimumplan: enterpriseplan :plugincategory: premium -[[what-is-tinymce-ai]] -== What is TinyMCE AI +include::partial$misc/admon-premium-plugin.adoc[] -[[plugin-vs-api]] -== Plugin vs API - -[[architecture-overview]] -== Architecture overview +The {pluginname} plugin integrates AI-assisted authoring with rich-text editing. Users can interact through Actions, Reviews, or Conversations that can use relevant context from multiple sources. [[interactive-example]] == Interactive example -liveDemo::{tinymceai}[] - -[[plugin-reference]] -== Plugin reference +liveDemo::{plugincode}[] [[basic-setup]] == Basic setup +To setup the {pluginname} plugin in the editor: + +* add `{plugincode}` to the `plugins` option in the editor configuration; +* add `{plugincode}` to the `toolbar` option in the editor configuration; +* configure the `tinymceai_token_provider` option to provide authentication tokens; + +For example: + +[source,js] +---- +tinymce.init({ + selector: 'textarea', // change this value according to your HTML + plugins: 'tinymceai', + toolbar: 'tinymceai', + tinymceai_token_provider: function() { + // Return a promise that resolves to a JWT token + return fetch('/api/token').then(response => response.text()); + } +}); +---- + [[options]] == Options @@ -36,16 +49,14 @@ The following configuration options affect the behavior of the {pluginname} plug include::partial$configuration/tinymceai_token_provider.adoc[leveloffset=+1] -[[toolbar-buttons]] -== Toolbar buttons - include::partial$misc/plugin-toolbar-button-id-boilerplate.adoc[] -[[menu-items]] -== Menu items +include::partial$toolbar-button-ids/{plugincode}-toolbar-buttons.adoc[leveloffset=+1] include::partial$misc/plugin-menu-item-id-boilerplate.adoc[] +include::partial$menu-item-ids/{plugincode}-menu-items.adoc[leveloffset=+1] + [[commands]] == Commands From 28eef2eb228dc9303258243a145545cf3675d6dd Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Tue, 10 Feb 2026 09:07:06 +1000 Subject: [PATCH 03/10] DOC-3356: Add JWT authentication guides for plugin, major content changes and improvements. --- modules/ROOT/nav.adoc | 17 +- .../ROOT/pages/tinymceai-actions-plugin.adoc | 99 ++-- .../ROOT/pages/tinymceai-api-overview.adoc | 8 +- .../ROOT/pages/tinymceai-api-quick-start.adoc | 13 +- modules/ROOT/pages/tinymceai-chat.adoc | 231 +++++++- .../pages/tinymceai-integration-options.adoc | 6 +- modules/ROOT/pages/tinymceai-integration.adoc | 557 ++++++++++++++++++ .../ROOT/pages/tinymceai-introduction.adoc | 107 +--- .../ROOT/pages/tinymceai-review-plugin.adoc | 25 +- ...ymceai-with-jwt-authentication-nodejs.adoc | 135 ++++- ...tinymceai-with-jwt-authentication-php.adoc | 137 ++++- modules/ROOT/pages/tinymceai.adoc | 35 ++ .../auth/tinymceai/jwt-setup-tinymceai.adoc | 91 +++ .../tinymceai/nodejs/configuration-steps.adoc | 31 + .../nodejs/initial-project-setup.adoc | 39 ++ .../nodejs/intro-and-prerequisites.adoc | 31 + .../tinymceai/php/configuration-steps.adoc | 31 + .../tinymceai/php/initial-project-setup.adoc | 53 ++ .../php/intro-and-prerequisites.adoc | 33 ++ .../partials/commands/tinymceai-cmds.adoc | 26 +- .../tinymceai_token_provider.adoc | 19 +- .../partials/events/tinymceai-events.adoc | 16 +- .../partials/plugin-apis/tinymceai-apis.adoc | 2 +- .../tinymceai-toolbar-buttons.adoc | 26 + 24 files changed, 1541 insertions(+), 227 deletions(-) create mode 100644 modules/ROOT/pages/tinymceai-integration.adoc create mode 100644 modules/ROOT/partials/auth/tinymceai/jwt-setup-tinymceai.adoc create mode 100644 modules/ROOT/partials/auth/tinymceai/nodejs/configuration-steps.adoc create mode 100644 modules/ROOT/partials/auth/tinymceai/nodejs/initial-project-setup.adoc create mode 100644 modules/ROOT/partials/auth/tinymceai/nodejs/intro-and-prerequisites.adoc create mode 100644 modules/ROOT/partials/auth/tinymceai/php/configuration-steps.adoc create mode 100644 modules/ROOT/partials/auth/tinymceai/php/initial-project-setup.adoc create mode 100644 modules/ROOT/partials/auth/tinymceai/php/intro-and-prerequisites.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 19585152d4..86cc274dc1 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -262,10 +262,10 @@ **** xref:ai-proxy.adoc[AI proxy server reference guide] *** TinyMCE AI **** xref:tinymceai-introduction.adoc[Introduction] -***** Features -****** xref:tinymceai-chat.adoc[Chat] -****** xref:tinymceai-review-plugin.adoc[Review] -****** xref:tinymceai-actions-plugin.adoc[Actions] +***** xref:tinymceai-chat.adoc[Chat] +***** xref:tinymceai-review-plugin.adoc[Review] +***** xref:tinymceai-actions-plugin.adoc[Actions] +***** xref:tinymceai-integration.adoc[Integration] ***** xref:tinymceai-integration-options.adoc[Integration Options] ****** xref:tinymceai.adoc[Plugin quick start] ****** REST API @@ -282,11 +282,12 @@ ******** xref:tinymceai-streaming.adoc[Streaming] ******* Integration ******** xref:tinymceai-api-overview.adoc#data-handling-and-security[Data Handling and Security] -******** xref:tinymceai-api-overview.adoc#on-premises-deployment[On-premises deployment] + ******** xref:tinymceai-api-overview.adoc#security-features[Security] -****** JWT Authentication -******* xref:tinymceai-with-jwt-authentication-nodejs.adoc[JWT authentication (Node.js)] -******* xref:tinymceai-with-jwt-authentication-php.adoc[JWT authentication (PHP)] +******** xref:tinymceai-api-overview.adoc#on-premises-deployment[On-premises deployment] +***** JWT Authentication +****** xref:tinymceai-with-jwt-authentication-nodejs.adoc[JWT authentication (Node.js)] +****** xref:tinymceai-with-jwt-authentication-php.adoc[JWT authentication (PHP)] *** xref:casechange.adoc[Case Change] *** xref:checklist.adoc[Checklist] *** Comments diff --git a/modules/ROOT/pages/tinymceai-actions-plugin.adoc b/modules/ROOT/pages/tinymceai-actions-plugin.adoc index e174544d7e..cdc30a7e9e 100644 --- a/modules/ROOT/pages/tinymceai-actions-plugin.adoc +++ b/modules/ROOT/pages/tinymceai-actions-plugin.adoc @@ -5,7 +5,12 @@ :description_short: quick actions feature :keywords: AI, quick actions, actions, tinymceai -quick actions streamline routine content transformations by offering one-click AI-powered suggestions directly within the editor. You can also ask questions about your selected text in the Chat to get instant AI insights and analysis. This feature enhances speed, relevance, and usability, particularly for repeatable or simple tasks, while preserving deeper chat-based functionality when needed. +Quick actions streamline routine content transformations by offering one-click AI-powered suggestions directly within the editor. You can also ask questions about your selected text in AI chat to get instant AI insights and analysis. This feature enhances speed, relevance, and usability, particularly for repeatable or simple tasks. The feature comes with an easy-to-use window interface but can also act as a conversation starter with the xref:tinymceai-chat.adoc[Chat]. + +[[demo]] +== Demo + +liveDemo::tinymceai[] [[overview]] == Overview @@ -14,17 +19,18 @@ Actions are fast, stateless operations that transform content directly. Unlike R **When to use Actions vs Reviews:** Use Actions when you need to transform specific text content (fix grammar, translate, adjust tone). Use Reviews when you need to analyze entire documents for quality improvements and get suggestions without automatically changing the content. +image::https://placehold.net/default.png[TinyMCE AI quick actions showing AI-powered suggestions and Q&A functionality] + [[integration]] == Integration -To start using the quick actions feature, first load the TinyMCE AI plugin in your editor configuration. See xref:tinymceai.adoc[Plugin Reference] for installation and enabling AI features. +To start using the Quick Actions feature, first load the TinyMCE AI plugin in your editor configuration. xref:tinymceai-integration.adoc[Learn more about installing and enabling AI features]. -Then, you can add the menu that opens the list of quick actions (`tinymceai-actions`) to your main toolbar and/or balloon toolbar configurations. To learn more about toolbar configuration, refer to the xref:toolbar-configuration-options.adoc[toolbar configuration] guide. +Then, you can add the menu that opens the list of Quick Actions (`tinymceai-actions`) image:https://placehold.net/default.png[Quick Actions icon,24px] to your main toolbar and/or balloon toolbar configurations. To learn more about toolbar configuration, refer to the xref:toolbar-configuration-options.adoc[toolbar configuration] guide. -// image::tinymceai/ai-quick-actions-dropdown.png[AI quick actions dropdown in the toolbar] -// TODO: Add image placeholder +image::https://placehold.net/default.png[TinyMCE AI Quick Actions dropdown in the toolbar] -Finally, you can also add individual quick actions to the toolbar as shortcuts for even easier access. For example, you can add the `ask-ai` button, or the `improve-writing` button. You can add whole categories to the toolbar, too. +Finally, you can also add individual Quick Actions to the toolbar as shortcuts for even easier access. For example, you can add the `ask-ai` image:https://placehold.net/default.png[Ask AI icon,24px] button, or the `improve-writing` image:https://placehold.net/default.png[Improve Writing icon,24px] button (find it in the demo above). You can add whole categories to the toolbar, too. xref:tinymceai-actions-plugin.adoc#default-actions[Learn more about available actions]. The final example configuration looks as follows: @@ -33,10 +39,13 @@ The final example configuration looks as follows: tinymce.init({ selector: '#editor', plugins: 'tinymceai', + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + }, - // Adding quick actions to the main editor toolbar + // Adding Quick Actions to the main editor toolbar. toolbar: [ - // The main quick actions button + // The main Quick Actions button 'tinymceai-actions', // Two individual actions @@ -49,13 +58,9 @@ tinymce.init({ // ... other toolbar items ], - // Adding quick actions to the balloon toolbar. Since some of the actions are selection-sensitive, - // accessing them might be easier for users using this kind of toolbar - quickbars_selection_toolbar: 'tinymceai-actions | ask-ai | improve-writing | translate', - - tinymceai_token_provider: function() { - return fetch('/api/token').then(response => response.text()); - } + // Adding Quick Actions to the balloon toolbar. Since some of the actions are selection-sensitive, + // accessing them might be easier for users using this kind of toolbar. + quickbars_selection_toolbar: 'tinymceai-actions | ask-ai | improve-writing | translate' }); ---- @@ -68,47 +73,47 @@ There are two types of actions available in the quick actions feature: * Executing other actions like "Continue writing" or "Make shorter" will open the window interface conveniently right next to your selection and present the answers from the AI for you to accept or reject them. -You can define the behavior of each action when you create custom ones. +You can define the behavior of each action when you xref:tinymceai-actions-plugin.adoc#custom-actions[create custom ones]. [[default-actions]] == Default Actions -By default, the quick actions feature includes several built-in actions that speed up the content editing process. All quick actions can be accessed through the menu button (`tinymceai-actions`) but also individually when handpicked by the integrator in the editor toolbar configuration. You can add the whole action categories to the toolbar too. +By default, the Quick Actions feature includes several built-in actions that speed up the content editing process. All Quick Actions can be accessed through the menu button image:https://placehold.net/default.png[Quick Actions icon,24px] (`tinymceai-actions`) but also individually when handpicked by the integrator in the xref:toolbar-configuration-options.adoc[editor toolbar configuration]. You can add the whole action categories to the toolbar too. -Keep in mind that you can add custom actions to the list and remove defaults. +Keep in mind that you can xref:tinymceai-actions-plugin.adoc#custom-actions[add custom actions] to the list and xref:tinymceai-actions-plugin.adoc#removing-default-actions[remove defaults]. Here's the full list of available actions: -* `ask-ai` -* **Chat commands** category (`chat-commands`) - ** `explain` - ** `summarize` - ** `highlight-key-points` -* `improve-writing` -* `continue` -* `fix-grammar` -* **Adjust length** category (`adjust-length`) - ** `make-shorter` - ** `make-longer` -* **Change tone** category (`change-tone`) - ** `make-tone-casual` - ** `make-tone-direct` - ** `make-tone-friendly` - ** `make-tone-confident` - ** `make-tone-professional` -* **Translate** category (`translate`) - ** `translate-to-english` - ** `translate-to-chinese` - ** `translate-to-french` - ** `translate-to-german` - ** `translate-to-italian` - ** `translate-to-portuguese` - ** `translate-to-russian` +* `'ask-ai'` +* **"Chat commands"** category (`'chat-commands'`) + ** `'explain'` + ** `'summarize'` + ** `'highlight-key-points'` +* `'improve-writing'` +* `'continue'` +* `'fix-grammar'` +* **"Adjust length"** category (`'adjust-length'`) + ** `'make-shorter'` + ** `'make-longer'` +* **"Change tone"** category (`'change-tone'`) + ** `'make-tone-casual'` + ** `'make-tone-direct'` + ** `'make-tone-friendly'` + ** `'make-tone-confident'` + ** `'make-tone-professional'` +* **"Translate"** category (`'translate'`) + ** `'translate-to-english'` + ** `'translate-to-chinese'` + ** `'translate-to-french'` + ** `'translate-to-german'` + ** `'translate-to-italian'` + ** `'translate-to-portuguese'` + ** `'translate-to-russian'` [[custom-actions]] == Custom Actions -The `tinymceai_actions_extraCommands` configuration property allows you to add new commands to the AI quick actions feature. Below, you will find an example of three extra actions added to the user interface: two of them open the quick actions window, but the last one interacts with the Chat. Learn more about types of actions. +The `tinymceai_actions_extraCommands` configuration property allows you to add new commands to the Quick actions feature. Below, you will find an example of three extra actions added to the user interface: two of them open the quick actions window, but the last one interacts with AI chat. Learn more about xref:tinymceai-actions-plugin.adoc#types-of-actions[types of actions]. [source,js] ---- @@ -149,7 +154,7 @@ tinymce.init({ [[removing-default-actions]] == Removing default actions -The `tinymceai_actions_removeCommands` configuration property allows you to remove existing commands from the AI quick actions feature. Here's an example that removes two actions ("Explain" and "Summarize"): +The `tinymceai_actions_removeCommands` configuration property allows you to remove existing commands from the Quick actions feature. Here's an example that removes two actions ("Explain" and "Summarize"): [source,js] ---- @@ -172,7 +177,7 @@ tinymce.init({ [[related-features]] == Related Features -* xref:tinymceai-chat.adoc[AI Chat] – For interactive discussions with document analysis and context. -* xref:tinymceai-review-plugin.adoc[AI Review] – For content quality analysis and improvement suggestions. +* xref:tinymceai-chat.adoc[AI chat] – For interactive discussions with document analysis and context. +* xref:tinymceai-review-plugin.adoc[AI review] – For content quality analysis and improvement suggestions. * xref:tinymceai-actions.adoc[Actions API] – For API-level action functionality. * xref:tinymceai-introduction.adoc[Introduction] – Overview of all TinyMCE AI features. diff --git a/modules/ROOT/pages/tinymceai-api-overview.adoc b/modules/ROOT/pages/tinymceai-api-overview.adoc index 09cbd2ed50..135b85f861 100644 --- a/modules/ROOT/pages/tinymceai-api-overview.adoc +++ b/modules/ROOT/pages/tinymceai-api-overview.adoc @@ -1,15 +1,15 @@ = TinyMCE AI API Overview :navtitle: API Overview -:description: Overview of TinyMCE AI REST API features and capabilities +:description: Overview of TinyMCE AI service features and capabilities :description_short: API Overview -:keywords: AI, API, REST API, overview, tinymceai +:keywords: AI, API, AI service, overview, tinymceai TinyMCE AI integrates AI-assisted authoring with rich-text editing. Users can interact through Actions, Reviews, or Conversations that can use relevant context from multiple sources. [NOTE] ==== -**REST API Reference**: The complete API documentation with all endpoints, parameters, request/response schemas, and interactive examples is available at link:https://tinymceai.api.tiny.cloud/docs[TinyMCE AI API Documentation] +**API Reference**: The complete API documentation with all endpoints, parameters, request/response schemas, and interactive examples is available at link:https://tinymceai.api.tiny.cloud/docs[TinyMCE AI API Documentation] ==== [[getting-started]] @@ -72,5 +72,5 @@ All data is encrypted in transit and at rest with end-to-end encryption. Convers [[resources-and-support]] == Resources and Support -* **REST API Documentation**: link:https://tinymceai.api.tiny.cloud/docs[Complete API reference for TinyMCE AI]. +* **API Documentation**: link:https://tinymceai.api.tiny.cloud/docs[Complete API reference for TinyMCE AI]. * **Customer Support**: link:https://www.tiny.cloud/contact/[Contact us] to get help from our support team or speak with sales. diff --git a/modules/ROOT/pages/tinymceai-api-quick-start.adoc b/modules/ROOT/pages/tinymceai-api-quick-start.adoc index 97d6c5f41e..43666a8eff 100644 --- a/modules/ROOT/pages/tinymceai-api-quick-start.adoc +++ b/modules/ROOT/pages/tinymceai-api-quick-start.adoc @@ -1,11 +1,11 @@ = TinyMCE AI API Quick Start :navtitle: API Quick Start -:description: Quick start guide for TinyMCE AI REST API +:description: Quick start guide for TinyMCE AI service :description_short: API quick start guide -:keywords: AI, quick start, API, REST API, tinymceai, setup +:keywords: AI, quick start, API, AI service, tinymceai, setup -The aim of this article is to get you up and running with the TinyMCE AI REST API. +The aim of this article is to get you up and running with the TinyMCE AI service. [TIP] ==== @@ -16,7 +16,7 @@ The TinyMCE Premium Features free trial allows for testing SaaS services. If you == Getting Started -To start using the TinyMCE AI REST API, follow the steps below: +To start using the TinyMCE AI service, follow the steps below: * Sign up for one of our link:https://www.tiny.cloud/pricing/[self-service plans], or link:https://www.tiny.cloud/contact/[contact us] to purchase the TinyMCE AI license. * Generate your access credentials in the link:https://www.tiny.cloud/my-account/[Customer Portal]. @@ -40,8 +40,7 @@ After signing up, you will receive access to the link:https://www.tiny.cloud/my- Log in to the link:https://www.tiny.cloud/my-account/[Customer Portal] and navigate to link:https://www.tiny.cloud/my-account/jwt/["JWT Keys"]. -// image::tinymceai/ai-trial-view.png[TinyMCE AI trial view] -// TODO: Add image placeholder +image::https://placehold.net/default.png[TinyMCE AI trial view] [[create-token-endpoint]] == Create token endpoint @@ -63,7 +62,7 @@ Cloud Services can reside in either US or EU region or in both. The region is se [[api-integration]] == API Integration -All features are accessible through the REST API at `https://tinymceai.api.tiny.cloud` with JWT authentication. +All features are accessible through the API at `https://tinymceai.api.tiny.cloud` with JWT authentication. For an overview of all API features, see xref:tinymceai-api-overview.adoc[API Overview]. diff --git a/modules/ROOT/pages/tinymceai-chat.adoc b/modules/ROOT/pages/tinymceai-chat.adoc index cfa352e859..71624ac662 100644 --- a/modules/ROOT/pages/tinymceai-chat.adoc +++ b/modules/ROOT/pages/tinymceai-chat.adoc @@ -12,17 +12,91 @@ The TinyMCE AI Chat is a conversational AI that can be used to aid content creat The Chat feature provides context setting and model selection to better suit the needs of specific content and holds chat history for quick reference of previous work. The Chat is also capable of using the web for more up-to-date information and reasoning to think more deeply about the answers and changes it is allowed to make. +image::https://placehold.net/default.png[TinyMCE AI Chat interface showing the conversational AI assistant] + +[[working-with-the-document]] +=== Working with the document + +TinyMCE AI operates directly within the context of your document. When you chat with it, you can ask questions about specific sections, request a full-document proofreading, and more. + +By enabling xref:tinymceai-chat.adoc#web-search[Web search] or xref:tinymceai-chat.adoc#reasoning[Reasoning], you can extend its capabilities — allowing the chat to look up information online and tackle complex tasks step by step. + +[[making-changes-to-the-content]] +=== Making changes to the content + +Not only can you chat with the AI, but you can also use it to introduce changes to your document. Ask it to _"Summarize the document"_, _"Turn this report into a one-page executive summary"_, or _"Suggest better section titles and subheadings"_. The AI will then propose a series of changes to the document you can xref:tinymceai-chat.adoc#previewing-changes[review] and xref:tinymceai-chat.adoc#applying-changes[accept or discard one by one]. **Copying and pasting chat transcripts is over; TinyMCE AI understands your content and edits with you hand in hand**. + +[[brainstorming]] +=== Brainstorming + +The chat feature jump-starts your creative process. Begin with a blank document and ask the AI for ideas. Build your content step by step by chatting and applying changes. Then review — or have the AI rewrite — the final draft for best results. All in one place. + +[[demo]] +== Demo + +liveDemo::tinymceai[] + [[integration]] == Integration -To start using the Chat feature, first load the TinyMCE AI plugin in your editor configuration. See xref:tinymceai.adoc[Plugin Reference] for installation and enabling AI features. +To start using the Chat feature, first load the TinyMCE AI plugin in your editor configuration. The Chat button image:https://placehold.net/default.png[Chat icon,24px] will appear in the AI user interface along with the Chat history image:https://placehold.net/default.png[History icon,24px]. See xref:tinymceai.adoc[Plugin Reference] for installation and enabling AI features. + +[[available-models]] +== Available models + +Users can select the desired AI model for their conversation from a dropdown at the bottom of the chat. + +image::https://placehold.net/default.png[TinyMCE AI Chat available models dropdown] + +Once selected, the AI model will persist for the duration of the conversation. If you want to change the model, you can start a new conversation using a dedicated image:https://placehold.net/default.png[New chat icon,24px] button at the top-right corner of the chat panel. + +[[web-search]] +=== Web search -The Chat interface can be accessed through the main AI button in the toolbar or by using the `tinymceai-conversations` toolbar button. +Web search in Chat allows it to access and retrieve real-time information from the internet. Instead of relying only on pre-trained knowledge, the model can search the web to find up-to-date facts, verify details, and provide more accurate, current answers. Toggle the "Enable web search" button image:https://placehold.net/default.png[Web search icon,24px] for a compatible model to start using the Web search functionality. + +[[reasoning]] +=== Reasoning + +Reasoning in Chat models turns on the ability to think through problems, draw logical conclusions, and make sense of complex information. It enables the model to analyze context, connect ideas, and produce well-structured, coherent answers beyond simple pattern matching. Toggle the "Enable reasoning" button image:https://placehold.net/default.png[Reasoning icon,24px] for a compatible model to start using the Reasoning functionality. + +[[model-selection-configuration]] +=== Configuration + +The `tinymceai_conversations_models` configuration property allows you to configure model selection for AI chat. The property lets the integrator set the default model, tailor the available models list, or turn the list off. xref:tinymceai-integration.adoc#supported-ai-models[Learn more about available AI models]. + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + toolbar: 'tinymceai', + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + }, + tinymceai_conversations_models: { + defaultModelId: 'claude-3-5-haiku', + modelSelectorAlwaysVisible: false, + displayedModels: ['gpt', 'claude'] + } +}); +---- + +[[adding-context-to-conversations]] +== Adding context to conversations + +The AI chat can work with your document and beyond. Use the "Add context" button image:https://placehold.net/default.png[Add context icon,24px] on the right of the prompt input, to add URLs, files, and external resources to your conversation. + +image::https://placehold.net/default.png[TinyMCE AI Chat add context user interface] + +Ask the AI about specific resources, for instance, _"Describe the attached image"_ or _"Summarize the key points from the attached Word document"_. The AI will analyze those resources for you and provide information you can easily use in your document. + +External resources enable you to seamlessly integrate knowledge bases and other centralized data into your AI chat conversations. Instead of uploading documents each time you want to chat, you can simply select them from a list and reference them during your conversation. [[context-configuration]] -== Context Configuration +=== Configuration -The `tinymceai_conversations_context` configuration property configures the AI Chat menu for adding resources to the prompt context. +The `tinymceai_conversations_context` configuration property configures the AI chat menu for adding resources to the prompt context. The example below enables built-in options to add the current document, URLs, and files to the conversation context by the user. @@ -38,18 +112,68 @@ tinymce.init({ return fetch('/api/token').then(response => response.text()); }, tinymceai_conversations_context: { - document: true, - url: true, - file: true, + // Allow for adding the current document to the conversation. + document: { + enabled: true + }, + // Allow for adding URLs to the conversation. + urls: { + enabled: true + }, + // Allow for uploading files to the conversation. + files: { + enabled: true + }, + // External resources configuration. sources: [ + // Definition of the custom context provider. { - id: 'knowledge-base', - label: 'Knowledge Base', - fetch: async () => { - const response = await fetch('/api/knowledge-base'); - return response.json(); - } - } + // The unique identifier of the provider. + id: 'my-docs', + // The human-readable name of the provider. + label: 'My Documents', + // The async callback to retrieve the list of available resources. + // Usually involves fetching data from a database or an external API, + // but here we use a simple array of resources for demonstration purposes. + getResources: async (query) => [ + // Text resources. + { + id: 'text3', + type: 'text', + label: 'Internal note in HTML format', + data: { + content: '

HTML note

Lorem ipsum dolor sit amet...

', + type: 'html' + } + }, + { + id: 'text4', + type: 'text', + label: 'Internal note (fetched on demand)', + // Note: Since the `data` property is not provided, the content will be retrieved using the `getData()` callback (see below). + // This will prevent fetching large content along with the list of resources. + }, + // URLs to resources. + { + id: 'url2', + type: 'web-resource', + label: 'Company brochure in PDF', + data: 'https://example.com/brochure.pdf' + }, + { + id: 'url3', + type: 'web-resource', + label: 'Company website in HTML', + data: 'https://example.com/index.html' + }, + // ... + ], + // The optional callback to retrieve the content of resources without the `data` property provided by the `getResources()` callback. + // When the user picks a specific resource, the content will be fetched on demand (from database or external API) by this callback. + // This prevents fetching large resources along with the list of resources. + getData: (id) => fetchDocumentContent(id) + }, + // More context providers... ] } }); @@ -58,36 +182,79 @@ tinymce.init({ [[working-with-ai-generated-changes]] == Working with AI-generated changes -When the AI suggests changes to your content, you can: +If you ask the AI for changes to your document, for instance, _"Bold key facts in the document"_, you will receive a series of proposed changes instead of plain text responses. + +image::https://placehold.net/default.png[TinyMCE AI Chat changes] + +Move your cursor over any change to highlight the section of your document it applies to, helping you identify it among other proposed edits. + +image::https://placehold.net/default.png[TinyMCE AI Chat highlighted changes in content] + +[[showing-details]] +=== Showing details + +You can toggle details of the changes by pressing the "Show details" button image:https://placehold.net/default.png[Show details icon,24px]. By default, you will see detailed information on what exactly was suggested, including additions (green markers), removals (red markers), and formatting changes (blue markers). + +image::https://placehold.net/default.png[TinyMCE AI Chat highlighted changes] + +Click the button again to see a clean, simplified overview of the changes as they'll appear in your document once accepted. + +image::https://placehold.net/default.png[TinyMCE AI Chat clean view] + +[[previewing-changes]] +=== Previewing changes + +Click the "Show in the text" button image:https://placehold.net/default.png[Show in the text icon,24px] to display the information window about an individual change with options to apply it or turn it into a Suggested Edits suggestion. You can use this window to browse all proposed changes and work with them one by one. As you navigate through the changes, the window will automatically follow the corresponding sections of the document. + +image::https://placehold.net/default.png[TinyMCE AI Chat changes preview in text] + +[[applying-changes]] +=== Applying changes + +If you click the "Apply" button in the AI balloon, the change proposed by the AI will be applied to the document. + +image::https://placehold.net/default.png[TinyMCE AI Chat apply changes] + +Click the "Apply all" button in chat to apply all AI suggestions at once. + +image::https://placehold.net/default.png[TinyMCE AI Chat apply all changes] + +[[inserting-suggested-edits]] +=== Inserting Suggested Edits suggestions + +When xref:suggestededits.adoc[Suggested Edits feature] is available in your integration, the "Insert suggestion" button image:https://placehold.net/default.png[Insert suggestion icon,24px] will be available in chat. Clicking it will create a Suggested Edits suggestion that can later be reviewed or discarded. + +image::https://placehold.net/default.png[TinyMCE AI Chat insert suggestion button] + +You can pick "Suggest" option from the "Apply all" menu to turn all changes suggested by AI into Suggested Edits suggestions. + +[[rejecting-suggestions]] +=== Rejecting suggestions + +You can click the "Delete" button image:https://placehold.net/default.png[Delete icon,24px] to reject AI suggestions you do not want before applying the remaining ones or turning them into Suggested Edits suggestions. -* **Accept** - Accept the suggested changes that are rendered directly in the document -* **Reject** - Discard the suggestion -* **Edit** - Modify the suggestion before applying -* **Suggested Edits** - Convert suggestions to Suggested Edits for review +image::https://placehold.net/default.png[TinyMCE AI Chat reject button] -// image::tinymceai/ai-chat-suggestions.png[AI Chat suggestions interface] -// TODO: Add image placeholder [[chat-history]] == Chat history -All your past conversations appear in the Chat history. Click the button to open the list, where you can reopen, rename, or delete any conversation. +All your past conversations appear in the Chat history. Click the button image:https://placehold.net/default.png[Chat history icon,24px] to open the list, where you can reopen, rename, or delete any conversation. Conversations are grouped by date to help you navigate your project easily. You can filter conversations by name using the search field at the top of the user interface. -// image::tinymceai/ai-chat-history.png[AI Chat history] -// TODO: Add image placeholder +image::https://placehold.net/default.png[AI Chat history] [NOTE] ==== -You can continue any conversation from the chat history as long as the AI model used for that conversation is still supported by the feature. Click the conversation in the history to load it in the Chat interface. +You can continue any conversation from the chat history as long as the AI model used for that conversation is xref:tinymceai-models.adoc#supported-models[still supported] by the feature. Click the conversation in the history to load it in the Chat interface. ==== [NOTE] ==== The ability to apply suggestions to the document or generate Suggested Edits from historical conversations may be restricted in some scenarios: -After closing the browser and reopening the AI Chat, previous conversations will no longer interact with the document content. To continue working with a conversation, you can reopen it from the chat history. +After closing the browser and reopening AI chat, previous conversations will no longer interact with the document content. To continue working with a conversation, you can reopen it from the chat history. ==== [[advanced-features]] @@ -95,16 +262,16 @@ After closing the browser and reopening the AI Chat, previous conversations will The Chat feature supports advanced capabilities: -* **Web Search** - Access up-to-date information from the web -* **Reasoning** - Deep thinking about answers and changes -* **Multi-turn conversations** - Maintain context across multiple interactions -* **Model selection** - Choose the appropriate AI model for your task +* xref:tinymceai-chat.adoc#chat-history[**Multi-turn conversations**] - Maintain context across multiple interactions +* xref:tinymceai-chat.adoc#available-models[**Model selection**] - Choose the appropriate AI model for your task +* xref:tinymceai-chat.adoc#web-search[**Web Search**] - Access up-to-date information from the web +* xref:tinymceai-chat.adoc#reasoning[**Reasoning**] - Deep thinking about answers and changes For more information about API-level features, see xref:tinymceai-conversations.adoc[Conversations API documentation]. [[related-features]] == Related Features -* xref:tinymceai-review-plugin.adoc[AI Review] – For content quality analysis and improvement suggestions. -* xref:tinymceai-actions-plugin.adoc[AI Quick Actions] – For fast, stateless content transformations. +* xref:tinymceai-review-plugin.adoc[AI review] – For content quality analysis and improvement suggestions. +* xref:tinymceai-actions-plugin.adoc[Quick actions] – For fast, stateless content transformations. * xref:tinymceai-introduction.adoc[Introduction] – Overview of all TinyMCE AI features. diff --git a/modules/ROOT/pages/tinymceai-integration-options.adoc b/modules/ROOT/pages/tinymceai-integration-options.adoc index eb56402cc0..daf975f9b7 100644 --- a/modules/ROOT/pages/tinymceai-integration-options.adoc +++ b/modules/ROOT/pages/tinymceai-integration-options.adoc @@ -3,7 +3,7 @@ :navtitle: Integration Options :description: Choose how to integrate TinyMCE AI with your application :description_short: Integration options for TinyMCE AI -:keywords: AI, integration, plugin, API, REST API, tinymceai +:keywords: AI, integration, plugin, API, AI service, tinymceai TinyMCE AI can be integrated with your application through two methods: @@ -18,8 +18,8 @@ Integrate AI features directly into the TinyMCE editor interface. Works with CDN | [.lead] -xref:tinymceai-api-overview.adoc[**REST API**] +xref:tinymceai-api-overview.adoc[**AI service**] -Use the REST API to build custom integrations and workflows. Perfect for server-side processing, custom UI implementations, and advanced use cases. Start with the xref:tinymceai-api-quick-start.adoc[API Quick Start] guide. +Use the AI service API to build custom integrations and workflows. Perfect for server-side processing, custom UI implementations, and advanced use cases. Start with the xref:tinymceai-api-quick-start.adoc[API Quick Start] guide. |=== diff --git a/modules/ROOT/pages/tinymceai-integration.adoc b/modules/ROOT/pages/tinymceai-integration.adoc new file mode 100644 index 0000000000..d661d76531 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-integration.adoc @@ -0,0 +1,557 @@ += TinyMCE AI Integration + +:navtitle: Integration +:description: Integration guide for TinyMCE AI plugin +:description_short: Integration guide +:keywords: AI, integration, plugin, configuration, tinymceai + +This guide will take you step-by-step through the process of running TinyMCE AI in your editor integration. It also presents possible configuration and customization options. + +[[installation]] +== Installation + +After installing the editor, add the feature to your plugin list and provide xref:tinymceai-integration.adoc#sample-implementation[essential configuration]: + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + toolbar: 'tinymceai', + tinymceai_token_provider: function() { + // Return a promise that resolves to a JWT token + return fetch('/api/token').then(response => response.text()); + } +}); +---- + +[NOTE] +==== +You must configure a user interface type for the AI features to work. Learn more about the available options in the xref:tinymceai-integration.adoc#ui-types-and-positioning[UI placement] section or use the xref:tinymceai-integration.adoc#sample-implementation[sample implementation] as a reference. +==== + +[NOTE] +==== +Using AI features with the Suggested Edits feature requires proper user configuration. Learn more about the xref:tinymceai-integration.adoc#suggested-edits-dependency[Suggested Edits dependency] or refer to the xref:tinymceai-integration.adoc#sample-implementation[sample implementation] for more details. +==== + +[[sample-implementation]] +== Sample implementation + +An example TinyMCE AI configuration is presented below. You can learn more about specific configurations such as xref:tinymceai-integration.adoc#ui-types-and-positioning[UI types and positioning] or xref:tinymceai-integration.adoc#suggested-edits-dependency[Suggested Edits dependency] in the later sections of this guide. + +To learn more about toolbar configuration, refer to the xref:toolbar-configuration-options.adoc[toolbar configuration] guide. + +[source,js] +---- +// Simplified integration of the Users plugin needed for Suggested Edits integration. +// For production applications, replace the dummy user with actual user data from your authentication system. +function setupUsers(editor) { + // Just add a minimal dummy user + editor.settings.tinymceai_user = { + id: 'user-1', + name: 'John Doe' + }; +} + +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai suggestededits', + + // Extend the main editor toolbar configuration with additional buttons: + // - 'tinymceai': opens the Quick actions menu, + // - 'tinymceai-conversations': moves the user focus to AI chat, + // - 'tinymceai-improve-writing': executes the "Improve Writing" quick action. + // + // You can add more Quick actions to the toolbar configuration if needed. + toolbar: [ + 'tinymceai', + 'tinymceai-conversations', + 'tinymceai-improve-writing', + // ... other toolbar items + ], + + // You can use the same AI feature buttons in the balloon toolbar configuration for contextual convenience. + contextmenu: 'tinymceai tinymceai-conversations tinymceai-improve-writing', + + setup: function(editor) { + setupUsers(editor); + }, + + // Configure the document identifier for AI chat history and context preservation. + // This should be a unique identifier for the document/article being edited. + tinymceai_document_id: 'document-123', // Replace with your actual document ID + + // Main configuration of AI feature. + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + }, + + // ⚠️ Mandatory UI configuration. + // Display the AI user interface in a dedicated DOM element. The interface can be also displayed + // in an overlay or in a custom way, learn more in the next chapters of this guide. + tinymceai_ui_type: 'sidebar', + tinymceai_sidebar_element: document.querySelector('.ai-sidebar'), + + // (Optional) Whether the AI interface should be visible when the editor is created. + tinymceai_ui_visible_by_default: false, + + // (Optional) Configure AI chat by configuring available context resources. + tinymceai_conversations_context: { + // Configuration of the built-in context options. + document: { + enabled: true + }, + urls: { + enabled: false + }, + files: { + enabled: true + }, + + // (Optional) Additional sources for AI chat context. + sources: [ + // Definition of the custom context provider. + { + // The unique identifier of the provider. + id: 'my-docs', + + // The human-readable name of the provider. + label: 'My Documents', + + // The async callback to retrieve the list of available resources. + // Usually involves fetching data from a database or an external API, + // but here we use a simple array of resources for demonstration purposes. + getResources: async (query) => [ + // Texts in various formats + { + id: 'text1', + type: 'text', + label: 'Internal note in plain text format', + data: { + content: 'Lorem ipsum dolor sit amet...', + type: 'text' + } + }, + { + id: 'text2', + type: 'text', + label: 'Internal note in Markdown format', + data: { + content: '## Markdown note\n\n**Lorem ipsum** dolor sit amet...', + type: 'markdown' + } + }, + { + id: 'text3', + type: 'text', + label: 'Internal note in HTML format', + data: { + content: '

HTML note

Lorem ipsum dolor sit amet...

', + type: 'html' + } + }, + { + id: 'text4', + type: 'text', + label: 'Internal note (fetched on demand)', + + // Note: Since the `data` property is not provided, the content will be retrieved using the `getData()` callback (see below). + // This will prevent fetching large content along with the list of resources. + }, + + // URLs to resources in different formats + { + id: 'url1', + type: 'web-resource', + label: 'Blog post in Markdown', + data: 'https://example.com/blog-post.md' + }, + { + id: 'url2', + type: 'web-resource', + label: 'Company brochure in PDF', + data: 'https://example.com/brochure.pdf' + }, + { + id: 'url3', + type: 'web-resource', + label: 'Company website in HTML', + data: 'https://example.com/index.html' + }, + { + id: 'url4', + type: 'web-resource', + label: 'Terms of service in plain text', + data: 'https://example.com/terms-of-service.txt' + }, + + // ... + ], + + // The optional callback to retrieve the content of resources without the `data` property provided by the `getResources()` callback. + // When the user picks a specific resource, the content will be fetched on demand (from database or external API) by this callback. + // This prevents fetching large resources along with the list of resources. + getData: (id) => fetchDocumentContent(id) + }, + + // More context providers... + ] + }, + + // (Optional) The configuration of AI chat models selection feature. + tinymceai_conversations_models: { + defaultModelId: 'agent-1', + modelSelectorAlwaysVisible: true, + displayedModels: ['gpt', 'claude'] + }, + + // (Optional) Configure the Quick actions feature by adding a new command. + tinymceai_quick_actions_extra_commands: [ + // An action that opens AI chat interface for interactive conversations. + { + id: 'explain-like-i-am-five', + displayedPrompt: 'Explain like I am five', + prompt: 'Explain the following text like I am five years old.', + type: 'CHAT' + }, + + // ... More custom actions ... + ] +}); +---- + +[[configuration]] +== Configuration + +[[supported-ai-models]] +=== Supported AI models + +TinyMCE AI supports multiple AI models from different providers. By default, the automatically selected model (`agent-1`) will be used for optimal cost and performance. + +You can narrow down the list of available models. xref:tinymceai-chat.adoc#model-selection-configuration[Learn how to configure the list of available models in Chat]. + +Here's a detailed list of available models with their capabilities: + +[cols="1,2,1,1,2"] +|=== +|Model |Description |xref:tinymceai-chat.adoc#web-search[Web Search] |xref:tinymceai-chat.adoc#reasoning[Reasoning] |Configuration id + +|**Auto (default)** +|Automatically selects best model for speed, quality, and cost. +|Yes +|Yes +|`'auto'` (also `'agent-1'`, learn more about xref:tinymceai-models.adoc#model-compatibility-versions[compatibility versions]) + +|**GPT-5.2** +|OpenAI's flagship model for advanced reasoning, creativity, and complex tasks +|Yes +|Yes +|`'gpt-5.2'` + +|**GPT-5.1** +|OpenAI's flagship model for advanced reasoning, creativity, and complex tasks +|Yes +|Yes +|`'gpt-5.1'` + +|**GPT-5** +|OpenAI's flagship model for advanced reasoning, creativity, and complex tasks +|Yes +|Yes +|`'gpt-5'` + +|**GPT-5 Mini** +|A lightweight version of GPT-5 – faster, more cost-efficient +|Yes +|Yes +|`'gpt-5-mini'` + +|**Claude 4.5 Haiku** +|Cost-efficient model for quick interactions with improved reasoning +|Yes +|Yes +|`'claude-4-5-haiku'` + +|**Claude 4.5 Sonnet** +|Advanced model with improved creativity, reliability, and reasoning +|Yes +|Yes +|`'claude-4-5-sonnet'` + +|**Gemini 3 Pro** +|Google's advanced model for versatile problem-solving and research +|Yes +|Yes +|`'gemini-3-pro'` + +|**Gemini 3 Flash** +|Lightweight Gemini model for fast, cost-efficient interactions +|Yes +|Yes +|`'gemini-3-flash'` + +|**Gemini 2.5 Flash** +|Lightweight Gemini model for fast, cost-efficient interactions +|Yes +|Yes +|`'gemini-2-5-flash'` + +|**GPT-4.1** +|OpenAI's model for reliable reasoning, speed, and versatility +|Yes +|No +|`'gpt-4.1'` + +|**GPT-4.1 Mini** +|A lighter variant of GPT-4.1 that balances speed and cost while maintaining solid accuracy +|Yes +|No +|`'gpt-4.1-mini'` +|=== + +[NOTE] +==== +Model availability depends on your subscription tier and service compatibility version. Some models may have specific limitations or requirements. For detailed information about available models, their capabilities, and API-level configuration, see xref:tinymceai-models.adoc[AI models documentation]. +==== + +[[document-id]] +=== Document ID + +The `tinymceai_document_id` configuration property serves as the document identifier corresponding to the edited resource (article, document, etc.) in your application. This ID is essential for maintaining xref:tinymceai-chat.adoc[Chat] history, ensuring that AI conversations are properly associated with the specific document being edited. When users interact with AI features, their chat history is preserved and linked to this document ID. + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + tinymceai_document_id: 'DOCUMENT_ID', // Replace with your actual document ID + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + } +}); +---- + +[NOTE] +==== +The `tinymceai_document_id` configuration uses a dedicated namespace in the configuration. This namespace may be subject to change in future versions as we continue to refine the AI integration architecture. +==== + +[[suggested-edits-dependency]] +=== Suggested Edits dependency + +TinyMCE AI can leverage the Suggested Edits feature to enhance the user experience, for instance, by allowing users to turn AI-generated content into suggestions that can later be reviewed, accepted, or rejected. Without the Suggested Edits plugin, TinyMCE AI will work, but some functionalities may be limited. For the most complete integration, we highly recommend using Suggested Edits along with TinyMCE AI. + +[NOTE] +==== +Please keep in mind that the `suggestededits` plugin requires user management, and as such, it will require you to provide a minimal user integration, even for non-collaborative setups. + +The xref:tinymceai-integration.adoc#sample-implementation[sample implementation] above shows a basic user setup function that adds a dummy user. For production applications, replace the dummy user with actual user data from your authentication system. +==== + +[[ui-types-and-positioning]] +=== UI types and positioning + +TinyMCE AI gives you flexible options for displaying the AI user interface. The `tinymceai_ui_type` and related configuration properties allow you to choose from three different UI placement modes: + +[[sidebar]] +==== Sidebar + +When in sidebar mode, the AI user interface is displayed in a specific DOM element, allowing you to inject it into your existing user interface. + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + tinymceai_ui_type: 'sidebar', + + // Existing DOM element to use as the container for the AI user interface. + tinymceai_sidebar_element: document.querySelector('#ai-sidebar-container'), + + // (Optional) The preferred side for positioning the tab buttons. + tinymceai_sidebar_side: 'right', + + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + } +}); +---- + +In addition to the above, we recommend using the following or similar CSS to style the sidebar container for the AI user interface (tabs) to render optimally: + +[source,css] +---- +#ai-sidebar-container .tinymce-ai-tabs { + /* An arbitrary fixed width to limit the space consumed by the AI tabs. */ + width: 500px; + + /* A fixed height that enables vertical scrolling (e.g., in AI chat feed). */ + height: 800px; +} +---- + +[[overlay]] +==== Overlay + +When in overlay mode, the AI user interface is displayed on top of the page, allowing you to position it on your preferred side. This mode is best suited for integrations with limited space. + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + tinymceai_ui_type: 'overlay', + tinymceai_overlay_side: 'right', + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + } +}); +---- + +Learn how to xref:tinymceai-integration.adoc#toggling-the-ui[toggle the AI overlay] using a dedicated toolbar button. + +[[custom]] +==== Custom + +When in custom mode, the AI user interface is displayed in a custom way, allowing you to use the building blocks of the AI user interface to create your own and satisfy the specific needs of your application. + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + tinymceai_ui_type: 'custom', + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + }, + setup: function(editor) { + // A custom integration of the AI user interface placing the tab buttons and panels separately in custom containers. + editor.on('tinymceai:ready', function() { + const aiTabs = editor.plugins.get('tinymceai').getTabs(); + + for (const id of aiTabs.getTabIds()) { + const tab = aiTabs.getTab(id); + + // Display tab button and panel in a custom container. + myButtonsContainer.appendChild(tab.button.element); + myPanelContainer.appendChild(tab.panel.element); + } + }); + } +}); +---- + +[[toggling-the-ui]] +=== Toggling the UI + +The user interface can be easily toggled by the users using the `'tinymceai-toggle'` image:https://placehold.net/default.png[Ask AI icon,24px] toolbar button. The button becomes available for configuration when the AI features are enabled. + +The following example shows how to enable the `'tinymceai-toggle'` button in the main editor toolbar: + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + + // Enable the 'tinymceai-toggle' button in the main editor toolbar. + toolbar: ['tinymceai-toggle', /* ... */], + + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + }, + + tinymceai_ui_type: 'overlay', + // ... other configuration +}); +---- + +You can also programmatically show or hide the AI interface: + +[source,js] +---- +// Show the AI interface +editor.execCommand('tinymceai:show'); + +// Hide the AI interface +editor.execCommand('tinymceai:hide'); + +// Toggle the AI interface +editor.execCommand('tinymceai:toggle'); +---- + +If you wish to initially hide the overlay until a user opens it with a button, you can use the xref:tinymceai-integration.adoc#hiding-the-ui-on-initialization[dedicated configuration]. + +[[hiding-the-ui-on-initialization]] +=== Hiding the UI on initialization + +By default, the AI interface will be visible when editor is created (and the xref:tinymceai-integration.adoc#toggling-the-ui[related toolbar button] will be active). If you wish to have it hidden until the user opens it (e.g. via toolbar button), set `tinymceai_ui_visible_by_default` property to `false`. + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + tinymceai_ui_visible_by_default: false, + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + } +}); +---- + +[[maximizing-the-ui]] +=== Maximizing the UI + +The maximize button image:https://placehold.net/default.png[Maximize icon,24px] in the upper-right corner allows changing the width of the TinyMCE AI user interface. Users can use this button to interact with the AI features more comfortably, especially while xref:tinymceai-chat.adoc[chatting] and interacting with large chunks of content. + +Clicking this button will toggle the `.tinymce-ai-tabs_maximized` CSS class on the `.tinymce-ai-tabs` DOM element. The integrator can then style the geometry of the element based on the specific requirements of the integration. + +* When the UI is configured in the xref:tinymceai-integration.adoc#sidebar[sidebar mode], the decision on how to style the maximized state of the user interface is left to the integrator due to many possible integration types and configurations. +* When the UI is configured in the xref:tinymceai-integration.adoc#overlay[overlay mode], integrators can override the `--tinymce-ai-tabs-overlay-width-maximized` CSS custom property to change the width of the overlay. + +[source,css] +---- +:root { + /* The TinyMCE AI interface will consume 40% of the space when maximized */ + --tinymce-ai-tabs-overlay-width-maximized: 40%; +} +---- + +You can also programmatically maximize or restore the AI interface: + +[source,js] +---- +// Maximize the AI interface +editor.execCommand('tinymceai:maximize'); + +// Restore the AI interface to normal size +editor.execCommand('tinymceai:restore'); +---- + +[[permissions]] +=== Permissions + +Learn more about the permissions system used in TinyMCE AI in a xref:tinymceai-permissions.adoc[dedicated guide]. + +[[chat]] +== Chat + +Learn more about integrating the Chat feature image:https://placehold.net/default.png[Chat icon,24px] in a xref:tinymceai-chat.adoc[dedicated guide]. + +[[quick-actions]] +== Quick Actions + +Learn more about integrating the Quick Actions feature image:https://placehold.net/default.png[Quick Actions icon,24px] in a xref:tinymceai-actions-plugin.adoc[dedicated guide]. + +[[review]] +== Review + +Learn more about integrating the Review feature image:https://placehold.net/default.png[Review icon,24px] in a xref:tinymceai-review-plugin.adoc[dedicated guide]. + +[[related-features]] +== Related Features + +* xref:tinymceai-introduction.adoc[Introduction] – Overview of all TinyMCE AI features. +* xref:tinymceai.adoc[Plugin Reference] – Complete plugin API reference. +* xref:tinymceai-api-overview.adoc[API Overview] – AI service documentation. diff --git a/modules/ROOT/pages/tinymceai-introduction.adoc b/modules/ROOT/pages/tinymceai-introduction.adoc index a252bd9a69..88d5867f1f 100644 --- a/modules/ROOT/pages/tinymceai-introduction.adoc +++ b/modules/ROOT/pages/tinymceai-introduction.adoc @@ -7,6 +7,11 @@ By integrating AI writing assistance directly into the editing experience, TinyMCE AI empowers authors with real-time AI writing support, streamlines content creation, and enhances editorial workflows across a wide range of use cases – from productivity boosts and proof-reading to content quality and consistency. +[[demo]] +== Demo + +liveDemo::tinymceai[] + [[what-is-tinymce-ai]] == What is TinyMCE AI @@ -16,8 +21,8 @@ Teams can implement a full suite of AI writing tools in weeks rather than months The core components of TinyMCE AI are: -* **{productname}**: A modern rich text editor with dozens of features that improve writing workflows, including collaboration. -* **AI service**: A state-of-the-art backend AI engine that incorporates multiple models and delivers high-quality content. Currently available only in Cloud setup, with on-premises deployment coming soon. The AI service also provides a REST API. +* **xref:tinymceai.adoc[{productname}]**: A modern rich text editor with dozens of features that improve writing workflows, including collaboration. +* **xref:tinymceai-api-overview.adoc[AI service]**: A state-of-the-art backend AI engine that incorporates multiple models and delivers high-quality content. Currently available only in Cloud setup, with on-premises deployment coming soon. [[features]] == TinyMCE AI features @@ -42,101 +47,3 @@ Developers can control access to AI features, models, and capabilities based on == Privacy and data handling You can find detailed information on how TinyMCE AI manages your data in the xref:tinymceai-api-overview.adoc#data-handling-and-security[API Overview] documentation. - -[[known-issues]] -== Known issues and caveats - -The TinyMCE AI plugin has the following known issues and caveats: - -=== General HTML Support - -TinyMCE AI may not work correctly when General HTML Support for block elements is enabled. This issue will be addressed in future updates. In the meantime, we recommend avoiding configurations that may cause problems. - -=== Issues with tables - -We are aware of certain glitches that may occur when the AI modifies complex tables or layout tables. To prevent data loss, please ensure that the content around these structures remains intact when using TinyMCE AI tools, while our team investigates the causes and potential solutions to this issue. - -=== Editor context and multiple editor handling - -While it's possible to use TinyMCE AI with multiple editors in an editor context, only the first editor registered in the context will currently be able to interact with AI tools and benefit from the content suggestions made by the AI. As our team works on resolving this issue, we recommend using standalone editor instances with TinyMCE AI. - -=== Inline image processing issues - -Inline images may not be processed correctly by commands within the AI Review feature. A solution is currently under development. - -=== Quick actions and content markers issues - -Applying quick action responses may result in the loss of Comments and Suggested Edits suggestion markers. This issue will be addressed in a future update. - -=== Limited interactivity in Chat history - -The interactivity of historical AI Chat conversations can become limited over time. - -=== Issues with specific AI models - -Some AI models may occasionally return empty responses. If this occurs, we recommend sending a follow-up message asking the Assistant to complete the previous request, or starting a new conversation. - -NOTE: If you wish to stay informed about updates or discuss TinyMCE AI possibilities, please reach out to us. - -[[common-api]] -== Common API - -The AI features register the following UI components and editor commands. - -[[ui-components]] -=== UI components - -The AI features register the following UI components: - -[cols="1,1"] -|=== -|Component name |Registered by - -|`tinymceai` |Main AI plugin button -|`tinymceai-conversations` |Conversations feature -|`tinymceai-actions` |Quick Actions feature -|`tinymceai-reviews` |Reviews feature -|`ask-ai` |Quick Actions -|`explain` |Quick Actions -|`summarize` |Quick Actions -|`highlight-key-points` |Quick Actions -|`improve-writing` |Quick Actions -|`continue` |Quick Actions -|`fix-grammar` |Quick Actions -|`make-shorter` |Quick Actions -|`make-longer` |Quick Actions -|`make-tone-casual` |Quick Actions -|`make-tone-direct` |Quick Actions -|`make-tone-friendly` |Quick Actions -|`make-tone-confident` |Quick Actions -|`make-tone-professional` |Quick Actions -|`translate-to-english` |Quick Actions -|`translate-to-chinese` |Quick Actions -|`translate-to-french` |Quick Actions -|`translate-to-german` |Quick Actions -|`translate-to-italian` |Quick Actions -|`translate-to-portuguese` |Quick Actions -|`translate-to-russian` |Quick Actions -|=== - -[[editor-commands]] -=== Editor commands - -The TinyMCE AI plugin provides the following {productname} commands: - -[cols="1,1"] -|=== -|Command name |Description - -|`mceTinymceAI` |Toggle AI interface visibility -|`mceTinymceAIConversations` |Open Conversations interface -|`mceTinymceAIActions` |Open Quick Actions interface -|`mceTinymceAIReviews` |Open Reviews interface -|=== - -NOTE: We recommend using the official {productname} inspector for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more. - -[[future-ideas]] -== Future ideas - share your feedback - -Have an idea for future improvements? We'd love to hear from you! Share your thoughts and suggestions with us through our link:https://www.tiny.cloud/contact/[contact form]. diff --git a/modules/ROOT/pages/tinymceai-review-plugin.adoc b/modules/ROOT/pages/tinymceai-review-plugin.adoc index e1ef6cdcfd..a15f271bb1 100644 --- a/modules/ROOT/pages/tinymceai-review-plugin.adoc +++ b/modules/ROOT/pages/tinymceai-review-plugin.adoc @@ -7,27 +7,32 @@ The Review feature provides users with AI-powered quality assurance for their content by running checks for grammar, style, tone, and more. It also introduces an intuitive interface for reviewing and managing AI-suggested edits directly within the document, ensuring content meets professional standards with minimal manual effort. +[[demo]] +== Demo + +liveDemo::tinymceai[] + [[overview]] == Overview The Review feature analyzes your content and provides specific recommendations for grammar, style, clarity, and tone improvements. Unlike Actions that transform content directly, Reviews analyze your content and provide suggestions without automatically changing the content. +image::https://placehold.net/default.png[TinyMCE AI Review feature showing AI-powered quality assurance and suggested edits] + [[integration]] == Integration -To start using the Review feature, first load the TinyMCE AI plugin in your editor configuration. The Review Mode button will appear in the AI user interface. See xref:tinymceai.adoc[Plugin Reference] for installation and enabling AI features. +To start using the Review feature, first load the TinyMCE AI plugin in your editor configuration. The Review Mode button image:https://placehold.net/default.png[Review icon,24px] will appear in the AI user interface. xref:tinymceai-integration.adoc[Learn more about installing and enabling AI features]. After picking one of the available commands in the Review Mode tab, AI will analyze the document and propose a series of suggestions: -// image::tinymceai/ai-review-sidebar.png[AI Review sidebar with suggestions] -// TODO: Add image placeholder +image::https://placehold.net/default.png[TinyMCE AI Review sidebar with suggestions] While in the Review Mode, the editor remains read-only and allows you to browse suggestions. You can either click suggestions in the sidebar or select them in the editor content (underlined): -// image::tinymceai/ai-review-suggestion.png[AI Review suggestion in content] -// TODO: Add image placeholder +image::https://placehold.net/default.png[TinyMCE AI Review suggestion in content] -You can accept or dismiss review suggestions by clicking the corresponding buttons. You can also accept all suggestions by using the "Accept all" button in the top of the user interface and preview changes similar to chat suggestions. Changes that were accepted or dismissed become greyed out in the interface. You can also abandon the review by hitting the "Exit review" button. +You can accept or dismiss review suggestions by clicking the corresponding buttons. You can also accept all suggestions by using the "Accept all" button in the top of the user interface and xref:tinymceai-chat.adoc#previewing-changes[preview changes similar to chat suggestions]. Changes that were accepted or dismissed become greyed out in the interface. You can also abandon the review by hitting the "Exit review" button. Once you are done reviewing your document and all changes are accepted or rejected, click "Finish review" (the button state changes automatically) to return to the normal operation of the editor, where typing is possible. @@ -40,7 +45,7 @@ The feature comes with several review commands: |=== |Command name |Command description |Additional information -|**Custom command** |Enter a custom command for a specific review |You can pick one of the available AI models to execute a custom command +|**Custom command** |Enter a custom command for a specific review |You can pick one of the xref:tinymceai-integration.adoc#supported-ai-models[available AI models] to execute a custom command |**Proofread** |Check the text for errors in grammar, spelling and punctuation | @@ -52,7 +57,7 @@ The feature comes with several review commands: |**Adjust tone and style** |Modify the text to a desired tone and style |Several tone and style options are available: _Casual, Direct, Friendly, Confident, Professional_ -|**Translate** |Translate the text into another language |Several languages are available out-of-the-box, and the list can be customized: _English, Spanish, French, German, Chinese (Simplified), Japanese, Russian, Portuguese, Korean, Italian_ +|**Translate** |Translate the text into another language |Several languages are available out-of-the-box, and the list can be xref:tinymceai-review-plugin.adoc#customizing-translation-commands[customized]: _English, Spanish, French, German, Chinese (Simplified), Japanese, Russian, Portuguese, Korean, Italian_ |=== [[customizing-translation-commands]] @@ -85,7 +90,7 @@ tinymce.init({ [[related-features]] == Related Features -* xref:tinymceai-chat.adoc[AI Chat] – For interactive discussions with document analysis and context. -* xref:tinymceai-actions-plugin.adoc[AI Quick Actions] – For content transformation and batch processing. +* xref:tinymceai-chat.adoc[AI chat] – For interactive discussions with document analysis and context. +* xref:tinymceai-actions-plugin.adoc[Quick actions] – For content transformation and batch processing. * xref:tinymceai-reviews.adoc[Reviews API] – For API-level review functionality. * xref:tinymceai-introduction.adoc[Introduction] – Overview of all TinyMCE AI features. diff --git a/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc b/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc index 78df157bf8..f79950def5 100644 --- a/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc +++ b/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc @@ -1,6 +1,131 @@ -= TinyMCE AI with JWT Authentication (Node.js) += {pluginname} with JWT authentication (Node.js) Guide +:plugincode: tinymceai +:pluginname: TinyMCE AI +:navtitle: JWT Authentication setup for {pluginname} +:description: Guide on how to setup JWT Authentication for TinyMCE AI with {productname} +:keywords: jwt, authentication, tinymceai, ai, node.js -:navtitle: JWT Authentication (Node.js) -:description: JWT authentication setup for TinyMCE AI using Node.js -:description_short: JWT authentication with Node.js -:keywords: AI, JWT, authentication, Node.js, tinymceai +include::partial$auth/tinymceai/nodejs/intro-and-prerequisites.adoc[] + +include::partial$auth/tinymceai/nodejs/initial-project-setup.adoc[] + +== Setup + +=== Generate a Public/Private Key Pair + +include::partial$auth/tinymceai/jwt-setup-tinymceai.adoc[leveloffset=+2] + +=== Server Setup (jwt.js) + +In the root directory, copy and paste the server setup code into the `jwt.js` file. + +[source,javascript] +---- +const express = require('express'); // Sets up the web server. +const jwt = require('jsonwebtoken'); // Generates and signs JWTs. +const cors = require('cors'); // Allows cross-origin requests. +const path = require('path'); // Handles file paths. + +const app = express(); +app.use(cors()); + +// Your private key (Replace this with your actual key) +const privateKey = ` +-----BEGIN PRIVATE KEY----- +{Your private PKCS8 key goes here} +-----END PRIVATE KEY----- +`; + +app.use(express.static(path.join(__dirname, 'public'))); + +// JWT token generation endpoint +app.post('/jwt', (req, res) => { + const payload = { + aud: 'no-api-key', // Replace with your actual API key + sub: 'user-id', // Replace with actual user identifier + iat: Math.floor(Date.now() / 1000), // Issue timestamp + exp: Math.floor(Date.now() / 1000) + (60 * 10), // Expiration time (10 minutes) + auth: { + ai: { + permissions: [ + 'ai:conversations:read', + 'ai:conversations:write', + 'ai:models:agent', + 'ai:actions:system:*', + 'ai:reviews:system:*' + ] + } + } + }; + + try { + // Tokens are signed with the RS256 algorithm using your private key + const token = jwt.sign(payload, privateKey, { algorithm: 'RS256' }); + // TinyMCE AI expects the token as a plain string, not JSON + res.send(token); + } catch (error) { + res.status(500).send('Failed to generate JWT token.'); + console.error(error.message); + } +}); + +const PORT = 3000; +app.listen(PORT, () => { + console.log(`Server running at http://localhost:${PORT}`); +}); +---- + +[NOTE] +==== +The JWT payload includes an `auth.ai.permissions` array that defines what AI features the user can access. Adjust these permissions based on your requirements. See xref:tinymceai-permissions.adoc[Permissions] for more details on available permissions. +==== + +=== Web Page (public/index.html) + +Inside the `public` folder where you created the `index.html` file add the HTML setup code. + +[source,html] +---- + + + + TinyMCE with TinyMCE AI + + + + +

TinyMCE AI Demo

+ + + +---- + +include::partial$auth/tinymceai/nodejs/configuration-steps.adoc[] + +[NOTE] +==== +When you run the project, you should see: + +* The {productname} editor +* AI feature buttons in the toolbar (`showai`, `aiquickactions`, `aireview`) +==== diff --git a/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc b/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc index 0e7a4027ba..6219a0f005 100644 --- a/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc +++ b/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc @@ -1,6 +1,133 @@ -= TinyMCE AI with JWT Authentication (PHP) += {pluginname} with JWT authentication (PHP) Guide +:navtitle: JWT Authentication setup for TinyMCE AI +:description: Guide on how to setup JWT Authentication for TinyMCE AI with {productname} +:keywords: jwt, authentication, tinymceai, ai, php +:pluginname: TinyMCE AI +:plugincode: tinymceai -:navtitle: JWT Authentication (PHP) -:description: JWT authentication setup for TinyMCE AI using PHP -:description_short: JWT authentication with PHP -:keywords: AI, JWT, authentication, PHP, tinymceai +include::partial$auth/tinymceai/php/intro-and-prerequisites.adoc[] + +include::partial$auth/tinymceai/php/initial-project-setup.adoc[] + +== Setup + +=== Generate a Public/Private Key Pair + +include::partial$auth/tinymceai/jwt-setup-tinymceai.adoc[leveloffset=+2] + +=== Server Setup (jwt.php) + +In the root directory, copy and paste the server setup code into the `jwt.php` file. + +[source,php] +---- + "no-api-key", // Replace with your actual API key + "sub" => "user-id", // Replace with actual user identifier + "iat" => time(), // Issue timestamp + "exp" => time() + 60 * 10, // Expiration time (10 minutes) + "auth" => array( + "ai" => array( + "permissions" => array( + "ai:conversations:read", + "ai:conversations:write", + "ai:models:agent", + "ai:actions:system:*", + "ai:reviews:system:*" + ) + ) + ) +); + +try { + // Tokens are signed with the RS256 algorithm using your private key + $privateKey = <<getMessage()); +} +?> +---- + +[NOTE] +==== +The JWT payload includes an `auth.ai.permissions` array that defines what AI features the user can access. Adjust these permissions based on your requirements. See xref:tinymceai-permissions.adoc[Permissions] for more details on available permissions. +==== + +=== Web Page Setup (index.html) + +Inside the root directory where you created the `index.html` file add the HTML setup code. + +[source,html] +---- + + + + TinyMCE with TinyMCE AI + + + + +

TinyMCE AI Demo

+ + + +---- + +include::partial$auth/tinymceai/php/configuration-steps.adoc[] + +[NOTE] +==== +When you run the project, you should see: +* The {productname} editor +* AI feature buttons in the toolbar (showai, aiquickactions, aireview) +==== diff --git a/modules/ROOT/pages/tinymceai.adoc b/modules/ROOT/pages/tinymceai.adoc index 681d72e8e8..1b76b4f370 100644 --- a/modules/ROOT/pages/tinymceai.adoc +++ b/modules/ROOT/pages/tinymceai.adoc @@ -77,3 +77,38 @@ include::partial$events/{plugincode}-events.adoc[] The {pluginname} plugin provides the following APIs. include::partial$plugin-apis/{plugincode}-apis.adoc[] + +[[known-issues]] +== Known issues and caveats + +The {pluginname} plugin has the following known issues and caveats: + +=== General HTML Support + +{pluginname} may not work correctly when General HTML Support for block elements is enabled. This issue will be addressed in future updates. In the meantime, we recommend avoiding configurations that may cause problems. + +=== Issues with tables + +We are aware of certain glitches that may occur when the AI modifies complex tables or layout tables. To prevent data loss, please ensure that the content around these structures remains intact when using {pluginname} tools, while our team investigates the causes and potential solutions to this issue. + +=== Editor context and multiple editor handling + +While it's possible to use {pluginname} with multiple editors in an editor context, only the first editor registered in the context will currently be able to interact with AI tools and benefit from the content suggestions made by the AI. As our team works on resolving this issue, we recommend using standalone editor instances with {pluginname}. + +=== Inline image processing issues + +Inline images may not be processed correctly by commands within AI review. A solution is currently under development. + +=== Quick actions and content markers issues + +Applying quick action responses may result in the loss of Comments and Suggested Edits suggestion markers. This issue will be addressed in a future update. + +=== Limited interactivity in Chat history + +The interactivity of historical AI chat conversations can become limited over time. + +=== Issues with specific AI models + +Some AI models may occasionally return empty responses. If this occurs, we recommend sending a follow-up message asking the Assistant to complete the previous request, or starting a new conversation. + +NOTE: If you wish to stay informed about updates or discuss {pluginname} possibilities, please reach out to us. diff --git a/modules/ROOT/partials/auth/tinymceai/jwt-setup-tinymceai.adoc b/modules/ROOT/partials/auth/tinymceai/jwt-setup-tinymceai.adoc new file mode 100644 index 0000000000..5be621d83f --- /dev/null +++ b/modules/ROOT/partials/auth/tinymceai/jwt-setup-tinymceai.adoc @@ -0,0 +1,91 @@ +[[setting-up-jwt-authentication]] +== Setting up JWT authentication + +To set up JSON Web Token (JWT) authentication for {productname} {pluginname}: + +. Add a public key to your {accountpage}, link:https://www.tiny.cloud/auth/login/[login]. +. Set up a JSON Web Token (JWT) Provider endpoint via link:{accountjwturl}[{accountpage} - JWT Keys] +. Configure your {productname} to use the JWT endpoint. + +include::partial$auth/private-public-key-pairs-for-tiny-cloud-services.adoc[] + +[[set-up-a-json-web-token-jwt-endpoint]] +== Set up a JSON Web Token (JWT) endpoint + +include::partial$auth/how-jwts-are-used.adoc[] + +=== JWT endpoint requirements + +A JSON Web Token (JWT) endpoint for {pluginname} requires: + +* The endpoint or server accepts a JSON HTTP POST request. +* User authentication - A method of verifying the user, and that they should have access to the {pluginname}. +* The JWTs are generated (signed) using the _private_ key that pairs with the _public_ key provided to link:{accountjwturl}[{accountpage} - JWT Keys]. +* The endpoint or server produces a plain text response with the token. {pluginname} will submit the token with requests to the AI service. + +[NOTE] +==== +Unlike some other TinyMCE plugins, {pluginname} expects the token as a plain text string, not a JSON object. Make sure your endpoint returns the token directly as text. +==== + +=== Required JWT claims for {pluginname} + +JSON Web Tokens produced by the JWT endpoint must include the following claims: + +`+aud+` _(required)_:: +*Type:* `+String+` ++ +The `aud` is a case-sensitive string that must match a valid API key that has the {pluginname} plugin enabled. + +`+sub+` _(required)_:: +*Type:* `+String+` ++ +The `sub` claim identifies the user. This should be a unique identifier for the user making the request. + +`+iat+` _(required)_:: +*Type:* `+Number+` ++ +The `iat` represents the issue timestamp, specified as the number of seconds. For example, to set the issue time to the current timestamp, calculate the issue time as the current timestamp divided by 1000. + +.Example +[source,json] +---- +iat: Math.floor(Date.now() / 1000), // Issue timestamp +---- + +`+exp+` _(required)_:: +*Type:* `+Number+` ++ +The `exp` represents the expiration timestamp, specified as the number of seconds. For example, to set a validity period of 10 minutes, calculate the expiration time as the current timestamp plus 600 seconds. + +.Example +[source,json] +---- +exp: Math.floor(Date.now() / 1000) + (60 * 10) // Expiration time (10 minutes) +---- + +`+auth+` _(required)_:: +*Type:* `+Object+` ++ +The `auth` object contains AI-specific permissions that control which features the user can access. + +.Example +[source,json] +---- +auth: { + ai: { + permissions: [ + "ai:conversations:read", + "ai:conversations:write", + "ai:models:agent", + "ai:actions:system:*", + "ai:reviews:system:*" + ] + } +} +---- + +[NOTE] +==== +See xref:tinymceai-permissions.adoc[Permissions] for a complete list of available permissions and best practices for configuring user access. +==== diff --git a/modules/ROOT/partials/auth/tinymceai/nodejs/configuration-steps.adoc b/modules/ROOT/partials/auth/tinymceai/nodejs/configuration-steps.adoc new file mode 100644 index 0000000000..08e6fdb050 --- /dev/null +++ b/modules/ROOT/partials/auth/tinymceai/nodejs/configuration-steps.adoc @@ -0,0 +1,31 @@ +== Configuration Steps + +=== Add Your API Key + +* Replace `no-api-key` in both files with your actual {productname} API key +* The API key should be the same in both the HTML script source and the JWT payload + +=== Add Your Private Key + +* Replace the private key placeholder in `jwt.js` with your actual private key +* Make sure it's in `PKCS8` format +* Keep this key secure and never share it publicly + +=== Configure AI Permissions + +* Adjust the `auth.ai.permissions` array in the JWT payload based on your requirements +* See xref:tinymceai-permissions.adoc[Permissions] for available permissions and best practices + +=== Running Your Project + +. Start the server: ++ +[source,bash] +---- +node jwt.js +---- + +. Open your browser to: `http://localhost:3000` +. You should see: +* The {productname} editor +* AI feature buttons in the toolbar (showai, aiquickactions, aireview) diff --git a/modules/ROOT/partials/auth/tinymceai/nodejs/initial-project-setup.adoc b/modules/ROOT/partials/auth/tinymceai/nodejs/initial-project-setup.adoc new file mode 100644 index 0000000000..bcac3b711a --- /dev/null +++ b/modules/ROOT/partials/auth/tinymceai/nodejs/initial-project-setup.adoc @@ -0,0 +1,39 @@ +== Quick Start Guide + +=== Project Setup + +[source,bash] +---- +# Create and enter project directory +mkdir tinymce-my-app +cd tinymce-my-app + +# Initialize project +npm init -y + +# Install required packages +npm install express cors jsonwebtoken +---- + +Verify that the `package.json` file now includes the required dependencies. + +=== Create Project Structure + +[source,bash] +---- +# Create the public folder for your web files +mkdir public +touch public/index.html +touch jwt.js +---- + +Your project should look like this: + +[source] +---- +/tinymce-my-app + /public + index.html (TinyMCE webpage) + jwt.js (Server code) + package.json (Project configuration) +---- diff --git a/modules/ROOT/partials/auth/tinymceai/nodejs/intro-and-prerequisites.adoc b/modules/ROOT/partials/auth/tinymceai/nodejs/intro-and-prerequisites.adoc new file mode 100644 index 0000000000..38c4dd2627 --- /dev/null +++ b/modules/ROOT/partials/auth/tinymceai/nodejs/intro-and-prerequisites.adoc @@ -0,0 +1,31 @@ +== Introduction + +{pluginname} requires setting up JSON Web Token (JWT) authentication to maintain control over AI feature access. A JWT endpoint generates and provides authorization tokens that verify users are authorized to use AI features, preventing unauthorized access. As a standard web services authorization solution, JWT is documented extensively at link:https://jwt.io/[https://jwt.io/]. + +This guide provides a comprehensive walkthrough for integrating {pluginname} with {productname}, including {pluginname} functionality, by using a Node.js server for JWT token generation. It covers project setup, server configuration, and {productname} customization. + +=== What You'll Build + +Before diving into the technical details, here's what you'll achieve with this guide: + +* A working {productname} editor running the {pluginname} plugin +* A secure authentication system using JWT tokens +* A simple Node.js server to handle the authentication + +[TIP] +==== +This guide is designed for developers new to JWT authentication and {productname} integration. +==== + +=== Prerequisites + +Before starting, ensure you have: + +* Node.js installed on your computer (to check, run `node -v` in your terminal) +* A {productname} API key with TinyMCE AI enabled (get one from link:https://www.tiny.cloud/signup[TinyMCE's website]) +* Basic familiarity with the command line + +[IMPORTANT] +==== +Make sure you have your API key ready before starting. You'll need it for both the server and client configuration. +==== diff --git a/modules/ROOT/partials/auth/tinymceai/php/configuration-steps.adoc b/modules/ROOT/partials/auth/tinymceai/php/configuration-steps.adoc new file mode 100644 index 0000000000..53aa83f2ea --- /dev/null +++ b/modules/ROOT/partials/auth/tinymceai/php/configuration-steps.adoc @@ -0,0 +1,31 @@ +== Configuration Steps + +=== Add Your API Key + +* Replace `no-api-key` in both files with your actual {productname} API key +* The API key should be the same in both the HTML script source and the JWT payload + +=== Add Your Private Key + +* Replace the private key placeholder in `jwt.php` with your actual private key +* Make sure it's in `PKCS8` format +* Keep this key secure and never share it publicly + +=== Configure AI Permissions + +* Adjust the `auth.ai.permissions` array in the JWT payload based on your requirements +* See xref:tinymceai-permissions.adoc[Permissions] for available permissions and best practices + +=== Running Your Project + +. Start the server: ++ +[source,bash] +---- +php -S localhost:3000 +---- + +. Open your browser to: `http://localhost:3000` +. You should see: +* The {productname} editor +* AI feature buttons in the toolbar (showai, aiquickactions, aireview) diff --git a/modules/ROOT/partials/auth/tinymceai/php/initial-project-setup.adoc b/modules/ROOT/partials/auth/tinymceai/php/initial-project-setup.adoc new file mode 100644 index 0000000000..5240d90c8b --- /dev/null +++ b/modules/ROOT/partials/auth/tinymceai/php/initial-project-setup.adoc @@ -0,0 +1,53 @@ +== Update PHP Configuration File + +Use the following command to locate the PHP configuration file: + +[source,bash] +---- +php --ini +---- + +Open the configuration file in a text editor and ensure the following settings are enabled: + +[source,ini] +---- +extension=openssl +extension_dir='ext' +---- + +[TIP] +The path to the extension directory may vary depending on your system. + +== Quick Start Guide + +=== Project Setup + +[source,bash] +---- +# Create and enter project directory +mkdir tinymce-app +cd tinymce-app +# Initialize Composer +composer require firebase/php-jwt +---- + +=== Create Project Structure + +[source,bash] +---- +# Create the public folder for your web files +touch index.html +touch jwt.php +---- + +Your project should look like this: + +[source] +---- +/tinymce-app + index.html (TinyMCE webpage) + jwt.php (Server code) + composer.json + composer.lock + vendor +---- diff --git a/modules/ROOT/partials/auth/tinymceai/php/intro-and-prerequisites.adoc b/modules/ROOT/partials/auth/tinymceai/php/intro-and-prerequisites.adoc new file mode 100644 index 0000000000..ac5231353c --- /dev/null +++ b/modules/ROOT/partials/auth/tinymceai/php/intro-and-prerequisites.adoc @@ -0,0 +1,33 @@ +== Introduction + +{pluginname} requires setting up JSON Web Token (JWT) authentication to maintain control over AI feature access. A JWT endpoint generates and provides authorization tokens that verify users are authorized to use AI features, preventing unauthorized access. As a standard web services authorization solution, JWT is documented extensively at link:https://jwt.io/[https://jwt.io/]. + +This guide provides a comprehensive walkthrough for integrating {pluginname} with {productname}, including {pluginname} functionality, by using a PHP server for JWT token generation. It covers project setup, server configuration, and {productname} customization. + +=== What You'll Build + +Before diving into the technical details, here's what you'll achieve with this guide: + +* A working {productname} editor running the {pluginname} plugin +* A secure authentication system using JWT tokens +* A simple PHP server to handle the authentication + +[TIP] +==== +This guide is designed for developers new to JWT authentication and {productname} integration. +==== + +=== Prerequisites + +Before starting, ensure you have: + +* PHP installed on your computer (to check, run `php -v` in your terminal) +* OpenSSL installed on your computer (to check, run `openssl version` in your terminal) +* Composer installed on your computer (to check, run `composer -v` in your terminal) +* A {productname} API key with TinyMCE AI enabled (get one from link:https://www.tiny.cloud/signup[TinyMCE's website]) +* Basic familiarity with the command line + +[IMPORTANT] +==== +Make sure you have your API key ready before starting. You'll need it for both the server and client configuration. +==== diff --git a/modules/ROOT/partials/commands/tinymceai-cmds.adoc b/modules/ROOT/partials/commands/tinymceai-cmds.adoc index 50f73c0a6d..33104ed01f 100644 --- a/modules/ROOT/partials/commands/tinymceai-cmds.adoc +++ b/modules/ROOT/partials/commands/tinymceai-cmds.adoc @@ -1 +1,25 @@ -== TinyMCE AI Commands +[cols="1,2"] +|=== +|Command name |Description + +|`tinymceai-toggle-sidebar` |Toggle the AI sidebar interface visibility. Accepts an optional object parameter with `type` ('static' or 'floating') and optional `view` (e.g., 'chat', 'review', 'actions') to open a specific view. +|`TinyMCEAIDumpDiagnostics` |Download diagnostic information for troubleshooting purposes. +|=== + +.Examples +[source,js] +---- +// Toggle the AI sidebar +editor.execCommand('tinymceai-toggle-sidebar'); + +// Open the sidebar with a specific view (e.g., 'chat') +editor.execCommand('tinymceai-toggle-sidebar', false, { + type: 'static', + view: 'chat' +}); + +// Close the sidebar +editor.execCommand('tinymceai-toggle-sidebar', false, { + type: 'static' +}); +---- diff --git a/modules/ROOT/partials/configuration/tinymceai_token_provider.adoc b/modules/ROOT/partials/configuration/tinymceai_token_provider.adoc index 569783d92d..1d8d24131d 100644 --- a/modules/ROOT/partials/configuration/tinymceai_token_provider.adoc +++ b/modules/ROOT/partials/configuration/tinymceai_token_provider.adoc @@ -1,20 +1,33 @@ [[tinymceai-token-provider]] == `+tinymceai_token_provider+` - -*Type:* `+Function+` +*Type:* `+Function+` (`+() => Promise+`) *Default value:* `+undefined+` +*Description:* A function that returns a Promise resolving to a JWT token string for authenticating with the AI service. + === Example: using `+tinymceai_token_provider+` +[source,js] +---- +tinymce.init({ + selector: 'textarea', + plugins: 'tinymceai', + toolbar: 'showai aiquickactions aireview', + tinymceai_token_provider: () => Promise.resolve('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...') +}); +---- + +NOTE: In production, you should fetch the JWT token from your backend server rather than hardcoding it. For example: + [source,js] ---- tinymce.init({ selector: 'textarea', plugins: 'tinymceai', tinymceai_token_provider: function() { - // Token provider implementation + return fetch('/api/token').then(response => response.text()); } }); ---- diff --git a/modules/ROOT/partials/events/tinymceai-events.adoc b/modules/ROOT/partials/events/tinymceai-events.adoc index a2c8b6cd30..710b38c055 100644 --- a/modules/ROOT/partials/events/tinymceai-events.adoc +++ b/modules/ROOT/partials/events/tinymceai-events.adoc @@ -1 +1,15 @@ -== TinyMCE AI Events +[cols="1,2"] +|=== +|Event name |Description + +|`tinymceai-toggle-floating-sidebar` |Dispatched when the floating AI sidebar should be toggled. This event is used internally to control the visibility of the floating sidebar interface. +|=== + +.Example +[source,js] +---- +editor.on('tinymceai-toggle-floating-sidebar', function() { + // Handle the toggle floating sidebar event + console.log('Floating sidebar toggle requested'); +}); +---- diff --git a/modules/ROOT/partials/plugin-apis/tinymceai-apis.adoc b/modules/ROOT/partials/plugin-apis/tinymceai-apis.adoc index 0d47644b4c..84fa199c5f 100644 --- a/modules/ROOT/partials/plugin-apis/tinymceai-apis.adoc +++ b/modules/ROOT/partials/plugin-apis/tinymceai-apis.adoc @@ -1 +1 @@ -== TinyMCE AI APIs +todo: diff --git a/modules/ROOT/partials/toolbar-button-ids/tinymceai-toolbar-buttons.adoc b/modules/ROOT/partials/toolbar-button-ids/tinymceai-toolbar-buttons.adoc index f98991c1aa..51ea2a2cec 100644 --- a/modules/ROOT/partials/toolbar-button-ids/tinymceai-toolbar-buttons.adoc +++ b/modules/ROOT/partials/toolbar-button-ids/tinymceai-toolbar-buttons.adoc @@ -1,4 +1,30 @@ [cols="1,3",options="header"] |=== |Toolbar button identifier |Description + +|`tinymceai` |Main AI plugin button +|`tinymceai-conversations` |Conversations feature +|`tinymceai-actions` |Quick Actions feature +|`tinymceai-reviews` |Reviews feature +|`ask-ai` |Quick Actions +|`explain` |Quick Actions +|`summarize` |Quick Actions +|`highlight-key-points` |Quick Actions +|`improve-writing` |Quick Actions +|`continue` |Quick Actions +|`fix-grammar` |Quick Actions +|`make-shorter` |Quick Actions +|`make-longer` |Quick Actions +|`make-tone-casual` |Quick Actions +|`make-tone-direct` |Quick Actions +|`make-tone-friendly` |Quick Actions +|`make-tone-confident` |Quick Actions +|`make-tone-professional` |Quick Actions +|`translate-to-english` |Quick Actions +|`translate-to-chinese` |Quick Actions +|`translate-to-french` |Quick Actions +|`translate-to-german` |Quick Actions +|`translate-to-italian` |Quick Actions +|`translate-to-portuguese` |Quick Actions +|`translate-to-russian` |Quick Actions |=== From 7075b22d9537181a22b543bf91521032802e7235 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Tue, 10 Feb 2026 09:10:13 +1000 Subject: [PATCH 04/10] DOC-3356: Update premium plugins link to point to intro page. --- modules/ROOT/partials/index-pages/premium-plugins.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/partials/index-pages/premium-plugins.adoc b/modules/ROOT/partials/index-pages/premium-plugins.adoc index 6afb85b3f0..90b06e5a2a 100644 --- a/modules/ROOT/partials/index-pages/premium-plugins.adoc +++ b/modules/ROOT/partials/index-pages/premium-plugins.adoc @@ -202,7 +202,7 @@ Insert a simple Table of Contents into the {productname} editor. a| [.lead] -xref:tinymceai.adoc[TinyMCE AI] +xref:tinymceai-introduction.adoc[TinyMCE AI] AI-powered features for {productname} including AI chat, AI review, and quick actions. From 9106ce6491c4297607063584010d7cf9a58305a9 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Wed, 11 Feb 2026 13:44:27 +1000 Subject: [PATCH 05/10] DOC-3358: Restructure JWT guides, fix broken partials across JWT guides. --- ...ymceai-with-jwt-authentication-nodejs.adoc | 96 ++++++++++++++-- ...tinymceai-with-jwt-authentication-php.adoc | 107 ++++++++++++++++-- .../ROOT/partials/auth/how-jwts-are-used.adoc | 29 +++++ .../auth/tinymceai/jwt-setup-tinymceai.adoc | 7 +- 4 files changed, 214 insertions(+), 25 deletions(-) diff --git a/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc b/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc index f79950def5..8eab84fc87 100644 --- a/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc +++ b/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc @@ -9,11 +9,90 @@ include::partial$auth/tinymceai/nodejs/intro-and-prerequisites.adoc[] include::partial$auth/tinymceai/nodejs/initial-project-setup.adoc[] -== Setup +== Generate a Public/Private Key Pair -=== Generate a Public/Private Key Pair +include::partial$auth/private-public-key-pairs-for-tiny-cloud-services.adoc[] -include::partial$auth/tinymceai/jwt-setup-tinymceai.adoc[leveloffset=+2] +== JWT Configuration Requirements + +This section explains what needs to be configured for JWT authentication, whether you're using a managed service (such as AWS or Azure JWT services) or setting up a manual endpoint. + +include::partial$auth/how-jwts-are-used.adoc[] + +=== JWT endpoint requirements + +A JSON Web Token (JWT) endpoint for {pluginname} requires: + +* The endpoint or server accepts a JSON HTTP POST request. +* User authentication - A method of verifying the user, and that they should have access to the {pluginname}. +* The JWTs are generated (signed) using the _private_ key that pairs with the _public_ key provided to link:{accountjwturl}[{accountpage} - JWT Keys]. +* The endpoint or server produces a JSON response with the token. {pluginname} will submit the token with requests to the AI service. + +=== Required JWT claims for {pluginname} + +JSON Web Tokens produced by the JWT endpoint must include the following claims: + +`+aud+` _(required)_:: +*Type:* `+String+` ++ +The `aud` is a case-sensitive string that must match a valid API key that has the {pluginname} plugin enabled. + +`+sub+` _(required)_:: +*Type:* `+String+` ++ +The `sub` claim identifies the user. This should be a unique identifier for the user making the request. + +`+iat+` _(required)_:: +*Type:* `+Number+` ++ +The `iat` represents the issue timestamp, specified as the number of seconds. For example, to set the issue time to the current timestamp, calculate the issue time as the current timestamp divided by 1000. + +.Example +[source,json] +---- +iat: Math.floor(Date.now() / 1000), // Issue timestamp +---- + +`+exp+` _(required)_:: +*Type:* `+Number+` ++ +The `exp` represents the expiration timestamp, specified as the number of seconds. For example, to set a validity period of 10 minutes, calculate the expiration time as the current timestamp plus 600 seconds. + +.Example +[source,json] +---- +exp: Math.floor(Date.now() / 1000) + (60 * 10) // Expiration time (10 minutes) +---- + +`+auth+` _(required)_:: +*Type:* `+Object+` ++ +The `auth` object contains AI-specific permissions that control which features the user can access. + +.Example +[source,json] +---- +auth: { + ai: { + permissions: [ + "ai:conversations:read", + "ai:conversations:write", + "ai:models:agent", + "ai:actions:system:*", + "ai:reviews:system:*" + ] + } +} +---- + +[NOTE] +==== +See xref:tinymceai-permissions.adoc[Permissions] for a complete list of available permissions and best practices for configuring user access. +==== + +== Set up JWT Endpoint + +The following section shows how to create a JWT endpoint manually. If you're using a managed JWT service (such as AWS or Azure), configure it according to the requirements above and skip to the xref:#configure-tinymce[Configure TinyMCE] section. === Server Setup (jwt.js) @@ -61,8 +140,7 @@ app.post('/jwt', (req, res) => { try { // Tokens are signed with the RS256 algorithm using your private key const token = jwt.sign(payload, privateKey, { algorithm: 'RS256' }); - // TinyMCE AI expects the token as a plain string, not JSON - res.send(token); + res.json({ token }); } catch (error) { res.status(500).send('Failed to generate JWT token.'); console.error(error.message); @@ -80,6 +158,9 @@ app.listen(PORT, () => { The JWT payload includes an `auth.ai.permissions` array that defines what AI features the user can access. Adjust these permissions based on your requirements. See xref:tinymceai-permissions.adoc[Permissions] for more details on available permissions. ==== +== Configure TinyMCE + +[[configure-tinymce]] === Web Page (public/index.html) Inside the `public` folder where you created the `index.html` file add the HTML setup code. @@ -101,12 +182,11 @@ Inside the `public` folder where you created the `index.html` file add the HTML plugins: 'tinymceai', toolbar: 'showai aiquickactions aireview', // tinymceai_token_provider fetches a token from the `/jwt` endpoint. - // TinyMCE AI expects the response to be a plain text token string. tinymceai_token_provider: () => { return fetch('http://localhost:3000/jwt', { method: 'POST', headers: { 'Content-Type': 'application/json' }, - }).then(response => response.text()); + }).then(response => response.json()); }, }); @@ -120,6 +200,8 @@ Inside the `public` folder where you created the `index.html` file add the HTML ---- +== Configuration and Running + include::partial$auth/tinymceai/nodejs/configuration-steps.adoc[] [NOTE] diff --git a/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc b/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc index 6219a0f005..3c35de35b9 100644 --- a/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc +++ b/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc @@ -9,11 +9,90 @@ include::partial$auth/tinymceai/php/intro-and-prerequisites.adoc[] include::partial$auth/tinymceai/php/initial-project-setup.adoc[] -== Setup +== Generate a Public/Private Key Pair -=== Generate a Public/Private Key Pair +include::partial$auth/private-public-key-pairs-for-tiny-cloud-services.adoc[] -include::partial$auth/tinymceai/jwt-setup-tinymceai.adoc[leveloffset=+2] +== JWT Configuration Requirements + +This section explains what needs to be configured for JWT authentication, whether you're using a managed service (such as AWS or Azure JWT services) or setting up a manual endpoint. + +include::partial$auth/how-jwts-are-used.adoc[] + +=== JWT endpoint requirements + +A JSON Web Token (JWT) endpoint for {pluginname} requires: + +* The endpoint or server accepts a JSON HTTP POST request. +* User authentication - A method of verifying the user, and that they should have access to the {pluginname}. +* The JWTs are generated (signed) using the _private_ key that pairs with the _public_ key provided to link:{accountjwturl}[{accountpage} - JWT Keys]. +* The endpoint or server produces a JSON response with the token. {pluginname} will submit the token with requests to the AI service. + +=== Required JWT claims for {pluginname} + +JSON Web Tokens produced by the JWT endpoint must include the following claims: + +`+aud+` _(required)_:: +*Type:* `+String+` ++ +The `aud` is a case-sensitive string that must match a valid API key that has the {pluginname} plugin enabled. + +`+sub+` _(required)_:: +*Type:* `+String+` ++ +The `sub` claim identifies the user. This should be a unique identifier for the user making the request. + +`+iat+` _(required)_:: +*Type:* `+Number+` ++ +The `iat` represents the issue timestamp, specified as the number of seconds. For example, to set the issue time to the current timestamp, calculate the issue time as the current timestamp divided by 1000. + +.Example +[source,json] +---- +iat: Math.floor(Date.now() / 1000), // Issue timestamp +---- + +`+exp+` _(required)_:: +*Type:* `+Number+` ++ +The `exp` represents the expiration timestamp, specified as the number of seconds. For example, to set a validity period of 10 minutes, calculate the expiration time as the current timestamp plus 600 seconds. + +.Example +[source,json] +---- +exp: Math.floor(Date.now() / 1000) + (60 * 10) // Expiration time (10 minutes) +---- + +`+auth+` _(required)_:: +*Type:* `+Object+` ++ +The `auth` object contains AI-specific permissions that control which features the user can access. + +.Example +[source,json] +---- +auth: { + ai: { + permissions: [ + "ai:conversations:read", + "ai:conversations:write", + "ai:models:agent", + "ai:actions:system:*", + "ai:reviews:system:*" + ] + } +} +---- + +[NOTE] +==== +See xref:tinymceai-permissions.adoc[Permissions] for a complete list of available permissions and best practices for configuring user access. +==== + +== Set up JWT Endpoint + +The following section shows how to create a JWT endpoint manually. If you're using a managed JWT service (such as AWS or Azure), configure it according to the requirements above and skip to the xref:#configure-tinymce[Configure TinyMCE] section. === Server Setup (jwt.php) @@ -27,8 +106,8 @@ use \Firebase\JWT\JWT; function fatalError($message) { http_response_code(500); - header('Content-Type: text/plain'); - die("JWT auth failed: " . $message); + header('Content-Type: application/json'); + die(json_encode(array("message" => "JWT auth failed: " . $message))); } // Check for OpenSSL extension @@ -68,10 +147,9 @@ try { EOD; $token = JWT::encode($payload, $privateKey, 'RS256'); - // TinyMCE AI expects the token as a plain text string, not JSON http_response_code(200); - header('Content-Type: text/plain'); - echo $token; + header('Content-Type: application/json'); + echo json_encode(array("token" => $token)); } catch (Exception $e) { fatalError($e->getMessage()); } @@ -83,7 +161,10 @@ try { The JWT payload includes an `auth.ai.permissions` array that defines what AI features the user can access. Adjust these permissions based on your requirements. See xref:tinymceai-permissions.adoc[Permissions] for more details on available permissions. ==== -=== Web Page Setup (index.html) +== Configure TinyMCE + +[[configure-tinymce]] +=== Web Page (index.html) Inside the root directory where you created the `index.html` file add the HTML setup code. @@ -104,12 +185,11 @@ Inside the root directory where you created the `index.html` file add the HTML s plugins: 'tinymceai', toolbar: 'showai aiquickactions aireview', // tinymceai_token_provider fetches a token from the `/jwt.php` endpoint. - // TinyMCE AI expects the response to be a plain text token string. tinymceai_token_provider: () => { return fetch('http://localhost:3000/jwt.php', { method: 'POST', headers: { 'Content-Type': 'application/json' }, - }).then(response => response.text()); + }).then(response => response.json()); }, }); @@ -123,11 +203,14 @@ Inside the root directory where you created the `index.html` file add the HTML s ---- +== Configuration and Running + include::partial$auth/tinymceai/php/configuration-steps.adoc[] [NOTE] ==== When you run the project, you should see: + * The {productname} editor -* AI feature buttons in the toolbar (showai, aiquickactions, aireview) +* AI feature buttons in the toolbar (`showai`, `aiquickactions`, `aireview`) ==== diff --git a/modules/ROOT/partials/auth/how-jwts-are-used.adoc b/modules/ROOT/partials/auth/how-jwts-are-used.adoc index 5b50ac1b35..811b1a5e6f 100644 --- a/modules/ROOT/partials/auth/how-jwts-are-used.adoc +++ b/modules/ROOT/partials/auth/how-jwts-are-used.adoc @@ -11,4 +11,33 @@ ifeval::["{plugincode}" == "tinydrive"] . If your JWT endpoint authorizes the user, your JWT endpoint will send a JWT to {pluginname}, certifying the user. . When the user makes a request (such as adding or deleting a file), the JWT will be sent with the request to show that the user is authorized. This JWT is verified using the _public_ key stored on the {cloudname} Server. . The {cloudname} Server sends a response, indicating that content submission was successful (or unauthorized if necessary). +endif::[] + +ifeval::["{plugincode}" == "tinymceai"] +. {pluginname} requests a signed JWT on behalf of the user. +. If your JWT endpoint authorizes the user, your JWT endpoint will send a JWT to {pluginname}, certifying the user. +. The JWT includes a `sub` (subject) claim that identifies the user. This user identifier is used to lock down conversation history, AI-generated content, and other user-specific data to individual users, ensuring privacy and data isolation. +. When the user makes a request (such as starting a chat conversation, requesting AI actions, or submitting reviews), the JWT will be sent with the request to show that the user is authorized. This JWT is verified using the _public_ key stored on the AI service. +. The AI service sends a response, indicating that the request was successful (or unauthorized if necessary). +endif::[] + +ifeval::["{plugincode}" == "importword"] +. {pluginname} requests a signed JWT on behalf of the user. +. If your JWT endpoint authorizes the user, your JWT endpoint will send a JWT to {pluginname}, certifying the user. +. When the user makes a request (such as importing a document), the JWT will be sent with the request to show that the user is authorized. This JWT is verified using the _public_ key stored on the {pluginname} Server. +. The {pluginname} Server sends a response, indicating that content submission was successful (or unauthorized if necessary). +endif::[] + +ifeval::["{plugincode}" == "exportword"] +. {pluginname} requests a signed JWT on behalf of the user. +. If your JWT endpoint authorizes the user, your JWT endpoint will send a JWT to {pluginname}, certifying the user. +. When the user makes a request (such as exporting a document), the JWT will be sent with the request to show that the user is authorized. This JWT is verified using the _public_ key stored on the {pluginname} Server. +. The {pluginname} Server sends a response, indicating that content submission was successful (or unauthorized if necessary). +endif::[] + +ifeval::["{plugincode}" == "exportpdf"] +. {pluginname} requests a signed JWT on behalf of the user. +. If your JWT endpoint authorizes the user, your JWT endpoint will send a JWT to {pluginname}, certifying the user. +. When the user makes a request (such as exporting a document), the JWT will be sent with the request to show that the user is authorized. This JWT is verified using the _public_ key stored on the {pluginname} Server. +. The {pluginname} Server sends a response, indicating that content submission was successful (or unauthorized if necessary). endif::[] \ No newline at end of file diff --git a/modules/ROOT/partials/auth/tinymceai/jwt-setup-tinymceai.adoc b/modules/ROOT/partials/auth/tinymceai/jwt-setup-tinymceai.adoc index 5be621d83f..b274431103 100644 --- a/modules/ROOT/partials/auth/tinymceai/jwt-setup-tinymceai.adoc +++ b/modules/ROOT/partials/auth/tinymceai/jwt-setup-tinymceai.adoc @@ -21,12 +21,7 @@ A JSON Web Token (JWT) endpoint for {pluginname} requires: * The endpoint or server accepts a JSON HTTP POST request. * User authentication - A method of verifying the user, and that they should have access to the {pluginname}. * The JWTs are generated (signed) using the _private_ key that pairs with the _public_ key provided to link:{accountjwturl}[{accountpage} - JWT Keys]. -* The endpoint or server produces a plain text response with the token. {pluginname} will submit the token with requests to the AI service. - -[NOTE] -==== -Unlike some other TinyMCE plugins, {pluginname} expects the token as a plain text string, not a JSON object. Make sure your endpoint returns the token directly as text. -==== +* The endpoint or server produces a JSON response with the token. {pluginname} will submit the token with requests to the AI service. === Required JWT claims for {pluginname} From 7bb949474064a56214a6d0743076fb10e7e485d9 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 16 Feb 2026 14:43:21 +1000 Subject: [PATCH 06/10] DOC-3356: Suggested improvements, copy edits and initial review changes. --- .../ROOT/pages/tinymceai-actions-plugin.adoc | 81 ++-- .../ROOT/pages/tinymceai-api-quick-start.adoc | 8 +- modules/ROOT/pages/tinymceai-chat.adoc | 173 +++----- .../ROOT/pages/tinymceai-conversations.adoc | 12 +- .../pages/tinymceai-integration-options.adoc | 6 +- modules/ROOT/pages/tinymceai-integration.adoc | 372 ++++-------------- .../ROOT/pages/tinymceai-introduction.adoc | 8 +- modules/ROOT/pages/tinymceai-limits.adoc | 4 +- modules/ROOT/pages/tinymceai-models.adoc | 16 +- .../ROOT/pages/tinymceai-review-plugin.adoc | 44 +-- modules/ROOT/pages/tinymceai-reviews.adoc | 10 +- modules/ROOT/pages/tinymceai-streaming.adoc | 4 +- ...ymceai-with-jwt-authentication-nodejs.adoc | 16 +- ...tinymceai-with-jwt-authentication-php.adoc | 16 +- modules/ROOT/pages/tinymceai.adoc | 21 +- ...lic-key-pairs-for-tiny-cloud-services.adoc | 18 +- .../auth/tinymceai/jwt-setup-tinymceai.adoc | 4 +- .../tinymceai/nodejs/configuration-steps.adoc | 16 +- .../nodejs/initial-project-setup.adoc | 6 +- .../nodejs/intro-and-prerequisites.adoc | 8 +- .../tinymceai/php/configuration-steps.adoc | 16 +- .../tinymceai/php/initial-project-setup.adoc | 6 +- .../php/intro-and-prerequisites.adoc | 12 +- .../partials/commands/tinymceai-cmds.adoc | 19 +- .../configuration/tinymceai_document_id.adoc | 31 ++ .../tinymceai_token_provider.adoc | 2 +- 26 files changed, 326 insertions(+), 603 deletions(-) create mode 100644 modules/ROOT/partials/configuration/tinymceai_document_id.adoc diff --git a/modules/ROOT/pages/tinymceai-actions-plugin.adoc b/modules/ROOT/pages/tinymceai-actions-plugin.adoc index cdc30a7e9e..c5301d3776 100644 --- a/modules/ROOT/pages/tinymceai-actions-plugin.adoc +++ b/modules/ROOT/pages/tinymceai-actions-plugin.adoc @@ -5,7 +5,7 @@ :description_short: quick actions feature :keywords: AI, quick actions, actions, tinymceai -Quick actions streamline routine content transformations by offering one-click AI-powered suggestions directly within the editor. You can also ask questions about your selected text in AI chat to get instant AI insights and analysis. This feature enhances speed, relevance, and usability, particularly for repeatable or simple tasks. The feature comes with an easy-to-use window interface but can also act as a conversation starter with the xref:tinymceai-chat.adoc[Chat]. +Quick actions streamline routine content transformations by offering one-click AI-powered suggestions directly within the editor. This feature enhances speed, relevance, and usability, particularly for repeatable or simple tasks. The feature comes with an easy-to-use window interface but can also act as a conversation starter with the xref:tinymceai-chat.adoc[Chat]. [[demo]] == Demo @@ -15,22 +15,29 @@ liveDemo::tinymceai[] [[overview]] == Overview -Actions are fast, stateless operations that transform content directly. Unlike Reviews that provide suggestions, Actions immediately modify your content based on the selected operation. +Actions are fast, stateless operations that transform content directly. Unlike Reviews that provide suggestions, Actions immediately modify content based on the selected operation. -**When to use Actions vs Reviews:** Use Actions when you need to transform specific text content (fix grammar, translate, adjust tone). Use Reviews when you need to analyze entire documents for quality improvements and get suggestions without automatically changing the content. +**When to use Actions vs Reviews:** Use Actions when transforming a selection or small section of text (fix grammar, translate, adjust tone). Use Reviews when analyzing entire documents for quality improvements and getting suggestions without automatically changing the content. image::https://placehold.net/default.png[TinyMCE AI quick actions showing AI-powered suggestions and Q&A functionality] [[integration]] == Integration -To start using the Quick Actions feature, first load the TinyMCE AI plugin in your editor configuration. xref:tinymceai-integration.adoc[Learn more about installing and enabling AI features]. +To start using the Quick Actions feature, first load the TinyMCE AI plugin in the editor configuration. xref:tinymceai-integration.adoc[Learn more about installing and enabling AI features]. -Then, you can add the menu that opens the list of Quick Actions (`tinymceai-actions`) image:https://placehold.net/default.png[Quick Actions icon,24px] to your main toolbar and/or balloon toolbar configurations. To learn more about toolbar configuration, refer to the xref:toolbar-configuration-options.adoc[toolbar configuration] guide. +Then, add the menu that opens the list of Quick Actions (`tinymceai-actions`) image:https://placehold.net/default.png[Quick Actions icon,24px] to the main toolbar and/or context toolbar (selection toolbar) configurations. + +[NOTE] +==== +AI features are added to the selection toolbar by default when the plugin is enabled. The `tinymceai_context_toolbar` configuration option controls which AI features appear in the selection toolbar. Configure it to show specific features, for example: `tinymceai_context_toolbar: 'showai aiquickactions aireview'` or `tinymceai_context_toolbar: 'showai aireview'` to show only certain features. +==== + +To learn more about toolbar configuration, refer to the xref:toolbar-configuration-options.adoc[toolbar configuration] guide. image::https://placehold.net/default.png[TinyMCE AI Quick Actions dropdown in the toolbar] -Finally, you can also add individual Quick Actions to the toolbar as shortcuts for even easier access. For example, you can add the `ask-ai` image:https://placehold.net/default.png[Ask AI icon,24px] button, or the `improve-writing` image:https://placehold.net/default.png[Improve Writing icon,24px] button (find it in the demo above). You can add whole categories to the toolbar, too. xref:tinymceai-actions-plugin.adoc#default-actions[Learn more about available actions]. +Finally, individual Quick Actions can also be added to the toolbar as shortcuts for even easier access. For example, add the `ask-ai` image:https://placehold.net/default.png[Ask AI icon,24px] button, or the `improve-writing` image:https://placehold.net/default.png[Improve Writing icon,24px] button (find it in the demo above). Whole categories can be added to the toolbar, too. xref:tinymceai-actions-plugin.adoc#default-actions[Learn more about available actions]. The final example configuration looks as follows: @@ -69,18 +76,18 @@ tinymce.init({ There are two types of actions available in the quick actions feature: -* Some actions, for instance, "Ask AI" or "Summarize", lead to the xref:tinymceai-chat.adoc[Chat] interface with selected text added as context. The former will just open the Chat and allow you to start typing your message. The latter, however, will not only open the Chat but also start the conversation for your current editor selection right away, and expect a summary of that selection from the AI. +* Chat actions, such as "Explain" or "Summarize", open the xref:tinymceai-chat.adoc[Chat] interface with the selected text added as context and automatically start the conversation with a pre-filled prompt. Actions like "Ask AI" open the Chat interface and allow users to start typing their message. -* Executing other actions like "Continue writing" or "Make shorter" will open the window interface conveniently right next to your selection and present the answers from the AI for you to accept or reject them. +* Preview actions, such as "Continue writing", "Make shorter", "Improve writing", or "Fix grammar", display the AI response in a preview interface where users can review and accept or reject the suggested changes. -You can define the behavior of each action when you xref:tinymceai-actions-plugin.adoc#custom-actions[create custom ones]. +The behavior of each action can be defined when xref:tinymceai-actions-plugin.adoc#custom-actions[creating custom ones]. [[default-actions]] == Default Actions -By default, the Quick Actions feature includes several built-in actions that speed up the content editing process. All Quick Actions can be accessed through the menu button image:https://placehold.net/default.png[Quick Actions icon,24px] (`tinymceai-actions`) but also individually when handpicked by the integrator in the xref:toolbar-configuration-options.adoc[editor toolbar configuration]. You can add the whole action categories to the toolbar too. +By default, the Quick Actions feature includes several built-in actions that speed up the content editing process. All Quick Actions can be accessed through the menu button image:https://placehold.net/default.png[Quick Actions icon,24px] (`tinymceai-actions`) but also individually when handpicked by the integrator in the xref:toolbar-configuration-options.adoc[editor toolbar configuration]. Whole action categories can be added to the toolbar too. -Keep in mind that you can xref:tinymceai-actions-plugin.adoc#custom-actions[add custom actions] to the list and xref:tinymceai-actions-plugin.adoc#removing-default-actions[remove defaults]. +Keep in mind that xref:tinymceai-actions-plugin.adoc#custom-actions[custom actions] can be added to the list and xref:tinymceai-actions-plugin.adoc#removing-default-actions[defaults can be removed]. Here's the full list of available actions: @@ -113,7 +120,7 @@ Here's the full list of available actions: [[custom-actions]] == Custom Actions -The `tinymceai_actions_extraCommands` configuration property allows you to add new commands to the Quick actions feature. Below, you will find an example of three extra actions added to the user interface: two of them open the quick actions window, but the last one interacts with AI chat. Learn more about xref:tinymceai-actions-plugin.adoc#types-of-actions[types of actions]. +The `tinymceai_custom_commands` configuration property allows adding new commands to the Quick actions feature. The items can be type `action` (a quick action that goes straight to the preview rendering) or type `chat` (opens the chat interface). The `displayedPrompt` is used in the menu items, while the `prompt` is what is actually sent to the AI. The `model` is required for `action` type commands. Learn more about xref:tinymceai-actions-plugin.adoc#types-of-actions[types of actions]. [source,js] ---- @@ -124,37 +131,38 @@ tinymce.init({ tinymceai_token_provider: function() { return fetch('/api/token').then(response => response.text()); }, - tinymceai_actions_extraCommands: [ + tinymceai_custom_commands: [ { - id: 'add-quote-from-famous-person', displayedPrompt: 'Add a quote from a famous person', prompt: 'Add a quote from a known person, which would make sense in the context of the selected text.', - type: 'ACTION', - model: 'agent-1' + type: 'action', + model: 'gemini-2-5-flash' }, { - id: 'summarize-in-bullet-points', displayedPrompt: 'Summarize in 5 bullet points', prompt: 'Summarize the selected text in 5 bullet points.', - type: 'CHAT' + type: 'chat' }, { - id: 'include-more-sarcasm', displayedPrompt: 'Rewrite adding more sarcasm', prompt: 'Rewrite using a sarcastic tone.', - type: 'ACTION', - model: 'agent-1' + type: 'action', + model: 'gemini-2-5-flash' } - - // ... More commands ... ] }); ---- -[[removing-default-actions]] -== Removing default actions +[[configuring-quick-actions-menu]] +== Configuring Quick Actions menu -The `tinymceai_actions_removeCommands` configuration property allows you to remove existing commands from the Quick actions feature. Here's an example that removes two actions ("Explain" and "Summarize"): +Which actions appear in the Quick Actions menu can be configured by specifying the list of actions to include. The `tinymceai_quickactions_menu` configuration option controls the main menu items. + +Sub-menus have their own configuration options: +* `tinymceai_chat_commands_menu` - Controls items in the "Chat commands" sub-menu +* `tinymceai_adjust_length_menu` - Controls items in the "Adjust length" sub-menu +* `tinymceai_change_tone_menu` - Controls items in the "Change tone" sub-menu +* `tinymceai_translate_menu` - Controls items in the "Translate" sub-menu [source,js] ---- @@ -165,11 +173,22 @@ tinymce.init({ tinymceai_token_provider: function() { return fetch('/api/token').then(response => response.text()); }, - tinymceai_actions_removeCommands: [ - 'explain', - 'summarize' - - // ... More commands to remove ... + // Configure the main Quick Actions menu + tinymceai_quickactions_menu: [ + 'tinymceai-chat-commands', + 'tinymceai-improve-writing', + 'tinymceai-continue', + 'tinymceai-fix-grammar', + 'tinymceai-adjust-length', + 'tinymceai-change-tone', + 'tinymceai-translate', + 'tinymceai-custom-commands' + ], + // Configure a sub-menu (e.g., chat commands) + tinymceai_chat_commands_menu: [ + 'tinymceai-explain', + 'tinymceai-summarize', + 'tinymceai-highlight-key-points' ] }); ---- diff --git a/modules/ROOT/pages/tinymceai-api-quick-start.adoc b/modules/ROOT/pages/tinymceai-api-quick-start.adoc index 43666a8eff..2a22a7927f 100644 --- a/modules/ROOT/pages/tinymceai-api-quick-start.adoc +++ b/modules/ROOT/pages/tinymceai-api-quick-start.adoc @@ -5,11 +5,11 @@ :description_short: API quick start guide :keywords: AI, quick start, API, AI service, tinymceai, setup -The aim of this article is to get you up and running with the TinyMCE AI service. +The aim of this article is to get users up and running with the TinyMCE AI service. [TIP] ==== -You can also sign up for the link:https://www.tiny.cloud/auth/signup/[TinyMCE Premium Features 14-day free trial] if you want to test this feature first. +Sign up for the link:https://www.tiny.cloud/auth/signup/[TinyMCE Premium Features 14-day free trial] to test this feature first. The TinyMCE Premium Features free trial allows for testing SaaS services. If you are interested in on-premises solutions, please link:https://www.tiny.cloud/contact/[contact us]. ==== @@ -18,8 +18,8 @@ The TinyMCE Premium Features free trial allows for testing SaaS services. If you To start using the TinyMCE AI service, follow the steps below: -* Sign up for one of our link:https://www.tiny.cloud/pricing/[self-service plans], or link:https://www.tiny.cloud/contact/[contact us] to purchase the TinyMCE AI license. -* Generate your access credentials in the link:https://www.tiny.cloud/my-account/[Customer Portal]. +* Sign up for one of the link:https://www.tiny.cloud/pricing/[self-service plans], or link:https://www.tiny.cloud/contact/[contact us] to purchase the TinyMCE AI license. +* Generate access credentials in the link:https://www.tiny.cloud/my-account/[Customer Portal]. * Write a script that generates one-time tokens for authorizing end users of your application in TinyMCE Cloud Services (using access credentials created earlier). All steps are explained in details below. diff --git a/modules/ROOT/pages/tinymceai-chat.adoc b/modules/ROOT/pages/tinymceai-chat.adoc index 71624ac662..89b3acdf06 100644 --- a/modules/ROOT/pages/tinymceai-chat.adoc +++ b/modules/ROOT/pages/tinymceai-chat.adoc @@ -17,19 +17,19 @@ image::https://placehold.net/default.png[TinyMCE AI Chat interface showing the c [[working-with-the-document]] === Working with the document -TinyMCE AI operates directly within the context of your document. When you chat with it, you can ask questions about specific sections, request a full-document proofreading, and more. +TinyMCE AI operates directly within the context of the document. Users can ask questions about specific sections, request a full-document proofreading, and more. -By enabling xref:tinymceai-chat.adoc#web-search[Web search] or xref:tinymceai-chat.adoc#reasoning[Reasoning], you can extend its capabilities — allowing the chat to look up information online and tackle complex tasks step by step. +By enabling xref:tinymceai-chat.adoc#web-search[Web search] or xref:tinymceai-chat.adoc#reasoning[Reasoning], the chat capabilities can be extended — allowing the chat to look up information online and tackle complex tasks step by step. [[making-changes-to-the-content]] === Making changes to the content -Not only can you chat with the AI, but you can also use it to introduce changes to your document. Ask it to _"Summarize the document"_, _"Turn this report into a one-page executive summary"_, or _"Suggest better section titles and subheadings"_. The AI will then propose a series of changes to the document you can xref:tinymceai-chat.adoc#previewing-changes[review] and xref:tinymceai-chat.adoc#applying-changes[accept or discard one by one]. **Copying and pasting chat transcripts is over; TinyMCE AI understands your content and edits with you hand in hand**. +Users can chat with the AI and use it to introduce changes to the document. Ask it to _"Summarize the document"_, _"Turn this report into a one-page executive summary"_, or _"Suggest better section titles and subheadings"_. The AI will then propose a series of changes to the document that can be xref:tinymceai-chat.adoc#previewing-changes[reviewed] and xref:tinymceai-chat.adoc#applying-changes[accepted or discarded one by one]. **Copying and pasting chat transcripts is over; TinyMCE AI understands the content and edits hand in hand**. [[brainstorming]] === Brainstorming -The chat feature jump-starts your creative process. Begin with a blank document and ask the AI for ideas. Build your content step by step by chatting and applying changes. Then review — or have the AI rewrite — the final draft for best results. All in one place. +The chat feature jump-starts the creative process. Begin with a blank document and ask the AI for ideas. Build content step by step by chatting and applying changes. Then review — or have the AI rewrite — the final draft for best results. All in one place. [[demo]] == Demo @@ -39,7 +39,7 @@ liveDemo::tinymceai[] [[integration]] == Integration -To start using the Chat feature, first load the TinyMCE AI plugin in your editor configuration. The Chat button image:https://placehold.net/default.png[Chat icon,24px] will appear in the AI user interface along with the Chat history image:https://placehold.net/default.png[History icon,24px]. See xref:tinymceai.adoc[Plugin Reference] for installation and enabling AI features. +To start using the Chat feature, first load the TinyMCE AI plugin in the editor configuration. The Chat button image:https://placehold.net/default.png[Chat icon,24px] will appear in the AI user interface along with the Chat history image:https://placehold.net/default.png[History icon,24px]. See xref:tinymceai.adoc[Plugin Reference] for installation and enabling AI features. [[available-models]] == Available models @@ -48,22 +48,32 @@ Users can select the desired AI model for their conversation from a dropdown at image::https://placehold.net/default.png[TinyMCE AI Chat available models dropdown] -Once selected, the AI model will persist for the duration of the conversation. If you want to change the model, you can start a new conversation using a dedicated image:https://placehold.net/default.png[New chat icon,24px] button at the top-right corner of the chat panel. +Once selected, the AI model will persist for the duration of the conversation. To change the model, start a new conversation using a dedicated image:https://placehold.net/default.png[New chat icon,24px] button at the top-right corner of the chat panel. [[web-search]] === Web search -Web search in Chat allows it to access and retrieve real-time information from the internet. Instead of relying only on pre-trained knowledge, the model can search the web to find up-to-date facts, verify details, and provide more accurate, current answers. Toggle the "Enable web search" button image:https://placehold.net/default.png[Web search icon,24px] for a compatible model to start using the Web search functionality. +Web search in Chat allows it to access and retrieve real-time information from the internet. Instead of relying only on pre-trained knowledge, the model can search the web to find up-to-date facts, verify details, and provide more accurate, current answers. + +Some models use web search automatically, while others may require manual activation. Whether the "Enable web search" button image:https://placehold.net/default.png[Web search icon,24px] needs to be toggled depends on the model and sometimes even how the prompt is worded. For models that support it, use the toggle button to enable web search functionality. [[reasoning]] === Reasoning -Reasoning in Chat models turns on the ability to think through problems, draw logical conclusions, and make sense of complex information. It enables the model to analyze context, connect ideas, and produce well-structured, coherent answers beyond simple pattern matching. Toggle the "Enable reasoning" button image:https://placehold.net/default.png[Reasoning icon,24px] for a compatible model to start using the Reasoning functionality. +Reasoning in Chat models turns on the ability to think through problems, draw logical conclusions, and make sense of complex information. It enables the model to analyze context, connect ideas, and produce well-structured, coherent answers beyond simple pattern matching. + +Some models use reasoning automatically, while others may require manual activation. Whether the "Enable reasoning" button image:https://placehold.net/default.png[Reasoning icon,24px] needs to be toggled depends on the model and sometimes even how the prompt is worded. For models that support it, use the toggle button to enable reasoning functionality. [[model-selection-configuration]] === Configuration -The `tinymceai_conversations_models` configuration property allows you to configure model selection for AI chat. The property lets the integrator set the default model, tailor the available models list, or turn the list off. xref:tinymceai-integration.adoc#supported-ai-models[Learn more about available AI models]. +Model selection for AI chat can be configured using three separate configuration options: + +* `tinymceai_default_model`: Set the default model to use for AI chat. +* `tinymceai_allow_model_selection`: Control whether users can select from available models (defaults to `true`). +* `tinymceai_allowed_models`: Specify an array of allowed model IDs that users can select from. + +xref:tinymceai-integration.adoc#supported-ai-models[Learn more about available AI models]. [source,js] ---- @@ -74,33 +84,32 @@ tinymce.init({ tinymceai_token_provider: function() { return fetch('/api/token').then(response => response.text()); }, - tinymceai_conversations_models: { - defaultModelId: 'claude-3-5-haiku', - modelSelectorAlwaysVisible: false, - displayedModels: ['gpt', 'claude'] - } + tinymceai_default_model: 'claude-3-5-haiku', + tinymceai_allow_model_selection: true, + tinymceai_allowed_models: ['gpt-4', 'claude-3-5-haiku'] }); ---- [[adding-context-to-conversations]] == Adding context to conversations -The AI chat can work with your document and beyond. Use the "Add context" button image:https://placehold.net/default.png[Add context icon,24px] on the right of the prompt input, to add URLs, files, and external resources to your conversation. +The AI chat can work with the document and beyond. Use the "Add context" button image:https://placehold.net/default.png[Add context icon,24px] on the right of the prompt input, to add URLs, files, and external resources to the conversation. image::https://placehold.net/default.png[TinyMCE AI Chat add context user interface] -Ask the AI about specific resources, for instance, _"Describe the attached image"_ or _"Summarize the key points from the attached Word document"_. The AI will analyze those resources for you and provide information you can easily use in your document. +Ask the AI about specific resources, for instance, _"Describe the attached image"_ or _"Summarize the key points from the attached Word document"_. The AI will analyze those resources and provide information that can be easily used in the document. -External resources enable you to seamlessly integrate knowledge bases and other centralized data into your AI chat conversations. Instead of uploading documents each time you want to chat, you can simply select them from a list and reference them during your conversation. +External resources enable seamless integration of knowledge bases and other centralized data into AI chat conversations. Instead of uploading documents each time, they can be selected from a list and referenced during the conversation. [[context-configuration]] === Configuration -The `tinymceai_conversations_context` configuration property configures the AI chat menu for adding resources to the prompt context. +Built-in options for adding the current document, URLs, and files to the conversation context are always available to users. There is no configuration option to enable or disable these built-in options. -The example below enables built-in options to add the current document, URLs, and files to the conversation context by the user. +To add custom external sources for users to select from, use the following configuration options: -It also demonstrates a context sources configuration that introduces a menu with external resources fetched from a database or an external API for the user to pick from. +* `tinymceai_additional_sources_list`: A function that returns a promise resolving to an array of available external sources. This is typically used to fetch a list of resources from a database or external API. +* `tinymceai_get_additional_source`: A function that retrieves the content of a specific source by ID. This is used for hooking into a repository of custom sources and fetching content on demand. [source,js] ---- @@ -111,70 +120,17 @@ tinymce.init({ tinymceai_token_provider: function() { return fetch('/api/token').then(response => response.text()); }, - tinymceai_conversations_context: { - // Allow for adding the current document to the conversation. - document: { - enabled: true - }, - // Allow for adding URLs to the conversation. - urls: { - enabled: true - }, - // Allow for uploading files to the conversation. - files: { - enabled: true - }, - // External resources configuration. - sources: [ - // Definition of the custom context provider. - { - // The unique identifier of the provider. - id: 'my-docs', - // The human-readable name of the provider. - label: 'My Documents', - // The async callback to retrieve the list of available resources. - // Usually involves fetching data from a database or an external API, - // but here we use a simple array of resources for demonstration purposes. - getResources: async (query) => [ - // Text resources. - { - id: 'text3', - type: 'text', - label: 'Internal note in HTML format', - data: { - content: '

HTML note

Lorem ipsum dolor sit amet...

', - type: 'html' - } - }, - { - id: 'text4', - type: 'text', - label: 'Internal note (fetched on demand)', - // Note: Since the `data` property is not provided, the content will be retrieved using the `getData()` callback (see below). - // This will prevent fetching large content along with the list of resources. - }, - // URLs to resources. - { - id: 'url2', - type: 'web-resource', - label: 'Company brochure in PDF', - data: 'https://example.com/brochure.pdf' - }, - { - id: 'url3', - type: 'web-resource', - label: 'Company website in HTML', - data: 'https://example.com/index.html' - }, - // ... - ], - // The optional callback to retrieve the content of resources without the `data` property provided by the `getResources()` callback. - // When the user picks a specific resource, the content will be fetched on demand (from database or external API) by this callback. - // This prevents fetching large resources along with the list of resources. - getData: (id) => fetchDocumentContent(id) - }, - // More context providers... - ] + // Function that returns a list of available external sources + tinymceai_additional_sources_list: async (query) => { + // Fetch sources from the database or API + const response = await fetch(`/api/sources?q=${query}`); + return response.json(); + }, + // Function to fetch the content of a specific source by ID + tinymceai_get_additional_source: async (id) => { + // Fetch the source content on demand + const response = await fetch(`/api/sources/${id}`); + return response.json(); } }); ---- @@ -182,36 +138,14 @@ tinymce.init({ [[working-with-ai-generated-changes]] == Working with AI-generated changes -If you ask the AI for changes to your document, for instance, _"Bold key facts in the document"_, you will receive a series of proposed changes instead of plain text responses. - -image::https://placehold.net/default.png[TinyMCE AI Chat changes] - -Move your cursor over any change to highlight the section of your document it applies to, helping you identify it among other proposed edits. - -image::https://placehold.net/default.png[TinyMCE AI Chat highlighted changes in content] - -[[showing-details]] -=== Showing details +When asking the AI for changes to the document, for instance, _"Bold key facts in the document"_, a series of proposed changes will be received. The changes are displayed directly in the document content, making it easy to see what will be modified. -You can toggle details of the changes by pressing the "Show details" button image:https://placehold.net/default.png[Show details icon,24px]. By default, you will see detailed information on what exactly was suggested, including additions (green markers), removals (red markers), and formatting changes (blue markers). - -image::https://placehold.net/default.png[TinyMCE AI Chat highlighted changes] - -Click the button again to see a clean, simplified overview of the changes as they'll appear in your document once accepted. - -image::https://placehold.net/default.png[TinyMCE AI Chat clean view] - -[[previewing-changes]] -=== Previewing changes - -Click the "Show in the text" button image:https://placehold.net/default.png[Show in the text icon,24px] to display the information window about an individual change with options to apply it or turn it into a Suggested Edits suggestion. You can use this window to browse all proposed changes and work with them one by one. As you navigate through the changes, the window will automatically follow the corresponding sections of the document. - -image::https://placehold.net/default.png[TinyMCE AI Chat changes preview in text] +Toggle between showing and previewing the changes using a single toggle button. When enabled, the proposed changes are highlighted in the document with markers indicating additions (green), removals (red), and formatting changes (blue). Navigate through the changes and work with them one by one. As navigation occurs, the information window automatically follows the corresponding sections of the document. [[applying-changes]] === Applying changes -If you click the "Apply" button in the AI balloon, the change proposed by the AI will be applied to the document. +Clicking the "Apply" button in the AI balloon applies the change proposed by the AI to the document. image::https://placehold.net/default.png[TinyMCE AI Chat apply changes] @@ -219,19 +153,10 @@ Click the "Apply all" button in chat to apply all AI suggestions at once. image::https://placehold.net/default.png[TinyMCE AI Chat apply all changes] -[[inserting-suggested-edits]] -=== Inserting Suggested Edits suggestions - -When xref:suggestededits.adoc[Suggested Edits feature] is available in your integration, the "Insert suggestion" button image:https://placehold.net/default.png[Insert suggestion icon,24px] will be available in chat. Clicking it will create a Suggested Edits suggestion that can later be reviewed or discarded. - -image::https://placehold.net/default.png[TinyMCE AI Chat insert suggestion button] - -You can pick "Suggest" option from the "Apply all" menu to turn all changes suggested by AI into Suggested Edits suggestions. - [[rejecting-suggestions]] === Rejecting suggestions -You can click the "Delete" button image:https://placehold.net/default.png[Delete icon,24px] to reject AI suggestions you do not want before applying the remaining ones or turning them into Suggested Edits suggestions. +Click the "Delete" button image:https://placehold.net/default.png[Delete icon,24px] to reject AI suggestions that are not wanted before applying the remaining ones. image::https://placehold.net/default.png[TinyMCE AI Chat reject button] @@ -239,22 +164,22 @@ image::https://placehold.net/default.png[TinyMCE AI Chat reject button] [[chat-history]] == Chat history -All your past conversations appear in the Chat history. Click the button image:https://placehold.net/default.png[Chat history icon,24px] to open the list, where you can reopen, rename, or delete any conversation. +All past conversations appear in the Chat history. Click the button image:https://placehold.net/default.png[Chat history icon,24px] to open the list, where conversations can be reopened, renamed, or deleted. -Conversations are grouped by date to help you navigate your project easily. You can filter conversations by name using the search field at the top of the user interface. +Conversations are grouped by date to help navigate the project easily. Conversations can be filtered by name using the search field at the top of the user interface. image::https://placehold.net/default.png[AI Chat history] [NOTE] ==== -You can continue any conversation from the chat history as long as the AI model used for that conversation is xref:tinymceai-models.adoc#supported-models[still supported] by the feature. Click the conversation in the history to load it in the Chat interface. +Any conversation from the chat history can be continued as long as the AI model used for that conversation is xref:tinymceai-models.adoc#supported-models[still supported] by the feature. Click the conversation in the history to load it in the Chat interface. ==== [NOTE] ==== The ability to apply suggestions to the document or generate Suggested Edits from historical conversations may be restricted in some scenarios: -After closing the browser and reopening AI chat, previous conversations will no longer interact with the document content. To continue working with a conversation, you can reopen it from the chat history. +After closing the browser and reopening AI chat, previous conversations will no longer interact with the document content. To continue working with a conversation, reopen it from the chat history. ==== [[advanced-features]] @@ -263,7 +188,7 @@ After closing the browser and reopening AI chat, previous conversations will no The Chat feature supports advanced capabilities: * xref:tinymceai-chat.adoc#chat-history[**Multi-turn conversations**] - Maintain context across multiple interactions -* xref:tinymceai-chat.adoc#available-models[**Model selection**] - Choose the appropriate AI model for your task +* xref:tinymceai-chat.adoc#available-models[**Model selection**] - Choose the appropriate AI model for the task * xref:tinymceai-chat.adoc#web-search[**Web Search**] - Access up-to-date information from the web * xref:tinymceai-chat.adoc#reasoning[**Reasoning**] - Deep thinking about answers and changes diff --git a/modules/ROOT/pages/tinymceai-conversations.adoc b/modules/ROOT/pages/tinymceai-conversations.adoc index 301fe0acdb..bd32c93f89 100644 --- a/modules/ROOT/pages/tinymceai-conversations.adoc +++ b/modules/ROOT/pages/tinymceai-conversations.adoc @@ -5,14 +5,14 @@ :description_short: AI chat feature :keywords: AI, chat, conversations, tinymceai -Conversations allow you to exchange multiple messages with AI that maintains them in its context. Conversations can be extended by external context sources like websites or files, and have the ability to refer to editor content and suggest modifications. +Conversations allow exchanging multiple messages with AI that maintains them in its context. Conversations can be extended by external context sources like websites or files, and have the ability to refer to editor content and suggest modifications. [[key-features]] == Key Features Upload PDFs, Word docs, and images for the AI to read and understand. Ask questions about specific sections and get intelligent answers. The AI extracts text while preserving structure from PDFs, maintains formatting context from Word documents, parses web content from HTML files, and processes images with OCR and object recognition. -Each conversation builds on previous messages, so the AI keeps track of your entire discussion and any files you have shared. You can mix documents, images, web links, and text in one conversation, and the AI connects information across all formats. Enable web search for real-time research while keeping your conversation context. +Each conversation builds on previous messages, so the AI keeps track of the entire discussion and any files that have been shared. Documents, images, web links, and text can be mixed in one conversation, and the AI connects information across all formats. Enable web search for real-time research while keeping conversation context. [[example-product-launch-workflow]] === Example: Product Launch Workflow @@ -22,7 +22,7 @@ Each conversation builds on previous messages, so the AI keeps track of your ent . **Reference blog post** → _"Write a press release using this blog post and our competitive advantages"_ . **Include brand guidelines** → _"Match our brand voice and key messaging"_ -The AI remembers everything you have shared and builds on it throughout your conversation. +The AI remembers everything that has been shared and builds on it throughout the conversation. [[advanced-features]] == Advanced Features @@ -64,7 +64,7 @@ Authorization: Bearer [[upload-a-document]] === Upload a Document -Before you can reference documents in conversations, you need to upload them first: +Before documents can be referenced in conversations, they need to be uploaded first: [source,http] ---- @@ -84,7 +84,7 @@ Response: } ---- -You can see how to upload other resources, including web resources and files using https://tinymceai.api.tiny.cloud/docs#tag/Conversations[REST API documentation]. +See how to upload other resources, including web resources and files using https://tinymceai.api.tiny.cloud/docs#tag/Conversations[REST API documentation]. [[send-a-message-with-context]] === Send a Message with Context @@ -150,6 +150,6 @@ Conversations use Server-Sent Events (SSE) for real-time streaming responses. Se * xref:tinymceai-chat.adoc[AI Chat Plugin] – For plugin integration and UI configuration. * xref:tinymceai-reviews.adoc[Reviews API] – Content quality analysis and improvement suggestions. * xref:tinymceai-actions.adoc[Actions API] – Content transformation and batch processing. -* xref:tinymceai-models.adoc[AI Models] – Choosing the right AI model for your conversations. +* xref:tinymceai-models.adoc[AI Models] – Choosing the right AI model for conversations. * xref:tinymceai-streaming.adoc[Streaming Responses] – Implementing real-time conversation features. * xref:tinymceai-api-overview.adoc[API Overview] – Overview of all API features. diff --git a/modules/ROOT/pages/tinymceai-integration-options.adoc b/modules/ROOT/pages/tinymceai-integration-options.adoc index daf975f9b7..244f726b26 100644 --- a/modules/ROOT/pages/tinymceai-integration-options.adoc +++ b/modules/ROOT/pages/tinymceai-integration-options.adoc @@ -1,11 +1,11 @@ = TinyMCE AI Integration Options :navtitle: Integration Options -:description: Choose how to integrate TinyMCE AI with your application +:description: Choose how to integrate TinyMCE AI with applications :description_short: Integration options for TinyMCE AI :keywords: AI, integration, plugin, API, AI service, tinymceai -TinyMCE AI can be integrated with your application through two methods: +TinyMCE AI can be integrated with applications through two methods: [cols=2*a] |=== @@ -14,7 +14,7 @@ TinyMCE AI can be integrated with your application through two methods: [.lead] xref:tinymceai.adoc[**Plugin Quick Start**] -Integrate AI features directly into the TinyMCE editor interface. Works with CDN or self-hosted TinyMCE installations. The fastest way to add AI capabilities to your editor. +Integrate AI features directly into the TinyMCE editor interface. Works with CDN or self-hosted TinyMCE installations. The fastest way to add AI capabilities to the editor. | [.lead] diff --git a/modules/ROOT/pages/tinymceai-integration.adoc b/modules/ROOT/pages/tinymceai-integration.adoc index d661d76531..e14529a4bf 100644 --- a/modules/ROOT/pages/tinymceai-integration.adoc +++ b/modules/ROOT/pages/tinymceai-integration.adoc @@ -5,12 +5,12 @@ :description_short: Integration guide :keywords: AI, integration, plugin, configuration, tinymceai -This guide will take you step-by-step through the process of running TinyMCE AI in your editor integration. It also presents possible configuration and customization options. +This guide provides step-by-step instructions for running TinyMCE AI in editor integrations. It also presents possible configuration and customization options. [[installation]] == Installation -After installing the editor, add the feature to your plugin list and provide xref:tinymceai-integration.adoc#sample-implementation[essential configuration]: +After installing the editor, add the feature to the plugin list and provide xref:tinymceai-integration.adoc#sample-implementation[essential configuration]: [source,js] ---- @@ -27,52 +27,25 @@ tinymce.init({ [NOTE] ==== -You must configure a user interface type for the AI features to work. Learn more about the available options in the xref:tinymceai-integration.adoc#ui-types-and-positioning[UI placement] section or use the xref:tinymceai-integration.adoc#sample-implementation[sample implementation] as a reference. -==== - -[NOTE] -==== -Using AI features with the Suggested Edits feature requires proper user configuration. Learn more about the xref:tinymceai-integration.adoc#suggested-edits-dependency[Suggested Edits dependency] or refer to the xref:tinymceai-integration.adoc#sample-implementation[sample implementation] for more details. +The sidebar type must be configured for the AI features to work. The sidebar can be set to `static` (default) or `floating` using the `tinymceai_sidebar_type` configuration option. Learn more in the xref:tinymceai-integration.adoc#ui-types-and-positioning[UI types and positioning] section or use the xref:tinymceai-integration.adoc#sample-implementation[sample implementation] as a reference. ==== [[sample-implementation]] == Sample implementation -An example TinyMCE AI configuration is presented below. You can learn more about specific configurations such as xref:tinymceai-integration.adoc#ui-types-and-positioning[UI types and positioning] or xref:tinymceai-integration.adoc#suggested-edits-dependency[Suggested Edits dependency] in the later sections of this guide. - -To learn more about toolbar configuration, refer to the xref:toolbar-configuration-options.adoc[toolbar configuration] guide. +An example TinyMCE AI configuration is presented below. Learn more about specific configurations in the later sections of this guide. [source,js] ---- -// Simplified integration of the Users plugin needed for Suggested Edits integration. -// For production applications, replace the dummy user with actual user data from your authentication system. -function setupUsers(editor) { - // Just add a minimal dummy user - editor.settings.tinymceai_user = { - id: 'user-1', - name: 'John Doe' - }; -} - tinymce.init({ selector: '#editor', - plugins: 'tinymceai suggestededits', + plugins: 'tinymceai', - // Extend the main editor toolbar configuration with additional buttons: - // - 'tinymceai': opens the Quick actions menu, - // - 'tinymceai-conversations': moves the user focus to AI chat, - // - 'tinymceai-improve-writing': executes the "Improve Writing" quick action. - // - // You can add more Quick actions to the toolbar configuration if needed. - toolbar: [ - 'tinymceai', - 'tinymceai-conversations', - 'tinymceai-improve-writing', - // ... other toolbar items - ], + // Add AI toolbar buttons + toolbar: 'showai aiquickactions aireview', - // You can use the same AI feature buttons in the balloon toolbar configuration for contextual convenience. - contextmenu: 'tinymceai tinymceai-conversations tinymceai-improve-writing', + // AI features are added to the selection toolbar by default + // Configure which features appear using tinymceai_context_toolbar setup: function(editor) { setupUsers(editor); @@ -80,142 +53,50 @@ tinymce.init({ // Configure the document identifier for AI chat history and context preservation. // This should be a unique identifier for the document/article being edited. - tinymceai_document_id: 'document-123', // Replace with your actual document ID + tinymceai_document_id: 'document-123', // Replace with the actual document ID // Main configuration of AI feature. tinymceai_token_provider: function() { return fetch('/api/token').then(response => response.text()); }, - // ⚠️ Mandatory UI configuration. - // Display the AI user interface in a dedicated DOM element. The interface can be also displayed - // in an overlay or in a custom way, learn more in the next chapters of this guide. - tinymceai_ui_type: 'sidebar', - tinymceai_sidebar_element: document.querySelector('.ai-sidebar'), + // Configure sidebar type (static or floating) + tinymceai_sidebar_type: 'static', - // (Optional) Whether the AI interface should be visible when the editor is created. - tinymceai_ui_visible_by_default: false, + // (Optional) Configure AI chat model selection. + tinymceai_default_model: 'agent-1', + tinymceai_allow_model_selection: true, + tinymceai_allowed_models: ['gpt', 'claude'], - // (Optional) Configure AI chat by configuring available context resources. - tinymceai_conversations_context: { - // Configuration of the built-in context options. - document: { - enabled: true - }, - urls: { - enabled: false - }, - files: { - enabled: true + // (Optional) Configure additional context sources for AI chat. + // Built-in options (document, URLs, files) are always available. + tinymceai_additional_sources_list: async (query) => [ + { + id: 'my-doc-1', + label: 'My Document 1', + type: 'text' }, - - // (Optional) Additional sources for AI chat context. - sources: [ - // Definition of the custom context provider. - { - // The unique identifier of the provider. - id: 'my-docs', - - // The human-readable name of the provider. - label: 'My Documents', - - // The async callback to retrieve the list of available resources. - // Usually involves fetching data from a database or an external API, - // but here we use a simple array of resources for demonstration purposes. - getResources: async (query) => [ - // Texts in various formats - { - id: 'text1', - type: 'text', - label: 'Internal note in plain text format', - data: { - content: 'Lorem ipsum dolor sit amet...', - type: 'text' - } - }, - { - id: 'text2', - type: 'text', - label: 'Internal note in Markdown format', - data: { - content: '## Markdown note\n\n**Lorem ipsum** dolor sit amet...', - type: 'markdown' - } - }, - { - id: 'text3', - type: 'text', - label: 'Internal note in HTML format', - data: { - content: '

HTML note

Lorem ipsum dolor sit amet...

', - type: 'html' - } - }, - { - id: 'text4', - type: 'text', - label: 'Internal note (fetched on demand)', - - // Note: Since the `data` property is not provided, the content will be retrieved using the `getData()` callback (see below). - // This will prevent fetching large content along with the list of resources. - }, - - // URLs to resources in different formats - { - id: 'url1', - type: 'web-resource', - label: 'Blog post in Markdown', - data: 'https://example.com/blog-post.md' - }, - { - id: 'url2', - type: 'web-resource', - label: 'Company brochure in PDF', - data: 'https://example.com/brochure.pdf' - }, - { - id: 'url3', - type: 'web-resource', - label: 'Company website in HTML', - data: 'https://example.com/index.html' - }, - { - id: 'url4', - type: 'web-resource', - label: 'Terms of service in plain text', - data: 'https://example.com/terms-of-service.txt' - }, - - // ... - ], - - // The optional callback to retrieve the content of resources without the `data` property provided by the `getResources()` callback. - // When the user picks a specific resource, the content will be fetched on demand (from database or external API) by this callback. - // This prevents fetching large resources along with the list of resources. - getData: (id) => fetchDocumentContent(id) - }, - - // More context providers... - ] - }, + { + id: 'my-doc-2', + label: 'My Document 2', + type: 'text' + } + // ... More sources ... + ], - // (Optional) The configuration of AI chat models selection feature. - tinymceai_conversations_models: { - defaultModelId: 'agent-1', - modelSelectorAlwaysVisible: true, - displayedModels: ['gpt', 'claude'] + // (Optional) Function to fetch content for additional sources. + tinymceai_get_additional_source: async (id) => { + // Fetch content from the database or API + return fetch(`/api/documents/${id}`).then(response => response.text()); }, - // (Optional) Configure the Quick actions feature by adding a new command. - tinymceai_quick_actions_extra_commands: [ - // An action that opens AI chat interface for interactive conversations. + // (Optional) Configure custom Quick Actions commands. + tinymceai_custom_commands: [ { - id: 'explain-like-i-am-five', displayedPrompt: 'Explain like I am five', - prompt: 'Explain the following text like I am five years old.', - type: 'CHAT' - }, - + prompt: 'Explain the following text in simple terms.', + type: 'chat' + } // ... More custom actions ... ] }); @@ -229,7 +110,7 @@ tinymce.init({ TinyMCE AI supports multiple AI models from different providers. By default, the automatically selected model (`agent-1`) will be used for optimal cost and performance. -You can narrow down the list of available models. xref:tinymceai-chat.adoc#model-selection-configuration[Learn how to configure the list of available models in Chat]. +The list of available models can be narrowed down. xref:tinymceai-chat.adoc#model-selection-configuration[Learn how to configure the list of available models in Chat]. Here's a detailed list of available models with their capabilities: @@ -312,20 +193,20 @@ Here's a detailed list of available models with their capabilities: [NOTE] ==== -Model availability depends on your subscription tier and service compatibility version. Some models may have specific limitations or requirements. For detailed information about available models, their capabilities, and API-level configuration, see xref:tinymceai-models.adoc[AI models documentation]. +Model availability depends on the subscription tier and service compatibility version. Some models may have specific limitations or requirements. For detailed information about available models, their capabilities, and API-level configuration, see xref:tinymceai-models.adoc[AI models documentation]. ==== [[document-id]] === Document ID -The `tinymceai_document_id` configuration property serves as the document identifier corresponding to the edited resource (article, document, etc.) in your application. This ID is essential for maintaining xref:tinymceai-chat.adoc[Chat] history, ensuring that AI conversations are properly associated with the specific document being edited. When users interact with AI features, their chat history is preserved and linked to this document ID. +The `tinymceai_document_id` configuration property serves as the document identifier corresponding to the edited resource (article, document, etc.) in the application. This ID is essential for maintaining xref:tinymceai-chat.adoc[Chat] history, ensuring that AI conversations are properly associated with the specific document being edited. When users interact with AI features, their chat history is preserved and linked to this document ID. [source,js] ---- tinymce.init({ selector: '#editor', plugins: 'tinymceai', - tinymceai_document_id: 'DOCUMENT_ID', // Replace with your actual document ID + tinymceai_document_id: 'DOCUMENT_ID', // Replace with the actual document ID tinymceai_token_provider: function() { return fetch('/api/token').then(response => response.text()); } @@ -334,120 +215,44 @@ tinymce.init({ [NOTE] ==== -The `tinymceai_document_id` configuration uses a dedicated namespace in the configuration. This namespace may be subject to change in future versions as we continue to refine the AI integration architecture. -==== - -[[suggested-edits-dependency]] -=== Suggested Edits dependency - -TinyMCE AI can leverage the Suggested Edits feature to enhance the user experience, for instance, by allowing users to turn AI-generated content into suggestions that can later be reviewed, accepted, or rejected. Without the Suggested Edits plugin, TinyMCE AI will work, but some functionalities may be limited. For the most complete integration, we highly recommend using Suggested Edits along with TinyMCE AI. - -[NOTE] -==== -Please keep in mind that the `suggestededits` plugin requires user management, and as such, it will require you to provide a minimal user integration, even for non-collaborative setups. - -The xref:tinymceai-integration.adoc#sample-implementation[sample implementation] above shows a basic user setup function that adds a dummy user. For production applications, replace the dummy user with actual user data from your authentication system. +The `tinymceai_document_id` configuration uses a dedicated namespace in the configuration. This namespace may be subject to change in future versions as the AI integration architecture continues to be refined. ==== [[ui-types-and-positioning]] === UI types and positioning -TinyMCE AI gives you flexible options for displaying the AI user interface. The `tinymceai_ui_type` and related configuration properties allow you to choose from three different UI placement modes: - -[[sidebar]] -==== Sidebar - -When in sidebar mode, the AI user interface is displayed in a specific DOM element, allowing you to inject it into your existing user interface. - -[source,js] ----- -tinymce.init({ - selector: '#editor', - plugins: 'tinymceai', - tinymceai_ui_type: 'sidebar', - - // Existing DOM element to use as the container for the AI user interface. - tinymceai_sidebar_element: document.querySelector('#ai-sidebar-container'), - - // (Optional) The preferred side for positioning the tab buttons. - tinymceai_sidebar_side: 'right', - - tinymceai_token_provider: function() { - return fetch('/api/token').then(response => response.text()); - } -}); ----- - -In addition to the above, we recommend using the following or similar CSS to style the sidebar container for the AI user interface (tabs) to render optimally: - -[source,css] ----- -#ai-sidebar-container .tinymce-ai-tabs { - /* An arbitrary fixed width to limit the space consumed by the AI tabs. */ - width: 500px; - - /* A fixed height that enables vertical scrolling (e.g., in AI chat feed). */ - height: 800px; -} ----- - -[[overlay]] -==== Overlay +TinyMCE AI supports two sidebar types for displaying the AI user interface. Use the `tinymceai_sidebar_type` configuration option to choose between them: -When in overlay mode, the AI user interface is displayed on top of the page, allowing you to position it on your preferred side. This mode is best suited for integrations with limited space. +* `static` (default): The sidebar is rendered inside the editor. +* `floating`: The sidebar is rendered in a separate container outside of the editor and can be dragged on the page. [source,js] ---- tinymce.init({ selector: '#editor', plugins: 'tinymceai', - tinymceai_ui_type: 'overlay', - tinymceai_overlay_side: 'right', + tinymceai_sidebar_type: 'static', // or 'floating' tinymceai_token_provider: function() { return fetch('/api/token').then(response => response.text()); } }); ---- -Learn how to xref:tinymceai-integration.adoc#toggling-the-ui[toggle the AI overlay] using a dedicated toolbar button. - -[[custom]] -==== Custom - -When in custom mode, the AI user interface is displayed in a custom way, allowing you to use the building blocks of the AI user interface to create your own and satisfy the specific needs of your application. - -[source,js] ----- -tinymce.init({ - selector: '#editor', - plugins: 'tinymceai', - tinymceai_ui_type: 'custom', - tinymceai_token_provider: function() { - return fetch('/api/token').then(response => response.text()); - }, - setup: function(editor) { - // A custom integration of the AI user interface placing the tab buttons and panels separately in custom containers. - editor.on('tinymceai:ready', function() { - const aiTabs = editor.plugins.get('tinymceai').getTabs(); - - for (const id of aiTabs.getTabIds()) { - const tab = aiTabs.getTab(id); - - // Display tab button and panel in a custom container. - myButtonsContainer.appendChild(tab.button.element); - myPanelContainer.appendChild(tab.panel.element); - } - }); - } -}); ----- +[NOTE] +==== +Changing the `tinymceai_sidebar_type` property dynamically (after the editor has been initialized) is not supported and can result in unpredictable behavior. +==== [[toggling-the-ui]] === Toggling the UI -The user interface can be easily toggled by the users using the `'tinymceai-toggle'` image:https://placehold.net/default.png[Ask AI icon,24px] toolbar button. The button becomes available for configuration when the AI features are enabled. +The AI user interface can be toggled by users using toolbar buttons or menu items. Clicking a toolbar button (or menu item) opens or minimizes the relevant AI sidebar. -The following example shows how to enable the `'tinymceai-toggle'` button in the main editor toolbar: +* Clicking the chat toolbar button opens the chat sidebar. Clicking it again minimizes the chat sidebar. Importantly, minimizing the chat sidebar does not wipe the chat history—it just hides the sidebar. +* Clicking the review button opens the review sidebar. +* When reviewing suggested changes, the sidebar can be minimized to provide more screen space for reviewing. Once done reviewing, the sidebar can be opened again to continue working. + +The following example shows how to enable the AI toolbar buttons: [source,js] ---- @@ -455,80 +260,45 @@ tinymce.init({ selector: '#editor', plugins: 'tinymceai', - // Enable the 'tinymceai-toggle' button in the main editor toolbar. - toolbar: ['tinymceai-toggle', /* ... */], + // Enable AI toolbar buttons + toolbar: ['showai', 'aiquickactions', 'aireview', /* ... */], tinymceai_token_provider: function() { return fetch('/api/token').then(response => response.text()); - }, - - tinymceai_ui_type: 'overlay', - // ... other configuration + } }); ---- -You can also programmatically show or hide the AI interface: +The AI sidebar can also be toggled programmatically: [source,js] ---- -// Show the AI interface -editor.execCommand('tinymceai:show'); - -// Hide the AI interface -editor.execCommand('tinymceai:hide'); - -// Toggle the AI interface -editor.execCommand('tinymceai:toggle'); +// Toggle the AI sidebar +editor.execCommand('tinymceai-toggle-sidebar'); ---- -If you wish to initially hide the overlay until a user opens it with a button, you can use the xref:tinymceai-integration.adoc#hiding-the-ui-on-initialization[dedicated configuration]. - [[hiding-the-ui-on-initialization]] === Hiding the UI on initialization -By default, the AI interface will be visible when editor is created (and the xref:tinymceai-integration.adoc#toggling-the-ui[related toolbar button] will be active). If you wish to have it hidden until the user opens it (e.g. via toolbar button), set `tinymceai_ui_visible_by_default` property to `false`. +By default, the AI interface will be hidden when the editor is created. To have it visible on load, use the `tinymceai-toggle-sidebar` command after the editor is initialized. [source,js] ---- tinymce.init({ selector: '#editor', plugins: 'tinymceai', - tinymceai_ui_visible_by_default: false, tinymceai_token_provider: function() { return fetch('/api/token').then(response => response.text()); + }, + setup: function(editor) { + editor.on('init', function() { + // Show the AI interface on load + editor.execCommand('tinymceai-toggle-sidebar'); + }); } }); ---- -[[maximizing-the-ui]] -=== Maximizing the UI - -The maximize button image:https://placehold.net/default.png[Maximize icon,24px] in the upper-right corner allows changing the width of the TinyMCE AI user interface. Users can use this button to interact with the AI features more comfortably, especially while xref:tinymceai-chat.adoc[chatting] and interacting with large chunks of content. - -Clicking this button will toggle the `.tinymce-ai-tabs_maximized` CSS class on the `.tinymce-ai-tabs` DOM element. The integrator can then style the geometry of the element based on the specific requirements of the integration. - -* When the UI is configured in the xref:tinymceai-integration.adoc#sidebar[sidebar mode], the decision on how to style the maximized state of the user interface is left to the integrator due to many possible integration types and configurations. -* When the UI is configured in the xref:tinymceai-integration.adoc#overlay[overlay mode], integrators can override the `--tinymce-ai-tabs-overlay-width-maximized` CSS custom property to change the width of the overlay. - -[source,css] ----- -:root { - /* The TinyMCE AI interface will consume 40% of the space when maximized */ - --tinymce-ai-tabs-overlay-width-maximized: 40%; -} ----- - -You can also programmatically maximize or restore the AI interface: - -[source,js] ----- -// Maximize the AI interface -editor.execCommand('tinymceai:maximize'); - -// Restore the AI interface to normal size -editor.execCommand('tinymceai:restore'); ----- - [[permissions]] === Permissions diff --git a/modules/ROOT/pages/tinymceai-introduction.adoc b/modules/ROOT/pages/tinymceai-introduction.adoc index 88d5867f1f..df2ddfc9ea 100644 --- a/modules/ROOT/pages/tinymceai-introduction.adoc +++ b/modules/ROOT/pages/tinymceai-introduction.adoc @@ -15,7 +15,7 @@ liveDemo::tinymceai[] [[what-is-tinymce-ai]] == What is TinyMCE AI -TinyMCE AI is an AI-powered writing assistant that integrates directly into our rich-text editor, {productname}, providing instant text rewriting, summarization, correction, and contextual chat help based on internal style guides. The platform includes automated review tools and enterprise-ready functionality that plugs into existing systems without requiring custom infrastructure. +TinyMCE AI is an AI-powered writing assistant that integrates directly into the rich-text editor, {productname}, providing instant text rewriting, summarization, correction, and contextual chat help based on internal style guides. The platform includes automated review tools and enterprise-ready functionality that plugs into existing systems without requiring custom infrastructure. Teams can implement a full suite of AI writing tools in weeks rather than months, delivering streamlined, compliant content workflows that maintain brand consistency and integrate seamlessly with existing document management systems. @@ -27,7 +27,7 @@ The core components of TinyMCE AI are: [[features]] == TinyMCE AI features -There are three main features of TinyMCE AI. You can test them all using the free trial. +There are three main features of TinyMCE AI. All features can be tested using the free trial. * xref:tinymceai-chat.adoc[**Chat**] – Interactive AI chats with history and persistent context. * xref:tinymceai-review-plugin.adoc[**Review**] – Content analysis and proofreading, optimized for larger content. @@ -36,7 +36,7 @@ There are three main features of TinyMCE AI. You can test them all using the fre [[integration-options]] == Integration Options -TinyMCE AI can be integrated with your application through two methods. See xref:tinymceai-integration-options.adoc[Integration Options] for details. +TinyMCE AI can be integrated with applications through two methods. See xref:tinymceai-integration-options.adoc[Integration Options] for details. [[permissions]] == Permissions @@ -46,4 +46,4 @@ Developers can control access to AI features, models, and capabilities based on [[privacy-and-data-handling]] == Privacy and data handling -You can find detailed information on how TinyMCE AI manages your data in the xref:tinymceai-api-overview.adoc#data-handling-and-security[API Overview] documentation. +Detailed information on how TinyMCE AI manages data can be found in the xref:tinymceai-api-overview.adoc#data-handling-and-security[API Overview] documentation. diff --git a/modules/ROOT/pages/tinymceai-limits.adoc b/modules/ROOT/pages/tinymceai-limits.adoc index 5a2c5c464c..16d26e0805 100644 --- a/modules/ROOT/pages/tinymceai-limits.adoc +++ b/modules/ROOT/pages/tinymceai-limits.adoc @@ -17,7 +17,7 @@ TinyMCE AI implements various limits to ensure fair usage, optimal performance, Rate limits control the frequency of API requests to prevent abuse and ensure service stability. The service implements limits on API requests, token usage, web search, and web scraping requests per minute. All rate limits are applied at both organization level (higher limits) and individual user level (lower limits) to ensure fair usage. -NOTE: Specific rate limit values are subject to change and may vary based on your subscription tier. Contact support for current rate limit details for your environment. +NOTE: Specific rate limit values are subject to change and may vary based on the subscription tier. Contact support for current rate limit details for the environment. [[context-limits]] == Context Limits @@ -27,7 +27,7 @@ Context limits control how much content can be attached to conversations to ensu [[file-limits]] === File Limits -Files are limited to 7MB each (PDF, DOCX, PNG, JPEG, Markdown, HTML, Plain text). You can upload up to 100 files per conversation with a total size limit of 30MB. PDF files are limited to 100 pages total across all PDFs in a conversation. +Files are limited to 7MB each (PDF, DOCX, PNG, JPEG, Markdown, HTML, Plain text). Up to 100 files can be uploaded per conversation with a total size limit of 30MB. PDF files are limited to 100 pages total across all PDFs in a conversation. [[model-specific-file-limits]] ==== Model-specific file limits diff --git a/modules/ROOT/pages/tinymceai-models.adoc b/modules/ROOT/pages/tinymceai-models.adoc index 8ecfacd6c0..adea0c2414 100644 --- a/modules/ROOT/pages/tinymceai-models.adoc +++ b/modules/ROOT/pages/tinymceai-models.adoc @@ -8,7 +8,7 @@ [[recommended-agent-models]] == Recommended: Agent Models -The `agent-1` model automatically selects the best AI model for your request based on speed, quality, and cost. It's the recommended choice for most use cases as it optimizes performance and cost automatically. +The `agent-1` model automatically selects the best AI model for requests based on speed, quality, and cost. It's the recommended choice for most use cases as it optimizes performance and cost automatically. [[available-models]] == Available Models @@ -18,7 +18,7 @@ TinyMCE AI supports multiple AI models from different providers. Each model has [[limitations]] === Limitations -Model availability depends on your subscription tier and service compatibility version. Some models may have specific limitations or requirements. +Model availability depends on the subscription tier and service compatibility version. Some models may have specific limitations or requirements. [[how-model-selection-works]] == How Model Selection Works @@ -30,7 +30,7 @@ The agent model (`agent-1`) automatically selects the best underlying model base * **Required capabilities** – Web search and reasoning require compatible models * **Cost optimization** – Balances quality with cost efficiency -You can also specify a model directly in your API requests for more control. +A model can also be specified directly in API requests for more control. [[model-compatibility-versions]] == Model Compatibility Versions @@ -45,7 +45,7 @@ Compatibility versions allow TinyMCE AI to introduce new models and capabilities [[checking-compatibility]] === Checking Compatibility -Check the `/v1/models` endpoint to see available models for your compatibility version. The API response includes model capabilities, limits, and availability. +Check the `/v1/models` endpoint to see available models for the compatibility version. The API response includes model capabilities, limits, and availability. [[model-capabilities]] == Model Capabilities @@ -65,11 +65,11 @@ Enable step-by-step reasoning to see the AI's problem-solving process. Some mode **Always-on reasoning models:** * Reasoning is always active during inference. -* You cannot turn reasoning off via the API. +* Reasoning cannot be turned off via the API. To determine if a model has always-on reasoning, check the API response when listing models. Models with mandatory reasoning will indicate this in their capability structure. -NOTE: Please observe, that model names such as `gpt-5`, `claude-4-sonnet`, etc. are examples. Actual available models depend on your service's compatibility version. Use the `/v1/models` endpoint to see current available models for your environment. +NOTE: Please observe, that model names such as `gpt-5`, `claude-4-sonnet`, etc. are examples. Actual available models depend on the service's compatibility version. Use the `/v1/models` endpoint to see current available models for the environment. [[web-scraping]] === Web Scraping @@ -82,7 +82,7 @@ Extract and process content from web pages for analysis and summarization. [[file-processing-limits]] === File Processing Limits -Files are limited to 7MB each (PDF, DOCX, PNG, JPEG, Markdown, HTML, Plain text). You can upload up to 100 files per conversation with a total size limit of 30MB. PDF files are limited to 100 pages total across all PDFs in a conversation. +Files are limited to 7MB each (PDF, DOCX, PNG, JPEG, Markdown, HTML, Plain text). Up to 100 files can be uploaded per conversation with a total size limit of 30MB. PDF files are limited to 100 pages total across all PDFs in a conversation. [[model-specific-file-limits]] ==== Model-specific file limits @@ -104,7 +104,7 @@ Model descriptions returned by the API are provided in English and may be update NOTE: Backend translation handling for model descriptions is planned in a future release. Until then, use the approach described below. -If your application requires translated model descriptions, maintain a translation map in your code keyed by `model.id`, with fallback to the English description from the API for unknown models. This allows new models to work immediately while you add translations at your own pace. +If the application requires translated model descriptions, maintain a translation map in the code keyed by `model.id`, with fallback to the English description from the API for unknown models. This allows new models to work immediately while translations are added at a custom pace. [[model-deprecation]] === Model Deprecation diff --git a/modules/ROOT/pages/tinymceai-review-plugin.adoc b/modules/ROOT/pages/tinymceai-review-plugin.adoc index a15f271bb1..2e5822328d 100644 --- a/modules/ROOT/pages/tinymceai-review-plugin.adoc +++ b/modules/ROOT/pages/tinymceai-review-plugin.adoc @@ -15,26 +15,26 @@ liveDemo::tinymceai[] [[overview]] == Overview -The Review feature analyzes your content and provides specific recommendations for grammar, style, clarity, and tone improvements. Unlike Actions that transform content directly, Reviews analyze your content and provide suggestions without automatically changing the content. +The Review feature analyzes content and provides specific recommendations for grammar, style, clarity, and tone improvements. Unlike Actions that transform content directly, Reviews analyze content and provide suggestions without automatically changing the content. image::https://placehold.net/default.png[TinyMCE AI Review feature showing AI-powered quality assurance and suggested edits] [[integration]] == Integration -To start using the Review feature, first load the TinyMCE AI plugin in your editor configuration. The Review Mode button image:https://placehold.net/default.png[Review icon,24px] will appear in the AI user interface. xref:tinymceai-integration.adoc[Learn more about installing and enabling AI features]. +To start using the Review feature, first load the TinyMCE AI plugin in the editor configuration. The Review Mode button image:https://placehold.net/default.png[Review icon,24px] will appear in the AI user interface. xref:tinymceai-integration.adoc[Learn more about installing and enabling AI features]. After picking one of the available commands in the Review Mode tab, AI will analyze the document and propose a series of suggestions: image::https://placehold.net/default.png[TinyMCE AI Review sidebar with suggestions] -While in the Review Mode, the editor remains read-only and allows you to browse suggestions. You can either click suggestions in the sidebar or select them in the editor content (underlined): +While in the Review Mode, the editor remains read-only and allows browsing suggestions. Suggestions can be clicked in the sidebar or selected in the editor content (underlined): image::https://placehold.net/default.png[TinyMCE AI Review suggestion in content] -You can accept or dismiss review suggestions by clicking the corresponding buttons. You can also accept all suggestions by using the "Accept all" button in the top of the user interface and xref:tinymceai-chat.adoc#previewing-changes[preview changes similar to chat suggestions]. Changes that were accepted or dismissed become greyed out in the interface. You can also abandon the review by hitting the "Exit review" button. +Review suggestions can be accepted or dismissed by clicking the corresponding buttons. All suggestions can also be accepted by using the "Accept all" button in the top of the user interface and xref:tinymceai-chat.adoc#previewing-changes[previewing changes similar to chat suggestions]. Changes that were accepted or dismissed become greyed out in the interface. The review can also be abandoned by clicking the "Exit review" button. -Once you are done reviewing your document and all changes are accepted or rejected, click "Finish review" (the button state changes automatically) to return to the normal operation of the editor, where typing is possible. +Once reviewing is complete and all changes are accepted or rejected, click "Finish review" (the button state changes automatically) to return to the normal operation of the editor, where typing is possible. [[review-commands]] == Review commands @@ -45,8 +45,6 @@ The feature comes with several review commands: |=== |Command name |Command description |Additional information -|**Custom command** |Enter a custom command for a specific review |You can pick one of the xref:tinymceai-integration.adoc#supported-ai-models[available AI models] to execute a custom command - |**Proofread** |Check the text for errors in grammar, spelling and punctuation | |**Improve clarity** |Improve the logical structure and precision for clearer message | @@ -56,36 +54,12 @@ The feature comes with several review commands: |**Adjust length** |Shorten or lengthen the text as needed |_Longer_ and _Shorter_ options available |**Adjust tone and style** |Modify the text to a desired tone and style |Several tone and style options are available: _Casual, Direct, Friendly, Confident, Professional_ - -|**Translate** |Translate the text into another language |Several languages are available out-of-the-box, and the list can be xref:tinymceai-review-plugin.adoc#customizing-translation-commands[customized]: _English, Spanish, French, German, Chinese (Simplified), Japanese, Russian, Portuguese, Korean, Italian_ |=== -[[customizing-translation-commands]] -== Customizing translation commands - -The `tinymceai_reviews_translations` configuration property allows you to provide a custom list of translations for the "Translate" check. For instance, the following configuration will add "German" and "French" to the list: - -[source,js] ----- -tinymce.init({ - selector: '#editor', - plugins: 'tinymceai', - toolbar: 'tinymceai', - tinymceai_token_provider: function() { - return fetch('/api/token').then(response => response.text()); - }, - tinymceai_reviews_translations: [ - { - id: 'german', - label: 'German' - }, - { - id: 'french', - label: 'French' - } - ] -}); ----- +[NOTE] +==== +Custom commands and translation are not currently supported in the Review feature. This may change in future updates. +==== [[related-features]] == Related Features diff --git a/modules/ROOT/pages/tinymceai-reviews.adoc b/modules/ROOT/pages/tinymceai-reviews.adoc index fc33c952fa..50d86cf2c6 100644 --- a/modules/ROOT/pages/tinymceai-reviews.adoc +++ b/modules/ROOT/pages/tinymceai-reviews.adoc @@ -5,9 +5,9 @@ :description_short: AI review feature :keywords: AI, review, reviews, tinymceai -Reviews provide comprehensive content analysis and improvement suggestions. Unlike Actions that transform content directly, Reviews analyze your content and provide specific recommendations for grammar, style, clarity, and tone improvements. +Reviews provide comprehensive content analysis and improvement suggestions. Unlike Actions that transform content directly, Reviews analyze content and provide specific recommendations for grammar, style, clarity, and tone improvements. -**When to use Reviews vs Actions:** Use Reviews when you need to analyze entire documents for quality improvements and get suggestions without automatically changing the content. Use Actions when you need to transform specific text content (fix grammar, translate, adjust tone). +**When to use Reviews vs Actions:** Use Reviews when analyzing entire documents for quality improvements and getting suggestions without automatically changing the content. Use Actions when transforming specific text content (fix grammar, translate, adjust tone). [[available-reviews]] == Available Reviews @@ -27,9 +27,9 @@ TinyMCE AI provides built-in system reviews for comprehensive content analysis: [[custom-reviews]] === Custom Reviews -In addition to system reviews, you can create custom reviews tailored to your specific content quality standards and editorial guidelines. Custom reviews allow you to define specialized analysis criteria using your own prompts to control the review behavior. +In addition to system reviews, custom reviews can be created tailored to specific content quality standards and editorial guidelines. Custom reviews allow defining specialized analysis criteria using custom prompts to control the review behavior. -Unlike system reviews that use predefined identifiers, custom reviews use a unified endpoint where you define the analysis behavior through a prompt parameter. +Unlike system reviews that use predefined identifiers, custom reviews use a unified endpoint where the analysis behavior is defined through a prompt parameter. [[key-features]] == Key Features @@ -144,7 +144,7 @@ Authorization: Bearer } ---- -Custom reviews require the `ai:reviews:custom` permission in your JWT token. +Custom reviews require the `ai:reviews:custom` permission in the JWT token. [[streaming-responses]] == Streaming Responses diff --git a/modules/ROOT/pages/tinymceai-streaming.adoc b/modules/ROOT/pages/tinymceai-streaming.adoc index 65e5602ba9..f21802ca75 100644 --- a/modules/ROOT/pages/tinymceai-streaming.adoc +++ b/modules/ROOT/pages/tinymceai-streaming.adoc @@ -10,7 +10,7 @@ Real-time AI interactions using Server-Sent Events (SSE) for immediate feedback [[overview]] == Overview -TinyMCE AI services use Server-Sent Events (SSE) to provide real-time streaming responses. This allows you to see AI-generated content as it is being created, providing immediate feedback and enabling interactive experiences. +TinyMCE AI services use Server-Sent Events (SSE) to provide real-time streaming responses. This allows users to see AI-generated content as it is being created, providing immediate feedback and enabling interactive experiences. [[sse-event-types]] == SSE Event Types @@ -35,7 +35,7 @@ const response = await fetch('/v1/your-endpoint', { 'Content-Type': 'application/json' }, body: JSON.stringify({ - // Your request payload + // Request payload }) }); diff --git a/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc b/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc index 8eab84fc87..aa6e3d8fec 100644 --- a/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc +++ b/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc @@ -15,7 +15,7 @@ include::partial$auth/private-public-key-pairs-for-tiny-cloud-services.adoc[] == JWT Configuration Requirements -This section explains what needs to be configured for JWT authentication, whether you're using a managed service (such as AWS or Azure JWT services) or setting up a manual endpoint. +This section explains what needs to be configured for JWT authentication, whether using a managed service (such as AWS or Azure JWT services) or setting up a manual endpoint. include::partial$auth/how-jwts-are-used.adoc[] @@ -92,7 +92,7 @@ See xref:tinymceai-permissions.adoc[Permissions] for a complete list of availabl == Set up JWT Endpoint -The following section shows how to create a JWT endpoint manually. If you're using a managed JWT service (such as AWS or Azure), configure it according to the requirements above and skip to the xref:#configure-tinymce[Configure TinyMCE] section. +The following section shows how to create a JWT endpoint manually. If using a managed JWT service (such as AWS or Azure), configure it according to the requirements above and skip to the xref:#configure-tinymce[Configure TinyMCE] section. === Server Setup (jwt.js) @@ -108,7 +108,7 @@ const path = require('path'); // Handles file paths. const app = express(); app.use(cors()); -// Your private key (Replace this with your actual key) +// Private key (Replace this with the actual key) const privateKey = ` -----BEGIN PRIVATE KEY----- {Your private PKCS8 key goes here} @@ -120,7 +120,7 @@ app.use(express.static(path.join(__dirname, 'public'))); // JWT token generation endpoint app.post('/jwt', (req, res) => { const payload = { - aud: 'no-api-key', // Replace with your actual API key + aud: 'no-api-key', // Replace with the actual API key sub: 'user-id', // Replace with actual user identifier iat: Math.floor(Date.now() / 1000), // Issue timestamp exp: Math.floor(Date.now() / 1000) + (60 * 10), // Expiration time (10 minutes) @@ -138,7 +138,7 @@ app.post('/jwt', (req, res) => { }; try { - // Tokens are signed with the RS256 algorithm using your private key + // Tokens are signed with the RS256 algorithm using the private key const token = jwt.sign(payload, privateKey, { algorithm: 'RS256' }); res.json({ token }); } catch (error) { @@ -155,7 +155,7 @@ app.listen(PORT, () => { [NOTE] ==== -The JWT payload includes an `auth.ai.permissions` array that defines what AI features the user can access. Adjust these permissions based on your requirements. See xref:tinymceai-permissions.adoc[Permissions] for more details on available permissions. +The JWT payload includes an `auth.ai.permissions` array that defines what AI features the user can access. Adjust these permissions based on requirements. See xref:tinymceai-permissions.adoc[Permissions] for more details on available permissions. ==== == Configure TinyMCE @@ -163,7 +163,7 @@ The JWT payload includes an `auth.ai.permissions` array that defines what AI fea [[configure-tinymce]] === Web Page (public/index.html) -Inside the `public` folder where you created the `index.html` file add the HTML setup code. +Inside the `public` folder where the `index.html` file was created, add the HTML setup code. [source,html] ---- @@ -206,7 +206,7 @@ include::partial$auth/tinymceai/nodejs/configuration-steps.adoc[] [NOTE] ==== -When you run the project, you should see: +When running the project, the following should be visible: * The {productname} editor * AI feature buttons in the toolbar (`showai`, `aiquickactions`, `aireview`) diff --git a/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc b/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc index 3c35de35b9..a37f586c14 100644 --- a/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc +++ b/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc @@ -15,7 +15,7 @@ include::partial$auth/private-public-key-pairs-for-tiny-cloud-services.adoc[] == JWT Configuration Requirements -This section explains what needs to be configured for JWT authentication, whether you're using a managed service (such as AWS or Azure JWT services) or setting up a manual endpoint. +This section explains what needs to be configured for JWT authentication, whether using a managed service (such as AWS or Azure JWT services) or setting up a manual endpoint. include::partial$auth/how-jwts-are-used.adoc[] @@ -92,7 +92,7 @@ See xref:tinymceai-permissions.adoc[Permissions] for a complete list of availabl == Set up JWT Endpoint -The following section shows how to create a JWT endpoint manually. If you're using a managed JWT service (such as AWS or Azure), configure it according to the requirements above and skip to the xref:#configure-tinymce[Configure TinyMCE] section. +The following section shows how to create a JWT endpoint manually. If using a managed JWT service (such as AWS or Azure), configure it according to the requirements above and skip to the xref:#configure-tinymce[Configure TinyMCE] section. === Server Setup (jwt.php) @@ -112,7 +112,7 @@ function fatalError($message) { // Check for OpenSSL extension if (!extension_loaded('openssl')) { - fatalError('You need to enable the openssl extension in your php.ini.'); + fatalError('The openssl extension must be enabled in php.ini.'); } // Enable CORS @@ -121,7 +121,7 @@ header("Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Ac // JWT payload $payload = array( - "aud" => "no-api-key", // Replace with your actual API key + "aud" => "no-api-key", // Replace with the actual API key "sub" => "user-id", // Replace with actual user identifier "iat" => time(), // Issue timestamp "exp" => time() + 60 * 10, // Expiration time (10 minutes) @@ -139,7 +139,7 @@ $payload = array( ); try { - // Tokens are signed with the RS256 algorithm using your private key + // Tokens are signed with the RS256 algorithm using the private key $privateKey = << response.text()); @@ -85,15 +85,15 @@ The {pluginname} plugin has the following known issues and caveats: === General HTML Support -{pluginname} may not work correctly when General HTML Support for block elements is enabled. This issue will be addressed in future updates. In the meantime, we recommend avoiding configurations that may cause problems. +{pluginname} may not work correctly when General HTML Support for block elements is enabled. This issue will be addressed in future updates. In the meantime, avoid configurations that may cause problems. === Issues with tables -We are aware of certain glitches that may occur when the AI modifies complex tables or layout tables. To prevent data loss, please ensure that the content around these structures remains intact when using {pluginname} tools, while our team investigates the causes and potential solutions to this issue. +Certain glitches may occur when the AI modifies complex tables or layout tables. To prevent data loss, ensure that the content around these structures remains intact when using {pluginname} tools, while the team investigates the causes and potential solutions to this issue. === Editor context and multiple editor handling -While it's possible to use {pluginname} with multiple editors in an editor context, only the first editor registered in the context will currently be able to interact with AI tools and benefit from the content suggestions made by the AI. As our team works on resolving this issue, we recommend using standalone editor instances with {pluginname}. +While it's possible to use {pluginname} with multiple editors in an editor context, only the first editor registered in the context will currently be able to interact with AI tools and benefit from the content suggestions made by the AI. As the team works on resolving this issue, use standalone editor instances with {pluginname}. === Inline image processing issues @@ -101,6 +101,11 @@ Inline images may not be processed correctly by commands within AI review. A sol === Quick actions and content markers issues +[NOTE] +==== +// TODO: Verify with QA about their testing results before finalizing this known issue documentation. +==== + Applying quick action responses may result in the loss of Comments and Suggested Edits suggestion markers. This issue will be addressed in a future update. === Limited interactivity in Chat history @@ -109,6 +114,6 @@ The interactivity of historical AI chat conversations can become limited over ti === Issues with specific AI models -Some AI models may occasionally return empty responses. If this occurs, we recommend sending a follow-up message asking the Assistant to complete the previous request, or starting a new conversation. +Some AI models may occasionally return empty responses. If this occurs, send a follow-up message asking the Assistant to complete the previous request, or start a new conversation. -NOTE: If you wish to stay informed about updates or discuss {pluginname} possibilities, please reach out to us. +NOTE: To stay informed about updates or discuss {pluginname} possibilities, please reach out. diff --git a/modules/ROOT/partials/auth/private-public-key-pairs-for-tiny-cloud-services.adoc b/modules/ROOT/partials/auth/private-public-key-pairs-for-tiny-cloud-services.adoc index 5e4b309b95..456d573004 100644 --- a/modules/ROOT/partials/auth/private-public-key-pairs-for-tiny-cloud-services.adoc +++ b/modules/ROOT/partials/auth/private-public-key-pairs-for-tiny-cloud-services.adoc @@ -1,16 +1,20 @@ -The **{pluginname}** Server requires a _public_ key generated from the same _private_ key that will be used on your JSON Web Token (JWT) provider endpoint. The public key(s) stored on the {pluginname} Server are used to ensure that content is sent by authorized users. +The **{pluginname}** Server requires a _public_ key generated from the same _private_ key that will be used on the JSON Web Token (JWT) provider endpoint. The public key(s) stored on the {pluginname} Server are used to ensure that content is sent by authorized users. -There are two methods for generating and adding a public key in the JWT Keys section of your account portal: +There are two methods for generating and adding a public key in the JWT Keys section of the account portal: . Generate New Keypair at link:{accountjwturl}[{accountpage} - JWT Keys] (recommended). . Generate a key pair locally and Import Public Key at link:{accountjwturl}[{accountpage} - JWT Keys]. -== Generate a key pair using the {accountpage} JWT Keys page +=== Generate a key pair using the {accountpage} JWT Keys page The link:{accountjwturl}[{accountpage} - JWT Keys] page provides a "Generate New Keypair" option, providing a quick and secure way of generating the required keys. This will store a copy of the _public_ key, and provide a downloadable file for both the public and private keys. {companyname} does **not store** the _private_ key and the key pair **cannot** be retrieved later. +=== Generate a key pair locally and add it to the account + +This method involves two steps: generating the key pair locally, then adding the public key to the account portal. + [[generate-a-key-pair-locally]] -== Generate a key pair locally +==== Generate a key pair locally When generating a key pair locally, use one of the supported algorithms. include::partial$auth/jwt-supported-algorithms.adoc[] @@ -19,11 +23,11 @@ For instructions on generating a key pair locally, see: xref:generate-rsa-key-pa [[add-a-public-key-to-the-tiny-cloud-api-key]] ifeval::[{numberedHeading} == true] -= 2. Add a public key in the JWT Keys section of your account portal +==== 2. Add a public key in the JWT Keys section of the account portal endif::[] ifeval::[{numberedHeading} != true] -== Add a public key in the JWT Keys section of your account portal +==== Add a public key in the JWT Keys section of the account portal endif::[] -Once a public key has been generated locally, use the "Import Public Key" option in the JWT Keys section of your account portal at: link:{accountjwturl}[{accountpage} - JWT Keys]. +Once a public key has been generated locally, use the "Import Public Key" option in the JWT Keys section of the account portal at: link:{accountjwturl}[{accountpage} - JWT Keys]. diff --git a/modules/ROOT/partials/auth/tinymceai/jwt-setup-tinymceai.adoc b/modules/ROOT/partials/auth/tinymceai/jwt-setup-tinymceai.adoc index b274431103..0031e6fb95 100644 --- a/modules/ROOT/partials/auth/tinymceai/jwt-setup-tinymceai.adoc +++ b/modules/ROOT/partials/auth/tinymceai/jwt-setup-tinymceai.adoc @@ -3,9 +3,9 @@ To set up JSON Web Token (JWT) authentication for {productname} {pluginname}: -. Add a public key to your {accountpage}, link:https://www.tiny.cloud/auth/login/[login]. +. Add a public key to the {accountpage}, link:https://www.tiny.cloud/auth/login/[login]. . Set up a JSON Web Token (JWT) Provider endpoint via link:{accountjwturl}[{accountpage} - JWT Keys] -. Configure your {productname} to use the JWT endpoint. +. Configure {productname} to use the JWT endpoint. include::partial$auth/private-public-key-pairs-for-tiny-cloud-services.adoc[] diff --git a/modules/ROOT/partials/auth/tinymceai/nodejs/configuration-steps.adoc b/modules/ROOT/partials/auth/tinymceai/nodejs/configuration-steps.adoc index 08e6fdb050..8e8c8fde10 100644 --- a/modules/ROOT/partials/auth/tinymceai/nodejs/configuration-steps.adoc +++ b/modules/ROOT/partials/auth/tinymceai/nodejs/configuration-steps.adoc @@ -1,22 +1,22 @@ == Configuration Steps -=== Add Your API Key +=== Add API Key -* Replace `no-api-key` in both files with your actual {productname} API key +* Replace `no-api-key` in both files with the actual {productname} API key * The API key should be the same in both the HTML script source and the JWT payload -=== Add Your Private Key +=== Add Private Key -* Replace the private key placeholder in `jwt.js` with your actual private key +* Replace the private key placeholder in `jwt.js` with the actual private key * Make sure it's in `PKCS8` format * Keep this key secure and never share it publicly === Configure AI Permissions -* Adjust the `auth.ai.permissions` array in the JWT payload based on your requirements +* Adjust the `auth.ai.permissions` array in the JWT payload based on requirements * See xref:tinymceai-permissions.adoc[Permissions] for available permissions and best practices -=== Running Your Project +=== Running the Project . Start the server: + @@ -25,7 +25,7 @@ node jwt.js ---- -. Open your browser to: `http://localhost:3000` -. You should see: +. Open the browser to: `http://localhost:3000` +. The following should be visible: * The {productname} editor * AI feature buttons in the toolbar (showai, aiquickactions, aireview) diff --git a/modules/ROOT/partials/auth/tinymceai/nodejs/initial-project-setup.adoc b/modules/ROOT/partials/auth/tinymceai/nodejs/initial-project-setup.adoc index bcac3b711a..51213d134e 100644 --- a/modules/ROOT/partials/auth/tinymceai/nodejs/initial-project-setup.adoc +++ b/modules/ROOT/partials/auth/tinymceai/nodejs/initial-project-setup.adoc @@ -1,5 +1,7 @@ == Quick Start Guide +If a Node.js project is not already set up, follow the steps below to create a basic environment for integrating TinyMCE AI with JWT authentication. If a project is already configured, skip this section and proceed to the xref:tinymceai-with-jwt-authentication-nodejs.adoc#jwt-configuration-requirements[JWT Configuration Requirements] section. + === Project Setup [source,bash] @@ -21,13 +23,13 @@ Verify that the `package.json` file now includes the required dependencies. [source,bash] ---- -# Create the public folder for your web files +# Create the public folder for web files mkdir public touch public/index.html touch jwt.js ---- -Your project should look like this: +The project should look like this: [source] ---- diff --git a/modules/ROOT/partials/auth/tinymceai/nodejs/intro-and-prerequisites.adoc b/modules/ROOT/partials/auth/tinymceai/nodejs/intro-and-prerequisites.adoc index 38c4dd2627..2bc6655d07 100644 --- a/modules/ROOT/partials/auth/tinymceai/nodejs/intro-and-prerequisites.adoc +++ b/modules/ROOT/partials/auth/tinymceai/nodejs/intro-and-prerequisites.adoc @@ -4,9 +4,9 @@ This guide provides a comprehensive walkthrough for integrating {pluginname} with {productname}, including {pluginname} functionality, by using a Node.js server for JWT token generation. It covers project setup, server configuration, and {productname} customization. -=== What You'll Build +=== What Will Be Built -Before diving into the technical details, here's what you'll achieve with this guide: +Before diving into the technical details, here's what will be achieved with this guide: * A working {productname} editor running the {pluginname} plugin * A secure authentication system using JWT tokens @@ -21,11 +21,11 @@ This guide is designed for developers new to JWT authentication and {productname Before starting, ensure you have: -* Node.js installed on your computer (to check, run `node -v` in your terminal) +* Node.js installed on the computer (to check, run `node -v` in the terminal) * A {productname} API key with TinyMCE AI enabled (get one from link:https://www.tiny.cloud/signup[TinyMCE's website]) * Basic familiarity with the command line [IMPORTANT] ==== -Make sure you have your API key ready before starting. You'll need it for both the server and client configuration. +Make sure the API key is ready before starting. It will be needed for both the server and client configuration. ==== diff --git a/modules/ROOT/partials/auth/tinymceai/php/configuration-steps.adoc b/modules/ROOT/partials/auth/tinymceai/php/configuration-steps.adoc index 53aa83f2ea..8879c3ab95 100644 --- a/modules/ROOT/partials/auth/tinymceai/php/configuration-steps.adoc +++ b/modules/ROOT/partials/auth/tinymceai/php/configuration-steps.adoc @@ -1,22 +1,22 @@ == Configuration Steps -=== Add Your API Key +=== Add API Key -* Replace `no-api-key` in both files with your actual {productname} API key +* Replace `no-api-key` in both files with the actual {productname} API key * The API key should be the same in both the HTML script source and the JWT payload -=== Add Your Private Key +=== Add Private Key -* Replace the private key placeholder in `jwt.php` with your actual private key +* Replace the private key placeholder in `jwt.php` with the actual private key * Make sure it's in `PKCS8` format * Keep this key secure and never share it publicly === Configure AI Permissions -* Adjust the `auth.ai.permissions` array in the JWT payload based on your requirements +* Adjust the `auth.ai.permissions` array in the JWT payload based on requirements * See xref:tinymceai-permissions.adoc[Permissions] for available permissions and best practices -=== Running Your Project +=== Running the Project . Start the server: + @@ -25,7 +25,7 @@ php -S localhost:3000 ---- -. Open your browser to: `http://localhost:3000` -. You should see: +. Open the browser to: `http://localhost:3000` +. The following should be visible: * The {productname} editor * AI feature buttons in the toolbar (showai, aiquickactions, aireview) diff --git a/modules/ROOT/partials/auth/tinymceai/php/initial-project-setup.adoc b/modules/ROOT/partials/auth/tinymceai/php/initial-project-setup.adoc index 5240d90c8b..b8f8f89a3c 100644 --- a/modules/ROOT/partials/auth/tinymceai/php/initial-project-setup.adoc +++ b/modules/ROOT/partials/auth/tinymceai/php/initial-project-setup.adoc @@ -16,7 +16,7 @@ extension_dir='ext' ---- [TIP] -The path to the extension directory may vary depending on your system. +The path to the extension directory may vary depending on the system. == Quick Start Guide @@ -35,12 +35,12 @@ composer require firebase/php-jwt [source,bash] ---- -# Create the public folder for your web files +# Create the public folder for web files touch index.html touch jwt.php ---- -Your project should look like this: +The project should look like this: [source] ---- diff --git a/modules/ROOT/partials/auth/tinymceai/php/intro-and-prerequisites.adoc b/modules/ROOT/partials/auth/tinymceai/php/intro-and-prerequisites.adoc index ac5231353c..fcd71e337b 100644 --- a/modules/ROOT/partials/auth/tinymceai/php/intro-and-prerequisites.adoc +++ b/modules/ROOT/partials/auth/tinymceai/php/intro-and-prerequisites.adoc @@ -4,9 +4,9 @@ This guide provides a comprehensive walkthrough for integrating {pluginname} with {productname}, including {pluginname} functionality, by using a PHP server for JWT token generation. It covers project setup, server configuration, and {productname} customization. -=== What You'll Build +=== What Will Be Built -Before diving into the technical details, here's what you'll achieve with this guide: +Before diving into the technical details, here's what will be achieved with this guide: * A working {productname} editor running the {pluginname} plugin * A secure authentication system using JWT tokens @@ -21,13 +21,13 @@ This guide is designed for developers new to JWT authentication and {productname Before starting, ensure you have: -* PHP installed on your computer (to check, run `php -v` in your terminal) -* OpenSSL installed on your computer (to check, run `openssl version` in your terminal) -* Composer installed on your computer (to check, run `composer -v` in your terminal) +* PHP installed on the computer (to check, run `php -v` in the terminal) +* OpenSSL installed on the computer (to check, run `openssl version` in the terminal) +* Composer installed on the computer (to check, run `composer -v` in the terminal) * A {productname} API key with TinyMCE AI enabled (get one from link:https://www.tiny.cloud/signup[TinyMCE's website]) * Basic familiarity with the command line [IMPORTANT] ==== -Make sure you have your API key ready before starting. You'll need it for both the server and client configuration. +Make sure the API key is ready before starting. It will be needed for both the server and client configuration. ==== diff --git a/modules/ROOT/partials/commands/tinymceai-cmds.adoc b/modules/ROOT/partials/commands/tinymceai-cmds.adoc index 33104ed01f..540f410e65 100644 --- a/modules/ROOT/partials/commands/tinymceai-cmds.adoc +++ b/modules/ROOT/partials/commands/tinymceai-cmds.adoc @@ -2,24 +2,17 @@ |=== |Command name |Description -|`tinymceai-toggle-sidebar` |Toggle the AI sidebar interface visibility. Accepts an optional object parameter with `type` ('static' or 'floating') and optional `view` (e.g., 'chat', 'review', 'actions') to open a specific view. -|`TinyMCEAIDumpDiagnostics` |Download diagnostic information for troubleshooting purposes. +|`tinymceai-toggle-sidebar` |Toggle the AI sidebar interface visibility. |=== +[NOTE] +==== +The command name may be changed to camelCase in a future version (e.g., `tinymceaiToggleSidebar`). +==== + .Examples [source,js] ---- // Toggle the AI sidebar editor.execCommand('tinymceai-toggle-sidebar'); - -// Open the sidebar with a specific view (e.g., 'chat') -editor.execCommand('tinymceai-toggle-sidebar', false, { - type: 'static', - view: 'chat' -}); - -// Close the sidebar -editor.execCommand('tinymceai-toggle-sidebar', false, { - type: 'static' -}); ---- diff --git a/modules/ROOT/partials/configuration/tinymceai_document_id.adoc b/modules/ROOT/partials/configuration/tinymceai_document_id.adoc new file mode 100644 index 0000000000..96b4df1401 --- /dev/null +++ b/modules/ROOT/partials/configuration/tinymceai_document_id.adoc @@ -0,0 +1,31 @@ +[[tinymceai-document-id]] +== `+tinymceai_document_id+` + +This option sets the unique identifier for the document being edited. This ID is essential for maintaining xref:tinymceai-chat.adoc[Chat] history across different sessions, ensuring that AI conversations are properly associated with the specific document being edited. When users interact with AI features, their chat history is preserved and linked to this document ID, allowing them to continue conversations from previous sessions. + +*Type:* `+String+` + +*Default value:* `+undefined+` + +.Example: using `tinymceai_document_id` option +[source,javascript] +---- +tinymce.init({ + selector: 'textarea', // Change this value according to the HTML + plugins: 'tinymceai', + tinymceai_document_id: 'document-123', // Replace with the actual document ID + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + } +}); +---- + +[NOTE] +==== +The `tinymceai_document_id` configuration uses a dedicated namespace in the configuration. This namespace may be subject to change in future versions as the AI integration architecture continues to be refined. +==== + +[NOTE] +==== +Each document should have a unique `tinymceai_document_id`. Reusing the same ID for different documents will cause chat history to be shared between those documents, which may lead to unexpected behavior. +==== diff --git a/modules/ROOT/partials/configuration/tinymceai_token_provider.adoc b/modules/ROOT/partials/configuration/tinymceai_token_provider.adoc index 1d8d24131d..2e9092b67e 100644 --- a/modules/ROOT/partials/configuration/tinymceai_token_provider.adoc +++ b/modules/ROOT/partials/configuration/tinymceai_token_provider.adoc @@ -19,7 +19,7 @@ tinymce.init({ }); ---- -NOTE: In production, you should fetch the JWT token from your backend server rather than hardcoding it. For example: +NOTE: In production, fetch the JWT token from the backend server rather than hardcoding it. For example: [source,js] ---- From da64a12392fb52e35b4e050fa351c9146b364283 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 16 Feb 2026 16:52:45 +1000 Subject: [PATCH 07/10] DOC-3356: Update, improve example and context around tinymceai_quickactions_menu. --- .../ROOT/pages/tinymceai-actions-plugin.adoc | 43 +++++++++++-------- 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/modules/ROOT/pages/tinymceai-actions-plugin.adoc b/modules/ROOT/pages/tinymceai-actions-plugin.adoc index c5301d3776..d74a07c007 100644 --- a/modules/ROOT/pages/tinymceai-actions-plugin.adoc +++ b/modules/ROOT/pages/tinymceai-actions-plugin.adoc @@ -37,7 +37,7 @@ To learn more about toolbar configuration, refer to the xref:toolbar-configurati image::https://placehold.net/default.png[TinyMCE AI Quick Actions dropdown in the toolbar] -Finally, individual Quick Actions can also be added to the toolbar as shortcuts for even easier access. For example, add the `ask-ai` image:https://placehold.net/default.png[Ask AI icon,24px] button, or the `improve-writing` image:https://placehold.net/default.png[Improve Writing icon,24px] button (find it in the demo above). Whole categories can be added to the toolbar, too. xref:tinymceai-actions-plugin.adoc#default-actions[Learn more about available actions]. +Finally, individual Quick Actions can also be added to the toolbar as shortcuts for even easier access. For example, add the `tinymceai-improve-writing` image:https://placehold.net/default.png[Improve Writing icon,24px] button, or the `tinymceai-explain` image:https://placehold.net/default.png[Explain icon,24px] button (find it in the demo above). Whole categories can be added to the toolbar, too. xref:tinymceai-actions-plugin.adoc#default-actions[Learn more about available actions]. The final example configuration looks as follows: @@ -51,23 +51,31 @@ tinymce.init({ }, // Adding Quick Actions to the main editor toolbar. - toolbar: [ - // The main Quick Actions button - 'tinymceai-actions', - - // Two individual actions - 'ask-ai', - 'improve-writing', - - // Whole action category - 'translate', - - // ... other toolbar items - ], + toolbar: 'undo redo showai aiquickactions aireview | styles | bold italic underline strikethrough | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | link image', - // Adding Quick Actions to the balloon toolbar. Since some of the actions are selection-sensitive, + // Adding Quick Actions to the context toolbar (selection toolbar). Since some of the actions are selection-sensitive, // accessing them might be easier for users using this kind of toolbar. - quickbars_selection_toolbar: 'tinymceai-actions | ask-ai | improve-writing | translate' + tinymceai_context_toolbar: 'showai aiquickactions aireview', + + // Configure the main Quick Actions menu + tinymceai_quickactions_menu: [ + 'tinymceai-chat-commands', + 'tinymceai-improve-writing', + 'tinymceai-continue', + 'tinymceai-fix-grammar', + 'tinymceai-adjust-length', + 'tinymceai-change-tone', + 'tinymceai-translate' + ], + + // Configure a sub-menu (e.g., chat commands) + tinymceai_chat_commands_menu: [ + 'tinymceai-explain', + 'tinymceai-summarize', + 'tinymceai-highlight-key-points' + ], + + tinymceai_sidebar_type: 'static' }); ---- @@ -76,7 +84,7 @@ tinymce.init({ There are two types of actions available in the quick actions feature: -* Chat actions, such as "Explain" or "Summarize", open the xref:tinymceai-chat.adoc[Chat] interface with the selected text added as context and automatically start the conversation with a pre-filled prompt. Actions like "Ask AI" open the Chat interface and allow users to start typing their message. +* Chat actions, such as "Explain" or "Summarize", open the xref:tinymceai-chat.adoc[Chat] interface with the selected text added as context and automatically start the conversation with a pre-filled prompt. * Preview actions, such as "Continue writing", "Make shorter", "Improve writing", or "Fix grammar", display the AI response in a preview interface where users can review and accept or reject the suggested changes. @@ -91,7 +99,6 @@ Keep in mind that xref:tinymceai-actions-plugin.adoc#custom-actions[custom actio Here's the full list of available actions: -* `'ask-ai'` * **"Chat commands"** category (`'chat-commands'`) ** `'explain'` ** `'summarize'` From 74e85f45996712fd8e6552b3d0c969b0d510afe3 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Tue, 17 Feb 2026 15:29:44 +1000 Subject: [PATCH 08/10] DOC-3356: Restructure JWT auth docs, add permissions page with tables, move security content to intro, fix API quick start links. --- modules/ROOT/nav.adoc | 39 +-- .../ROOT/pages/tinymceai-actions-plugin.adoc | 66 +++- modules/ROOT/pages/tinymceai-actions.adoc | 206 ----------- .../ROOT/pages/tinymceai-api-overview.adoc | 41 +-- .../ROOT/pages/tinymceai-api-quick-start.adoc | 23 +- modules/ROOT/pages/tinymceai-chat.adoc | 71 +++- .../ROOT/pages/tinymceai-conversations.adoc | 155 --------- modules/ROOT/pages/tinymceai-integration.adoc | 327 ------------------ .../ROOT/pages/tinymceai-introduction.adoc | 34 +- .../tinymceai-jwt-authentication-intro.adoc | 74 ++++ modules/ROOT/pages/tinymceai-limits.adoc | 2 +- modules/ROOT/pages/tinymceai-models.adoc | 90 ++++- modules/ROOT/pages/tinymceai-permissions.adoc | 223 ++++++------ .../ROOT/pages/tinymceai-review-plugin.adoc | 65 +++- modules/ROOT/pages/tinymceai-reviews.adoc | 169 --------- modules/ROOT/pages/tinymceai-streaming.adoc | 20 +- ...ymceai-with-jwt-authentication-nodejs.adoc | 4 +- ...tinymceai-with-jwt-authentication-php.adoc | 4 +- modules/ROOT/pages/tinymceai.adoc | 140 +++++++- 19 files changed, 666 insertions(+), 1087 deletions(-) delete mode 100644 modules/ROOT/pages/tinymceai-actions.adoc delete mode 100644 modules/ROOT/pages/tinymceai-conversations.adoc delete mode 100644 modules/ROOT/pages/tinymceai-integration.adoc create mode 100644 modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc delete mode 100644 modules/ROOT/pages/tinymceai-reviews.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 86cc274dc1..b1cb83bccb 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -262,30 +262,21 @@ **** xref:ai-proxy.adoc[AI proxy server reference guide] *** TinyMCE AI **** xref:tinymceai-introduction.adoc[Introduction] -***** xref:tinymceai-chat.adoc[Chat] -***** xref:tinymceai-review-plugin.adoc[Review] -***** xref:tinymceai-actions-plugin.adoc[Actions] -***** xref:tinymceai-integration.adoc[Integration] -***** xref:tinymceai-integration-options.adoc[Integration Options] -****** xref:tinymceai.adoc[Plugin quick start] -****** REST API -******* xref:tinymceai-api-overview.adoc[API Overview] -******* xref:tinymceai-api-quick-start.adoc[API quick start] -******* Features -******** xref:tinymceai-conversations.adoc[Conversations] -******** xref:tinymceai-reviews.adoc[Reviews] -******** xref:tinymceai-actions.adoc[Actions] -******* Configuration -******** xref:tinymceai-models.adoc[AI models] -******** xref:tinymceai-permissions.adoc[Permissions] -******** xref:tinymceai-limits.adoc[Limits] -******** xref:tinymceai-streaming.adoc[Streaming] -******* Integration -******** xref:tinymceai-api-overview.adoc#data-handling-and-security[Data Handling and Security] - -******** xref:tinymceai-api-overview.adoc#security-features[Security] -******** xref:tinymceai-api-overview.adoc#on-premises-deployment[On-premises deployment] -***** JWT Authentication +**** xref:tinymceai-chat.adoc[Chat] +**** xref:tinymceai-review-plugin.adoc[Review] +**** xref:tinymceai-actions-plugin.adoc[Actions] +**** xref:tinymceai-integration-options.adoc[Integration Options] +***** xref:tinymceai.adoc[Plugin quick start] +***** REST API +****** xref:tinymceai-api-overview.adoc[API Overview] +****** xref:tinymceai-api-quick-start.adoc[API quick start] +****** Configuration +******* xref:tinymceai-models.adoc[AI models] +******* xref:tinymceai-limits.adoc[Limits] +******* xref:tinymceai-streaming.adoc[Streaming] +**** xref:tinymceai-jwt-authentication-intro.adoc[JWT Authentication] +***** xref:tinymceai-permissions.adoc[Permissions] +***** Guides ****** xref:tinymceai-with-jwt-authentication-nodejs.adoc[JWT authentication (Node.js)] ****** xref:tinymceai-with-jwt-authentication-php.adoc[JWT authentication (PHP)] *** xref:casechange.adoc[Case Change] diff --git a/modules/ROOT/pages/tinymceai-actions-plugin.adoc b/modules/ROOT/pages/tinymceai-actions-plugin.adoc index d74a07c007..7093cccb26 100644 --- a/modules/ROOT/pages/tinymceai-actions-plugin.adoc +++ b/modules/ROOT/pages/tinymceai-actions-plugin.adoc @@ -7,14 +7,16 @@ Quick actions streamline routine content transformations by offering one-click AI-powered suggestions directly within the editor. This feature enhances speed, relevance, and usability, particularly for repeatable or simple tasks. The feature comes with an easy-to-use window interface but can also act as a conversation starter with the xref:tinymceai-chat.adoc[Chat]. +The Quick Actions feature is available as a plugin UI and via the xref:tinymceai-actions-plugin.adoc#actions-api[Actions API]. This page covers both: + +* Plugin sections describe user-facing features and configuration. +* API sections cover REST API access (starting at xref:tinymceai-actions-plugin.adoc#actions-api[Actions API]). + [[demo]] == Demo liveDemo::tinymceai[] -[[overview]] -== Overview - Actions are fast, stateless operations that transform content directly. Unlike Reviews that provide suggestions, Actions immediately modify content based on the selected operation. **When to use Actions vs Reviews:** Use Actions when transforming a selection or small section of text (fix grammar, translate, adjust tone). Use Reviews when analyzing entire documents for quality improvements and getting suggestions without automatically changing the content. @@ -24,7 +26,7 @@ image::https://placehold.net/default.png[TinyMCE AI quick actions showing AI-pow [[integration]] == Integration -To start using the Quick Actions feature, first load the TinyMCE AI plugin in the editor configuration. xref:tinymceai-integration.adoc[Learn more about installing and enabling AI features]. +To start using the Quick Actions feature, first load the TinyMCE AI plugin in the editor configuration. See xref:tinymceai.adoc[Plugin Reference] for installation and enabling AI features. Then, add the menu that opens the list of Quick Actions (`tinymceai-actions`) image:https://placehold.net/default.png[Quick Actions icon,24px] to the main toolbar and/or context toolbar (selection toolbar) configurations. @@ -200,10 +202,62 @@ tinymce.init({ }); ---- +[[actions-api]] +== Actions API + +The Quick Actions plugin feature is built on top of the Actions API, which provides REST API access to action functionality. Actions are fast, stateless operations that transform content directly. Unlike Reviews that provide suggestions, Actions immediately modify your content based on the selected operation. + +**When to use Actions vs Reviews:** Use Actions when you need to transform specific text content (fix grammar, translate, adjust tone). Use Reviews when you need to analyze entire documents for quality improvements and get suggestions without automatically changing the content. + +Unlike conversations, actions do not remember previous interactions. Each action is independent and focused on a single task. Actions use streaming output with Server-Sent Events for real-time feedback as results are generated. + +[[actions-system-actions-api]] +=== System Actions + +TinyMCE AI provides built-in system actions for common content transformations via the API. These correspond to the default actions available in the plugin UI: + +* **Fix Grammar** (`fix-grammar`) – Correct grammar, spelling, and punctuation errors. See https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] for the fix grammar endpoint. +* **Improve Writing** (`improve-writing`) – Enhance clarity, word choice, and sentence structure. See https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] for the improve writing endpoint. +* **Continue Writing** (`continue`) – Complete unfinished sentences, paragraphs, or entire documents. See https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] for the continue writing endpoint. +* **Make Longer** (`make-longer`) – Expand content with more detail, examples, and explanations. See https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] for the make longer endpoint. +* **Make Shorter** (`make-shorter`) – Condense lengthy text while keeping the essential information. See https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] for the make shorter endpoint. +* **Adjust Tone** (`make-tone-*`) – Change writing style to casual, professional, friendly, or confident. See https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] for tone adjustment endpoints. +* **Translate** (`translate-*`) – Convert content between languages with proper cultural context. See https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] for the translation endpoint. + +[[actions-custom-actions-api]] +=== Custom Actions via API + +In addition to system actions, you can create custom actions tailored to your specific use cases via the API. Custom actions allow you to define specialized content transformations using your own prompts to control AI behavior. + +Unlike system actions that use predefined identifiers, custom actions use a unified endpoint where you define the transformation behavior through a prompt parameter. See https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] for the custom actions endpoint and implementation details. + +Custom actions require the `ai:actions:custom` permission in your JWT token. + +[[actions-streaming]] +=== Streaming Responses + +Actions use Server-Sent Events (SSE) for real-time streaming results. See the xref:tinymceai-streaming.adoc[Streaming Responses guide] for detailed implementation information. + +[[actions-api-reference]] +=== API Reference + +For complete endpoint documentation, request/response schemas, authentication details, and additional parameters, see: + +* **https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API Reference]** – Full documentation for system and custom actions endpoints with interactive examples + +The REST API documentation includes examples for: + +* Grammar fix - see https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] +* Writing improvement - see https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] +* Content expansion (make longer) - see https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] +* Content condensation (make shorter) - see https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] +* Tone adjustment - see https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] +* Translation - see https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] +* Custom actions with custom prompts - see https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] +* Streaming responses - see https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] + [[related-features]] == Related Features * xref:tinymceai-chat.adoc[AI chat] – For interactive discussions with document analysis and context. * xref:tinymceai-review-plugin.adoc[AI review] – For content quality analysis and improvement suggestions. -* xref:tinymceai-actions.adoc[Actions API] – For API-level action functionality. -* xref:tinymceai-introduction.adoc[Introduction] – Overview of all TinyMCE AI features. diff --git a/modules/ROOT/pages/tinymceai-actions.adoc b/modules/ROOT/pages/tinymceai-actions.adoc deleted file mode 100644 index 994a42d2be..0000000000 --- a/modules/ROOT/pages/tinymceai-actions.adoc +++ /dev/null @@ -1,206 +0,0 @@ -= TinyMCE AI Quick Actions - -:navtitle: Quick Actions -:description: Quick actions feature for {productname} -:description_short: Quick actions feature -:keywords: AI, quick actions, actions, tinymceai - -Actions are fast, stateless operations that transform content directly. Unlike Reviews that provide suggestions, Actions immediately modify your content based on the selected operation. - -**When to use Actions vs Reviews:** Use Actions when you need to transform specific text content (fix grammar, translate, adjust tone). Use Reviews when you need to analyze entire documents for quality improvements and get suggestions without automatically changing the content. - -Unlike conversations, actions do not remember previous interactions. Each action is independent and focused on a single task. - -[[available-actions]] -== Available Actions - -[[system-actions]] -=== System Actions - -TinyMCE AI provides built-in system actions for common content transformations: - -* **Fix Grammar** – Correct grammar, spelling, and punctuation errors. -* **Improve Writing** – Enhance clarity, word choice, and sentence structure. -* **Continue Writing** – Complete unfinished sentences, paragraphs, or entire documents. -* **Make Longer** – Expand content with more detail, examples, and explanations. -* **Make Shorter** – Condense lengthy text while keeping the essential information. -* **Adjust Tone** – Change writing style to casual, professional, friendly, or confident. -* **Translate** – Convert content between languages with proper cultural context. - -[[custom-actions]] -=== Custom Actions - -In addition to system actions, you can create custom actions tailored to your specific use cases. Custom actions allow you to define specialized content transformations using your own prompts to control AI behavior. - -Unlike system actions that use predefined identifiers, custom actions use a unified endpoint where you define the transformation behavior through a prompt parameter. - -[[key-features]] -== Key Features - -Each action is independent and does not require conversation context. Actions use streaming output with Server-Sent Events for real-time feedback as results are generated. - -[[api-examples]] -== API Examples - -[[grammar-fix-example]] -=== Grammar Fix Example - -[source,http] ----- -POST /v1/actions/system/fix-grammar/calls -Content-Type: application/json -Authorization: Bearer - -{ - "content": [ - { - "type": "text", - "content": "

The norhtern lights dence across the polar skies, painting ribbons of green and purple light that ripple like a cosmic curtain.

" - } - ] -} ----- - -[[writing-improvement-example]] -=== Writing Improvement Example - -[source,http] ----- -POST /v1/actions/system/improve-writing/calls -Content-Type: application/json -Authorization: Bearer - -{ - "content": [ - { - "type": "text", - "content": "

The system works by processing data through various algorithms to produce results.

" - } - ] -} ----- - -[[content-expansion]] -=== Content Expansion - -[source,http] ----- -POST /v1/actions/system/make-longer/calls -Content-Type: application/json -Authorization: Bearer - -{ - "content": [ - { - "type": "text", - "content": "

Artificial intelligence is transforming the way we work.

" - } - ] -} ----- - -[[content-condensation-example]] -=== Content Condensation Example - -[source,http] ----- -POST /v1/actions/system/make-shorter/calls -Content-Type: application/json -Authorization: Bearer - -{ - "content": [ - { - "type": "text", - "content": "

Artificial intelligence, which is a rapidly evolving field of computer science that focuses on creating intelligent machines capable of performing tasks that typically require human intelligence, is transforming the way we work across various industries and sectors.

" - } - ] -} ----- - -[[tone-adjustment-example]] -=== Tone Adjustment Example - -[source,http] ----- -POST /v1/actions/system/make-tone-casual/calls -Content-Type: application/json -Authorization: Bearer - -{ - "content": [ - { - "type": "text", - "content": "

We regret to inform you that your request cannot be processed at this time.

" - } - ] -} ----- - -[[translation-example]] -=== Translation Example - -[source,http] ----- -POST /v1/actions/system/translate/calls -Content-Type: application/json -Authorization: Bearer - -{ - "content": [ - { - "type": "text", - "content": "

Hello, how are you today?

" - } - ], - "args": { - "language": "Spanish" - } -} ----- - -[[custom-action-example]] -=== Custom Action Example - -[source,http] ----- -POST /v1/actions/custom/calls -Content-Type: application/json -Authorization: Bearer - -{ - "content": [ - { - "type": "text", - "content": "

The company's Q4 revenue was $2.5M, representing a 15% increase YoY.

" - } - ], - "prompt": "Convert financial abbreviations to full words (e.g., 'YoY' to 'year-over-year', 'Q4' to 'fourth quarter') to make the text more accessible to general audiences.", - "model": "agent-1", - "outputFormat": "html" -} ----- - -Custom actions require the `ai:actions:custom` permission in your JWT token. - -[[streaming-responses]] -== Streaming Responses - -Actions use Server-Sent Events (SSE) for real-time streaming results. See the xref:tinymceai-streaming.adoc[Streaming Responses guide] for detailed implementation information. - -[[api-reference]] -== API Reference - -For complete endpoint documentation, request/response schemas, authentication details, and additional parameters, see: - -* **https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API Reference]** – Full documentation for system and custom actions endpoints. -* **https://tinymceai.api.tiny.cloud/docs[Complete API Documentation]** – Interactive API reference with all TinyMCE AI endpoints. - -[[related-features]] -== Related Features - -* xref:tinymceai-actions-plugin.adoc[AI Quick Actions Plugin] – For plugin integration and UI configuration. -* xref:tinymceai-conversations.adoc[Conversations API] – For interactive discussions with document analysis and context. -* xref:tinymceai-reviews.adoc[Reviews API] – For content quality analysis and improvement suggestions. -* xref:tinymceai-streaming.adoc[Streaming Responses] – For implementing real-time review suggestions. -* xref:tinymceai-api-overview.adoc[API Overview] – Overview of all API features. diff --git a/modules/ROOT/pages/tinymceai-api-overview.adoc b/modules/ROOT/pages/tinymceai-api-overview.adoc index 135b85f861..ea84c8e588 100644 --- a/modules/ROOT/pages/tinymceai-api-overview.adoc +++ b/modules/ROOT/pages/tinymceai-api-overview.adoc @@ -20,9 +20,9 @@ New to TinyMCE AI? Kick your adventure off with the xref:tinymceai-api-quick-sta [[tinymce-ai-features]] == TinyMCE AI features -* xref:tinymceai-conversations.adoc[**Conversations**] – Interactive AI chats with history and persistent context. -* xref:tinymceai-reviews.adoc[**Reviews**] – Content analysis and proofreading, optimized for larger content. -* xref:tinymceai-actions.adoc[**Actions**] – Fast, stateless operations for specific tasks. +* xref:tinymceai-chat.adoc[**Chat**] – Interactive AI chats with history and persistent context. +* xref:tinymceai-review-plugin.adoc[**Review**] – Content analysis and proofreading, optimized for larger content. +* xref:tinymceai-actions-plugin.adoc[**Quick Actions**] – Fast, stateless operations for specific tasks. [[architecture]] == Architecture @@ -34,41 +34,6 @@ The following pages cover the system architecture. * xref:tinymceai-permissions.adoc[**Permissions**] – How to control user access to features. * xref:tinymceai-limits.adoc[**Limits**] – Rate limits, context size limits, and file restrictions. -[[data-handling-and-security]] -== Data Handling and Security - -[[regional-data-storage]] -=== Regional Data Storage - -All data stored by TinyMCE AI follows the region settings of your TinyMCE Cloud Services environment, ensuring compliance with data residency requirements and optimal performance for your geographic location. - -[TIP] -==== -**Important**: Data sent to LLM providers for processing is currently processed in the US region, regardless of your Cloud Services environment region. -==== - -[[data-retention-policy]] -=== Data Retention Policy - -Conversation data is automatically deleted after 12 months of inactivity, including: - -* all conversation messages and history, -* attached documents, files, and web resources, -* conversation metadata and settings. - -[[security]] -=== Security - -All data is encrypted in transit and at rest with end-to-end encryption. Conversations and attachments are stored in secure cloud infrastructure with fine-grained access control and comprehensive permission systems. Audit Logs are available through our Customer Portal and the API. - -[[on-premises-deployment]] -== On-Premises Deployment - -[TIP] -==== -**Coming Soon**: On-premises deployment is currently in development. Follow TinyMCE social accounts and our newsletter for updates. -==== - [[resources-and-support]] == Resources and Support diff --git a/modules/ROOT/pages/tinymceai-api-quick-start.adoc b/modules/ROOT/pages/tinymceai-api-quick-start.adoc index 2a22a7927f..bc64cd4120 100644 --- a/modules/ROOT/pages/tinymceai-api-quick-start.adoc +++ b/modules/ROOT/pages/tinymceai-api-quick-start.adoc @@ -66,23 +66,24 @@ All features are accessible through the API at `https://tinymceai.api.tiny.cloud For an overview of all API features, see xref:tinymceai-api-overview.adoc[API Overview]. -For detailed API examples and implementation guides, see: +For feature documentation and API access information, see: -* xref:tinymceai-conversations.adoc[Conversations] – Interactive AI discussions and document analysis. -* xref:tinymceai-reviews.adoc[Reviews] – Content improvement and quality analysis. -* xref:tinymceai-actions.adoc[Actions] – Content transformation and batch processing. -* xref:tinymceai-streaming.adoc[Streaming] – Real-time AI interactions. +* xref:tinymceai-chat.adoc#conversations-api[Chat] – Interactive AI discussions and document analysis via the Conversations API. +* xref:tinymceai-review-plugin.adoc#reviews-api[Review] – Content improvement and quality analysis via the Reviews API. +* xref:tinymceai-actions-plugin.adoc#actions-api[Quick Actions] – Content transformation via the Actions API. +* xref:tinymceai-streaming.adoc[Streaming] – Real-time AI interactions with code examples. -link:https://tinymceai.api.tiny.cloud/docs[Complete API Documentation] – Full API reference for TinyMCE AI +link:https://tinymceai.api.tiny.cloud/docs[Complete API Documentation] – Full API reference with interactive examples for all endpoints [[next-steps]] == Next Steps -Now that you made your first API call, explore the features: +After setting up your JWT endpoint, continue with: -* xref:tinymceai-api-overview.adoc[API Overview] – Overview of all API features, data handling, and security. -* xref:tinymceai-conversations.adoc[Conversations] – Start with interactive AI discussions. +* xref:tinymceai-api-overview.adoc[API Overview] – Overview of all API features and capabilities. * xref:tinymceai-models.adoc[AI Models] – Choose the right model for your use case. * xref:tinymceai-permissions.adoc[Permissions] – Set up user access control for production. -* xref:tinymceai-reviews.adoc[Reviews] – Add content improvement features. -* xref:tinymceai-actions.adoc[Actions] – Implement content transformation. +* xref:tinymceai-streaming.adoc[Streaming] – Learn how to handle real-time streaming responses. +* xref:tinymceai-chat.adoc#conversations-api[Chat API] – Start with interactive AI discussions. +* xref:tinymceai-review-plugin.adoc#reviews-api[Review API] – Add content improvement features. +* xref:tinymceai-actions-plugin.adoc#actions-api[Quick Actions API] – Implement content transformation. diff --git a/modules/ROOT/pages/tinymceai-chat.adoc b/modules/ROOT/pages/tinymceai-chat.adoc index 89b3acdf06..60c501acc3 100644 --- a/modules/ROOT/pages/tinymceai-chat.adoc +++ b/modules/ROOT/pages/tinymceai-chat.adoc @@ -5,12 +5,15 @@ :description_short: AI Chat feature :keywords: AI, chat, conversations, tinymceai -The TinyMCE AI Chat is a conversational AI that can be used to aid content creation and editing. It introduces a dynamic chat interface designed to facilitate rich, multi-turn interactions between users and an AI Assistant. This capability moves beyond single-prompt content generation, enabling a more interactive and collaborative experience within writing workflows. +The TinyMCE AI Chat is a conversational AI that facilitates rich, multi-turn interactions between users and an AI Assistant for content creation and editing. It provides context setting, model selection, chat history, and capabilities for web search and reasoning. -[[overview]] -== Overview +The Chat feature is available as a plugin UI and via the xref:tinymceai-chat.adoc#conversations-api[Conversations API]. This page covers both: -The Chat feature provides context setting and model selection to better suit the needs of specific content and holds chat history for quick reference of previous work. The Chat is also capable of using the web for more up-to-date information and reasoning to think more deeply about the answers and changes it is allowed to make. +* Plugin sections describe user-facing features and configuration. +* API sections cover REST API access (starting at xref:tinymceai-chat.adoc#conversations-api[Conversations API]). + +[[using-chat]] +== Using Chat image::https://placehold.net/default.png[TinyMCE AI Chat interface showing the conversational AI assistant] @@ -73,7 +76,7 @@ Model selection for AI chat can be configured using three separate configuration * `tinymceai_allow_model_selection`: Control whether users can select from available models (defaults to `true`). * `tinymceai_allowed_models`: Specify an array of allowed model IDs that users can select from. -xref:tinymceai-integration.adoc#supported-ai-models[Learn more about available AI models]. +xref:tinymceai-models.adoc#supported-models-table[Learn more about available AI models]. [source,js] ---- @@ -182,21 +185,61 @@ The ability to apply suggestions to the document or generate Suggested Edits fro After closing the browser and reopening AI chat, previous conversations will no longer interact with the document content. To continue working with a conversation, reopen it from the chat history. ==== -[[advanced-features]] -== Advanced Features +[[conversations-api]] +== Conversations API + +The Chat plugin feature is built on top of the Conversations API, which provides REST API access to conversation functionality. Conversations allow exchanging multiple messages with AI that maintains them in its context. Conversations can be extended by external context sources like websites or files, and have the ability to refer to editor content and suggest modifications. + +[[conversations-key-features]] +=== Key Features + +Upload PDFs, Word docs, and images for the AI to read and understand. Ask questions about specific sections and get intelligent answers. The AI extracts text while preserving structure from PDFs, maintains formatting context from Word documents, parses web content from HTML files, and processes images with OCR and object recognition. + +Each conversation builds on previous messages, so the AI keeps track of the entire discussion and any files that have been shared. Documents, images, web links, and text can be mixed in one conversation, and the AI connects information across all formats. + +[[example-product-launch-workflow]] +=== Example: Product Launch Workflow + +. **Upload product spec** → _"What are the key features for marketing?"_ +. **Add competitor analysis** → _"How do we compare to competitors?"_ +. **Reference blog post** → _"Write a press release using this blog post and our competitive advantages"_ +. **Include brand guidelines** → _"Match our brand voice and key messaging"_ + +The AI remembers everything that has been shared and builds on it throughout the conversation. + +[[conversations-api-capabilities]] +=== API Capabilities + +When using the Conversations API directly, you can configure advanced capabilities: + +* **Web Search** – Enable real-time web search to access current information during conversations. Configure via the `webSearch` capability in API requests. See https://tinymceai.api.tiny.cloud/docs#tag/Conversation-Web-Resources[Conversation Web Resources API] for endpoint details. +* **Reasoning** – Enable step-by-step reasoning to see the AI's problem-solving process. Configure via the `reasoning` capability in API requests. See https://tinymceai.api.tiny.cloud/docs#tag/Conversation-Messages[Conversation Messages API] for endpoint details. + +[[conversations-streaming]] +=== Streaming Responses + +Conversations use Server-Sent Events (SSE) for real-time streaming responses. See the xref:tinymceai-streaming.adoc[Streaming Responses guide] for detailed implementation information and code examples. + +[[conversations-api-reference]] +=== API Reference + +For complete API documentation including endpoints, parameters, request/response schemas, and interactive examples, see: -The Chat feature supports advanced capabilities: +* **https://tinymceai.api.tiny.cloud/docs#tag/Conversations[REST API Conversations Documentation]** – Full documentation for conversations endpoints with interactive examples -* xref:tinymceai-chat.adoc#chat-history[**Multi-turn conversations**] - Maintain context across multiple interactions -* xref:tinymceai-chat.adoc#available-models[**Model selection**] - Choose the appropriate AI model for the task -* xref:tinymceai-chat.adoc#web-search[**Web Search**] - Access up-to-date information from the web -* xref:tinymceai-chat.adoc#reasoning[**Reasoning**] - Deep thinking about answers and changes +The REST API documentation includes examples for: -For more information about API-level features, see xref:tinymceai-conversations.adoc[Conversations API documentation]. +* Creating conversations - see https://tinymceai.api.tiny.cloud/docs#tag/Conversations[Conversations API] +* Uploading documents - see https://tinymceai.api.tiny.cloud/docs#tag/Conversation-Documents[Conversation Documents API] +* Uploading files - see https://tinymceai.api.tiny.cloud/docs#tag/Conversation-Files[Conversation Files API] +* Uploading web resources - see https://tinymceai.api.tiny.cloud/docs#tag/Conversation-Web-Resources[Conversation Web Resources API] +* Sending messages with context - see https://tinymceai.api.tiny.cloud/docs#tag/Conversation-Messages[Conversation Messages API] +* Configuring web search capabilities - see https://tinymceai.api.tiny.cloud/docs#tag/Conversation-Web-Resources[Conversation Web Resources API] +* Configuring reasoning capabilities - see https://tinymceai.api.tiny.cloud/docs#tag/Conversation-Messages[Conversation Messages API] +* Streaming responses - see https://tinymceai.api.tiny.cloud/docs#tag/Conversation-Messages[Conversation Messages API] [[related-features]] == Related Features * xref:tinymceai-review-plugin.adoc[AI review] – For content quality analysis and improvement suggestions. * xref:tinymceai-actions-plugin.adoc[Quick actions] – For fast, stateless content transformations. -* xref:tinymceai-introduction.adoc[Introduction] – Overview of all TinyMCE AI features. diff --git a/modules/ROOT/pages/tinymceai-conversations.adoc b/modules/ROOT/pages/tinymceai-conversations.adoc deleted file mode 100644 index bd32c93f89..0000000000 --- a/modules/ROOT/pages/tinymceai-conversations.adoc +++ /dev/null @@ -1,155 +0,0 @@ -= TinyMCE AI Conversations - -:navtitle: Conversations -:description: AI chat feature for {productname} -:description_short: AI chat feature -:keywords: AI, chat, conversations, tinymceai - -Conversations allow exchanging multiple messages with AI that maintains them in its context. Conversations can be extended by external context sources like websites or files, and have the ability to refer to editor content and suggest modifications. - -[[key-features]] -== Key Features - -Upload PDFs, Word docs, and images for the AI to read and understand. Ask questions about specific sections and get intelligent answers. The AI extracts text while preserving structure from PDFs, maintains formatting context from Word documents, parses web content from HTML files, and processes images with OCR and object recognition. - -Each conversation builds on previous messages, so the AI keeps track of the entire discussion and any files that have been shared. Documents, images, web links, and text can be mixed in one conversation, and the AI connects information across all formats. Enable web search for real-time research while keeping conversation context. - -[[example-product-launch-workflow]] -=== Example: Product Launch Workflow - -. **Upload product spec** → _"What are the key features for marketing?"_ -. **Add competitor analysis** → _"How do we compare to competitors?"_ -. **Reference blog post** → _"Write a press release using this blog post and our competitive advantages"_ -. **Include brand guidelines** → _"Match our brand voice and key messaging"_ - -The AI remembers everything that has been shared and builds on it throughout the conversation. - -[[advanced-features]] -== Advanced Features - -[[web-search]] -=== Web Search - -Enable real-time web search to access current information during conversations. The AI searches the web for relevant content, processes and analyzes the results, and integrates findings into responses while maintaining conversation context. Configure via the `webSearch` capability in API requests. - -[[reasoning]] -=== Reasoning - -Enable step-by-step reasoning to see the AI's problem-solving process. The AI breaks down complex queries into logical steps, considers multiple approaches, and can revise conclusions when new information emerges. Configure via the `reasoning` capability in API requests. - -[[api-reference]] -== API Reference - -For complete API documentation including endpoints, parameters, and response schemas, see the https://tinymceai.api.tiny.cloud/docs#tag/Conversations[REST API documentation]. - -[[api-examples]] -== API Examples - -[[create-a-conversation]] -=== Create a Conversation - -[source,http] ----- -POST /v1/conversations -Content-Type: application/json -Authorization: Bearer - -{ - "id": "my-conversation-123", - "title": "Document Analysis Session", - "group": "research" -} ----- - -[[upload-a-document]] -=== Upload a Document - -Before documents can be referenced in conversations, they need to be uploaded first: - -[source,http] ----- -POST /v1/conversations/my-conversation-123/documents -Content-Type: multipart/form-data -Authorization: Bearer - -file: [your-document.pdf] ----- - -Response: - -[source,json] ----- -{ - "id": "doc-123" -} ----- - -See how to upload other resources, including web resources and files using https://tinymceai.api.tiny.cloud/docs#tag/Conversations[REST API documentation]. - -[[send-a-message-with-context]] -=== Send a Message with Context - -[source,http] ----- -POST /v1/conversations/my-conversation-123/messages -Content-Type: application/json -Authorization: Bearer - -{ - "prompt": "Analyze the attached document and provide a summary of the key points", - "model": "agent-1", - "content": [ - { - "type": "document", - "id": "doc-123" - } - ], - "capabilities": { - "webSearch": {}, - "reasoning": {} - } -} ----- - -[[send-a-message-with-multiple-context-types]] -=== Send a Message with Multiple Context Types - -[source,http] ----- -POST /v1/conversations/my-conversation-123/messages -Content-Type: application/json -Authorization: Bearer - -{ - "prompt": "Compare the attached document with the information from the web resource", - "model": "agent-1", - "content": [ - { - "type": "document", - "id": "doc-123" - }, - { - "type": "web-resource", - "id": "web-123" - } - ], - "capabilities": { - "webSearch": {} - } -} ----- - -[[streaming-responses]] -== Streaming Responses - -Conversations use Server-Sent Events (SSE) for real-time streaming responses. See the xref:tinymceai-streaming.adoc[Streaming Responses guide] for detailed implementation information and code examples. - -[[related-features]] -== Related Features - -* xref:tinymceai-chat.adoc[AI Chat Plugin] – For plugin integration and UI configuration. -* xref:tinymceai-reviews.adoc[Reviews API] – Content quality analysis and improvement suggestions. -* xref:tinymceai-actions.adoc[Actions API] – Content transformation and batch processing. -* xref:tinymceai-models.adoc[AI Models] – Choosing the right AI model for conversations. -* xref:tinymceai-streaming.adoc[Streaming Responses] – Implementing real-time conversation features. -* xref:tinymceai-api-overview.adoc[API Overview] – Overview of all API features. diff --git a/modules/ROOT/pages/tinymceai-integration.adoc b/modules/ROOT/pages/tinymceai-integration.adoc deleted file mode 100644 index e14529a4bf..0000000000 --- a/modules/ROOT/pages/tinymceai-integration.adoc +++ /dev/null @@ -1,327 +0,0 @@ -= TinyMCE AI Integration - -:navtitle: Integration -:description: Integration guide for TinyMCE AI plugin -:description_short: Integration guide -:keywords: AI, integration, plugin, configuration, tinymceai - -This guide provides step-by-step instructions for running TinyMCE AI in editor integrations. It also presents possible configuration and customization options. - -[[installation]] -== Installation - -After installing the editor, add the feature to the plugin list and provide xref:tinymceai-integration.adoc#sample-implementation[essential configuration]: - -[source,js] ----- -tinymce.init({ - selector: '#editor', - plugins: 'tinymceai', - toolbar: 'tinymceai', - tinymceai_token_provider: function() { - // Return a promise that resolves to a JWT token - return fetch('/api/token').then(response => response.text()); - } -}); ----- - -[NOTE] -==== -The sidebar type must be configured for the AI features to work. The sidebar can be set to `static` (default) or `floating` using the `tinymceai_sidebar_type` configuration option. Learn more in the xref:tinymceai-integration.adoc#ui-types-and-positioning[UI types and positioning] section or use the xref:tinymceai-integration.adoc#sample-implementation[sample implementation] as a reference. -==== - -[[sample-implementation]] -== Sample implementation - -An example TinyMCE AI configuration is presented below. Learn more about specific configurations in the later sections of this guide. - -[source,js] ----- -tinymce.init({ - selector: '#editor', - plugins: 'tinymceai', - - // Add AI toolbar buttons - toolbar: 'showai aiquickactions aireview', - - // AI features are added to the selection toolbar by default - // Configure which features appear using tinymceai_context_toolbar - - setup: function(editor) { - setupUsers(editor); - }, - - // Configure the document identifier for AI chat history and context preservation. - // This should be a unique identifier for the document/article being edited. - tinymceai_document_id: 'document-123', // Replace with the actual document ID - - // Main configuration of AI feature. - tinymceai_token_provider: function() { - return fetch('/api/token').then(response => response.text()); - }, - - // Configure sidebar type (static or floating) - tinymceai_sidebar_type: 'static', - - // (Optional) Configure AI chat model selection. - tinymceai_default_model: 'agent-1', - tinymceai_allow_model_selection: true, - tinymceai_allowed_models: ['gpt', 'claude'], - - // (Optional) Configure additional context sources for AI chat. - // Built-in options (document, URLs, files) are always available. - tinymceai_additional_sources_list: async (query) => [ - { - id: 'my-doc-1', - label: 'My Document 1', - type: 'text' - }, - { - id: 'my-doc-2', - label: 'My Document 2', - type: 'text' - } - // ... More sources ... - ], - - // (Optional) Function to fetch content for additional sources. - tinymceai_get_additional_source: async (id) => { - // Fetch content from the database or API - return fetch(`/api/documents/${id}`).then(response => response.text()); - }, - - // (Optional) Configure custom Quick Actions commands. - tinymceai_custom_commands: [ - { - displayedPrompt: 'Explain like I am five', - prompt: 'Explain the following text in simple terms.', - type: 'chat' - } - // ... More custom actions ... - ] -}); ----- - -[[configuration]] -== Configuration - -[[supported-ai-models]] -=== Supported AI models - -TinyMCE AI supports multiple AI models from different providers. By default, the automatically selected model (`agent-1`) will be used for optimal cost and performance. - -The list of available models can be narrowed down. xref:tinymceai-chat.adoc#model-selection-configuration[Learn how to configure the list of available models in Chat]. - -Here's a detailed list of available models with their capabilities: - -[cols="1,2,1,1,2"] -|=== -|Model |Description |xref:tinymceai-chat.adoc#web-search[Web Search] |xref:tinymceai-chat.adoc#reasoning[Reasoning] |Configuration id - -|**Auto (default)** -|Automatically selects best model for speed, quality, and cost. -|Yes -|Yes -|`'auto'` (also `'agent-1'`, learn more about xref:tinymceai-models.adoc#model-compatibility-versions[compatibility versions]) - -|**GPT-5.2** -|OpenAI's flagship model for advanced reasoning, creativity, and complex tasks -|Yes -|Yes -|`'gpt-5.2'` - -|**GPT-5.1** -|OpenAI's flagship model for advanced reasoning, creativity, and complex tasks -|Yes -|Yes -|`'gpt-5.1'` - -|**GPT-5** -|OpenAI's flagship model for advanced reasoning, creativity, and complex tasks -|Yes -|Yes -|`'gpt-5'` - -|**GPT-5 Mini** -|A lightweight version of GPT-5 – faster, more cost-efficient -|Yes -|Yes -|`'gpt-5-mini'` - -|**Claude 4.5 Haiku** -|Cost-efficient model for quick interactions with improved reasoning -|Yes -|Yes -|`'claude-4-5-haiku'` - -|**Claude 4.5 Sonnet** -|Advanced model with improved creativity, reliability, and reasoning -|Yes -|Yes -|`'claude-4-5-sonnet'` - -|**Gemini 3 Pro** -|Google's advanced model for versatile problem-solving and research -|Yes -|Yes -|`'gemini-3-pro'` - -|**Gemini 3 Flash** -|Lightweight Gemini model for fast, cost-efficient interactions -|Yes -|Yes -|`'gemini-3-flash'` - -|**Gemini 2.5 Flash** -|Lightweight Gemini model for fast, cost-efficient interactions -|Yes -|Yes -|`'gemini-2-5-flash'` - -|**GPT-4.1** -|OpenAI's model for reliable reasoning, speed, and versatility -|Yes -|No -|`'gpt-4.1'` - -|**GPT-4.1 Mini** -|A lighter variant of GPT-4.1 that balances speed and cost while maintaining solid accuracy -|Yes -|No -|`'gpt-4.1-mini'` -|=== - -[NOTE] -==== -Model availability depends on the subscription tier and service compatibility version. Some models may have specific limitations or requirements. For detailed information about available models, their capabilities, and API-level configuration, see xref:tinymceai-models.adoc[AI models documentation]. -==== - -[[document-id]] -=== Document ID - -The `tinymceai_document_id` configuration property serves as the document identifier corresponding to the edited resource (article, document, etc.) in the application. This ID is essential for maintaining xref:tinymceai-chat.adoc[Chat] history, ensuring that AI conversations are properly associated with the specific document being edited. When users interact with AI features, their chat history is preserved and linked to this document ID. - -[source,js] ----- -tinymce.init({ - selector: '#editor', - plugins: 'tinymceai', - tinymceai_document_id: 'DOCUMENT_ID', // Replace with the actual document ID - tinymceai_token_provider: function() { - return fetch('/api/token').then(response => response.text()); - } -}); ----- - -[NOTE] -==== -The `tinymceai_document_id` configuration uses a dedicated namespace in the configuration. This namespace may be subject to change in future versions as the AI integration architecture continues to be refined. -==== - -[[ui-types-and-positioning]] -=== UI types and positioning - -TinyMCE AI supports two sidebar types for displaying the AI user interface. Use the `tinymceai_sidebar_type` configuration option to choose between them: - -* `static` (default): The sidebar is rendered inside the editor. -* `floating`: The sidebar is rendered in a separate container outside of the editor and can be dragged on the page. - -[source,js] ----- -tinymce.init({ - selector: '#editor', - plugins: 'tinymceai', - tinymceai_sidebar_type: 'static', // or 'floating' - tinymceai_token_provider: function() { - return fetch('/api/token').then(response => response.text()); - } -}); ----- - -[NOTE] -==== -Changing the `tinymceai_sidebar_type` property dynamically (after the editor has been initialized) is not supported and can result in unpredictable behavior. -==== - -[[toggling-the-ui]] -=== Toggling the UI - -The AI user interface can be toggled by users using toolbar buttons or menu items. Clicking a toolbar button (or menu item) opens or minimizes the relevant AI sidebar. - -* Clicking the chat toolbar button opens the chat sidebar. Clicking it again minimizes the chat sidebar. Importantly, minimizing the chat sidebar does not wipe the chat history—it just hides the sidebar. -* Clicking the review button opens the review sidebar. -* When reviewing suggested changes, the sidebar can be minimized to provide more screen space for reviewing. Once done reviewing, the sidebar can be opened again to continue working. - -The following example shows how to enable the AI toolbar buttons: - -[source,js] ----- -tinymce.init({ - selector: '#editor', - plugins: 'tinymceai', - - // Enable AI toolbar buttons - toolbar: ['showai', 'aiquickactions', 'aireview', /* ... */], - - tinymceai_token_provider: function() { - return fetch('/api/token').then(response => response.text()); - } -}); ----- - -The AI sidebar can also be toggled programmatically: - -[source,js] ----- -// Toggle the AI sidebar -editor.execCommand('tinymceai-toggle-sidebar'); ----- - -[[hiding-the-ui-on-initialization]] -=== Hiding the UI on initialization - -By default, the AI interface will be hidden when the editor is created. To have it visible on load, use the `tinymceai-toggle-sidebar` command after the editor is initialized. - -[source,js] ----- -tinymce.init({ - selector: '#editor', - plugins: 'tinymceai', - tinymceai_token_provider: function() { - return fetch('/api/token').then(response => response.text()); - }, - setup: function(editor) { - editor.on('init', function() { - // Show the AI interface on load - editor.execCommand('tinymceai-toggle-sidebar'); - }); - } -}); ----- - -[[permissions]] -=== Permissions - -Learn more about the permissions system used in TinyMCE AI in a xref:tinymceai-permissions.adoc[dedicated guide]. - -[[chat]] -== Chat - -Learn more about integrating the Chat feature image:https://placehold.net/default.png[Chat icon,24px] in a xref:tinymceai-chat.adoc[dedicated guide]. - -[[quick-actions]] -== Quick Actions - -Learn more about integrating the Quick Actions feature image:https://placehold.net/default.png[Quick Actions icon,24px] in a xref:tinymceai-actions-plugin.adoc[dedicated guide]. - -[[review]] -== Review - -Learn more about integrating the Review feature image:https://placehold.net/default.png[Review icon,24px] in a xref:tinymceai-review-plugin.adoc[dedicated guide]. - -[[related-features]] -== Related Features - -* xref:tinymceai-introduction.adoc[Introduction] – Overview of all TinyMCE AI features. -* xref:tinymceai.adoc[Plugin Reference] – Complete plugin API reference. -* xref:tinymceai-api-overview.adoc[API Overview] – AI service documentation. diff --git a/modules/ROOT/pages/tinymceai-introduction.adoc b/modules/ROOT/pages/tinymceai-introduction.adoc index df2ddfc9ea..24c7448800 100644 --- a/modules/ROOT/pages/tinymceai-introduction.adoc +++ b/modules/ROOT/pages/tinymceai-introduction.adoc @@ -22,7 +22,7 @@ Teams can implement a full suite of AI writing tools in weeks rather than months The core components of TinyMCE AI are: * **xref:tinymceai.adoc[{productname}]**: A modern rich text editor with dozens of features that improve writing workflows, including collaboration. -* **xref:tinymceai-api-overview.adoc[AI service]**: A state-of-the-art backend AI engine that incorporates multiple models and delivers high-quality content. Currently available only in Cloud setup, with on-premises deployment coming soon. +* **xref:tinymceai-api-overview.adoc[AI service]**: A state-of-the-art backend AI engine that incorporates multiple models and delivers high-quality content. Currently available in Cloud setup. See xref:tinymceai-introduction.adoc#on-premises-deployment[On-Premises Deployment] for deployment options. [[features]] == TinyMCE AI features @@ -46,4 +46,34 @@ Developers can control access to AI features, models, and capabilities based on [[privacy-and-data-handling]] == Privacy and data handling -Detailed information on how TinyMCE AI manages data can be found in the xref:tinymceai-api-overview.adoc#data-handling-and-security[API Overview] documentation. +[[regional-data-storage]] +=== Regional Data Storage + +All data stored by TinyMCE AI follows the region settings of your TinyMCE Cloud Services environment, ensuring compliance with data residency requirements and optimal performance for your geographic location. + +[IMPORTANT] +==== +Data sent to LLM providers for processing is currently processed in the US region, regardless of your Cloud Services environment region. +==== + +[[data-retention-policy]] +=== Data Retention Policy + +Conversation data is automatically deleted after 12 months of inactivity, including: + +* all conversation messages and history, +* attached documents, files, and web resources, +* conversation metadata and settings. + +[[security]] +=== Security + +All data is encrypted in transit and at rest with end-to-end encryption. Conversations and attachments are stored in secure cloud infrastructure with fine-grained access control and comprehensive permission systems. Audit Logs are available through our Customer Portal and the API. + +[[on-premises-deployment]] +== On-Premises Deployment + +[NOTE] +==== +On-premises deployment is currently in development. Follow TinyMCE social accounts and our newsletter for updates. +==== diff --git a/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc b/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc new file mode 100644 index 0000000000..69fd456893 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc @@ -0,0 +1,74 @@ += TinyMCE AI JWT Authentication + +:navtitle: JWT Authentication +:description: JWT authentication requirements and permissions for TinyMCE AI +:description_short: JWT Authentication +:keywords: AI, JWT, authentication, permissions, tinymceai + +TinyMCE AI requires JWT (JSON Web Token) authentication when using the Tiny Cloud service. JWT authentication provides secure, user-specific access to TinyMCE AI features. Each JWT token contains claims that identify the user and specify which AI features they can access. + +[[requirements]] +== Requirements + +JWT authentication for TinyMCE AI requires the following components: + +[[public-private-key-pair]] +=== Public/Private Key Pair + +A public/private key pair is required for signing JWT tokens. The public key must be added to your {accountpage}, and the private key is used by your JWT endpoint to sign tokens. + +For details on generating and managing key pairs, see: + +* xref:tinymceai-with-jwt-authentication-nodejs.adoc#generate-a-public-private-key-pair[Node.js guide - Generate a Public/Private Key Pair] +* xref:tinymceai-with-jwt-authentication-php.adoc#generate-a-public-private-key-pair[PHP guide - Generate a Public/Private Key Pair] + +[[jwt-endpoint]] +=== JWT Endpoint + +A JWT endpoint that generates tokens with required claims. The endpoint must accept JSON HTTP POST requests and return a JSON response containing the signed JWT token. + +For detailed endpoint requirements, see: + +* xref:tinymceai-with-jwt-authentication-nodejs.adoc#jwt-endpoint-requirements[Node.js guide - JWT endpoint requirements] +* xref:tinymceai-with-jwt-authentication-php.adoc#jwt-endpoint-requirements[PHP guide - JWT endpoint requirements] + +[[required-claims]] +=== Required JWT Claims + +JWT tokens must include the following required claims: `aud`, `sub`, `iat`, `exp`, and `auth`. The `auth` object contains AI-specific permissions that control feature access. + +For complete details on all required claims, including types, formats, and examples, see: + +* xref:tinymceai-with-jwt-authentication-nodejs.adoc#required-jwt-claims-for-tinymce-ai[Node.js guide - Required JWT claims] +* xref:tinymceai-with-jwt-authentication-php.adoc#required-jwt-claims-for-tinymce-ai[PHP guide - Required JWT claims] + +[[permissions]] +=== Permissions + +Permissions are specified in the `auth.ai.permissions` array within the JWT token and control which AI features, models, and capabilities users can access. + +For a complete list of available permissions, permission examples, and best practices, see xref:tinymceai-permissions.adoc[Permissions]. + +[[quick-setup]] +== Quick Setup + +To set up JWT authentication for TinyMCE AI: + +. Generate a public/private key pair and add the public key to your {accountpage} via link:{accountjwturl}[{accountpage} - JWT Keys]. +. Set up a JWT endpoint that generates tokens with the required claims. +. Configure your {productname} to use the JWT endpoint via the `tinymceai_token_provider` option. + +For step-by-step implementation instructions with complete code examples, see: + +* xref:tinymceai-with-jwt-authentication-nodejs.adoc[JWT authentication (Node.js)] – Complete Node.js implementation guide +* xref:tinymceai-with-jwt-authentication-php.adoc[JWT authentication (PHP)] – Complete PHP implementation guide + +[[related-features]] +== Related Features + +* xref:tinymceai-permissions.adoc[Permissions]: Complete permissions reference and examples. +* xref:tinymceai-models.adoc[AI Models]: Model selection and capabilities. +* xref:tinymceai-chat.adoc[Chat]: Interactive AI discussions. +* xref:tinymceai-review-plugin.adoc[Review]: Content improvement. +* xref:tinymceai-actions-plugin.adoc[Quick Actions]: Content transformation. +* link:https://tinymceai.api.tiny.cloud/docs[API Documentation]: Complete API reference for TinyMCE AI. diff --git a/modules/ROOT/pages/tinymceai-limits.adoc b/modules/ROOT/pages/tinymceai-limits.adoc index 16d26e0805..ce8378cfcf 100644 --- a/modules/ROOT/pages/tinymceai-limits.adoc +++ b/modules/ROOT/pages/tinymceai-limits.adoc @@ -49,5 +49,5 @@ Different AI models have varying capabilities and limitations that affect contex * xref:tinymceai-models.adoc[Learn about AI Models] for model-specific limitations. * xref:tinymceai-permissions.adoc[Set up Permisssions] to control user access. -* xref:tinymceai-conversations.adoc[Explore Conversations] for context management. +* xref:tinymceai-chat.adoc[Explore Chat] for context management. * https://tinymceai.api.tiny.cloud/docs[API Documentation] – Complete API reference for TinyMCE AI. diff --git a/modules/ROOT/pages/tinymceai-models.adoc b/modules/ROOT/pages/tinymceai-models.adoc index adea0c2414..d944965964 100644 --- a/modules/ROOT/pages/tinymceai-models.adoc +++ b/modules/ROOT/pages/tinymceai-models.adoc @@ -13,7 +13,89 @@ The `agent-1` model automatically selects the best AI model for requests based o [[available-models]] == Available Models -TinyMCE AI supports multiple AI models from different providers. Each model has unique capabilities, performance characteristics, and cost profiles. +TinyMCE AI supports multiple AI models from different providers. Each model has unique capabilities, performance characteristics, and cost profiles. By default, the automatically selected model (`agent-1`) will be used for optimal cost and performance. + +[[supported-models-table]] +=== Supported Models + +Here's a detailed list of available models with their capabilities: + +[cols="1,2,1,1,2"] +|=== +|Model |Description |xref:tinymceai-chat.adoc#web-search[Web Search] |xref:tinymceai-chat.adoc#reasoning[Reasoning] |Configuration id + +|**Auto (default)** +|Automatically selects best model for speed, quality, and cost. +|Yes +|Yes +|`'auto'` (also `'agent-1'`, learn more about xref:tinymceai-models.adoc#model-compatibility-versions[compatibility versions]) + +|**GPT-5.2** +|OpenAI's flagship model for advanced reasoning, creativity, and complex tasks +|Yes +|Yes +|`'gpt-5.2'` + +|**GPT-5.1** +|OpenAI's flagship model for advanced reasoning, creativity, and complex tasks +|Yes +|Yes +|`'gpt-5.1'` + +|**GPT-5** +|OpenAI's flagship model for advanced reasoning, creativity, and complex tasks +|Yes +|Yes +|`'gpt-5'` + +|**GPT-5 Mini** +|A lightweight version of GPT-5 – faster, more cost-efficient +|Yes +|Yes +|`'gpt-5-mini'` + +|**Claude 4.5 Haiku** +|Cost-efficient model for quick interactions with improved reasoning +|Yes +|Yes +|`'claude-4-5-haiku'` + +|**Claude 4.5 Sonnet** +|Advanced model with improved creativity, reliability, and reasoning +|Yes +|Yes +|`'claude-4-5-sonnet'` + +|**Gemini 3 Pro** +|Google's advanced model for versatile problem-solving and research +|Yes +|Yes +|`'gemini-3-pro'` + +|**Gemini 3 Flash** +|Lightweight Gemini model for fast, cost-efficient interactions +|Yes +|Yes +|`'gemini-3-flash'` + +|**Gemini 2.5 Flash** +|Lightweight Gemini model for fast, cost-efficient interactions +|Yes +|Yes +|`'gemini-2-5-flash'` + +|**GPT-4.1** +|OpenAI's model for reliable reasoning, speed, and versatility +|Yes +|No +|`'gpt-4.1'` + +|**GPT-4.1 Mini** +|A lighter variant of GPT-4.1 that balances speed and cost while maintaining solid accuracy +|Yes +|No +|`'gpt-4.1-mini'` +|=== [[limitations]] === Limitations @@ -211,6 +293,6 @@ For complete documentation on model endpoints, compatibility versions, and capab [[related-features]] == Related Features -* xref:tinymceai-conversations.adoc[Conversations] – Use models in interactive AI discussions. -* xref:tinymceai-reviews.adoc[Reviews] – Apply models to content analysis and improvement. -* xref:tinymceai-actions.adoc[Actions] – Use models for content transformation tasks. +* xref:tinymceai-chat.adoc[Chat] – Use models in interactive AI discussions. +* xref:tinymceai-review-plugin.adoc[Review] – Apply models to content analysis and improvement. +* xref:tinymceai-actions-plugin.adoc[Quick Actions] – Use models for content transformation tasks. diff --git a/modules/ROOT/pages/tinymceai-permissions.adoc b/modules/ROOT/pages/tinymceai-permissions.adoc index 95db0faaaa..1d4002fe1a 100644 --- a/modules/ROOT/pages/tinymceai-permissions.adoc +++ b/modules/ROOT/pages/tinymceai-permissions.adoc @@ -1,15 +1,40 @@ -= TinyMCE AI Permissions += TinyMCE AI JWT Permissions :navtitle: Permissions -:description: Permission configuration for TinyMCE AI -:description_short: Permission configuration -:keywords: AI, permissions, configuration, tinymceai - -[[overview]] -== Overview +:description: JWT permissions system for TinyMCE AI +:description_short: JWT Permissions +:keywords: AI, JWT, permissions, authentication, tinymceai TinyMCE AI uses a permission-based access control system to manage user access to AI features. Permissions are specified in JWT tokens and control which features, models, and capabilities users can access. +For information about JWT authentication setup and required claims, see xref:tinymceai-jwt-authentication-intro.adoc[JWT Authentication]. + +[[quick-reference]] +== Quick Reference + +[cols="2,3"] +|=== +|Category |Permissions + +|Admin +|`ai:admin` + +|Models +|`ai:models:*`, `ai:models::*`, `ai:models::`, `ai:models:agent` + +|Conversations +|`ai:conversations:*`, `ai:conversations:read`, `ai:conversations:write`, `ai:conversations:websearch`, `ai:conversations:reasoning` + +|Context +|`ai:conversations:context:*`, `ai:conversations:context:files:*`, `ai:conversations:context:files:`, `ai:conversations:context:urls` + +|Actions +|`ai:actions:*`, `ai:actions:custom`, `ai:actions:system:*`, `ai:actions:system:` + +|Reviews +|`ai:reviews:*`, `ai:reviews:custom`, `ai:reviews:system:*`, `ai:reviews:system:` +|=== + [[use-cases]] == Use Cases @@ -24,140 +49,118 @@ TinyMCE AI uses a permission-based access control system to manage user access t Permissions follow a hierarchical format: `ai:::` [[admin-permissions]] -=== Admin Permissions +== Admin Permissions -[[aiadmin]] -==== `ai:admin` +[cols="2,3"] +|=== +|Permission |Description -Grants full access to all TinyMCE AI features, models, and capabilities. Use with caution in production environments. +|`ai:admin` +|Grants full access to all TinyMCE AI features, models, and capabilities. Use with caution in production environments. +|=== [[model-permissions]] -=== Model Permissions - -[[aimodels]] -==== `ai:models:*` +== Model Permissions -Access to all available AI models. Use with caution as this includes access to new models that may be more expensive. +[cols="2,3"] +|=== +|Permission |Description -[[aimodelsprovider]] -==== `ai:models::*` +|`ai:models:*` +|Access to all available AI models. Use with caution as this includes access to new models that may be more expensive. -Access to all models from a specific provider (e.g., `ai:models:openai:*`, `ai:models:anthropic:*`). +|`ai:models::*` +|Access to all models from a specific provider (e.g., `ai:models:openai:*`, `ai:models:anthropic:*`). -[[aimodelsprovidermodel-name]] -==== `ai:models::` +|`ai:models::` +|Access to a specific model (e.g., `ai:models:openai:gpt-4o`, `ai:models:anthropic:claude-3-sonnet`). -Access to a specific model (e.g., `ai:models:openai:gpt-4o`, `ai:models:anthropic:claude-3-sonnet`). - -[[aimodelsagent-recommended]] -==== `ai:models:agent` ⭐ Recommended - -Access to the agent model which automatically selects the best model for each request. This is the recommended permission for most use cases. +|`ai:models:agent` ⭐ Recommended +|Access to the agent model which automatically selects the best model for each request. This is the recommended permission for most use cases. +|=== [[conversation-permissions]] -=== Conversation Permissions - -[[aiconversations]] -==== `ai:conversations:*` +== Conversation Permissions -Full access to all conversation features including read, write, web search, and reasoning. +[cols="2,3"] +|=== +|Permission |Description -[[aiconversationsread]] -==== `ai:conversations:read` +|`ai:conversations:*` +|Full access to all conversation features including read, write, web search, and reasoning. -Ability to read and list conversations. +|`ai:conversations:read` +|Ability to read and list conversations. -[[aiconversationswrite]] -==== `ai:conversations:write` +|`ai:conversations:write` +|Ability to create and send messages in conversations. -Ability to create and send messages in conversations. +|`ai:conversations:websearch` +|Ability to use web search capability in conversations. -[[aiconversationswebsearch]] -==== `ai:conversations:websearch` - -Ability to use web search capability in conversations. - -[[aiconversationsreasoning]] -==== `ai:conversations:reasoning` - -Ability to use reasoning capability in conversations. +|`ai:conversations:reasoning` +|Ability to use reasoning capability in conversations. +|=== [[context-permissions]] -=== Context Permissions - -[[aiconversationscontext]] -==== `ai:conversations:context:*` +== Context Permissions -Access to all context types (files and URLs). +[cols="2,3"] +|=== +|Permission |Description -[[aiconversationscontextfiles]] -==== `ai:conversations:context:files:*` +|`ai:conversations:context:*` +|Access to all context types (files and URLs). -Access to all file types for context. +|`ai:conversations:context:files:*` +|Access to all file types for context. -[[aiconversationscontextfilesformat]] -==== `ai:conversations:context:files:` +|`ai:conversations:context:files:` +|Access to specific file formats (e.g., `ai:conversations:context:files:pdf`, `ai:conversations:context:files:docx`). -Access to specific file formats (e.g., `ai:conversations:context:files:pdf`, `ai:conversations:context:files:docx`). - -[[aiconversationscontexturls]] -==== `ai:conversations:context:urls` - -Ability to use web URLs as context sources. +|`ai:conversations:context:urls` +|Ability to use web URLs as context sources. +|=== [[actions-permissions]] -=== Actions Permissions - -[[aiactions]] -==== `ai:actions:*` +== Actions Permissions -Access to all action types, including custom and system actions. +[cols="2,3"] +|=== +|Permission |Description -[[aiactionscustom]] -==== `ai:actions:custom` +|`ai:actions:*` +|Access to all action types, including custom and system actions. -Ability to run custom actions with free-form prompts. +|`ai:actions:custom` +|Ability to run custom actions with free-form prompts. -[[aiactionssystem]] -==== `ai:actions:system:*` +|`ai:actions:system:*` +|Access to all pre-defined system actions. -Access to all pre-defined system actions. - -[[aiactionssystemaction-name]] -==== `ai:actions:system:` - -Access to specific system actions. Examples: - -* `ai:actions:system:improve-writing` -* `ai:actions:system:fix-grammar` -* `ai:actions:system:translate` +|`ai:actions:system:` +|Access to specific system actions. Examples: `ai:actions:system:improve-writing`, `ai:actions:system:fix-grammar`, `ai:actions:system:translate` +|=== [[reviews-permissions]] -=== Reviews Permissions - -[[aireviews]] -==== `ai:reviews:*` - -Access to all review types, including custom and system reviews. - -[[aireviewscustom]] -==== `ai:reviews:custom` - -Ability to run custom reviews with free-form prompts. +== Reviews Permissions -[[aireviewssystem]] -==== `ai:reviews:system:*` +[cols="2,3"] +|=== +|Permission |Description -Access to all pre-defined system reviews. +|`ai:reviews:*` +|Access to all review types, including custom and system reviews. -[[aireviewssystemreview-name]] -==== `ai:reviews:system:` +|`ai:reviews:custom` +|Ability to run custom reviews with free-form prompts. -Access to specific system reviews. Examples: +|`ai:reviews:system:*` +|Access to all pre-defined system reviews. -* `ai:reviews:system:correctness` -* `ai:reviews:system:clarity` -* `ai:reviews:system:make-tone-professional` +|`ai:reviews:system:` +|Access to specific system reviews. Examples: `ai:reviews:system:correctness`, `ai:reviews:system:clarity`, `ai:reviews:system:make-tone-professional` +|=== [[permission-examples]] == Permission Examples @@ -250,11 +253,11 @@ Avoid `ai:models:*` in production to prevent unexpected access to new expensive When a user lacks required permissions, the API returns a `403 Forbidden` error with the message "No permissions to the resource". Common issues include missing model permissions, file type restrictions, feature access without permission, and action/review access without permission. -[[next-steps]] -== Next Steps +[[related-features]] +== Related Features -* xref:tinymceai-models.adoc[Learn about AI Models] for model selection and capabilities. -* xref:tinymceai-conversations.adoc[Learn about Conversations] for interactive AI discussions. -* xref:tinymceai-reviews.adoc[Explore Reviews] for content improvement. -* xref:tinymceai-actions.adoc[Discover Actions] for content transformation. -* https://tinymceai.api.tiny.cloud/docs[API Documentation] – Complete API reference for TinyMCE AI. +* xref:tinymceai-jwt-authentication-intro.adoc[JWT Authentication] – JWT authentication setup and required claims. +* xref:tinymceai-models.adoc[AI Models] – Model selection and capabilities. +* xref:tinymceai-chat.adoc[Chat] – Interactive AI discussions. +* xref:tinymceai-review-plugin.adoc[Review] – Content improvement. +* xref:tinymceai-actions-plugin.adoc[Quick Actions] – Content transformation. diff --git a/modules/ROOT/pages/tinymceai-review-plugin.adoc b/modules/ROOT/pages/tinymceai-review-plugin.adoc index 2e5822328d..2efe6b94fc 100644 --- a/modules/ROOT/pages/tinymceai-review-plugin.adoc +++ b/modules/ROOT/pages/tinymceai-review-plugin.adoc @@ -5,16 +5,18 @@ :description_short: AI Review feature :keywords: AI, review, reviews, tinymceai -The Review feature provides users with AI-powered quality assurance for their content by running checks for grammar, style, tone, and more. It also introduces an intuitive interface for reviewing and managing AI-suggested edits directly within the document, ensuring content meets professional standards with minimal manual effort. +The Review feature provides AI-powered quality assurance for content by running checks for grammar, style, tone, and more. It introduces an intuitive interface for reviewing and managing AI-suggested edits directly within the document, ensuring content meets professional standards with minimal manual effort. + +The Review feature is available as a plugin UI and via the xref:tinymceai-review-plugin.adoc#reviews-api[Reviews API]. This page covers both: + +* Plugin sections describe user-facing features and configuration. +* API sections cover REST API access (starting at xref:tinymceai-review-plugin.adoc#reviews-api[Reviews API]). [[demo]] == Demo liveDemo::tinymceai[] -[[overview]] -== Overview - The Review feature analyzes content and provides specific recommendations for grammar, style, clarity, and tone improvements. Unlike Actions that transform content directly, Reviews analyze content and provide suggestions without automatically changing the content. image::https://placehold.net/default.png[TinyMCE AI Review feature showing AI-powered quality assurance and suggested edits] @@ -22,7 +24,7 @@ image::https://placehold.net/default.png[TinyMCE AI Review feature showing AI-po [[integration]] == Integration -To start using the Review feature, first load the TinyMCE AI plugin in the editor configuration. The Review Mode button image:https://placehold.net/default.png[Review icon,24px] will appear in the AI user interface. xref:tinymceai-integration.adoc[Learn more about installing and enabling AI features]. +To start using the Review feature, first load the TinyMCE AI plugin in the editor configuration. The Review Mode button image:https://placehold.net/default.png[Review icon,24px] will appear in the AI user interface. See xref:tinymceai.adoc[Plugin Reference] for installation and enabling AI features. After picking one of the available commands in the Review Mode tab, AI will analyze the document and propose a series of suggestions: @@ -61,10 +63,59 @@ The feature comes with several review commands: Custom commands and translation are not currently supported in the Review feature. This may change in future updates. ==== +[[reviews-api]] +== Reviews API + +The Review plugin feature is built on top of the Reviews API, which provides REST API access to review functionality. Reviews provide comprehensive content analysis and improvement suggestions. Unlike Actions that transform content directly, Reviews analyze content and provide specific recommendations for grammar, style, clarity, and tone improvements. + +**When to use Reviews vs Actions:** Use Reviews when analyzing entire documents for quality improvements and getting suggestions without automatically changing the content. Use Actions when transforming specific text content (fix grammar, translate, adjust tone). + +Reviews use streaming output with Server-Sent Events for real-time feedback as suggestions are generated. Each review type is optimized for specific improvement tasks, providing consistent, high-quality analysis of text structure, style, and quality. Reviews provide specific, actionable recommendations for content improvement. + +[[reviews-system-reviews-api]] +=== System Reviews + +TinyMCE AI provides built-in system reviews for comprehensive content analysis via the API. These correspond to the review commands available in the plugin UI: + +* **Correctness** (corresponds to "Proofread" in plugin) – Fix grammar, spelling, and factual errors. See https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API] for the correctness endpoint. +* **Clarity** (corresponds to "Improve clarity" in plugin) – Improve sentence structure, word choice, and logical flow. See https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API] for the clarity endpoint. +* **Readability** (corresponds to "Improve readability" in plugin) – Enhance paragraph structure, transitions, and reading level. See https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API] for the readability endpoint. +* **Length Optimization** (corresponds to "Adjust length" in plugin) – Expand or condense content while preserving key information. See https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API] for the length optimization endpoint. +* **Tone Adjustment** (corresponds to "Adjust tone and style" in plugin) – Modify tone to casual, direct, friendly, confident, or professional styles. See https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API] for tone adjustment endpoints. +* **Translation** – Translate content between languages with cultural adaptation. (Note: Translation is not currently available in the plugin UI, but is available via the API.) See https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API] for the translation endpoint. + +[[reviews-custom-reviews]] +=== Custom Reviews + +In addition to system reviews, custom reviews can be created tailored to specific content quality standards and editorial guidelines. Custom reviews allow defining specialized analysis criteria using custom prompts to control the review behavior. + +Unlike system reviews that use predefined identifiers, custom reviews use a unified endpoint where the analysis behavior is defined through a prompt parameter. See https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API] for the custom reviews endpoint and implementation details. + +Custom reviews require the `ai:reviews:custom` permission in the JWT token. + +[[reviews-streaming]] +=== Streaming Responses + +Reviews use Server-Sent Events (SSE) for real-time streaming results. See the xref:tinymceai-streaming.adoc[Streaming Responses guide] for detailed implementation information. + +[[reviews-api-reference]] +=== API Reference + +For complete endpoint documentation, request/response schemas, authentication details, and additional parameters, see: + +* **https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API Reference]** – Full documentation for system and custom reviews endpoints with interactive examples + +The REST API documentation includes examples for: + +* Basic grammar review - see https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API] +* Clarity improvement - see https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API] +* Tone adjustment - see https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API] +* Translation reviews - see https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API] +* Custom reviews with custom prompts - see https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API] +* Streaming responses - see https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API] + [[related-features]] == Related Features * xref:tinymceai-chat.adoc[AI chat] – For interactive discussions with document analysis and context. * xref:tinymceai-actions-plugin.adoc[Quick actions] – For content transformation and batch processing. -* xref:tinymceai-reviews.adoc[Reviews API] – For API-level review functionality. -* xref:tinymceai-introduction.adoc[Introduction] – Overview of all TinyMCE AI features. diff --git a/modules/ROOT/pages/tinymceai-reviews.adoc b/modules/ROOT/pages/tinymceai-reviews.adoc deleted file mode 100644 index 50d86cf2c6..0000000000 --- a/modules/ROOT/pages/tinymceai-reviews.adoc +++ /dev/null @@ -1,169 +0,0 @@ -= TinyMCE AI Reviews - -:navtitle: Reviews -:description: AI review feature for {productname} -:description_short: AI review feature -:keywords: AI, review, reviews, tinymceai - -Reviews provide comprehensive content analysis and improvement suggestions. Unlike Actions that transform content directly, Reviews analyze content and provide specific recommendations for grammar, style, clarity, and tone improvements. - -**When to use Reviews vs Actions:** Use Reviews when analyzing entire documents for quality improvements and getting suggestions without automatically changing the content. Use Actions when transforming specific text content (fix grammar, translate, adjust tone). - -[[available-reviews]] -== Available Reviews - -[[system-reviews]] -=== System Reviews - -TinyMCE AI provides built-in system reviews for comprehensive content analysis: - -* **Correctness** – Fix grammar, spelling, and factual errors. -* **Clarity** – Improve sentence structure, word choice, and logical flow. -* **Readability** – Enhance paragraph structure, transitions, and reading level. -* **Length Optimization** – Expand or condense content while preserving key information. -* **Tone Adjustment** – Modify tone to casual, direct, friendly, confident, or professional styles. -* **Translation** – Translate content between languages with cultural adaptation. - -[[custom-reviews]] -=== Custom Reviews - -In addition to system reviews, custom reviews can be created tailored to specific content quality standards and editorial guidelines. Custom reviews allow defining specialized analysis criteria using custom prompts to control the review behavior. - -Unlike system reviews that use predefined identifiers, custom reviews use a unified endpoint where the analysis behavior is defined through a prompt parameter. - -[[key-features]] -== Key Features - -Reviews use streaming output with Server-Sent Events for real-time feedback as suggestions are generated. Each review type is optimized for specific improvement tasks, providing consistent, high-quality analysis of text structure, style, and quality. - -Reviews provide specific, actionable recommendations for content improvement. - -[[api-examples]] -== API Examples - -[[basic-grammar-review-example]] -=== Basic Grammar Review Example - -[source,http] ----- -POST /v1/reviews/system/correctness/calls -Content-Type: application/json -Authorization: Bearer - -{ - "content": [ - { - "type": "text", - "content": "

The norhtern lights dence across the polar skies, painting ribbons of green and purple light that ripple like a cosmic curtain.

" - } - ] -} ----- - -[[clarity-improvement-example]] -=== Clarity Improvement Example - -[source,http] ----- -POST /v1/reviews/system/clarity/calls -Content-Type: application/json -Authorization: Bearer - -{ - "content": [ - { - "type": "text", - "content": "

The system works by processing data through various algorithms to produce results.

" - } - ] -} ----- - -[[tone-adjustment-example]] -=== Tone Adjustment Example - -[source,http] ----- -POST /v1/reviews/system/make-tone-casual/calls -Content-Type: application/json -Authorization: Bearer - -{ - "content": [ - { - "type": "text", - "content": "

We regret to inform you that your request cannot be processed at this time.

" - } - ], - "args": { - "language": "casual" - } -} ----- - -[[translation-review]] -=== Translation Review - -[source,http] ----- -POST /v1/reviews/system/translate/calls -Content-Type: application/json -Authorization: Bearer - -{ - "content": [ - { - "type": "text", - "content": "

Hello, how are you today?

" - } - ], - "args": { - "language": "Spanish" - } -} ----- - -[[custom-review-example]] -=== Custom Review Example - -[source,http] ----- -POST /v1/reviews/custom/calls -Content-Type: application/json -Authorization: Bearer - -{ - "content": [ - { - "type": "text", - "content": "

Our product is really good and customers love it because it has many features.

" - } - ], - "prompt": "Review the text for vague language and generic claims. Suggest specific, concrete alternatives that would make the content more credible and informative.", - "model": "agent-1" -} ----- - -Custom reviews require the `ai:reviews:custom` permission in the JWT token. - -[[streaming-responses]] -== Streaming Responses - -Reviews use Server-Sent Events (SSE) for real-time streaming results. See the xref:tinymceai-streaming.adoc[Streaming Responses guide] for detailed implementation information. - -[[api-reference]] -== API Reference - -For complete endpoint documentation, request/response schemas, authentication details, and additional parameters, see: - -* **https://tinymceai.api.tiny.cloud/docs#tag/Reviews[Reviews API Reference]** – Full documentation for system and custom reviews endpoints. -* **https://tinymceai.api.tiny.cloud/docs[Complete API Documentation]** – Interactive API reference with all TinyMCE AI endpoints. - -[[related-features]] -== Related Features - -* xref:tinymceai-review-plugin.adoc[AI Review Plugin] – For plugin integration and UI configuration. -* xref:tinymceai-conversations.adoc[Conversations API] – For interactive discussions with document analysis and context. -* xref:tinymceai-actions.adoc[Actions API] – For content transformation and batch processing. -* xref:tinymceai-streaming.adoc[Streaming Responses] – For implementing real-time review suggestions. -* xref:tinymceai-api-overview.adoc[API Overview] – Overview of all API features. diff --git a/modules/ROOT/pages/tinymceai-streaming.adoc b/modules/ROOT/pages/tinymceai-streaming.adoc index f21802ca75..0374ac619a 100644 --- a/modules/ROOT/pages/tinymceai-streaming.adoc +++ b/modules/ROOT/pages/tinymceai-streaming.adoc @@ -17,9 +17,9 @@ TinyMCE AI services use Server-Sent Events (SSE) to provide real-time streaming Different AI services provide different types of streaming events. For service-specific event details, see: -* xref:tinymceai-conversations.adoc#streaming-responses[Conversations] – Interactive AI discussions with text streaming, web search sources, and reasoning. -* xref:tinymceai-reviews.adoc#streaming-responses[Reviews] – Content improvement suggestions and review progress. -* xref:tinymceai-actions.adoc#streaming-responses[Actions] – Content transformations and action progress. +* xref:tinymceai-chat.adoc#conversations-streaming[Chat] – Interactive AI discussions with text streaming, web search sources, and reasoning. +* xref:tinymceai-review-plugin.adoc#reviews-streaming[Review] – Content improvement suggestions and review progress. +* xref:tinymceai-actions-plugin.adoc#actions-streaming[Quick Actions] – Content transformations and action progress. [[basic-implementation]] == Basic Implementation @@ -78,9 +78,9 @@ while (true) { For detailed event handling examples specific to each service, see: -* xref:tinymceai-conversations.adoc#streaming-responses[Conversations] – Text streaming, web search sources, reasoning, and document modifications. -* xref:tinymceai-reviews.adoc#streaming-responses[Reviews] – Review suggestions and progress tracking. -* xref:tinymceai-actions.adoc#streaming-responses[Actions] – Content transformations and action progress. +* xref:tinymceai-chat.adoc#conversations-streaming[Chat] – Text streaming, web search sources, reasoning, and document modifications. +* xref:tinymceai-review-plugin.adoc#reviews-streaming[Review] – Review suggestions and progress tracking. +* xref:tinymceai-actions-plugin.adoc#actions-streaming[Quick Actions] – Content transformations and action progress. [[error-handling]] == Error Handling @@ -106,7 +106,7 @@ if (data.event === 'error') { [[progress-tracking]] == Progress Tracking -Use metadata events to show progress. For service-specific progress tracking examples, see xref:tinymceai-reviews.adoc[Review progress and status information]. +Use metadata events to show progress. For service-specific progress tracking examples, see xref:tinymceai-review-plugin.adoc[Review progress and status information]. [[api-reference]] == API Reference @@ -121,6 +121,6 @@ For complete documentation on streaming endpoints, event schemas, and error code [[next-steps]] == Next Steps -* xref:tinymceai-conversations.adoc[Learn about Conversations] for interactive AI discussions. -* xref:tinymceai-reviews.adoc[Explore Reviews] for content improvement. -* xref:tinymceai-actions.adoc[Discover Actions] for content transformation. +* xref:tinymceai-chat.adoc[Learn about Chat] for interactive AI discussions. +* xref:tinymceai-review-plugin.adoc[Explore Review] for content improvement. +* xref:tinymceai-actions-plugin.adoc[Discover Quick Actions] for content transformation. diff --git a/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc b/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc index aa6e3d8fec..8ad3e7f7c5 100644 --- a/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc +++ b/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc @@ -17,6 +17,8 @@ include::partial$auth/private-public-key-pairs-for-tiny-cloud-services.adoc[] This section explains what needs to be configured for JWT authentication, whether using a managed service (such as AWS or Azure JWT services) or setting up a manual endpoint. +For complete information about JWT requirements, claims, and permissions, see xref:tinymceai-jwt-authentication-intro.adoc[JWT Authentication]. + include::partial$auth/how-jwts-are-used.adoc[] === JWT endpoint requirements @@ -87,7 +89,7 @@ auth: { [NOTE] ==== -See xref:tinymceai-permissions.adoc[Permissions] for a complete list of available permissions and best practices for configuring user access. +See xref:tinymceai-jwt-authentication-intro.adoc#permissions[Permissions] for a complete list of available permissions and best practices for configuring user access. ==== == Set up JWT Endpoint diff --git a/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc b/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc index a37f586c14..6af4bc1556 100644 --- a/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc +++ b/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc @@ -17,6 +17,8 @@ include::partial$auth/private-public-key-pairs-for-tiny-cloud-services.adoc[] This section explains what needs to be configured for JWT authentication, whether using a managed service (such as AWS or Azure JWT services) or setting up a manual endpoint. +For complete information about JWT requirements, claims, and permissions, see xref:tinymceai-jwt-authentication-intro.adoc[JWT Authentication]. + include::partial$auth/how-jwts-are-used.adoc[] === JWT endpoint requirements @@ -87,7 +89,7 @@ auth: { [NOTE] ==== -See xref:tinymceai-permissions.adoc[Permissions] for a complete list of available permissions and best practices for configuring user access. +See xref:tinymceai-jwt-authentication-intro.adoc#permissions[Permissions] for a complete list of available permissions and best practices for configuring user access. ==== == Set up JWT Endpoint diff --git a/modules/ROOT/pages/tinymceai.adoc b/modules/ROOT/pages/tinymceai.adoc index 76b2215b60..f98a268441 100644 --- a/modules/ROOT/pages/tinymceai.adoc +++ b/modules/ROOT/pages/tinymceai.adoc @@ -27,7 +27,8 @@ To setup the {pluginname} plugin in the editor: * configure the `tinymceai_token_provider` option to provide authentication tokens; * add the AI toolbar buttons to the `toolbar` option in the editor configuration. The plugin provides approximately 3 toolbar buttons for different features: `showai`, `aiquickactions`, and `aireview`; -For example: +[[minimal-setup]] +=== Minimal setup [source,js] ---- @@ -42,6 +43,74 @@ tinymce.init({ }); ---- +[[complete-setup]] +=== Complete setup example + +An example {pluginname} configuration with common options: + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + + // Add AI toolbar buttons + toolbar: 'showai aiquickactions aireview', + + // AI features are added to the selection toolbar by default + // Configure which features appear using tinymceai_context_toolbar + + // Configure the document identifier for AI chat history and context preservation. + // This should be a unique identifier for the document/article being edited. + tinymceai_document_id: 'document-123', // Replace with the actual document ID + + // Main configuration of AI feature. + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + }, + + // Configure sidebar type (static or floating) + tinymceai_sidebar_type: 'static', + + // (Optional) Configure AI chat model selection. + tinymceai_default_model: 'agent-1', + tinymceai_allow_model_selection: true, + tinymceai_allowed_models: ['gpt', 'claude'], + + // (Optional) Configure additional context sources for AI chat. + // Built-in options (document, URLs, files) are always available. + tinymceai_additional_sources_list: async (query) => [ + { + id: 'my-doc-1', + label: 'My Document 1', + type: 'text' + }, + { + id: 'my-doc-2', + label: 'My Document 2', + type: 'text' + } + // ... More sources ... + ], + + // (Optional) Function to fetch content for additional sources. + tinymceai_get_additional_source: async (id) => { + // Fetch content from the database or API + return fetch(`/api/documents/${id}`).then(response => response.text()); + }, + + // (Optional) Configure custom Quick Actions commands. + tinymceai_custom_commands: [ + { + displayedPrompt: 'Explain like I am five', + prompt: 'Explain the following text in simple terms.', + type: 'chat' + } + // ... More custom actions ... + ] +}); +---- + [[options]] == Options @@ -49,6 +118,75 @@ The following configuration options affect the behavior of the {pluginname} plug include::partial$configuration/tinymceai_token_provider.adoc[leveloffset=+1] +include::partial$configuration/tinymceai_document_id.adoc[leveloffset=+1] + +[[tinymceai-sidebar-type]] +== `+tinymceai_sidebar_type+` + +This option controls how the AI sidebar is displayed. The sidebar can be set to `static` (default) or `floating`. + +*Type:* `+String+` + +*Default value:* `+'static'+` + +*Valid values:* +* `+'static'+` – The sidebar is rendered inside the editor. +* `+'floating'+` – The sidebar is rendered in a separate container outside of the editor and can be dragged on the page. + +.Example: using `tinymceai_sidebar_type` option +[source,javascript] +---- +tinymce.init({ + selector: 'textarea', + plugins: 'tinymceai', + tinymceai_sidebar_type: 'static', // or 'floating' + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + } +}); +---- + +[NOTE] +==== +Changing the `tinymceai_sidebar_type` property dynamically (after the editor has been initialized) is not supported and can result in unpredictable behavior. +==== + +[[ui-control]] +== UI Control + +The AI user interface can be toggled by users using toolbar buttons or menu items. Clicking a toolbar button (or menu item) opens or minimizes the relevant AI sidebar. + +* Clicking the chat toolbar button opens the chat sidebar. Clicking it again minimizes the chat sidebar. Importantly, minimizing the chat sidebar does not wipe the chat history—it just hides the sidebar. +* Clicking the review button opens the review sidebar. +* When reviewing suggested changes, the sidebar can be minimized to provide more screen space for reviewing. Once done reviewing, the sidebar can be opened again to continue working. + +The AI sidebar can also be toggled programmatically: + +[source,js] +---- +// Toggle the AI sidebar +editor.execCommand('tinymceai-toggle-sidebar'); +---- + +By default, the AI interface will be hidden when the editor is created. To have it visible on load, use the `tinymceai-toggle-sidebar` command after the editor is initialized: + +[source,js] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + }, + setup: function(editor) { + editor.on('init', function() { + // Show the AI interface on load + editor.execCommand('tinymceai-toggle-sidebar'); + }); + } +}); +---- + include::partial$misc/plugin-toolbar-button-id-boilerplate.adoc[] include::partial$toolbar-button-ids/{plugincode}-toolbar-buttons.adoc[leveloffset=+1] From a91997f2e4e2b5f5ef908eeea358fe78dec51db5 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Wed, 18 Feb 2026 10:30:33 +1000 Subject: [PATCH 09/10] DOC-3356: Move limits and models in nav.adoc file. --- modules/ROOT/nav.adoc | 7 +++---- modules/ROOT/pages/tinymceai-limits.adoc | 2 +- modules/ROOT/pages/tinymceai-models.adoc | 26 ++++++++++++++++++------ 3 files changed, 24 insertions(+), 11 deletions(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index b1cb83bccb..7fe983a16e 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -265,15 +265,14 @@ **** xref:tinymceai-chat.adoc[Chat] **** xref:tinymceai-review-plugin.adoc[Review] **** xref:tinymceai-actions-plugin.adoc[Actions] +**** xref:tinymceai-models.adoc[AI Models] +**** xref:tinymceai-limits.adoc[Limits] **** xref:tinymceai-integration-options.adoc[Integration Options] ***** xref:tinymceai.adoc[Plugin quick start] ***** REST API ****** xref:tinymceai-api-overview.adoc[API Overview] ****** xref:tinymceai-api-quick-start.adoc[API quick start] -****** Configuration -******* xref:tinymceai-models.adoc[AI models] -******* xref:tinymceai-limits.adoc[Limits] -******* xref:tinymceai-streaming.adoc[Streaming] +****** xref:tinymceai-streaming.adoc[Streaming] **** xref:tinymceai-jwt-authentication-intro.adoc[JWT Authentication] ***** xref:tinymceai-permissions.adoc[Permissions] ***** Guides diff --git a/modules/ROOT/pages/tinymceai-limits.adoc b/modules/ROOT/pages/tinymceai-limits.adoc index ce8378cfcf..da83067b32 100644 --- a/modules/ROOT/pages/tinymceai-limits.adoc +++ b/modules/ROOT/pages/tinymceai-limits.adoc @@ -15,7 +15,7 @@ TinyMCE AI implements various limits to ensure fair usage, optimal performance, [[rate-limits]] == Rate Limits -Rate limits control the frequency of API requests to prevent abuse and ensure service stability. The service implements limits on API requests, token usage, web search, and web scraping requests per minute. All rate limits are applied at both organization level (higher limits) and individual user level (lower limits) to ensure fair usage. +Rate limits control the frequency of requests to prevent abuse and ensure service stability. These limits apply to both plugin usage and direct API calls, as the plugin uses the API under the hood. The service implements limits on requests, token usage, web search, and web scraping requests per minute. All rate limits are applied at both organization level (higher limits) and individual user level (lower limits) to ensure fair usage. NOTE: Specific rate limit values are subject to change and may vary based on the subscription tier. Contact support for current rate limit details for the environment. diff --git a/modules/ROOT/pages/tinymceai-models.adoc b/modules/ROOT/pages/tinymceai-models.adoc index d944965964..013c30ba80 100644 --- a/modules/ROOT/pages/tinymceai-models.adoc +++ b/modules/ROOT/pages/tinymceai-models.adoc @@ -5,6 +5,8 @@ :description_short: AI model configuration :keywords: AI, models, configuration, tinymceai +TinyMCE AI supports multiple AI models from different providers. Model selection and configuration can be done through the plugin UI or via the REST API. This page covers model capabilities, configuration options, and limitations that apply to both plugin and API usage. + [[recommended-agent-models]] == Recommended: Agent Models @@ -112,7 +114,13 @@ The agent model (`agent-1`) automatically selects the best underlying model base * **Required capabilities** – Web search and reasoning require compatible models * **Cost optimization** – Balances quality with cost efficiency -A model can also be specified directly in API requests for more control. +[[model-configuration]] +=== Model Configuration + +Models can be configured in two ways: + +* **Plugin Configuration** – Use `tinymceai_default_model`, `tinymceai_allow_model_selection`, and `tinymceai_allowed_models` options. See xref:tinymceai-chat.adoc#model-selection-configuration[Chat model configuration] for details. +* **API Configuration** – Specify the model directly in API requests for more control. See xref:tinymceai-models.adoc#api-examples[API Examples] below. [[model-compatibility-versions]] == Model Compatibility Versions @@ -127,12 +135,15 @@ Compatibility versions allow TinyMCE AI to introduce new models and capabilities [[checking-compatibility]] === Checking Compatibility -Check the `/v1/models` endpoint to see available models for the compatibility version. The API response includes model capabilities, limits, and availability. +To see available models for your compatibility version: + +* **Via API** – Check the `/v1/models` endpoint. The API response includes model capabilities, limits, and availability. +* **Via Plugin** – Available models are shown in the model selection dropdown when `tinymceai_allow_model_selection` is enabled. [[model-capabilities]] == Model Capabilities -Different models support different capabilities. Check the model information endpoint to see which capabilities are available for each model. +Different models support different capabilities. Check the model information via the API endpoint or the plugin's model selection UI to see which capabilities are available for each model. [[web-search]] === Web Search @@ -149,9 +160,9 @@ Enable step-by-step reasoning to see the AI's problem-solving process. Some mode * Reasoning is always active during inference. * Reasoning cannot be turned off via the API. -To determine if a model has always-on reasoning, check the API response when listing models. Models with mandatory reasoning will indicate this in their capability structure. +To determine if a model has always-on reasoning, check the API response when listing models or refer to the model capabilities in the plugin UI. Models with mandatory reasoning will indicate this in their capability structure. -NOTE: Please observe, that model names such as `gpt-5`, `claude-4-sonnet`, etc. are examples. Actual available models depend on the service's compatibility version. Use the `/v1/models` endpoint to see current available models for the environment. +NOTE: Please observe, that model names such as `gpt-5`, `claude-4-sonnet`, etc. are examples. Actual available models depend on the service's compatibility version. Use the `/v1/models` API endpoint or check the plugin's model selection dropdown to see current available models for your environment. [[web-scraping]] === Web Scraping @@ -196,6 +207,8 @@ Models scheduled for removal will include a `removal` field with an ISO 8601 dat [[api-examples]] == API Examples +The following examples show how to configure models when using the REST API directly. For plugin configuration, see xref:tinymceai-chat.adoc#model-selection-configuration[Chat model configuration]. + [[model-selection]] === Model Selection @@ -293,6 +306,7 @@ For complete documentation on model endpoints, compatibility versions, and capab [[related-features]] == Related Features -* xref:tinymceai-chat.adoc[Chat] – Use models in interactive AI discussions. +* xref:tinymceai-chat.adoc[Chat] – Use models in interactive AI discussions and configure model selection. * xref:tinymceai-review-plugin.adoc[Review] – Apply models to content analysis and improvement. * xref:tinymceai-actions-plugin.adoc[Quick Actions] – Use models for content transformation tasks. +* xref:tinymceai.adoc[Plugin Reference] – Complete plugin configuration options including model settings. \ No newline at end of file From 8e69ba1c14b33c8758212cea9a80daf6a7ed6de9 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Thu, 19 Feb 2026 21:36:27 +1000 Subject: [PATCH 10/10] DOC-3356: Refactor JWT intro page to include refinded details for tinymceai. --- .../tinymceai-jwt-authentication-intro.adoc | 232 ++++++++++++++++-- .../nodejs/intro-and-prerequisites.adoc | 2 +- .../php/intro-and-prerequisites.adoc | 2 +- 3 files changed, 207 insertions(+), 29 deletions(-) diff --git a/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc b/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc index 69fd456893..4b6abca247 100644 --- a/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc +++ b/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc @@ -4,65 +4,243 @@ :description: JWT authentication requirements and permissions for TinyMCE AI :description_short: JWT Authentication :keywords: AI, JWT, authentication, permissions, tinymceai +:pluginname: TinyMCE AI -TinyMCE AI requires JWT (JSON Web Token) authentication when using the Tiny Cloud service. JWT authentication provides secure, user-specific access to TinyMCE AI features. Each JWT token contains claims that identify the user and specify which AI features they can access. +{pluginname} requires JWT (JSON Web Token) authentication when using the Tiny Cloud service. JWT authentication provides secure, user-specific access to {pluginname} features. Each JWT token contains claims that identify the user and specify which AI features they can access. -[[requirements]] -== Requirements +{productname} recommends using the libraries listed on link:https://www.jwt.io/libraries[jwt.io/libraries] to create JWT tokens. These libraries support the algorithms required by {pluginname}. For details on supported algorithms, see xref:#supported-algorithms[Supported Algorithms]. -JWT authentication for TinyMCE AI requires the following components: +[[token-endpoint-overview]] +== Token Endpoint Overview -[[public-private-key-pair]] -=== Public/Private Key Pair +To connect {productname} with {pluginname}, a token endpoint must be created. This guide outlines the principles required to create it. -A public/private key pair is required for signing JWT tokens. The public key must be added to your {accountpage}, and the private key is used by your JWT endpoint to sign tokens. +[[how-tinymce-ai-uses-tokens]] +== How {pluginname} Uses Tokens -For details on generating and managing key pairs, see: +To authenticate users, {pluginname} uses tokens. The purpose of tokens is to inform the AI service that the user has access to AI features and which API key the user should connect to. The authenticity of tokens is provided by a digital signature. -* xref:tinymceai-with-jwt-authentication-nodejs.adoc#generate-a-public-private-key-pair[Node.js guide - Generate a Public/Private Key Pair] -* xref:tinymceai-with-jwt-authentication-php.adoc#generate-a-public-private-key-pair[PHP guide - Generate a Public/Private Key Pair] +*The token endpoint*: is where {productname} makes a request to get the token. It is required to return the token only if the user proves their identity. It should be placed inside the system, not exposed as a public endpoint without proper authentication. -[[jwt-endpoint]] -=== JWT Endpoint +The following diagram shows how {pluginname} uses tokens: -A JWT endpoint that generates tokens with required claims. The endpoint must accept JSON HTTP POST requests and return a JSON response containing the signed JWT token. +image::JWT-flow.svg[JSON Web Token Call Flow,title="JSON Web Token Call Flow"] -For detailed endpoint requirements, see: +[[jwt-specification]] +== The JSON Web Tokens Specification -* xref:tinymceai-with-jwt-authentication-nodejs.adoc#jwt-endpoint-requirements[Node.js guide - JWT endpoint requirements] -* xref:tinymceai-with-jwt-authentication-php.adoc#jwt-endpoint-requirements[PHP guide - JWT endpoint requirements] +{pluginname} tokens are represented as JSON Web Tokens (JWT). JWT is an open link:https://datatracker.ietf.org/doc/html/rfc7519[standard] (RFC 7519) for transmitting digitally signed information. Using it ensures that the data comes from a trusted source and has not been tampered with. -[[required-claims]] -=== Required JWT Claims +A JWT consists of three parts separated by dots `.` -JWT tokens must include the following required claims: `aud`, `sub`, `iat`, `exp`, and `auth`. The `auth` object contains AI-specific permissions that control feature access. +* **Header**: Contains metadata about the token, including the signing algorithm +* **Payload**: Contains the claims (user information, permissions, etc.) +* **Signature**: Used to verify the token's authenticity -For complete details on all required claims, including types, formats, and examples, see: +[source,json] +---- +{header}.{payload}.{signature} +---- -* xref:tinymceai-with-jwt-authentication-nodejs.adoc#required-jwt-claims-for-tinymce-ai[Node.js guide - Required JWT claims] -* xref:tinymceai-with-jwt-authentication-php.adoc#required-jwt-claims-for-tinymce-ai[PHP guide - Required JWT claims] +.Example: +[source,json] +---- +eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLTQ4NzI5IiwibmFtZSI6Ikplc3NpY2EgV2lsbGlhbXMiLCJpYXQiOjE3Mjg0NzM2NDJ9.kX9mP2qL8vN4rT7wY3zA5bC6dE1fG2hI3jK4lM5nO6pQ7rS8tU9vW0xY1zA2b +---- + +[[jwt-header]] +=== Header + +The JWT header identifies the token type and specifies the cryptographic algorithm used to sign the token. For {pluginname}, the header must be a JSON object containing: + +* `alg` – The signing algorithm used to create the token signature. See xref:#supported-algorithms[Supported Algorithms] for the list of supported algorithms. {companyname} recommends using `RS256`. +* `typ` – The token type identifier, which must always be `JWT` + +The header is Base64URL-encoded to form the first part of the JWT token. + +.Example header +[source,json] +---- +{ + "alg": "RS256", + "typ": "JWT" +} +---- + +[[jwt-payload]] +=== Payload + +The JWT payload is a JSON object containing claims that identify the user, specify their AI permissions, and control token validity. The payload is Base64URL-encoded to form the second part of the JWT token. + +[[payload-properties]] +==== Payload Properties + +The following properties **must** be included in the payload: + +* `aud` – The API key that has entitlements to use {pluginname}. +* `sub` – The user ID. This should be a unique identifier for the user making the request. This identifier is used to lock down conversation history, AI-generated content, and other user-specific data to individual users, ensuring privacy and data isolation. +* `iat` – "Issued at". Make sure that `iat` is present and contains a correct time stated in seconds. Some JWT implementations do not include it by default. Sometimes the system time may also be invalid, causing issues. +* `exp` – Token expiration time. Identifies the expiration time after which the JWT will not be accepted. {pluginname} only accepts tokens no older than 24 hours. This field can be used to shorten the token validity time. +* `auth` – The `auth.ai.permissions` array inside is required. This defines which AI features the user can access. See xref:#permissions[Permissions] below for details. + +The properties that are optional: + +* `user` – User information. Providing `name` and `email` is recommended for better user experience and debugging. + +[[example-token-payload]] +==== Example Token Payload + +The example below presents a complete token payload with access to all AI features: + +[source,json] +---- +{ + "aud": "your-api-key", + "iat": 1511963669, + "exp": 1511967269, + "sub": "user-123", + "user": { + "email": "user@example.com", + "name": "John Doe" + }, + "auth": { + "ai": { + "permissions": [ + "ai:conversations:read", + "ai:conversations:write", + "ai:models:agent", + "ai:actions:system:*", + "ai:reviews:system:*" + ] + } + } +} +---- [[permissions]] -=== Permissions +==== Permissions Permissions are specified in the `auth.ai.permissions` array within the JWT token and control which AI features, models, and capabilities users can access. For a complete list of available permissions, permission examples, and best practices, see xref:tinymceai-permissions.adoc[Permissions]. +For complete details on all required claims, including types, formats, and implementation examples, see: + +* xref:tinymceai-with-jwt-authentication-nodejs.adoc#required-jwt-claims-for-tinymce-ai[Node.js guide - Required JWT claims] +* xref:tinymceai-with-jwt-authentication-php.adoc#required-jwt-claims-for-tinymce-ai[PHP guide - Required JWT claims] + +[[jwt-signature]] +=== Signature + +The signature is created by encoding the header and payload using Base64URL, then signing them with the private key using the specified algorithm. The {pluginname} service verifies the signature using the corresponding public key stored in the {accountpage}. + +[[supported-algorithms]] +=== Supported Algorithms + +{productname} does not support symmetrical encryption algorithms, such as `HS256`. {companyname} recommends using the `RS256` algorithm. The following algorithms are supported: + +* RS256 +* RS384 +* RS512 +* PS256 +* PS384 +* PS512 + +For details on each of these algorithms, visit: link:https://tools.ietf.org/html/rfc7518#section-3[RFC 7518, JSON Web Algorithms (JWA) Section 3 - Cryptographic Algorithms for Digital Signatures and MACs]. + +[[token-requests]] +== Requests to the Token Endpoint + +The token for {pluginname} is requested by the {pluginname} plugin. The easiest way to configure this is to set the `tinymceai_token_provider` option to a function that fetches the token from the endpoint. + +The token endpoint will be requested: +* At editor initialization +* Periodically to refresh the token (typically every hour) + +[[simple-token-request]] +=== Simple Usage + +[source,javascript] +---- +tinymce.init({ + selector: 'textarea', + plugins: 'tinymceai', + toolbar: 'showai aiquickactions aireview', + tinymceai_token_provider: () => { + return fetch('https://example.com/cs-token-endpoint', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + }).then(response => response.json()); + }, +}); +---- + +[TIP] +==== +The editor will not be ready to use until the first token is obtained from the token endpoint. If an error occurs during the initial request, the editor will not start correctly. +==== + +For more advanced token request customization, see xref:tinymceai-with-jwt-authentication-nodejs.adoc#configure-tinymce[Configure TinyMCE] in the implementation guides. + +[[token-responses]] +== Responses from the Token Endpoint + +The endpoint must respond with a JSON object containing a `token` property. The response format is: + +[source,json] +---- +{ + "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." +} +---- + +The {pluginname} plugin extracts the token from the `token` property. Plain text string responses are no longer supported and will not work. + [[quick-setup]] == Quick Setup -To set up JWT authentication for TinyMCE AI: +To set up JWT authentication for {pluginname}: -. Generate a public/private key pair and add the public key to your {accountpage} via link:{accountjwturl}[{accountpage} - JWT Keys]. +. Generate a public/private key pair and add the public key to the {accountpage} via link:{accountjwturl}[{accountpage} - JWT Keys]. . Set up a JWT endpoint that generates tokens with the required claims. -. Configure your {productname} to use the JWT endpoint via the `tinymceai_token_provider` option. +. Configure {productname} to use the JWT endpoint via the `tinymceai_token_provider` option. For step-by-step implementation instructions with complete code examples, see: * xref:tinymceai-with-jwt-authentication-nodejs.adoc[JWT authentication (Node.js)] – Complete Node.js implementation guide * xref:tinymceai-with-jwt-authentication-php.adoc[JWT authentication (PHP)] – Complete PHP implementation guide +[[tools]] +== Tools + +JWT tokens can be validated and debugged using the link:https://jwt.io/[jwt.io debugger]. + +[[troubleshooting]] +== Troubleshooting + +[[invalid-token-error]] +=== Invalid token + +If an error message indicates an invalid token: + +* Verify that the token was created in accordance with the required claims and format +* Ensure the API key in the `aud` claim is correct and valid +* Verify that the token is signed with one of the xref:#supported-algorithms[supported algorithms] +* Check that the public key in the {accountpage} matches the private key used to sign the token +* Validate the token structure using the link:https://jwt.io/[jwt.io debugger] +* Ensure the `iat` (issued at) timestamp is correct and not in the future +* Verify that system time is accurate (time drift can cause token validation issues) + +[[insufficient-permissions-error]] +=== Insufficient permissions + +If an error indicates insufficient permissions: + +* Verify that the token includes the `auth.ai.permissions` array with the required permissions +* Check that the permissions match the AI features being accessed +* Review the xref:tinymceai-permissions.adoc[Permissions] guide for the correct permission format +* Ensure permissions are specified correctly (e.g., `ai:conversations:read`, `ai:conversations:write`) + [[related-features]] == Related Features @@ -71,4 +249,4 @@ For step-by-step implementation instructions with complete code examples, see: * xref:tinymceai-chat.adoc[Chat]: Interactive AI discussions. * xref:tinymceai-review-plugin.adoc[Review]: Content improvement. * xref:tinymceai-actions-plugin.adoc[Quick Actions]: Content transformation. -* link:https://tinymceai.api.tiny.cloud/docs[API Documentation]: Complete API reference for TinyMCE AI. +* link:https://tinymceai.api.tiny.cloud/docs[API Documentation]: Complete API reference for {pluginname}. diff --git a/modules/ROOT/partials/auth/tinymceai/nodejs/intro-and-prerequisites.adoc b/modules/ROOT/partials/auth/tinymceai/nodejs/intro-and-prerequisites.adoc index 2bc6655d07..b9ccddc90d 100644 --- a/modules/ROOT/partials/auth/tinymceai/nodejs/intro-and-prerequisites.adoc +++ b/modules/ROOT/partials/auth/tinymceai/nodejs/intro-and-prerequisites.adoc @@ -1,6 +1,6 @@ == Introduction -{pluginname} requires setting up JSON Web Token (JWT) authentication to maintain control over AI feature access. A JWT endpoint generates and provides authorization tokens that verify users are authorized to use AI features, preventing unauthorized access. As a standard web services authorization solution, JWT is documented extensively at link:https://jwt.io/[https://jwt.io/]. +{pluginname} requires setting up JSON Web Token (JWT) authentication to maintain control over AI feature access. A JWT endpoint generates and provides authorization tokens that verify users are authorized to use AI features, preventing unauthorized access. As a standard web services authorization solution, JWT is documented extensively at link:https://jwt.io/[https://jwt.io/]. {productname} recommends using the libraries listed on link:https://www.jwt.io/libraries[jwt.io/libraries] to create JWT tokens. This guide provides a comprehensive walkthrough for integrating {pluginname} with {productname}, including {pluginname} functionality, by using a Node.js server for JWT token generation. It covers project setup, server configuration, and {productname} customization. diff --git a/modules/ROOT/partials/auth/tinymceai/php/intro-and-prerequisites.adoc b/modules/ROOT/partials/auth/tinymceai/php/intro-and-prerequisites.adoc index fcd71e337b..9ec88dcce2 100644 --- a/modules/ROOT/partials/auth/tinymceai/php/intro-and-prerequisites.adoc +++ b/modules/ROOT/partials/auth/tinymceai/php/intro-and-prerequisites.adoc @@ -1,6 +1,6 @@ == Introduction -{pluginname} requires setting up JSON Web Token (JWT) authentication to maintain control over AI feature access. A JWT endpoint generates and provides authorization tokens that verify users are authorized to use AI features, preventing unauthorized access. As a standard web services authorization solution, JWT is documented extensively at link:https://jwt.io/[https://jwt.io/]. +{pluginname} requires setting up JSON Web Token (JWT) authentication to maintain control over AI feature access. A JWT endpoint generates and provides authorization tokens that verify users are authorized to use AI features, preventing unauthorized access. As a standard web services authorization solution, JWT is documented extensively at link:https://jwt.io/[https://jwt.io/]. {productname} recommends using the libraries listed on link:https://www.jwt.io/libraries[jwt.io/libraries] to create JWT tokens. This guide provides a comprehensive walkthrough for integrating {pluginname} with {productname}, including {pluginname} functionality, by using a PHP server for JWT token generation. It covers project setup, server configuration, and {productname} customization.