@fullstackcraftllc/floe 0.0.2 → 0.0.4

package/dist/impliedpdf/index.js

@@ -1 +1,278 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateImpliedProbabilityDistribution = estimateImpliedProbabilityDistribution;
+exports.estimateImpliedProbabilityDistributions = estimateImpliedProbabilityDistributions;
+exports.getProbabilityInRange = getProbabilityInRange;
+exports.getCumulativeProbability = getCumulativeProbability;
+exports.getQuantile = getQuantile;
+/**
+ * Estimate an implied probability density function (PDF) for a single expiry
+ * using Breeden-Litzenberger style numerical differentiation of call prices.
+ *
+ * This method computes the second derivative of call option prices with respect
+ * to strike price, which under risk-neutral pricing gives the probability density
+ * of the underlying ending at each strike.
+ *
+ * @param symbol - Underlying ticker symbol
+ * @param underlyingPrice - Current spot/mark price of the underlying
+ * @param callOptions - Array of call options for a single expiry (must have bid > 0 and ask > 0)
+ * @returns ImpliedProbabilityDistribution with strike-level probabilities and summary statistics
+ *
+ * @example
+ * ```typescript
+ * const result = estimateImpliedProbabilityDistribution(
+ *   'QQQ',
+ *   500.00,
+ *   callOptionsForExpiry
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Mode:', result.distribution.mostLikelyPrice);
+ *   console.log('Expected move:', result.distribution.expectedMove);
+ * }
+ * ```
+ */
+function estimateImpliedProbabilityDistribution(symbol, underlyingPrice, callOptions) {
+    // Sort call options by strike price ascending
+    const sortedOptions = [...callOptions].sort((a, b) => a.strike - b.strike);
+    const n = sortedOptions.length;
+    if (n < 3) {
+        return { success: false, error: 'Not enough data points (need at least 3 call options)' };
+    }
+    // Get expiration from first option (assuming all same expiry)
+    const expiryDate = sortedOptions[0].expirationTimestamp;
+    // Estimate second derivative numerically (central difference)
+    // f(K) ≈ d²C/dK² where C is the call price
+    const strikeProbabilities = new Array(n);
+    // Initialize edge cases with zero probability
+    strikeProbabilities[0] = { strike: sortedOptions[0].strike, probability: 0 };
+    strikeProbabilities[n - 1] = { strike: sortedOptions[n - 1].strike, probability: 0 };
+    for (let i = 1; i < n - 1; i++) {
+        const kPrev = sortedOptions[i - 1].strike;
+        const kCurr = sortedOptions[i].strike;
+        const kNext = sortedOptions[i + 1].strike;
+        // Use mid prices for stability
+        const midPrev = (sortedOptions[i - 1].bid + sortedOptions[i - 1].ask) / 2;
+        const midCurr = (sortedOptions[i].bid + sortedOptions[i].ask) / 2;
+        const midNext = (sortedOptions[i + 1].bid + sortedOptions[i + 1].ask) / 2;
+        const cPrev = midPrev;
+        const cNext = midNext;
+        // Protect against division by zero if strikes are too close
+        const strikeDiff = kNext - kPrev;
+        if (Math.abs(strikeDiff) < 1e-9) {
+            strikeProbabilities[i] = { strike: kCurr, probability: 0 };
+            continue;
+        }
+        // Second derivative: d²C/dK² ≈ (C(K+) - 2*C(K) + C(K-)) / (ΔK)²
+        const d2 = (cNext - 2 * midCurr + cPrev) / Math.pow(strikeDiff, 2);
+        // f(K) = e^{rT} * d²C/dK², ignoring discount for simplicity
+        // Ensure non-negative probability
+        strikeProbabilities[i] = { strike: kCurr, probability: Math.max(d2, 0) };
+    }
+    // Normalize densities to sum to 1
+    let sum = 0;
+    for (const sp of strikeProbabilities) {
+        sum += sp.probability;
+    }
+    // Protect against division by zero if all probabilities are 0
+    if (sum < 1e-9) {
+        return { success: false, error: `Insufficient probability mass to normalize (sum=${sum})` };
+    }
+    for (let i = 0; i < strikeProbabilities.length; i++) {
+        strikeProbabilities[i].probability /= sum;
+    }
+    // Compute summary statistics
+    // Most likely price (mode)
+    let mostLikelyPrice = strikeProbabilities[0].strike;
+    let maxProb = 0;
+    for (const sp of strikeProbabilities) {
+        if (sp.probability > maxProb) {
+            maxProb = sp.probability;
+            mostLikelyPrice = sp.strike;
+        }
+    }
+    // Compute cumulative distribution for median
+    let cumulative = 0;
+    let medianPrice = strikeProbabilities[Math.floor(strikeProbabilities.length / 2)].strike;
+    for (const sp of strikeProbabilities) {
+        cumulative += sp.probability;
+        if (cumulative >= 0.5) {
+            medianPrice = sp.strike;
+            break;
+        }
+    }
+    // Expected value (mean)
+    let mean = 0;
+    for (const sp of strikeProbabilities) {
+        mean += sp.strike * sp.probability;
+    }
+    // Variance and expected move (standard deviation)
+    let variance = 0;
+    for (const sp of strikeProbabilities) {
+        const diff = sp.strike - mean;
+        variance += diff * diff * sp.probability;
+    }
+    const expectedMove = Math.sqrt(variance);
+    // Tail skew: rightTail / leftTail relative to mean
+    let leftTail = 0;
+    let rightTail = 0;
+    for (const sp of strikeProbabilities) {
+        if (sp.strike < mean) {
+            leftTail += sp.probability;
+        }
+        else {
+            rightTail += sp.probability;
+        }
+    }
+    const tailSkew = rightTail / Math.max(leftTail, 1e-9);
+    // Cumulative probabilities above and below spot price
+    let cumulativeBelowSpot = 0;
+    let cumulativeAboveSpot = 0;
+    for (const sp of strikeProbabilities) {
+        if (sp.strike < underlyingPrice) {
+            cumulativeBelowSpot += sp.probability;
+        }
+        else if (sp.strike > underlyingPrice) {
+            cumulativeAboveSpot += sp.probability;
+        }
+    }
+    return {
+        success: true,
+        distribution: {
+            symbol,
+            expiryDate,
+            calculationTimestamp: Date.now(),
+            underlyingPrice,
+            strikeProbabilities,
+            mostLikelyPrice,
+            medianPrice,
+            expectedValue: mean,
+            expectedMove,
+            tailSkew,
+            cumulativeProbabilityAboveSpot: cumulativeAboveSpot,
+            cumulativeProbabilityBelowSpot: cumulativeBelowSpot,
+        },
+    };
+}
+/**
+ * Estimate implied probability distributions for all expirations in an option chain
+ *
+ * @param symbol - Underlying ticker symbol
+ * @param underlyingPrice - Current spot/mark price of the underlying
+ * @param options - Array of all options (calls and puts, all expirations)
+ * @returns Array of ImpliedProbabilityDistribution for each expiration
+ *
+ * @example
+ * ```typescript
+ * const distributions = estimateImpliedProbabilityDistributions(
+ *   'QQQ',
+ *   500.00,
+ *   chain.options
+ * );
+ *
+ * for (const dist of distributions) {
+ *   console.log(`Expiry: ${new Date(dist.expiryDate).toISOString()}`);
+ *   console.log(`Mode: ${dist.mostLikelyPrice}`);
+ * }
+ * ```
+ */
+function estimateImpliedProbabilityDistributions(symbol, underlyingPrice, options) {
+    // Get unique expirations
+    const expirationsSet = new Set();
+    for (const option of options) {
+        expirationsSet.add(option.expirationTimestamp);
+    }
+    const expirations = Array.from(expirationsSet).sort((a, b) => a - b);
+    const distributions = [];
+    for (const expiry of expirations) {
+        // Filter to call options at this expiry with valid bid/ask
+        const callOptionsAtExpiry = options.filter((opt) => opt.expirationTimestamp === expiry &&
+            opt.optionType === 'call' &&
+            opt.bid > 0 &&
+            opt.ask > 0);
+        const result = estimateImpliedProbabilityDistribution(symbol, underlyingPrice, callOptionsAtExpiry);
+        if (result.success) {
+            distributions.push(result.distribution);
+        }
+        // Silently skip expirations that don't have enough data
+    }
+    return distributions;
+}
+/**
+ * Get the probability of the underlying finishing between two price levels
+ *
+ * @param distribution - Implied probability distribution
+ * @param lowerBound - Lower price bound
+ * @param upperBound - Upper price bound
+ * @returns Probability of finishing between the bounds
+ *
+ * @example
+ * ```typescript
+ * // Probability of QQQ finishing between 490 and 510
+ * const prob = getProbabilityInRange(distribution, 490, 510);
+ * console.log(`${(prob * 100).toFixed(1)}% chance of finishing in range`);
+ * ```
+ */
+function getProbabilityInRange(distribution, lowerBound, upperBound) {
+    let probability = 0;
+    for (const sp of distribution.strikeProbabilities) {
+        if (sp.strike >= lowerBound && sp.strike <= upperBound) {
+            probability += sp.probability;
+        }
+    }
+    return probability;
+}
+/**
+ * Get the cumulative probability up to a given price level
+ *
+ * @param distribution - Implied probability distribution
+ * @param price - Price level
+ * @returns Cumulative probability of finishing at or below the price
+ *
+ * @example
+ * ```typescript
+ * // Probability of QQQ finishing at or below 495
+ * const prob = getCumulativeProbability(distribution, 495);
+ * console.log(`${(prob * 100).toFixed(1)}% chance of finishing <= 495`);
+ * ```
+ */
+function getCumulativeProbability(distribution, price) {
+    let probability = 0;
+    for (const sp of distribution.strikeProbabilities) {
+        if (sp.strike <= price) {
+            probability += sp.probability;
+        }
+    }
+    return probability;
+}
+/**
+ * Get the quantile (inverse CDF) for a given probability
+ *
+ * @param distribution - Implied probability distribution
+ * @param probability - Probability value between 0 and 1
+ * @returns Strike price at the given probability quantile
+ *
+ * @example
+ * ```typescript
+ * // Find the 5th and 95th percentile strikes
+ * const p5 = getQuantile(distribution, 0.05);
+ * const p95 = getQuantile(distribution, 0.95);
+ * console.log(`90% confidence interval: [${p5}, ${p95}]`);
+ * ```
+ */
+function getQuantile(distribution, probability) {
+    if (probability <= 0) {
+        return distribution.strikeProbabilities[0]?.strike ?? 0;
+    }
+    if (probability >= 1) {
+        return distribution.strikeProbabilities[distribution.strikeProbabilities.length - 1]?.strike ?? 0;
+    }
+    let cumulative = 0;
+    for (const sp of distribution.strikeProbabilities) {
+        cumulative += sp.probability;
+        if (cumulative >= probability) {
+            return sp.strike;
+        }
+    }
+    return distribution.strikeProbabilities[distribution.strikeProbabilities.length - 1]?.strike ?? 0;
+}

