@fullstackcraftllc/floe 0.0.15 → 0.0.16

package/dist/exposure/index.d.ts

@@ -1,17 +1,22 @@
-import { OptionChain, ExposurePerExpiry, IVSurface } from '../types';
+import { OptionChain, ExposureVariantsPerExpiry, ExposureCalculationOptions, IVSurface } from '../types';
 /**
- * Calculate Gamma, Vanna, and Charm exposures for an option chain
+ * Calculate canonical, state-weighted, and flow-delta exposure variants.
  *
- * @param chain - Option chain with market context (spot, rates, options)
- * @param ivSurfaces - IV surfaces for all expirations
- * @returns Array of exposure metrics per expiration
+ * canonical:
+ * - GEX: dollars per 1% underlying move
+ * - VEX: dollars per 1 vol-point move
+ * - CEX: dollars per 1 day of time decay
  *
- * @example
- * ```typescript
- * const exposures = calculateGammaVannaCharmExposures(chain, ivSurfaces);
- * ```
+ * stateWeighted:
+ * - Gamma: same as canonical (spot is already the state variable)
+ * - Vanna: canonical vanna weighted by strike IV level
+ * - Charm: canonical charm weighted by days-to-expiration
+ *
+ * flowDelta:
+ * - Canonical exposure formulas using OI deltas:
+ *   (liveOpenInterest - openInterest)
  */
-export declare function calculateGammaVannaCharmExposures(chain: OptionChain, ivSurfaces: IVSurface[]): ExposurePerExpiry[];
+export declare function calculateGammaVannaCharmExposures(chain: OptionChain, ivSurfaces: IVSurface[], options?: ExposureCalculationOptions): ExposureVariantsPerExpiry[];
 /**
  * Calculate shares needed to cover net exposure
  *

package/dist/exposure/index.js

@@ -6,70 +6,62 @@ const types_1 = require("../types");
 const blackscholes_1 = require("../blackscholes");
 const volatility_1 = require("../volatility");
 /**
- * Calculate Gamma, Vanna, and Charm exposures for an option chain
+ * Calculate canonical, state-weighted, and flow-delta exposure variants.
  *
- * @param chain - Option chain with market context (spot, rates, options)
- * @param ivSurfaces - IV surfaces for all expirations
- * @returns Array of exposure metrics per expiration
+ * canonical:
+ * - GEX: dollars per 1% underlying move
+ * - VEX: dollars per 1 vol-point move
+ * - CEX: dollars per 1 day of time decay
  *
- * @example
- * ```typescript
- * const exposures = calculateGammaVannaCharmExposures(chain, ivSurfaces);
- * ```
+ * stateWeighted:
+ * - Gamma: same as canonical (spot is already the state variable)
+ * - Vanna: canonical vanna weighted by strike IV level
+ * - Charm: canonical charm weighted by days-to-expiration
+ *
+ * flowDelta:
+ * - Canonical exposure formulas using OI deltas:
+ *   (liveOpenInterest - openInterest)
  */
