@fullstackcraftllc/floe 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -10,4 +10,9 @@ export { getIVSurfaces, getIVForStrike, } from './volatility';
 export { smoothTotalVarianceSmile, } from './volatility/smoothing';
 export { calculateGammaVannaCharmExposures, calculateSharesNeededToCover, } from './exposure';
 export { cumulativeNormalDistribution, normalPDF, } from './utils/statistics';
+export { buildOCCSymbol, parseOCCSymbol, generateStrikesAroundSpot, generateOCCSymbolsForStrikes, generateOCCSymbolsAroundSpot, } from './utils/occ';
+export type { OCCSymbolParams, ParsedOCCSymbol, StrikeGenerationParams, } from './utils/occ';
+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.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.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
@@ -45,6 +45,19 @@ Object.defineProperty(exports, "calculateSharesNeededToCover", { enumerable: tru
 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; } });
+// OCC symbol utilities
+var occ_1 = require("./utils/occ");
+Object.defineProperty(exports, "buildOCCSymbol", { enumerable: true, get: function () { return occ_1.buildOCCSymbol; } });
+Object.defineProperty(exports, "parseOCCSymbol", { enumerable: true, get: function () { return occ_1.parseOCCSymbol; } });
+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; } });
+// Client
+var FloeClient_1 = require("./client/FloeClient");
+Object.defineProperty(exports, "FloeClient", { enumerable: true, get: function () { return FloeClient_1.FloeClient; } });
+Object.defineProperty(exports, "Broker", { enumerable: true, get: function () { return FloeClient_1.Broker; } });
+var TradierClient_1 = require("./client/brokers/TradierClient");
+Object.defineProperty(exports, "TradierClient", { enumerable: true, get: function () { return TradierClient_1.TradierClient; } });
 // Broker adapters
 var adapters_1 = require("./adapters");
 Object.defineProperty(exports, "genericAdapter", { enumerable: true, get: function () { return adapters_1.genericAdapter; } });

package/dist/types/index.d.ts

@@ -63,10 +63,37 @@ export interface Greeks {
     /** Ultima: Rate of change of volga with respect to volatility */
     ultima: number;
 }
