@piaa/sdk 1.1.0 → 1.2.0

package/README.md

@@ -9,7 +9,9 @@ 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.
+- **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-*`).
@@ -40,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() {
@@ -59,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) {
@@ -80,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";
@@ -119,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

@@ -8,6 +8,8 @@ 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 {
@@ -17,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.
      */

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 EconomicEvent, type EconomicCalendarResponse, type GetCalendarOptions, type YieldCurvePoint, type YieldCurveResponse, type MarketInsight, 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}`,
@@ -775,6 +776,17 @@ class SocialResource {
   constructor(transport) {
     this.transport = transport;
   }
+  async getPosts(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/posts${query}`, "GET", undefined, options);
+  }
   async getFeed(options) {
     const params = new URLSearchParams;
     if (options?.symbol)
@@ -786,9 +798,6 @@ class SocialResource {
     const query = params.toString() ? `?${params.toString()}` : "";
     return this.transport.request(`/api/v1/social/feed${query}`, "GET", undefined, options);
   }
-  async getPosts(options) {
-    return this.getFeed(options);
-  }
 }
 
 // src/resources/economic.ts
@@ -825,6 +834,59 @@ class FixedIncomeResource {
   }
 }
 
+// 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
 class WsResource {
   transport;
@@ -841,16 +903,20 @@ 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);
@@ -871,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/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/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,16 +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.
      */
-    getFeed(options?: GetSocialOptions): Promise<SocialFeedResponse>;
+    getPosts(options?: GetSocialPostsOptions): Promise<SocialPostsResponse>;
     /**
-     * @deprecated Use `getFeed(options)` instead.
+     * Fetches the real-time social discussion feed.
      */
-    getPosts(options?: GetSocialOptions): Promise<SocialFeedResponse>;
+    getFeed(options?: GetSocialOptions): Promise<SocialFeedResponse>;
 }

package/dist/types.d.ts

@@ -142,3 +142,112 @@ export interface WsTicketResponse {
     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.1.0",
+  "version": "1.2.0",
   "description": "Official TypeScript/JavaScript SDK for PIA Market Intelligence Platform",
   "main": "./dist/index.js",
   "module": "./dist/index.js",