felo-ai 0.2.5 → 0.2.6

package/README.en.md

@@ -8,9 +8,9 @@ Felo AI provides a terminal CLI and Claude Code skill, with support for English,
 
 ---
 
-## Two Core Capabilities
+## Capabilities
 
-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).
+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).
 
 ### Capability 1: Real-time Search
 
@@ -56,6 +56,8 @@ Get your API key at [felo.ai](https://felo.ai) (Settings → API Keys).
 |---------|-------------|
 | `felo search "<query>"` | Real-time search |
 | `felo slides "<prompt>"` | Generate PPT |
+| `felo web-extract --url <url>` | Extract webpage content (markdown/text/html) |
+| `felo youtube-subtitling -v <url-or-id>` | Fetch YouTube video subtitles |
 | `felo config set FELO_API_KEY <key>` | Save API key |
 | `felo config get/list/path/unset` | View / list / path / remove config |
 
@@ -79,6 +81,22 @@ felo slides "Q4 2024 business review, 10 pages" --poll-timeout 300
 npx felo-ai slides "Tokyo travel guide, 5 slides"
 ```
 
+**Web extract**
+
+```bash
+felo web-extract --url "https://example.com"
+felo web-extract --url "https://example.com" --format text --readability
+node felo-web-extract/scripts/run_web_extract.mjs --url "https://example.com" --format markdown
+```
+
+**YouTube subtitling**
+
+```bash
+felo youtube-subtitling -v "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+felo youtube-subtitling -v "dQw4w9WgXcQ" --language en
+node felo-youtube-subtitling/scripts/run_youtube_subtitling.mjs -v "dQw4w9WgXcQ" -l zh-CN
+```
+
 ---
 
 ## Claude Code Skills
@@ -93,6 +111,10 @@ After setting `FELO_API_KEY`, ask Claude things like “What’s the weather in
 
 **Slides (PPT)** — `npx @claude/skills add felo-slides`, then `/felo-slides your topic`. Same `FELO_API_KEY`. [Details →](./felo-slides/README.md)
 
+**Web Extract** — `felo web-extract --url "https://example.com"` or run `node felo-web-extract/scripts/run_web_extract.mjs` from repo. [Details →](./felo-web-extract/README.md)
+
+**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)
+
 ---
 
 ## Links

package/README.md

@@ -2,7 +2,7 @@
 
 **Ask anything. Get current answers. Generate slides from a prompt.**
 
-[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.
+[npm package: **felo-ai**](https://www.npmjs.com/package/felo-ai) — Real-time search, PPT generation, web page extraction, and YouTube subtitles from the terminal. Also works as Claude Code skills. Supports Chinese, English, Japanese, and Korean.
 
 [![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)]()
 
@@ -51,6 +51,8 @@ Get your API key from [felo.ai](https://felo.ai) (Settings → API Keys). Enviro
 | ------------------------------------ | ----------------------------------------------------- |
 | `felo search "<query>"`              | Search for current info (weather, news, prices, etc.) |
 | `felo slides "<prompt>"`             | Generate PPT; returns link when done                 |
+| `felo web-extract --url <url>`       | Extract webpage content (markdown/text/html)          |
+| `felo youtube-subtitling -v <url-or-id>` | Fetch YouTube video subtitles by video URL or ID   |
 | `felo config set FELO_API_KEY <key>` | Save API key to config                                |
 | `felo config get FELO_API_KEY`       | Print stored key                                      |
 | `felo config list`                   | List config keys                                      |
@@ -77,12 +79,67 @@ felo slides "Q4 2024 business review, 10 pages" --poll-timeout 300
 npx felo-ai slides "Tokyo travel guide, 5 slides"
 ```
 
+**Web extract** (after `npm install -g felo-ai`)
+
+```bash
+# Packaged CLI
+felo web-extract --url "https://example.com"
+felo web-extract --url "https://example.com/article" --format markdown --readability
+felo web-extract --url "https://example.com" --target-selector "article.main" --format text
+felo web-extract --url "https://example.com" -j
+npx felo-ai web-extract --url "https://example.com" --format markdown
+
+# From repo: run script directly (no install)
+node felo-web-extract/scripts/run_web_extract.mjs --url "https://example.com" --format markdown
+node felo-web-extract/scripts/run_web_extract.mjs --url "https://example.com" --readability -f text
+```
+
+**How to pass parameters**
+
+| Parameter | CLI option | Example | Description |
+|-----------|------------|---------|--------------|
+| URL (required) | `-u`, `--url` | `--url "https://example.com"` | Page to extract |
+| Output format | `-f`, `--format` | `--format text` or `-f markdown` | `html`, `text`, or `markdown` (default: markdown) |
+| Target element | `--target-selector` | `--target-selector "article.main"` | CSS selector; only this element is extracted |
+| Wait for element | `--wait-for-selector` | `--wait-for-selector ".content"` | Wait for selector before extracting (e.g. dynamic pages) |
+| Readability | `--readability` | `--readability` | Main article content only (no nav/ads) |
+| Crawl mode | `--crawl-mode` | `--crawl-mode fine` | `fast` (default) or `fine` |
+| Timeout (seconds) | `-t`, `--timeout` | `--timeout 120` or `-t 90` | Request timeout (default: 60) |
+| Full JSON response | `-j`, `--json` | `-j` or `--json` | Print full API response instead of content only |
+
+Examples with multiple options:
+
+```bash
+felo web-extract -u "https://example.com" -f text --readability -t 90
+felo web-extract --url "https://example.com" --target-selector "#main" --wait-for-selector ".loaded" --format markdown --json
+```
+
+Same `FELO_API_KEY` as search/slides.
+
+**YouTube subtitling** (after `npm install -g felo-ai`)
+
+```bash
+# Packaged CLI
+felo youtube-subtitling -v "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+felo youtube-subtitling -v "dQw4w9WgXcQ" --language zh-CN
+felo youtube-subtitling -v "https://youtu.be/dQw4w9WgXcQ" --with-time -j
+npx felo-ai youtube-subtitling -v "dQw4w9WgXcQ"
+
+# From repo: run script directly (no install)
+node felo-youtube-subtitling/scripts/run_youtube_subtitling.mjs --video-code "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+node felo-youtube-subtitling/scripts/run_youtube_subtitling.mjs -v "dQw4w9WgXcQ" -l zh-CN --with-time
+```
+
+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).
+
 ### CLI FAQ
 
 - **Key not found?** Run `felo config set FELO_API_KEY <key>` or set the `FELO_API_KEY` environment variable.
 - **Request timeout?** Use `felo search "query" --timeout 120` (default 60 seconds). 5xx errors are retried automatically with backoff.
 - **Slides taking long?** Use `felo slides "topic" --poll-timeout 300` (default 1200s) to limit wait.
 - **Where is config stored?** Run `felo config path` to see the file (e.g. `~/.felo/config.json`).
