@fullstackcraftllc/floe 0.0.1

package/dist/index.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * @fullstackcraftllc/floe - Options Analytics Library
+ *
+ * A comprehensive TypeScript library for options pricing, Greeks calculation,
+ * and dealer exposure analysis across multiple brokers.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOptionChain = exports.getAdapter = exports.brokerAdapters = exports.tdaAdapter = exports.ibkrAdapter = exports.schwabAdapter = exports.genericAdapter = exports.normalPDF = exports.cumulativeNormalDistribution = exports.calculateSharesNeededToCover = exports.calculateGammaVannaCharmExposures = exports.smoothTotalVarianceSmile = exports.getIVForStrike = exports.getIVSurfaces = exports.getTimeToExpirationInYears = exports.getMillisecondsToExpiration = exports.calculateImpliedVolatility = exports.calculateGreeks = exports.blackScholes = void 0;
+// Core types
+__exportStar(require("./types"), exports);
+// Black-Scholes pricing and Greeks
+var blackscholes_1 = require("./blackscholes");
+Object.defineProperty(exports, "blackScholes", { enumerable: true, get: function () { return blackscholes_1.blackScholes; } });
+Object.defineProperty(exports, "calculateGreeks", { enumerable: true, get: function () { return blackscholes_1.calculateGreeks; } });
+Object.defineProperty(exports, "calculateImpliedVolatility", { enumerable: true, get: function () { return blackscholes_1.calculateImpliedVolatility; } });
+Object.defineProperty(exports, "getMillisecondsToExpiration", { enumerable: true, get: function () { return blackscholes_1.getMillisecondsToExpiration; } });
+Object.defineProperty(exports, "getTimeToExpirationInYears", { enumerable: true, get: function () { return blackscholes_1.getTimeToExpirationInYears; } });
+// Volatility surface construction
+var volatility_1 = require("./volatility");
+Object.defineProperty(exports, "getIVSurfaces", { enumerable: true, get: function () { return volatility_1.getIVSurfaces; } });
+Object.defineProperty(exports, "getIVForStrike", { enumerable: true, get: function () { return volatility_1.getIVForStrike; } });
+// Smoothing algorithms
+var smoothing_1 = require("./volatility/smoothing");
+Object.defineProperty(exports, "smoothTotalVarianceSmile", { enumerable: true, get: function () { return smoothing_1.smoothTotalVarianceSmile; } });
+// Exposure calculations
+var exposure_1 = require("./exposure");
+Object.defineProperty(exports, "calculateGammaVannaCharmExposures", { enumerable: true, get: function () { return exposure_1.calculateGammaVannaCharmExposures; } });
+Object.defineProperty(exports, "calculateSharesNeededToCover", { enumerable: true, get: function () { return exposure_1.calculateSharesNeededToCover; } });
+// Statistical utilities
+var statistics_1 = require("./utils/statistics");
+Object.defineProperty(exports, "cumulativeNormalDistribution", { enumerable: true, get: function () { return statistics_1.cumulativeNormalDistribution; } });
+Object.defineProperty(exports, "normalPDF", { enumerable: true, get: function () { return statistics_1.normalPDF; } });
+// Broker adapters
+var adapters_1 = require("./adapters");
+Object.defineProperty(exports, "genericAdapter", { enumerable: true, get: function () { return adapters_1.genericAdapter; } });
+Object.defineProperty(exports, "schwabAdapter", { enumerable: true, get: function () { return adapters_1.schwabAdapter; } });
+Object.defineProperty(exports, "ibkrAdapter", { enumerable: true, get: function () { return adapters_1.ibkrAdapter; } });
+Object.defineProperty(exports, "tdaAdapter", { enumerable: true, get: function () { return adapters_1.tdaAdapter; } });
+Object.defineProperty(exports, "brokerAdapters", { enumerable: true, get: function () { return adapters_1.brokerAdapters; } });
+Object.defineProperty(exports, "getAdapter", { enumerable: true, get: function () { return adapters_1.getAdapter; } });
+Object.defineProperty(exports, "createOptionChain", { enumerable: true, get: function () { return adapters_1.createOptionChain; } });

