felo-ai 0.2.5 → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,30 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.2.7] - 2025-03-06
9
+
10
+ ### Breaking Changes
11
+
12
+ - **CLI 命令与技能重命名:web extract → web fetch**
13
+ - 命令 `felo web-extract` 已更名为 `felo web-fetch`,请更新脚本与文档。
14
+ - 独立脚本路径由 `felo-web-extract/scripts/run_web_extract.mjs` 改为 `felo-web-fetch/scripts/run_web_fetch.mjs`。
15
+ - 技能/目录名由 `felo-web-extract` 改为 `felo-web-fetch`;触发词示例:`/felo-web-fetch`、`use felo web fetch`。
16
+ - 后端 API 路径未变(仍为 `POST /v2/web/extract`),仅产品对外名称改为「Web Fetch」。
17
+
18
+ ### Changed
19
+
20
+ - 产品名称统一为「Web Fetch」:README、SKILL、package 描述与关键词已同步更新。
21
+ - `felo-youtube-subtitling` 技能中「网页内容」相关引用已更新为 `felo-web-fetch`。
22
+
23
+ ---
24
+
25
+ ## [0.2.6] - (previous)
26
+
27
+ Earlier releases: search, slides, web extract, youtube-subtitling features.
28
+
29
+ [0.2.7]: https://github.com/Felo-Inc/felo-skills/compare/v0.2.6...v0.2.7
30
+ [0.2.6]: https://github.com/Felo-Inc/felo-skills/releases/tag/v0.2.6
package/README.en.md CHANGED
@@ -8,9 +8,9 @@ Felo AI provides a terminal CLI and Claude Code skill, with support for English,
8
8
 
9
9
  ---
10
10
 
11
- ## Two Core Capabilities
11
+ ## Capabilities
12
12
 
13
- Felo AI offers two main features: **Real-time Search** and **PPT Generation**. Use them via the CLI in your terminal, or in Claude Code via the skill (search can trigger automatically).
13
+ Felo AI offers **Real-time Search**, **PPT Generation**, **Web Page Extraction**, and **YouTube Subtitles**. Use them via the CLI in your terminal, or in Claude Code via skills (search can trigger automatically).
14
14
 
15
15
  ### Capability 1: Real-time Search
16
16
 