+- **Web extract after install?** Use `felo web-extract --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.
+- **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).
 
 ---
 
@@ -124,6 +181,10 @@ Ask Claude: "What's the weather in Tokyo today?"
 
 **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).
 
+**Felo Web Extract:** In terminal run `felo web-extract --url "https://example.com"` (see [felo-web-extract](./felo-web-extract/README.md)). In Claude Code you can install the skill and use it to extract webpage content from a URL.
+
+**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.
+
 ---
 
 ## Usage Examples

package/felo-slides/SKILL.md

@@ -15,11 +15,13 @@ Trigger this skill for requests about creating presentation files:
 - Export presentation content into a shareable slide link
 
 Trigger keywords:
+
 - Chinese prompts about making slides or presentations
 - English: slides, PPT, presentation deck, generate presentation
 - Explicit commands: `/felo-slides`, "use felo slides"
 
 Do NOT use this skill for:
+
 - Real-time information lookup (use `felo-search`)
 - Questions about local codebase files
 - Pure text tasks that do not require slide generation
@@ -35,11 +37,13 @@ Do NOT use this skill for:
 ### 2. Configure environment variable
 
 Linux/macOS:
+
 ```bash
 export FELO_API_KEY="your-api-key-here"
 ```
 
 Windows PowerShell:
+
 ```powershell
 $env:FELO_API_KEY="your-api-key-here"
 ```
@@ -72,6 +76,7 @@ node felo-slides/scripts/run_ppt_task.mjs \
 ```
 
 Script behavior:
