@luxalgo/vela-pinets 0.2.12 → 0.2.14

package/dist/index.d.cts

@@ -1,5 +1,64 @@
 import { ScriptingEngine, EngineCapabilities, InputValue, PreparedScript, ExecutionRequest, ExecutionHandlers, ExecutionSession } from '@luxalgo/vela/plugin';
 
+/**
+ * The host-facing order-flow seam behind Pine's `request.footprint()`.
+ *
+ * Vela owns bars, never order flow — so a host that HAS per-bar volume footprints
+ * (a footprint-capable data provider) hands the engine a {@link FootprintSource},
+ * and the engine exposes it to PineTS as the optional `getFootprintData` surface of
+ * its virtual market-data provider. Without a source the surface is simply absent
+ * and every `request.footprint()` call answers `na`, exactly as PineTS specifies.
+ *
+ * The shapes below are structurally identical to PineTS's `FootprintBar` /
+ * `FootprintLevel` (declared here rather than imported so this package builds and
+ * types against any pinets version — the surface only becomes REACHABLE once the
+ * bundled pinets implements `request.footprint()`).
+ */
+/** Executed volume at one price level of a bar, split by aggressor side. */
+interface FootprintLevel {
+    /** Level price — the LOW edge of the price bucket this level covers. */
+    price: number;
+    /** Volume executed by buy-aggressors (ask lifts) at this level. */
+    buyVolume: number;
+    /** Volume executed by sell-aggressors (bid hits) at this level. */
+    sellVolume: number;
+}
+/**
+ * The volume footprint of ONE chart bar, keyed by the bar's open time. Levels may
+ * sit on any price grid: PineTS re-bins them into `ticks_per_row × mintick` rows
+ * itself, so a source serves its finest granularity and never needs the row size.
+ */
+interface FootprintBar {
+    /** Bar open time, epoch ms — equals the matching bar's `time`. */
+    openTime: number;
+    /** Price step the levels were bucketed on. Informational only. */
+    tick?: number;
+    /** Price levels, any order; levels without volume may be omitted. */
+    levels: FootprintLevel[];
+}
+/** The window PineTS asks for — mirrors its `getMarketData(…, limit, sDate, eDate)` slots. */
+interface FootprintRange {
+    /** First bar open time (epoch ms), inclusive. Absent on a bare tail poll. */
+    from?: number;
+    /** Exclusive end (epoch ms). Absent = "up to now". */
+    to?: number;
+    /** Bar count of the loaded history on the initial load; absent on tail polls. */
+    limit?: number;
+}
+/**
+ * Per-bar footprints of `(symbol, timeframe)` over `range`, plain symbol (chart-type
+ * modifiers never reach it: order flow is never derived). Usually the chart series,
+ * but a `request.footprint()` evaluated inside `request.security()` asks for THAT
+ * context's symbol and timeframe, which may differ from the chart's.
+ *
+ * Call pattern (PineTS's), per series: one call over the whole loaded history, then
+ * — whenever the market data changes (a live tick, new bars) — a call from the
+ * forming bar's open time onward. Returned bars REPLACE what PineTS holds for those
+ * open times, so a live source just answers with its current state for the tail.
+ * Bars the source cannot serve are omitted; the script reads `na` for them.
+ */
+type FootprintSource = (symbol: string, timeframe: string, range: FootprintRange) => Promise<FootprintBar[]>;
+
 /**
  * Which scripts publish a declaration-props schema (the settings dialog's
  * "Properties" tab): every script, only `strategy()` scripts, or none.
@@ -35,6 +94,13 @@ interface PineEngineOptions {
      * source/spec values, and `setProps` still applies.
      */
     props?: PropsFilter;
+    /**
+     * Per-bar volume footprints for Pine's `request.footprint()`. Vela owns bars, not
+     * order flow, so a host with a footprint-capable data source supplies this; the
+     * engine exposes it to PineTS as its provider's optional `getFootprintData`
+     * surface. Absent ≡ `request.footprint()` answers `na` on every bar.
+     */
+    footprints?: FootprintSource;
 }
 /**
  * The in-process PineTS implementation of `ScriptingEngine`. Both the static run
@@ -48,6 +114,7 @@ declare class PineEngine implements ScriptingEngine {
     readonly capabilities: EngineCapabilities;
     private readonly defaultProps;
     private readonly propsVisibility;
+    private readonly footprints;
     constructor(opts?: PineEngineOptions);
     prepare(source: string, instanceId: string): Promise<PreparedScript>;
     execute(req: ExecutionRequest, handlers: ExecutionHandlers): ExecutionSession;
@@ -88,6 +155,14 @@ interface PineWorkerOptions {
      * source/spec values, and `setProps` still applies.
      */
     props?: PropsFilter;
