oritwoen/omnichron

# omnichron [](https://npmjs.com/package/omnichron) [](https://npm.chart.dev/omnichron) [](https://github.com/oritwoen/omnichron/blob/main/LICENSE) [](https://deepwiki.com/oritwoen/omnichron) 用于查询 Web Archive 提供商的统一 TypeScript 接口。一个 API，多个来源，一致的输出。 ## 特性 - 🔍 **多提供商支持** - Wayback Machine, Archive.today, Common Crawl, Perma.cc, WebCite - 🌳 **Tree-shakable** - 提供商通过动态导入延迟加载，仅打包您使用的内容 - 📦 **内置缓存** - 通过 [unstorage](https://github.com/unjs/unstorage) 提供可插拔的存储层，支持可配置 TTL - ⚡ **并行查询** - 并发控制、批处理、自动重试、可配置超时 - 🔧 **配置文件** - 通过 [c12](https://github.com/unjs/c12) 支持 `omnichron.config.ts`、`.omnichron` 和 `package.json` - 🏷️ **完全类型化** - 所有响应、选项和特定于提供商的元数据均提供 TypeScript 定义 ## 安装 ``` pnpm add omnichron ``` ## 用法 ``` import { createArchive, providers } from "omnichron"; const archive = createArchive(providers.wayback()); const response = await archive.snapshots("example.com", { limit: 100 }); if (response.success) { for (const page of response.pages) { console.log(page.url, page.timestamp, page.snapshot); } } ``` 使用 `providers.all()` 一次查询所有提供商（不包含 Perma.cc，因为它需要 API key）： ``` const archive = createArchive(providers.all()); const response = await archive.snapshots("example.com"); ``` 要选择特定的提供商，请将它们包装在 `Promise.all` 中： ``` const archive = createArchive( Promise.all([providers.wayback(), providers.archiveToday(), providers.commoncrawl()]), ); ``` ### Perma.cc Perma.cc 需要 API key： ``` const archive = createArchive(providers.permacc({ apiKey: "YOUR_API_KEY" })); ``` ### 错误处理 `snapshots()` 返回带有 `success` 标志的响应对象。如果您希望在失败时抛出异常，请使用 `getPages()`： ``` // safe - check success flag yourself const response = await archive.snapshots("example.com"); // throws on failure, returns pages array directly const pages = await archive.getPages("example.com"); ``` ## 提供商 | Provider | Factory | Notes | | --------------- | -------------------------- | ----------------------------------------- | | Wayback Machine | `providers.wayback()` | web.archive.org CDX API | | Archive.today | `providers.archiveToday()` | archive.ph via Memento timemap | | Common Crawl | `providers.commoncrawl()` | 默认为最新集合 | | Perma.cc | `providers.permacc()` | 需要 `apiKey` | | WebCite | `providers.webcite()` | 只读，不再接受新存档 | | All | `providers.all()` | 除 Perma.cc 外的所有上述提供商 | 您可以在创建后动态添加提供商： ``` const archive = createArchive(providers.wayback()); await archive.use(providers.archiveToday()); await archive.useAll([providers.commoncrawl(), providers.webcite()]); ``` ## 响应格式 每个提供商都将其输出标准化为相同的结构： ``` interface ArchiveResponse { success: boolean; pages: ArchivedPage[]; error?: string; _meta?: ResponseMetadata; fromCache?: boolean; } interface ArchivedPage { url: string; // original URL timestamp: string; // ISO 8601 snapshot: string; // direct link to the archived version _meta: Record; } ``` 每个页面上的 `_meta` 对象包含特定于提供商的字段。Wayback 在其原始格式中包含 `status` 和 `timestamp`。Common Crawl 添加了 `digest`、`mime`、`collection`。Perma.cc 包含 `guid`、`title`、`created_by`。Archive.today 提供 `hash` 和 `raw_date`。 ## 配置 omnichron 通过 [c12](https://github.com/unjs/c12) 加载配置，这意味着您可以通过配置文件、环境变量覆盖或 `package.json` 进行配置： ``` // omnichron.config.ts export default { storage: { cache: true, ttl: 7 * 24 * 60 * 60 * 1000, // 7 days prefix: "omnichron", }, performance: { concurrency: 3, batchSize: 20, timeout: 10_000, retries: 1, }, }; ``` 特定于环境的覆盖可通过 `$development`、`$production` 和 `$test` 键实现。 ### 自定义存储驱动 缓存层由 [unstorage](https://github.com/unjs/unstorage) 支持，因此任何 unstorage 驱动都可以工作： ``` import { configureStorage } from "omnichron"; import fsDriver from "unstorage/drivers/fs"; await configureStorage({ driver: fsDriver({ base: "./cache" }), ttl: 24 * 60 * 60 * 1000, // 1 day }); ``` 也支持针对每次请求的缓存控制： ``` // skip cache for this request await archive.snapshots("example.com", { cache: false }); ``` ## API ### `createArchive(providers, options?)` 创建一个 archive 客户端。接受单个 provider、`Promise` 或 `Promise`。 返回： - `snapshots(domain, options?)` - 返回带有 success 标志的完整 `ArchiveResponse` - `getPages(domain, options?)` - 返回 `ArchivedPage[]`，失败时抛出异常 - `use(provider)` - 向实例添加一个 provider - `useAll(providers)` - 一次添加多个 provider ### 选项 所有方法都接受 `ArchiveOptions`： | Option | Type | Default | Description | | ------------- | --------- | ----------- | ------------------------------------ | | `limit` | `number` | `1000` | 返回的最大结果数 | | `cache` | `boolean` | `true` | 启用/禁用缓存 | | `ttl` | `number` | `604800000` | 缓存 TTL（毫秒）(7 天) | | `concurrency` | `number` | `3` | 最大并行请求数 | | `batchSize` | `number` | `20` | 每个处理批次的项数 | | `timeout` | `number` | `10000` | 请求超时时间 (ms) | | `retries` | `number` | `1` | 失败时的重试次数 | | `apiKey` | `string` | - | 需要 auth 的提供商的 API key | 选项可以在三个级别设置：配置文件（全局默认值）、`createArchive` 调用（实例默认值）和单个方法调用（每次请求）。每一级别覆盖上一级别的设置。 ### 存储实用工具 - `configureStorage(options?)` - 配置缓存驱动和设置 - `clearProviderStorage(provider)` - 清除特定 provider 的缓存响应 - `storage` - 直接访问底层 unstorage 实例 ## 路线图 **提供商：** Archive-It, Conifer (前身是 Webrecorder) **功能：** 用于创建存档的页面存档 API，而不仅仅是读取 ## 许可证 MIT

标签：API 封装, Archive.today, ESC4, GNU通用公共许可证, Node.js, npm 包, OSINT, SOC Prime, Tree-shaking, TypeScript, URL抓取, Wayback Machine, Web Archive, 历史数据, 反汇编, 安全插件, 并发查询, 开发工具, 开源库, 搜索引擎爬虫, 数据抓取, 暗色界面, 统一接口, 网页存档, 自动化攻击