@@ -56,6 +56,8 @@ Get your API key at [felo.ai](https://felo.ai) (Settings → API Keys).
56
56
  |---------|-------------|
57
57
  | `felo search "<query>"` | Real-time search |
58
58
  | `felo slides "<prompt>"` | Generate PPT |
59
+ | `felo web-fetch --url <url>` | Fetch webpage content (markdown/text/html) |
60
+ | `felo youtube-subtitling -v <url-or-id>` | Fetch YouTube video subtitles |
59
61
  | `felo config set FELO_API_KEY <key>` | Save API key |
60
62
  | `felo config get/list/path/unset` | View / list / path / remove config |
61
63
 
@@ -79,6 +81,22 @@ felo slides "Q4 2024 business review, 10 pages" --poll-timeout 300
79
81
  npx felo-ai slides "Tokyo travel guide, 5 slides"
80
82
  ```
81
83
 
84
+ **Web fetch**
85
+
86
+ ```bash
87
+ felo web-fetch --url "https://example.com"
88
+ felo web-fetch --url "https://example.com" --format text --readability
89
+ node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --format markdown
90
+ ```
91
+
92
+ **YouTube subtitling**
93
+
94
+ ```bash
95
+ felo youtube-subtitling -v "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
96
+ felo youtube-subtitling -v "dQw4w9WgXcQ" --language en
97
+ node felo-youtube-subtitling/scripts/run_youtube_subtitling.mjs -v "dQw4w9WgXcQ" -l zh-CN
98
+ ```
99
+
82
100
  ---
83
101
 
84
102
  ## Claude Code Skills
@@ -93,6 +111,10 @@ After setting `FELO_API_KEY`, ask Claude things like “What’s the weather in
93
111
 
94
112
  **Slides (PPT)** — `npx @claude/skills add felo-slides`, then `/felo-slides your topic`. Same `FELO_API_KEY`. [Details →](./felo-slides/README.md)
95
113
 
114
+ **Web Fetch** — `felo web-fetch --url "https://example.com"` or run `node felo-web-fetch/scripts/run_web_fetch.mjs` from repo. [Details →](./felo-web-fetch/README.md)
115
+
116
+ **YouTube Subtitling** — `felo youtube-subtitling -v "URL_or_VIDEO_ID"` or run `node felo-youtube-subtitling/scripts/run_youtube_subtitling.mjs` from repo. [Details →](./felo-youtube-subtitling/README.md)
117
+
96
118
  ---
97
119
 
98
120
  ## Links
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  **Ask anything. Get current answers. Generate slides from a prompt.**
4
4
 
5
- [npm package: **felo-ai**](https://www.npmjs.com/package/felo-ai) — Real-time search and PPT generation from the terminal. Also works as Claude Code skills. Supports Chinese, English, Japanese, and Korean.
5
+ [npm package: **felo-ai**](https://www.npmjs.com/package/felo-ai) — Real-time search, PPT generation, web fetch, and YouTube subtitles from the terminal. Also works as Claude Code skills. Supports Chinese, English, Japanese, and Korean.
6
6
 
7
7
  [![npm version](https://img.shields.io/npm/v/felo-ai.svg)](https://www.npmjs.com/package/felo-ai) [![License](https://img.shields.io/badge/license-MIT-green)]()
8
8
 
@@ -51,6 +51,8 @@ Get your API key from [felo.ai](https://felo.ai) (Settings → API Keys). Enviro
51
51
  | ------------------------------------ | ----------------------------------------------------- |
52
52
  | `felo search "<query>"` | Search for current info (weather, news, prices, etc.) |
53
53
  | `felo slides "<prompt>"` | Generate PPT; returns link when done |
54
+ | `felo web-fetch --url <url>` | Fetch webpage content (markdown/text/html) |
55
+ | `felo youtube-subtitling -v <url-or-id>` | Fetch YouTube video subtitles by video URL or ID |
54
56
  | `felo config set FELO_API_KEY <key>` | Save API key to config |
55
57
  | `felo config get FELO_API_KEY` | Print stored key |
56
58
  | `felo config list` | List config keys |
@@ -77,12 +79,67 @@ felo slides "Q4 2024 business review, 10 pages" --poll-timeout 300
77
79
  npx felo-ai slides "Tokyo travel guide, 5 slides"
78
80
  ```
79
81
 
82
+ **Web fetch** (after `npm install -g felo-ai`)
83
+
84
+ ```bash
85
+ # Packaged CLI
86
+ felo web-fetch --url "https://example.com"
87
+ felo web-fetch --url "https://example.com/article" --format markdown --readability
88
+ felo web-fetch --url "https://example.com" --target-selector "article.main" --format text
89
+ felo web-fetch --url "https://example.com" -j
90
+ npx felo-ai web-fetch --url "https://example.com" --format markdown
91
+
92
+ # From repo: run script directly (no install)
93
+ node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --format markdown
94
+ node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --readability -f text
95
+ ```
96
+
97
+ **How to pass parameters**
98
+
99
+ | Parameter | CLI option | Example | Description |
100
+ |-----------|------------|---------|--------------|
101
+ | URL (required) | `-u`, `--url` | `--url "https://example.com"` | Page to fetch |
102
+ | Output format | `-f`, `--format` | `--format text` or `-f markdown` | `html`, `text`, or `markdown` (default: markdown) |
103
+ | Target element | `--target-selector` | `--target-selector "article.main"` | CSS selector; only this element is fetched |
104
+ | Wait for element | `--wait-for-selector` | `--wait-for-selector ".content"` | Wait for selector before fetching (e.g. dynamic pages) |
105
+ | Readability | `--readability` | `--readability` | Main article content only (no nav/ads) |
106
+ | Crawl mode | `--crawl-mode` | `--crawl-mode fine` | `fast` (default) or `fine` |
107
+ | Timeout (seconds) | `-t`, `--timeout` | `--timeout 120` or `-t 90` | Request timeout (default: 60) |
108
+ | Full JSON response | `-j`, `--json` | `-j` or `--json` | Print full API response instead of content only |
109
+
110
+ Examples with multiple options:
111
+
112
+ ```bash
113
+ felo web-fetch -u "https://example.com" -f text --readability -t 90
114
+ felo web-fetch --url "https://example.com" --target-selector "#main" --wait-for-selector ".loaded" --format markdown --json
115
+ ```
116
+
117
+ Same `FELO_API_KEY` as search/slides.
118
+
119
+ **YouTube subtitling** (after `npm install -g felo-ai`)
120
+
121
+ ```bash
122
+ # Packaged CLI
123
+ felo youtube-subtitling -v "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
124
+ felo youtube-subtitling -v "dQw4w9WgXcQ" --language zh-CN
125
+ felo youtube-subtitling -v "https://youtu.be/dQw4w9WgXcQ" --with-time -j
126
+ npx felo-ai youtube-subtitling -v "dQw4w9WgXcQ"
127
+
128
+ # From repo: run script directly (no install)
129
+ node felo-youtube-subtitling/scripts/run_youtube_subtitling.mjs --video-code "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
130
+ node felo-youtube-subtitling/scripts/run_youtube_subtitling.mjs -v "dQw4w9WgXcQ" -l zh-CN --with-time
131
+ ```
132
+
133
+ Options: `-v/--video-code` (required: **YouTube video URL** or video ID), `-l/--language` (e.g. en, zh-CN), `--with-time`, `-j/--json`. Same `FELO_API_KEY` as other commands. See [felo-youtube-subtitling](./felo-youtube-subtitling/README.md).
134
+
80
135
  ### CLI FAQ
81
136
 
82
137
  - **Key not found?** Run `felo config set FELO_API_KEY <key>` or set the `FELO_API_KEY` environment variable.
83
138
  - **Request timeout?** Use `felo search "query" --timeout 120` (default 60 seconds). 5xx errors are retried automatically with backoff.
84
139
  - **Slides taking long?** Use `felo slides "topic" --poll-timeout 300` (default 1200s) to limit wait.
85
140
  - **Where is config stored?** Run `felo config path` to see the file (e.g. `~/.felo/config.json`).
141
+ - **Web fetch after install?** Use `felo web-fetch --url "<page url>"`. Other params: `--format markdown|text|html`, `--readability`, `--target-selector "selector"`, `--wait-for-selector "selector"`, `--crawl-mode fast|fine`, `--timeout 120`, `--json`. See the "How to pass parameters" table above. Same API key as other commands.
142
+ - **YouTube subtitles?** Use `felo youtube-subtitling -v "<url or video_id>"` (full YouTube link or 11-char ID). Optional: `-l/--language`, `--with-time`, `-j/--json`. See [felo-youtube-subtitling](./felo-youtube-subtitling/README.md).
86
143
 
87
144
  ---
88
145
 
@@ -124,6 +181,10 @@ Ask Claude: "What's the weather in Tokyo today?"
124
181
 
125
182
  **Felo Slides (PPT):** In terminal run `felo slides "your topic"`. In Claude Code install with `npx @claude/skills add felo-slides`, then use `/felo-slides your topic`. See [felo-slides](./felo-slides/README.md).
126
183
 
184
+ **Felo Web Fetch:** In terminal run `felo web-fetch --url "https://example.com"` (see [felo-web-fetch](./felo-web-fetch/README.md)). In Claude Code you can install the skill and use it to fetch webpage content from a URL.
185
+
186
+ **Felo YouTube Subtitling:** In terminal run `felo youtube-subtitling -v "URL_or_VIDEO_ID"` (see [felo-youtube-subtitling](./felo-youtube-subtitling/README.md)). Fetches subtitles/captions; accepts full YouTube link or video ID.
187
+
127
188
  ---
128
189
 
129
190
  ## Usage Examples
@@ -338,6 +399,12 @@ Run CLI tests: `npm test`
338
399
 
339
400
  ---
340
401
 
402
+ ## Version history
403
+
404
+ See [CHANGELOG.md](./CHANGELOG.md) for release notes (e.g. breaking changes such as `web-extract` → `web-fetch` in v0.2.7).
405
+
406
+ ---
407
+
341
408
  ## License
342
409
 
343
410
  MIT — see [LICENSE](./felo-search/LICENSE) in the repo for details.
@@ -15,11 +15,13 @@ Trigger this skill for requests about creating presentation files:
15
15
  - Export presentation content into a shareable slide link
16
16
 
17
17
  Trigger keywords:
18
+
18
19
  - Chinese prompts about making slides or presentations
19
20
  - English: slides, PPT, presentation deck, generate presentation
20
21
  - Explicit commands: `/felo-slides`, "use felo slides"
21
22
 
22
23
  Do NOT use this skill for:
24
+
23
25
  - Real-time information lookup (use `felo-search`)
24
26
  - Questions about local codebase files
25
27
  - Pure text tasks that do not require slide generation
@@ -35,11 +37,13 @@ Do NOT use this skill for:
35
37
  ### 2. Configure environment variable
36
38
 
37
39
  Linux/macOS:
40
+
38
41
  ```bash
39
42
  export FELO_API_KEY="your-api-key-here"
40
43
  ```
41
44
 
42
45
  Windows PowerShell:
46
+
43
47
  ```powershell
44
48
  $env:FELO_API_KEY="your-api-key-here"
45
49
  ```
@@ -72,6 +76,7 @@ node felo-slides/scripts/run_ppt_task.mjs \
72
76
  ```
73
77
 
74
78
  Script behavior:
79
+
75
80
  - Creates task via `POST https://openapi.felo.ai/v2/ppts`
76
81
  - Polls via `GET https://openapi.felo.ai/v2/tasks/{task_id}/historical`
77
82
  - Treats `COMPLETED`/`SUCCESS` as success terminal (case-insensitive)
@@ -91,16 +96,19 @@ node felo-slides/scripts/run_ppt_task.mjs \
91
96
  ```
92
97
 
93
98
  This outputs structured JSON including:
99
+
94
100
  - `task_id`
95
101
  - `task_status`
96
102
  - `ppt_url`
97
103
  - `live_doc_url`
98
104
  - `livedoc_short_id`
99
105
  - `ppt_business_id`
106
+ - `error_message`
100
107
 
101
108
  ### Step 4: Return structured result
102
109
 
103
110
  On success, return:
111
+
104
112
  - `ppt_url` immediately (script default output, fallback `live_doc_url`)
105
113
  - if `--json` is used, also include `task_id`, terminal status, and optional metadata
106
114
 
@@ -110,12 +118,14 @@ Use this response structure:
110
118
 
111
119
  ```markdown
112
120
  ## PPT Generation Result
121
+
113
122
  - Task ID: <task_id>
114
123
  - Status: <status>
115
124
  - PPT URL: <ppt_url>
116
125
  - Live Doc URL: <live_doc_url or N/A>
117
126
 
118
127
  ## Notes
128
+
119
129
  - livedoc_short_id: <value or N/A>
120
130
  - ppt_business_id: <value or N/A>
121
131
  ```
@@ -124,6 +134,7 @@ Error format:
124
134
 
125
135
  ```markdown
126
136
  ## PPT Generation Failed
137
+
127
138
  - Error Type: <error code or category>
128
139
  - Message: <readable message>
129
140
  - Suggested Action: <next step>
@@ -132,11 +143,13 @@ Error format:
132
143
  ## Error Handling
133
144
 
134
145
  Known API error codes:
146
+
135
147
  - `INVALID_API_KEY` (401): key invalid or revoked
136
148
  - `PPT_TASK_CREATE_FAILED` (502): create task downstream failed
137
149
  - `PPT_TASK_QUERY_FAILED` (502): query task downstream failed
138
150
 
139
151
  Timeout handling:
152
+
140
153
  - If timeout reached, return last known status and instruct user to retry later
141
154
  - Include `task_id` so user can query again
142
155
 
@@ -151,4 +164,3 @@ Timeout handling:
151
164
 
152
165
  - [Felo PPT Task API](https://openapi.felo.ai/docs/api-reference/v2/ppt-tasks.html)
153
166
  - [Felo Open Platform](https://openapi.felo.ai/docs/)
154
-
@@ -0,0 +1,78 @@
1
+ # Felo Web Fetch Skill
2
+
3
+ Fetch webpage content from a URL using the [Felo Web Extract API](https://openapi.felo.ai/docs/api-reference/v2/web-extract.html).
4
+
5
+ ## Features
6
+
7
+ - Fetch content from any URL as **html**, **text**, or **markdown** (`--format`)
8
+ - **Target one element** with a CSS selector (`--target-selector`, e.g. `article.main`, `#content`)
9
+ - Optional **readability** mode for main article content only
10
+ - Crawl modes: `fast` (default) or `fine`
11
+ - Same `FELO_API_KEY` as other Felo skills
12
+
13
+ ## Quick Start
14
+
15
+ ### 1) Configure API key
16
+
17
+ At [felo.ai](https://felo.ai) -> Settings -> API Keys, create a key, then:
18
+
19
+ ```bash
20
+ # Linux/macOS
21
+ export FELO_API_KEY="your-api-key-here"
22
+ ```
23
+
24
+ ```powershell
25
+ # Windows PowerShell
26
+ $env:FELO_API_KEY="your-api-key-here"
27
+ ```
28
+
29
+ ### 2) Run fetch
30
+
31
+ ```bash
32
+ # Fetch as Markdown (default)
33
+ node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com/article"
34
+
35
+ # With readability for clean article text
36
+ node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --readability --format markdown
37
+
38
+ # Full JSON response
39
+ node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --json
40
+
41
+ # Only a specific element (CSS selector) and output format
42
+ node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --target-selector "article.main" --format markdown
43
+ ```
44
+
45
+ ## Using the packaged CLI (`felo web-fetch`)
46
+
47
+ After `npm install -g felo-ai`, you can run:
48
+
49
+ ```bash
50
+ felo web-fetch --url "https://example.com"
51
+ ```
52
+
53
+ **All parameters (how to pass)**
54
+
55
+ | Parameter | Option | Example |
56
+ |-----------|--------|---------|
57
+ | URL (required) | `-u`, `--url` | `--url "https://example.com"` |
58
+ | Output format | `-f`, `--format` | `--format text`, `-f markdown`, `-f html` |
59
+ | Target element (CSS selector) | `--target-selector` | `--target-selector "article.main"` |
60
+ | Wait for selector | `--wait-for-selector` | `--wait-for-selector ".content"` |
61
+ | Readability (main content only) | `--readability` | `--readability` |
62
+ | Crawl mode | `--crawl-mode` | `--crawl-mode fine` (default: `fast`) |
63
+ | Timeout (seconds) | `-t`, `--timeout` | `--timeout 120`, `-t 90` |
64
+ | Full JSON response | `-j`, `--json` | `-j` or `--json` |
65
+
66
+ **Examples with multiple options**
67
+
68
+ ```bash
69
+ felo web-fetch -u "https://example.com" -f text --readability
70
+ felo web-fetch --url "https://example.com" --target-selector "#content" --format markdown --timeout 90
71
+ felo web-fetch --url "https://example.com" --wait-for-selector "main" --readability -j
72
+ ```
73
+
74
+ ## When to use (Agent)
75
+
76
+ Trigger keywords: fetch webpage, scrape URL, fetch page content, url to markdown, `/felo-web-fetch`.
77
+
78
+ See [SKILL.md](SKILL.md) for full agent instructions and API parameters.
@@ -0,0 +1,200 @@
1
+ ---
2
+ name: felo-web-fetch
3
+ description: "Fetch web page content from a URL using Felo Web Extract API. Use when users ask to scrape/capture/fetch webpage content, get article text from URL, convert page to markdown/text, or when explicit commands like /felo-web-fetch are used. Supports html, text, markdown output and readability mode."
4
+ ---
5
+
6
+ # Felo Web Fetch Skill
7
+
8
+ ## When to Use
9
+
10
+ Trigger this skill when the user wants to:
11
+
12
+ - Fetch or scrape content from a webpage URL
13
+ - Get article/main text from a link
14
+ - Convert a webpage to Markdown or plain text
15
+ - Capture readable content from a URL for summarization or processing
16
+
17
+ Trigger keywords (examples):
18
+
19
+ - fetch webpage, scrape URL, fetch page content, web fetch, url to markdown
20
+ - Explicit: `/felo-web-fetch`, "use felo web fetch"
21
+ - Same intent in other languages (e.g. 网页抓取, 提取网页内容) also triggers this skill
22
+
23
+ Do NOT use for:
24
+
25
+ - Real-time search or Q&A (use `felo-search`)
26
+ - Generating slides (use `felo-slides`)
27
+ - Local file content (read files directly)
28
+
29
+ ## Setup
30
+
31
+ ### 1. Get API key
32
+
33
+ 1. Visit [felo.ai](https://felo.ai)
34
+ 2. Open Settings -> API Keys
35
+ 3. Create and copy your API key
36
+
37
+ ### 2. Configure environment variable
38
+
39
+ Linux/macOS:
40
+
41
+ ```bash
42
+ export FELO_API_KEY="your-api-key-here"
43
+ ```
44
+
45
+ Windows PowerShell:
46
+
47
+ ```powershell
48
+ $env:FELO_API_KEY="your-api-key-here"
49
+ ```
50
+
51
+ ## How to Execute
52
+
53
+ ### Option A: Use the bundled script or packaged CLI
54
+
55
+ **Script** (from repo):
56
+
57
+ ```bash
58
+ node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com/article" [options]
59
+ ```
60
+
61
+ **Packaged CLI** (after `npm install -g felo-ai`): same options, with short forms allowed:
62
+
63
+ ```bash
64
+ felo web-fetch -u "https://example.com" [options]
65
+ # Short forms: -u (url), -f (format), -t (timeout, seconds), -j (json)
66
+ ```
67
+
68
+ Options:
69
+
70
+ | Option | Default | Description |
71
+ |--------|---------|-------------|
72
+ | `--url` | (required) | Webpage URL to fetch |
73
+ | `--format` | markdown | Output format: `html`, `text`, `markdown` |
74
+ | `--target-selector` | - | CSS selector: fetch only this element (e.g. `article.main`, `#content`) |
75
+ | `--wait-for-selector` | - | Wait for this selector before fetching (e.g. dynamic content) |
76
+ | `--readability` | false | Enable readability processing (main content only) |
77
+ | `--crawl-mode` | fast | `fast` or `fine` |
78
+ | `--timeout` | 60000 (script) / 60 (CLI) | Request timeout: script uses **milliseconds**, CLI uses **seconds** (e.g. `-t 90`) |
79
+ | `--json` / `-j` | false | Print full API response as JSON |
80
+
81
+ ### How to write instructions (target_selector + output_format)
82
+
83
+ When the user wants a **specific part** of the page or a **specific output format**, phrase the command like this:
84
+
85
+ - **Output format**: "Fetch as **text**" / "Get **markdown**" / "Return **html**" → use `--format text`, `--format markdown`, or `--format html`.
86
+ - **Target one element**: "Only the **main article**" / "Just the **content inside** `#main`" / "Fetch only **article.main-content**" → use `--target-selector "article.main"` or the selector they give (e.g. `#main`, `.main-content`, `article .post`).
87
+
88
+ Examples of user intents and equivalent commands:
89
+
90
+ | User intent | Command |
91
+ |-------------|---------|
92
+ | "Fetch this page as plain text" | `--url "..." --format text` |
93
+ | "Get only the main content area" | `--url "..." --target-selector "main"` or `article` |
94
+ | "Fetch the div with id=content as markdown" | `--url "..." --target-selector "#content" --format markdown` |
95
+ | "Just the article body, as HTML" | `--url "..." --target-selector "article .body" --format html` |
96
+
97
+ Examples:
98
+
99
+ ```bash
100
+ # Basic: fetch as Markdown
101
+ node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com"
102
+
103
+ # Article-style with readability
104
+ node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com/article" --readability --format markdown
105
+
106
+ # Raw HTML
107
+ node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --format html --json
108
+
109
+ # Only the element matching a CSS selector (e.g. main article)
110
+ node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --target-selector "article.main" --format markdown
111
+
112
+ # Specific output format + target selector
113
+ node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --target-selector "#content" --format text
114
+ ```
115
+
116
+ ### Option B: Call API with curl
117
+
118
+ ```bash
119
+ curl -X POST "https://openapi.felo.ai/v2/web/extract" \
120
+ -H "Authorization: Bearer $FELO_API_KEY" \
121
+ -H "Content-Type: application/json" \
122
+ -d '{"url": "https://example.com", "output_format": "markdown", "with_readability": true}'
123
+ ```
124
+
125
+ ## API Reference (summary)
126
+
127
+ - **Endpoint**: `POST /v2/web/extract`
128
+ - **Base URL**: `https://openapi.felo.ai`. Override with `FELO_API_BASE` env if needed.
129
+ - **Auth**: `Authorization: Bearer YOUR_API_KEY`
130
+
131
+ ### Request body (JSON)
132
+
133
+ | Parameter | Type | Required | Default | Description |
134
+ |-----------|------|----------|---------|-------------|
135
+ | url | string | Yes | - | Webpage URL to fetch |
136
+ | crawl_mode | string | No | fast | `fast` or `fine` |
137
+ | output_format | string | No | html | `html`, `text`, `markdown` |
138
+ | with_readability | boolean | No | - | Use readability (main content) |
139
+ | with_links_summary | boolean | No | - | Include links summary |
140
+ | with_images_summary | boolean | No | - | Include images summary |
141
+ | target_selector | string | No | - | CSS selector for target element |
142
+ | wait_for_selector | string | No | - | Wait for selector before fetch |
143
+ | timeout | integer | No | - | Timeout in milliseconds |
144
+ | with_cache | boolean | No | true | Use cache |
145
+
146
+ ### Response
147
+
148
+ Success (200):
149
+
150
+ ```json
151
+ {
152
+ "code": 0,
153
+ "message": "success",
154
+ "data": {
155
+ "content": { ... }
156
+ }
157
+ }
158
+ ```
159
+
160
+ Fetched content is in `data.content`; structure depends on `output_format`.
161
+
162
+ ### Error codes
163
+
164
+ | HTTP | Code | Description |
165
+ |------|------|-------------|
166
+ | 400 | - | Parameter validation failed |
167
+ | 401 | INVALID_API_KEY | API key invalid or revoked |
168
+ | 500/502 | WEB_EXTRACT_FAILED | Fetch failed (server or page error) |
169
+
170
+ ## Output Format
171
+
172
+ On success (script without `--json`):
173
+
174
+ - Print the fetched content only (for direct use or piping).
175
+
176
+ With `--json`:
177
+
178
+ - Print full API response including `code`, `message`, `data`.
179
+
180
+ Error response to user:
181
+
182
+ ```markdown
183
+ ## Web Fetch Failed
184
+
185
+ - Error: <code or message>
186
+ - URL: <requested url>
187
+ - Suggestion: <e.g. check URL, retry, or use --timeout>
188
+ ```
189
+
190
+ ## Important Notes
191
+
192
+ - Always check `FELO_API_KEY` before calling; if missing, return setup instructions.
193
+ - For long articles or slow sites, consider `--timeout` or `timeout` in request body.
194
+ - Use `output_format: "markdown"` and `with_readability: true` for clean article text.
195
+ - API may cache results; use `with_cache: false` in body only when fresh content is required (script does not expose this by default).
196
+
197
+ ## References
198
+
199
+ - [Felo Web Extract API](https://openapi.felo.ai/docs/api-reference/v2/web-extract.html)
200
+ - [Felo Open Platform](https://openapi.felo.ai/docs/)