+
 - Creates task via `POST https://openapi.felo.ai/v2/ppts`
 - Polls via `GET https://openapi.felo.ai/v2/tasks/{task_id}/historical`
 - Treats `COMPLETED`/`SUCCESS` as success terminal (case-insensitive)
@@ -91,16 +96,19 @@ node felo-slides/scripts/run_ppt_task.mjs \
 ```
 
 This outputs structured JSON including:
+
 - `task_id`
 - `task_status`
 - `ppt_url`
 - `live_doc_url`
 - `livedoc_short_id`
 - `ppt_business_id`
+- `error_message`
 
 ### Step 4: Return structured result
 
 On success, return:
+
 - `ppt_url` immediately (script default output, fallback `live_doc_url`)
 - if `--json` is used, also include `task_id`, terminal status, and optional metadata
 
@@ -110,12 +118,14 @@ Use this response structure:
 
 ```markdown
 ## PPT Generation Result
+
 - Task ID: <task_id>
 - Status: <status>
 - PPT URL: <ppt_url>
 - Live Doc URL: <live_doc_url or N/A>
 
 ## Notes
+
 - livedoc_short_id: <value or N/A>
 - ppt_business_id: <value or N/A>
 ```
@@ -124,6 +134,7 @@ Error format:
 
 ```markdown
 ## PPT Generation Failed
+
 - Error Type: <error code or category>
 - Message: <readable message>
 - Suggested Action: <next step>
@@ -132,11 +143,13 @@ Error format:
 ## Error Handling
 
 Known API error codes:
+
 - `INVALID_API_KEY` (401): key invalid or revoked
 - `PPT_TASK_CREATE_FAILED` (502): create task downstream failed
 - `PPT_TASK_QUERY_FAILED` (502): query task downstream failed
 
 Timeout handling:
+
 - If timeout reached, return last known status and instruct user to retry later
 - Include `task_id` so user can query again
 
