Chromia Console Client

A TypeScript/JavaScript client library for interacting with the Chromia Console Vector Database API. This client provides a simple and type-safe way to manage vector collections, perform similarity searches, and work with embeddings.

Installation

npm install @chromia/de-console-client

Or with yarn:

yarn add @chromia/de-console-client

Or with pnpm:

pnpm add @chromia/de-console-client

Quick Start

import { Configuration, ChromiaVectorDBApiFactory, VectorCollection } from '@chromia/de-console-client';

// 1. Configure the client
const configuration = new Configuration({
  basePath: 'https://api.app.deconsole.com',
  brid: 'YOUR_BLOCKCHAIN_RID',
  network: 'mainnet', // or 'testnet' or 'https://node0.testnet.chromia.com'
  chromiaApiKey: 'YOUR_API_KEY' // optional
});

// 2. Create the API client
const client = ChromiaVectorDBApiFactory(configuration);

// 3. Create a collection
const collection: VectorCollection = {
  name: 'my_first_collection',
  dimension: 384, // Vector dimension for embeddings
  index: 'hnsw_cosine',
  query_max_vector: 10,
  store_batch_size: 100
};
await client.addCollection(collection);

// 4. Store some text as vector embeddings (batch operation)
await client.createVectorEmbeddingBatch(
  'my_first_collection',
  [
    'The quick brown fox jumps over the lazy dog',
    'Chromia is a relational blockchain platform',
    'Vector databases enable semantic search'
  ]
);

// 5. Search using text query
const searchResults = await client.searchObjects(
  'my_first_collection',
  'tell me about Chromia',
  undefined, // maxDistance (optional)
  2          // maxVectors - return top 2 results
);

console.log('Search results:', searchResults.data.payloads);

File storage quickstart

import { Configuration, ChromiaFileStorageApiFactory } from '@chromia/de-console-client';

// 1. Configure the client
const configuration = new Configuration({
  basePath: 'https://api.app.deconsole.com',
  brid: 'YOUR_BLOCKCHAIN_RID', // Chromia bucket chain RID
  network: 'mainnet', // or 'testnet' or 'https://node0.testnet.chromia.com'
  chromiaApiKey: 'YOUR_API_KEY' // optional
});

// 2. Create file storage API client
const client = ChromiaFileStorageApiFactory(configuration);

// 3. Upload a file
const uploadResult = await client.uploadFile({
    name: 'file_name.txt',
    data: 'fileDataBase64', // Base64 encoded text
    is_public: true
});
console.log('File hash:', uploadResult.data.file_hash);

// 3a. Upload a file using multipart/form-data (uploadFileMultipart)
const fileForMultipart = new File(['file content'], 'file_name.txt', { type: 'text/plain' });
const multipartUploadResult = await client.uploadFileMultipart(fileForMultipart);
console.log('File uploaded successfully using multipart!');
console.log('File hash:', multipartUploadResult.data.file_hash);

// 4. List uploaded files metadata
const listResult = await client.getUserFiles();
console.log('Total files:', listResult.data.files?.length || 0);
if (listResult.data.files) {
  listResult.data.files.forEach((f) => {
    console.log(`  - ${f.name} (${f.file_hash})`);
    console.log(`    Size: ${f.size} bytes, Type: ${f.content_type}, Public: ${f.is_public || false}`);
  });
}

// 4. Download the file
const downloadResult = await client.downloadFile(uploadedFileHash);
console.log('File downloaded successfully!');
console.log('File name:', downloadResult.data.name);
console.log('File size:', downloadResult.data.size, 'bytes');
console.log('Content type:', downloadResult.data.content_type);
console.log('File hash:', downloadResult.data.file_hash);

// 5. Delete the file
const deleteResult = await client.deleteFile(uploadedFileHash);
console.log('Transaction result:', deleteResult.data);

Configuration

The Configuration object accepts the following parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | basePath | string | Yes | Base URL of the Chromia Console API | | brid | string | Yes | Blockchain RID (Identifier) | | network | string | Yes | Network name (e.g., 'mainnet', 'testnet') or url| | chromiaApiKey | string | No | API key for authentication |

Environment Variables