+    /**
+     * Per-bar volume footprints for Pine's `request.footprint()`. Vela owns bars, not
+     * order flow, so a host with a footprint-capable data source supplies this; the
+     * worker exposes it to PineTS as its provider's optional `getFootprintData`
+     * surface and round-trips each call here (the source runs on the main thread,
+     * like `fetchSeries`). Absent ≡ `request.footprint()` answers `na` on every bar.
+     */
+    footprints?: FootprintSource;
 }
 /**
  * A worker-backed PineTS engine: identical Pine semantics to `PineEngine`, but the
@@ -110,6 +185,7 @@ declare class PineWorkerEngine implements ScriptingEngine {
     private readonly spawn;
     private readonly defaultProps;
     private readonly propsVisibility;
+    private readonly footprints;
     private readonly prepares;
     private readonly sessions;
     private reqId;
@@ -146,6 +222,12 @@ declare class PineWorkerEngine implements ScriptingEngine {
      * cache-backed gateway (same provider, neutral by (symbol, timeframe)).
      */
     private serveFetch;
+    /**
+     * Answer a worker's footprint request from the engine's `footprints` option. The
+     * worker only asks when `execute` flagged a source, so a missing one here is a
+     * host bug — answer empty rather than hang the script's await.
+     */
+    private serveFootprints;
 }
 
-export { PineEngine, type PineEngineOptions, PineWorkerEngine, type PineWorkerOptions, type PropsFilter, type PropsVisibility };
+export { type FootprintBar, type FootprintLevel, type FootprintRange, type FootprintSource, PineEngine, type PineEngineOptions, PineWorkerEngine, type PineWorkerOptions, type PropsFilter, type PropsVisibility };

package/dist/index.d.ts

@@ -1,5 +1,64 @@
 import { ScriptingEngine, EngineCapabilities, InputValue, PreparedScript, ExecutionRequest, ExecutionHandlers, ExecutionSession } from '@luxalgo/vela/plugin';
 
+/**
+ * The host-facing order-flow seam behind Pine's `request.footprint()`.
+ *
+ * Vela owns bars, never order flow — so a host that HAS per-bar volume footprints
+ * (a footprint-capable data provider) hands the engine a {@link FootprintSource},
+ * and the engine exposes it to PineTS as the optional `getFootprintData` surface of
+ * its virtual market-data provider. Without a source the surface is simply absent
+ * and every `request.footprint()` call answers `na`, exactly as PineTS specifies.
+ *
+ * The shapes below are structurally identical to PineTS's `FootprintBar` /
+ * `FootprintLevel` (declared here rather than imported so this package builds and
+ * types against any pinets version — the surface only becomes REACHABLE once the
+ * bundled pinets implements `request.footprint()`).
+ */
+/** Executed volume at one price level of a bar, split by aggressor side. */
+interface FootprintLevel {
+    /** Level price — the LOW edge of the price bucket this level covers. */
+    price: number;
+    /** Volume executed by buy-aggressors (ask lifts) at this level. */
+    buyVolume: number;
+    /** Volume executed by sell-aggressors (bid hits) at this level. */
+    sellVolume: number;
+}
+/**
+ * The volume footprint of ONE chart bar, keyed by the bar's open time. Levels may
+ * sit on any price grid: PineTS re-bins them into `ticks_per_row × mintick` rows
+ * itself, so a source serves its finest granularity and never needs the row size.
+ */
+interface FootprintBar {
+    /** Bar open time, epoch ms — equals the matching bar's `time`. */
+    openTime: number;
+    /** Price step the levels were bucketed on. Informational only. */
+    tick?: number;
+    /** Price levels, any order; levels without volume may be omitted. */
+    levels: FootprintLevel[];
+}
+/** The window PineTS asks for — mirrors its `getMarketData(…, limit, sDate, eDate)` slots. */
+interface FootprintRange {
+    /** First bar open time (epoch ms), inclusive. Absent on a bare tail poll. */
+    from?: number;
+    /** Exclusive end (epoch ms). Absent = "up to now". */
+    to?: number;
+    /** Bar count of the loaded history on the initial load; absent on tail polls. */
+    limit?: number;
+}
+/**
+ * Per-bar footprints of `(symbol, timeframe)` over `range`, plain symbol (chart-type
+ * modifiers never reach it: order flow is never derived). Usually the chart series,
+ * but a `request.footprint()` evaluated inside `request.security()` asks for THAT
+ * context's symbol and timeframe, which may differ from the chart's.
+ *
+ * Call pattern (PineTS's), per series: one call over the whole loaded history, then
+ * — whenever the market data changes (a live tick, new bars) — a call from the
+ * forming bar's open time onward. Returned bars REPLACE what PineTS holds for those
+ * open times, so a live source just answers with its current state for the tail.
+ * Bars the source cannot serve are omitted; the script reads `na` for them.
+ */
+type FootprintSource = (symbol: string, timeframe: string, range: FootprintRange) => Promise<FootprintBar[]>;
+
 /**
  * Which scripts publish a declaration-props schema (the settings dialog's
  * "Properties" tab): every script, only `strategy()` scripts, or none.
@@ -35,6 +94,13 @@ interface PineEngineOptions {
      * source/spec values, and `setProps` still applies.
      */
     props?: PropsFilter;
