Classes¶

Detailed documentation for all classes in the Verdikta Common library.

ManifestParser¶

The ManifestParser class handles parsing and processing of Verdikta manifest files, including multi-CID scenarios and complex content combination.

Constructor¶

const { ManifestParser } = require('@verdikta/common');

const parser = new ManifestParser(ipfsClient, logger);

Parameters: - ipfsClient (IPFSClient): Configured IPFS client instance - logger (Logger): Logger instance for debugging

Methods¶

parse(extractedPath)¶

Parse a single manifest from an extracted archive directory.

const result = await parser.parse('./extracted-archive');

Parameters: - extractedPath (string): Path to extracted archive directory

Returns: Promise

Throws: ValidationError, ArchiveError

parseMultipleManifests(extractedPaths, cidOrder)¶

Parse multiple manifests and combine them into a single query.

const result = await parser.parseMultipleManifests(
  ['./archive1', './archive2'], 
  ['primary', 'rebuttal']
);

Parameters: - extractedPaths (string[]): Array of paths to extracted archives - cidOrder (string[]): Array of CID identifiers in processing order

Returns: Promise

Throws: ValidationError, ArchiveError

constructCombinedQuery(primaryManifest, bCIDManifests, addendumString?)¶

Construct a combined query from multiple manifests with optional addendum.

const query = await parser.constructCombinedQuery(
  primaryManifest,
  bCIDManifests,
  'Current market data: ETH = $2000'
);

Parameters: - primaryManifest (Object): The primary manifest object - bCIDManifests (Object[]): Array of additional manifest objects - addendumString (string, optional): Real-time data to append

Returns: Promise - Combined query string

IPFSClient¶

The IPFSClient class provides robust IPFS connectivity with retry logic, multiple gateways, and error handling.

Constructor¶

const { IPFSClient } = require('@verdikta/common');

const ipfsClient = new IPFSClient(config, logger);

Parameters: - config (Object): IPFS configuration object - logger (Logger): Logger instance

Methods¶

fetchFromIPFS(cid)¶

Fetch content from IPFS with automatic retry and gateway fallback.

const content = await ipfsClient.fetchFromIPFS('QmYourCIDHere');

Parameters: - cid (string): IPFS Content Identifier

Returns: Promise - Raw content data

Throws: IPFSError, NetworkError

uploadToIPFS(data, filename?)¶

Upload content to IPFS pinning service.

const result = await ipfsClient.uploadToIPFS(
  Buffer.from('content'),
  'filename.txt'
);

Parameters: - data (Buffer|string): Content to upload - filename (string, optional): Filename for the upload

Returns: Promise

interface UploadResult {
  IpfsHash: string;
  PinSize: number;
  Timestamp: string;
}

Throws: IPFSError, NetworkError

validateCID(cid)¶

Validate a Content Identifier format.

const isValid = ipfsClient.validateCID('QmYourCIDHere');

Parameters: - cid (string): CID to validate

Returns: boolean

ArchiveService¶

The ArchiveService class handles archive operations including fetching from IPFS and extraction to the filesystem.

Constructor¶

const { ArchiveService } = require('@verdikta/common');

const archiveService = new ArchiveService(ipfsClient, logger, config);

Parameters: - ipfsClient (IPFSClient): IPFS client instance - logger (Logger): Logger instance - config (Object): Configuration object

Methods¶

getArchive(cid)¶

Fetch an archive from IPFS or test fixtures.

const archiveData = await archiveService.getArchive('QmArchiveCID');

Parameters: - cid (string): Content Identifier for the archive

Returns: Promise - Archive data

Throws: IPFSError, ArchiveError

extractArchive(archiveData, extractionPath)¶

Extract an archive to the filesystem.

const extractPath = await archiveService.extractArchive(
  archiveData, 
  './extraction-directory'
);

Parameters: - archiveData (Buffer): Raw archive data - extractionPath (string): Directory to extract to

Returns: Promise - Path to extracted content

Throws: ArchiveError

detectArchiveFormat(archiveData)¶

Detect the format of an archive from its data.

const format = archiveService.detectArchiveFormat(archiveData);
// Returns: 'zip', 'tar', 'tar.gz', etc.

Parameters: - archiveData (Buffer): Raw archive data

Returns: string - Archive format

Logger¶

Configurable logging system built on Winston with support for console and file output.

Constructor¶

const { Logger } = require('@verdikta/common');

const logger = new Logger(config);

Parameters: - config (Object): Logging configuration - level (string): Log level ('debug', 'info', 'warn', 'error') - console (boolean): Enable console output - file (boolean): Enable file output - filename (string, optional): Log file path

Methods¶

info(message, meta?)¶

Log an info-level message.

logger.info('Processing started', { archiveId: 'abc123' });

Parameters: - message (string): Log message - meta (Object, optional): Additional metadata

debug(message, meta?)¶

Log a debug-level message.

logger.debug('Parsing manifest', { path: './archive' });

Parameters: - message (string): Log message - meta (Object, optional): Additional metadata

warn(message, meta?)¶

Log a warning-level message.

logger.warn('Fallback gateway used', { gateway: 'backup.ipfs.io' });

Parameters: - message (string): Log message - meta (Object, optional): Additional metadata

error(message, meta?)¶

Log an error-level message.

logger.error('IPFS fetch failed', { cid: 'QmCID', error: errorObj });

Parameters: - message (string): Log message - meta (Object, optional): Additional metadata

setLevel(level)¶

Change the logging level dynamically.

logger.setLevel('debug');

Parameters: - level (string): New log level

Usage Patterns¶

Basic Instantiation¶

const { createClient } = require('@verdikta/common');

// Get all classes via factory
const { manifestParser, ipfsClient, archiveService, logger } = createClient();

// Or instantiate individually
const { IPFSClient, Logger, ManifestParser } = require('@verdikta/common');

const logger = new Logger({ level: 'info' });
const ipfsClient = new IPFSClient(ipfsConfig, logger);
const manifestParser = new ManifestParser(ipfsClient, logger);

Error Handling¶

All classes follow consistent error handling patterns:

try {
  const result = await manifestParser.parse('./archive');
} catch (error) {
  if (error instanceof ValidationError) {
    logger.error('Validation failed', { details: error.details });
  } else if (error instanceof ArchiveError) {
    logger.error('Archive processing failed', { error: error.message });
  } else {
    logger.error('Unexpected error', { error: error.message });
    throw error;
  }
}

Configuration¶

Each class accepts configuration in its constructor:

// IPFS Client configuration
const ipfsClient = new IPFSClient({
  gateway: 'https://ipfs.io',
  timeout: 30000,
  retryOptions: {
    retries: 5,
    factor: 2
  }
}, logger);

// Logger configuration
const logger = new Logger({
  level: 'debug',
  console: true,
  file: true,
  filename: './verdikta.log'
});