-function calculateGammaVannaCharmExposures(chain, ivSurfaces) {
-    const { spot, riskFreeRate, dividendYield, options } = chain;
+function calculateGammaVannaCharmExposures(chain, ivSurfaces, options = {}) {
+    const { spot, riskFreeRate, dividendYield, options: chainOptions } = chain;
+    const asOfTimestamp = options.asOfTimestamp ?? Date.now();
     const exposureRows = [];
-    // Get unique expirations from options
     const expirationsSet = new Set();
-    for (const option of options) {
+    for (const option of chainOptions) {
         expirationsSet.add(option.expirationTimestamp);
     }
     const expirations = Array.from(expirationsSet).sort((a, b) => a - b);
-    // Loop through all expirations
+    const putOptionsByKey = new Map();
+    for (const option of chainOptions) {
+        if (option.optionType === 'put') {
+            putOptionsByKey.set(getOptionKey(option.expirationTimestamp, option.strike), option);
+        }
+    }
     for (const expiration of expirations) {
-        // Skip any expiration that is in the past
-        if (expiration < Date.now()) {
+        if (expiration < asOfTimestamp) {
+            continue;
+        }
+        const timeToExpirationInYears = (expiration - asOfTimestamp) / types_1.MILLISECONDS_PER_YEAR;
+        if (timeToExpirationInYears <= 0) {
             continue;
         }
-        // Reset totals for this expiration
-        let totalGammaExposure = 0.0;
-        let totalVannaExposure = 0.0;
-        let totalCharmExposure = 0.0;
-        let strikeOfMaxGamma = 0.0;
-        let strikeOfMinGamma = 0.0;
-        let strikeOfMaxVanna = 0.0;
-        let strikeOfMinVanna = 0.0;
-        let strikeOfMaxCharm = 0.0;
-        let strikeOfMinCharm = 0.0;
-        let strikeOfMaxNet = 0.0;
-        let strikeOfMinNet = 0.0;
-        const strikeExposures = [];
-        // Process all call options first
-        for (const callOption of options) {
-            // Check if this option is at the expiration we are looking at
-            if (callOption.expirationTimestamp !== expiration || callOption.optionType === 'put') {
+        const timeToExpirationInDays = Math.max(timeToExpirationInYears * types_1.DAYS_PER_YEAR, 0);
+        const strikeExposureVariants = [];
+        for (const callOption of chainOptions) {
+            if (callOption.expirationTimestamp !== expiration || callOption.optionType !== 'call') {
                 continue;
             }
-            // Get the corresponding put option
-            const putOption = options.find((opt) => opt.expirationTimestamp === expiration &&
-                opt.optionType === 'put' &&
-                opt.strike === callOption.strike);
+            const putOption = putOptionsByKey.get(getOptionKey(expiration, callOption.strike));
             if (!putOption) {
-                continue; // Skip if no matching put
+                continue;
             }
-            // Get IV for this strike and expiry from the surface
-            const callIVAtStrike = (0, volatility_1.getIVForStrike)(ivSurfaces, expiration, 'call', callOption.strike);
-            const putIVAtStrike = (0, volatility_1.getIVForStrike)(ivSurfaces, expiration, 'put', putOption.strike);
-            // Get time to expiration in years
-            const timeToExpirationInYears = (0, blackscholes_1.getTimeToExpirationInYears)(expiration);
-            // Calculate Greeks for both call and put
-            // Rates are already decimals in OptionChain, IV from surface is percentage
+            const callIVAtStrike = resolveIVPercent((0, volatility_1.getIVForStrike)(ivSurfaces, expiration, 'call', callOption.strike), callOption.impliedVolatility);
+            const putIVAtStrike = resolveIVPercent((0, volatility_1.getIVForStrike)(ivSurfaces, expiration, 'put', putOption.strike), putOption.impliedVolatility);
             const callGreeks = (0, blackscholes_1.calculateGreeks)({
                 spot,
                 strike: callOption.strike,
                 timeToExpiry: timeToExpirationInYears,
-                volatility: callIVAtStrike / 100.0, // Convert from percentage to decimal
+                volatility: callIVAtStrike / 100.0,
                 riskFreeRate,
                 dividendYield,
                 optionType: 'call',
@@ -83,74 +75,33 @@ function calculateGammaVannaCharmExposures(chain, ivSurfaces) {
                 dividendYield,
                 optionType: 'put',
             });
-            // Calculate exposures from dealer perspective
-            // Dealer is short calls (negative gamma) and long puts (positive gamma)
-            // Multiply by 100 for contract size, multiply by spot for dollar exposure
-            // Multiply by 0.01 for 1% move sensitivity
-            // Gamma: second order with respect to price twice
-            const gammaExposureForStrike = -callOption.openInterest * callGreeks.gamma * (spot * 100.0) * spot * 0.01 +
-                putOption.openInterest * putGreeks.gamma * (spot * 100.0) * spot * 0.01;
-            // Vanna: second order with respect to price and volatility
-            const vannaExposureForStrike = -callOption.openInterest * callGreeks.vanna * (spot * 100.0) * callIVAtStrike * 0.01 +
-                putOption.openInterest * putGreeks.vanna * (spot * 100.0) * putIVAtStrike * 0.01;
-            // Charm: second order with respect to price and time
-            // Already normalized per day in calculateGreeks
-            const charmExposureForStrike = -callOption.openInterest * callGreeks.charm * (spot * 100.0) * types_1.DAYS_PER_YEAR * timeToExpirationInYears +
-                putOption.openInterest * putGreeks.charm * (spot * 100.0) * types_1.DAYS_PER_YEAR * timeToExpirationInYears;
-            // NaN checks
-            const gammaExposure = isNaN(gammaExposureForStrike) ? 0.0 : gammaExposureForStrike;
-            const vannaExposure = isNaN(vannaExposureForStrike) ? 0.0 : vannaExposureForStrike;
-            const charmExposure = isNaN(charmExposureForStrike) ? 0.0 : charmExposureForStrike;
-            // Add to totals
-            totalGammaExposure += gammaExposure;
-            totalVannaExposure += vannaExposure;
-            totalCharmExposure += charmExposure;
-            // Add to strike exposures
-            strikeExposures.push({
+            const callOpenInterest = sanitizeFinite(callOption.openInterest);
+            const putOpenInterest = sanitizeFinite(putOption.openInterest);
+            const canonical = calculateCanonicalVector(spot, callOpenInterest, putOpenInterest, callGreeks.gamma, putGreeks.gamma, callGreeks.vanna, putGreeks.vanna, callGreeks.charm, putGreeks.charm);
+            const stateWeighted = calculateStateWeightedVector(spot, callOpenInterest, putOpenInterest, callGreeks.vanna, putGreeks.vanna, callGreeks.charm, putGreeks.charm, callIVAtStrike, putIVAtStrike, timeToExpirationInDays, canonical.gammaExposure);
+            const callFlowDelta = resolveFlowDeltaOpenInterest(callOption.openInterest, callOption.liveOpenInterest);
+            const putFlowDelta = resolveFlowDeltaOpenInterest(putOption.openInterest, putOption.liveOpenInterest);
+            const flowDelta = calculateCanonicalVector(spot, callFlowDelta, putFlowDelta, callGreeks.gamma, putGreeks.gamma, callGreeks.vanna, putGreeks.vanna, callGreeks.charm, putGreeks.charm);
+            strikeExposureVariants.push({
                 strikePrice: callOption.strike,
-                gammaExposure,
-                vannaExposure,
-                charmExposure,
-                netExposure: gammaExposure + vannaExposure + charmExposure,
+                canonical,
+                stateWeighted,
+                flowDelta,
             });
         }
-        if (strikeExposures.length === 0) {
-            continue; // No options for this expiration
+        if (strikeExposureVariants.length === 0) {
+            continue;
         }
-        // Sort by gamma exposure and find extremes
-        strikeExposures.sort((a, b) => b.gammaExposure - a.gammaExposure);
-        strikeOfMaxGamma = strikeExposures[0].strikePrice;
-        strikeOfMinGamma = strikeExposures[strikeExposures.length - 1].strikePrice;
-        // Sort by vanna exposure and find extremes
-        strikeExposures.sort((a, b) => b.vannaExposure - a.vannaExposure);
-        strikeOfMaxVanna = strikeExposures[0].strikePrice;
-        strikeOfMinVanna = strikeExposures[strikeExposures.length - 1].strikePrice;
-        // Sort by charm exposure and find extremes
-        strikeExposures.sort((a, b) => b.charmExposure - a.charmExposure);
-        strikeOfMaxCharm = strikeExposures[0].strikePrice;
-        strikeOfMinCharm = strikeExposures[strikeExposures.length - 1].strikePrice;
-        // Sort by net exposure and find extremes
-        strikeExposures.sort((a, b) => b.netExposure - a.netExposure);
-        strikeOfMaxNet = strikeExposures[0].strikePrice;
-        strikeOfMinNet = strikeExposures[strikeExposures.length - 1].strikePrice;
-        const totalNetExposure = totalGammaExposure + totalVannaExposure + totalCharmExposure;
-        // Add exposure row
+        const canonical = buildModeBreakdown(strikeExposureVariants, 'canonical');
+        const stateWeighted = buildModeBreakdown(strikeExposureVariants, 'stateWeighted');
+        const flowDelta = buildModeBreakdown(strikeExposureVariants, 'flowDelta');
         exposureRows.push({
             spotPrice: spot,
             expiration,
-            totalGammaExposure,
-            totalVannaExposure,
-            totalCharmExposure,
-            totalNetExposure,
-            strikeOfMaxGamma,
-            strikeOfMinGamma,
-            strikeOfMaxVanna,
-            strikeOfMinVanna,
-            strikeOfMaxCharm,
-            strikeOfMinCharm,
-            strikeOfMaxNet,
-            strikeOfMinNet,
-            strikeExposures
+            canonical,
+            stateWeighted,
+            flowDelta,
+            strikeExposureVariants,
         });
     }
     return exposureRows;
@@ -210,3 +161,110 @@ function calculateSharesNeededToCover(sharesOutstanding, totalNetExposure, under
         resultingSpotToCover: resultingPrice,
     };
 }
+function getOptionKey(expiration, strike) {
+    return `${expiration}:${strike}`;
+}
+function calculateCanonicalVector(spot, callPosition, putPosition, callGamma, putGamma, callVanna, putVanna, callCharm, putCharm) {
+    const gammaExposure = -callPosition * callGamma * (spot * 100.0) * spot * 0.01 +
+        putPosition * putGamma * (spot * 100.0) * spot * 0.01;
+    const vannaExposure = -callPosition * callVanna * (spot * 100.0) * 0.01 +
+        putPosition * putVanna * (spot * 100.0) * 0.01;
+    const charmExposure = -callPosition * callCharm * (spot * 100.0) +
+        putPosition * putCharm * (spot * 100.0);
+    return sanitizeVector({
+        gammaExposure,
+        vannaExposure,
+        charmExposure,
+        netExposure: gammaExposure + vannaExposure + charmExposure,
+    });
+}
+function calculateStateWeightedVector(spot, callPosition, putPosition, callVanna, putVanna, callCharm, putCharm, callIVPercent, putIVPercent, timeToExpirationInDays, canonicalGammaExposure) {
+    const callIVLevel = Math.max(callIVPercent * 0.01, 0);
+    const putIVLevel = Math.max(putIVPercent * 0.01, 0);
+    // Gamma already uses instantaneous price scaling in canonical GEX.
+    const gammaExposure = canonicalGammaExposure;
+    const vannaExposure = -callPosition * callVanna * (spot * 100.0) * 0.01 * callIVLevel +
+        putPosition * putVanna * (spot * 100.0) * 0.01 * putIVLevel;
+    const canonicalCharmComponent = -callPosition * callCharm * (spot * 100.0) +
+        putPosition * putCharm * (spot * 100.0);
+    const charmExposure = canonicalCharmComponent * Math.max(timeToExpirationInDays, 0);
+    return sanitizeVector({
+        gammaExposure,
+        vannaExposure,
+        charmExposure,
+        netExposure: gammaExposure + vannaExposure + charmExposure,
+    });
+}
+function resolveFlowDeltaOpenInterest(openInterest, liveOpenInterest) {
+    if (typeof liveOpenInterest !== 'number' || !isFinite(liveOpenInterest)) {
+        return 0;
+    }
+    return sanitizeFinite(liveOpenInterest - openInterest);
+}
+function resolveIVPercent(ivFromSurface, optionImpliedVolatilityDecimal) {
+    if (isFinite(ivFromSurface) && ivFromSurface > 0) {
+        return ivFromSurface;
+    }
+    const fallback = optionImpliedVolatilityDecimal * 100.0;
+    if (isFinite(fallback) && fallback > 0) {
+        return fallback;
+    }
+    return 0;
+}
+function buildModeBreakdown(strikeExposureVariants, mode) {
+    const strikeExposures = strikeExposureVariants.map((strike) => ({
+        strikePrice: strike.strikePrice,
+        ...strike[mode],
+    }));
+    if (strikeExposures.length === 0) {
+        return {
+            totalGammaExposure: 0,
+            totalVannaExposure: 0,
+            totalCharmExposure: 0,
+            totalNetExposure: 0,
+            strikeOfMaxGamma: 0,
+            strikeOfMinGamma: 0,
+            strikeOfMaxVanna: 0,
+            strikeOfMinVanna: 0,
+            strikeOfMaxCharm: 0,
+            strikeOfMinCharm: 0,
+            strikeOfMaxNet: 0,
+            strikeOfMinNet: 0,
+            strikeExposures: [],
+        };
+    }
+    const totalGammaExposure = strikeExposures.reduce((sum, s) => sum + s.gammaExposure, 0);
+    const totalVannaExposure = strikeExposures.reduce((sum, s) => sum + s.vannaExposure, 0);
+    const totalCharmExposure = strikeExposures.reduce((sum, s) => sum + s.charmExposure, 0);
+    const totalNetExposure = totalGammaExposure + totalVannaExposure + totalCharmExposure;
+    const byGamma = [...strikeExposures].sort((a, b) => b.gammaExposure - a.gammaExposure);
+    const byVanna = [...strikeExposures].sort((a, b) => b.vannaExposure - a.vannaExposure);
+    const byCharm = [...strikeExposures].sort((a, b) => b.charmExposure - a.charmExposure);
+    const byNet = [...strikeExposures].sort((a, b) => b.netExposure - a.netExposure);
+    return {
+        totalGammaExposure: sanitizeFinite(totalGammaExposure),
+        totalVannaExposure: sanitizeFinite(totalVannaExposure),
+        totalCharmExposure: sanitizeFinite(totalCharmExposure),
+        totalNetExposure: sanitizeFinite(totalNetExposure),
+        strikeOfMaxGamma: byGamma[0].strikePrice,
+        strikeOfMinGamma: byGamma[byGamma.length - 1].strikePrice,
+        strikeOfMaxVanna: byVanna[0].strikePrice,
+        strikeOfMinVanna: byVanna[byVanna.length - 1].strikePrice,
+        strikeOfMaxCharm: byCharm[0].strikePrice,
+        strikeOfMinCharm: byCharm[byCharm.length - 1].strikePrice,
+        strikeOfMaxNet: byNet[0].strikePrice,
+        strikeOfMinNet: byNet[byNet.length - 1].strikePrice,
+        strikeExposures: byNet,
+    };
+}
+function sanitizeVector(vector) {
+    return {
+        gammaExposure: sanitizeFinite(vector.gammaExposure),
+        vannaExposure: sanitizeFinite(vector.vannaExposure),
+        charmExposure: sanitizeFinite(vector.charmExposure),
+        netExposure: sanitizeFinite(vector.netExposure),
+    };
+}
+function sanitizeFinite(value) {
+    return isFinite(value) && !isNaN(value) ? value : 0;
+}

package/dist/impliedpdf/adjusted.d.ts

@@ -114,7 +114,7 @@ export declare const OPEX_CONFIG: ExposureAdjustmentConfig;
  * @param symbol - Underlying ticker symbol
  * @param underlyingPrice - Current spot price
  * @param callOptions - Call options for a single expiry
- * @param exposures - Exposure metrics from calculateGammaVannaCharmExposures()
+ * @param exposures - Canonical exposure metrics from calculateGammaVannaCharmExposures()
  * @param config - Adjustment configuration (uses defaults if not provided)
  * @returns Baseline and adjusted PDFs with comparison metrics
  *
@@ -122,7 +122,10 @@ export declare const OPEX_CONFIG: ExposureAdjustmentConfig;
  * ```typescript
  * // Get exposures first
  * const allExposures = calculateGammaVannaCharmExposures(chain, ivSurfaces);
- * const expiryExposures = allExposures.find(e => e.expiration === targetExpiry);
+ * const expiry = allExposures.find(e => e.expiration === targetExpiry);
+ * const expiryExposures = expiry
+ *   ? { spotPrice: expiry.spotPrice, expiration: expiry.expiration, ...expiry.canonical }
+ *   : undefined;
  *
  * // Calculate adjusted PDF
  * const result = estimateExposureAdjustedPDF(

package/dist/impliedpdf/adjusted.js

@@ -122,7 +122,7 @@ exports.OPEX_CONFIG = {
  * @param symbol - Underlying ticker symbol
  * @param underlyingPrice - Current spot price
  * @param callOptions - Call options for a single expiry
- * @param exposures - Exposure metrics from calculateGammaVannaCharmExposures()
+ * @param exposures - Canonical exposure metrics from calculateGammaVannaCharmExposures()
  * @param config - Adjustment configuration (uses defaults if not provided)
  * @returns Baseline and adjusted PDFs with comparison metrics
  *
@@ -130,7 +130,10 @@ exports.OPEX_CONFIG = {
  * ```typescript
  * // Get exposures first
  * const allExposures = calculateGammaVannaCharmExposures(chain, ivSurfaces);
- * const expiryExposures = allExposures.find(e => e.expiration === targetExpiry);
+ * const expiry = allExposures.find(e => e.expiration === targetExpiry);
+ * const expiryExposures = expiry
+ *   ? { spotPrice: expiry.spotPrice, expiration: expiry.expiration, ...expiry.canonical }
+ *   : undefined;
  *
  * // Calculate adjusted PDF
  * const result = estimateExposureAdjustedPDF(

package/dist/types/index.d.ts

@@ -172,6 +172,52 @@ export interface StrikeExposure {
     /** Net exposure (gamma + vanna + charm) */
     netExposure: number;
 }
+/**
+ * Input options for exposure calculations.
+ */
+export interface ExposureCalculationOptions {
+    /**
+     * Reference timestamp in milliseconds.
+     * If omitted, Date.now() is used.
+     */
+    asOfTimestamp?: number;
+}
+/**
+ * Exposure vector used by variant outputs.
+ */
+export interface ExposureVector {
+    gammaExposure: number;
+    vannaExposure: number;
+    charmExposure: number;
+    netExposure: number;
+}
+/**
+ * Per-strike exposure variants (canonical, state-weighted, and flow delta).
+ */
+export interface StrikeExposureVariants {
+    strikePrice: number;
+    canonical: ExposureVector;
+    stateWeighted: ExposureVector;
+    flowDelta: ExposureVector;
+}
+/**
+ * Full exposure breakdown for one mode.
+ */
+export interface ExposureModeBreakdown {
+    totalGammaExposure: number;
+    totalVannaExposure: number;
+    totalCharmExposure: number;
+    totalNetExposure: number;
+    strikeOfMaxGamma: number;
+    strikeOfMinGamma: number;
+    strikeOfMaxVanna: number;
+    strikeOfMinVanna: number;
+    strikeOfMaxCharm: number;
+    strikeOfMinCharm: number;
+    strikeOfMaxNet: number;
+    strikeOfMinNet: number;
+    strikeExposures: StrikeExposure[];
+}
 /**
  * Exposure metrics per expiration
  */
@@ -207,6 +253,26 @@ export interface ExposurePerExpiry {
     /** Per-strike exposures */
     strikeExposures: StrikeExposure[];
 }
+/**
+ * Exposure variants per expiration.
+ * canonical: classic per-1% / per-vol-point / per-day definitions
+ * stateWeighted: level-weighted vanna/charm (gamma remains canonical)
+ * flowDelta: exposure deltas from intraday OI changes (liveOpenInterest - openInterest)
+ */
+export interface ExposureVariantsPerExpiry {
+    /** Current spot price */
+    spotPrice: number;
+    /** Expiration timestamp in milliseconds */
+    expiration: number;
+    /** Canonical exposure mode */
+    canonical: ExposureModeBreakdown;
+    /** State-weighted exposure mode */
+    stateWeighted: ExposureModeBreakdown;
+    /** Flow-delta exposure mode */
+    flowDelta: ExposureModeBreakdown;
+    /** Per-strike variants */
+    strikeExposureVariants: StrikeExposureVariants[];
+}
 /**
  * Dealer Gamma Exposure (GEX) metrics
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackcraftllc/floe",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "Production-ready options analytics toolkit. Normalize broker data structures and calculate Black-Scholes, Greeks, and exposures with a clean, type-safe API. Built for trading platforms and fintech applications.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",