@hpkv/rest-client/dist/src/client.d.ts

A NodeJS REST client for high-performance key-value store (HPKV)

import { RecordResponse, RangeResponse, QueryOptions, QueryResponse, SearchOptions, SearchResponse } from "./types";
/**
 * Client for interacting with the HPKV REST API
 *
 * This client provides methods for all HPKV REST API endpoints including:
 * - Record operations (get, set, delete)
 * - Atomic operations (increment/decrement)
 * - Range queries
 * - Nexus Search and Query capabilities
 */
export declare class HPKVRestClient {
    private baseUrl;
    private nexusBaseUrl;
    private apiKey;
    private headers;
    /**
     * Creates a new HPKV client
     * @param baseUrl - The base URL for the HPKV REST API
     * @param nexusBaseUrl - The base URL for the HPKV Nexus API
     * @param apiKey - Your HPKV API key
     * @throws {Error} When required parameters are missing
     */
    constructor(baseUrl: string, nexusBaseUrl: string, apiKey: string);
    /**
     * Make an HTTP request to the API
     * @private
     * @param method - HTTP method (GET, POST, DELETE)
     * @param path - API endpoint path
     * @param options - Request options (body, etc.)
     * @returns API response data
     * @throws {ApiError} When the API returns an error
     */
    private _request;
    /**
     * Get error code based on HTTP status
     * @private
     * @param status - HTTP status code
     * @returns Error code
     */
    private _getErrorCode;
    /**
     * Insert or update a record
     *
     * This method supports three operations:
     * 1. Insert a new record if the key doesn't exist
     * 2. Update an existing record by completely replacing its value
     * 3. Perform a partial update (append or JSON patch) when partialUpdate is true
     *
     * @param key - The key to store the value under
     * @param value - The value to store (string or object that will be stringified)
     * @param partialUpdate - If true, append to existing value or apply JSON patch if both values are valid JSON
     * @returns Response with success status and message
     * @throws {ApiError} When the API returns an error (400 Bad Request, 401 Unauthorized, etc.)
     *
     * @example
     * // Insert a new record
     * client.set("user:123", { name: "John", age: 30 });
     *
     * @example
     * // Update with JSON patch (when partialUpdate=true and both values are JSON)
     * client.set("user:123", { age: 31, city: "New York" }, true);
     */
    set(key: string, value: unknown, partialUpdate?: boolean): Promise<RecordResponse>;
    /**
     * Get a record by key
     *
     * Retrieves the value stored at the specified key.
     *
     * @param key - The key to retrieve
     * @returns Response containing the key and value
     * @throws {ApiError} When the API returns an error (404 Not Found if key doesn't exist)
     */
    get(key: string): Promise<RecordResponse>;
    /**
     * Delete a record
     *
     * Removes the record stored at the specified key.
     *
     * @param key - The key to delete
     * @returns Response with success status and message
     * @throws {ApiError} When the API returns an error (404 Not Found if key doesn't exist)
     */
    delete(key: string): Promise<RecordResponse>;
    /**
     * Increment or decrement a numeric value
     *
     * Atomically increments or decrements the numeric value stored at the specified key.
     * This operation is useful for counters, rate limiters, and other scenarios where
     * you need to ensure consistency without race conditions.
     *
     * @param key - The key containing the numeric value to increment/decrement
     * @param increment - Value to add (positive) or subtract (negative)
     * @returns Response with the new value after increment/decrement
     * @throws {ApiError} When the API returns an error (404 Not Found if key doesn't exist)
     *
     * @example
     * // Increment a counter
     * const response = await client.atomicIncrement("counter:123", 1);
     * console.log(response.result); // The new counter value
     *
     * @example
     * // Decrement a counter
     * const response = await client.atomicIncrement("counter:123", -1);
     * console.log(response.result); // The new counter value
     */
    atomicIncrement(key: string, increment: number): Promise<RecordResponse>;
    /**
     * Query records within a key range
     *
     * Retrieves multiple records with keys that fall within the specified range.
     * This is useful for retrieving related data with similar keys, such as all users
     * with IDs in a certain range.
     *
     * @param startKey - Starting key for the range (inclusive)
     * @param endKey - Ending key for the range (inclusive)
     * @param limit - Maximum number of records to return (default: 100, max: 1000)
     * @returns Response containing matching records, count, and truncation status
     * @throws {ApiError} When the API returns an error
     */
    range(startKey: string, endKey: string, limit?: number): Promise<RangeResponse>;
    /**
     * Perform semantic search using Nexus Search
     *
     * Searches for records that match the semantic meaning of the query.
     *
     * @param query - The search query
     * @param options - Search options (topK, minScore)
     * @returns Search results
     * @throws {ApiError} When the API returns an error
     * @throws {Error} When query is empty
     */
    nexusSearch(query: string, options?: SearchOptions): Promise<SearchResponse>;
    /**
     * Get AI-generated answers using Nexus Query
     *
     * Retrieves AI-generated answers based on the provided query.
     *
     * @param query - The query for which to generate answers
     * @param options - Query options (topK, minScore)
     * @returns Query results with AI-generated answers
     * @throws {ApiError} When the API returns an error
     * @throws {Error} When query is empty
     */
    nexusQuery(query: string, options?: QueryOptions): Promise<QueryResponse>;
    /**
     * Handle API errors
     *
     * @private
     * @param error - The API error to handle
     * @throws {ApiError} Enhanced error with additional context
     */
    private _handleError;
    /**
     * Get human-readable error message based on status code
     *
     * @private
     * @param status - HTTP status code
     * @param data - Error data from the API
     * @returns Human-readable error message
     */
    private _getErrorMessage;
}