Builds a content object compatible with an AI session, optionally inserting it into an external array.

• Object: The constructed content object, if contents is not an array.
• undefined: If the contents parameter is an array, the method pushes to the array and returns undefined.

• Constructs a content object with validated parts using internal #_partTypes.
• Includes a role if provided.
• Includes a finishReason field unless rmFinishReason is explicitly true.
• Supports both item.parts as an array or a singular item.content object.

const message = session.buildContents(null, {
  parts: [{ text: "Hello!" }],
  finishReason: "stop"
}, "user");

Note: This method is flexible for both single and batched usage. If contents is provided as an array, it's assumed you are accumulating multiple content objects for submission.

Counts tokens by sending a request to an external API, processing the response, and returning relevant token data. If the function isn't set or the request fails, an error is thrown.

• Request Logic:
  The method sends a POST request to an external API using the fetch function, passing the necessary apiKey and model. It also serializes the dataContent to be used in the request body.

• Response Handling:
  The response from the API is processed to extract several pieces of token information, such as:

  • Total Tokens: The total number of tokens used.
  • Cached Content Token Count: The token count for any cached content.
  • Prompt Token Details: Information about tokens used in the prompt (e.g., modality and token count).

• Error Handling:
  If the API returns an error, it uses the buildErrorData function to capture and handle the error appropriately.

• Promise Usage:
  Since the request is asynchronous, the method returns a Promise which resolves with the token data once the response is successfully received. If any error occurs during the request, it rejects the promise.

// Set the function to count tokens
tinyAi._setCountTokens(
  (apiKey, model, controller, data) => 
    new Promise((resolve, reject) => {
      const dataContent = requestBuilder(data);  // Prepares data for the request
      const modelInfo = tinyAi.getModelData(model);  // Retrieves model data
      dataContent.model = modelInfo?.name;  // Adds model name to request
      
      // Check if contents are available to process
      if (Array.isArray(dataContent.contents) && dataContent.contents.length > 0) {
        fetch(`${apiUrl}/models/${model}:countTokens?key=${encodeURIComponent(apiKey)}`, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ generateContentRequest: dataContent }),
          signal: controller ? controller.signal : undefined,
        })
          .then((res) => res.json())  // Parse JSON response
          .then((result) => {
            const finalData = { _response: result };
            
            // Handle the successful response
            if (!result.error) {
              finalData.totalTokens = result.totalTokens || null;
              finalData.cachedContentTokenCount = result.cachedContentTokenCount || null;
              finalData.promptTokensDetails = result.promptTokensDetails || {};
            } else {
              // Handle errors
              buildErrorData(result, finalData);
            }

            resolve(finalData);  // Resolve the promise with the final token data
          })
          .catch(reject);  // Reject promise on error
      } else {
        resolve({ _response: {}, totalTokens: null, cachedContentTokenCount: null });
      }
    })
);

// Example call:
const tokenData = tinyAi.countTokens(data, model, controller);
console.log(tokenData);

This function retrieves error details based on the provided error code. It checks if there is any error data associated with the code and returns a structured object with the error message. If no error is found, it returns null.

• Error Lookup:

  • The method first checks if the _errorCode object exists.
  • It looks for the provided error code within the _errorCode object.

• Error Data Handling:

  • If the error data exists and is a string, it returns an object with the text key containing the error message.
  • If the error data is an object and contains a text property, it returns that object.

• Return Value:

  • Returns an object containing the error message if found.
  • If no error is found for the provided code, it returns null.

// Example error code lookup
const errorDetails = tinyAi.getErrorCode(404);
console.log(errorDetails);  // Output: { text: 'Not Found' }

// Example with a custom error object
const customErrorDetails = tinyAi.getErrorCode('SERVER_ERROR');
console.log(customErrorDetails);  // Output: { text: 'Internal Server Error' }

