How rapiercraft/n8n-nodes-alterlab works
1. Repository role
- This is an n8n community node package named n8n-nodes-alterlab.
- Its purpose is to expose AlterLab’s web-scraping API as an n8n workflow node so workflows can send URLs and receive scraped content back.
2. Core runtime boundary
- The package is a Node.js / TypeScript library, not a standalone app.
- It runs inside the n8n host process as a custom node extension and depends on n8n’s node/credential SDK conventions.
3. Main functional subsystem: AlterLab node
- The central implementation lives under nodes/AlterLab/AlterLab.node.ts.
- AlterLab.node.json is the node manifest used by n8n to describe the node’s UI, inputs, outputs, and behavior.
- This is the primary execution unit that maps n8n workflow items into AlterLab API calls and returns results back into the workflow.
4. Authentication subsystem
- Two credential types are defined under credentials/:
- AlterLabApi.credentials.ts for API key authentication.
- AlterLabOAuth2Api.credentials.ts for OAuth2-based sign-in.
- These form a separate boundary from the node logic: the node consumes credentials, but credential handling is encapsulated in dedicated n8n credential definitions.
5. External service dependency
- The package is a client for the AlterLab SaaS API.
- That external platform performs the actual scraping, anti-bot handling, JavaScript rendering, extraction, screenshot/PDF/OCR, and tier selection described in the README.
- The node is therefore mostly an orchestration and data-mapping layer between n8n and AlterLab.
6. Workflow data flow
- Input typically enters as one or more n8n items containing a URL and optional scrape options.
- The node sends those parameters to AlterLab, then receives a response containing fields such as markdown, text, raw HTML, structured JSON, billing metadata, and optional artifact URLs.
- The node flattens this into n8n-friendly JSON output for downstream nodes.
7. Outputs and downstream integration
- The output contract is designed for workflow chaining:
- human/LLM-friendly text like markdown
- machine-readable structured data like json / filteredContent
- operational metadata like billing.cost and billing.tier
- optional artifact links like screenshotUrl and pdfUrl
- This makes the node a producer for other n8n nodes such as filters, sheet sinks, Slack, Notion, databases, or AI steps.
8. Execution modes and scrape orchestration
- The README indicates support for modes such as auto, html, js, pdf, and ocr, plus extraction profiles and custom schemas/prompts.
- Architecturally, this means the node is not just a raw fetch wrapper; it is a parameterized request orchestrator that lets workflows choose scraping strategy and output shape.
9. Build and packaging layer
- package.json, tsconfig.json, and gulpfile.js indicate a build pipeline that compiles TypeScript into distributable JavaScript for n8n.
- The package is published to npm and intended to be installed via n8n’s community node mechanism or standard npm installation.
10. Release and CI/CD boundary
- GitHub Actions under .github/workflows/ handle:
- CI validation
- automated publishing to npm on release
- project automation
- This separates source development from package distribution and enforces the package’s compiled output before publication.
11. Repo structure and assets
- assets/ contains branding and screenshots used primarily for the README and marketplace presentation.
- These do not affect runtime behavior, but they signal that the repo is a packaged integration distributed through npm and n8n’s UI.
12. Operational assumptions
- The package assumes network access to AlterLab’s API and a configured credential in n8n.
- Any scaling, anti-bot bypass, browser rendering, proxying, or extraction intelligence happens outside the repo in the AlterLab platform, not locally in the node.
13. Diagram takeaway
- The architecture is best drawn as: n8n workflow item(s) → AlterLab node → AlterLab credentials → AlterLab API service → structured scrape response → downstream n8n nodes.
- The repo itself contains the node adapter, credential definitions, packaging/build logic, and release automation around that external API integration.
Main entry points: AlterLab.node.ts AlterLab node · package.json Package config · gulpfile.js Build script · AlterLab.node.json Node manifest
Components 17
n8n runtime
Custom node code that runs inside the n8n host process.
- Workflow items · Incoming n8n items carrying URLs and scrape options.
- AlterLab node · Main execution unit that maps workflow items to AlterLab requests and returns results.
nodes/AlterLab/AlterLab.node.ts - Node manifest · n8n UI and behavior definition for the AlterLab node.
nodes/AlterLab/AlterLab.node.json - Request orchestration · Selects scraping mode, extraction profile, and output shape for each request.
- Response mapper · Flattens AlterLab responses into n8n-friendly JSON for downstream steps.
Authentication
n8n credential definitions used by the node.
- API key · Credential definition for AlterLab API key authentication.
credentials/AlterLabApi.credentials.ts - OAuth2 login · Credential definition for AlterLab OAuth2 authentication.
credentials/AlterLabOAuth2Api.credentials.ts
External service
AlterLab SaaS API that performs scraping and extraction.
- AlterLab API · External scraping service that executes rendering, extraction, OCR, and artifact generation.
- Billing data · Cost and tier metadata returned with scrape results.
- Artifacts · Optional screenshot and PDF links returned by the service.
Build & release
Compilation, packaging, CI, and publishing automation.
- Package config · Package metadata and scripts for distribution.
package.json - TypeScript config · TypeScript compilation settings for the library.
tsconfig.json - Build script · Gulp-based build and packaging pipeline.
gulpfile.js - CI workflow · Validation workflow for source and build checks.
.github/workflows/ci.yml - Publish workflow · Automated npm publishing workflow for releases.
.github/workflows/publish.yml - Project automation · Repository automation for project management.
.github/workflows/project-auto-add.yml
Assets
Presentation and marketplace resources.
- Branding · Screenshots and brand assets used in README and marketplace presentation.
assets
Connections 18
- Workflow items → AlterLab node: input · n8n items enter the node for processing.
- Node manifest → AlterLab node: describes · Manifest defines node UI, inputs, outputs, and behavior.
- AlterLab node → Request orchestration: builds · Node converts workflow parameters into scrape requests.
- Request orchestration → API key: uses · API key credentials can authorize requests.
- Request orchestration → OAuth2 login: uses · OAuth2 credentials can authorize requests.
- Request orchestration → AlterLab API: calls · Requests are sent to the AlterLab scraping service.
- AlterLab API → Response mapper: returns · Service returns scraped content and metadata.
- Response mapper → Billing data: includes · Mapped output exposes cost and tier information.
- Response mapper → Artifacts: includes · Mapped output can include screenshot and PDF links.
- Response mapper → AlterLab node: outputs · Node emits flattened JSON back into the workflow.
- AlterLab node → Workflow items: produces · Workflow continues with the node's output items.
- Package config → Build script: scripts · Package scripts drive the build pipeline.
- TypeScript config → Build script: configures · TypeScript settings shape compilation output.
- Build script → AlterLab node: compiles · Source node code is compiled for distribution.
- CI workflow → Build script: validates · CI checks the build and package behavior.
- Publish workflow → Package config: publishes · Release workflow publishes the package to npm.
- Project automation → Package config: automates · Project automation supports repository workflow management.
- Branding → Package config: supports · Assets support README and marketplace presentation.