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, options?)¶

Parse a single manifest from an extracted archive directory.

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

Parameters: - extractedPath (string): Path to extracted archive directory - options (object, optional): { archiveRole?: 'primary' | 'bCID', cid?: string } attached to MalformedArchiveError

Returns: Promise

Throws: MalformedArchiveError for content-level rejections; untyped Error for IPFS fetch and I/O failures.

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: MalformedArchiveError for content-level rejections (archiveRole: 'bCID' when the failing archive is not the first CID); untyped Error for IPFS fetch and I/O failures.

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 fetches and uploads IPFS content. fetchFromIPFS tries gateways in sweeps (every gateway, back to back) and applies backoff only between sweeps. Pass gateways for operator-preferred hosts; the legacy gateway string is appended after that list. Built-in defaults always follow. gatewayToken is sent only to operator-configured gateways. retryOptions.retries is the number of additional sweeps. maxFetchMs is the wall-clock budget for one fetch.

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(filePath)¶

Upload a file to the IPFS pinning service. Retries use uploadRetryOptions, which is independent of fetch sweeps.

const cid = await ipfsClient.uploadToIPFS('/path/to/file.zip');

Parameters: - filePath (string): Path of the file to upload

Returns: Promise - Pinned CID

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: 'https://backup.example' });

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({
  gateways: ['https://<subdomain>.mypinata.cloud'],
  gatewayToken: process.env.IPFS_GATEWAY_TOKEN,
  timeout: 30000,
  maxFetchMs: 120000,
  retryOptions: {
    retries: 2,
    factor: 2
  }
}, logger);

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