This function is responsible for generating content through a content generation API. It checks whether the content generation function (#_genContentApi) has been defined and then calls it to handle the actual API interaction.

1. API Function Check:

   • The function first checks if #_genContentApi is a defined function. If it is, it calls this function to generate content using the provided parameters.
   • If #_genContentApi is not defined, it throws an error, indicating that no content generation API script has been set up.

2. Parameters:

   • data: The content generation input data (this could be a prompt or specific details for the API).
   • model: Specifies which model to use for content generation (optional, defaults to a predefined model if not provided).
   • controller: A controller object that may be used to manage the content generation process (e.g., for cancellation or timeouts).
   • streamCallback: An optional callback function that handles streaming content if the API supports it.

3. Calling the Internal API Function:

   • If the API function exists, it is invoked with the following parameters:
     • API key (this.#_apiKey)
     • Streaming flag (true/false)
     • The data provided (data)
     • Model to use (either provided or default)
     • Stream callback function (if provided)
     • Controller (if provided)
   • If no API script is defined, an error is thrown.

The actual content generation function is set using ._setGenContent(). This function defines how the API request will be made, handles both streaming and non-streaming responses, and processes the results.

1. Request Handling:

   • A Promise is returned to handle the asynchronous request.
   • The requestBody is created by calling requestBuilder(data), which structures the provided data according to the API's expectations.

2. Usage Metadata:

   • The function defines a helper method buildUsageMetada(result) to process the token usage metadata returned by the API. This includes counting tokens for candidates, prompts, and totals.
   • If the metadata is missing, an error is logged.

3. Content Construction:

   • buildContent(result, finalData) processes the response to extract relevant content from the API response (typically from the candidates field), and adds it to the finalData.contents array.
   • It also adds a "finish reason" (if available) to the content items.

4. Streaming Response:

   • If the request is for streaming, the streamingResponse function is used to handle the streamed data in real-time.
   • The response is read in chunks using a TextDecoder, and each chunk is processed as JSON. Each chunk is passed to the streamingCallback for handling as it arrives.
   • Streaming continues until all data has been received.

5. Final Data Processing:

   • Once the streaming is complete (or if the request is non-streaming), the final data is processed:
     • finalData is populated with content and token usage metadata.
     • If an error occurred, error data is processed instead.

6. Making the Request:

   • The function makes a fetch request to the API endpoint, either for generating content normally or for streaming.
   • The request uses the POST method and includes the requestBody in the payload as JSON.
   • If the request is for streaming, it is processed through streamingResponse.

7. Error Handling:

   • There is comprehensive error handling throughout, including:
     • If the API response is invalid or contains errors.
     • If the request fails (either in streaming or non-streaming cases).
     • Specific messages are logged for debugging.

• The genContent function is a wrapper for generating content through an external API.
• The function checks if the necessary API function (#_genContentApi) is available, then calls it to initiate the content generation process.
• It handles both normal and streaming content generation, processing API responses and building the final data accordingly.
• The streamingCallback allows real-time handling of streamed content as it arrives.

This method retrieves the stored data for a specific session ID. If no id is passed, it uses the currently selected session ID.

To access session-specific data from the internal history store, either by a given ID or by the currently active session.

• Calls getId(id) to resolve the correct session ID:
  • Returns the given id if valid and in multi-session mode.
  • Otherwise, falls back to this.#_selectedHistory.
• Returns the corresponding entry in this.history or null if not found.

// Returns data for a specific ID
const sessionData = tinyAi.getData("session_abc");

// Returns data for currently selected session
const currentData = tinyAi.getData();

This method is commonly used internally when accessing session content like messages, token counts, or metadata tied to a specific conversation. It ensures consistent session resolution by relying on getId(id).

This method calculates the total number of tokens used in a specific or currently selected session.

To aggregate all token counts stored in the tokens object of a session, including:

• Per-message tokens (tokens.data)
• Other numeric token values in tokens (e.g. summary, cached count)

1. Calls getData(id) to resolve the session history.
2. If session exists:
   • Iterates over history.tokens.data[], adding each count value.
   • Then checks every property in history.tokens (besides .data) and adds numeric values.
3. Returns the total count or null if no session was found.

{
  tokens: {
    data: [
      { count: 56 },
      { count: 72 },
      ...
    ],
    cachedContentTokenCount: 12,
    summary: 8
  }
}

const total = tinyAi.getTotalTokens("session_456");
// e.g., returns 148 (from data) + 12 + 8 = 168

const currentTotal = tinyAi.getTotalTokens();
// Returns total tokens of currently selected session

• It’s a hybrid aggregation — combines array entries (tokens.data) and top-level numeric fields inside the tokens object.
• Will gracefully return null if the session doesn’t exist or lacks token data.

This method retrieves token data for a specific message in a session history based on its index.

To return a single entry from the tokens.data[] array of a session, which typically contains token analysis per message.

1. Calls getData(id) to access session history.
2. Verifies that the message index exists using indexExists(msgIndex, id).
3. If it exists, returns the token data at tokens.data[msgIndex].

{
  count: 87
}

const tokenInfo = tinyAi.getMsgTokensByIndex(3, "session_123");
// Might return: { count: 87 }

const currentTokenInfo = tinyAi.getMsgTokensByIndex(2);
// Uses currently selected session

• Assumes that token data was previously added using addData(...) or another internal method.
• This method does not compute or update token counts, only retrieves what was stored.

This method retrieves token data for a specific message, identified by its unique msgId, within a given or currently selected session.

To provide access to token analysis (like token count, type, modality) for a specific message in the history, based on its message ID rather than its index.

const history = this.getData(id);
if (history) {
  const msgIndex = this.getIndexOfId(msgId);
  if (msgIndex > -1)
    return history.tokens.data[msgIndex];
}
return null;

• getData(id) retrieves the session history object.
• getIndexOfId(msgId) returns the index of the message with that ID.
• Returns token data at that index if valid.

{
  count: 64
}

const tokens = tinyAi.getMsgTokensById("msg_890", "session_001");
// Might return: { count: 64 }

• It does not calculate token counts, just accesses the token metadata already stored.
• Useful for internal features like detailed analytics, audits, or debugging specific message performance.

This method retrieves the hash value of a specific message from the session history using its index.

To fetch the hash of a message at a given index in the session history. Hash values are typically used for integrity checks, verification, or ensuring that message data has not been altered.

const history = this.getData(id);
if (history) {
  const existsIndex = this.indexExists(msgIndex, id);
  if (existsIndex) return history.hash.data[msgIndex];
}
return null;

• getData(id) retrieves the session history.
• indexExists(msgIndex, id) checks if the provided index exists within the history.
• If the index is valid, the corresponding hash value is returned from the history.hash.data array.

const hash = tinyAi.getMsgHashByIndex(2, "session_001");
// Might return: "ab123c456d789fgh1234567890abcdef"

• The method does not generate a hash; it retrieves it from pre-existing data stored during previous sessions.
• Useful for verifying the integrity or identity of a message during debugging or data synchronization tasks.

This method retrieves the hash value of a specific message from the session history using its message ID.

To fetch the hash of a message by its unique message ID from the session history. The hash can be used for verifying message integrity, checksums, or ensuring consistency in data.

const history = this.getData(id);
if (history) {
  const msgIndex = this.getIndexOfId(msgId);
  if (msgIndex > -1) return history.hash.data[msgIndex];
}
return null;

• getData(id) retrieves the session history data.
• getIndexOfId(msgId) finds the index of the message with the given ID in the session's data.
• If the message ID is valid (i.e., it exists in the session), it returns the corresponding hash from history.hash.data.

const hash = tinyAi.getMsgHashById("msg123", "session_001");
// Might return: "ab123c456d789fgh1234567890abcdef"

• This method relies on the existence of the message ID in the session history.
• It is useful for identifying or validating specific messages based on their IDs, especially in scenarios like debugging, data validation, or ensuring message integrity across sessions.

This method checks if a specific index exists in the session history.

To determine whether a message exists at a given index in the session history. It ensures that the requested index is valid and points to an existing message.

return this.getMsgByIndex(index, id) ? true : false;

• getMsgByIndex(index, id) is called to retrieve the message at the specified index for the session with the given id.
• If the message is found, it returns true. If the message is not found (i.e., the index is invalid or does not exist), it returns false.

const exists = tinyAi.indexExists(3, "session_001");
// Returns: true if there's a message at index 3 in the session "session_001", otherwise false.

• This method acts as a helper to validate that the given index corresponds to an actual message in the session history.
• It relies on the getMsgByIndex method, so if the index doesn't exist, that method will return null or an invalid result, which will cause indexExists to return false.

Retrieves a specific message object from the session history by its index.

This method is used to access a single message stored in a session’s history using its numerical index. The message objects are previously constructed using the buildContent method and stored in a structured format under the data property of the session history.

• getData(id) is used to retrieve the session history object.
• If a valid history is found and there is an entry at data[index], it returns that message.
• If the index is invalid or the session doesn’t exist, it returns null.

const msg = sessionManager.getMsgByIndex(3);
// → Returns the message object at index 3 in the currently selected session, or null if not found.

The message object is expected to be the result of a call to buildContent(...), so it may include structured properties like role, content, timestamp, meta, etc., depending on your implementation.

Retrieves a specific message object from the session history using its unique message ID.

This method allows you to access a specific message stored in a session by referencing its unique msgId. The messages are objects previously created via buildContent and stored inside the data structure of the session.

• Uses getData(id) to fetch the session history.
• Resolves the message's index with getIndexOfId(msgId).
• If valid data exists at that index, the message object is returned.
• Returns null if the session doesn't exist, the ID is not found, or the data is missing at the resolved index.

const message = sessionManager.getMsgById("msg-abc123");
// → Returns the full message object, or null if not found.

Retrieves the index position of a message within the session history using its unique message ID.

This method searches for a specific message ID inside the session's ids array and returns its index. This index is typically used to retrieve related data (e.g., message content, tokens, or hashes) stored in parallel arrays like data, tokens, or hash.

• Accesses the current or specified session via getData(id).
• Searches for the msgId in the ids array using indexOf.
• Returns the corresponding index if found.
• If not found or if the session is invalid, returns -1.

const index = sessionManager.getIndexOfId("msg-abc123");
// → Might return 5, or -1 if the message ID isn't in the session.

Retrieves the message ID located at a specific index within the session history.

This method is used to fetch the message ID that corresponds to a given index in the session’s history. The index is validated based on the existence of a message entry in history.data. If the index is invalid or data is missing, -1 is returned.

• Retrieves session data using getData(id).
• Checks if a message exists at the specified index inside history.data.
• If valid, returns the corresponding ID from history.ids.
• If the index is invalid or data is missing, returns -1.

const msgId = sessionManager.getIdByIndex(3);
// → Might return "msg-xyz789" or -1 if the index doesn't exist.

Deletes a specific message entry at a given index within the session history.

This method removes all data related to a message from the session history arrays (data, ids, hashes, and tokens) based on a specific index. It also emits a deleteIndex event to notify subscribers of the deletion.

• Retrieves the session history using getData(id).
• Validates the existence of data at the specified index.
• If valid:
  • Removes entries from all relevant arrays: data, ids, hash.data, and tokens.data.
  • Emits a deleteIndex event with the index, message ID, and session ID.
  • Returns true.
• If invalid:
  • Returns false.

const success = sessionManager.deleteIndex(2);
if (success) {
  console.log("Entry deleted.");
} else {
  console.log("Entry not found or index invalid.");
}

Replaces an existing message entry in the session history at the specified index with new data and/or token count.

• Retrieves the session history using getData(id).
• Verifies if the specified index exists.
• If either data or tokens is provided and the index is valid:
  • Replaces history.data[index] with the new data, if provided.
  • Updates the hash at history.hash.data[index] using objHash(data).
  • Updates the token count at history.tokens.data[index], if tokens is provided.
  • Emits a replaceIndex event with the updated information.
  • Returns true.
• If no valid data or tokens is passed, or the index is invalid, returns false.

sessionManager.replaceIndex(3, { role: "user", content: "Updated message." }, 40);

Retrieves the index of the last entry in the session history.

• Uses getData(id) to retrieve the session history.
• Checks if the last item in history.data exists.
• If valid, returns the index of the last item (length - 1).
• If the history is invalid or empty, returns -1.

const last = sessionManager.getLastIndex(); // returns the last message index

Retrieves the data of the last entry in the session history.

• Uses getData(id) to retrieve the session history.
• Checks if the last entry exists in history.data.
• Returns the last item if valid; otherwise returns null.

const lastData = sessionManager.getLastIndexData();
if (lastData) {
  console.log("Last message content:", lastData.content);
}

Checks if the session history has at least one valid entry.

• Retrieves session history using getData(id).
• Returns true if the first entry in history.data exists and is truthy.
• Otherwise, returns false.

if (sessionManager.existsFirstIndex()) {
  console.log("The session contains at least one message.");
}

Retrieves the first entry from the session history.

• Uses getData(id) to retrieve the current session's history object.
• Returns the first element in the history.data array if present.
• Returns null if the session history is invalid or empty.

const firstEntry = sessionManager.getFirstIndexData();
if (firstEntry) {
  console.log("First message:", firstEntry);
}

Adds new data to the selected session history.

• Uses this.getId(id) to retrieve the selected session ID.
• If the session history exists for the selected session, it increments the nextId and adds the new data entry to the data, tokens.data, ids, and hash.data arrays.
• Emits the addData event with the new ID, data, token content, hash, and session ID.

try {
  const newData = { content: "New message data" };
  const tokenInfo = { count: 5 };
  const newId = sessionManager.addData(newData, tokenInfo);
  console.log(`New data added with ID: ${newId}`);
} catch (error) {
  console.error(error.message);
}

This method is responsible for adding new entries into the session history while tracking token-related data. The tokenData can be passed to associate additional information, like a count, with the new data entry.

Resets all stored data associated with a given session.

• Retrieves the target session ID using this.getId(id).
• Validates whether the selected session ID exists in the session history.
• If the session contains stored items, it repeatedly deletes the first index (deleteIndex(0)) until the session becomes empty.
• Returns a numeric status code representing the outcome.

const status = sessionManager.resetContentData();

switch (status) {
  case 0:
    console.log("No valid session found.");
    break;
  case 1:
    console.log("Session found but already empty.");
    break;
  case 2:
    console.log("Session data successfully cleared.");
    break;
}

This method ensures that a session's stored data is fully cleared, providing clear return codes to help you handle different outcomes in your application logic.