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 [e-mail].