> ## Documentation Index
> Fetch the complete documentation index at: https://docs.benzinga.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Benzinga Node.js SDK

<div id="overview">
  ## 개요
</div>

Benzinga TypeScript/JavaScript SDK는 Benzinga API와 상호작용하기 위한 모듈식, 이벤트 기반 인터페이스를 제공합니다. TypeScript로 작성된 이 SDK는 브라우저와 Node.js 환경 모두에서 원활하게 동작하며, 캐싱, 깊은 비교(deep comparison) 및 기타 고급 기능을 포함한 향상된 구현을 제공합니다.

<div id="key-features">
  ## 주요 기능
</div>

* **TypeScript 지원** - 완전한 TypeScript 타입과 인터페이스 제공
* **범용** - 브라우저와 Node.js 환경 모두에서 동작
* **모듈형 아키텍처** - 필요한 모듈만 설치 가능
* **이벤트 기반** - 실시간 데이터를 위한 반응형 프로그래밍 패턴
* **고급 기능** - 내장 캐싱, 깊은 비교, 각종 최적화 기능
* **최신** - async/await를 지원하는 ES6+ 문법

<div id="requirements">
  ## 요구 사항
</div>

* **Node.js 14 이상**

<div id="installation">
  ## 설치
</div>

SDK는 모듈형 아키텍처를 사용합니다. 먼저 핵심 세션 모듈을 설치하세요:

```bash theme={null}
npm install @benzinga/session
```

그다음 필요에 따라 추가 모듈을 설치하세요:

```bash theme={null}
# 예제: 특정 모듈 설치
npm install @benzinga/calendar-data
npm install @benzinga/quotes
npm install @benzinga/news-data
```

<div id="getting-started">
  ## 시작하기
</div>

<div id="session-setup">
  ### 세션 설정
</div>

`@benzinga/session` 모듈은 Benzinga API 인증을 위한 기반을 제공합니다. 다른 모든 모듈은 이 Session 객체에 의존합니다.

```typescript theme={null}
import { Session } from '@benzinga/session';

// API 키를 사용하여 세션 초기화
const session = new Session({
  apiKey: 'YOUR_API_KEY'
});
```

<div id="configuration-options">
  ### 구성 옵션
</div>

`Session` 객체는 동작을 사용자 정의하기 위한 다양한 구성 옵션을 허용합니다:

```typescript theme={null}
const session = new Session({
  apiKey: 'YOUR_API_KEY',
  environment: 'production', // 또는 'sandbox'
  timeout: 30000,            // 요청 타임아웃(밀리초 단위)
  // 추가 구성 옵션
});
```

<div id="core-concepts">
  ## 핵심 개념
</div>

<div id="modular-design">
  ### 모듈형 설계
</div>

각 Benzinga API 도메인은 별도의 npm 모듈로 패키징됩니다. 이를 통해 다음과 같은 일을 할 수 있습니다:

* 필요한 모듈만 설치
* 번들 크기 축소
* 관심사를 명확히 분리
* 모듈을 독립적으로 업데이트

<div id="event-based-architecture">
  ### 이벤트 기반 아키텍처
</div>

SDK는 실시간 데이터 스트림 및 업데이트를 처리하기 위해 이벤트 기반 패턴을 사용합니다:

```typescript theme={null}
// 예시: 데이터 업데이트 구독
dataManager.subscribe((data) => {
  console.log('New data received:', data);
});

// Example: Handle events
dataManager.on('update', (event) => {
  console.log('Data updated:', event);
});
```

<div id="caching-performance">
  ### 캐싱 및 성능
</div>

SDK에는 다음을 위한 내장 캐싱 메커니즘이 포함되어 있습니다:

* 불필요한 API 호출 감소
* 응답 시간 개선
* 대역폭 사용 최적화
* 오프라인 대체 기능 제공

<div id="deep-comparison">
  ### 심층 비교
</div>

고급 데이터 비교 기능을 통해 다음을 수행할 수 있습니다:

* 중첩 객체 변경 사항 감지
* 효율적인 상태 관리
* 스마트한 업데이트 트리거
* UI 애플리케이션에서 불필요한 리렌더링 감소

<div id="available-modules">
  ## 사용 가능한 모듈
</div>

SDK는 각기 다른 API 도메인에 맞춰 특화된 모듈로 구성되어 있습니다.

<div id="core-modules">
  ### 코어 모듈
</div>

* **`@benzinga/session`** - 인증 및 세션 관리 (필수)
* **`@benzinga/calendar-data`** - 캘린더 이벤트 및 기업 행동
* **`@benzinga/news-data`** - 뉴스 기사 및 시장 정보
* **`@benzinga/quotes`** - 실시간 및 지연 시세
* **`@benzinga/fundamentals`** - 기업 기초 재무 지표 및 재무 데이터

