@echoscan/echoscan 0.1.0

package/README.md

@@ -0,0 +1,149 @@
+# `@echoscan/echoscan` (Node)
+
+中文 | [English](#english)
+
+## 中文
+
+### 安装
+
+```bash
+npm install @echoscan/echoscan
+```
+
+### 可用调用方式
+
+```js
+import { createLiteClient, createProClient } from '@echoscan/echoscan';
+```
+
+Lite（匿名）：
+
+```js
+const lite = createLiteClient();
+const report = await lite.getReport(imprint);
+```
+
+Pro（需要 apiKey）：
+
+```js
+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）。
+
+```js
+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()` 顶层结构：
+
+```json
+{
+  "analysis": {},
+  "lyingCount": 0,
+  "projection": {}
+}
+```
+
+`getHistory()` 顶层结构：
+
+```json
+{
+  "imprint": "fp_session_...",
+  "range": {},
+  "recent": [],
+  "summary": {},
+  "timeline": []
+}
+```
+
+完整字段说明链接：[echoscan](https://echoscan.org)
+
+---
+
+## English
+
+### Install
+
+```bash
+npm install @echoscan/echoscan
+```
+
+### Usage
+
+```js
+import { createLiteClient, createProClient } from '@echoscan/echoscan';
+```
+
+Lite (anonymous):
+
+```js
+const lite = createLiteClient();
+const report = await lite.getReport(imprint);
+```
+
+Pro (apiKey required):
+
+```js
+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).
+
+```js
+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:
+
+```json
+{
+  "analysis": {},
+  "lyingCount": 0,
+  "projection": {}
+}
+```
+
+`getHistory()` top-level shape:
+
+```json
+{
+  "imprint": "fp_session_...",
+  "range": {},
+  "recent": [],
+  "summary": {},
+  "timeline": []
+}
+```
+
+Full field reference: [echoscan](https://echoscan.org)

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@echoscan/echoscan",
+  "version": "0.1.0",
+  "description": "EchoScan package for Node.js",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.mjs",
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT"
+}

package/src/index.d.ts

@@ -0,0 +1,51 @@
+export type EchoScanApiErrorCode =
+  | 'invalid_request'
+  | 'auth_failed'
+  | 'forbidden'
+  | 'not_found'
+  | 'quota_exceeded'
+  | 'timeout'
+  | 'upstream_unavailable'
+  | 'network_error'
+  | 'unknown_error';
+
+export type EchoScanApiError = Error & {
+  name: 'EchoScanApiError';
+  code: EchoScanApiErrorCode;
+  httpStatus: number;
+  message: string;
+  requestId: string | null;
+  retryable: boolean;
+};
+
+export type HistoryQuery =
+  | {
+      days: number;
+      from?: never;
+      to?: never;
+      recent?: number;
+    }
+  | {
+      days?: never;
+      from: string;
+      to: string;
+      recent?: number;
+    };
+
+export type LiteClient = {
+  getReport(imprint: string): Promise<unknown>;
+};
+
+export type ProClient = {
+  getReport(imprint: string): Promise<unknown>;
+  getHistory(imprint: string, query?: HistoryQuery): Promise<unknown>;
+};
+
+export type DebugClient = {
+  getReport(imprint: string): Promise<unknown>;
+  getDetails(imprint: string): Promise<unknown>;
+};
+
+export function createLiteClient(): LiteClient;
+export function createProClient(input: { apiKey: string }): ProClient;
+export function createDebugClient(input: { apiKey: string }): DebugClient;

package/src/index.mjs

@@ -0,0 +1,286 @@
+const DEFAULT_BASE_URL = 'https://api.echoscan.org';
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_RETRIES = 2;
+const SDK_USER_AGENT = 'echoscan-node/0.1.0';
+
+function parseIntEnv(name, fallback) {
+  const value = process.env[name];
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    return fallback;
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function normalizeBaseUrl(rawBaseUrl) {
+  const baseUrl = typeof rawBaseUrl === 'string' && rawBaseUrl.trim().length > 0
+    ? rawBaseUrl.trim()
+    : DEFAULT_BASE_URL;
+  return baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+}
+
+function buildRuntimeConfig() {
+  return {
+    baseUrl: normalizeBaseUrl(process.env.ECHOSCAN_SERVER_BASE_URL),
+    timeoutMs: parseIntEnv('ECHOSCAN_SERVER_TIMEOUT_MS', DEFAULT_TIMEOUT_MS),
+    retries: parseIntEnv('ECHOSCAN_SERVER_RETRIES', DEFAULT_RETRIES),
+  };
+}
+
+function generateRequestId() {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return `req_${crypto.randomUUID()}`;
+  }
+  return `req_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function buildApiError(code, httpStatus, requestId, retryable) {
+  const messages = {
+    invalid_request: 'Invalid request',
+    auth_failed: 'Authentication failed',
+    forbidden: 'Forbidden',
+    not_found: 'Not found',
+    quota_exceeded: 'Quota exceeded',
+    timeout: 'Request timed out',
+    upstream_unavailable: 'Upstream service unavailable',
+    network_error: 'Network error',
+    unknown_error: 'Unexpected error',
+  };
+
+  const error = new Error(messages[code] ?? messages.unknown_error);
+  error.name = 'EchoScanApiError';
+  error.code = code;
+  error.httpStatus = httpStatus;
+  error.requestId = requestId ?? null;
+  error.retryable = retryable;
+  return error;
+}
+
+function mapHttpStatusToCode(status) {
+  if (status === 400) return 'invalid_request';
+  if (status === 401) return 'auth_failed';
+  if (status === 403) return 'forbidden';
+  if (status === 404) return 'not_found';
+  if (status === 408) return 'timeout';
+  if (status === 429) return 'quota_exceeded';
+  if (status === 500 || status === 502 || status === 503 || status === 504) {
+    return 'upstream_unavailable';
+  }
+  return 'unknown_error';
+}
+
+function assertApiKey(apiKey, role) {
+  const normalized = typeof apiKey === 'string' ? apiKey.trim() : '';
+  if (normalized.length === 0) {
+    throw new Error(`apiKey is required for ${role} client`);
+  }
+  return normalized;
+}
+
+function assertImprint(imprint) {
+  if (typeof imprint !== 'string' || imprint.trim().length === 0) {
+    throw new Error('imprint must be a non-empty string');
+  }
+  return imprint.trim();
+}
+
+function assertDateValue(value, field) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    throw new Error(`${field} must use YYYY-MM-DD format`);
+  }
+  return value;
+}
+
+function buildHistoryQuery(query = {}) {
+  if (!query || typeof query !== 'object') {
+    throw new Error('history query must be an object');
+  }
+
+  const hasDays = Object.prototype.hasOwnProperty.call(query, 'days');
+  const hasFrom = Object.prototype.hasOwnProperty.call(query, 'from');
+  const hasTo = Object.prototype.hasOwnProperty.call(query, 'to');
+
+  if (hasDays && (hasFrom || hasTo)) {
+    throw new Error('history query: days and from/to are mutually exclusive');
+  }
+
+  if (hasFrom !== hasTo) {
+    throw new Error('history query: from and to must be provided together');
+  }
+
+  const params = new URLSearchParams();
+
+  if (hasDays) {
+    const days = Number(query.days);
+    if (!Number.isFinite(days) || days <= 0) {
+      throw new Error('history query: days must be a positive number');
+    }
+    params.set('days', String(Math.trunc(days)));
+  }
+
+  if (hasFrom && hasTo) {
+    const from = assertDateValue(query.from, 'from');
+    const to = assertDateValue(query.to, 'to');
+    if (from > to) {
+      throw new Error('history query: from must be <= to');
+    }
+    params.set('from', from);
+    params.set('to', to);
+  }
+
+  if (Object.prototype.hasOwnProperty.call(query, 'recent')) {
+    const recent = Number(query.recent);
+    if (!Number.isFinite(recent) || recent <= 0) {
+      throw new Error('history query: recent must be a positive number');
+    }
+    params.set('recent', String(Math.trunc(recent)));
+  }
+
+  const queryString = params.toString();
+  return queryString.length > 0 ? `?${queryString}` : '';
+}
+
+async function decodeJsonSafely(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+async function performGet({
+  baseUrl,
+  path,
+  apiKey,
+  timeoutMs,
+  retries,
+  fetchImpl,
+}) {
+  const url = `${baseUrl}${path}`;
+  const maxAttempts = retries + 1;
+  let lastError = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    const requestId = generateRequestId();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      const headers = {
+        Accept: 'application/json',
+        'User-Agent': SDK_USER_AGENT,
+        'X-Request-Id': requestId,
+      };
+      if (apiKey) {
+        headers['X-API-Key'] = apiKey;
+      }
+
+      const response = await fetchImpl(url, {
+        method: 'GET',
+        headers,
+        signal: controller.signal,
+      });
+      clearTimeout(timer);
+
+      if (response.ok) {
+        return await decodeJsonSafely(response);
+      }
+
+      const body = await decodeJsonSafely(response);
+      const responseRequestId = response.headers?.get?.('x-request-id')
+        ?? body?.requestId
+        ?? body?.request_id
+        ?? requestId;
+      const code = mapHttpStatusToCode(response.status);
+      const retryable = attempt < maxAttempts && (response.status >= 500 || response.status === 429);
+      lastError = buildApiError(code, response.status, responseRequestId, retryable);
+      if (retryable) {
+        continue;
+      }
+      throw lastError;
+    } catch (error) {
+      clearTimeout(timer);
+
+      if (error?.name === 'EchoScanApiError') {
+        throw error;
+      }
+
+      const isAbortError = error?.name === 'AbortError';
+      const code = isAbortError ? 'timeout' : 'network_error';
+      const retryable = attempt < maxAttempts;
+      lastError = buildApiError(code, isAbortError ? 408 : 0, requestId, retryable);
+
+      if (retryable) {
+        continue;
+      }
+      throw lastError;
+    }
+  }
+
+  throw lastError ?? buildApiError('unknown_error', 0, null, false);
+}
+
+function createBaseClient(apiKey) {
+  const runtime = buildRuntimeConfig();
+  const fetchImpl = globalThis.fetch?.bind(globalThis);
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('global fetch is unavailable in this runtime');
+  }
+
+  const get = (path) => performGet({
+    baseUrl: runtime.baseUrl,
+    path,
+    apiKey,
+    timeoutMs: runtime.timeoutMs,
+    retries: runtime.retries,
+    fetchImpl,
+  });
+
+  return { get };
+}
+
+export function createLiteClient() {
+  const client = createBaseClient(null);
+  return {
+    getReport(imprint) {
+      const normalizedImprint = assertImprint(imprint);
+      return client.get(`/api/v1/fingerprint/report-lite/${encodeURIComponent(normalizedImprint)}`);
+    },
+  };
+}
+
+export function createProClient({ apiKey } = {}) {
+  const normalizedApiKey = assertApiKey(apiKey, 'pro');
+  const client = createBaseClient(normalizedApiKey);
+
+  return {
+    getReport(imprint) {
+      const normalizedImprint = assertImprint(imprint);
+      return client.get(`/api/v1/fingerprint/report/${encodeURIComponent(normalizedImprint)}`);
+    },
+    getHistory(imprint, query = {}) {
+      const normalizedImprint = assertImprint(imprint);
+      const queryString = buildHistoryQuery(query);
+      return client.get(`/api/v1/fingerprint/imprint/${encodeURIComponent(normalizedImprint)}/history${queryString}`);
+    },
+  };
+}
+
+export function createDebugClient({ apiKey } = {}) {
+  const normalizedApiKey = assertApiKey(apiKey, 'debug');
+  const client = createBaseClient(normalizedApiKey);
+
+  return {
+    getReport(imprint) {
+      const normalizedImprint = assertImprint(imprint);
+      return client.get(`/api/v1/internal/fingerprint/report/${encodeURIComponent(normalizedImprint)}`);
+    },
+    getDetails(imprint) {
+      const normalizedImprint = assertImprint(imprint);
+      return client.get(`/api/v1/internal/fingerprint/details/${encodeURIComponent(normalizedImprint)}`);
+    },
+  };
+}