@piaa/sdk 1.0.2 → 1.1.0

package/README.md

@@ -8,12 +8,11 @@ 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.
+- **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-*`).
 
 ---
 

package/dist/client.d.ts

@@ -6,6 +6,8 @@ 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 { WsResource } from "./resources/ws";
 import type { RateLimitInfo } from "./types";
 export declare class PiaClient {
@@ -23,6 +25,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,6 @@ 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 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";

package/dist/index.js

@@ -731,6 +731,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 +754,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
@@ -757,7 +775,7 @@ class SocialResource {
   constructor(transport) {
     this.transport = transport;
   }
-  async getPosts(options) {
+  async getFeed(options) {
     const params = new URLSearchParams;
     if (options?.symbol)
       params.set("symbol", options.symbol.trim().toUpperCase());
@@ -766,7 +784,44 @@ class SocialResource {
     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);
+    return this.transport.request(`/api/v1/social/feed${query}`, "GET", undefined, options);
+  }
+  async getPosts(options) {
+    return this.getFeed(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);
   }
 }
 
@@ -788,6 +843,8 @@ class PiaClient {
   market;
   social;
   news;
+  economic;
+  fixedIncome;
   ws;
   realtime;
   constructor(options = {}) {
@@ -796,6 +853,8 @@ class PiaClient {
     this.market = new MarketResource(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);
   }

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

@@ -9,5 +9,9 @@ export declare class SocialResource {
     /**
      * Fetches the latest social sentiment posts and discussions.
      */
+    getFeed(options?: GetSocialOptions): Promise<SocialFeedResponse>;
+    /**
+     * @deprecated Use `getFeed(options)` instead.
+     */
     getPosts(options?: GetSocialOptions): Promise<SocialFeedResponse>;
 }

package/dist/types.d.ts

@@ -98,8 +98,45 @@ 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;

package/package.json

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