@@ -151,4 +164,3 @@ Timeout handling:
 
 - [Felo PPT Task API](https://openapi.felo.ai/docs/api-reference/v2/ppt-tasks.html)
 - [Felo Open Platform](https://openapi.felo.ai/docs/)
-

package/felo-web-extract/README.md

@@ -0,0 +1,78 @@
+# Felo Web Extract Skill
+
+Extract webpage content from a URL using the [Felo Web Extract API](https://openapi.felo.ai/docs/api-reference/v2/web-extract.html).
+
+## Features
+
+- Extract content from any URL as **html**, **text**, or **markdown** (`--format`)
+- **Target one element** with a CSS selector (`--target-selector`, e.g. `article.main`, `#content`)
+- Optional **readability** mode for main article content only
+- Crawl modes: `fast` (default) or `fine`
+- Same `FELO_API_KEY` as other Felo skills
+
+## Quick Start
+
+### 1) Configure API key
+
+At [felo.ai](https://felo.ai) -> Settings -> API Keys, create a key, then:
+
+```bash
+# Linux/macOS
+export FELO_API_KEY="your-api-key-here"
+```
+
+```powershell
+# Windows PowerShell
+$env:FELO_API_KEY="your-api-key-here"
+```
+
+### 2) Run extraction
+
+```bash
+# Extract as Markdown (default)
+node felo-web-extract/scripts/run_web_extract.mjs --url "https://example.com/article"
+
+# With readability for clean article text
+node felo-web-extract/scripts/run_web_extract.mjs --url "https://example.com" --readability --format markdown
+
+# Full JSON response
+node felo-web-extract/scripts/run_web_extract.mjs --url "https://example.com" --json
+
+# Only a specific element (CSS selector) and output format
+node felo-web-extract/scripts/run_web_extract.mjs --url "https://example.com" --target-selector "article.main" --format markdown
+```
+
+## Using the packaged CLI (`felo web-extract`)
+
+After `npm install -g felo-ai`, you can run:
+
+```bash
+felo web-extract --url "https://example.com"
+```
+
+**All parameters (how to pass)**
+
+| Parameter | Option | Example |
+|-----------|--------|---------|
+| URL (required) | `-u`, `--url` | `--url "https://example.com"` |
+| Output format | `-f`, `--format` | `--format text`, `-f markdown`, `-f html` |
+| Target element (CSS selector) | `--target-selector` | `--target-selector "article.main"` |
+| Wait for selector | `--wait-for-selector` | `--wait-for-selector ".content"` |
+| Readability (main content only) | `--readability` | `--readability` |
+| Crawl mode | `--crawl-mode` | `--crawl-mode fine` (default: `fast`) |
+| Timeout (seconds) | `-t`, `--timeout` | `--timeout 120`, `-t 90` |
+| Full JSON response | `-j`, `--json` | `-j` or `--json` |
+
+**Examples with multiple options**
+
+```bash
+felo web-extract -u "https://example.com" -f text --readability
+felo web-extract --url "https://example.com" --target-selector "#content" --format markdown --timeout 90
+felo web-extract --url "https://example.com" --wait-for-selector "main" --readability -j
+```
+
+## When to use (Agent)
+
+Trigger keywords: extract webpage, scrape URL, fetch page content, url to markdown, `/felo-web-extract`.
+
+See [SKILL.md](SKILL.md) for full agent instructions and API parameters.

package/felo-web-extract/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: felo-web-extract
+description: "Extract web page content from a URL using Felo Web Extract API. Use when users ask to scrape/capture/fetch webpage content, extract article text from URL, convert page to markdown/text, or when explicit commands like /felo-web-extract are used. Supports html, text, markdown output and readability mode."
+---
+
+# Felo Web Extract Skill
+
+## When to Use
+
+Trigger this skill when the user wants to:
+
+- Extract or scrape content from a webpage URL
+- Get article/main text from a link
+- Convert a webpage to Markdown or plain text
+- Capture readable content from a URL for summarization or processing
+
+Trigger keywords (examples):
+
+- extract webpage, scrape URL, fetch page content, web extract, url to markdown
+- Explicit: `/felo-web-extract`, "use felo web extract"
+- Same intent in other languages (e.g. 网页抓取, 提取网页内容) also triggers this skill
+
+Do NOT use for:
+
+- Real-time search or Q&A (use `felo-search`)
+- Generating slides (use `felo-slides`)
+- Local file content (read files directly)
+
+## Setup
+
+### 1. Get API key
+
+1. Visit [felo.ai](https://felo.ai)
+2. Open Settings -> API Keys
+3. Create and copy your API key
+
+### 2. Configure environment variable
+
+Linux/macOS:
+
+```bash
+export FELO_API_KEY="your-api-key-here"
+```
+
+Windows PowerShell:
+
+```powershell
+$env:FELO_API_KEY="your-api-key-here"
+```
+
+## How to Execute
+
+### Option A: Use the bundled script or packaged CLI
+
+**Script** (from repo):
+
+```bash
+node felo-web-extract/scripts/run_web_extract.mjs --url "https://example.com/article" [options]
+```
+
+**Packaged CLI** (after `npm install -g felo-ai`): same options, with short forms allowed:
+
+```bash
+felo web-extract -u "https://example.com" [options]
+# Short forms: -u (url), -f (format), -t (timeout, seconds), -j (json)
+```
+
+Options:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--url` | (required) | Webpage URL to extract |
+| `--format` | markdown | Output format: `html`, `text`, `markdown` |
+| `--target-selector` | - | CSS selector: extract only this element (e.g. `article.main`, `#content`) |
+| `--wait-for-selector` | - | Wait for this selector before extracting (e.g. dynamic content) |
+| `--readability` | false | Enable readability processing (main content only) |
+| `--crawl-mode` | fast | `fast` or `fine` |
+| `--timeout` | 60000 (script) / 60 (CLI) | Request timeout: script uses **milliseconds**, CLI uses **seconds** (e.g. `-t 90`) |
+| `--json` / `-j` | false | Print full API response as JSON |
+
+### How to write instructions (target_selector + output_format)
+
+When the user wants a **specific part** of the page or a **specific output format**, phrase the command like this:
+
+- **Output format**: "Extract as **text**" / "Get **markdown**" / "Return **html**" → use `--format text`, `--format markdown`, or `--format html`.
+- **Target one element**: "Only the **main article**" / "Just the **content inside** `#main`" / "Extract only **article.main-content**" → use `--target-selector "article.main"` or the selector they give (e.g. `#main`, `.main-content`, `article .post`).
+
+Examples of user intents and equivalent commands:
+
+| User intent | Command |
+|-------------|---------|
+| "Extract this page as plain text" | `--url "..." --format text` |
+| "Get only the main content area" | `--url "..." --target-selector "main"` or `article` |
+| "Extract the div with id=content as markdown" | `--url "..." --target-selector "#content" --format markdown` |
+| "Just the article body, as HTML" | `--url "..." --target-selector "article .body" --format html` |
+
+Examples:
+
+```bash
+# Basic: extract as Markdown
+node felo-web-extract/scripts/run_web_extract.mjs --url "https://example.com"
+
+# Article-style with readability
+node felo-web-extract/scripts/run_web_extract.mjs --url "https://example.com/article" --readability --format markdown
+
+# Raw HTML
+node felo-web-extract/scripts/run_web_extract.mjs --url "https://example.com" --format html --json
+
+# Only the element matching a CSS selector (e.g. main article)
+node felo-web-extract/scripts/run_web_extract.mjs --url "https://example.com" --target-selector "article.main" --format markdown
+
+# Specific output format + target selector
+node felo-web-extract/scripts/run_web_extract.mjs --url "https://example.com" --target-selector "#content" --format text
+```
+
+### Option B: Call API with curl
+
+```bash
+curl -X POST "https://openapi.felo.ai/v2/web/extract" \
+  -H "Authorization: Bearer $FELO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com", "output_format": "markdown", "with_readability": true}'
+```
+
+## API Reference (summary)
+
+- **Endpoint**: `POST /v2/web/extract`
+- **Base URL**: `https://openapi.felo.ai`. Override with `FELO_API_BASE` env if needed.
+- **Auth**: `Authorization: Bearer YOUR_API_KEY`
+
+### Request body (JSON)
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| url | string | Yes | - | Webpage URL to extract |
+| crawl_mode | string | No | fast | `fast` or `fine` |
+| output_format | string | No | html | `html`, `text`, `markdown` |
+| with_readability | boolean | No | - | Use readability (main content) |
+| with_links_summary | boolean | No | - | Include links summary |
+| with_images_summary | boolean | No | - | Include images summary |
+| target_selector | string | No | - | CSS selector for target element |
+| wait_for_selector | string | No | - | Wait for selector before extract |
+| timeout | integer | No | - | Timeout in milliseconds |
+| with_cache | boolean | No | true | Use cache |
+
+### Response
+
+Success (200):
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "content": { ... }
+  }
+}
+```
+
+Extracted content is in `data.content`; structure depends on `output_format`.
+
+### Error codes
+
+| HTTP | Code | Description |
+|------|------|-------------|
+| 400 | - | Parameter validation failed |
+| 401 | INVALID_API_KEY | API key invalid or revoked |
+| 500/502 | WEB_EXTRACT_FAILED | Extract failed (server or page error) |
+
+## Output Format
+
+On success (script without `--json`):
+
+- Print the extracted content only (for direct use or piping).
+
+With `--json`:
+
+- Print full API response including `code`, `message`, `data`.
+
+Error response to user:
+
+```markdown
+## Web Extract Failed
+
+- Error: <code or message>
+- URL: <requested url>
+- Suggestion: <e.g. check URL, retry, or use --timeout>
+```
+
+## Important Notes
+
+- Always check `FELO_API_KEY` before calling; if missing, return setup instructions.
+- For long articles or slow sites, consider `--timeout` or `timeout` in request body.
+- Use `output_format: "markdown"` and `with_readability: true` for clean article text.
+- API may cache results; use `with_cache: false` in body only when fresh content is required (script does not expose this by default).
+
+## References
+
+- [Felo Web Extract API](https://openapi.felo.ai/docs/api-reference/v2/web-extract.html)
+- [Felo Open Platform](https://openapi.felo.ai/docs/)