@barfinex/types
Version:
Core TypeScript type definitions and shared interfaces for the Barfinex ecosystem. Provides strongly-typed contracts for modules, services, and plugins.
397 lines • 13.9 kB
TypeScript
import { Detector } from './detector.interface';
import { Connector } from './connector.interface';
import { AccountEvent } from './account.interface';
import { ConnectorType, MarketType } from './connector.interface';
import { Order } from './order.interface';
import { OrderBook } from './orderbook.interface';
import { InstrumentPrice, Instrument } from './instrument.interface';
import { Trade } from './trade.interface';
import { Candle, TimeFrame } from '.';
import { DetectorStrategySignalAttribution } from './detector-strategy.interface';
/**
* Strict event sources.
* Only these 4 applications can emit events.
*/
export declare enum EventSource {
PROVIDER = "PROVIDER",
INSPECTOR = "INSPECTOR",
DETECTOR = "DETECTOR",
ADVISOR = "ADVISOR"
}
/**
* All allowed subscription/event types.
* Must always start with one of the EventSource prefixes.
*/
export declare enum SubscriptionType {
PROVIDER_MARKETDATA_TRADE = "PROVIDER_MARKETDATA_TRADE",
PROVIDER_MARKETDATA_ORDERBOOK = "PROVIDER_MARKETDATA_ORDERBOOK",
PROVIDER_MARKETDATA_CANDLE = "PROVIDER_MARKETDATA_CANDLE",
PROVIDER_ACCOUNT_EVENT = "PROVIDER_ACCOUNT_EVENT",
PROVIDER_ORDER_CREATE = "PROVIDER_ORDER_CREATE",
PROVIDER_ORDER_CLOSE = "PROVIDER_ORDER_CLOSE",
PROVIDER_INSTRUMENTS = "PROVIDER_INSTRUMENTS",
PROVIDER_INSTRUMENT_PRICES = "PROVIDER_INSTRUMENT_PRICES",
INSPECTOR_TREND_DETECTED = "INSPECTOR_TREND_DETECTED",
INSPECTOR_RANGE_DETECTED = "INSPECTOR_RANGE_DETECTED",
INSPECTOR_VOLATILITY_SPIKE = "INSPECTOR_VOLATILITY_SPIKE",
INSPECTOR_LIQUIDITY_DROPPED = "INSPECTOR_LIQUIDITY_DROPPED",
INSPECTOR_DATA_GAP_DETECTED = "INSPECTOR_DATA_GAP_DETECTED",
INSPECTOR_DATA_OUTLIER_DETECTED = "INSPECTOR_DATA_OUTLIER_DETECTED",
INSPECTOR_DATA_MATURITY_UPDATE = "INSPECTOR_DATA_MATURITY_UPDATE",
INSPECTOR_RISK_LIMIT_BREACH = "INSPECTOR_RISK_LIMIT_BREACH",
INSPECTOR_RISK_MARGIN_UPDATE = "INSPECTOR_RISK_MARGIN_UPDATE",
INSPECTOR_RISK_KILL_SWITCH = "INSPECTOR_RISK_KILL_SWITCH",
INSPECTOR_TRADE_OUTCOME = "INSPECTOR_TRADE_OUTCOME",
DETECTOR_SIGNAL_GENERATED = "DETECTOR_SIGNAL_GENERATED",
DETECTOR_SIGNAL_UPDATED = "DETECTOR_SIGNAL_UPDATED",
DETECTOR_SIGNAL_INVALIDATED = "DETECTOR_SIGNAL_INVALIDATED",
DETECTOR_POSITION_OPEN_REQUEST = "DETECTOR_POSITION_OPEN_REQUEST",
DETECTOR_POSITION_CLOSE_REQUEST = "DETECTOR_POSITION_CLOSE_REQUEST",
DETECTOR_POSITION_REDUCE_REQUEST = "DETECTOR_POSITION_REDUCE_REQUEST",
DETECTOR_POSITION_FLIP_REQUEST = "DETECTOR_POSITION_FLIP_REQUEST",
ADVISOR_DECISION_REQUEST = "ADVISOR_DECISION_REQUEST",
ADVISOR_DECISION_RESPONSE = "ADVISOR_DECISION_RESPONSE",
ADVISOR_DECISION_MADE = "ADVISOR_DECISION_MADE",
ADVISOR_SIGNAL_GENERATED = "ADVISOR_SIGNAL_GENERATED",
ADVISOR_EXECUTION_INTENT_OPEN = "ADVISOR_EXECUTION_INTENT_OPEN",
ADVISOR_EXECUTION_INTENT_CLOSE = "ADVISOR_EXECUTION_INTENT_CLOSE",
ADVISOR_EXECUTION_INTENT_REDUCE = "ADVISOR_EXECUTION_INTENT_REDUCE",
ADVISOR_EXECUTION_INTENT_FLIP = "ADVISOR_EXECUTION_INTENT_FLIP",
EXECUTION_INTENT_OPEN = "ADVISOR_EXECUTION_INTENT_OPEN",
EXECUTION_INTENT_CLOSE = "ADVISOR_EXECUTION_INTENT_CLOSE",
EXECUTION_INTENT_REDUCE = "ADVISOR_EXECUTION_INTENT_REDUCE",
EXECUTION_INTENT_FLIP = "ADVISOR_EXECUTION_INTENT_FLIP",
ADVISOR_AUTONOMOUS_CYCLE_STARTED = "ADVISOR_AUTONOMOUS_CYCLE_STARTED",
ADVISOR_AUTONOMOUS_CYCLE_COMPLETED = "ADVISOR_AUTONOMOUS_CYCLE_COMPLETED",
ADVISOR_DECISION_CONTEXT_SNAPSHOT = "ADVISOR_DECISION_CONTEXT_SNAPSHOT",
ADVISOR_CONVICTION_SNAPSHOT = "ADVISOR_CONVICTION_SNAPSHOT",
ADVISOR_CONVICTION_CALIBRATION_SNAPSHOT = "ADVISOR_CONVICTION_CALIBRATION_SNAPSHOT",
ADVISOR_PORTFOLIO_ALLOCATION_SNAPSHOT = "ADVISOR_PORTFOLIO_ALLOCATION_SNAPSHOT",
ADVISOR_PORTFOLIO_CORRELATION_SNAPSHOT = "ADVISOR_PORTFOLIO_CORRELATION_SNAPSHOT",
ADVISOR_REGIME_CAPITAL_ROTATION_SNAPSHOT = "ADVISOR_REGIME_CAPITAL_ROTATION_SNAPSHOT",
ADVISOR_NET_EXPOSURE_SNAPSHOT = "ADVISOR_NET_EXPOSURE_SNAPSHOT",
ADVISOR_FACTOR_EXPOSURE_SNAPSHOT = "ADVISOR_FACTOR_EXPOSURE_SNAPSHOT",
ADVISOR_PORTFOLIO_RISK_MODE_SNAPSHOT = "ADVISOR_PORTFOLIO_RISK_MODE_SNAPSHOT",
ADVISOR_PERFORMANCE_FEEDBACK_PROCESSED = "ADVISOR_PERFORMANCE_FEEDBACK_PROCESSED",
ADVISOR_OUTCOME_ATTRIBUTION_SNAPSHOT = "ADVISOR_OUTCOME_ATTRIBUTION_SNAPSHOT",
ADVISOR_CONFIDENCE_LOW = "ADVISOR_CONFIDENCE_LOW",
ADVISOR_MODEL_SWITCHED = "ADVISOR_MODEL_SWITCHED",
ADVISOR_HALLUCINATION_DETECTED = "ADVISOR_HALLUCINATION_DETECTED"
}
/**
* Base institutional event contract.
*/
export interface BaseEvent<TType extends SubscriptionType, TPayload> {
eventId: string;
type: TType;
source: EventSource;
timestamp: number;
correlationId?: string;
causationId?: string;
payload: TPayload;
}
/**
* Inspector-specific payload examples.
*/
export interface InspectorRiskPayload {
instrument: Instrument;
currentExposure: number;
maxAllowedExposure: number;
reason?: string;
}
export interface InspectorRegimePayload {
instrument: Instrument;
regime: 'TREND' | 'RANGE' | 'VOLATILE' | 'UNKNOWN';
}
export interface InspectorTradeOutcomePayload {
symbol: string;
regime?: string;
entryPrice?: number;
exitPrice?: number;
realizedPnL: number;
outcomeType?: 'MARKET' | 'EXECUTION' | 'INFRA';
executionErrorCode?: string;
slippagePct?: number;
latencyMs?: number;
convictionScore?: number;
volatilityScore?: number;
liquidityScore?: number;
closedAt: number;
}
/**
* Detector payloads.
*/
export interface DetectorSignalPayload extends DetectorStrategySignalAttribution {
instrument: Instrument;
side: 'LONG' | 'SHORT';
confidence: number;
strategyId: string;
}
/**
* Advisor payloads.
*/
/**
* @deprecated Use `AdvisorDecisionMadePayload` for decision data and
* `ExecutionIntentPayload` for execution data.
*/
export interface AdvisorDecisionPayload {
decisionId: string;
approved: boolean;
reasoning?: string;
confidence?: number;
modelProfile?: 'coding' | 'ml';
}
export type AdvisorDecisionMadeDecision = 'OPEN' | 'CLOSE' | 'HOLD' | 'REDUCE';
export interface AdvisorDecisionMadePayload {
decisionId: string;
traceId: string;
symbol: string;
decision: AdvisorDecisionMadeDecision;
confidence: number;
reasoning?: string;
modelProfile?: 'coding' | 'ml';
timestamp: number;
}
export type ExecutionIntentSide = 'BUY' | 'SELL';
export type ExecutionIntentSource = 'advisor' | 'detector' | 'inspector';
export interface ExecutionIntentPayload {
intentId: string;
decisionId: string;
traceId: string;
symbol: string;
side: ExecutionIntentSide;
quantity: number;
leverage: number;
connector: ConnectorType;
marketType: MarketType;
accountId: string;
sandbox: boolean;
idempotencyKey: string;
source: ExecutionIntentSource;
schemaVersion: number;
timestamp: number;
}
export interface AdvisorSignalPayload {
symbol: string;
direction: 'LONG' | 'SHORT' | 'NEUTRAL';
regime: string;
volatilityBucket: 'LOW' | 'MEDIUM' | 'HIGH';
confidence?: number;
contextMeta?: Record<string, unknown>;
}
export interface AdvisorAutonomousCycleStartedPayload {
symbol: string;
trigger: 'candle_close' | 'interval';
startedAt: number;
}
export interface AdvisorAutonomousCycleCompletedPayload {
symbol: string;
trigger: 'candle_close' | 'interval';
outcome: 'executed' | 'rejected' | 'no_trade' | 'skipped' | 'failed';
reasons?: string[];
completedAt: number;
}
export interface AdvisorConvictionPayload {
symbol: string;
finalScore: number;
baseScore: number;
riskFloor: number;
capitalMultiplier: number;
allocatedMultiplier?: number;
multiplierRaw: number;
multiplierCapped: number;
components: {
confidenceScore: number;
regimeScore: number;
volatilityScore: number;
liquidityScore: number;
healthScore?: number;
};
confidence: number;
regime: string;
generatedAt: number;
}
export interface AdvisorConvictionCalibrationPayload {
currentWeights: {
confidence: number;
regime: number;
volatility: number;
liquidity: number;
health: number;
};
performanceByBucket: Array<{
regime: string;
volatilityBucket: string;
liquidityBucket: string;
convictionBand: string;
sampleSize: number;
winRate: number;
avgPnL: number;
expectancy: number;
}>;
updatedAt: number;
}
export interface AdvisorPortfolioAllocationPayload {
totalCandidates: number;
totalScore: number;
perSymbol: Array<{
symbol: string;
finalScore: number;
capitalMultiplier: number;
allocatedMultiplier: number;
}>;
generatedAt: number;
}
export interface AdvisorPortfolioRiskModeSnapshotPayload {
currentEquity: number;
peakEquity: number;
drawdownPct: number;
currentMode: 'NORMAL' | 'DEFENSIVE' | 'SURVIVAL';
throttleFactor: number;
}
export interface AdvisorPortfolioCorrelationSnapshotPayload {
totalCandidates: number;
clusterScore: number;
clusterPenaltyFactor: number;
perSymbol: Array<{
symbol: string;
originalAllocation: number;
adjustedAllocation: number;
regime: string;
direction: 'LONG' | 'SHORT' | 'UNKNOWN';
}>;
}
export interface AdvisorRegimeCapitalRotationSnapshotPayload {
dominantRegime: 'TREND_STRONG' | 'TREND_WEAK' | 'RANGE' | 'VOLATILE' | 'UNKNOWN';
regimeDistribution: {
TREND_STRONG: number;
TREND_WEAK: number;
RANGE: number;
VOLATILE: number;
UNKNOWN: number;
};
cycleCapMultiplier: number;
effectiveCycleCap: number;
}
export interface AdvisorNetExposureSnapshotPayload {
gross: number;
net: number;
netPct: number;
maxNetPct: number;
penaltyApplied: boolean;
dominantSide: 'LONG' | 'SHORT' | 'NONE';
perSymbol: Array<{
symbol: string;
direction: 'LONG' | 'SHORT' | 'UNKNOWN';
originalAllocation: number;
adjustedAllocation: number;
}>;
}
export interface AdvisorFactorExposureSnapshotPayload {
factorDistribution: Record<string, {
allocatedMultiplier: number;
exposurePct: number;
}>;
maxFactorPct: number;
adjustedFactors: string[];
perSymbol: Array<{
symbol: string;
factorKey: string;
originalAllocation: number;
adjustedAllocation: number;
}>;
}
export interface AdvisorPerformanceFeedbackProcessedPayload {
symbol: string;
pnl: number;
convictionScore: number;
bucketAssignment: {
regime: string;
volatilityBucket: 'low' | 'mid' | 'high';
liquidityBucket: 'low' | 'mid' | 'high';
convictionBand: 'low' | 'mid' | 'high';
};
updatedWeights: {
confidence: number;
regime: number;
volatility: number;
liquidity: number;
health: number;
};
}
export interface AdvisorOutcomeAttributionSnapshotPayload {
rollingWindowSize: number;
countsByOutcomeType: {
MARKET: number;
EXECUTION: number;
INFRA: number;
};
countsBySymbol: Array<{
symbol: string;
total: number;
byOutcomeType: {
MARKET: number;
EXECUTION: number;
INFRA: number;
};
}>;
countsByConnectorType: Array<{
connectorType: string;
total: number;
byOutcomeType: {
MARKET: number;
EXECUTION: number;
INFRA: number;
};
}>;
lastOutcomes: Array<{
symbol: string;
connectorType?: string;
outcomeType: 'MARKET' | 'EXECUTION' | 'INFRA';
calibrationApplied: boolean;
timestamp: number;
executionErrorCode?: string;
slippagePct?: number;
latencyMs?: number;
}>;
}
/**
* Strict union of all allowed payloads.
* NO any allowed.
*/
export type EventPayload = AccountEvent | Order | OrderBook | Trade | Instrument[] | InstrumentPrice | Candle | InspectorRiskPayload | InspectorRegimePayload | InspectorTradeOutcomePayload | DetectorSignalPayload
/**
* @deprecated Use AdvisorDecisionMadePayload + ExecutionIntentPayload.
* Kept for backward compatibility with legacy consumers.
*/
| AdvisorDecisionPayload | AdvisorDecisionMadePayload | ExecutionIntentPayload | AdvisorSignalPayload | AdvisorAutonomousCycleStartedPayload | AdvisorAutonomousCycleCompletedPayload | AdvisorConvictionPayload | AdvisorConvictionCalibrationPayload | AdvisorPortfolioAllocationPayload | AdvisorPortfolioCorrelationSnapshotPayload | AdvisorRegimeCapitalRotationSnapshotPayload | AdvisorNetExposureSnapshotPayload | AdvisorFactorExposureSnapshotPayload | AdvisorPortfolioRiskModeSnapshotPayload | AdvisorPerformanceFeedbackProcessedPayload | AdvisorOutcomeAttributionSnapshotPayload;
export type EventEnvelope = BaseEvent<SubscriptionType, EventPayload>;
/**
* Subscription value wrapper.
*/
export interface SubscriptionValue {
value: EventPayload | EventEnvelope;
options: {
key?: string;
connectorType?: ConnectorType;
marketType?: MarketType;
updateMoment: number;
};
}
/**
* Subscription configuration.
*/
export interface Subscription {
type: SubscriptionType;
instruments?: Instrument[];
connector?: Connector;
detector?: Detector;
updateMoment?: number;
active: boolean;
intervals?: TimeFrame[];
}
/**
* Compile-time source validation.
*/
export declare function assertEventSourceMatch(type: `${EventSource}_${string}` | SubscriptionType, source: EventSource): void;
//# sourceMappingURL=subscription.interface.d.ts.map