@echoscan/echoscan (Node)

中文 | English

中文

安装

npm install @echoscan/echoscan

可用调用方式

import { createLiteClient, createProClient } from '@echoscan/echoscan';

Lite（需要 apiKey）：

const lite = createLiteClient({ apiKey: process.env.ECHOSCAN_LITE_KEY });
const report = await lite.getReport(imprint);

Pro（需要 apiKey）：

const pro = createProClient({ apiKey: process.env.ECHOSCAN_PRO_KEY });
const report = await pro.getReport(imprint);
const history = await pro.getHistory(imprint, { days: 7 });

History 查询模式

仅 Pro 客户端可用（需要 Pro API Key）。

await pro.getHistory(imprint, { days: 7 });
await pro.getHistory(imprint, { from: '2026-03-01', to: '2026-03-18' });
await pro.getHistory(imprint, { from: '2026-03-01', to: '2026-03-18', recent: 20 });

规则：

• days 与 from/to 互斥
• from 和 to 必须成对出现
• 日期格式必须是 YYYY-MM-DD

返回值与错误

getReport() 顶层结构：

{
  "analysis": {},
  "lyingCount": 0,
  "projection": {}
}

getHistory() 顶层结构：

{
  "imprint": "fp_session_...",
  "range": {},
  "recent": [],
  "summary": {},
  "timeline": []
}

Geo 字段说明（重要）

• SDK 只透传服务端返回，不在客户端自行做 IP 地理定位。
• 若服务端仅有 GeoLite2-Country.mmdb，通常只能返回国家级 geo；region/city 可能为空。
• 若服务端 geo enrichment 不可用，返回会降级（例如仅有 country_hint 或无 geo 字段）。
• 若服务端 geo enrichment 可用，主要查看 projection.geo.data.geo_public，字段包括：country_code、country_name、region_code、region_name、city、timezone。
• projection.geo.data 还会带 confidence 与 geo_low_trust（例如 locale 与 IP 国家冲突）用于前端展示可信度提示。
• 受保护报表现在使用 analysis.ip 作为统一网络/IP 入口：status、access.ip、access.geo，以及 proxy.status / proxy.real_ip。
• 在存储/调试字段中：geo_source_ip 是主判定 IP（canonical/best-effort），geo_request_client_ip 是请求链路观测 IP（证据）；两者可能不同（代理或多跳网络常见）。
• confidence 与 geo_low_trust 评价的是主结果（geo_public + geo_source_ip），不是 geo_request_client_ip 的评分。
• 若你的产品对外展示 MaxMind GeoLite 数据，请附署名：This product includes GeoLite Data created by MaxMind, available from https://www.maxmind.com.

完整字段说明链接：echoscan

English

Install

npm install @echoscan/echoscan

Usage

import { createLiteClient, createProClient } from '@echoscan/echoscan';

Lite (apiKey required):

const lite = createLiteClient({ apiKey: process.env.ECHOSCAN_LITE_KEY });
const report = await lite.getReport(imprint);

Pro (apiKey required):

const pro = createProClient({ apiKey: process.env.ECHOSCAN_PRO_KEY });
const report = await pro.getReport(imprint);
const history = await pro.getHistory(imprint, { days: 7 });

History query modes

Pro-only (requires a Pro API key).

await pro.getHistory(imprint, { days: 7 });
await pro.getHistory(imprint, { from: '2026-03-01', to: '2026-03-18' });
await pro.getHistory(imprint, { from: '2026-03-01', to: '2026-03-18', recent: 20 });

Rules:

• days and from/to are mutually exclusive
• from and to must be provided together
• date format must be YYYY-MM-DD

Response and errors

getReport() top-level shape:

{
  "analysis": {},
  "lyingCount": 0,
  "projection": {}
}

getHistory() top-level shape:

{
  "imprint": "fp_session_...",
  "range": {},
  "recent": [],
  "summary": {},
  "timeline": []
}

Geo fields (important)

• The SDK forwards server responses and does not perform client-side IP geolocation.
• If the backend only has GeoLite2-Country.mmdb, geo is typically country-level only; region/city may be empty.
• If backend geo enrichment is unavailable, responses degrade (for example country_hint only, or no geo fields).
• When geo enrichment is available, the primary display payload is projection.geo.data.geo_public with fields: country_code, country_name, region_code, region_name, city, timezone.
• projection.geo.data also includes confidence and geo_low_trust (for example locale vs IP-country mismatch) for trust-aware UX.
• Protected reports now use analysis.ip as the unified network/IP surface: status, access.ip, access.geo, and proxy.status / proxy.real_ip.
• In storage/debug fields, geo_source_ip is the primary canonical (best-effort) lookup IP, while geo_request_client_ip is request-chain observed evidence; they may differ (common with proxies or multi-hop networks).
• confidence and geo_low_trust rate the primary result (geo_public derived from geo_source_ip), not geo_request_client_ip.
• If your product displays MaxMind GeoLite data externally, include attribution: This product includes GeoLite Data created by MaxMind, available from https://www.maxmind.com.

Full field reference: echoscan