sentisense 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,413 @@
+interface SentiSenseOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+interface StockPrice {
+    ticker: string;
+    price: number;
+    change: number;
+    changePercent: number;
+    previousClose: number;
+    timestamp: number;
+}
+interface StockDetail {
+    ticker: string;
+    name: string;
+    kbEntityId?: string;
+    urlSlug?: string;
+}
+interface StockImage {
+    iconUrl: string | null;
+    logoUrl: string | null;
+}
+interface StockProfile {
+    ticker: string;
+    name: string;
+    ceo?: string;
+    sector?: string;
+    industry?: string;
+    marketCap?: number;
+    description?: string;
+    [key: string]: unknown;
+}
+interface StockEntity {
+    entityId: string;
+    name: string;
+    type: string;
+    [key: string]: unknown;
+}
+interface ChartDataPoint {
+    date: string;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}
+interface ChartData {
+    ticker: string;
+    timeframe: string;
+    data: ChartDataPoint[];
+}
+interface MarketStatus {
+    status: string;
+    [key: string]: unknown;
+}
+interface Fundamentals {
+    ticker: string;
+    timeframe: string;
+    [key: string]: unknown;
+}
+interface FundamentalsPeriod {
+    fiscalPeriod: string;
+    fiscalYear: number;
+}
+interface ShortInterest {
+    ticker: string;
+    [key: string]: unknown;
+}
+interface FloatInfo {
+    ticker: string;
+    [key: string]: unknown;
+}
+interface ShortVolume {
+    ticker: string;
+    [key: string]: unknown;
+}
+interface MetricsBreakdown {
+    [key: string]: unknown;
+}
+interface AISummary {
+    ticker: string;
+    [key: string]: unknown;
+}
+interface GetChartOptions {
+    timeframe?: "1M" | "3M" | "6M" | "1Y";
+}
+interface GetImagesOptions {
+    forced?: boolean;
+}
+interface GetDescriptionsOptions {
+    forced?: boolean;
+}
+interface GetSimilarOptions {
+    limit?: number;
+}
+interface GetProfileOptions {
+    forced?: boolean;
+}
+interface GetAISummaryOptions {
+    depth?: "basic" | "deep";
+    forceRefresh?: boolean;
+}
+interface GetMetricsBreakdownOptions {
+    startTime?: number;
+    endTime?: number;
+}
+interface GetFundamentalsOptions {
+    timeframe?: "quarterly" | "annual";
+    fiscalPeriod?: string;
+    fiscalYear?: number;
+}
+type DocumentSource = "news" | "reddit" | "x" | "substack";
+interface Document {
+    id: string;
+    text: string;
+    subtext: string;
+    url: string;
+    source: "NEWS" | "REDDIT" | "X" | "SUBSTACK";
+    publisher: string;
+    published: number;
+    averageSentiment: number;
+    reliability: number;
+    sentimentMap: Record<string, string>;
+    primaryImageUrl: string | null;
+}
+interface StoryCluster {
+    id: string;
+    title: string;
+    summarizedContent: string;
+    selectedImageUrl: string | null;
+    clusterSize: number;
+    averageSentiment: number;
+    createdAt: number;
+}
+interface Story {
+    cluster: StoryCluster;
+    displayTickers: string[];
+    tickers: string[];
+    impactScore: number;
+    representativeTimestamp: number;
+    topDocuments?: Document[];
+}
+interface TheNewsResponse {
+    [key: string]: unknown;
+}
+interface GetByTickerOptions {
+    source?: DocumentSource;
+    days?: number;
+    hours?: number;
+    limit?: number;
+}
+interface GetByTickerRangeOptions {
+    startDate: string;
+    endDate: string;
+    source?: DocumentSource;
+    limit?: number;
+}
+interface GetByEntityOptions {
+    source?: DocumentSource;
+    days?: number;
+    hours?: number;
+    limit?: number;
+}
+interface SearchDocumentsOptions {
+    source?: DocumentSource;
+    days?: number;
+    limit?: number;
+}
+interface GetBySourceOptions {
+    days?: number;
+    hours?: number;
+    limit?: number;
+}
+interface GetStoriesOptions {
+    limit?: number;
+    days?: number;
+    offset?: number;
+    expanded?: boolean;
+    filterHours?: number;
+}
+interface GetStoryOptions {
+    share?: boolean;
+}
+interface GetStoriesByTickerOptions {
+    limit?: number;
+}
+interface Quarter {
+    value: string;
+    label: string;
+    reportDate: string;
+}
+interface InstitutionalFlow {
+    ticker: string;
+    companyName: string;
+    totalSharesBought: number;
+    totalSharesSold: number;
+    netSharesChange: number;
+    newPositions: number;
+    increasedPositions: number;
+    decreasedPositions: number;
+    soldOutPositions: number;
+    indexFundNetChange: number;
+    hedgeFundNetChange: number;
+    activistActivity: boolean;
+    reportDate: string;
+}
+interface Holder {
+    filerCik: string;
+    filerName: string;
+    filerCategory: string;
+    shares: number;
+    valueUsd: number;
+    changeType: "NEW" | "INCREASED" | "DECREASED" | "SOLD_OUT" | "UNCHANGED";
+    sharesChange: number;
+    sharesChangePct: number;
+}
+interface GetFlowsOptions {
+    limit?: number;
+}
+interface MentionData {
+    [key: string]: unknown;
+}
+interface MentionCount {
+    [key: string]: unknown;
+}
+interface SentimentData {
+    [key: string]: unknown;
+}
+interface EntityMetricsDateRange {
+    startDate?: string;
+    endDate?: string;
+}
+interface GetMentionsOptions extends EntityMetricsDateRange {
+    source?: DocumentSource;
+}
+interface GetMentionCountOptions extends EntityMetricsDateRange {
+    source?: DocumentSource;
+}
+interface GetSentimentBySourceOptions {
+    date?: string;
+}
+interface MarketMood {
+    [key: string]: unknown;
+}
+interface KBEntity {
+    entityId: string;
+    name: string;
+    [key: string]: unknown;
+}
+
+declare class Documents {
+    private client;
+    constructor(client: APIClient);
+    /** Get news articles for a stock. */
+    getByTicker(ticker: string, options?: GetByTickerOptions): Promise<Document[]>;
+    /** Get news articles for a stock within a date range. */
+    getByTickerRange(ticker: string, options: GetByTickerRangeOptions): Promise<Document[]>;
+    /** Get documents for a KB entity. */
+    getByEntity(entityId: string, options?: GetByEntityOptions): Promise<Document[]>;
+    /** Smart search with natural language query parsing. */
+    search(query: string, options?: SearchDocumentsOptions): Promise<Document[]>;
+    /** Get latest documents from a source type. */
+    getBySource(source: DocumentSource, options?: GetBySourceOptions): Promise<Document[]>;
+    /** Get AI-curated news story clusters. */
+    getStories(options?: GetStoriesOptions): Promise<Story[]>;
+    /** Get detailed story with all source documents. Free users get preview. */
+    getStory(clusterId: string, options?: GetStoryOptions): Promise<Story>;
+    /** Get stories for a specific stock. */
+    getStoriesByTicker(ticker: string, options?: GetStoriesByTickerOptions): Promise<Story[]>;
+}
+
+declare class EntityMetrics {
+    private client;
+    constructor(client: APIClient);
+    /** Get mention data for a stock. */
+    getMentions(symbol: string, options?: GetMentionsOptions): Promise<MentionData>;
+    /** Get mention counts broken down by source. */
+    getMentionCountBySource(symbol: string, options?: EntityMetricsDateRange): Promise<MentionCount>;
+    /** Get total mention count. */
+    getMentionCount(symbol: string, options?: GetMentionCountOptions): Promise<MentionCount>;
+    /** Get sentiment data for a stock. */
+    getSentiment(symbol: string, options?: EntityMetricsDateRange): Promise<SentimentData>;
+    /** Get sentiment broken down by source. */
+    getSentimentBySource(symbol: string, options?: GetSentimentBySourceOptions): Promise<SentimentData>;
+    /** Get average sentiment score. */
+    getAverageSentiment(symbol: string, options?: EntityMetricsDateRange): Promise<SentimentData>;
+}
+
+declare class Institutional {
+    private client;
+    constructor(client: APIClient);
+    /** Get available 13F reporting quarters. */
+    getQuarters(): Promise<Quarter[]>;
+    /** Get aggregate institutional activity per ticker for a quarter. */
+    getFlows(reportDate: string, options?: GetFlowsOptions): Promise<InstitutionalFlow[]>;
+    /** Get institutional holders for a specific stock. */
+    getHolders(ticker: string, reportDate: string): Promise<Holder[]>;
+    /** Get activist investor positions (NEW or INCREASED). */
+    getActivists(reportDate: string): Promise<Holder[]>;
+}
+
+declare class KB {
+    private client;
+    constructor(client: APIClient);
+    /** Get popular entities for search suggestions. */
+    getPopularEntities(): Promise<KBEntity[]>;
+    /** Get entity detail with metrics and relationships. */
+    getEntity(entityId: string): Promise<KBEntity>;
+    /** Get all tracked entities. */
+    getAllEntities(): Promise<KBEntity[]>;
+}
+
+declare class MarketMoodResource {
+    private client;
+    constructor(client: APIClient);
+    /** Get market mood data (scores, history, sectors). */
+    get(): Promise<MarketMood>;
+}
+
+declare class Stocks {
+    private client;
+    constructor(client: APIClient);
+    /** List all available ticker symbols. */
+    list(): Promise<string[]>;
+    /** List all stocks with name, kbEntityId, urlSlug. */
+    listDetailed(): Promise<StockDetail[]>;
+    /** Get popular ticker symbols. */
+    listPopular(): Promise<string[]>;
+    /** Get popular stocks with details. */
+    listPopularDetailed(): Promise<StockDetail[]>;
+    /** Get real-time price for a single ticker. */
+    getPrice(ticker: string): Promise<StockPrice>;
+    /** Get real-time prices for multiple tickers. */
+    getPrices(tickers: string[]): Promise<Record<string, StockPrice>>;
+    /** Get batch company logo URLs. */
+    getImages(tickers: string[], options?: GetImagesOptions): Promise<Record<string, StockImage>>;
+    /** Get company profiles with branding, market cap, sector. */
+    getDescriptions(tickers: string[], options?: GetDescriptionsOptions): Promise<Record<string, StockProfile>>;
+    /** Get peer/similar stocks. */
+    getSimilar(ticker: string, options?: GetSimilarOptions): Promise<StockDetail[]>;
+    /** Get company profile (CEO, sector, industry, market data). */
+    getProfile(ticker: string, options?: GetProfileOptions): Promise<StockProfile>;
+    /** Get related KB entities (people, products, partners). */
+    getEntities(ticker: string): Promise<StockEntity[]>;
+    /** Get AI-generated stock analysis report. Requires PRO tier. */
+    getAISummary(ticker: string, options?: GetAISummaryOptions): Promise<AISummary>;
+    /** Get sentiment/mention metrics breakdown by entity. */
+    getMetricsBreakdown(ticker: string, metricType: string, options?: GetMetricsBreakdownOptions): Promise<MetricsBreakdown>;
+    /** Get historical OHLCV chart data. */
+    getChart(ticker: string, options?: GetChartOptions): Promise<ChartData>;
+    /** Get current market open/closed/pre-market/after-hours status. */
+    getMarketStatus(): Promise<MarketStatus>;
+    /** Get financial statement data. */
+    getFundamentals(ticker: string, options?: GetFundamentalsOptions): Promise<Fundamentals>;
+    /** Get available fiscal periods. */
+    getFundamentalsPeriods(ticker: string): Promise<FundamentalsPeriod[]>;
+    /** Get most recent fundamentals snapshot. */
+    getCurrentFundamentals(ticker: string): Promise<Fundamentals>;
+    /** Get historical P/E, P/B, P/S ratios. */
+    getHistoricalRatios(ticker: string): Promise<unknown>;
+    /** Get historical revenue data. */
+    getHistoricalRevenue(ticker: string): Promise<unknown>;
+    /** Get short interest metrics (FINRA). */
+    getShortInterest(ticker: string): Promise<ShortInterest>;
+    /** Get float information. */
+    getFloat(ticker: string): Promise<FloatInfo>;
+    /** Get short volume trading data. */
+    getShortVolume(ticker: string): Promise<ShortVolume>;
+}
+
+/** @internal HTTP interface exposed to resource classes. */
+interface APIClient {
+    get<T = unknown>(path: string, params?: object): Promise<T>;
+}
+declare class SentiSense implements APIClient {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    readonly stocks: Stocks;
+    readonly documents: Documents;
+    readonly institutional: Institutional;
+    readonly entityMetrics: EntityMetrics;
+    readonly marketMood: MarketMoodResource;
+    readonly kb: KB;
+    constructor(options?: SentiSenseOptions);
+    /** @internal */
+    get<T = unknown>(path: string, params?: object): Promise<T>;
+    private buildUrl;
+    private handleErrorResponse;
+}
+
+declare class SentiSenseError extends Error {
+    status?: number;
+    code?: string;
+    constructor(message: string, status?: number, code?: string);
+}
+declare class AuthenticationError extends SentiSenseError {
+    constructor(message: string, status: number, code?: string);
+}
+declare class NotFoundError extends SentiSenseError {
+    constructor(message: string, code?: string);
+}
+declare class RateLimitError extends SentiSenseError {
+    constructor(message: string, code?: string);
+}
+declare class APIError extends SentiSenseError {
+    constructor(message: string, status: number, code?: string);
+}
+
+declare const VERSION = "0.1.0";
+
+export { type AISummary, APIError, AuthenticationError, type ChartData, type ChartDataPoint, type Document, type DocumentSource, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type Holder, type InstitutionalFlow, type KBEntity, type MarketMood, type MarketStatus, type MentionCount, type MentionData, type MetricsBreakdown, NotFoundError, type Quarter, RateLimitError, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentData, type ShortInterest, type ShortVolume, type StockDetail, type StockEntity, type StockImage, type StockPrice, type StockProfile, type Story, type StoryCluster, type TheNewsResponse, VERSION, SentiSense as default };