package/dist/index.d.ts

@@ -12,6 +12,9 @@ export { calculateGammaVannaCharmExposures, calculateSharesNeededToCover, } from
 export { cumulativeNormalDistribution, normalPDF, } from './utils/statistics';
 export { buildOCCSymbol, parseOCCSymbol, generateStrikesAroundSpot, generateOCCSymbolsForStrikes, generateOCCSymbolsAroundSpot, } from './utils/occ';
 export type { OCCSymbolParams, ParsedOCCSymbol, StrikeGenerationParams, } from './utils/occ';
+export { estimateImpliedProbabilityDistribution, estimateImpliedProbabilityDistributions, getProbabilityInRange, getCumulativeProbability, getQuantile, } from './impliedpdf';
+export type { StrikeProbability, ImpliedProbabilityDistribution, ImpliedPDFResult, } from './impliedpdf';
 export { FloeClient, Broker } from './client/FloeClient';
 export { TradierClient } from './client/brokers/TradierClient';
+export type { AggressorSide, IntradayTrade } from './client/brokers/TradierClient';
 export { genericAdapter, schwabAdapter, ibkrAdapter, tdaAdapter, brokerAdapters, getAdapter, createOptionChain, } from './adapters';

package/dist/index.js

@@ -20,7 +20,7 @@ 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.TradierClient = exports.Broker = exports.FloeClient = exports.generateOCCSymbolsAroundSpot = exports.generateOCCSymbolsForStrikes = exports.generateStrikesAroundSpot = exports.parseOCCSymbol = exports.buildOCCSymbol = 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;
+exports.createOptionChain = exports.getAdapter = exports.brokerAdapters = exports.tdaAdapter = exports.ibkrAdapter = exports.schwabAdapter = exports.genericAdapter = exports.TradierClient = exports.Broker = exports.FloeClient = exports.getQuantile = exports.getCumulativeProbability = exports.getProbabilityInRange = exports.estimateImpliedProbabilityDistributions = exports.estimateImpliedProbabilityDistribution = exports.generateOCCSymbolsAroundSpot = exports.generateOCCSymbolsForStrikes = exports.generateStrikesAroundSpot = exports.parseOCCSymbol = exports.buildOCCSymbol = 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
@@ -52,6 +52,13 @@ Object.defineProperty(exports, "parseOCCSymbol", { enumerable: true, get: functi
 Object.defineProperty(exports, "generateStrikesAroundSpot", { enumerable: true, get: function () { return occ_1.generateStrikesAroundSpot; } });
 Object.defineProperty(exports, "generateOCCSymbolsForStrikes", { enumerable: true, get: function () { return occ_1.generateOCCSymbolsForStrikes; } });
 Object.defineProperty(exports, "generateOCCSymbolsAroundSpot", { enumerable: true, get: function () { return occ_1.generateOCCSymbolsAroundSpot; } });
+// Implied PDF (probability density function)
+var impliedpdf_1 = require("./impliedpdf");
+Object.defineProperty(exports, "estimateImpliedProbabilityDistribution", { enumerable: true, get: function () { return impliedpdf_1.estimateImpliedProbabilityDistribution; } });
+Object.defineProperty(exports, "estimateImpliedProbabilityDistributions", { enumerable: true, get: function () { return impliedpdf_1.estimateImpliedProbabilityDistributions; } });
+Object.defineProperty(exports, "getProbabilityInRange", { enumerable: true, get: function () { return impliedpdf_1.getProbabilityInRange; } });
+Object.defineProperty(exports, "getCumulativeProbability", { enumerable: true, get: function () { return impliedpdf_1.getCumulativeProbability; } });
+Object.defineProperty(exports, "getQuantile", { enumerable: true, get: function () { return impliedpdf_1.getQuantile; } });
 // Client
 var FloeClient_1 = require("./client/FloeClient");
 Object.defineProperty(exports, "FloeClient", { enumerable: true, get: function () { return FloeClient_1.FloeClient; } });

package/dist/utils/occ.d.ts

@@ -48,7 +48,7 @@ export interface StrikeGenerationParams {
     /** Number of strikes below spot to include */
     strikesBelow?: number;
     /** Strike increment (e.g., 1 for $1 increments, 5 for $5) */
-    strikeIncrement?: number;
+    strikeIncrementInDollars?: number;
 }
 /**
  * Builds an OCC-formatted option symbol.

package/dist/utils/occ.js

@@ -48,7 +48,8 @@ function buildOCCSymbol(params) {
         ? symbol.toUpperCase().padEnd(6, ' ')
         : symbol.toUpperCase();
     // Format expiration date as YYMMDD
-    const expirationDate = typeof expiration === 'string' ? new Date(expiration) : expiration;
+    // Use UTC methods to avoid timezone shifts when parsing ISO date strings
+    const expirationDate = typeof expiration === 'string' ? new Date(expiration + 'T12:00:00') : expiration;
     const year = expirationDate.getFullYear().toString().slice(-2);
     const month = (expirationDate.getMonth() + 1).toString().padStart(2, '0');
     const day = expirationDate.getDate().toString().padStart(2, '0');
@@ -100,11 +101,11 @@ function parseOCCSymbol(occSymbol) {
     if (symbol.length === 0) {
         throw new Error(`Invalid OCC symbol: no ticker found in ${occSymbol}`);
     }
-    // Parse date
+    // Parse date - use noon to avoid timezone edge cases
     const year = 2000 + parseInt(dateString.slice(0, 2), 10);
     const month = parseInt(dateString.slice(2, 4), 10) - 1; // 0-indexed
     const day = parseInt(dateString.slice(4, 6), 10);
-    const expiration = new Date(year, month, day);
+    const expiration = new Date(year, month, day, 12, 0, 0);
     // Validate date
     if (isNaN(expiration.getTime())) {
         throw new Error(`Invalid date in OCC symbol: ${dateString}`);
@@ -133,7 +134,7 @@ function parseOCCSymbol(occSymbol) {
  * ```
  */
 function generateStrikesAroundSpot(params) {
-    const { spot, strikesAbove = 10, strikesBelow = 10, strikeIncrement = 1 } = params;
+    const { spot, strikesAbove = 10, strikesBelow = 10, strikeIncrementInDollars: strikeIncrement = 1 } = params;
     // Find the nearest strike at or below spot
     const baseStrike = Math.floor(spot / strikeIncrement) * strikeIncrement;
     const strikes = [];

package/dist/volatility/index.d.ts

@@ -20,7 +20,7 @@ import { OptionChain, IVSurface, VolatilityModel, SmoothingModel } from '../type
  */
 export declare function getIVSurfaces(volatilityModel: VolatilityModel, smoothingModel: SmoothingModel, chain: OptionChain): IVSurface[];
 /**
- * Get smoothed IV for a specific expiration, option type, and strike
+ * Helper function to get the smoothed IV for a specific expiration, option type, and strike combination
  *
  * @param ivSurfaces - Array of IV surfaces
  * @param expiration - Expiration timestamp in milliseconds

package/dist/volatility/index.js

@@ -134,7 +134,7 @@ function getIVSurfaces(volatilityModel, smoothingModel, chain) {
     return ivSurfaces;
 }
 /**
- * Get smoothed IV for a specific expiration, option type, and strike
+ * Helper function to get the smoothed IV for a specific expiration, option type, and strike combination
  *
  * @param ivSurfaces - Array of IV surfaces
  * @param expiration - Expiration timestamp in milliseconds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackcraftllc/floe",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "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",
@@ -41,6 +41,7 @@
   "devDependencies": {
     "@types/jest": "^29.5.0",
     "@types/node": "^20.0.0",
+    "dotenv": "^17.2.3",
     "jest": "^29.5.0",
     "ts-jest": "^29.1.0",
     "typescript": "^5.9.3"