n8n-nodes-firecrawl-v2 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 THE NEXOVA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# n8n-nodes-firecrawl-v2
+
+Community node for [Firecrawl](https://firecrawl.dev) **v2 API** on n8n. Scrape, crawl, map, search, and extract web content with full JavaScript rendering and AI-powered extraction.
+
+Works with both **Firecrawl Cloud** and **self-hosted** instances.
+
+Built by [THE NEXOVA](https://thenexova.com). Full guide: [n8n Firecrawl Node: Web Scraping, Crawling, and AI Extraction Guide](https://thenexova.com/n8n-firecrawl-node-web-scraping-crawling-and-ai-extraction-guide/)
+
+## Installation
+
+### n8n Community Nodes
+
+1. Go to **Settings** > **Community Nodes**
+2. Select **Install**
+3. Enter `n8n-nodes-firecrawl-v2`
+4. Agree to the risks and click **Install**
+
+### Manual (Self-Hosted)
+
+```bash
+cd ~/.n8n
+npm install n8n-nodes-firecrawl-v2
+```
+
+Restart n8n after installation.
+
+## Credentials
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| Base URL | `https://api.firecrawl.dev/v2` | Change for self-hosted. **Must include `/v2`**. |
+| API Key | | Your Firecrawl API key |
+
+Authentication: `Authorization: Bearer {apiKey}`. Tested via `POST /scrape` on `https://example.com`.
+
+## Operations
+
+### 1. Scrape
+
+Scrape content from a single URL with JS rendering.
+
+**Endpoint:** `POST /scrape`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | String | | Target URL (required) |
+
+**Scrape Options:**
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `formats` | `markdown` | `markdown`, `html`, `rawHtml`, `links`, `screenshot`, `json`, `summary`, `images`, `audio`, `changeTracking` |
+| `onlyMainContent` | `true` | Strip headers, nav, footers |
+| `includeTags` | | CSS selectors to keep (e.g., `article, .content`) |
+| `excludeTags` | | CSS selectors to remove (e.g., `nav, .sidebar`) |
+| `waitFor` | `0` | Wait for JS render (ms). Increase for SPA pages. |
+| `timeout` | `30000` | Request timeout (ms), max 300,000 |
+| `mobile` | `false` | Emulate mobile viewport |
+| `blockAds` | `true` | Block ads and cookie popups |
+| `proxy` | `auto` | Proxy: `auto`, `basic`, `enhanced` |
+| `locationCountry` | | ISO country code (e.g., `VN`, `US`) |
+| `locationLanguages` | | Locale codes (e.g., `vi-VN, en-US`) |
+
+**Sample output:**
+
+```json
+{
+  "markdown": "# Page Title\n\nExtracted content...",
+  "metadata": {
+    "title": "Page Title",
+    "sourceURL": "https://example.com",
+    "statusCode": 200
+  }
+}
+```
+
+### 2. Crawl
+
+Crawl an entire website. Async job with optional polling.
+
+**Endpoint:** `POST /crawl`
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `crawlUrl` | | Starting URL (required) |
+| `waitForCompletion` | `false` | Poll until job finishes |
+| `maxPollTime` | `300` | Max wait in seconds |
+
+**Crawl Options:**
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `limit` | `100` | Max pages |
+| `maxDiscoveryDepth` | `2` | Max link depth |
+| `includePaths` | | Regex patterns to include (e.g., `/blog/*`) |
+| `excludePaths` | | Regex patterns to exclude (e.g., `/admin/*`) |
+| `sitemap` | `include` | `include`, `skip`, or `only` |
+| `crawlEntireDomain` | `false` | Follow sibling/parent links |
+| `allowExternalLinks` | `false` | Follow external links |
+| `allowSubdomains` | `false` | Crawl subdomains |
+| `delay` | `0` | Seconds between requests (forces concurrency=1) |
+| `formats` | `markdown` | Output format per page |
+| `onlyMainContent` | `true` | Strip boilerplate |
+
+> When `waitForCompletion` is off, output only contains the job `id`. Use **Get Crawl Status** to fetch results. Polling interval: 2 seconds.
+
+### 3. Get Crawl Status
+
+**Endpoint:** `GET /crawl/{crawlId}` | **Parameter:** `crawlId` (job ID)
+
+### 4. Cancel Crawl
+
+**Endpoint:** `DELETE /crawl/{crawlId}` | **Parameter:** `cancelCrawlId` (job ID)
+
+### 5. Map
+
+Discover all URLs on a website without scraping content. Faster than Crawl.
+
+**Endpoint:** `POST /map`
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `mapUrl` | | Starting URL (required) |
+| `search` | | Search query to rank by relevance |
+| `includeSubdomains` | `true` | Include subdomain URLs |
+| `limit` | `5000` | Max URLs (max: 100,000) |
+| `ignoreQueryParameters` | `true` | Deduplicate by stripping query strings |
+| `ignoreCache` | `false` | Bypass sitemap cache |
+
+### 6. Search
+
+Web search with optional page scraping.
+
+**Endpoint:** `POST /search`
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `searchQuery` | | Keywords, max 500 chars (required) |
+| `limit` | `5` | Results count (1-100) |
+| `country` | `US` | ISO country code |
+| `tbs` | Any Time | Time filter: past hour/day/week/month/year |
+| `formats` | `markdown` | Content format for results |
+| `onlyMainContent` | `true` | Strip boilerplate |
+
+### 7. Extract
+
+AI-powered structured data extraction using natural language prompts.
+
+**Endpoint:** `POST /extract`
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `extractUrls` | | Comma-separated URLs (glob patterns supported: `https://example.com/*`) |
+| `extractPrompt` | | Natural language instruction |
+| `extractSchema` | | Optional JSON Schema for output structure |
+| `extractWaitForCompletion` | `true` | Wait for results (**defaults ON**, unlike Crawl/Batch) |
+| `extractMaxPollTime` | `300` | Max wait in seconds |
+
+**Extract Options:**
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `enableWebSearch` | `false` | Use web search for additional data |
+| `showSources` | `false` | Include source URLs |
+
+**Example:**
+
+```
+Prompt: "Extract company name, phone, address from this page"
+Schema: {
+  "type": "object",
+  "properties": {
+    "company_name": { "type": "string" },
+    "phone": { "type": "string" },
+    "address": { "type": "string" }
+  }
+}
+```
+
+### 8. Get Extract Status
+
+**Endpoint:** `GET /extract/{extractId}` | **Parameter:** `extractId` (job ID)
+
+### 9. Batch Scrape
+
+Scrape multiple URLs asynchronously.
+
+**Endpoint:** `POST /batch/scrape`
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `batchUrls` | | Comma-separated URLs |
+| `batchWaitForCompletion` | `false` | Wait for all to finish |
+| `batchMaxPollTime` | `300` | Max wait in seconds |
+
+Options: `formats`, `onlyMainContent`, `maxConcurrency`.
+
+### 10. Get Batch Scrape Status
+
+**Endpoint:** `GET /batch/scrape/{batchScrapeId}` | **Parameter:** `batchScrapeId` (job ID)
+
+## Technical Notes
+
+- **Async operations** (Crawl, Extract, Batch Scrape) return a job ID by default. Enable `waitForCompletion` to get results inline. Polling interval: 2 seconds.
+- **Extract defaults to `waitForCompletion: true`**, while Crawl and Batch Scrape default to `false`.
+- **Scrape supports 10 formats** (including `json`, `summary`, `audio`). Crawl, Search, and Batch Scrape support 5 basic formats.
+- **Comma-separated inputs:** `includeTags`, `excludeTags`, `includePaths`, `excludePaths`, `extractUrls`, `batchUrls` all accept comma-separated lists.
+- **Self-hosted Base URL** must include `/v2` (e.g., `http://firecrawl:3002/v2`).
+- **Error handling:** Supports `continueOnFail`. On error, output is `{ "error": "message" }`.
+
+## Workflow Examples
+
+**Competitive intelligence:**
+
+```
+Schedule Trigger (weekly)
+  -> Firecrawl: Map (competitor URL)
+  -> Firecrawl: Batch Scrape (URLs from Map)
+  -> Code Node (diff with last week)
+  -> Google Sheets + Slack notification
+```
+
+**AI data extraction:**
+
+```
+Manual Trigger
+  -> Firecrawl: Extract (directory URL, prompt, schema)
+  -> Google Sheets: Append rows
+```
+
+**Content monitoring:**
+
+```
+Schedule Trigger (daily)
+  -> Firecrawl: Scrape (formats: changeTracking)
+  -> IF (changes detected) -> Email alert
+```
+
+## Compatibility
+
+- n8n: >= 1.0.0
+- Firecrawl API: v2
+- Tested with self-hosted Firecrawl and Firecrawl Cloud
+
+## About
+
+[THE NEXOVA](https://thenexova.com) builds automation infrastructure for businesses. Need custom n8n nodes, self-hosted Firecrawl deployment, or scraping workflow design? [Get in touch](https://thenexova.com/contact/).
+
+## License
+
+[MIT](LICENSE)

package/dist/credentials/FirecrawlApi.credentials.d.ts

@@ -0,0 +1,9 @@
+import { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class FirecrawlApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}

package/dist/credentials/FirecrawlApi.credentials.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FirecrawlApi = void 0;
+class FirecrawlApi {
+    constructor() {
+        this.name = 'firecrawlApi';
+        this.displayName = 'Firecrawl API';
+        this.documentationUrl = 'https://docs.firecrawl.dev';
+        this.properties = [
+            {
+                displayName: 'Base URL',
+                name: 'baseUrl',
+                type: 'string',
+                default: 'https://api.firecrawl.dev/v2',
+                placeholder: 'https://api.firecrawl.dev/v2',
+                description: 'Base URL including API version. For self-hosted instances, use your server URL (e.g. http://localhost:3002/v2)',
+            },
+            {
+                displayName: 'API Key',
+                name: 'apiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                description: 'Your Firecrawl API key',
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Authorization: '=Bearer {{$credentials.apiKey}}',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.baseUrl}}',
+                url: '/scrape',
+                method: 'POST',
+                body: {
+                    url: 'https://example.com',
+                    formats: ['markdown'],
+                },
+            },
+        };
+    }
+}
+exports.FirecrawlApi = FirecrawlApi;

package/dist/nodes/Firecrawl/Firecrawl.node.d.ts

@@ -0,0 +1,5 @@
+import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class Firecrawl implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}