@sitevision/api 2025.1.1 → 2025.1.2

package/common/router/index.d.ts

@@ -57,6 +57,7 @@ export interface Response {
   redirect(path: string, query?: string, status?: number): void;
   cookie(cookie: Cookie): void;
   clearCookie(name: string, path?: string): void;
+  flush(): void;
 
   /**
    * This method will render a component with data

package/index.d.ts

@@ -132,6 +132,7 @@ import './server/WebContentUtil';
 import './server/WebResourceFactory';
 import './server/XSLTUtil';
 import './server/XmlParserUtil';
+import './server/ai';
 import './server/appData';
 import './server/appInfo';
 import './server/appResource';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sitevision/api",
-  "version": "2025.1.1",
+  "version": "2025.1.2",
   "author": "Sitevision AB",
   "license": "MIT",
   "type": "module",
@@ -30,5 +30,5 @@
     "access": "public",
     "directory": "dist"
   },
-  "gitHead": "fef445686db4d5d6ccf41b93179735c9604c05f8"
+  "gitHead": "fad9ce2f6b699279e49c3bf5fb234b0f37605dc8"
 }

package/server/MimeTypeUtil/index.d.ts

@@ -235,6 +235,46 @@ export interface MimeTypeUtil extends MimeTypeUtilConstants {
    * @since Sitevision 2024.04.1
    */
   isAudioType(aFileExtensionExpression: String | string): boolean;
+
+  /**
+   * Checks if a specified file extension is a JSON type (according to its mapped MIME type).
+   * @param aFileExtensionExpression a file extension (e.g "json") or an expression that ends with a period and a file extension
 (e.g "myfile.json" or "https://www.xyz.com/files/myfile.json"). Case insensitive.
+   * @return true if aFileExtensionExpression is mapped to a MIME type that depicts the JSON format, false otherwise
+   * @see #isJsonMime(String)
+   * @since Sitevision 2025.01.2
+   */
+  isJsonType(aFileExtensionExpression: String | string): boolean;
+
+  /**
+   * Checks if a specified MIME type depicts the JSON format.
+   *
+   *  <p>
+   *     The primary JSON format MIME is <code>"application/json"</code> and should always be handled as UTF-8 text. Other MIME:s that uses the JSON
+   *     format typically has a <code>"+json"</code> suffix (see <a href="https://www.rfc-editor.org/rfc/rfc6839#section-3.1">RFC 6839</a>)
+   *     or a <code>"+json-seq"</code> suffix (see <a href="https://www.rfc-editor.org/rfc/rfc8091#section-3">RFC 8091</a>). But there
+   *     are also some legacy/unofficial MIME:s that also depicts the JSON format (e.g. "text/json", "application/jsonrequest").
+   *     Example of typical MIME types that depicts the JSON format:
+   *  </p>
+   *  <ul>
+   *     <li>application/json</li>
+   *     <li>application/vnd.api+json</li>
+   *     <li>application/vnd.restful+json</li>
+   *     <li>application/ld+json</li>
+   *     <li>application/ld-frame+json</li>
+   *     <li>application/jsonml+json</li>
+   *     <li>application/geo+json</li>
+   *     <li>application/calendar+json</li>
+   *  </ul>
+   *
+   *  <p>
+   *     A <code>Content-Type</code> header value for a JSON response is typically <code>"application/json; charset=utf-8"</code>.
+   *     This method handles such values, only the leading MIME part will be checked (any semicolon suffix part will be completely ignored).
+   *  </p>
+   * @param aMimeType a MIME value or Content-Type header value
+   * @return true if aMimeType matches a MIME that depicts the JSON format, false otherwise
+   * @since Sitevision 2025.01.2
+   */
+  isJsonMime(aMimeType: String | string): boolean;
 }
 
 declare namespace MimeTypeUtil {}

package/server/MimeTypeUtil/index.js

@@ -17,5 +17,7 @@ var _default = exports["default"] = {
   isMSPowerpointType: function isMSPowerpointType() {},
   isMSOfficeType: function isMSOfficeType() {},
   isFontType: function isFontType() {},
-  isAudioType: function isAudioType() {}
+  isAudioType: function isAudioType() {},
+  isJsonType: function isJsonType() {},
+  isJsonMime: function isJsonMime() {}
 };

