@wicklib/pro 0.0.0-stage → 0.11.0

package/dist/index.d.ts

@@ -0,0 +1,593 @@
+import { OhlcData, LicenseContext, ChartOverlayApi, ChartApi, Feature, WickExtension } from '@wicklib/core';
+
+/**
+ * Semantic version of the installed pro package.
+ */
+declare const PRO_VERSION: string;
+
+/**
+ * Target position for a strategy.
+ *
+ * -1 = fully short
+ *  0 = flat
+ *  1 = fully long
+ */
+type StrategyTarget = -1 | 0 | 1;
+/**
+ * Context passed to a strategy once per closed bar.
+ */
+interface StrategyContext {
+    readonly bar: OhlcData;
+    readonly index: number;
+    readonly position: StrategyTarget;
+    readonly cash: number;
+    readonly units: number;
+    readonly equity: number;
+}
+/**
+ * Strategy callback. Return a target to schedule a fill at the next bar open, or
+ * `undefined`/`null` to hold the current target.
+ */
+type StrategyFunction = (context: StrategyContext) => StrategyTarget | null | undefined;
+/**
+ * Backtest configuration.
+ */
+interface BacktestOptions {
+    /** Starting cash. Required and positive. */
+    initialCapital: number;
+    /** Fractional fee charged on absolute traded notional. Defaults to 0. */
+    feeRate?: number;
+    /** Fractional slippage applied against the fill. Defaults to 0. */
+    slippage?: number;
+}
+/**
+ * One executed target change.
+ */
+interface BacktestFill {
+    time: number;
+    side: "buy" | "sell";
+    price: number;
+    quantity: number;
+    fee: number;
+}
+/**
+ * One marked-to-market equity point.
+ */
+interface EquityPoint {
+    time: number;
+    cash: number;
+    units: number;
+    position: StrategyTarget;
+    price: number;
+    equity: number;
+}
+/**
+ * Deterministic strategy backtest result.
+ */
+interface BacktestResult {
+    initialCapital: number;
+    finalEquity: number;
+    returnPercent: number;
+    maxDrawdown: number;
+    fills: readonly BacktestFill[];
+    equity: readonly EquityPoint[];
+}
+/**
+ * Runs a target-position strategy against closed bars.
+ *
+ * Signals are evaluated on bar close and filled at the next bar open, preventing
+ * lookahead. Position sizing is fully invested at the fill price; leverage is not added.
+ * Requires the `strategy` license feature.
+ */
+declare function runBacktest(context: LicenseContext, bars: readonly OhlcData[], strategy: StrategyFunction, options: BacktestOptions): BacktestResult;
+
+/**
+ * One alert emitted by a script, including the bar it belongs to.
+ */
+interface ScriptAlertEvent {
+    time: number;
+    barIndex: number;
+    message: string;
+}
+/**
+ * Output required from a compiled script replay.
+ *
+ * This is structurally compatible with `@wicklib/script`'s `CompiledScript`, without making
+ * Pro depend on the script package at runtime.
+ */
+interface ScriptRunResult {
+    plots: Readonly<Record<string, ReadonlyArray<number | null>>>;
+    alerts: ReadonlyArray<string>;
+    alertEvents?: ReadonlyArray<ScriptAlertEvent>;
+}
+/**
+ * Minimal compiled-script contract accepted by the adapter.
+ */
+interface CompiledScriptLike {
+    replay(bars: readonly OhlcData[]): Promise<ScriptRunResult>;
+}
+/**
+ * Options for a script-driven backtest.
+ */
+interface ScriptBacktestOptions extends BacktestOptions {
+    /** Plot id whose values are target positions: -1 short, 0 flat, 1 long, null hold. */
+    signalPlot: string;
+}
+/**
+ * Backtest result plus script alerts.
+ */
+interface ScriptBacktestResult extends BacktestResult {
+    alerts: readonly ScriptAlertEvent[];
+}
+/**
+ * Runs a compiled script, maps one plot to target positions, and backtests the result.
+ *
+ * The script must emit positions on the configured plot. Alerts are returned with their
+ * source bar so the host can deliver or persist them. Requires the `strategy` feature.
+ */
+declare function runScriptBacktest(context: LicenseContext, script: CompiledScriptLike, bars: readonly OhlcData[], options: ScriptBacktestOptions): Promise<ScriptBacktestResult>;
+
+/**
+ * Price field used by a price alert.
+ */
+type AlertPriceSource = "close" | "high" | "low";
+/**
+ * Price alert direction.
+ *
+ * `cross` reports the side that was crossed.
+ */
+type AlertDirection = "above" | "below" | "cross";
+/**
+ * A serializable price alert rule.
+ */
+interface PriceAlertRule {
+    readonly id: string;
+    readonly price: number;
+    readonly direction: AlertDirection;
+    /** Defaults to close. */
+    readonly source?: AlertPriceSource;
+}
+/**
+ * A triggered alert.
+ */
+interface AlertTrigger {
+    readonly ruleId: string;
+    readonly time: number;
+    readonly direction: "above" | "below";
+    readonly price: number;
+    readonly value: number;
+    readonly bar: OhlcData;
+}
+/**
+ * Deterministic, offline alert evaluator for streaming bars.
+ *
+ * The first bar initializes state and never triggers. Subsequent bars trigger only on a
+ * transition so a rule does not fire repeatedly while it remains true.
+ */
+declare class AlertEngine {
+    private readonly rules;
+    private readonly previous;
+    private lastTime;
+    constructor(context: LicenseContext, rules: readonly PriceAlertRule[]);
+    /**
+     * Consumes one closed bar and returns the alerts triggered by that bar.
+     */
+    update(bar: OhlcData): readonly AlertTrigger[];
+    /**
+     * Clears previous values so the next bar initializes state again.
+     */
+    reset(): void;
+}
+/**
+ * Evaluates a batch of closed bars through the same streaming alert path.
+ */
+declare function evaluateAlerts(context: LicenseContext, rules: readonly PriceAlertRule[], bars: readonly OhlcData[]): readonly AlertTrigger[];
+
+/**
+ * One side of a Level-2 depth snapshot.
+ */
+interface DepthLevel {
+    price: number;
+    size: number;
+}
+/**
+ * A full bid/ask book snapshot at a point in time.
+ */
+interface DepthSnapshot {
+    /** Unix timestamp in milliseconds. */
+    time: number;
+    bids: readonly DepthLevel[];
+    asks: readonly DepthLevel[];
+}
+/**
+ * Aggregated bid/ask liquidity by price bucket.
+ */
+interface DepthLevelBar {
+    priceLow: number;
+    priceHigh: number;
+    bidSize: number;
+    askSize: number;
+    totalSize: number;
+    delta: number;
+    imbalance: "bid" | "ask" | null;
+}
+/**
+ * Aggregated depth for one snapshot.
+ */
+interface DepthBar {
+    time: number;
+    priceLow: number;
+    priceHigh: number;
+    bidSize: number;
+    askSize: number;
+    totalSize: number;
+    delta: number;
+    imbalance: "bid" | "ask" | null;
+    levels: readonly DepthLevelBar[];
+}
+/**
+ * Options for depth aggregation.
+ */
+interface DepthOptions {
+    /** Price bucket width. Required. */
+    priceStep?: number;
+    /** Ratio that qualifies total book pressure as imbalanced. Defaults to 2. */
+    imbalanceRatio?: number;
+}
+/**
+ * Incremental L2 depth aggregator.
+ *
+ * Snapshots are complete books, so newer snapshots replace the current view rather than
+ * accumulate. Non-decreasing timestamps are enforced.
+ */
+declare class DepthAggregator {
+    private readonly options;
+    private readonly bars;
+    private lastTime;
+    constructor(context: LicenseContext, options: DepthOptions);
+    /**
+     * Adds or replaces one complete snapshot and returns its aggregated bar.
+     */
+    push(snapshot: DepthSnapshot): DepthBar;
+    /**
+     * Returns the latest snapshot at or before a time.
+     */
+    latest(time?: number): DepthBar | null;
+    /**
+     * Returns all snapshots in ascending time order.
+     */
+    getBars(): readonly DepthBar[];
+    /**
+     * Clears all snapshots and the streaming order guard.
+     */
+    reset(): void;
+}
+/**
+ * Aggregates a batch of complete L2 book snapshots.
+ *
+ * Requires the `orderflow` license feature.
+ */
+declare function computeDepth(context: LicenseContext, snapshots: readonly DepthSnapshot[], options: DepthOptions): readonly DepthBar[];
+
+/**
+ * Aggressor side of a trade tick.
+ */
+type TradeSide = "buy" | "sell";
+/**
+ * Minimal trade tick accepted by the orderflow aggregator.
+ */
+interface TradeTick {
+    /** Unix timestamp in milliseconds. */
+    time: number;
+    price: number;
+    size: number;
+    side: TradeSide;
+}
+/**
+ * Orderflow aggregation options.
+ */
+interface FootprintOptions {
+    /** Time bucket size in milliseconds. Defaults to one minute. */
+    bucketMs?: number;
+    /** Price bucket width. Required. */
+    priceStep?: number;
+    /** Ratio that qualifies a level as imbalanced. Defaults to 3. */
+    imbalanceRatio?: number;
+}
+/**
+ * One price level in a footprint bar.
+ */
+interface FootprintLevel {
+    priceLow: number;
+    priceHigh: number;
+    buyVolume: number;
+    sellVolume: number;
+    totalVolume: number;
+    delta: number;
+    imbalance: TradeSide | null;
+}
+/**
+ * Aggregated footprint for one time bucket.
+ */
+interface FootprintBar {
+    time: number;
+    priceLow: number;
+    priceHigh: number;
+    buyVolume: number;
+    sellVolume: number;
+    totalVolume: number;
+    delta: number;
+    levels: readonly FootprintLevel[];
+}
+/**
+ * Incremental trade-tick footprint aggregator.
+ *
+ * Trades must arrive in non-decreasing time order. Ticks in the same bucket update the
+ * same bar, so streaming and batch aggregation share the same code path.
+ */
+declare class FootprintAggregator {
+    private readonly options;
+    private readonly levels;
+    private lastTradeTime;
+    constructor(context: LicenseContext, options: FootprintOptions);
+    /**
+     * Adds one trade and returns the updated bar for its time bucket.
+     */
+    push(trade: TradeTick): FootprintBar;
+    /**
+     * Adds multiple trades in input order.
+     */
+    pushMany(trades: readonly TradeTick[]): readonly FootprintBar[];
+    /**
+     * Returns a bar by bucket start time, or any time inside that bucket.
+     */
+    getBar(time: number): FootprintBar | null;
+    /**
+     * Returns all completed/current buckets in ascending time order.
+     */
+    getBars(): readonly FootprintBar[];
+    /**
+     * Clears all trades and resets the streaming order guard.
+     */
+    reset(): void;
+    private buildBar;
+    private validateTrade;
+}
+/**
+ * Aggregates trade ticks into bid/ask footprint bars with delta and imbalance.
+ *
+ * Requires the `orderflow` license feature. Trades are sorted by time before aggregation.
+ */
+declare function computeFootprint(context: LicenseContext, trades: readonly TradeTick[], options: FootprintOptions): readonly FootprintBar[];
+
+/**
+ * Options for absorption detection.
+ */
+interface AbsorptionOptions {
+    /** Time bucket size in milliseconds. Defaults to one minute. */
+    bucketMs?: number;
+    /** Price bucket width. Required. */
+    priceStep?: number;
+    /** Aggressive volume must reach passive size × this ratio. Defaults to 2. */
+    absorptionRatio?: number;
+}
+/**
+ * A detected absorption event.
+ */
+interface AbsorptionEvent {
+    /** Bucket start time in milliseconds. */
+    time: number;
+    priceLow: number;
+    priceHigh: number;
+    /** Aggressor side that was absorbed. */
+    side: TradeSide;
+    /** Aggressive trade volume in the bucket and level. */
+    aggressiveVolume: number;
+    /** Passive book size at the level when the bucket completed. */
+    passiveVolume: number;
+    /** aggressiveVolume / passiveVolume. */
+    ratio: number;
+}
+/**
+ * Detects aggressive volume absorbed by passive L2 liquidity.
+ *
+ * For each footprint bucket and price level:
+ * - aggressive buys are compared with ask depth
+ * - aggressive sells are compared with bid depth
+ *
+ * A level is reported when aggressive volume is at least the configured multiple of the
+ * passive size. Requires the `orderflow` license feature.
+ */
+declare function detectAbsorption(context: LicenseContext, trades: readonly TradeTick[], snapshots: readonly DepthSnapshot[], options: AbsorptionOptions): readonly AbsorptionEvent[];
+
+/**
+ * Volume distribution model.
+ *
+ * `uniform` spreads each bar's volume evenly across its price range. `close` assigns the
+ * whole bar volume to the bin containing the close.
+ */
+type VolumeProfileDistribution = "uniform" | "close";
+/**
+ * Options for {@link computeVolumeProfile}.
+ */
+interface VolumeProfileOptions {
+    /** Number of equal-width price bins. Defaults to 24. */
+    bins?: number;
+    /** Fixed price range. Defaults to the bars' low/high span. */
+    priceRange?: {
+        min: number;
+        max: number;
+    };
+    /** Fraction of total volume covered by the value area. Defaults to 0.7. */
+    valueArea?: number;
+    /** Volume distribution model. Defaults to uniform. */
+    distribution?: VolumeProfileDistribution;
+}
+/**
+ * One price bucket in a volume profile.
+ */
+interface VolumeProfileBin {
+    index: number;
+    priceLow: number;
+    priceHigh: number;
+    priceMid: number;
+    volume: number;
+}
+/**
+ * Computed volume profile.
+ */
+interface VolumeProfile {
+    bins: readonly VolumeProfileBin[];
+    range: {
+        min: number;
+        max: number;
+    };
+    totalVolume: number;
+    /** Point of control, or null when there is no volume. */
+    poc: VolumeProfileBin | null;
+    valueArea: {
+        low: number;
+        high: number;
+        volume: number;
+    } | null;
+}
+/**
+ * Computes a deterministic volume profile from OHLCV bars.
+ *
+ * Requires the `volume-profile` license feature. Bars without a finite positive volume are
+ * ignored. Throws `WickError("INVALID_DATA")` when no usable volume remains.
+ */
+declare function computeVolumeProfile(context: LicenseContext, bars: readonly OhlcData[], options?: VolumeProfileOptions): VolumeProfile;
+
+/**
+ * Colors used by the volume-profile overlay.
+ */
+interface VolumeProfileOverlayColors {
+    bar: string;
+    valueArea: string;
+    poc: string;
+}
+/**
+ * Options for {@link addVolumeProfileOverlay}.
+ */
+interface VolumeProfileOverlayOptions extends VolumeProfileOptions {
+    /** Overlay id. Defaults to a unique pro id. */
+    id?: string;
+    /** Pane to draw in. Defaults to the main pane. */
+    paneId?: string;
+    /** Histogram side. Defaults to the left side. */
+    side?: "left" | "right";
+    /** Histogram width as a fraction of the pane plot width. Defaults to 0.22. */
+    widthRatio?: number;
+    colors?: Partial<VolumeProfileOverlayColors>;
+}
+/**
+ * Live volume-profile overlay.
+ */
+interface VolumeProfileOverlay extends ChartOverlayApi {
+    readonly profile: VolumeProfile;
+}
+/**
+ * Computes a volume profile and adds it to a chart as a clipped pane overlay.
+ *
+ * Requires the `volume-profile` license feature.
+ */
+declare function addVolumeProfileOverlay(context: LicenseContext, chart: ChartApi, bars: readonly OhlcData[], options?: VolumeProfileOverlayOptions): VolumeProfileOverlay;
+
+/**
+ * Features shipped in the commercial tier.
+ */
+declare const PRO_FEATURES: readonly ["orderflow", "volume-profile", "panes", "layouts", "strategy", "alerts", "script-functions"];
+/**
+ * A feature name provided by the commercial tier.
+ */
+type ProFeature = (typeof PRO_FEATURES)[number];
+/**
+ * Core feature tokens covered by the pro feature list.
+ */
+declare const PRO_CORE_FEATURES: readonly Feature[];
+
+/**
+ * Extension descriptor for a commercial feature.
+ */
+interface ProExtension extends WickExtension {
+    readonly kind: "feature";
+    readonly feature: ProFeature;
+}
+/**
+ * Capability descriptors for the commercial feature set.
+ *
+ * Hosts pass the granted descriptors through `ChartOptions.extensions`. Individual
+ * analytics register their runtime behavior separately.
+ */
+declare const PRO_EXTENSIONS: readonly ProExtension[];
+/**
+ * Returns the feature descriptors granted by a license context.
+ */
+declare function getProExtensions(context: LicenseContext): readonly ProExtension[];
+
+/**
+ * Decoded payload of a Wicklib license token.
+ *
+ * Tokens are Ed25519-signed and verified offline. `exp` is seconds since the Unix
+ * epoch. `kid` selects the embedded public key.
+ */
+interface LicenseTokenPayload {
+    product: string;
+    plan: string;
+    seats: number;
+    domains: string[];
+    exp: number;
+    features: Feature[];
+    kid: string;
+}
+/**
+ * Options for creating a license context.
+ */
+interface LicenseVerifierOptions {
+    /** Public keys indexed by `kid`, encoded as base64url raw Ed25519 keys. */
+    publicKeys: Readonly<Record<string, string>>;
+    /** Clock override for deterministic tests. Returns seconds since the epoch. */
+    now?: () => number;
+    /** Origin the license is being used from, if domain locking is enabled. */
+    domain?: string;
+    /** Expected product id. Defaults to wicklib-pro. */
+    product?: string;
+}
+/**
+ * Machine-readable license failure codes.
+ */
+type LicenseErrorCode = "CRYPTO_UNAVAILABLE" | "INVALID_TOKEN" | "UNSUPPORTED_ALGORITHM" | "UNKNOWN_KID" | "INVALID_PAYLOAD" | "EXPIRED" | "WRONG_PRODUCT" | "DOMAIN_REQUIRED" | "DOMAIN_NOT_ALLOWED" | "SIGNATURE_INVALID";
+/**
+ * Typed license verification failure.
+ */
+declare class LicenseError extends Error {
+    readonly code: LicenseErrorCode;
+    constructor(code: LicenseErrorCode, message: string);
+}
+/**
+ * Verifies an Ed25519 license token and returns the feature context used by pro
+ * extensions.
+ *
+ * Verification is fully offline. No network or telemetry calls are made.
+ */
+declare function createLicenseContext(token: string, options: LicenseVerifierOptions): Promise<LicenseContext>;
+
+/**
+ * Wicklib Pro public API.
+ *
+ * The package is published to npm under the Wicklib Commercial License; its source
+ * repository is private.
+ */
+
+/**
+ * Returns true when the active license grants a pro feature.
+ */
+declare function hasProFeature(context: LicenseContext, feature: Feature): boolean;
+/**
+ * Throws `WickError("LICENSE_REQUIRED")` when a pro feature is not granted.
+ */
+declare function assertProFeature(context: LicenseContext, feature: Feature): void;
+
+export { AlertEngine, DepthAggregator, FootprintAggregator, LicenseError, PRO_CORE_FEATURES, PRO_EXTENSIONS, PRO_FEATURES, PRO_VERSION, addVolumeProfileOverlay, assertProFeature, computeDepth, computeFootprint, computeVolumeProfile, createLicenseContext, detectAbsorption, evaluateAlerts, getProExtensions, hasProFeature, runBacktest, runScriptBacktest };
+export type { AbsorptionEvent, AbsorptionOptions, AlertDirection, AlertPriceSource, AlertTrigger, BacktestFill, BacktestOptions, BacktestResult, CompiledScriptLike, DepthBar, DepthLevel, DepthLevelBar, DepthOptions, DepthSnapshot, EquityPoint, FootprintBar, FootprintLevel, FootprintOptions, LicenseErrorCode, LicenseTokenPayload, LicenseVerifierOptions, PriceAlertRule, ProExtension, ProFeature, ScriptAlertEvent, ScriptBacktestOptions, ScriptBacktestResult, ScriptRunResult, StrategyContext, StrategyFunction, StrategyTarget, TradeSide, TradeTick, VolumeProfile, VolumeProfileBin, VolumeProfileDistribution, VolumeProfileOptions, VolumeProfileOverlay, VolumeProfileOverlayColors, VolumeProfileOverlayOptions };