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..7fe983a16e 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -260,6 +260,24 @@ **** 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-introduction.adoc[Introduction] +**** 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] +****** 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] *** 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-plugin.adoc b/modules/ROOT/pages/tinymceai-actions-plugin.adoc new file mode 100644 index 0000000000..7093cccb26 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-actions-plugin.adoc @@ -0,0 +1,263 @@ += 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. 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[] + +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. + +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 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. + +[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, 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: + +[source,js] +---- +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. + 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 context toolbar (selection toolbar). Since some of the actions are selection-sensitive, + // accessing them might be easier for users using this kind of toolbar. + 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' +}); +---- + +[[types-of-actions]] +== Types of actions + +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. + +* 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. + +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]. Whole action categories can be added to the toolbar too. + +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: + +* **"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_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] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + toolbar: 'tinymceai-actions', + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + }, + tinymceai_custom_commands: [ + { + 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: 'gemini-2-5-flash' + }, + { + displayedPrompt: 'Summarize in 5 bullet points', + prompt: 'Summarize the selected text in 5 bullet points.', + type: 'chat' + }, + { + displayedPrompt: 'Rewrite adding more sarcasm', + prompt: 'Rewrite using a sarcastic tone.', + type: 'action', + model: 'gemini-2-5-flash' + } + ] +}); +---- + +[[configuring-quick-actions-menu]] +== Configuring Quick Actions menu + +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] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + toolbar: 'tinymceai-actions', + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + }, + // 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' + ] +}); +---- + +[[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. diff --git a/modules/ROOT/pages/tinymceai-api-overview.adoc b/modules/ROOT/pages/tinymceai-api-overview.adoc new file mode 100644 index 0000000000..ea84c8e588 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-api-overview.adoc @@ -0,0 +1,41 @@ += TinyMCE AI API Overview + +:navtitle: API Overview +:description: Overview of TinyMCE AI service features and capabilities +:description_short: API Overview +: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] +==== +**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-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 + +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. + +[[resources-and-support]] +== Resources and Support + +* **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..bc64cd4120 --- /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 service +:description_short: API quick start guide +:keywords: AI, quick start, API, AI service, tinymceai, setup + +The aim of this article is to get users up and running with the TinyMCE AI service. + +[TIP] +==== +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]. +==== + +== Getting Started + +To start using the TinyMCE AI service, follow the steps below: + +* 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. + +[[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::https://placehold.net/default.png[TinyMCE AI trial view] + +[[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 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 feature documentation and API access information, see: + +* 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 with interactive examples for all endpoints + +[[next-steps]] +== Next Steps + +After setting up your JWT endpoint, continue with: + +* 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-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 new file mode 100644 index 0000000000..60c501acc3 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-chat.adoc @@ -0,0 +1,245 @@ += 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 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. + +The Chat feature is available as a plugin UI and via the xref:tinymceai-chat.adoc#conversations-api[Conversations API]. This page covers both: + +* 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] + +[[working-with-the-document]] +=== Working with the document + +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], 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 + +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 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 + +liveDemo::tinymceai[] + +[[integration]] +== Integration + +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 + +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. 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. + +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. + +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 + +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-models.adoc#supported-models-table[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_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 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 and provide information that can be easily used in the document. + +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 + +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. + +To add custom external sources for users to select from, use the following configuration options: + +* `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] +---- +tinymce.init({ + selector: '#editor', + plugins: 'tinymceai', + toolbar: 'tinymceai', + tinymceai_token_provider: function() { + return fetch('/api/token').then(response => response.text()); + }, + // 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(); + } +}); +---- + +[[working-with-ai-generated-changes]] +== Working with AI-generated changes + +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. + +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 + +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] + +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] + +[[rejecting-suggestions]] +=== Rejecting 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] + + +[[chat-history]] +== Chat history + +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 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] +==== +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, reopen it from the chat history. +==== + +[[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: + +* **https://tinymceai.api.tiny.cloud/docs#tag/Conversations[REST API Conversations Documentation]** – Full documentation for conversations endpoints with interactive examples + +The REST API documentation includes examples for: + +* 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. diff --git a/modules/ROOT/pages/tinymceai-integration-options.adoc b/modules/ROOT/pages/tinymceai-integration-options.adoc new file mode 100644 index 0000000000..244f726b26 --- /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 applications +:description_short: Integration options for TinyMCE AI +:keywords: AI, integration, plugin, API, AI service, tinymceai + +TinyMCE AI can be integrated with applications 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 the editor. + +| +[.lead] +xref:tinymceai-api-overview.adoc[**AI service**] + +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-introduction.adoc b/modules/ROOT/pages/tinymceai-introduction.adoc new file mode 100644 index 0000000000..24c7448800 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-introduction.adoc @@ -0,0 +1,79 @@ += 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. + +[[demo]] +== Demo + +liveDemo::tinymceai[] + +[[what-is-tinymce-ai]] +== What is TinyMCE AI + +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. + +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 in Cloud setup. See xref:tinymceai-introduction.adoc#on-premises-deployment[On-Premises Deployment] for deployment options. + +[[features]] +== TinyMCE AI features + +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. +* xref:tinymceai-actions-plugin.adoc[**Actions**] – Fast, stateless operations for specific tasks. + +[[integration-options]] +== Integration Options + +TinyMCE AI can be integrated with applications 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 + +[[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..4b6abca247 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc @@ -0,0 +1,252 @@ += 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 +:pluginname: TinyMCE AI + +{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. + +{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]. + +[[token-endpoint-overview]] +== Token Endpoint Overview + +To connect {productname} with {pluginname}, a token endpoint must be created. This guide outlines the principles required to create it. + +[[how-tinymce-ai-uses-tokens]] +== How {pluginname} Uses Tokens + +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. + +*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. + +The following diagram shows how {pluginname} uses tokens: + +image::JWT-flow.svg[JSON Web Token Call Flow,title="JSON Web Token Call Flow"] + +[[jwt-specification]] +== The JSON Web Tokens Specification + +{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. + +A JWT consists of three parts separated by dots `.` + +* **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 + +[source,json] +---- +{header}.{payload}.{signature} +---- + +.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 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 {pluginname}: + +. 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 {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 + +* 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 {pluginname}. diff --git a/modules/ROOT/pages/tinymceai-limits.adoc b/modules/ROOT/pages/tinymceai-limits.adoc new file mode 100644 index 0000000000..da83067b32 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-limits.adoc @@ -0,0 +1,53 @@ += TinyMCE AI Limits + +:navtitle: Limits +: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 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. + +[[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). 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 + +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-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 new file mode 100644 index 0000000000..013c30ba80 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-models.adoc @@ -0,0 +1,312 @@ += TinyMCE AI Models + +:navtitle: AI Models +:description: AI model configuration for TinyMCE AI +: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 + +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 + +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 + +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 + +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 + +[[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 + +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 + +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 via the API endpoint or the plugin's model selection UI 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. +* Reasoning cannot be turned off via the API. + +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` API endpoint or check the plugin's model selection dropdown 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). 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 + +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 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 + +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 + +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 + +[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-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 diff --git a/modules/ROOT/pages/tinymceai-permissions.adoc b/modules/ROOT/pages/tinymceai-permissions.adoc new file mode 100644 index 0000000000..1d4002fe1a --- /dev/null +++ b/modules/ROOT/pages/tinymceai-permissions.adoc @@ -0,0 +1,263 @@ += TinyMCE AI JWT Permissions + +:navtitle: Permissions +: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 + +* **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 + +[cols="2,3"] +|=== +|Permission |Description + +|`ai:admin` +|Grants full access to all TinyMCE AI features, models, and capabilities. Use with caution in production environments. +|=== + +[[model-permissions]] +== Model Permissions + +[cols="2,3"] +|=== +|Permission |Description + +|`ai:models:*` +|Access to all available AI models. Use with caution as this includes access to new models that may be more expensive. + +|`ai:models::*` +|Access to all models from a specific provider (e.g., `ai:models:openai:*`, `ai:models:anthropic:*`). + +|`ai:models::` +|Access to a specific model (e.g., `ai:models:openai:gpt-4o`, `ai:models:anthropic:claude-3-sonnet`). + +|`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 + +[cols="2,3"] +|=== +|Permission |Description + +|`ai:conversations:*` +|Full access to all conversation features including read, write, web search, and reasoning. + +|`ai:conversations:read` +|Ability to read and list conversations. + +|`ai:conversations:write` +|Ability to create and send messages in conversations. + +|`ai:conversations:websearch` +|Ability to use web search capability in conversations. + +|`ai:conversations:reasoning` +|Ability to use reasoning capability in conversations. +|=== + +[[context-permissions]] +== Context Permissions + +[cols="2,3"] +|=== +|Permission |Description + +|`ai:conversations:context:*` +|Access to all context types (files and URLs). + +|`ai:conversations:context:files:*` +|Access to all file types for context. + +|`ai:conversations:context:files:` +|Access to specific file formats (e.g., `ai:conversations:context:files:pdf`, `ai:conversations:context:files:docx`). + +|`ai:conversations:context:urls` +|Ability to use web URLs as context sources. +|=== + +[[actions-permissions]] +== Actions Permissions + +[cols="2,3"] +|=== +|Permission |Description + +|`ai:actions:*` +|Access to all action types, including custom and system actions. + +|`ai:actions:custom` +|Ability to run custom actions with free-form prompts. + +|`ai:actions:system:*` +|Access to all pre-defined system actions. + +|`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 + +[cols="2,3"] +|=== +|Permission |Description + +|`ai:reviews:*` +|Access to all review types, including custom and system reviews. + +|`ai:reviews:custom` +|Ability to run custom reviews with free-form prompts. + +|`ai:reviews:system:*` +|Access to all pre-defined system reviews. + +|`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. + +[[related-features]] +== Related Features + +* 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-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-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-review-plugin.adoc b/modules/ROOT/pages/tinymceai-review-plugin.adoc new file mode 100644 index 0000000000..2efe6b94fc --- /dev/null +++ b/modules/ROOT/pages/tinymceai-review-plugin.adoc @@ -0,0 +1,121 @@ += 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 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[] + +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 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: + +image::https://placehold.net/default.png[TinyMCE AI Review sidebar with suggestions] + +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] + +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 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 + +The feature comes with several review commands: + +[cols="1,1,1"] +|=== +|Command name |Command description |Additional information + +|**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_ +|=== + +[NOTE] +==== +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. diff --git a/modules/ROOT/pages/tinymceai-streaming.adoc b/modules/ROOT/pages/tinymceai-streaming.adoc new file mode 100644 index 0000000000..0374ac619a --- /dev/null +++ b/modules/ROOT/pages/tinymceai-streaming.adoc @@ -0,0 +1,126 @@ += TinyMCE AI Streaming + +:navtitle: Streaming +: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 users 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-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 + +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({ + // 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-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 + +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-review-plugin.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-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 new file mode 100644 index 0000000000..8ad3e7f7c5 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-with-jwt-authentication-nodejs.adoc @@ -0,0 +1,215 @@ += {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 + +include::partial$auth/tinymceai/nodejs/intro-and-prerequisites.adoc[] + +include::partial$auth/tinymceai/nodejs/initial-project-setup.adoc[] + +== Generate a Public/Private Key Pair + +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 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 + +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-jwt-authentication-intro.adoc#permissions[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 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) + +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()); + +// Private key (Replace this with the 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 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) + 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 the private key + const token = jwt.sign(payload, privateKey, { algorithm: 'RS256' }); + res.json({ 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 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 the `index.html` file was created, add the HTML setup code. + +[source,html] +---- + + + + TinyMCE with TinyMCE AI + + + + +

TinyMCE AI Demo

+ + + +---- + +== Configuration and Running + +include::partial$auth/tinymceai/nodejs/configuration-steps.adoc[] + +[NOTE] +==== +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 new file mode 100644 index 0000000000..6af4bc1556 --- /dev/null +++ b/modules/ROOT/pages/tinymceai-with-jwt-authentication-php.adoc @@ -0,0 +1,218 @@ += {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 + +include::partial$auth/tinymceai/php/intro-and-prerequisites.adoc[] + +include::partial$auth/tinymceai/php/initial-project-setup.adoc[] + +== Generate a Public/Private Key Pair + +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 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 + +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-jwt-authentication-intro.adoc#permissions[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 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) + +In the root directory, copy and paste the server setup code into the `jwt.php` file. + +[source,php] +---- + "JWT auth failed: " . $message))); +} + +// Check for OpenSSL extension +if (!extension_loaded('openssl')) { + fatalError('The openssl extension must be enabled in php.ini.'); +} + +// Enable CORS +header("Access-Control-Allow-Origin: *"); +header("Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept"); + +// JWT payload +$payload = array( + "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) + "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 the private key + $privateKey = << $token)); +} catch (Exception $e) { + fatalError($e->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 requirements. See xref:tinymceai-permissions.adoc[Permissions] for more details on available permissions. +==== + +== Configure TinyMCE + +[[configure-tinymce]] +=== Web Page (index.html) + +Inside the root directory where the `index.html` file was created, add the HTML setup code. + +[source,html] +---- + + + + TinyMCE with TinyMCE AI + + + + +

TinyMCE AI Demo

+ + + +---- + +== Configuration and Running + +include::partial$auth/tinymceai/php/configuration-steps.adoc[] + +[NOTE] +==== +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.adoc b/modules/ROOT/pages/tinymceai.adoc new file mode 100644 index 0000000000..f98a268441 --- /dev/null +++ b/modules/ROOT/pages/tinymceai.adoc @@ -0,0 +1,257 @@ += TinyMCE AI Plugin + +: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 + +include::partial$misc/admon-premium-plugin.adoc[] + +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::{plugincode}[] + +[[basic-setup]] +== Basic setup + +To setup the {pluginname} plugin in the editor: + +* add `{plugincode}` to the `plugins` option in the editor configuration; +* 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`; + +[[minimal-setup]] +=== Minimal setup + +[source,js] +---- +tinymce.init({ + selector: 'textarea', // change this value according to the HTML + plugins: 'tinymceai', + toolbar: 'showai aiquickactions aireview', + tinymceai_token_provider: function() { + // Return a promise that resolves to a JWT token + return fetch('/api/token').then(response => response.text()); + } +}); +---- + +[[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 + +The following configuration options affect the behavior of the {pluginname} plugin. + +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] + +include::partial$misc/plugin-menu-item-id-boilerplate.adoc[] + +include::partial$menu-item-ids/{plugincode}-menu-items.adoc[leveloffset=+1] + +[[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[] + +[[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, avoid configurations that may cause problems. + +=== Issues with tables + +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 the team works on resolving this issue, use 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 + +[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 + +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, send a follow-up message asking the Assistant to complete the previous request, or start a new conversation. + +NOTE: To stay informed about updates or discuss {pluginname} possibilities, please reach out. 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/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 new file mode 100644 index 0000000000..0031e6fb95 --- /dev/null +++ b/modules/ROOT/partials/auth/tinymceai/jwt-setup-tinymceai.adoc @@ -0,0 +1,86 @@ +[[setting-up-jwt-authentication]] +== Setting up JWT authentication + +To set up JSON Web Token (JWT) authentication for {productname} {pluginname}: + +. 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 {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 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. +==== 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..8e8c8fde10 --- /dev/null +++ b/modules/ROOT/partials/auth/tinymceai/nodejs/configuration-steps.adoc @@ -0,0 +1,31 @@ +== Configuration Steps + +=== Add 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 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 requirements +* See xref:tinymceai-permissions.adoc[Permissions] for available permissions and best practices + +=== Running the Project + +. Start the server: ++ +[source,bash] +---- +node jwt.js +---- + +. 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 new file mode 100644 index 0000000000..51213d134e --- /dev/null +++ b/modules/ROOT/partials/auth/tinymceai/nodejs/initial-project-setup.adoc @@ -0,0 +1,41 @@ +== 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] +---- +# 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 web files +mkdir public +touch public/index.html +touch jwt.js +---- + +The 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..b9ccddc90d --- /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/]. {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. + +=== What Will Be Built + +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 +* 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 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 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 new file mode 100644 index 0000000000..8879c3ab95 --- /dev/null +++ b/modules/ROOT/partials/auth/tinymceai/php/configuration-steps.adoc @@ -0,0 +1,31 @@ +== Configuration Steps + +=== Add 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 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 requirements +* See xref:tinymceai-permissions.adoc[Permissions] for available permissions and best practices + +=== Running the Project + +. Start the server: ++ +[source,bash] +---- +php -S localhost:3000 +---- + +. 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 new file mode 100644 index 0000000000..b8f8f89a3c --- /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 the 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 web files +touch index.html +touch jwt.php +---- + +The 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..9ec88dcce2 --- /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/]. {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. + +=== What Will Be Built + +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 +* 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 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 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 new file mode 100644 index 0000000000..540f410e65 --- /dev/null +++ b/modules/ROOT/partials/commands/tinymceai-cmds.adoc @@ -0,0 +1,18 @@ +[cols="1,2"] +|=== +|Command name |Description + +|`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'); +---- 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 new file mode 100644 index 0000000000..2e9092b67e --- /dev/null +++ b/modules/ROOT/partials/configuration/tinymceai_token_provider.adoc @@ -0,0 +1,33 @@ +[[tinymceai-token-provider]] +== `+tinymceai_token_provider+` + +*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, fetch the JWT token from the backend server rather than hardcoding it. For example: + +[source,js] +---- +tinymce.init({ + selector: 'textarea', + plugins: 'tinymceai', + tinymceai_token_provider: function() { + 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 new file mode 100644 index 0000000000..710b38c055 --- /dev/null +++ b/modules/ROOT/partials/events/tinymceai-events.adoc @@ -0,0 +1,15 @@ +[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/index-pages/premium-plugins.adoc b/modules/ROOT/partials/index-pages/premium-plugins.adoc index 8f1777535e..90b06e5a2a 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-introduction.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..84fa199c5f --- /dev/null +++ b/modules/ROOT/partials/plugin-apis/tinymceai-apis.adoc @@ -0,0 +1 @@ +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 new file mode 100644 index 0000000000..51ea2a2cec --- /dev/null +++ b/modules/ROOT/partials/toolbar-button-ids/tinymceai-toolbar-buttons.adoc @@ -0,0 +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 +|===