trasorio-sdk/index.d.ts

Official Node.js SDK for Trasor.io trust infrastructure platform

/**
 * TypeScript definitions for Trasor.io Node.js SDK
 * @version 2.0.0
 */

export interface TrasorClientOptions {
  /** Base URL for the API (default: https://api.trasor.io) */
  baseUrl?: string;
  /** Request timeout in milliseconds (default: 30000) */
  timeout?: number;
  /** Enable debug logging (default: false) */
  debug?: boolean;
}

export interface LogEventParams {
  /** Name/identifier of the AI agent or service */
  agentName: string;
  /** The action that was performed */
  action: string;
  /** Input data/parameters for the action */
  inputs?: Record<string, any>;
  /** Output data/results from the action */
  outputs?: Record<string, any>;
  /** Additional metadata about the event */
  metadata?: Record<string, any>;
  /** Workflow or session identifier */
  workflowId?: string;
  /** Status of the action (e.g., "success", "error", "pending") */
  status?: string;
}

export interface LogEventResponse {
  /** Unique identifier for the audit log entry */
  id: string;
  /** SHA-256 hash of the log entry */
  hash: string;
  /** Previous log entry hash for chain verification */
  previousHash: string | null;
  /** Timestamp when the log was created */
  timestamp: string;
  /** Agent identifier */
  agentId: string;
  /** Action performed */
  action: string;
  /** Input data */
  inputs?: Record<string, any>;
  /** Output data */
  outputs?: Record<string, any>;
  /** Additional metadata */
  metadata?: Record<string, any>;
  /** Workflow identifier */
  workflowId?: string;
  /** Status of the action */
  status?: string;
  /** Whether the log entry is verified */
  verified: boolean;
}

export interface GetLogsOptions {
  /** Number of logs to return (max 100, default: 50) */
  limit?: number;
  /** Number of logs to skip (default: 0) */
  offset?: number;
  /** Filter by workflow ID */
  workflowId?: string;
}

export interface GetLogsResponse {
  /** Array of audit log entries */
  logs: LogEventResponse[];
  /** Pagination metadata */
  pagination: {
    /** Total number of logs available */
    total: number;
    /** Current limit */
    limit: number;
    /** Current offset */
    offset: number;
    /** Whether there are more logs available */
    hasNext: boolean;
    /** Whether there are previous logs */
    hasPrev: boolean;
  };
}

export interface VerifyChainResponse {
  /** Whether the chain integrity is valid */
  isValid: boolean;
  /** Hash of the last verified log entry */
  lastVerifiedHash?: string;
  /** Error message if validation failed */
  errorMessage?: string;
}

export interface GetStatsResponse {
  /** Total number of logs in the account */
  totalLogs: number;
  /** Chain integrity percentage (0-100) */
  chainIntegrity: number;
  /** Hash of the most recent log entry */
  latestHash: string;
  /** Hash of the first log entry */
  genesisHash: string;
}

/**
 * Base error class for all Trasor.io SDK errors
 */
export class TrasorError extends Error {
  /** HTTP status code if applicable */
  statusCode?: number;
  
  constructor(message: string, statusCode?: number);
}

/**
 * Authentication error (401)
 */
export class AuthenticationError extends TrasorError {
  constructor(message?: string);
}

/**
 * Validation error (400)
 */
export class ValidationError extends TrasorError {
  constructor(message?: string);
}

/**
 * API error (4xx/5xx)
 */
export class APIError extends TrasorError {
  constructor(message?: string, statusCode?: number);
}

/**
 * Trasor.io Client for Node.js
 * 
 * A simple, developer-friendly client for recording audit logs with Trasor.io's
 * trust infrastructure platform.
 */
export class TrasorClient {
  /** API key used for authentication */
  readonly apiKey: string;
  /** Base URL for API requests */
  readonly baseUrl: string;
  /** Request timeout in milliseconds */
  readonly timeout: number;
  /** Whether debug logging is enabled */
  readonly debug: boolean;

  /**
   * Create a new Trasor.io client instance
   * 
   * @param apiKey - Your Trasor.io API key (format: trasor_live_*)
   * @param options - Configuration options
   * @throws {ValidationError} If API key is missing or invalid format
   */
  constructor(apiKey: string, options?: TrasorClientOptions);

  /**
   * Create a new audit log entry
   * 
   * @param params - Log event parameters
   * @returns Promise resolving to the created audit log entry
   * @throws {ValidationError} If required parameters are missing or invalid
   * @throws {AuthenticationError} If API key is invalid or unauthorized
   * @throws {APIError} If the API returns an error response
   */
  logEvent(params: LogEventParams): Promise<LogEventResponse>;

  /**
   * Retrieve audit logs with pagination
   * 
   * @param options - Query options
   * @returns Promise resolving to paginated list of audit logs
   * @throws {ValidationError} If parameters are invalid
   * @throws {AuthenticationError} If API key is invalid or unauthorized
   * @throws {APIError} If the API returns an error response
   */
  getLogs(options?: GetLogsOptions): Promise<GetLogsResponse>;

  /**
   * Verify the integrity of the audit log chain
   * 
   * @returns Promise resolving to verification results
   * @throws {AuthenticationError} If API key is invalid or unauthorized
   * @throws {APIError} If the API returns an error response
   */
  verifyChain(): Promise<VerifyChainResponse>;

  /**
   * Get account statistics and metrics
   * 
   * @returns Promise resolving to account statistics
   * @throws {AuthenticationError} If API key is invalid or unauthorized
   * @throws {APIError} If the API returns an error response
   */
  getStats(): Promise<GetStatsResponse>;
}

// Default export for CommonJS compatibility
export default TrasorClient;