You can use environment variables to configure the client:

const configuration = new Configuration({
  basePath: process.env.CHROMIA_CONSOLE_BASE_PATH,
  brid: process.env.BRID,
  network: process.env.NETWORK || 'mainnet',
  chromiaApiKey: process.env.API_KEY,
});

API Reference

File storage operations

• getUserFiles() Get user files
• uploadFile(uploadFileRequest) - Upload a file
• uploadFileBatch(uploadFileBatchRequest) - Upload multiple files in batch
• uploadFileBatchMultipart(files) - Upload a files in batch using multipart form data
• uploadFileMultipart(file) - Upload a file using multipart form data
• downloadFile(fileHash) - Download a file
• downloadFileBatch(downloadFileBatchRequest) - Download multiple files in batch
• downloadFileContent(fileHash) - Download raw file content
• deleteFile(fileHash) - Delete a file
• deleteFileBatch(deleteFileBatchRequest) - Delete multiple files in batch

Entity DB operations

• createRecord(entityName, obj) Create a new record in an entity
• deleteRecordById(entityName, id) Delete a record by ID
• getRecordById(entityName, id) Get a specific record by ID
• getRecords(entityName) Get all records from an entity
• getRecordsByIds(entityName, ids) Get a list of records by IDs
• updateRecordById(entityName, id, obj) Update a record by ID

Collection Management

• getCollections() - Get all available collections
• addCollection(collection) - Create a new collection
• changeCollection(changes) - Update collection configuration
• removeCollection(name) - Remove a collection

Vector Operations

• createVector(collection, vectorRequest) - Create a single vector
• createVectorBatch(collection, batchRequest) - Create multiple vectors
• createVectorBatchChunked(collection, batchRequest) - Create vectors in chunks
• deleteVector(collection, payload) - Delete a vector
• deleteVectorBatch(collection, payloads) - Delete multiple vectors

Embedding Operations

• createVectorEmbedding(collection, payload) - Create text embedding
• createVectorEmbeddingBatch(collection, payloads) - Create text embeddings batch
• createVectorEmbeddingBatchChunked(collection, payloads) - Create text embeddings in chunks
• createImageEmbedding(collection, imageRequest) - Create image embedding
• createImageEmbeddingBatch(collection, batchRequest) - Create image embeddings batch

Search Operations

• searchObjects(collection, query, maxDistance?, maxVectors?) - Search by text
• getClosestObjects(collection, vectorRequest, maxDistance?, maxVectors?) - Search by vector
• getClosestObjectsWithDistance(collection, vectorRequest, maxDistance?, maxVectors?) - Search with distances
• getClosestObjectsWithFilter(collection, filterRequest, maxDistance?, maxVectors?) - Search with filter
• searchImages(collection, imageRequest, maxDistance?, maxVectors?) - Search similar images

Import Operations

• getDefaultDataWithEmbedding() - Get default import data
• importDefaultData(collection) - Import default data

Response Types

TransactionResultBody

All write operations return a TransactionResultBody:

{
  txRid: string;      // Transaction ID
  status: string;     // 'confirmed', 'waiting', 'pending', or 'rejected'
  rejectReason?: string; // Only present if status is 'rejected'
}

GetClosestResponse

Search operations return a GetClosestResponse:

{
  payloads: string[]; // Array of matched payloads
}

PayloadDistance

Distance-aware searches return PayloadDistance[]:

{
  text: string;       // Payload text
  distance: number;   // Distance from query vector
}

Error Handling

The client uses Axios for HTTP requests. Handle errors using try-catch:

try {
  const response = await client.createVector(
    'my_collection',
    vectorRequest
  );
  console.log('Success:', response.data);
} catch (error) {
  if (error.response) {
    // The request was made and the server responded with a status code
    // that falls out of the range of 2xx
    console.error('Error status:', error.response.status);
    console.error('Error data:', error.response.data);
  } else if (error.request) {
    // The request was made but no response was received
    console.error('No response received:', error.request);
  } else {
    // Something happened in setting up the request
    console.error('Error:', error.message);
  }
}

Support

For issues and questions:

• Create an issue in the GitLab repository
• Check the Chromia documentation
• Visit the Chromia community