reportify-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reportify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# Reportify SDK for TypeScript/JavaScript
+
+TypeScript SDK for Reportify API - Financial data and document search.
+
+## Installation
+
+```bash
+npm install reportify-sdk
+# or
+yarn add reportify-sdk
+# or
+pnpm add reportify-sdk
+```
+
+## Quick Start
+
+```typescript
+import { Reportify } from 'reportify-sdk';
+
+// Initialize client
+const client = new Reportify({ apiKey: 'your-api-key' });
+
+// Search documents
+const docs = await client.search('Tesla earnings', { num: 10 });
+docs.forEach(doc => console.log(doc.title));
+```
+
+## Features
+
+### Document Search
+
+```typescript
+// General search across all categories
+const docs = await client.search('revenue growth', { num: 10 });
+
+// Search specific document types
+const news = await client.searchNews('Apple iPhone', { num: 10 });
+const reports = await client.searchReports('semiconductor analysis', { num: 10 });
+const filings = await client.searchFilings('10-K annual report', { symbols: ['US:AAPL'] });
+const transcripts = await client.searchTranscripts('guidance', { symbols: ['US:TSLA'] });
+```
+
+### Stock Data
+
+```typescript
+// Financial statements
+const income = await client.stock.incomeStatement('US:AAPL', { period: 'quarterly' });
+const balance = await client.stock.balanceSheet('US:AAPL');
+const cashflow = await client.stock.cashflowStatement('US:AAPL');
+
+// Price data
+const prices = await client.stock.prices('US:AAPL', { limit: 30 });
+const kline = await client.stock.kline('US:TSLA', { interval: '1d', limit: 100 });
+
+// Real-time quotes
+const quotes = await client.stock.quote(['US:AAPL', 'US:MSFT']);
+
+// Company info
+const overview = await client.stock.overview('US:AAPL');
+const shareholders = await client.stock.shareholders('US:AAPL');
+
+// Screening and calendar
+const stocks = await client.stock.screener({ market: 'US', minMarketCap: 1e10 });
+const earnings = await client.stock.earningsCalendar({ area: 'us', startDate: '2024-01-01' });
+```
+
+### Timeline
+
+```typescript
+// Get timeline for followed entities
+const companies = await client.timeline.companies({ num: 20 });
+const topics = await client.timeline.topics({ num: 20 });
+const institutes = await client.timeline.institutes({ num: 20 });
+const publicMedia = await client.timeline.publicMedia({ num: 20 });
+const socialMedia = await client.timeline.socialMedia({ num: 20 });
+```
+
+### Knowledge Base
+
+```typescript
+// Search user's uploaded documents
+const chunks = await client.kb.search('quarterly revenue', { folderIds: ['folder_id'] });
+```
+
+### Documents
+
+```typescript
+// Get document content
+const doc = await client.docs.get('doc_id');
+const summary = await client.docs.summary('doc_id');
+
+// List and search documents
+const docs = await client.docs.list({ symbols: ['US:AAPL'], pageSize: 10 });
+const chunks = await client.docs.searchChunks('revenue breakdown', { num: 5 });
+```
+
+## Error Handling
+
+```typescript
+import {
+  Reportify,
+  AuthenticationError,
+  RateLimitError,
+  NotFoundError,
+  APIError,
+} from 'reportify-sdk';
+
+try {
+  const docs = await client.search('Tesla');
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.log('Invalid API key');
+  } else if (error instanceof RateLimitError) {
+    console.log('Rate limit exceeded, please wait');
+  } else if (error instanceof NotFoundError) {
+    console.log('Resource not found');
+  } else if (error instanceof APIError) {
+    console.log(`API error: ${error.message}`);
+  }
+}
+```
+
+## Configuration
+
+```typescript
+const client = new Reportify({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.reportify.cn',  // Optional: custom API URL
+  timeout: 30000,  // Optional: request timeout in milliseconds
+});
+```
+
+## TypeScript Support
+
+This SDK is written in TypeScript and provides full type definitions out of the box.
+
+```typescript
+import type {
+  Document,
+  CompanyOverview,
+  FinancialStatement,
+  PriceData,
+  Quote,
+} from 'reportify-sdk';
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

package/dist/index.d.mts

@@ -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 };