package/dist/types/index.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Core types for options analytics
+ */
+/**
+ * Option type (call or put)
+ */
+export type OptionType = 'call' | 'put';
+/**
+ * Volatility calculation method
+ */
+export type VolatilityModel = 'blackscholes' | 'svm' | 'garch';
+/**
+ * Smoothing method for IV surface
+ */
+export type SmoothingModel = 'totalvariance' | 'none';
+/**
+ * Parameters for Black-Scholes calculation
+ */
+export interface BlackScholesParams {
+    /** Current price of the underlying asset */
+    spot: number;
+    /** Strike price of the option */
+    strike: number;
+    /** Time to expiration in years */
+    timeToExpiry: number;
+    /** Implied volatility (annualized, as decimal e.g., 0.20 for 20%) */
+    volatility: number;
+    /** Risk-free interest rate (annualized, as decimal) */
+    riskFreeRate: number;
+    /** Option type */
+    optionType: OptionType;
+    /** Dividend yield (annualized, as decimal) */
+    dividendYield?: number;
+}
+/**
+ * Complete set of option Greeks and higher-order Greeks
+ */
+export interface Greeks {
+    /** Price: Option theoretical value */
+    price: number;
+    /** Delta: Rate of change of option price with respect to underlying price */
+    delta: number;
+    /** Gamma: Rate of change of delta with respect to underlying price */
+    gamma: number;
+    /** Theta: Rate of change of option price with respect to time (per day) */
+    theta: number;
+    /** Vega: Rate of change of option price with respect to volatility (per 1% change) */
+    vega: number;
+    /** Rho: Rate of change of option price with respect to interest rate (per 1% change) */
+    rho: number;
+    /** Charm: Rate of change of delta with respect to time (per day) */
+    charm: number;
+    /** Vanna: Rate of change of delta with respect to volatility */
+    vanna: number;
+    /** Volga (Vomma): Rate of change of vega with respect to volatility */
+    volga: number;
+    /** Speed: Rate of change of gamma with respect to underlying price */
+    speed: number;
+    /** Zomma: Rate of change of gamma with respect to volatility */
+    zomma: number;
+    /** Color: Rate of change of gamma with respect to time */
+    color: number;
+    /** Ultima: Rate of change of volga with respect to volatility */
+    ultima: number;
+}
+/**
+ * Normalized option data structure (broker-agnostic)
+ */
+export interface NormalizedOption {
+    /** Strike price */
+    strike: number;
+    /** Expiration date (ISO 8601) */
+    expiration: string;
+    /** Expiration timestamp in milliseconds */
+    expirationTimestamp: number;
+    /** Option type */
+    optionType: OptionType;
+    /** Current bid price */
+    bid: number;
+    /** Current ask price */
+    ask: number;
+    /** Mark (mid) price */
+    mark: number;
+    /** Last traded price */
+    last: number;
+    /** Trading volume */
+    volume: number;
+    /** Open interest */
+    openInterest: number;
+    /** Implied volatility (as decimal) */
+    impliedVolatility: number;
+    /** Pre-calculated Greeks (optional) */
+    greeks?: Greeks;
+}
+/**
+ * Complete option chain with market context
+ */
+export interface OptionChain {
+    /** Underlying symbol */
+    symbol: string;
+    /** Current spot price of the underlying */
+    spot: number;
+    /** Risk-free interest rate (as decimal, e.g., 0.05 for 5%) */
+    riskFreeRate: number;
+    /** Dividend yield (as decimal, e.g., 0.02 for 2%) */
+    dividendYield: number;
+    /** All options in the chain */
+    options: NormalizedOption[];
+}
+/**
+ * IV Surface for a single expiration and option type
+ */
+export interface IVSurface {
+    /** Expiration timestamp in milliseconds */
+    expirationDate: number;
+    /** Option type (CALL or PUT) */
+    putCall: OptionType;
+    /** Sorted strike prices */
+    strikes: number[];
+    /** Raw calculated IVs (as percentages) */
+    rawIVs: number[];
+    /** Smoothed IVs after applying smoothing algorithm (as percentages) */
+    smoothedIVs: number[];
+}
+/**
+ * Strike-level exposure metrics
+ */
+export interface StrikeExposure {
+    /** Strike price */
+    strikePrice: number;
+    /** Gamma exposure at this strike */
+    gammaExposure: number;
+    /** Vanna exposure at this strike */
+    vannaExposure: number;
+    /** Charm exposure at this strike */
+    charmExposure: number;
+    /** Net exposure (gamma + vanna + charm) */
+    netExposure: number;
+}
+/**
+ * Exposure metrics per expiration
+ */
+export interface ExposurePerExpiry {
+    /** Current spot price */
+    spotPrice: number;
+    /** Expiration timestamp in milliseconds */
+    expiration: number;
+    /** Total gamma exposure for this expiration */
+    totalGammaExposure: number;
+    /** Total vanna exposure for this expiration */
+    totalVannaExposure: number;
+    /** Total charm exposure for this expiration */
+    totalCharmExposure: number;
+    /** Total net exposure (sum of all three) */
+    totalNetExposure: number;
+    /** Strike with maximum gamma */
+    strikeOfMaxGamma: number;
+    /** Strike with minimum gamma */
+    strikeOfMinGamma: number;
+    /** Strike with maximum vanna */
+    strikeOfMaxVanna: number;
+    /** Strike with minimum vanna */
+    strikeOfMinVanna: number;
+    /** Strike with maximum charm */
+    strikeOfMaxCharm: number;
+    /** Strike with minimum charm */
+    strikeOfMinCharm: number;
+    /** Strike with maximum net exposure */
+    strikeOfMaxNet: number;
+    /** Strike with minimum net exposure */
+    strikeOfMinNet: number;
+    /** Per-strike exposures */
+    strikeExposures: StrikeExposure[];
+}
+/**
+ * Dealer Gamma Exposure (GEX) metrics
+ */
+export interface GEXMetrics {
+    /** Total gamma exposure by strike */
+    byStrike: Map<number, number>;
+    /** Net gamma exposure */
+    netGamma: number;
+    /** Largest positive gamma strike */
+    maxPositiveStrike: number;
+    /** Largest negative gamma strike */
+    maxNegativeStrike: number;
+    /** Zero gamma level (flip point) */
+    zeroGammaLevel: number | null;
+}
+/**
+ * Dealer Vanna Exposure (VEX) metrics
+ */
+export interface VannaMetrics {
+    /** Total vanna exposure by strike */
+    byStrike: Map<number, number>;
+    /** Net vanna exposure */
+    netVanna: number;
+}
+/**
+ * Dealer Charm Exposure (CEX) metrics
+ */
+export interface CharmMetrics {
+    /** Total charm exposure by strike */
+    byStrike: Map<number, number>;
+    /** Net charm exposure */
+    netCharm: number;
+}
+/**
+ * Broker-specific data types
+ */
+/**
+ * Raw option data from any broker (to be normalized)
+ */
+export interface RawOptionData {
+    [key: string]: any;
+}
+/**
+ * Adapter function type for normalizing broker data
+ */
+export type BrokerAdapter = (data: RawOptionData) => NormalizedOption;
+/**
+ * Constants
+ */
+export declare const MILLISECONDS_PER_YEAR = 31536000000;
+export declare const MILLISECONDS_PER_DAY = 86400000;
+export declare const MINUTES_PER_YEAR = 525600;
+export declare const MINUTES_PER_DAY = 1440;
+export declare const DAYS_PER_YEAR = 365;