<div id="specialized-modules">
  ### 전용 모듈
</div>

* **`@benzinga/ratings`** - 애널리스트 등급 및 목표가
* **`@benzinga/options`** - 옵션 거래 동향 및 분석
* **`@benzinga/transcripts`** - 실적 발표 콜 녹취록
* **`@benzinga/logos`** - 기업 로고 및 브랜딩
* **`@benzinga/signals`** - 거래 시그널 및 지표

<div id="typescript-support">
  ## TypeScript 지원
</div>

이 SDK는 TypeScript로 작성되었으며 완전한 타입 정의를 제공합니다:

```typescript theme={null}
import { Session } from '@benzinga/session';
import { CalendarData, DividendEvent } from '@benzinga/calendar-data';

// TypeScript는 자동 완성 및 타입 검사를 제공합니다
const session = new Session({ apiKey: 'YOUR_API_KEY' });
const calendar = new CalendarData(session);

// 타입 안전 API 호출
const dividends: DividendEvent[] = await calendar.getDividends({
  dateFrom: '2024-01-01',
  dateTo: '2024-12-31',
  ticker: 'AAPL'
});
```

<div id="usage-examples">
  ## 사용 예제
</div>

<div id="basic-data-fetching">
  ### 기본 데이터 조회
</div>

```typescript theme={null}
import { Session } from '@benzinga/session';
import { NewsData } from '@benzinga/news-data';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const news = new NewsData(session);

// 최신 뉴스 가져오기
const articles = await news.getNews({
  pageSize: 10,
  displayOutput: 'full'
});

console.log(articles);
```

<div id="real-time-data-streams">
  ### 실시간 데이터 스트림
</div>

```typescript theme={null}
import { Session } from '@benzinga/session';
import { QuoteStream } from '@benzinga/quotes';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const quoteStream = new QuoteStream(session);

// 실시간 시세 구독
quoteStream.subscribe(['AAPL', 'MSFT', 'GOOGL'], (quote) => {
  console.log('Quote update:', quote);
});

// 완료되면 구독 해제
quoteStream.unsubscribe(['AAPL']);
```

<div id="calendar-events">
  ### calendar 이벤트
</div>

```typescript theme={null}
import { Session } from '@benzinga/session';
import { CalendarData } from '@benzinga/calendar-data';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const calendar = new CalendarData(session);

// 예정된 실적 조회
const earnings = await calendar.getEarnings({
  dateFrom: '2024-01-01',
  dateTo: '2024-01-31',
  importance: 3  // 높은 중요도만 해당
});

// 배당 정보 조회
const dividends = await calendar.getDividends({
  ticker: 'AAPL'
});
```

<div id="company-fundamentals">
  ### 기업의 기초 재무 지표
</div>

```typescript theme={null}
import { Session } from '@benzinga/session';
import { Fundamentals } from '@benzinga/fundamentals';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const fundamentals = new Fundamentals(session);

// 회사 프로필 가져오기
const profile = await fundamentals.getCompanyProfile('AAPL');

// 밸류에이션 비율 가져오기
const valuationRatios = await fundamentals.getValuationRatios('AAPL');

// 재무제표 가져오기
const financials = await fundamentals.getFinancials('AAPL');
```

<div id="browser-usage">
  ## 브라우저에서 사용
</div>

SDK는 Webpack, Rollup, Vite와 같은 번들러를 사용하는 브라우저 환경에서도 동작합니다.

```typescript theme={null}
// React, Vue 또는 Angular 애플리케이션에서
import { Session } from '@benzinga/session';
import { NewsData } from '@benzinga/news-data';

export function NewsComponent() {
  const session = new Session({ apiKey: process.env.BENZINGA_API_KEY });
  const news = new NewsData(session);

  // 컴포넌트 로직에서 사용
  useEffect(() => {
    news.getNews({ pageSize: 5 }).then(articles => {
      setNewsData(articles);
    });
  }, []);
}
```

<div id="error-handling">
  ## 오류 처리
</div>

try-catch 블록으로 오류를 적절히 처리하세요:

```typescript theme={null}
import { Session } from '@benzinga/session';
import { NewsData } from '@benzinga/news-data';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const news = new NewsData(session);

try {
  const articles = await news.getNews({ pageSize: 10 });
  console.log(articles);
} catch (error) {
  if (error.code === 'UNAUTHORIZED') {
    console.error('잘못된 API 키');
  } else if (error.code === 'RATE_LIMIT') {
    console.error('속도 제한 초과됨');
  } else {
    console.error('오류 발생:', error.message);
  }
}
```