+/**
+ * Normalized ticker data structure (broker-agnostic)
+ */
+export interface NormalizedTicker {
+    /** Underlying symbol */
+    symbol: string;
+    /** Current spot price of the underlying (mid of bid/ask, or last trade) */
+    spot: number;
+    /** Current bid price */
+    bid: number;
+    /** Current bid size */
+    bidSize: number;
+    /** Current ask price */
+    ask: number;
+    /** Current ask size */
+    askSize: number;
+    /** Last traded price */
+    last: number;
+    /** Cumulative volume for the day */
+    volume: number;
+    /** Timestamp of the quote in milliseconds */
+    timestamp: number;
+}
 /**
  * Normalized option data structure (broker-agnostic)
  */
 export interface NormalizedOption {
+    /** OCC-formatted option symbol (e.g., 'AAPL  230120C00150000') */
+    occSymbol: string;
+    /** Underlying ticker symbol */
+    underlying: string;
     /** Strike price */
     strike: number;
     /** Expiration date (ISO 8601) */
@@ -77,8 +104,12 @@ export interface NormalizedOption {
     optionType: OptionType;
     /** Current bid price */
     bid: number;
+    /** Current bid size */
+    bidSize: number;
     /** Current ask price */
     ask: number;
+    /** Current ask size */
+    askSize: number;
     /** Mark (mid) price */
     mark: number;
     /** Last traded price */
@@ -87,8 +118,12 @@ export interface NormalizedOption {
     volume: number;
     /** Open interest */
     openInterest: number;
+    /** Live open interest - calculated intraday by comparing using open interest as t=0 and comparing trades to the current NBBO for that option */
+    liveOpenInterest?: number;
     /** Implied volatility (as decimal) */
     impliedVolatility: number;
+    /** Timestamp of the quote in milliseconds */
+    timestamp: number;
     /** Pre-calculated Greeks (optional) */
     greeks?: Greeks;
 }

package/dist/utils/occ.d.ts

@@ -0,0 +1,164 @@
+/**
+ * OCC (Options Clearing Corporation) symbol utilities
+ *
+ * OCC symbols follow the format: ROOT + YYMMDD + C/P + STRIKE
+ * Example: AAPL230120C00150000 = AAPL $150 Call expiring Jan 20, 2023
+ */
+import { OptionType } from '../types';
+/**
+ * Parameters for building an OCC option symbol
+ */
+export interface OCCSymbolParams {
+    /** Underlying ticker symbol (e.g., 'AAPL', 'QQQ') */
+    symbol: string;
+    /** Expiration date (Date object or ISO string) */
+    expiration: Date | string;
+    /** Option type: 'call' or 'put' */
+    optionType: OptionType;
+    /** Strike price in dollars (e.g., 150.50) */
+    strike: number;
+    /**
+     * If true, pads the symbol to 6 characters with spaces (standard OCC format).
+     * If false (default), uses compact format without spaces (common for APIs).
+     * @default false
+     */
+    padded?: boolean;
+}
+/**
+ * Parsed components of an OCC option symbol
+ */
+export interface ParsedOCCSymbol {
+    /** Underlying ticker symbol */
+    symbol: string;
+    /** Expiration date */
+    expiration: Date;
+    /** Option type */
+    optionType: OptionType;
+    /** Strike price in dollars */
+    strike: number;
+}
+/**
+ * Parameters for generating strikes around a spot price
+ */
+export interface StrikeGenerationParams {
+    /** Current spot/underlying price */
+    spot: number;
+    /** Number of strikes above spot to include */
+    strikesAbove?: number;
+    /** Number of strikes below spot to include */
+    strikesBelow?: number;
+    /** Strike increment (e.g., 1 for $1 increments, 5 for $5) */
+    strikeIncrementInDollars?: number;
+}
+/**
+ * Builds an OCC-formatted option symbol.
+ *
+ * @param params - The option parameters
+ * @returns OCC-formatted symbol string
+ *
+ * @remarks
+ * OCC format: ROOT(6 chars, left-padded) + YYMMDD + C/P + STRIKE(8 digits, price × 1000)
+ *
+ * @example
+ * ```typescript
+ * const symbol = buildOCCSymbol({
+ *   symbol: 'AAPL',
+ *   expiration: new Date('2023-01-20'),
+ *   optionType: 'call',
+ *   strike: 150
+ * });
+ * // Returns: 'AAPL230120C00150000' (compact format, default)
+ *
+ * // With padded format (standard OCC)
+ * const symbol2 = buildOCCSymbol({
+ *   symbol: 'QQQ',
+ *   expiration: '2024-03-15',
+ *   optionType: 'put',
+ *   strike: 425.50,
+ *   padded: true
+ * });
+ * // Returns: 'QQQ   240315P00425500'
+ * ```
+ */
+export declare function buildOCCSymbol(params: OCCSymbolParams): string;
+/**
+ * Parses an OCC-formatted option symbol into its components.
+ * Supports both compact format (e.g., 'AAPL230120C00150000') and
+ * padded format (e.g., 'AAPL  230120C00150000').
+ *
+ * @param occSymbol - The OCC symbol to parse
+ * @returns Parsed symbol components
+ * @throws {Error} If the symbol format is invalid
+ *
+ * @example
+ * ```typescript
+ * // Compact format
+ * const parsed = parseOCCSymbol('AAPL230120C00150000');
+ * // Returns: { symbol: 'AAPL', expiration: Date, optionType: 'call', strike: 150 }
+ *
+ * // Padded format (21 chars)
+ * const parsed2 = parseOCCSymbol('AAPL  230120C00150000');
+ * // Returns: { symbol: 'AAPL', expiration: Date, optionType: 'call', strike: 150 }
+ * ```
+ */
+export declare function parseOCCSymbol(occSymbol: string): ParsedOCCSymbol;
+/**
+ * Generates an array of strike prices centered around a spot price.
+ *
+ * @param params - Strike generation parameters
+ * @returns Array of strike prices, sorted ascending
+ *
+ * @example
+ * ```typescript
+ * const strikes = generateStrikesAroundSpot({
+ *   spot: 450.25,
+ *   strikesAbove: 10,
+ *   strikesBelow: 10,
+ *   strikeIncrement: 5
+ * });
+ * // Returns: [405, 410, 415, 420, 425, 430, 435, 440, 445, 450, 455, 460, 465, 470, 475, 480, 485, 490, 495, 500]
+ * ```
+ */
+export declare function generateStrikesAroundSpot(params: StrikeGenerationParams): number[];
+/**
+ * Generates OCC symbols for calls and puts across multiple strikes.
+ *
+ * @param symbol - Underlying ticker symbol
+ * @param expiration - Option expiration date
+ * @param strikes - Array of strike prices
+ * @param includeTypes - Which option types to include (default: both)
+ * @returns Array of OCC symbol strings
+ *
+ * @example
+ * ```typescript
+ * const symbols = generateOCCSymbolsForStrikes(
+ *   'QQQ',
+ *   new Date('2024-01-19'),
+ *   [495, 500, 505],
+ *   ['call', 'put']
+ * );
+ * // Returns 6 symbols: 3 calls + 3 puts
+ * ```
+ */
+export declare function generateOCCSymbolsForStrikes(symbol: string, expiration: Date | string, strikes: number[], includeTypes?: OptionType[]): string[];
+/**
+ * Convenience function to generate OCC symbols around current spot price.
+ *
+ * @param symbol - Underlying ticker symbol
+ * @param expiration - Option expiration date
+ * @param spot - Current spot price
+ * @param options - Strike generation options
+ * @returns Array of OCC symbol strings for calls and puts
+ *
+ * @example
+ * ```typescript
+ * // Generate 20 calls + 20 puts around QQQ at $502.50
+ * const symbols = generateOCCSymbolsAroundSpot('QQQ', '2024-01-19', 502.50, {
+ *   strikesAbove: 10,
+ *   strikesBelow: 10,
+ *   strikeIncrement: 5
+ * });
+ * // Returns 42 symbols (21 strikes × 2 types)
+ * ```
+ */
+export declare function generateOCCSymbolsAroundSpot(symbol: string, expiration: Date | string, spot: number, options?: Omit<StrikeGenerationParams, 'spot'>): string[];

package/dist/utils/occ.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * OCC (Options Clearing Corporation) symbol utilities
+ *
+ * OCC symbols follow the format: ROOT + YYMMDD + C/P + STRIKE
+ * Example: AAPL230120C00150000 = AAPL $150 Call expiring Jan 20, 2023
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOCCSymbol = buildOCCSymbol;
+exports.parseOCCSymbol = parseOCCSymbol;
+exports.generateStrikesAroundSpot = generateStrikesAroundSpot;
+exports.generateOCCSymbolsForStrikes = generateOCCSymbolsForStrikes;
+exports.generateOCCSymbolsAroundSpot = generateOCCSymbolsAroundSpot;
+/**
+ * Builds an OCC-formatted option symbol.
+ *
+ * @param params - The option parameters
+ * @returns OCC-formatted symbol string
+ *
+ * @remarks
+ * OCC format: ROOT(6 chars, left-padded) + YYMMDD + C/P + STRIKE(8 digits, price × 1000)
+ *
+ * @example
+ * ```typescript
+ * const symbol = buildOCCSymbol({
+ *   symbol: 'AAPL',
+ *   expiration: new Date('2023-01-20'),
+ *   optionType: 'call',
+ *   strike: 150
+ * });
+ * // Returns: 'AAPL230120C00150000' (compact format, default)
+ *
+ * // With padded format (standard OCC)
+ * const symbol2 = buildOCCSymbol({
+ *   symbol: 'QQQ',
+ *   expiration: '2024-03-15',
+ *   optionType: 'put',
+ *   strike: 425.50,
+ *   padded: true
+ * });
+ * // Returns: 'QQQ   240315P00425500'
+ * ```
+ */
+function buildOCCSymbol(params) {
+    const { symbol, expiration, optionType, strike, padded = false } = params;
+    // Format symbol - either padded to 6 chars or compact
+    const formattedSymbol = padded
+        ? symbol.toUpperCase().padEnd(6, ' ')
+        : symbol.toUpperCase();
+    // Format expiration date as YYMMDD
+    // 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');
+    const dateString = `${year}${month}${day}`;
+    // Option type indicator
+    const typeIndicator = optionType === 'call' ? 'C' : 'P';
+    // Strike price: multiply by 1000, pad to 8 digits
+    const strikeInt = Math.round(strike * 1000);
+    const strikeString = strikeInt.toString().padStart(8, '0');
+    return `${formattedSymbol}${dateString}${typeIndicator}${strikeString}`;
+}
+/**
+ * Parses an OCC-formatted option symbol into its components.
+ * Supports both compact format (e.g., 'AAPL230120C00150000') and
+ * padded format (e.g., 'AAPL  230120C00150000').
+ *
+ * @param occSymbol - The OCC symbol to parse
+ * @returns Parsed symbol components
+ * @throws {Error} If the symbol format is invalid
+ *
+ * @example
+ * ```typescript
+ * // Compact format
+ * const parsed = parseOCCSymbol('AAPL230120C00150000');
+ * // Returns: { symbol: 'AAPL', expiration: Date, optionType: 'call', strike: 150 }
+ *
+ * // Padded format (21 chars)
+ * const parsed2 = parseOCCSymbol('AAPL  230120C00150000');
+ * // Returns: { symbol: 'AAPL', expiration: Date, optionType: 'call', strike: 150 }
+ * ```
+ */
+function parseOCCSymbol(occSymbol) {
+    // Find the option type indicator (C or P) which is always followed by 8 strike digits
+    // This works for both compact and padded formats
+    const typeMatch = occSymbol.match(/([CP])(\d{8})$/);
+    if (!typeMatch) {
+        throw new Error(`Invalid OCC symbol format: ${occSymbol}`);
+    }
+    const typeIndicator = typeMatch[1];
+    const strikeString = typeMatch[2];
+    // Everything before the type indicator should be: SYMBOL + YYMMDD
+    const prefix = occSymbol.slice(0, -9); // Remove C/P + 8 digits
+    // Last 6 characters of prefix are the date (YYMMDD)
+    if (prefix.length < 6) {
+        throw new Error(`Invalid OCC symbol format: ${occSymbol}`);
+    }
+    const dateString = prefix.slice(-6);
+    const symbol = prefix.slice(0, -6).trim();
+    if (symbol.length === 0) {
+        throw new Error(`Invalid OCC symbol: no ticker found in ${occSymbol}`);
+    }
+    // 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, 12, 0, 0);
+    // Validate date
+    if (isNaN(expiration.getTime())) {
+        throw new Error(`Invalid date in OCC symbol: ${dateString}`);
+    }
+    // Parse option type
+    const optionType = typeIndicator === 'C' ? 'call' : 'put';
+    // Parse strike (divide by 1000)
+    const strike = parseInt(strikeString, 10) / 1000;
+    return { symbol, expiration, optionType, strike };
+}
+/**
+ * Generates an array of strike prices centered around a spot price.
+ *
+ * @param params - Strike generation parameters
+ * @returns Array of strike prices, sorted ascending
+ *
+ * @example
+ * ```typescript
+ * const strikes = generateStrikesAroundSpot({
+ *   spot: 450.25,
+ *   strikesAbove: 10,
+ *   strikesBelow: 10,
+ *   strikeIncrement: 5
+ * });
+ * // Returns: [405, 410, 415, 420, 425, 430, 435, 440, 445, 450, 455, 460, 465, 470, 475, 480, 485, 490, 495, 500]
+ * ```
+ */
+function generateStrikesAroundSpot(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 = [];
+    // Generate strikes below (including base)
+    for (let i = strikesBelow; i >= 0; i--) {
+        strikes.push(baseStrike - i * strikeIncrement);
+    }
+    // Generate strikes above
+    for (let i = 1; i <= strikesAbove; i++) {
+        strikes.push(baseStrike + i * strikeIncrement);
+    }
+    return strikes;
+}
+/**
+ * Generates OCC symbols for calls and puts across multiple strikes.
+ *
+ * @param symbol - Underlying ticker symbol
+ * @param expiration - Option expiration date
+ * @param strikes - Array of strike prices
+ * @param includeTypes - Which option types to include (default: both)
+ * @returns Array of OCC symbol strings
+ *
+ * @example
+ * ```typescript
+ * const symbols = generateOCCSymbolsForStrikes(
+ *   'QQQ',
+ *   new Date('2024-01-19'),
+ *   [495, 500, 505],
+ *   ['call', 'put']
+ * );
+ * // Returns 6 symbols: 3 calls + 3 puts
+ * ```
+ */
+function generateOCCSymbolsForStrikes(symbol, expiration, strikes, includeTypes = ['call', 'put']) {
+    const symbols = [];
+    for (const strike of strikes) {
+        for (const optionType of includeTypes) {
+            symbols.push(buildOCCSymbol({ symbol, expiration, optionType, strike }));
+        }
+    }
+    return symbols;
+}
+/**
+ * Convenience function to generate OCC symbols around current spot price.
+ *
+ * @param symbol - Underlying ticker symbol
+ * @param expiration - Option expiration date
+ * @param spot - Current spot price
+ * @param options - Strike generation options
+ * @returns Array of OCC symbol strings for calls and puts
+ *
+ * @example
+ * ```typescript
+ * // Generate 20 calls + 20 puts around QQQ at $502.50
+ * const symbols = generateOCCSymbolsAroundSpot('QQQ', '2024-01-19', 502.50, {
+ *   strikesAbove: 10,
+ *   strikesBelow: 10,
+ *   strikeIncrement: 5
+ * });
+ * // Returns 42 symbols (21 strikes × 2 types)
+ * ```
+ */
+function generateOCCSymbolsAroundSpot(symbol, expiration, spot, options) {
+    const strikes = generateStrikesAroundSpot({ spot, ...options });
+    return generateOCCSymbolsForStrikes(symbol, expiration, strikes);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fullstackcraftllc/floe",
-  "version": "0.0.1",
-  "description": "Production-ready options analytics toolkit. Normalize broker data structures and calculate Black-Scholes, Greeks, and GEX with a clean, type-safe API. Built for trading platforms and fintech applications.",
+  "version": "0.0.3",
+  "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",
   "scripts": {
@@ -43,7 +43,7 @@
     "@types/node": "^20.0.0",
     "jest": "^29.5.0",
     "ts-jest": "^29.1.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.9.3"
   },
   "files": [
     "dist",