# Amily-Databin

A Databin component designed to optimize data storage persistence. It does not directly provide a user interface but is intended for developers to call for data operations.

The purpose of this component is to simplify data storage for developers, offering a straightforward method for data storage with persistence support. This component solely manages data storage and retrieval; it does not offer a user interface. (However, this does not mean the component cannot be used for user interfaces; users are encouraged to design their own user interfaces.)

## Installation

### Install via Link (Recommended)

1.  In the SillyTavern extensions page, click "Install from URL".
2.  Enter the following link: `https://amily-gitlab.amily49.cc/slvccans/Amily-Databin`
3.  Click "Install".
4.  Restart SillyTavern.

### Manual Installation

1.  Download the ZIP archive of this repository.
2.  Extract the ZIP file.
3.  Copy the `Amily-Databin` folder to the `SillyTavern/public/extensions` directory.
4.  Restart SillyTavern.

## Usage

This plugin acts as a data bucket component and does not provide a user interface. It is primarily intended for developers to call.

## API Usage

This plugin injects a global `window.AmilyDatabin` object into the client-side environment for simplified, granular data interaction.

**Architectural Note:** The `SourceType` constants table is dynamically managed via the `sourcetype.json` file. The client automatically fetches this configuration from the server upon loading, making the system extensible without requiring client-side code changes.

### `AmilyDatabin.SourceType`

A constants table used to define the source of the data.

```javascript
{
    CHAT_LOG: 1,       // For chat log storage
    CHARACTER_CARD: 2, // For character card storage
    WORLD_BOOK: 3      // For world book storage
}
```

### `AmilyDatabin.getData(source, fileName, objName = null)`

Retrieves specific data from the server. The `objName` is optional and will be auto-detected from the current context if omitted.

```javascript
/**
 * Fetches specific data from the server.
 * @param {number} source - The data source identifier (use AmilyDatabin.SourceType).
 * @param {string} fileName - The file name or unique key for the data.
 * @param {string} [objName=null] - Optional. The specific object name (e.g., character ID). If null, it's auto-detected. **Note: For `WORLD_BOOK` type, `objName` cannot be automatically detected and must be provided explicitly.**
 * @returns {Promise<object|null>} A Promise that resolves to the requested data object, or null if not found.
 */
async function retrieveCurrentCharacterMemory() {
    try {
        // We omit objName, so the plugin will automatically use the current character's ID.
        const memory = await window.AmilyDatabin.getData(
            window.AmilyDatabin.SourceType.CHARACTER_CARD,
            "character_memory.json"
        );
        
        if (memory) {
            console.log("Retrieved current character memory:", memory);
        } else {
            console.log("No memory found for the current character.");
        }
        return memory;
    } catch (error) {
        console.error("Failed to retrieve data:", error);
        return null;
    }
}

// Example call for automatic context:
retrieveCurrentCharacterMemory();
```

### `AmilyDatabin.saveData(source, fileName, fileContent, objName = null)`

Saves a JavaScript object to a specific path on the server. The `objName` is optional.

```javascript
/**
 * Saves a data object to a specific path on the server.
 * @param {number} source - The data source identifier (use AmilyDatabin.SourceType).
 * @param {string} fileName - The file name or unique key for the data.
 * @param {object} fileContent - The JavaScript object to save.
 * @param {string} [objName=null] - Optional. The specific object name. If null, it's auto-detected. **Note: For `WORLD_BOOK` type, `objName` cannot be automatically detected and must be provided explicitly.**
 * @returns {Promise<boolean>} A Promise that resolves to true if successful, false otherwise.
 */
async function saveCurrentChatLog(chatHistory) {
    try {
        // objName is omitted here, it will be resolved to the current chat's ID automatically.
        const success = await window.AmilyDatabin.saveData(
            window.AmilyDatabin.SourceType.CHAT_LOG,
            `log_${new Date().getTime()}.json`, // Example of a unique key
            { history: chatHistory, savedAt: new Date().toISOString() }
        );

        if (success) {
            console.log("Chat log for current chat saved successfully.");
        } else {
            console.error("Failed to save chat log.");
        }
        return success;
    } catch (error) {
        console.error("Error during data saving:", error);
        return false;
    }
}

// Example call:
const currentChat = ["User: Hi!", "Character: Hello!"];
saveCurrentChatLog(currentChat);
```

### `AmilyDatabin.deleteData(source, fileName, objName = null)`

Deletes a specific data file from the server. The `objName` is optional.

```javascript
/**
 * Deletes a specific data file from the server.
 * @param {number} source - The data source identifier (use AmilyDatabin.SourceType).
 * @param {string} [objName=null] - Optional. The specific object name. If null, it's auto-detected. **Note: For `WORLD_BOOK` type, `objName` cannot be automatically detected and must be provided explicitly.**
 * @returns {Promise<boolean>} A Promise that resolves to true if successful, false otherwise.
 */
async function deleteCurrentCharacterMemory() {
    try {
        const success = await window.AmilyDatabin.deleteData(
            window.AmilyDatabin.SourceType.CHARACTER_CARD,
            "character_memory.json"
        );
        
        if (success) {
            console.log("Successfully deleted current character memory.");
        } else {
            console.log("Failed to delete character memory.");
        }
        return success;
    } catch (error) {
        console.error("Failed to delete data:", error);
        return false;
    }
}

// Example call:
deleteCurrentCharacterMemory();
```

## Debug Methods

These methods are designed for quick debugging in the browser console. They do not interact with the backend API.

### `AmilyDatabin.getDebugInstance()`

Outputs the `AmilyDatabin` object itself to the console. Useful for inspecting its current state, `SourceType` map, and available methods.

```javascript
// Call in browser console:
AmilyDatabin.getDebugInstance();
// Expected output: { SourceType: { CHAT_LOG: 1, ... }, initialize: f, ... }
```

### `AmilyDatabin.getDebugChatId()`

Attempts to resolve the current chat ID using the same logic as the main API methods and logs it to the console.

```javascript
// Call in browser console:
AmilyDatabin.getDebugChatId();
// Expected output: [Amily-Databin] Current Chat ID (Debug): "your_chat_id_here"
```

### `AmilyDatabin.getDebugCardId()`

Attempts to resolve the current character card ID using the same logic as the main API methods and logs it to the console.

```javascript
// Call in browser console:
AmilyDatabin.getDebugCardId();
// Expected output: [Amily-Databin] Current Character Card ID (Debug): "your_character_id_here"
```

## Developer

The main logic is located in `index.js` (server-side) and `public/client.js` (client-side). The plugin registers itself with SillyTavern's extension API.

You can interact with this plugin via the global `window.AmilyDatabin` object directly.