@barfinex/types
Version:
Core TypeScript type definitions and shared interfaces for the Barfinex ecosystem. Provides strongly-typed contracts for modules, services, and plugins.
222 lines • 8.18 kB
TypeScript
/**
* Canonical data quality and decision-readiness contracts shared by Provider, Advisor, and Studio.
* Used for Layer 1 (Provider validation) and Layer 2 (Advisor decision guard) and aggregation APIs.
*/
export declare const DataQualityLevel: {
readonly OK: "OK";
readonly WARNING: "WARNING";
readonly ERROR: "ERROR";
};
export type DataQualityLevel = (typeof DataQualityLevel)[keyof typeof DataQualityLevel];
export declare const DataMaturityLevel: {
readonly INSUFFICIENT: "INSUFFICIENT";
readonly PARTIAL: "PARTIAL";
readonly READY: "READY";
readonly OPTIMAL: "OPTIMAL";
};
export type DataMaturityLevel = (typeof DataMaturityLevel)[keyof typeof DataMaturityLevel];
export declare const DataQualityIssueCategory: {
readonly missing_data: "missing_data";
readonly stale_data: "stale_data";
readonly gap_detected: "gap_detected";
readonly duplicate_data: "duplicate_data";
readonly out_of_order: "out_of_order";
readonly nan_detected: "nan_detected";
readonly invalid_range: "invalid_range";
readonly stream_inactive: "stream_inactive";
readonly indicator_not_ready: "indicator_not_ready";
readonly feature_incomplete: "feature_incomplete";
readonly decision_blocked: "decision_blocked";
};
export type DataQualityIssueCategory = (typeof DataQualityIssueCategory)[keyof typeof DataQualityIssueCategory];
export interface DataQualityIssue {
category: DataQualityIssueCategory | string;
component?: string;
code?: string;
message: string;
severity: 'warning' | 'critical';
field?: string;
value?: unknown;
symbol?: string;
evaluatedAt?: number;
remediationHint?: string;
suggestedAction?: string;
/** When false, issue does not affect symbol level (e.g. low_activity). Default true. */
blocking?: boolean;
}
export interface DataQualityStatus {
level: DataQualityLevel;
maturity: DataMaturityLevel;
issues: DataQualityIssue[];
warnings: string[];
lastDataTimestamp?: number;
evaluatedAt: number;
advisorEligible?: boolean;
}
export interface InstrumentDataQualityStatus extends DataQualityStatus {
symbol: string;
connectorType?: string;
marketType?: string;
candles?: {
status: DataQualityLevel;
message?: string;
count?: number;
};
trades?: {
status: DataQualityLevel;
message?: string;
lastTimestamp?: number;
};
orderbook?: {
status: DataQualityLevel;
message?: string;
lastTimestamp?: number;
};
indicators?: {
status: DataQualityLevel;
message?: string;
ready?: string[];
notReady?: string[];
};
}
export declare const DecisionBlockReason: {
readonly no_sufficient_candle_history: "no_sufficient_candle_history";
readonly required_feature_missing: "required_feature_missing";
readonly nan_or_infinite_required_feature: "nan_or_infinite_required_feature";
readonly nan_feature: "nan_feature";
readonly invalid_feature_range: "invalid_feature_range";
readonly feature_vector_incomplete: "feature_vector_incomplete";
readonly orderbook_required_but_stale_or_missing: "orderbook_required_but_stale_or_missing";
readonly trade_context_required_but_stale_or_missing: "trade_context_required_but_stale_or_missing";
readonly upstream_maturity_below_ready: "upstream_maturity_below_ready";
readonly data_maturity_below_ready: "data_maturity_below_ready";
readonly required_stream_stale: "required_stream_stale";
readonly indicator_not_ready: "indicator_not_ready";
readonly invalid_or_empty_detector_context: "invalid_or_empty_detector_context";
readonly no_context: "no_context";
readonly market_quality_invalid: "market_quality_invalid";
readonly missing_required_data: "missing_required_data";
readonly throttled: "throttled";
readonly readiness_blocked: "readiness_blocked";
readonly calibration_blocked: "calibration_blocked";
readonly strategy_dependency_mismatch: "strategy_dependency_mismatch";
readonly other: "other";
};
export type DecisionBlockReason = (typeof DecisionBlockReason)[keyof typeof DecisionBlockReason];
export interface AdvisorDecisionReadinessStatus {
symbol: string;
ready: boolean;
blocked: boolean;
reasons: DecisionBlockReason[] | string[];
missingFields?: string[];
invalidValues?: string[];
nanFields?: string[];
validationErrors?: string[];
decisionBlockReason?: DecisionBlockReason | string;
featureValidationStatus?: 'valid' | 'invalid' | 'unknown';
missingFeatureCount?: number;
nanFeatureCount?: number;
strategyRequirementFailure?: string;
suggestedAction?: string;
lastBlockedAt?: number;
lastSuccessfulDecisionAt?: number;
dataMaturity?: DataMaturityLevel | string;
lastValidatedAt: number;
strategy?: string;
detector?: string;
}
export interface AdvisorDecisionValidationResult {
valid: boolean;
errors: string[];
missingFields: string[];
invalidValues: string[];
nanFields: string[];
accepted: boolean;
reasons: string[];
featureTimestamp?: number | null;
maxAllowedAgeMs?: number;
observedAgeMs?: number | null;
strategyRequirementFailure?: string;
blockReasons?: DecisionBlockReason[] | string[];
dataQualityStatus?: DataQualityLevel;
dataMaturity?: DataMaturityLevel | string;
evaluatedAt: number;
}
/** Advisor aggregate status: UNKNOWN when proxy unavailable; READY when no symbols or all ready; NOT_READY otherwise. */
export type AdvisorStatusType = 'READY' | 'NOT_READY' | 'UNKNOWN';
export interface ProviderDataQualityOverviewResponse {
systemSummary: {
overallStatus: DataQualityLevel;
/** READY = all symbols ready or none tracked; NOT_READY = at least one not ready; UNKNOWN = advisor proxy unavailable. */
advisorStatus: AdvisorStatusType;
blockedSymbolCount: number;
warningCount: number;
symbolCount: number;
lastRefresh: number;
};
providerStreams?: {
candles: {
status: DataQualityLevel;
message?: string;
};
trades: {
status: DataQualityLevel;
message?: string;
};
orderbook: {
status: DataQualityLevel;
message?: string;
};
};
symbols?: InstrumentDataQualityStatus[];
advisorReadiness?: AdvisorDecisionReadinessStatus[];
recentErrors?: DataQualityIssue[];
recentWarnings?: DataQualityIssue[];
}
export interface ProviderInstrumentDataQualityResponse extends InstrumentDataQualityStatus {
advisorReadiness?: AdvisorDecisionReadinessStatus | null;
issues: DataQualityIssue[];
}
export interface DataQualityDesktopPayload {
systemSummary: ProviderDataQualityOverviewResponse['systemSummary'];
providerStreams?: ProviderDataQualityOverviewResponse['providerStreams'];
symbolLevel: InstrumentDataQualityStatus[];
indicatorReadiness?: Record<string, {
status: DataQualityLevel;
symbolsReady: number;
symbolsTotal: number;
}>;
advisorReadiness: {
ready: number;
blocked: number;
degraded: number;
bySymbol: AdvisorDecisionReadinessStatus[];
lastRefresh: number;
};
blockedSymbols: Array<{
symbol: string;
primaryReason: string;
reasons: string[];
missingFields?: string[];
invalidValues?: string[];
nanFields?: string[];
suggestedAction?: string;
}>;
symbolDrilldown?: Record<string, {
symbol: string;
featureReadiness: 'READY' | 'WARNING' | 'BLOCKED';
missingInputs: string[];
blockReasons: string[];
timestamps: {
lastValidatedAt?: number;
lastBlockedAt?: number;
lastSuccessfulDecisionAt?: number;
};
rootCauses: string[];
suggestedAction?: string;
}>;
recentErrors: DataQualityIssue[];
recentWarnings: DataQualityIssue[];
lastRefresh: number;
}
//# sourceMappingURL=data-quality.interface.d.ts.map