recallrai/dist/user.d.ts

Official Node.js SDK for RecallrAI - Revolutionary contextual memory system that enables AI assistants to form meaningful connections between conversations, just like human memory.

/**
 * User management functionality for the RecallrAI SDK.
 */
import { HTTPClient } from "./utils";
import { UserModel, SessionStatus, UserMemoriesList, UserMessagesList, UserMemoryItem, MergeConflictStatus } from "./models";
import type { Unavailable } from "./models";
import { Session } from "./session";
import { MergeConflict } from "./merge-conflict";
/**
 * Represents a user in the RecallrAI system with methods for user management.
 *
 * This class wraps a user object and provides methods for updating user data,
 * and for creating and managing sessions.
 */
export declare class User {
    private http;
    private userData;
    userId: string;
    metadata: Record<string, any> | Unavailable;
    mergeConflictEnabled: boolean | undefined | Unavailable;
    createdAt: Date | Unavailable;
    lastActiveAt: Date | Unavailable;
    /**
     * Initialize a user.
     *
     * @param httpClient - HTTP client for API communication.
     * @param userData - User data model with user information.
     */
    constructor(httpClient: HTTPClient, userData: UserModel);
    /**
     * Update this user's metadata or ID.
     *
     * @param newMetadata - New metadata to associate with the user.
     * @param newUserId - New ID for the user.
     * @param mergeConflictEnabled - Per-user merge conflict override.
     *   `true` = always raise merge conflicts for this user.
     *   `false` = never raise merge conflicts for this user.
     *   `undefined` = do not change the current setting.
     * @throws {UserNotFoundError} If the user is not found.
     * @throws {UserAlreadyExistsError} If a user with the new_user_id already exists.
     * @throws {AuthenticationError} If the API key or project ID is invalid.
     * @throws {InternalServerError} If the server encounters an error.
     * @throws {NetworkError} If there are network issues.
     * @throws {TimeoutError} If the request times out.
     * @throws {RecallrAIError} For other API-related errors.
     */
    update({ newMetadata, newUserId, mergeConflictEnabled, }?: {
        newMetadata?: Record<string, any>;
        newUserId?: string;
        mergeConflictEnabled?: boolean;
    }): Promise<void>;
    /**
     * Refresh this user's data from the server.
     *
     * @throws {UserNotFoundError} If the user is not found.
     * @throws {AuthenticationError} If the API key or project ID is invalid.
     * @throws {InternalServerError} If the server encounters an error.
     * @throws {NetworkError} If there are network issues.
     * @throws {TimeoutError} If the request times out.
     * @throws {RecallrAIError} For other API-related errors.
     */
    refresh(): Promise<void>;
    /**
     * Delete this user.
     *
     * @throws {UserNotFoundError} If the user is not found.
     * @throws {AuthenticationError} If the API key or project ID is invalid.
     * @throws {InternalServerError} If the server encounters an error.
     * @throws {NetworkError} If there are network issues.
     * @throws {TimeoutError} If the request times out.
     * @throws {RecallrAIError} For other API-related errors.
     */
    delete(): Promise<void>;
    /**
     * Create a new session for this user.
     *
     * @param autoProcessAfterSeconds - Seconds of inactivity allowed before automatically processing the session (min 600). Defaults to 600.
     * @param metadata - Optional metadata for the session.
     * @param customCreatedAtUtc - Optional custom timestamp for when the session was created (must be UTC). Useful for importing historical data.
     * @returns A Session object to interact with the created session.
     * @throws {UserNotFoundError} If the user is not found.
     * @throws {AuthenticationError} If the API key or project ID is invalid.
     * @throws {InternalServerError} If the server encounters an error.
     * @throws {NetworkError} If there are network issues.
     * @throws {TimeoutError} If the request times out.
     * @throws {RecallrAIError} For other API-related errors.
     */
    createSession({ autoProcessAfterSeconds, metadata, customCreatedAtUtc, }?: {
        autoProcessAfterSeconds?: number;
        metadata?: Record<string, any>;
        customCreatedAtUtc?: Date;
    }): Promise<Session>;
    /**
     * Get an existing session for this user.
     *
     * @param sessionId - ID of the session to retrieve.
     * @param options - Optional behavior flags.
     * @param options.validate - Whether to validate session existence via API before creating the instance.
     *   Defaults to true. Set to false when sessionId is trusted.
     * @returns A Session object to interact with the session.
     * @throws {UserNotFoundError} If the user is not found.
     * @throws {SessionNotFoundError} If the session is not found.
     * @throws {AuthenticationError} If the API key or project ID is invalid.
     * @throws {InternalServerError} If the server encounters an error.
     * @throws {NetworkError} If there are network issues.
     * @throws {TimeoutError} If the request times out.
     * @throws {RecallrAIError} For other API-related errors.
     */
    getSession(sessionId: string, { validate }?: {
        validate?: boolean;
    }): Promise<Session>;
    /**
     * List sessions for this user with pagination.
     *
     * @param offset - Number of records to skip. Defaults to 0.
     * @param limit - Maximum number of records to return. Defaults to 10.
     * @param metadataFilter - Optional metadata filter for sessions.
     * @param statusFilter - Optional list of session statuses to filter by (e.g., ["pending", "processing", "processed", "insufficient_balance"]).
     * @returns List of sessions with pagination info.
     * @throws {UserNotFoundError} If the user is not found.
     * @throws {AuthenticationError} If the API key or project ID is invalid.
     * @throws {InternalServerError} If the server encounters an error.
     * @throws {NetworkError} If there are network issues.
     * @throws {TimeoutError} If the request times out.
     * @throws {RecallrAIError} For other API-related errors.
     */
    listSessions({ offset, limit, metadataFilter, statusFilter, }?: {
        offset?: number;
        limit?: number;
        metadataFilter?: Record<string, any>;
        statusFilter?: SessionStatus[];
    }): Promise<{
        sessions: Session[];
        total: number;
        hasMore: boolean;
    }>;
    /**
     * List memories for this user with optional category and session filters.
     *
     * @param offset - Number of records to skip. Defaults to 0.
     * @param limit - Maximum number of records to return (1-200). Defaults to 20.
     * @param categories - Optional list of category names to filter by.
     * @param sessionIdFilter - Optional list of session IDs to filter by.
     * @param sessionMetadataFilter - Optional object to filter by session metadata (exact match on keys -> values).
     * @param includePreviousVersions - Include full version history for each memory. Defaults to true.
     * @param includeConnectedMemories - Include connected memories. Defaults to true.
     * @returns UserMemoriesList: Paginated list of memory items.
     * @throws {UserNotFoundError} If the user is not found.
     * @throws {AuthenticationError} If the API key or project ID is invalid.
     * @throws {InternalServerError} If the server encounters an error.
     * @throws {NetworkError} If there are network issues.
     * @throws {TimeoutError} If the request times out.
     * @throws {RecallrAIError} For other API-related errors.
     */
    listMemories({ offset, limit, categories, sessionIdFilter, sessionMetadataFilter, includePreviousVersions, includeConnectedMemories, }?: {
        offset?: number;
        limit?: number;
        categories?: string[];
        sessionIdFilter?: string[];
        sessionMetadataFilter?: Record<string, any>;
        includePreviousVersions?: boolean;
        includeConnectedMemories?: boolean;
    }): Promise<UserMemoriesList>;
    /**
     * Retrieve a specific memory by ID.
     *
     * @param memoryId - UUID of the memory to retrieve.
     * @param includePreviousVersions - Include full version history. Defaults to true.
     * @param includeConnectedMemories - Include connected memories. Defaults to true.
     * @returns UserMemoryItem: Complete memory object.
     * @throws {RecallrAIError} If the memory is not found or another error occurs.
     * @throws {AuthenticationError} If the API key or project ID is invalid.
     * @throws {InternalServerError} If the server encounters an error.
     * @throws {NetworkError} If there are network issues.
     * @throws {TimeoutError} If the request times out.
     */
    getMemory(memoryId: string, { includePreviousVersions, includeConnectedMemories, }?: {
        includePreviousVersions?: boolean;
        includeConnectedMemories?: boolean;
    }): Promise<UserMemoryItem>;
    /**
     * Delete a memory (or its version history) for this user.
     *
     * @param memoryId - UUID of the memory to delete (can be any version in the chain).
     * @param deletePreviousVersions - If true, deletes the specified version and all
     *   previous versions in the chain. If false (default), deletes only the specified version.
     * @throws {RecallrAIError} If the memory is not found or another error occurs.
     * @throws {AuthenticationError} If the API key or project ID is invalid.
     * @throws {InternalServerError} If the server encounters an error.
     * @throws {NetworkError} If there are network issues.
     * @throws {TimeoutError} If the request times out.
     */
    deleteMemory(memoryId: string, deletePreviousVersions?: boolean): Promise<void>;
    /**
     * List merge conflicts for this user.
     *
     * @param offset - Number of records to skip. Defaults to 0.
     * @param limit - Maximum number of records to return. Defaults to 10.
     * @param status - Optional filter by conflict status.
     * @param sortBy - Field to sort by (created_at, resolved_at). Defaults to "created_at".
     * @param sortOrder - Sort order (asc, desc). Defaults to "desc".
     * @returns MergeConflictList: Paginated list of merge conflicts.
     * @throws {UserNotFoundError} If the user is not found.
     * @throws {AuthenticationError} If the API key or project ID is invalid.
     * @throws {InternalServerError} If the server encounters an error.
     * @throws {NetworkError} If there are network issues.
     * @throws {TimeoutError} If the request times out.
     * @throws {RecallrAIError} For other API-related errors.
     */
    listMergeConflicts({ offset, limit, status, sortBy, sortOrder, }?: {
        offset?: number;
        limit?: number;
        status?: MergeConflictStatus;
        sortBy?: string;
        sortOrder?: string;
    }): Promise<{
        conflicts: MergeConflict[];
        total: number;
        hasMore: boolean;
    }>;
    /**
     * Get a specific merge conflict by ID.
     *
     * @param conflictId - Unique identifier of the merge conflict.
     * @returns MergeConflict: The merge conflict object.
     * @throws {UserNotFoundError} If the user is not found.
     * @throws {MergeConflictNotFoundError} If the merge conflict is not found.
     * @throws {AuthenticationError} If the API key or project ID is invalid.
     * @throws {InternalServerError} If the server encounters an error.
     * @throws {NetworkError} If there are network issues.
     * @throws {TimeoutError} If the request times out.
     * @throws {RecallrAIError} For other API-related errors.
     */
    getMergeConflict(conflictId: string): Promise<MergeConflict>;
    /**
     * Get the last N messages for this user across all their sessions.
     *
     * This method is useful for chatbot applications where you want to see
     * the recent conversation history for context.
     *
     * @param n - Number of recent messages to retrieve (1-100, default: 10).
     * @returns UserMessagesList: List of the most recent messages.
     * @throws {UserNotFoundError} If the user is not found.
     * @throws {AuthenticationError} If the API key or project ID is invalid.
     * @throws {InternalServerError} If the server encounters an error.
     * @throws {NetworkError} If there are network issues.
     * @throws {TimeoutError} If the request times out.
     * @throws {RecallrAIError} For other API-related errors.
     * @throws {Error} If n is not between 1 and 100.
     */
    getLastNMessages(n: number): Promise<UserMessagesList>;
    private parseUserResponse;
    private parseSessionResponse;
    private parseMemoryItem;
    private parseMergeConflictResponse;
    toString(): string;
}