@piaa/sdk 1.0.2 → 1.2.0

package/README.md

@@ -8,12 +8,13 @@ Designed for institutional algorithmic traders, fintech dashboards, and quantita
 
 ## Features
 
-- ⚡ **Zero-Fuss Sensible Defaults**: Connect in 3 lines of code with pre-configured endpoints and sensible timeout/retry defaults.
-- 🔁 **Enterprise Resiliency**: Automatic exponential backoff with full jitter for transient 5xx/429 network hiccups and retry-after headers.
-- 🛡️ **Typed Error Hierarchy**: Clear, actionable, strongly-typed errors (`AuthenticationError`, `RateLimitError`, `TimeoutError`, `ValidationError`, `NetworkError`).
-- 🔒 **Zero Sensitive Data Leaks**: Automatic redaction of API keys, bearer tokens, and secrets from error logs and stack traces.
-- 📡 **Cross-Platform Realtime Streaming**: Built-in resilient WebSocket client with **In-Band Message Authentication**, ping/pong keep-alives, and automatic re-subscription on reconnect.
-- 📊 **Rate Limit Telemetry**: Real-time inspection of RFC 6585 and daily quota headers (`X-RateLimit-*`, `X-DailyQuota-*`).
+- **Zero-Fuss Sensible Defaults**: Connect in 3 lines of code with pre-configured endpoints and sensible timeout/retry defaults.
+- **Dual Proxy-Resilient Auth**: Transparently sends both standard `Authorization: Bearer <key>` and `x-api-key` headers to guarantee 100% compatibility across Cloudflare tunnels, WAFs, and internal gateways.
+- **Typed Error Hierarchy**: Clear, actionable, strongly-typed errors (`AuthenticationError`, `RateLimitError`, `TimeoutError`, `ValidationError`, `NetworkError`).
+- **Derivatives & Macro Intelligence**: Real-time Options Chain, Gamma Exposure (GEX), Fear & Greed Index, and CFTC Commitment of Traders (COT) positioning.
+- **Zero Sensitive Data Leaks**: Automatic redaction of API keys, bearer tokens, and secrets from error logs and stack traces.
+- **Cross-Platform Realtime Streaming**: Built-in resilient WebSocket client with **In-Band Message Authentication**, ping/pong keep-alives, and automatic re-subscription on reconnect.
+- **Rate Limit Telemetry**: Real-time inspection of RFC 6585 and daily quota headers (`X-RateLimit-*`, `X-DailyQuota-*`).
 
 ---
 
@@ -41,7 +42,7 @@ import { PiaClient, RateLimitError, AuthenticationError } from "@piaa/sdk";
 
 // Automatically picks up process.env.PIA_API_KEY if omitted
 const client = new PiaClient({
-  apiKey: "wi_live_your_api_key",
+  apiKey: "wi_live_...",
 });
 
 async function run() {
@@ -60,7 +61,22 @@ async function run() {
     });
     console.log(`Fetched ${candles.count} bars for ${candles.symbol}`);
 