package/server/OutputUtil/index.d.ts

@@ -276,6 +276,21 @@ export interface OutputUtil extends OutputUtilConstants {
    */
   getNodeAsText(aNode: Node): string;
 
+  /**
+   * Gets the output as a specific content-type from a page node.
+   *
+   *  <p>
+   *     <strong>Note! Due to security reasons (potential never-ending loops) it is prohibited to get the output of
+   *     the currently executing page (i.e. {@link senselogic.sitevision.api.context.PortletContextUtil#getCurrentPage()})!</strong>
+   *  </p>
+   * @param aPageNode a page node (sv:page, sv:article, sv:sitePage) where current user has READ permission, must not be null or "current page".
+   * @param aContentType a content-type marker, i.e. {@link #CONTENT_TYPE_TEXT_PLAIN}, {@link #CONTENT_TYPE_TEXT_HTML} or&#xA; {@link #CONTENT_TYPE_TEXT_XML}
+   * @return the output result for specified aContentType.&#xA; If aPageNode is null or "current page", an empty String is returned.&#xA; If current user doesn't have READ permission on aPageNode, an empty String is returned.
+   * @see #getNodeOutput(Node, Node, int)
+   * @since Sitevision 2025.01.2
+   */
+  getNodeOutput(aPageNode: Node, aContentType: number): string;
+
   /**
    * Gets the output as a specific content-type from a page node or a page content node.
    *
@@ -289,7 +304,7 @@ export interface OutputUtil extends OutputUtilConstants {
    *  </p>
    * @param aPageNode a page node (sv:page, sv:article, sv:sitePage) where current user has READ permission, must not be null or "current page".
    * @param aPagePartNode a page part node that exist as content on aPageNode (or null if you want the complete output from aPageNode).
-   * @param aContentType a content-type marker, i.e.&#xA; <a href="#CONTENT_TYPE_TEXT_PLAIN">CONTENT_TYPE_TEXT_PLAIN</a>,&#xA; <a href="#CONTENT_TYPE_TEXT_HTML">CONTENT_TYPE_TEXT_HTML</a> or&#xA; <a href="#CONTENT_TYPE_TEXT_XML">CONTENT_TYPE_TEXT_XML</a>.
+   * @param aContentType a content-type marker, i.e. {@link #CONTENT_TYPE_TEXT_PLAIN}, {@link #CONTENT_TYPE_TEXT_HTML} or&#xA; {@link #CONTENT_TYPE_TEXT_XML}
    * @return the output result for specified aContentType.&#xA; If aPageNode is null or "current page", an empty String is returned.&#xA; If current user doesn't have READ permission on aPageNode, an empty String is returned.&#xA; If aPagePartNode is null, the output result of aPageNode is returned.&#xA; If aPagePartNode doesn't exist as content on aPageNode, an empty String is returned.
    * @since Sitevision 2.6
    */

package/server/ai/index.d.ts

@@ -0,0 +1,211 @@
+import type { Node } from '../../types/javax/jcr/Node';
+
+/**
+ * Represents a message in an AI conversation.
+ */
+export interface Message {
+  /**
+   * The role of the entity generating the message.
+   * - `system`: Provides context or instructions.
+   * - `user`: Represents the end user.
+   * - `assistant`: Represents the AI model.
+   */
+  role: 'system' | 'user' | 'assistant';
+
+  /**
+   * The actual content of the message.
+   */
+  content: string;
+}
+
+/**
+ * Options for generating text using an AI model.
+ */
+export interface GenerateTextOptions {
+  /**
+   * Messages that form the conversation context.
+   */
+  messages: Message[];
+
+  /**
+   * Maximum duration (in milliseconds) before timing out.
+   * The default value and valid range are environment-dependent and can be 
+   * configured via a system property. If not explicitly set, the system 
+   * determines an appropriate timeout value.
+   */
+  timeout?: number;
+
+  /**
+   * The maximum number of tokens (words/word fragments) the model can generate.
+   */
+  maxTokens?: number;
+
+  /**
+   * Controls response randomness:
+   * - Lower values (e.g., 0) make responses deterministic.
+   * - Higher values (e.g., 1) increase variability.
+   */
+  temperature?: number;
+
+  /**
+   * Reduces repeated token usage in generated text.
+   * Higher values promote more diverse output.
+   */
+  frequencyPenalty?: number;
+}
+
+/**
+ * Result object for text generation.
+ */
+export interface GenerateTextResult {
+  /**
+   * The generated text output from the AI model.
+   */
+  text: string;
+
+  /**
+   * Contains an error message if something went wrong, otherwise an empty string.
+   */
+  error: string;
+
+  /**
+   * The reason why the generation process stopped.
+   * Possible values:
+   * - `stop`: Completed successfully.
+   * - `length`: Stopped due to reaching max tokens.
+   * - `error`: Failed unexpectedly.
+   * - `other`: Other reasons (model/system behavior).
+   */
+  finishReason: string;
+
+  /**
+   * (Optional) Token usage statistics for this request.
+   */
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+/**
+ * Options for streaming text from an AI model.
+ */
+export interface StreamTextOptions {
+  /**
+   * Messages that form the conversation context.
+   */
+  messages: Message[];
+
+  /**
+   * Maximum duration (in milliseconds) before timing out.
+   * The default value and valid range are environment-dependent and can be 
+   * configured via a system property. If not explicitly set, the system 
+   * determines an appropriate timeout value.
+   */
+  timeout?: number;
+
+  /**
+   * The maximum number of tokens (words/word fragments) the model can generate.
+   */
+  maxTokens?: number;
+
+  /**
+   * Controls response randomness:
+   * - Lower values (e.g., 0) make responses deterministic.
+   * - Higher values (e.g., 1) increase variability.
+   */
+  temperature?: number;
+
+  /**
+   * Reduces repeated token usage in generated text.
+   * Higher values promote more diverse output.
+   */
+  frequencyPenalty?: number;
+
+  /**
+   * Callback function that is triggered for each received token.
+   * The function receives the token as a string.
+   *
+   * @param token The streamed token received from the AI model.
+   */
+  onChunk: (token: string) => void;
+
+  /**
+   * Callback function triggered when the streaming operation completes.
+   *
+   * @param result The final result of the stream operation.
+   */
+  onFinish: (result: StreamFinishResult) => void;
+}
+
+/**
+ * Final result object for a streaming text operation.
+ */
+export interface StreamFinishResult {
+  /**
+   * Always an empty string (for structural consistency with `GenerateTextResult`).
+   */
+  text: string;
+
+  /**
+   * Contains an error message if something went wrong, otherwise an empty string.
+   */
+  error: string;
+
+  /**
+   * The reason why the streaming process stopped.
+   * Possible values:
+   * - `stop`: Completed successfully.
+   * - `length`: Stopped due to reaching max tokens.
+   * - `error`: Failed unexpectedly.
+   * - `other`: Other reasons (model/system behavior).
+   */
+  finishReason: string;
+
+  /**
+   * (Optional) Token usage statistics for this request.
+   */
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+/**
+ * AI SDK for interacting with Large Language Models (LLMs).
+ */
+export interface AI {
+  /**
+   * Generates text based on provided messages.
+   *
+   * @param llmConfiguration The AI model configuration node.
+   * @param options Options for text generation.
+   * @returns The generated text result.
+   */
+  generateText(
+    llmConfiguration: Node,
+    options: GenerateTextOptions
+  ): GenerateTextResult;
+
+  /**
+   * Streams generated text from an AI model.
+   *
+   * This function does not return a value. Instead, it processes streamed responses
+   * using the provided `onChunk` and `onFinish` callback functions.
+   *
+   * @param llmConfiguration The AI model configuration node.
+   * @param options Options for streaming text.
+   */
+  streamText(llmConfiguration: Node, options: StreamTextOptions): void;
+}
+
+declare namespace AI {}
+
+/**
+ * The AI SDK instance.
+ */
+declare var ai: AI;
+
+export default ai;

package/server/ai/index.js

@@ -0,0 +1,10 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = void 0;
+var _default = exports["default"] = {
+  generateText: function generateText() {},
+  streamText: function streamText() {}
+};