package/dist/types/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Core types for options analytics
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DAYS_PER_YEAR = exports.MINUTES_PER_DAY = exports.MINUTES_PER_YEAR = exports.MILLISECONDS_PER_DAY = exports.MILLISECONDS_PER_YEAR = void 0;
+/**
+ * Constants
+ */
+exports.MILLISECONDS_PER_YEAR = 31536000000;
+exports.MILLISECONDS_PER_DAY = 86400000;
+exports.MINUTES_PER_YEAR = 525600;
+exports.MINUTES_PER_DAY = 1440;
+exports.DAYS_PER_YEAR = 365;

package/dist/utils/statistics.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Statistical utility functions
+ */
+/**
+ * Cumulative distribution function for standard normal distribution
+ * Using an approximation method (Abramowitz and Stegun)
+ *
+ * @param x - Input value
+ * @returns Cumulative probability
+ */
+export declare function cumulativeNormalDistribution(x: number): number;
+/**
+ * Probability density function for standard normal distribution
+ *
+ * @param x - Input value
+ * @returns Probability density
+ */
+export declare function normalPDF(x: number): number;

package/dist/utils/statistics.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Statistical utility functions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cumulativeNormalDistribution = cumulativeNormalDistribution;
+exports.normalPDF = normalPDF;
+/**
+ * Cumulative distribution function for standard normal distribution
+ * Using an approximation method (Abramowitz and Stegun)
+ *
+ * @param x - Input value
+ * @returns Cumulative probability
+ */
+function cumulativeNormalDistribution(x) {
+    const t = 1 / (1 + 0.2316419 * Math.abs(x));
+    const d = 0.3989423 * Math.exp((-x * x) / 2);
+    const probability = d *
+        t *
+        (0.3193815 +
+            t * (-0.3565638 + t * (1.781478 + t * (-1.821256 + t * 1.330274))));
+    return x > 0 ? 1 - probability : probability;
+}
+/**
+ * Probability density function for standard normal distribution
+ *
+ * @param x - Input value
+ * @returns Probability density
+ */
+function normalPDF(x) {
+    return Math.exp((-x * x) / 2) / Math.sqrt(2 * Math.PI);
+}

