Skip to content

API Reference

Complete API documentation for Verdikta Common library.

Overview

The Verdikta Common library provides a comprehensive set of utilities for working with Verdikta manifests, IPFS content, and arbitration case processing. The API is designed to be simple for basic use cases while providing advanced functionality for complex scenarios.

Main Exports

Factory Function

createClient(config?)

Creates a fully configured Verdikta client with all services initialized.

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

const client = createClient({
  ipfs: {
    pinningKey: 'your-api-key',
    timeout: 30000
  },
  logging: {
    level: 'info'
  }
});

Parameters: - config (Object, optional): Configuration object - ipfs (Object): IPFS client configuration - logging (Object): Logging configuration
- temp (Object): Temporary directory configuration

Returns: Object with initialized services: - manifestParser: ManifestParser instance - archiveService: ArchiveService instance - ipfsClient: IPFSClient instance - validator: Validator utilities - logger: Logger instance - config: Merged configuration

Convenience Functions

parseManifest(extractedPath)

Simple function to parse a manifest from an extracted archive directory.

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

const result = await parseManifest('./path/to/archive');

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

Returns: Promise

validateRequest(request)

Validate a request object against the schema.

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

await validateRequest({
  query: "Should party A receive compensation?",
  outcomes: ["Yes", "No"]
});

Parameters: - request (Object): Request object to validate

Returns: Promise (throws ValidationError if invalid)

Core Classes

ManifestParser

Handles parsing and processing of Verdikta manifest files.

→ See ManifestParser documentation

IPFSClient

Provides IPFS connectivity with retry logic and multiple gateway support.

→ See IPFSClient documentation

ArchiveService

Manages archive operations including fetching and extraction.

→ See ArchiveService documentation

Logger

Configurable logging system built on Winston.

→ See Logger documentation

Utilities

Validator

Joi-based validation utilities for manifests and requests.

→ See Validator documentation

Configuration

Default configuration options and environment variable support.

→ See Configuration documentation

Error Classes

Custom error classes for different types of failures.

→ See Error Classes documentation

Type Definitions

ManifestResult

interface ManifestResult {
  prompt: string;
  models: AIModel[];
  iterations: number;
  outcomes: string[];
  name?: string;
  addendum?: string;
  bCIDs?: Record<string, string>;
  references: string[];
  additional: AdditionalFile[];
  support: SupportFile[];
}

AIModel

interface AIModel {
  AI_MODEL: string;
  AI_PROVIDER: string;
  NO_COUNTS: number;
  WEIGHT: number;
}

AdditionalFile

interface AdditionalFile {
  name: string;
  type: string;
  filename?: string;
  hash?: string;
  description?: string;
}

Configuration Types

interface VerdiktaConfig {
  ipfs: {
    gateway: string;
    pinningService: string;
    pinningKey: string;
    timeout: number;
    retryOptions: RetryOptions;
  };
  logging: {
    level: string;
    console: boolean;
    file: boolean;
    filename?: string;
  };
  temp: {
    dir: string;
  };
}

Error Handling

All methods may throw the following error types:

  • ValidationError: Schema validation failures
  • IPFSError: IPFS operation failures
  • ArchiveError: Archive processing failures
  • ConfigurationError: Invalid configuration
  • NetworkError: Network connectivity issues
const { 
  ValidationError,
  IPFSError, 
  ArchiveError 
} = require('@verdikta/common');

try {
  await parseManifest(path);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.details);
  } else if (error instanceof IPFSError) {
    console.error('IPFS error:', error.message);
  }
}

Quick Reference

Most Common Methods

// Parse a manifest
const result = await parseManifest('./archive');

// Create configured client
const client = createClient(config);

// Fetch from IPFS
const content = await client.ipfsClient.fetchFromIPFS('QmCID');

// Process multiple manifests
const result = await client.manifestParser.parseMultipleManifests(
  paths, 
  cidOrder
);

// Validate manifest
await client.validator.validateManifest(manifest);

Configuration Quick Start

const client = createClient({
  ipfs: {
    pinningKey: process.env.PINATA_API_KEY,
    timeout: 45000
  },
  logging: {
    level: 'debug',
    file: true
  }
});

For detailed information about specific classes and methods, see: