@piaa/sdk 1.1.0 → 1.3.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

@@ -4,8 +4,14 @@
 import { type PiaClientOptions, type ResolvedPiaConfig } from "./config";
 import { RealtimeClient } from "./realtime/socket";
 import { MarketResource } from "./resources/market";
-import { NewsResource } from "./resources/news";
+import { IntelligenceResource } from "./resources/intelligence";
+import { OptionsResource } from "./resources/options";
+import { MacroResource } from "./resources/macro";
+import { GeosignalsResource } from "./resources/geosignals";
+import { EnergyResource } from "./resources/energy";
+import { SecResource } from "./resources/sec";
 import { SocialResource } from "./resources/social";
+import { NewsResource } from "./resources/news";
 import { EconomicResource } from "./resources/economic";
 import { FixedIncomeResource } from "./resources/fixed-income";
 import { WsResource } from "./resources/ws";
@@ -17,6 +23,30 @@ export declare class PiaClient {
      * Market data & prices API resource.
      */
     readonly market: MarketResource;
+    /**
+     * AI-powered quantitative intelligence and narrative catalysts resource.
+     */
+    readonly intelligence: IntelligenceResource;
+    /**
+     * Derivatives, options chain, and Gamma Exposure (GEX) resource.
+     */
+    readonly options: OptionsResource;
+    /**
+     * Macro indicators, Fear & Greed index, COT positioning, and central banks.
+     */
+    readonly macro: MacroResource;
+    /**
+     * Geopolitical risk alerts, conflict mapping, and asset exposure resource.
+     */
+    readonly geosignals: GeosignalsResource;
+    /**
+     * Energy benchmarks, crude spreads, and natural gas storage resource.
+     */
+    readonly energy: EnergyResource;
+    /**
+     * SEC EDGAR corporate filings (10-K, 10-Q, 8-K, Form 4) resource.
+     */
+    readonly sec: SecResource;
     /**
      * Social sentiment and discussions resource.
      */
@@ -43,14 +73,6 @@ export declare class PiaClient {
     readonly realtime: RealtimeClient;
     /**
      * Initializes a new PIA API Client.
-     *
-     * @example
-     * ```typescript
-     * import { PiaClient } from "@piaa/sdk";
-     *
-     * const client = new PiaClient({ apiKey: "wi_live_..." });
-     * const prices = await client.market.getPrices();
-     * ```
      */
     constructor(options?: PiaClientOptions);
     /**

package/dist/errors.d.ts

@@ -93,3 +93,7 @@ export declare class ApiError extends PiaError {
     readonly rawBody?: unknown;
     constructor(message: string, statusCode: number, rawBody?: unknown, details?: PiaErrorDetails);
 }
+/**
+ * Sanitizes and redacts API keys and secrets from string representations.
+ */
+export declare function redactSensitive(input: string): string;

package/dist/index.d.ts

@@ -3,9 +3,20 @@
  * Enterprise market intelligence & realtime streaming SDK.
  */
 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 { RealtimeClient, type SocketState } from "./realtime/socket";
-export { type RealtimeEvents } from "./realtime/events";
+export { type PiaClientOptions, type ResolvedPiaConfig, resolveConfig, } from "./config";
+export { PiaError, ConfigurationError, ValidationError, AuthenticationError, PermissionError, RateLimitError, TimeoutError, NetworkError, ParseError, ApiError, redactSensitive, } from "./errors";
+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 SocialPostItem, type SocialPostsResponse, type GetSocialPostsOptions, type GetSocialOptions, type NewsArticle, type NewsFeedResponse, type GetNewsOptions, type EconomicEvent, type EconomicCalendarResponse, type GetCalendarOptions, type YieldCurvePoint, type YieldCurveResponse, type WsTicketResponse, type OptionContract, type OptionChainResponse, type OptionGexResponse, type OptionSummaryResponse, type FearGreedData, type FearGreedHistoryResponse, type CotPositioning, type CotReportResponse, type CentralBankStanceResponse, } from "./types";
+export { RealtimeClient, type SocketState, } from "./realtime/socket";
+export { type RealtimeEvents, } from "./realtime/events";
+export { MarketResource } from "./resources/market";
+export { IntelligenceResource, type IntelligenceAnalyzeRequest, type IntelligenceAnalyzeResponse, type MarketInsightResponse } from "./resources/intelligence";
+export { OptionsResource } from "./resources/options";
+export { MacroResource } from "./resources/macro";
+export { GeosignalsResource, type GeoSignalEvent, type GeoSignalsResponse, type GeoSignalsMapResponse, type GeoSignalsAssetImpactResponse } from "./resources/geosignals";
+export { EnergyResource, type EnergyDashboardResponse, type EnergySeriesResponse } from "./resources/energy";
+export { SecResource, type SecFilingItem, type SecFilingsResponse, type GetSecFilingsOptions } from "./resources/sec";
+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";

package/dist/index.js

@@ -100,6 +100,15 @@ class ApiError extends PiaError {
     this.rawBody = rawBody;
   }
 }
+function redactSensitive(input) {
+  if (!input || typeof input !== "string")
+    return input;
+  return input.replace(/wi_live_([a-zA-Z0-9_-]+)/g, (_match, p1) => {
+    if (p1.length <= 4)
+      return "wi_live_***";
+    return `wi_live_***${p1.slice(-4)}`;
+  }).replace(/Bearer\s+[a-zA-Z0-9._-]+/gi, "Bearer [REDACTED]");
+}
 
 // src/logger.ts
 var SENSITIVE_KEY_PATTERNS = [
@@ -108,7 +117,7 @@ var SENSITIVE_KEY_PATTERNS = [
   /api[_-]?key["':\s]+["']?([a-zA-Z0-9_-]+)["']?/gi,
   /password["':\s]+["']?([^"'\s]+)["']?/gi
 ];
-function redactSensitive(input) {
+function redactSensitive2(input) {
   let redacted = input;
   for (const pattern of SENSITIVE_KEY_PATTERNS) {
     redacted = redacted.replace(pattern, (match) => {
@@ -138,13 +147,13 @@ class DefaultLogger {
     this.levelNum = LOG_LEVELS[level] ?? LOG_LEVELS.warn;
   }
   safeFormat(msg, args) {
-    const cleanMsg = `${this.prefix} ${redactSensitive(msg)}`;
+    const cleanMsg = `${this.prefix} ${redactSensitive2(msg)}`;
     const cleanArgs = args.map((arg) => {
       if (typeof arg === "string")
-        return redactSensitive(arg);
+        return redactSensitive2(arg);
       if (typeof arg === "object" && arg !== null) {
         try {
-          return JSON.parse(redactSensitive(JSON.stringify(arg)));
+          return JSON.parse(redactSensitive2(JSON.stringify(arg)));
         } catch {
           return "[Unserializable Object]";
         }
@@ -253,7 +262,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.3.0";
 
 class HttpTransport {
   config;
@@ -290,6 +299,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}`,
@@ -738,34 +748,162 @@ class MarketResource {
     const cleanSymbol = symbol.trim().toUpperCase();
     return this.transport.request(`/api/v1/market/insights/${encodeURIComponent(cleanSymbol)}`, "GET", undefined, options);
   }
+  async getTradingHalts(options) {
+    return this.transport.request("/api/v1/market/trading-halts", "GET", undefined, options);
+  }
+  async getCorporateActions(options) {
+    return this.transport.request("/api/v1/market/corporate-actions", "GET", undefined, options);
+  }
+  async getRealizedVolatility(symbol, options) {
+    const params = new URLSearchParams;
+    if (symbol)
+      params.set("symbol", symbol.trim().toUpperCase());
+    const query = params.toString() ? `?${params.toString()}` : "";
+    return this.transport.request(`/api/v1/market/realized-volatility${query}`, "GET", undefined, options);
+  }
+  async getImpliedVolatility(symbol, options) {
+    const params = new URLSearchParams;
+    if (symbol)
+      params.set("symbol", symbol.trim().toUpperCase());
+    const query = params.toString() ? `?${params.toString()}` : "";
+    return this.transport.request(`/api/v1/market/implied-volatility${query}`, "GET", undefined, options);
+  }
   async getWhy(symbol, options) {
     return this.getInsights(symbol, options);
   }
 }
 
-// src/resources/news.ts
-class NewsResource {
+// src/resources/intelligence.ts
+class IntelligenceResource {
   transport;
   constructor(transport) {
     this.transport = transport;
   }
-  async getNews(options) {
-    const params = new URLSearchParams;
-    if (options?.symbols && options.symbols.length > 0) {
-      params.set("symbols", options.symbols.map((s) => s.trim().toUpperCase()).join(","));
+  async analyze(request, options) {
+    return this.transport.request("/api/v1/intelligence/analyze", "POST", request, options);
+  }
+  async getInsights(symbol, options) {
+    if (!symbol || typeof symbol !== "string" || symbol.trim() === "") {
+      throw new ValidationError("Symbol must be a non-empty string.", "symbol");
     }
-    if (options?.category)
-      params.set("category", options.category);
+    const cleanSymbol = symbol.trim().toUpperCase();
+    return this.transport.request(`/api/v1/market/insights/${encodeURIComponent(cleanSymbol)}`, "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/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/geosignals.ts
+class GeosignalsResource {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async getEvents(options) {
+    return this.transport.request("/api/v1/geosignals", "GET", undefined, options);
+  }
+  async getMap(options) {
+    return this.transport.request("/api/v1/geosignals/map", "GET", undefined, options);
+  }
+  async getAssetImpacts(options) {
+    return this.transport.request("/api/v1/geosignals/assets", "GET", undefined, options);
+  }
+}
+
+// src/resources/energy.ts
+class EnergyResource {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async getDashboard(options) {
+    return this.transport.request("/api/v1/energy/dashboard", "GET", undefined, options);
+  }
+  async getSeries(seriesId, options) {
+    const params = new URLSearchParams;
+    if (seriesId)
+      params.set("id", seriesId);
+    const query = params.toString() ? `?${params.toString()}` : "";
+    return this.transport.request(`/api/v1/energy/series${query}`, "GET", undefined, options);
+  }
+}
+
+// src/resources/sec.ts
+class SecResource {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async getFilings(options) {
+    const params = new URLSearchParams;
+    if (options?.symbol)
+      params.set("symbol", options.symbol.trim().toUpperCase());
+    if (options?.form_type)
+      params.set("form_type", options.form_type);
     if (options?.limit)
       params.set("limit", String(options.limit));
+    if (options?.since)
+      params.set("since", options.since);
     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);
+    return this.transport.request(`/api/v1/sec/filings${query}`, "GET", undefined, options);
   }
-  async getById(id, options) {
-    return this.transport.request(`/api/v1/news/${encodeURIComponent(id)}`, "GET", undefined, options);
+  async getCompany(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/sec/companies/${encodeURIComponent(cleanSymbol)}`, "GET", undefined, options);
   }
 }
 
@@ -775,6 +913,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,8 +935,31 @@ 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/news.ts
+class NewsResource {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async getNews(options) {
+    const params = new URLSearchParams;
+    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);
   }
 }
 
@@ -809,6 +981,12 @@ class EconomicResource {
   async getIndicators(options) {
     return this.transport.request("/api/v1/economic/indicators", "GET", undefined, options);
   }
+  async getCategories(options) {
+    return this.transport.request("/api/v1/economic/categories", "GET", undefined, options);
+  }
+  async getCountries(options) {
+    return this.transport.request("/api/v1/economic/countries", "GET", undefined, options);
+  }
 }
 
 // src/resources/fixed-income.ts
@@ -841,16 +1019,28 @@ class PiaClient {
   config;
   transport;
   market;
+  intelligence;
+  options;
+  macro;
+  geosignals;
+  energy;
+  sec;
   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.intelligence = new IntelligenceResource(this.transport);
+    this.options = new OptionsResource(this.transport);
+    this.macro = new MacroResource(this.transport);
+    this.geosignals = new GeosignalsResource(this.transport);
+    this.energy = new EnergyResource(this.transport);
+    this.sec = new SecResource(this.transport);
     this.social = new SocialResource(this.transport);
     this.news = new NewsResource(this.transport);
     this.economic = new EconomicResource(this.transport);
@@ -866,20 +1056,27 @@ export {
   ApiError,
   AuthenticationError,
   ConfigurationError,
-  DEFAULT_BASE_URL,
-  DEFAULT_MAX_RETRIES,
-  DEFAULT_TIMEOUT_MS,
-  DEFAULT_WS_URL,
-  DefaultLogger,
+  EconomicResource,
+  EnergyResource,
+  FixedIncomeResource,
+  GeosignalsResource,
+  IntelligenceResource,
+  MacroResource,
+  MarketResource,
   NetworkError,
+  NewsResource,
+  OptionsResource,
   ParseError,
   PermissionError,
   PiaClient,
   PiaError,
   RateLimitError,
   RealtimeClient,
+  SecResource,
+  SocialResource,
   TimeoutError,
   ValidationError,
+  WsResource,
   redactSensitive,
   resolveConfig
 };

package/dist/resources/economic.d.ts

@@ -14,4 +14,12 @@ export declare class EconomicResource {
      * Retrieves macroeconomic indicators and series metadata.
      */
     getIndicators(options?: RequestOptions): Promise<any>;
+    /**
+     * Retrieves list of available macroeconomic indicator categories.
+     */
+    getCategories(options?: RequestOptions): Promise<any>;
+    /**
+     * Retrieves list of supported sovereign countries for economic indicators.
+     */
+    getCountries(options?: RequestOptions): Promise<any>;
 }

package/dist/resources/energy.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Official PIA SDK - Energy Markets & Commodity Reserves Resource
+ */
+import type { HttpTransport } from "../http/transport";
+import type { RequestOptions } from "../types";
+export interface EnergyDashboardResponse {
+    crude_oil?: {
+        wti_price?: number;
+        brent_price?: number;
+        spread?: number;
+        weekly_change_pct?: number;
+    };
+    natural_gas?: {
+        henry_hub_price?: number;
+        storage_bcf?: number;
+        storage_change?: number;
+    };
+    refining_margins?: Record<string, number>;
+    updated_at: string;
+}
+export interface EnergySeriesResponse {
+    series_id: string;
+    name: string;
+    unit: string;
+    data: Array<{
+        date: string;
+        value: number;
+    }>;
+}
+export declare class EnergyResource {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Retrieves energy market dashboard including WTI/Brent crude prices, crack spreads, and storage.
+     */
+    getDashboard(options?: RequestOptions): Promise<EnergyDashboardResponse>;
+    /**
+     * Retrieves historical time series data for a specific energy benchmark series.
+     */
+    getSeries(seriesId: string, options?: RequestOptions): Promise<EnergySeriesResponse>;
+}

package/dist/resources/geosignals.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Official PIA SDK - Geopolitical Signals & Macro Conflict Map Resource
+ */
+import type { HttpTransport } from "../http/transport";
+import type { RequestOptions } from "../types";
+export interface GeoSignalEvent {
+    id: string;
+    title: string;
+    region: string;
+    severity: "low" | "medium" | "high" | "critical";
+    category: "conflict" | "sanction" | "trade" | "election" | "supply_chain";
+    latitude?: number;
+    longitude?: number;
+    impacted_assets?: string[];
+    summary: string;
+    published_at: string;
+}
+export interface GeoSignalsResponse {
+    total: number;
+    events: GeoSignalEvent[];
+}
+export interface GeoSignalsMapResponse {
+    layers: Array<{
+        region: string;
+        risk_level: number;
+        active_conflicts: number;
+        chokepoints_status?: Record<string, string>;
+    }>;
+}
+export interface GeoSignalsAssetImpactResponse {
+    assets: Array<{
+        symbol: string;
+        risk_score: number;
+        primary_risk_driver: string;
+        affected_supply_pct?: number;
+    }>;
+}
+export declare class GeosignalsResource {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Retrieves active geopolitical risk events and conflict alerts.
+     */
+    getEvents(options?: RequestOptions): Promise<GeoSignalsResponse>;
+    /**
+     * Retrieves global geopolitical risk map layer data and maritime chokepoints status.
+     */
+    getMap(options?: RequestOptions): Promise<GeoSignalsMapResponse>;
+    /**
+     * Retrieves mapped asset vulnerabilities and commodity exposure to current geopolitical tensions.
+     */
+    getAssetImpacts(options?: RequestOptions): Promise<GeoSignalsAssetImpactResponse>;
+}

package/dist/resources/intelligence.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Official PIA SDK - AI Intelligence & Market Analysis Resource
+ */
+import type { HttpTransport } from "../http/transport";
+import type { RequestOptions } from "../types";
+export interface IntelligenceAnalyzeRequest {
+    symbol?: string;
+    query?: string;
+    context?: Record<string, any>;
+}
+export interface IntelligenceAnalyzeResponse {
+    symbol?: string;
+    sentiment?: "bullish" | "bearish" | "neutral";
+    confidence?: number;
+    analysis: string;
+    catalysts?: string[];
+    key_levels?: {
+        support?: number[];
+        resistance?: number[];
+    };
+    generated_at: string;
+}
+export interface MarketInsightResponse {
+    symbol: string;
+    summary: string;
+    sentiment: string;
+    drivers?: string[];
+    timestamp?: string;
+}
+export declare class IntelligenceResource {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Generates AI-powered real-time quantitative analysis and catalyst explanations.
+     */
+    analyze(request: IntelligenceAnalyzeRequest, options?: RequestOptions): Promise<IntelligenceAnalyzeResponse>;
+    /**
+     * Retrieves synthesized AI narrative insights and price drivers for a specific symbol.
+     */
+    getInsights(symbol: string, options?: RequestOptions): Promise<MarketInsightResponse>;
+}

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

@@ -25,6 +25,22 @@ export declare class MarketResource {
      * Retrieves AI/Quant market insights and price movement narrative for a given instrument.
      */
     getInsights(symbol: string, options?: RequestOptions): Promise<any>;
+    /**
+     * Retrieves active market trading halts and circuit breaker triggers.
+     */
+    getTradingHalts(options?: RequestOptions): Promise<any>;
+    /**
+     * Retrieves upcoming and historical corporate actions (dividends, splits, earnings).
+     */
+    getCorporateActions(options?: RequestOptions): Promise<any>;
+    /**
+     * Calculates historical realized volatility (HV) across rolling windows (10d, 30d, 90d).
+     */
+    getRealizedVolatility(symbol?: string, options?: RequestOptions): Promise<any>;
+    /**
+     * Retrieves implied volatility (IV) surface and ATM volatility index.
+     */
+    getImpliedVolatility(symbol?: string, options?: RequestOptions): Promise<any>;
     /**
      * @deprecated Use `getInsights(symbol)` instead.
      */

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/sec.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Official PIA SDK - SEC EDGAR Filings Resource
+ */
+import type { HttpTransport } from "../http/transport";
+import type { RequestOptions } from "../types";
+export interface SecFilingItem {
+    id: string;
+    symbol: string;
+    form_type: "10-K" | "10-Q" | "8-K" | "4" | "13F" | string;
+    company_name: string;
+    cik: string;
+    filing_date: string;
+    report_url: string;
+    description?: string;
+}
+export interface SecFilingsResponse {
+    total: number;
+    items: SecFilingItem[];
+    has_more?: boolean;
+}
+export interface GetSecFilingsOptions extends RequestOptions {
+    symbol?: string;
+    form_type?: string;
+    limit?: number;
+    since?: string;
+}
+export declare class SecResource {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Retrieves latest corporate SEC EDGAR filings (10-K, 10-Q, 8-K, Form 4 insider trades).
+     */
+    getFilings(options?: GetSecFilingsOptions): Promise<SecFilingsResponse>;
+    /**
+     * Retrieves SEC filing history for a specific public company symbol.
+     */
+    getCompany(symbol: string, options?: RequestOptions): Promise<any>;
+}

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.3.0",
   "description": "Official TypeScript/JavaScript SDK for PIA Market Intelligence Platform",
   "main": "./dist/index.js",
   "module": "./dist/index.js",