package/dist/volatility/index.d.ts

@@ -0,0 +1,37 @@
+import { OptionChain, IVSurface, VolatilityModel, SmoothingModel } from '../types';
+/**
+ * Build IV surfaces for all expirations in an option chain
+ *
+ * @param volatilityModel - Method to calculate IV
+ *   - 'blackscholes': Use Black-Scholes IV inversion (implemented) ✅
+ *   - 'svm': TODO - Support Vector Machine based IV estimation
+ *   - 'garch': TODO - GARCH model for volatility forecasting
+ * @param smoothingModel - Smoothing method to apply
+ *   - 'totalvariance': Cubic spline + convex hull (implemented) ✅
+ *   - 'none': No smoothing, use raw IVs ✅
+ *   - TODO: Future - 'svi', 'ssvi', 'sabr' parametric models
+ * @param chain - Option chain with market context (spot, rates, options)
+ * @returns Array of IV surfaces (one per expiration per option type)
+ *
+ * @example
+ * ```typescript
+ * const surfaces = getIVSurfaces('blackscholes', 'totalvariance', chain);
+ * ```
+ */
+export declare function getIVSurfaces(volatilityModel: VolatilityModel, smoothingModel: SmoothingModel, chain: OptionChain): IVSurface[];
+/**
+ * Get smoothed IV for a specific expiration, option type, and strike
+ *
+ * @param ivSurfaces - Array of IV surfaces
+ * @param expiration - Expiration timestamp in milliseconds
+ * @param optionType - 'call' or 'put'
+ * @param strike - Strike price
+ * @returns Smoothed IV as a percentage, or 0 if not found
+ *
+ * @example
+ * ```typescript
+ * const iv = getIVForStrike(surfaces, 1234567890000, 'call', 105);
+ * console.log(`IV: ${iv}%`);
+ * ```
+ */
+export declare function getIVForStrike(ivSurfaces: IVSurface[], expiration: number, optionType: 'call' | 'put', strike: number): number;

