IonoFlux Node.js SDK

1. Server 키 만들기

계정 페이지에서 로그인한 뒤 Server API 키를 만드세요. 이 SDK는 Node.js 전용입니다. 키는 백엔드에만 보관하고 브라우저·React 클라이언트 번들, HTML, 로그, 소스 저장소에 넣지 마세요.

Server 키 발급에는 서비스 URL이 필요합니다. 기존 서비스 정책에 맞는 URL을 사용하세요. SDK는 키를 발급하거나 이 요구를 우회하지 않습니다.

export IONOFLUX_API_KEY='your-server-key'

2. 빠른 시작

import { Client } from 'ionoflux';

const client = new Client();
try {
  const current = await client.spaceWeather.current();
  console.log(current.data);
  console.log(current.rateLimit.remaining);
} finally {
  client.close();
}

new Client()는 IONOFLUX_API_KEY에서 키를 읽고 apiKey 옵션이 이를 우선합니다. ESM 예제는 .mjs 파일이나 type: module 패키지에서 실행하세요. 시각은 유효한 Date 또는 Z/시간대 오프셋이 있는 ISO 문자열을 받아 UTC로 보냅니다. sources()와 data.status()는 키 없이 호출하며 설정된 키도 보내지 않습니다.

import { Client, RateLimitError } from 'ionoflux';

const client = new Client({ timeoutMs: 10000, maxRetries: 1 });
try {
  const series = await client.solar.flux({
    start: '2026-10-01T00:00:00Z',
    end: '2026-10-02T00:00:00Z',
    interval: '1h', limit: 100,
  });
  console.log(series.data.unit, series.data.attribution);
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(error.retryAfter, error.rateLimit.resetSeconds);
  } else {
    throw error;
  }
} finally {
  client.close();
}

CommonJS도 지원합니다. 아래 require로 불러온 뒤 async 함수 안에서 동일한 Promise 메서드를 호출하세요. TypeScript 타입 선언도 포함되어 있습니다.

const { Client } = require('ionoflux');

지원 호출

모든 Promise는 data(원본 JSON 필드), rawBody(바이트), statusCode, 안전한 headers, rateLimit을 가진 APIResponse를 반환합니다. 입력 옵션은 camelCase, 반환 JSON 필드 이름은 원래 형식입니다. 시계열은 start, end, interval, limit 옵션을 공통으로 씁니다.

전리층·전파 예측·실측 수신 보고

0.1.3부터 지원하며 모두 Server 키가 필요합니다. 위치는 "lat,lon", Maidenhead 로케이터 또는 지명을 받습니다. 범위를 벗어난 인자는 요청 전에 RangeError를 발생시킵니다.

import { Client } from 'ionoflux';

const client = new Client();
try {
  const muf = await client.ionosphere.muf({ lat: 37.57, lon: 126.98 });
  console.log(muf.data.muf_mhz, muf.data.attribution);

  const path = await client.propagation.path({
    from: 'Seoul, South Korea', to: 'FN20', frequency: 14.074, mode: 'ft8',
  });
  console.log(path.data.prediction, path.data.model);

  const heard = await client.observations.paths({
    from: 'PM37', to: 'PM95', hours: 1, band: '20m',
  });
  console.log(heard.data.a_to_b);
} finally {
  client.close();
}

모델 TEC/MUF와 모든 전파 예측 결과는 NOAA GloTEC 지도 기반 모델 출력이고, 이오노존데 MUF와 관측소는 실측값입니다. 수신 보고는 그 순간의 한 방향 전파를 증명하지만, 보고가 없다고 밴드가 닫혔다는 뜻은 아닙니다. 각 응답의 attribution을 유지하세요. WSPRnet 데이터는 상업적으로 이용할 수 없습니다.

지원 범위와 제약

현재 Node.js 22+ 전용이며 브라우저/React 클라이언트, 지도 렌더링, 대량·과거 수신 보고 다운로드는 제공하지 않습니다. 다른 작업은 REST API를 이용하세요. SDK는 HTTPS만 사용하고 리다이렉트를 따르지 않습니다.

timeoutMs 기본값은 각 시도 전체(본문 수신 포함) 10000ms입니다. maxRetries는 기본 1회/최대 3회이며 일부 일시 네트워크 장애와 HTTP 502/503/504에만 적용됩니다. Retry-After 또는 잔여 한도 0이면 HTTP 재시도를 하지 않고, 429는 자동 재시도하지 않습니다. 재시도도 한도를 사용할 수 있습니다. close()는 진행 중 요청을 취소하지만 Node.js 공유 fetch 연결 풀은 종료하지 않습니다.

자세히: API 옵션과 제약 · 변경 기록 · 한국어 README

라이선스와 약관

SDK 코드는 PolyForm Noncommercial License 1.0.0를 따릅니다. 개인·취미 사용과 라이선스가 명시한 교육·연구 등 기관 사용을 포함한 비상업적 사용을 허용합니다. 그 범위를 벗어난 상업적 사용에는 별도 서면 라이선스가 필요하며, OSI 오픈소스 라이선스가 아닙니다.

SDK를 재배포할 때는 라이선스 조항과 NOTICE의 Required Notice를 유지하세요:

Required Notice: IonoFlux (https://ionoflux.runvia.app)

SDK 라이선스는 코드에만 적용됩니다. API 이용, API 결과의 출처 표기, 원 제공 기관의 데이터 라이선스는 별개이므로 각 응답의 source와 attribution을 유지해 주세요.