+    /**
+     * Per-bar volume footprints for Pine's `request.footprint()`. Vela owns bars, not
+     * order flow, so a host with a footprint-capable data source supplies this; the
+     * engine exposes it to PineTS as its provider's optional `getFootprintData`
+     * surface. Absent ≡ `request.footprint()` answers `na` on every bar.
+     */
+    footprints?: FootprintSource;
 }
 /**
  * The in-process PineTS implementation of `ScriptingEngine`. Both the static run
@@ -48,6 +114,7 @@ declare class PineEngine implements ScriptingEngine {
     readonly capabilities: EngineCapabilities;
     private readonly defaultProps;
     private readonly propsVisibility;
+    private readonly footprints;
     constructor(opts?: PineEngineOptions);
     prepare(source: string, instanceId: string): Promise<PreparedScript>;
     execute(req: ExecutionRequest, handlers: ExecutionHandlers): ExecutionSession;
@@ -88,6 +155,14 @@ interface PineWorkerOptions {
      * source/spec values, and `setProps` still applies.
      */
     props?: PropsFilter;
+    /**
+     * Per-bar volume footprints for Pine's `request.footprint()`. Vela owns bars, not
+     * order flow, so a host with a footprint-capable data source supplies this; the
+     * worker exposes it to PineTS as its provider's optional `getFootprintData`
+     * surface and round-trips each call here (the source runs on the main thread,
+     * like `fetchSeries`). Absent ≡ `request.footprint()` answers `na` on every bar.
+     */
+    footprints?: FootprintSource;
 }
 /**
  * A worker-backed PineTS engine: identical Pine semantics to `PineEngine`, but the
@@ -110,6 +185,7 @@ declare class PineWorkerEngine implements ScriptingEngine {
     private readonly spawn;
     private readonly defaultProps;
     private readonly propsVisibility;
+    private readonly footprints;
     private readonly prepares;
     private readonly sessions;
     private reqId;
@@ -146,6 +222,12 @@ declare class PineWorkerEngine implements ScriptingEngine {
      * cache-backed gateway (same provider, neutral by (symbol, timeframe)).
      */
     private serveFetch;
+    /**
+     * Answer a worker's footprint request from the engine's `footprints` option. The
+     * worker only asks when `execute` flagged a source, so a missing one here is a
+     * host bug — answer empty rather than hang the script's await.
+     */
+    private serveFootprints;
 }
 
-export { PineEngine, type PineEngineOptions, PineWorkerEngine, type PineWorkerOptions, type PropsFilter, type PropsVisibility };
+export { type FootprintBar, type FootprintLevel, type FootprintRange, type FootprintSource, PineEngine, type PineEngineOptions, PineWorkerEngine, type PineWorkerOptions, type PropsFilter, type PropsVisibility };