package/dist/volatility/index.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getIVSurfaces = getIVSurfaces;
+exports.getIVForStrike = getIVForStrike;
+const types_1 = require("../types");
+const blackscholes_1 = require("../blackscholes");
+const smoothing_1 = require("./smoothing");
+/**
+ * Build IV surfaces for all expirations in an option chain
+ *
+ * @param volatilityModel - Method to calculate IV
+ *   - 'blackscholes': Use Black-Scholes IV inversion (implemented) ✅
+ *   - 'svm': TODO - Support Vector Machine based IV estimation
+ *   - 'garch': TODO - GARCH model for volatility forecasting
+ * @param smoothingModel - Smoothing method to apply
+ *   - 'totalvariance': Cubic spline + convex hull (implemented) ✅
+ *   - 'none': No smoothing, use raw IVs ✅
+ *   - TODO: Future - 'svi', 'ssvi', 'sabr' parametric models
+ * @param chain - Option chain with market context (spot, rates, options)
+ * @returns Array of IV surfaces (one per expiration per option type)
+ *
+ * @example
+ * ```typescript
+ * const surfaces = getIVSurfaces('blackscholes', 'totalvariance', chain);
+ * ```
+ */
+function getIVSurfaces(volatilityModel, smoothingModel, chain) {
+    const { spot, riskFreeRate, dividendYield, options } = chain;
+    const ivSurfaces = [];
+    // Get all unique expirations from options
+    const expirationsSet = new Set();
+    for (const option of options) {
+        expirationsSet.add(option.expirationTimestamp);
+    }
+    const expirations = Array.from(expirationsSet).sort((a, b) => a - b);
+    // Loop through all expirations
+    for (const expiration of expirations) {
+        // Separate CALL and PUT surfaces for this expiration
+        const callStrikes = [];
+        const callIVs = [];
+        const putStrikes = [];
+        const putIVs = [];
+        // Loop through options to find those that match the expiration
+        for (const option of options) {
+            if (option.expirationTimestamp !== expiration) {
+                continue;
+            }
+            // Compute IV using selected model
+            if (volatilityModel === 'blackscholes') {
+                const timeToExpirationInYears = (0, blackscholes_1.getTimeToExpirationInYears)(option.expirationTimestamp);
+                const isCall = option.optionType === 'call';
+                // Rates are already decimals in OptionChain
+                const iv = (0, blackscholes_1.calculateImpliedVolatility)(option.mark, spot, option.strike, riskFreeRate, dividendYield, timeToExpirationInYears, option.optionType);
+                if (isCall) {
+                    callStrikes.push(option.strike);
+                    callIVs.push(iv);
+                }
+                else {
+                    putStrikes.push(option.strike);
+                    putIVs.push(iv);
+                }
+            }
+            // TODO: Implement 'svm' model
+            // else if (volatilityModel === 'svm') {
+            //   // Support Vector Machine based IV estimation
+            //   // Could use historical data patterns to predict IV
+            // }
+            // TODO: Implement 'garch' model
+            // else if (volatilityModel === 'garch') {
+            //   // GARCH model for volatility forecasting
+            //   // Time series approach for IV prediction
+            // }
+        }
+        // Helper to sort and append surface
+        const appendSurface = (strikes, ivs, optionType) => {
+            if (strikes.length === 0) {
+                return;
+            }
+            // Sort by strike
+            const pairs = strikes.map((strike, i) => ({ strike, iv: ivs[i] }));
+            pairs.sort((a, b) => a.strike - b.strike);
+            const sortedStrikes = pairs.map((p) => p.strike);
+            const rawIVs = pairs.map((p) => p.iv);
+            // Default: no smoothing, smoothedIVs = copy of rawIVs
+            let smoothedIVs = [...rawIVs];
+            // Only smooth if we have enough valid data points (IV > 1.5% floor)
+            // Filter out floor values before smoothing to avoid contamination
+            if (smoothingModel === 'totalvariance' && expiration > Date.now()) {
+                const IV_FLOOR = 1.5; // IVs at or below this are considered unreliable (deep ITM/OTM)
+                // Find the range of valid IVs
+                const validData = [];
+                for (let i = 0; i < rawIVs.length; i++) {
+                    if (rawIVs[i] > IV_FLOOR) {
+                        validData.push({
+                            strike: sortedStrikes[i],
+                            iv: rawIVs[i],
+                            index: i,
+                        });
+                    }
+                }
+                // Only smooth if we have at least 5 valid points
+                if (validData.length >= 5) {
+                    const validStrikes = validData.map((d) => d.strike);
+                    const validIVs = validData.map((d) => d.iv);
+                    const T = (expiration - Date.now()) / types_1.MILLISECONDS_PER_YEAR;
+                    const smoothedValidIVs = (0, smoothing_1.smoothTotalVarianceSmile)(validStrikes, validIVs, T);
+                    // Copy smoothed values back to corresponding indices
+                    smoothedIVs = [...rawIVs]; // Start with raw IVs
+                    for (let j = 0; j < validData.length; j++) {
+                        smoothedIVs[validData[j].index] = smoothedValidIVs[j];
+                    }
+                }
+            }
+            // TODO: Future smoothing models
+            // else if (smoothingModel === 'svi') {
+            //   // Stochastic Volatility Inspired parametric model
+            // }
+            // else if (smoothingModel === 'ssvi') {
+            //   // Surface SVI for multiple expirations
+            // }
+            const ivSurface = {
+                expirationDate: expiration,
+                putCall: optionType,
+                strikes: sortedStrikes,
+                rawIVs,
+                smoothedIVs,
+            };
+            ivSurfaces.push(ivSurface);
+        };
+        // Append call and put surfaces if present
+        appendSurface(callStrikes, callIVs, 'call');
+        appendSurface(putStrikes, putIVs, 'put');
+    }
+    return ivSurfaces;
+}
+/**
+ * Get smoothed IV for a specific expiration, option type, and strike
+ *
+ * @param ivSurfaces - Array of IV surfaces
+ * @param expiration - Expiration timestamp in milliseconds
+ * @param optionType - 'call' or 'put'
+ * @param strike - Strike price
+ * @returns Smoothed IV as a percentage, or 0 if not found
+ *
+ * @example
+ * ```typescript
+ * const iv = getIVForStrike(surfaces, 1234567890000, 'call', 105);
+ * console.log(`IV: ${iv}%`);
+ * ```
+ */
+function getIVForStrike(ivSurfaces, expiration, optionType, strike) {
+    for (const ivSurface of ivSurfaces) {
+        if (ivSurface.expirationDate === expiration && ivSurface.putCall === optionType) {
+            // Find the strike in the strikes array
+            for (let i = 0; i < ivSurface.strikes.length; i++) {
+                if (ivSurface.strikes[i] === strike) {
+                    return ivSurface.smoothedIVs[i];
+                }
+            }
+        }
+    }
+    return 0.0;
+}

package/dist/volatility/smoothing.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Volatility surface smoothing algorithms
+ */
+/**
+ * Smooth total variance smile using cubic spline interpolation and convexity enforcement
+ *
+ * @param strikes - Sorted array of strike prices
+ * @param ivs - Array of IVs as percentages (e.g., 20 = 20%)
+ * @param T - Time to expiration in years
+ * @returns Smoothed IVs as percentages
+ *
+ * @example
+ * ```typescript
+ * const smoothed = smoothTotalVarianceSmile([90, 95, 100, 105, 110], [22, 20, 18, 20, 22], 0.25);
+ * ```
+ */
+export declare function smoothTotalVarianceSmile(strikes: number[], ivs: number[], T: number): number[];