<div id="pagination">
  ## 페이지네이션
</div>

페이지네이션 결과를 효율적으로 처리하십시오:

```typescript theme={null}
import { Session } from '@benzinga/session';
import { NewsData } from '@benzinga/news-data';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const news = new NewsData(session);

// 여러 페이지 가져오기
let page = 0;
let allArticles = [];

while (page < 5) {
  const articles = await news.getNews({
    page: page,
    pageSize: 100
  });

  if (articles.length === 0) break;

  allArticles = allArticles.concat(articles);
  page++;
}

console.log(`Fetched ${allArticles.length} articles`);
```

<div id="caching-strategy">
  ## 캐싱 전략
</div>

성능 향상을 위해 내장된 캐싱 기능을 활용하세요:

```typescript theme={null}
import { Session } from '@benzinga/session';
import { CalendarData } from '@benzinga/calendar-data';

const session = new Session({
  apiKey: 'YOUR_API_KEY',
  cache: {
    enabled: true,
    ttl: 300000  // 5분간 캐시
  }
});

const calendar = new CalendarData(session);

// 첫 번째 호출은 API 요청
const earnings1 = await calendar.getEarnings({ ticker: 'AAPL' });

// 두 번째 호출은 캐시된 데이터 사용(TTL 내인 경우)
const earnings2 = await calendar.getEarnings({ ticker: 'AAPL' });
```

<div id="best-practices">
  ## 모범 사례
</div>

<div id="1-reuse-session-objects">
  ### 1. 세션 객체 재사용
</div>

애플리케이션 전역에서 재사용할 세션 인스턴스를 하나만 생성하세요:

```typescript theme={null}
// session.ts
export const globalSession = new Session({ apiKey: process.env.BENZINGA_API_KEY });

// 다른 파일들에서
import { globalSession } from './session';
const news = new NewsData(globalSession);
```

<div id="2-environment-variables">
  ### 2. 환경 변수
</div>

API 키를 환경 변수에 안전하게 저장하세요.

```typescript theme={null}
// .env 파일
BENZINGA_API_KEY=your_api_key_here

// 코드 내
const session = new Session({
  apiKey: process.env.BENZINGA_API_KEY
});
```

<div id="3-type-safety">
  ### 3. 타입 안전성
</div>

타입 안전한 API 상호 작용을 위해 TypeScript를 활용하십시오:

```typescript theme={null}
import type { NewsArticle, NewsParams } from '@benzinga/news-data';

const params: NewsParams = {
  pageSize: 10,
  displayOutput: 'full',
  ticker: 'AAPL'
};

const articles: NewsArticle[] = await news.getNews(params);
```

<div id="4-error-boundaries">
  ### 4. 에러 바운더리
</div>

프로덕션 환경에서는 에러 바운더리를 구현하십시오.

```typescript theme={null}
const safeApiCall = async (fn: () => Promise<any>) => {
  try {
    return await fn();
  } catch (error) {
    console.error('API Error:', error);
    // 오류 추적 서비스에 로그 기록
    return null;
  }
};

const articles = await safeApiCall(() => news.getNews({ pageSize: 10 }));
```

<div id="resources">
  ## 리소스
</div>

* **저장소(Repository)**: [github.com/Benzinga/benzinga-javascript-client](https://github.com/Benzinga/benzinga-javascript-client)
* **npm 패키지**: [@benzinga/session](https://www.npmjs.com/package/@benzinga/session)
* **API 키**: [cloud.benzinga.com](https://cloud.benzinga.com)
* **TypeScript**: 버전 4.0 이상
* **Node.js**: 버전 14 이상

<div id="module-documentation">
  ## 모듈 문서
</div>

특정 모듈에 대한 자세한 내용은 각 패키지의 README를 참조하십시오:

* `@benzinga/session` - 핵심 인증 및 구성
* `@benzinga/calendar-data` - calendar 이벤트 API
* `@benzinga/news-data` - 뉴스 및 기사 API
* `@benzinga/quotes` - 실시간 시세 API
* `@benzinga/fundamentals` - 기초 재무 지표 및 재무 정보 API

<div id="support">
  ## 지원
</div>

기술 지원이나 API 키 발급이 필요하면 [cloud.benzinga.com](https://cloud.benzinga.com)에서 Benzinga에 문의하세요.

<div id="contributing">
  ## 기여하기
</div>

Benzinga JavaScript SDK는 오픈 소스입니다. 누구나 기여하실 수 있습니다. 자세한 내용은 [GitHub 저장소](https://github.com/Benzinga/benzinga-javascript-client)를 방문하세요.