-    // 3. Inspect rate limit telemetry
+    // 3. Options Chain & Gamma Exposure (GEX)
+    const gex = await client.options.getGex("SPX");
+    console.log(`SPX Net GEX: $${gex.net_gex?.toLocaleString()} (0-Gamma: ${gex.zero_gamma_level})`);
+
+    // 4. Macro Sentiment & Positioning (Fear & Greed, COT)
+    const fg = await client.macro.getFearGreed();
+    console.log(`Fear & Greed Index: ${fg.score} (${fg.rating})`);
+
+    const cot = await client.macro.getCot("GOLD");
+    console.log(`Gold Commercial Net: ${cot.reports[0]?.net_position}`);
+
+    // 5. Social Discussions & Breaking News
+    const posts = await client.social.getPosts({ limit: 10, symbol: "BTC" });
+    console.log(`Latest post by @${posts.items[0]?.author_username}: "${posts.items[0]?.text}"`);
+
+    // 6. Inspect rate limit telemetry
     const quota = client.getRateLimitInfo();
     console.log(`Remaining daily hits: ${quota.dailyRemaining}/${quota.dailyLimit}`);
   } catch (err) {
@@ -81,7 +97,7 @@ run();
 
 ### 2. Realtime WebSocket Streaming (In-Band Message Auth)
 
-Cross-platform streaming without query-string leakage:
+Cross-platform streaming without query-string token leakage:
 
 ```typescript
 import { PiaClient } from "@piaa/sdk";
@@ -120,6 +136,22 @@ client.realtime.connect();
 
 ---
 
+## Complete Resource Reference
+
+| Resource | Methods | Endpoint | Description |
+|---|---|---|---|
+| `client.market` | `getPrices()`, `getCandles()`, `getOrderBook()` | `/api/v1/market/*` | Live price snapshot, ClickHouse OHLCV candles, and Level 2 DOM. |
+| `client.options` | `getChain()`, `getGex()`, `getSummary()` | `/api/v1/options/*` | Full options chain, Gamma Exposure levels, and put/call sentiment. |
+| `client.macro` | `getFearGreed()`, `getCot()`, `getCentralBankStance()` | `/api/v1/fear-greed`, `/api/v1/cot/*`, `/api/v1/central-banks/*` | Fear & Greed sentiment index, CFTC institutional COT reports, and central bank monetary policy stance. |
+| `client.social` | `getPosts()`, `getFeed()` | `/api/v1/social/*` | Real-time social sentiment and discussion feeds from Twitter/𝕏. |
+| `client.news` | `getNews()` | `/api/v1/news` | Curated multi-asset financial news headlines and articles. |
+| `client.economic` | `getCalendar()` | `/api/v1/economic/calendar` | Global economic calendar events, CPI releases, and rate decisions. |
+| `client.fixedIncome` | `getYieldCurve()` | `/api/v1/rates/yield-curve` | Benchmark sovereign bond yield curves across tenors. |
+| `client.ws` | `createTicket()` | `/api/v1/ws/ticket` | Ephemeral single-use WebSocket connection tickets. |
+| `client.realtime` | `connect()`, `subscribe()`, `unsubscribe()`, `disconnect()` | `/api/v1/ws` | Low-latency streaming socket client with event emitters. |
+
+---
+
 ## Configuration Reference
 
 ```typescript

package/dist/client.d.ts

@@ -6,6 +6,10 @@ import { RealtimeClient } from "./realtime/socket";
 import { MarketResource } from "./resources/market";
 import { NewsResource } from "./resources/news";
 import { SocialResource } from "./resources/social";
+import { EconomicResource } from "./resources/economic";
+import { FixedIncomeResource } from "./resources/fixed-income";
+import { MacroResource } from "./resources/macro";
+import { OptionsResource } from "./resources/options";
 import { WsResource } from "./resources/ws";
 import type { RateLimitInfo } from "./types";
 export declare class PiaClient {
@@ -15,6 +19,14 @@ export declare class PiaClient {
      * Market data & prices API resource.
      */
     readonly market: MarketResource;
+    /**
+     * Derivatives, options chain, and Gamma Exposure (GEX) resource.
+     */
+    readonly options: OptionsResource;
+    /**
+     * Macro indicators, Fear & Greed index, COT positioning, and central banks.
+     */
+    readonly macro: MacroResource;
     /**
      * Social sentiment and discussions resource.
      */
@@ -23,6 +35,14 @@ export declare class PiaClient {
      * Financial news resource.
      */
     readonly news: NewsResource;
+    /**
+     * Macroeconomic calendar and indicators resource.
+     */
+    readonly economic: EconomicResource;
+    /**
+     * Sovereign bond yields and fixed income rates resource.
+     */
+    readonly fixedIncome: FixedIncomeResource;
     /**
      * WebSocket ticket issuance resource.
      */

package/dist/index.d.ts

@@ -6,6 +6,14 @@ export { PiaClient } from "./client";
 export { type PiaClientOptions, type ResolvedPiaConfig, resolveConfig, DEFAULT_BASE_URL, DEFAULT_WS_URL, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_RETRIES, } from "./config";
 export { PiaError, type PiaErrorDetails, ConfigurationError, ValidationError, AuthenticationError, PermissionError, RateLimitError, TimeoutError, NetworkError, ParseError, ApiError, } from "./errors";
 export { type PiaLogger, type LogLevel, DefaultLogger, redactSensitive, } from "./logger";
-export { type Timeframe, type RateLimitInfo, type RequestOptions, type MarketPrice, type MarketPricesResponse, type Candle, type CandleResponse, type GetCandlesOptions, type OrderBook, type OrderBookLevel, type SocialPost, type SocialFeedResponse, type GetSocialOptions, type NewsArticle, type NewsFeedResponse, type GetNewsOptions, type WsTicketResponse, } from "./types";
+export { type Timeframe, type RateLimitInfo, type RequestOptions, type MarketPrice, type MarketPricesResponse, type Candle, type CandleResponse, type GetCandlesOptions, type OrderBook, type OrderBookLevel, type SocialPost, type SocialFeedResponse, type GetSocialOptions, type SocialPostItem, type SocialPostsResponse, type GetSocialPostsOptions, type OptionContract, type OptionChainResponse, type OptionGexResponse, type OptionSummaryResponse, type FearGreedData, type FearGreedHistoryResponse, type CotPositioning, type CotReportResponse, type CentralBankStanceResponse, type NewsArticle, type NewsFeedResponse, type GetNewsOptions, type EconomicEvent, type EconomicCalendarResponse, type GetCalendarOptions, type YieldCurvePoint, type YieldCurveResponse, type MarketInsight, type WsTicketResponse, } from "./types";
+export { MarketResource } from "./resources/market";
+export { OptionsResource } from "./resources/options";
+export { MacroResource } from "./resources/macro";
+export { SocialResource } from "./resources/social";
+export { NewsResource } from "./resources/news";
+export { EconomicResource } from "./resources/economic";
+export { FixedIncomeResource } from "./resources/fixed-income";
+export { WsResource } from "./resources/ws";
 export { RealtimeClient, type SocketState } from "./realtime/socket";
 export { type RealtimeEvents } from "./realtime/events";

package/dist/index.js

@@ -253,7 +253,7 @@ function resolveConfig(options = {}) {
 
 // src/http/transport.ts
 var RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
-var SDK_VERSION = "1.0.2";
+var SDK_VERSION = "1.2.0";
 
 class HttpTransport {
   config;
@@ -290,6 +290,7 @@ class HttpTransport {
       }
       try {
         const headers = {
+          Authorization: `Bearer ${this.config.apiKey}`,
           "x-api-key": this.config.apiKey,
           Accept: "application/json",
           "User-Agent": `pia-sdk-ts/${SDK_VERSION}`,
@@ -731,6 +732,16 @@ class MarketResource {
     const cleanSymbol = symbol.trim().toUpperCase();
     return this.transport.request(`/api/v1/market/orderbook/${encodeURIComponent(cleanSymbol)}`, "GET", undefined, options);
   }
+  async getInsights(symbol, options) {
+    if (!symbol || typeof symbol !== "string" || symbol.trim() === "") {
+      throw new ValidationError("Symbol must be a non-empty string.", "symbol");
+    }
+    const cleanSymbol = symbol.trim().toUpperCase();
+    return this.transport.request(`/api/v1/market/insights/${encodeURIComponent(cleanSymbol)}`, "GET", undefined, options);
+  }
+  async getWhy(symbol, options) {
+    return this.getInsights(symbol, options);
+  }
 }
 
 // src/resources/news.ts
@@ -744,11 +755,19 @@ class NewsResource {
     if (options?.symbols && options.symbols.length > 0) {
       params.set("symbols", options.symbols.map((s) => s.trim().toUpperCase()).join(","));
     }
+    if (options?.category)
+      params.set("category", options.category);
     if (options?.limit)
       params.set("limit", String(options.limit));
     const query = params.toString() ? `?${params.toString()}` : "";
     return this.transport.request(`/api/v1/news${query}`, "GET", undefined, options);
   }
+  async getLatest(options) {
+    return this.transport.request("/api/v1/news/latest", "GET", undefined, options);
+  }
+  async getById(id, options) {
+    return this.transport.request(`/api/v1/news/${encodeURIComponent(id)}`, "GET", undefined, options);
+  }
 }
 
 // src/resources/social.ts
@@ -768,6 +787,104 @@ class SocialResource {
     const query = params.toString() ? `?${params.toString()}` : "";
     return this.transport.request(`/api/v1/social/posts${query}`, "GET", undefined, options);
   }
+  async getFeed(options) {
+    const params = new URLSearchParams;
+    if (options?.symbol)
+      params.set("symbol", options.symbol.trim().toUpperCase());
+    if (options?.limit)
+      params.set("limit", String(options.limit));
+    if (options?.cursor)
+      params.set("cursor", options.cursor);
+    const query = params.toString() ? `?${params.toString()}` : "";
+    return this.transport.request(`/api/v1/social/feed${query}`, "GET", undefined, options);
+  }
+}
+
+// src/resources/economic.ts
+class EconomicResource {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async getCalendar(options) {
+    const params = new URLSearchParams;
+    if (options?.impact)
+      params.set("impact", options.impact);
+    if (options?.limit)
+      params.set("limit", String(options.limit));
+    const query = params.toString() ? `?${params.toString()}` : "";
+    return this.transport.request(`/api/v1/economic/calendar${query}`, "GET", undefined, options);
+  }
+  async getIndicators(options) {
+    return this.transport.request("/api/v1/economic/indicators", "GET", undefined, options);
+  }
+}
+
+// src/resources/fixed-income.ts
+class FixedIncomeResource {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async getYieldCurve(options) {
+    return this.transport.request("/api/v1/fixed-income/yield-curve", "GET", undefined, options);
+  }
+  async getSpreads(options) {
+    return this.transport.request("/api/v1/fixed-income/spreads", "GET", undefined, options);
+  }
+}
+
+// src/resources/macro.ts
+class MacroResource {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async getFearGreed(options) {
+    return this.transport.request("/api/v1/fear-greed", "GET", undefined, options);
+  }
+  async getFearGreedHistory(options) {
+    return this.transport.request("/api/v1/fear-greed/history", "GET", undefined, options);
+  }
+  async getCot(symbol, options) {
+    if (!symbol || typeof symbol !== "string" || symbol.trim() === "") {
+      throw new ValidationError("Symbol must be a non-empty string.", "symbol");
+    }
+    const clean = symbol.trim().toUpperCase();
+    return this.transport.request(`/api/v1/cot/symbol/${encodeURIComponent(clean)}`, "GET", undefined, options);
+  }
+  async getCentralBankStance(bank, options) {
+    if (!bank || typeof bank !== "string" || bank.trim() === "") {
+      throw new ValidationError("Bank must be a non-empty string.", "bank");
+    }
+    const clean = bank.trim().toLowerCase();
+    return this.transport.request(`/api/v1/central-banks/${encodeURIComponent(clean)}/stance`, "GET", undefined, options);
+  }
+}
+
+// src/resources/options.ts
+class OptionsResource {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async getChain(symbol, options) {
+    if (!symbol || typeof symbol !== "string" || symbol.trim() === "") {
+      throw new ValidationError("Symbol must be a non-empty string.", "symbol");
+    }
+    const clean = symbol.trim().toUpperCase();
+    return this.transport.request(`/api/v1/options/chain/${encodeURIComponent(clean)}`, "GET", undefined, options);
+  }
+  async getGex(symbol, options) {
+    if (!symbol || typeof symbol !== "string" || symbol.trim() === "") {
+      throw new ValidationError("Symbol must be a non-empty string.", "symbol");
+    }
+    const clean = symbol.trim().toUpperCase();
+    return this.transport.request(`/api/v1/options/gex/${encodeURIComponent(clean)}`, "GET", undefined, options);
+  }
+  async getSummary(options) {
+    return this.transport.request("/api/v1/options/summary", "GET", undefined, options);
+  }
 }
 
 // src/resources/ws.ts
@@ -786,16 +903,24 @@ class PiaClient {
   config;
   transport;
   market;
+  options;
+  macro;
   social;
   news;
+  economic;
+  fixedIncome;
   ws;
   realtime;
-  constructor(options = {}) {
-    this.config = Object.freeze(resolveConfig(options));
+  constructor(options) {
+    this.config = resolveConfig(options);
     this.transport = new HttpTransport(this.config);
     this.market = new MarketResource(this.transport);
+    this.options = new OptionsResource(this.transport);
+    this.macro = new MacroResource(this.transport);
     this.social = new SocialResource(this.transport);
     this.news = new NewsResource(this.transport);
+    this.economic = new EconomicResource(this.transport);
+    this.fixedIncome = new FixedIncomeResource(this.transport);
     this.ws = new WsResource(this.transport);
     this.realtime = new RealtimeClient(this.config);
   }
@@ -812,15 +937,23 @@ export {
   DEFAULT_TIMEOUT_MS,
   DEFAULT_WS_URL,
   DefaultLogger,
+  EconomicResource,
+  FixedIncomeResource,
+  MacroResource,
+  MarketResource,
   NetworkError,
+  NewsResource,
+  OptionsResource,
   ParseError,
   PermissionError,
   PiaClient,
   PiaError,
   RateLimitError,
   RealtimeClient,
+  SocialResource,
   TimeoutError,
   ValidationError,
+  WsResource,
   redactSensitive,
   resolveConfig
 };

package/dist/resources/economic.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Official PIA SDK - Economic Intelligence API Resource
+ */
+import type { HttpTransport } from "../http/transport";
+import type { EconomicCalendarResponse, GetCalendarOptions, RequestOptions } from "../types";
+export declare class EconomicResource {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Fetches global macroeconomic calendar events (NFP, CPI, interest rates, GDP).
+     */
+    getCalendar(options?: GetCalendarOptions): Promise<EconomicCalendarResponse>;
+    /**
+     * Retrieves macroeconomic indicators and series metadata.
+     */
+    getIndicators(options?: RequestOptions): Promise<any>;
+}

package/dist/resources/fixed-income.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Official PIA SDK - Fixed Income & Sovereign Rates API Resource
+ */
+import type { HttpTransport } from "../http/transport";
+import type { RequestOptions, YieldCurveResponse } from "../types";
+export declare class FixedIncomeResource {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Retrieves US Treasury sovereign bond yield curve structure across all standard tenors.
+     */
+    getYieldCurve(options?: RequestOptions): Promise<YieldCurveResponse>;
+    /**
+     * Retrieves sovereign yield spreads (2Y-10Y, 3M-10Y curve steepness indicators).
+     */
+    getSpreads(options?: RequestOptions): Promise<any>;
+}

package/dist/resources/macro.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Official PIA SDK - Macro & Market Sentiment Resource
+ */
+import type { HttpTransport } from "../http/transport";
+import type { CentralBankStanceResponse, CotReportResponse, FearGreedData, FearGreedHistoryResponse, RequestOptions } from "../types";
+export declare class MacroResource {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Retrieves the current Fear & Greed Index score and sentiment rating.
+     */
+    getFearGreed(options?: RequestOptions): Promise<FearGreedData>;
+    /**
+     * Retrieves historical Fear & Greed Index time series.
+     */
+    getFearGreedHistory(options?: RequestOptions): Promise<FearGreedHistoryResponse>;
+    /**
+     * Fetches CFTC Commitment of Traders (COT) institutional positioning report for a symbol.
+     *
+     * @param symbol Commodity/Currency/Index symbol (e.g. "GOLD", "WTI", "EURUSD", "SPX")
+     */
+    getCot(symbol: string, options?: RequestOptions): Promise<CotReportResponse>;
+    /**
+     * Fetches monetary policy stance and interest rate assessment for a central bank.
+     *
+     * @param bank Bank code (e.g. "fed", "ecb", "boj", "bi", "boe")
+     */
+    getCentralBankStance(bank: string, options?: RequestOptions): Promise<CentralBankStanceResponse>;
+}

package/dist/resources/market.d.ts

@@ -21,4 +21,12 @@ export declare class MarketResource {
      * Retrieves Level 2 DOM (Depth of Market) order book for a symbol.
      */
     getOrderBook(symbol: string, options?: RequestOptions): Promise<OrderBook>;
+    /**
+     * Retrieves AI/Quant market insights and price movement narrative for a given instrument.
+     */
+    getInsights(symbol: string, options?: RequestOptions): Promise<any>;
+    /**
+     * @deprecated Use `getInsights(symbol)` instead.
+     */
+    getWhy(symbol: string, options?: RequestOptions): Promise<any>;
 }

package/dist/resources/news.d.ts

@@ -2,7 +2,7 @@
  * Official PIA SDK - News Intelligence API Resource
  */
 import type { HttpTransport } from "../http/transport";
-import type { GetNewsOptions, NewsFeedResponse } from "../types";
+import type { GetNewsOptions, NewsFeedResponse, RequestOptions } from "../types";
 export declare class NewsResource {
     private readonly transport;
     constructor(transport: HttpTransport);
@@ -10,4 +10,12 @@ export declare class NewsResource {
      * Fetches curated financial and macro news articles.
      */
     getNews(options?: GetNewsOptions): Promise<NewsFeedResponse>;
+    /**
+     * Fetches the latest breaking financial news bulletin.
+     */
+    getLatest(options?: RequestOptions): Promise<any>;
+    /**
+     * Fetches detailed intelligence for a specific news article ID.
+     */
+    getById(id: string, options?: RequestOptions): Promise<any>;
 }

package/dist/resources/options.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Official PIA SDK - Derivatives & Options Analytics Resource
+ */
+import type { HttpTransport } from "../http/transport";
+import type { OptionChainResponse, OptionGexResponse, OptionSummaryResponse, RequestOptions } from "../types";
+export declare class OptionsResource {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Fetches the real-time option chain for an underlying asset symbol.
+     *
+     * @param symbol Underlier ticker (e.g. "AAPL", "NVDA", "SPX")
+     */
+    getChain(symbol: string, options?: RequestOptions): Promise<OptionChainResponse>;
+    /**
+     * Fetches Gamma Exposure (GEX) profile and key zero-gamma levels.
+     *
+     * @param symbol Underlier ticker (e.g. "SPX", "NVDA", "QQQ")
+     */
+    getGex(symbol: string, options?: RequestOptions): Promise<OptionGexResponse>;
+    /**
+     * Retrieves overall options market activity and put/call sentiment summary.
+     */
+    getSummary(options?: RequestOptions): Promise<OptionSummaryResponse>;
+}

package/dist/resources/social.d.ts

@@ -2,12 +2,18 @@
  * Official PIA SDK - Social Intelligence API Resource
  */
 import type { HttpTransport } from "../http/transport";
-import type { GetSocialOptions, SocialFeedResponse } from "../types";
+import type { GetSocialOptions, GetSocialPostsOptions, SocialFeedResponse, SocialPostsResponse } from "../types";
 export declare class SocialResource {
     private readonly transport;
     constructor(transport: HttpTransport);
     /**
-     * Fetches the latest social sentiment posts and discussions.
+     * Fetches the latest social sentiment posts from PostgreSQL / RSSHub ingestion pipeline.
+     *
+     * @param options Pagination limit, cursor, and optional symbol filter.
      */
-    getPosts(options?: GetSocialOptions): Promise<SocialFeedResponse>;
+    getPosts(options?: GetSocialPostsOptions): Promise<SocialPostsResponse>;
+    /**
+     * Fetches the real-time social discussion feed.
+     */
+    getFeed(options?: GetSocialOptions): Promise<SocialFeedResponse>;
 }

package/dist/types.d.ts

@@ -98,10 +98,156 @@ export interface NewsFeedResponse {
 }
 export interface GetNewsOptions extends RequestOptions {
     symbols?: string[];
+    category?: "forex" | "stock" | "all" | string;
     limit?: number;
 }
+export interface EconomicEvent {
+    id?: string;
+    event: string;
+    country: string;
+    currency?: string;
+    date: string;
+    time?: string;
+    actual?: number | null;
+    forecast?: number | null;
+    previous?: number | null;
+    impact?: "high" | "medium" | "low" | string;
+}
+export interface EconomicCalendarResponse {
+    total: number;
+    items: EconomicEvent[];
+}
+export interface GetCalendarOptions extends RequestOptions {
+    impact?: string;
+    limit?: number;
+}
+export interface YieldCurvePoint {
+    tenor: string;
+    yield: number;
+    date?: string;
+}
+export interface YieldCurveResponse {
+    date: string;
+    points: YieldCurvePoint[];
+}
+export interface MarketInsight {
+    symbol: string;
+    title: string;
+    summary: string;
+    sentiment?: string;
+    confidence?: number;
+}
 export interface WsTicketResponse {
     ticket: string;
     expires_in?: number;
     ws_url?: string;
 }
+export interface SocialPostItem {
+    author_username: string;
+    author_display_name?: string;
+    text: string;
+    url: string;
+    created_at: string;
+    platform: string;
+    like_count?: number;
+    retweet_count?: number;
+    media_urls?: string[];
+    source_account?: string;
+}
+export interface SocialPostsResponse {
+    has_more: boolean;
+    items: SocialPostItem[];
+    next_before?: string | null;
+}
+export interface GetSocialPostsOptions extends RequestOptions {
+    limit?: number;
+    cursor?: string;
+    symbol?: string;
+}
+export interface OptionContract {
+    symbol: string;
+    strike: number;
+    expiration: string;
+    option_type: "call" | "put" | string;
+    bid?: number;
+    ask?: number;
+    last?: number;
+    volume?: number;
+    open_interest?: number;
+    implied_volatility?: number;
+    delta?: number;
+    gamma?: number;
+    theta?: number;
+    vega?: number;
+}
+export interface OptionChainResponse {
+    symbol: string;
+    underlying_price?: number;
+    expirations: string[];
+    contracts: OptionContract[];
+}
+export interface OptionGexResponse {
+    symbol: string;
+    net_gex?: number;
+    total_call_gex?: number;
+    total_put_gex?: number;
+    zero_gamma_level?: number;
+    major_positive_levels?: Array<{
+        strike: number;
+        gex: number;
+    }>;
+    major_negative_levels?: Array<{
+        strike: number;
+        gex: number;
+    }>;
+    updated_at?: string;
+}
+export interface OptionSummaryResponse {
+    total_volume?: number;
+    total_open_interest?: number;
+    put_call_ratio?: number;
+    most_active_symbols?: Array<{
+        symbol: string;
+        volume: number;
+    }>;
+}
+export interface FearGreedData {
+    score: number;
+    rating: string;
+    timestamp: string | number;
+    previous_close?: number;
+    previous_1_week?: number;
+    previous_1_month?: number;
+    previous_1_year?: number;
+}
+export interface FearGreedHistoryResponse {
+    current: FearGreedData;
+    history: Array<{
+        score: number;
+        rating: string;
+        timestamp: string | number;
+    }>;
+}
+export interface CotPositioning {
+    market_code: string;
+    market_name?: string;
+    report_date: string;
+    commercial_long?: number;
+    commercial_short?: number;
+    non_commercial_long?: number;
+    non_commercial_short?: number;
+    net_position?: number;
+}
+export interface CotReportResponse {
+    symbol?: string;
+    market_code?: string;
+    reports: CotPositioning[];
+}
+export interface CentralBankStanceResponse {
+    bank: string;
+    name?: string;
+    stance: "hawkish" | "dovish" | "neutral" | string;
+    rate?: number;
+    last_updated?: string;
+    summary?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piaa/sdk",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Official TypeScript/JavaScript SDK for PIA Market Intelligence Platform",
   "main": "./dist/index.js",
   "module": "./dist/index.js",