sandai-core

The sandai-core package provides the core functionality for the Sandai 3D AI Characters. It includes a framework for managing interactions with an embedded iframe, sending and receiving messages, and constructing URLs with typed query parameters.

Features

• Iframe Communication: Send and receive messages between the main window and an embedded Sandai iframe.
• Interaction Management: Use the InteractionManager to control AI character speech and interaction.
• Typed URL Builder: Easily construct URLs with typed query parameters.

Installation

To install sandai-core, run:

npm install sandai-core

Usage

1. Initializing SandaiClient

The SandaiClient class manages iframe communication and provides an interface for interaction.

<iframe 
  id="myIframeId" 
  src="https://sandai.org/chat">
</iframe>

import { SandaiClient } from "sandai-core";

const sandaiClient = new SandaiClient("myIframeId");

Parameters

• iframeId (string): The ID of the target iframe element in the DOM.

Throws

• Error: If the specified element does not exist or is not an iframe.

2. Interaction Manager

The InteractionManager class allows communication with the Sandai iframe.

Example: Making the AI character speak

import { SandaiClient } from "sandai-core";

const sandaiClient = new SandaiClient("myIframeId");
sandaiClient.interactionManager.say("Hello, world!");
sandaiClient.interactionManager.stop();

Interaction Manager Methods

• say(message: string): Sends a speech message to the iframe.
• stop(): Stops the AI character from speaking.

3. URL Builder

The UrlBuilder class simplifies the process of constructing URLs with typed query parameters.

Example

import { UrlBuilder } from "sandai-core";

interface Params {
  userId: number;
  search: string;
  isActive: boolean;
}

const url = new UrlBuilder<Params>("https://example.com")
  .setParam("userId", 123)
  .setParam("search", "test")
  .setParam("isActive", true)
  .build();

console.log(url); // "https://example.com?userId=123&search=test&isActive=true"

URL Builder Methods

• setParam<K extends keyof T>(key: K, value: T[K]): this: Sets a query parameter in the URL.
• build(): string: Returns the fully constructed URL with query parameters.

API Documentation

SandaiClient

| Method | Description | |--------|-------------| | new SandaiClient(iframeId: string) | Initializes the client with the specified iframe ID. | | _sendMessage(data: any) | Sends a message to the iframe. | | _listenForMessage(callback: (data: any) => void) | Listens for messages from the iframe. | | _getDocs() | Retrieves documentation for the interaction manager. |

InteractionManager

| Method | Description | |--------|-------------| | say(message: string) | Sends a speech message to the iframe. | | stop() | Stops speech from the iframe. | | _sendMessage(data: SendSpeechMessage \| StopSpeechMessage) | Sends a message to the iframe. | | _listenForMessage(callback: (data: any) => void) | Listens for messages from the iframe. | | _getDocs() | Retrieves documentation for available interaction methods. |

UrlBuilder

| Method | Description | |--------|-------------| | new UrlBuilder<T>(baseUrl: string) | Creates a new URL builder with the given base URL. | | setParam<K extends keyof T>(key: K, value: T[K]): this | Sets a query parameter in the URL. | | build(): string | Builds and returns the final URL. |

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Feel free to submit a pull request or open an issue.

Contact

For support or inquiries, please reach out to [email protected].