reportify-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,505 @@
+/**
+ * Reportify SDK Type Definitions
+ */
+interface ReportifyConfig {
+    /** Your Reportify API key */
+    apiKey: string;
+    /** Base URL for the API (default: https://api.reportify.cn) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+interface Document {
+    docId?: string;
+    title: string;
+    summary: string;
+    category: string;
+    publishedAt?: number;
+    channelId?: string;
+    channelName?: string;
+    companies?: CompanyInfo[];
+    tags?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    score?: number;
+    url?: string;
+}
+interface CompanyInfo {
+    name: string;
+    industry?: string;
+    sector?: string;
+    stocks?: StockInfo[];
+}
+interface StockInfo {
+    symbol: string;
+    market: string;
+    ticker: string;
+}
+interface Chunk {
+    chunkId: string;
+    content: string;
+    docId: string;
+    score?: number;
+    doc?: Document;
+}
+interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+interface SearchOptions {
+    num?: number;
+    categories?: string[];
+    symbols?: string[];
+    startDate?: string;
+    endDate?: string;
+}
+interface CompanyOverview {
+    symbol: string;
+    name: string;
+    description?: string;
+    sector?: string;
+    industry?: string;
+    marketCap?: number;
+    employees?: number;
+    website?: string;
+    [key: string]: unknown;
+}
+interface Shareholder {
+    name: string;
+    shares: number;
+    percentage: number;
+    type?: string;
+}
+interface FinancialStatement {
+    date: string;
+    [key: string]: string | number | null;
+}
+interface PriceData {
+    date: string;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+    [key: string]: string | number;
+}
+interface Quote {
+    symbol: string;
+    price: number;
+    change: number;
+    changePercent: number;
+    volume?: number;
+    marketCap?: number;
+    timestamp?: number;
+}
+interface EarningsEvent {
+    symbol: string;
+    companyName: string;
+    date: string;
+    time?: string;
+    epsEstimate?: number;
+    epsActual?: number;
+    [key: string]: unknown;
+}
+interface IPOEvent {
+    symbol?: string;
+    companyName: string;
+    status: string;
+    listingDate?: string;
+    priceRange?: string;
+    [key: string]: unknown;
+}
+type Period = 'annual' | 'quarterly';
+type Interval = '1d' | '1w' | '1m';
+type PriceAdjust = 'forward' | 'backward' | 'none';
+type Market = 'us' | 'hk' | 'cn';
+type IPOStatus = 'Filing' | 'Hearing' | 'Priced';
+interface TimelineOptions {
+    num?: number;
+}
+interface KBSearchOptions {
+    folderIds?: string[];
+    docIds?: string[];
+    startDate?: string;
+    endDate?: string;
+    num?: number;
+}
+declare class ReportifyError extends Error {
+    statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+declare class AuthenticationError extends ReportifyError {
+    constructor(message?: string);
+}
+declare class RateLimitError extends ReportifyError {
+    constructor(message?: string);
+}
+declare class NotFoundError extends ReportifyError {
+    constructor(message?: string);
+}
+declare class APIError extends ReportifyError {
+    constructor(message: string, statusCode?: number);
+}
+
+/**
+ * Stock Module
+ *
+ * Provides access to stock market data including prices, financial statements,
+ * and company information.
+ */
+
+declare class StockModule {
+    private client;
+    constructor(client: Reportify);
+    /**
+     * Get company overview including business description, sector, and key metrics
+     *
+     * @param symbol - Stock symbol (e.g., "US:AAPL", "HK:0700")
+     */
+    overview(symbol: string): Promise<CompanyOverview>;
+    /**
+     * Get list of major shareholders
+     *
+     * @param symbol - Stock symbol
+     */
+    shareholders(symbol: string): Promise<Shareholder[]>;
+    /**
+     * Get income statement data
+     *
+     * @param symbol - Stock symbol
+     * @param options.period - "annual" or "quarterly"
+     * @param options.limit - Number of periods to return
+     */
+    incomeStatement(symbol: string, options?: {
+        period?: Period;
+        limit?: number;
+    }): Promise<FinancialStatement[]>;
+    /**
+     * Get balance sheet data
+     *
+     * @param symbol - Stock symbol
+     * @param options.period - "annual" or "quarterly"
+     * @param options.limit - Number of periods to return
+     */
+    balanceSheet(symbol: string, options?: {
+        period?: Period;
+        limit?: number;
+    }): Promise<FinancialStatement[]>;
+    /**
+     * Get cash flow statement data
+     *
+     * @param symbol - Stock symbol
+     * @param options.period - "annual" or "quarterly"
+     * @param options.limit - Number of periods to return
+     */
+    cashflowStatement(symbol: string, options?: {
+        period?: Period;
+        limit?: number;
+    }): Promise<FinancialStatement[]>;
+    /**
+     * Get revenue breakdown by segment, product, or region
+     *
+     * @param symbol - Stock symbol
+     * @param options.breakdownType - Type of breakdown
+     */
+    revenueBreakdown(symbol: string, options?: {
+        breakdownType?: 'segment' | 'product' | 'region';
+    }): Promise<FinancialStatement[]>;
+    /**
+     * Get historical stock prices
+     *
+     * @param symbol - Stock symbol
+     * @param options - Query options
+     */
+    prices(symbol: string, options?: {
+        startDate?: string;
+        endDate?: string;
+        limit?: number;
+    }): Promise<PriceData[]>;
+    /**
+     * Get K-line (candlestick) data
+     *
+     * @param symbol - Stock symbol
+     * @param options - Query options
+     */
+    kline(symbol: string, options?: {
+        interval?: Interval;
+        adjust?: PriceAdjust;
+        startDate?: string;
+        endDate?: string;
+        limit?: number;
+    }): Promise<PriceData[]>;
+    /**
+     * Get real-time stock quotes
+     *
+     * @param symbols - Single symbol or array of symbols
+     */
+    quote(symbols: string | string[]): Promise<Quote[]>;
+    /**
+     * Get stock index prices
+     *
+     * @param symbol - Index symbol
+     * @param options - Query options
+     */
+    indexPrices(symbol: string, options?: {
+        startDate?: string;
+        endDate?: string;
+        limit?: number;
+    }): Promise<PriceData[]>;
+    /**
+     * Screen stocks based on various criteria
+     */
+    screener(options?: {
+        market?: string;
+        sector?: string;
+        minMarketCap?: number;
+        maxMarketCap?: number;
+        minPe?: number;
+        maxPe?: number;
+        limit?: number;
+    }): Promise<CompanyOverview[]>;
+    /**
+     * Get earnings announcement calendar
+     */
+    earningsCalendar(options?: {
+        area?: Market;
+        startDate?: string;
+        endDate?: string;
+        symbol?: string;
+    }): Promise<EarningsEvent[]>;
+    /**
+     * Get Hong Kong IPO calendar
+     */
+    ipoCalendarHK(status?: IPOStatus): Promise<IPOEvent[]>;
+    private normalizeArrayResponse;
+}
+
+/**
+ * Timeline Module
+ *
+ * Provides access to timeline feeds based on user's followed entities.
+ */
+
+declare class TimelineModule {
+    private client;
+    constructor(client: Reportify);
+    /**
+     * Get timeline for followed companies
+     *
+     * Returns recent content related to companies the user is following.
+     *
+     * @param options.num - Number of items to return (default: 10, max: 100)
+     */
+    companies(options?: TimelineOptions): Promise<Document[]>;
+    /**
+     * Get timeline for followed topics
+     *
+     * Returns recent content related to custom topics the user is following.
+     *
+     * @param options.num - Number of items to return
+     */
+    topics(options?: TimelineOptions): Promise<Document[]>;
+    /**
+     * Get timeline for followed professional institutes
+     *
+     * Returns recent content from research institutions, banks, etc.
+     *
+     * @param options.num - Number of items to return
+     */
+    institutes(options?: TimelineOptions): Promise<Document[]>;
+    /**
+     * Get timeline for followed public media
+     *
+     * Returns recent content from public media accounts.
+     *
+     * @param options.num - Number of items to return
+     */
+    publicMedia(options?: TimelineOptions): Promise<Document[]>;
+    /**
+     * Get timeline for followed social media
+     *
+     * Returns recent content from social media accounts.
+     *
+     * @param options.num - Number of items to return
+     */
+    socialMedia(options?: TimelineOptions): Promise<Document[]>;
+}
+
+/**
+ * Knowledge Base Module
+ *
+ * Provides access to user's personal knowledge base for searching
+ * uploaded documents.
+ */
+
+declare class KBModule {
+    private client;
+    constructor(client: Reportify);
+    /**
+     * Search user's knowledge base
+     *
+     * Performs semantic search across documents the user has uploaded.
+     *
+     * @param query - Search query string
+     * @param options - Search options
+     *
+     * @example
+     * ```typescript
+     * const results = await client.kb.search('quarterly revenue', { num: 5 });
+     * results.forEach(chunk => console.log(chunk.content));
+     * ```
+     */
+    search(query: string, options?: KBSearchOptions): Promise<Chunk[]>;
+}
+
+/**
+ * Documents Module
+ *
+ * Provides access to document content, metadata, and summaries.
+ */
+
+interface DocContent {
+    docId: string;
+    title: string;
+    content?: string;
+    chunks?: Chunk[];
+    fileUrl?: string;
+    mediaUrl?: string;
+    [key: string]: unknown;
+}
+interface DocSummary {
+    docId: string;
+    title: string;
+    summary: string;
+    keyPoints?: string[];
+    [key: string]: unknown;
+}
+interface DocsListOptions {
+    symbols?: string[];
+    categories?: string[];
+    startDate?: string;
+    endDate?: string;
+    page?: number;
+    pageSize?: number;
+}
+interface ChunkSearchOptions {
+    symbols?: string[];
+    categories?: string[];
+    startDate?: string;
+    endDate?: string;
+    num?: number;
+}
+declare class DocsModule {
+    private client;
+    constructor(client: Reportify);
+    /**
+     * Get document content and metadata
+     *
+     * @param docId - Document ID
+     */
+    get(docId: string): Promise<DocContent>;
+    /**
+     * Get document summary
+     *
+     * @param docId - Document ID
+     */
+    summary(docId: string): Promise<DocSummary>;
+    /**
+     * Get raw document content
+     *
+     * @param docId - Document ID
+     */
+    rawContent(docId: string): Promise<DocContent>;
+    /**
+     * List documents with filters
+     *
+     * @param options - Filter options
+     */
+    list(options?: DocsListOptions): Promise<PaginatedResponse<Document>>;
+    /**
+     * Search document chunks semantically
+     *
+     * @param query - Search query string
+     * @param options - Search options
+     */
+    searchChunks(query: string, options?: ChunkSearchOptions): Promise<Chunk[]>;
+}
+
+/**
+ * Reportify Client
+ *
+ * Main client class for interacting with the Reportify API.
+ */
+
+/**
+ * Reportify API Client
+ *
+ * A user-friendly client for accessing financial data, document search,
+ * and knowledge base through the Reportify API.
+ *
+ * @example
+ * ```typescript
+ * import { Reportify } from 'reportify-sdk';
+ *
+ * const client = new Reportify({ apiKey: 'your-api-key' });
+ * const docs = await client.search('Tesla earnings', { num: 10 });
+ * ```
+ */
+declare class Reportify {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    readonly stock: StockModule;
+    readonly timeline: TimelineModule;
+    readonly kb: KBModule;
+    readonly docs: DocsModule;
+    constructor(config: ReportifyConfig);
+    /**
+     * Make an HTTP request to the API
+     */
+    request<T = unknown>(method: string, path: string, options?: {
+        params?: Record<string, unknown>;
+        body?: Record<string, unknown>;
+    }): Promise<T>;
+    /**
+     * Make a GET request
+     */
+    get<T = unknown>(path: string, params?: Record<string, unknown>): Promise<T>;
+    /**
+     * Make a POST request
+     */
+    post<T = unknown>(path: string, body?: Record<string, unknown>): Promise<T>;
+    /**
+     * Search documents across all categories
+     *
+     * @param query - Search query string
+     * @param options - Search options
+     * @returns List of matching documents
+     *
+     * @example
+     * ```typescript
+     * const docs = await client.search('Tesla earnings', { num: 10 });
+     * docs.forEach(doc => console.log(doc.title));
+     * ```
+     */
+    search(query: string, options?: SearchOptions): Promise<Document[]>;
+    /**
+     * Search news articles
+     */
+    searchNews(query: string, options?: SearchOptions): Promise<Document[]>;
+    /**
+     * Search research reports
+     */
+    searchReports(query: string, options?: SearchOptions): Promise<Document[]>;
+    /**
+     * Search company filings
+     */
+    searchFilings(query: string, options?: SearchOptions): Promise<Document[]>;
+    /**
+     * Search earnings call transcripts
+     */
+    searchTranscripts(query: string, options?: SearchOptions): Promise<Document[]>;
+}
+
+export { APIError, AuthenticationError, type Chunk, type CompanyInfo, type CompanyOverview, DocsModule, type Document, type EarningsEvent, type FinancialStatement, type IPOEvent, type IPOStatus, type Interval, KBModule, type KBSearchOptions, type Market, NotFoundError, type PaginatedResponse, type Period, type PriceAdjust, type PriceData, type Quote, RateLimitError, Reportify, type ReportifyConfig, ReportifyError, type SearchOptions, type Shareholder, type StockInfo, StockModule, TimelineModule, type TimelineOptions };