Developer and Implementation Reference

This page documents the internal structure and implementation model of the Davix H2I n8n node for developers, maintainers, and technical reviewers who need to understand how the node is structured, how requests are built, how outputs are produced, and how the package is built and distributed.

Repository structure overview #

The implementation specification documents the repository structure as:

/root
 ├─ README.md
 ├─ LICENSE
 ├─ package.json
 ├─ package-lock.json
 ├─ tsconfig.json
 ├─ eslint.config.js
 ├─ src/
 │   └─ index.ts
 ├─ credentials/
 │   └─ DavixH2IApi.credentials.ts
 ├─ nodes/
 │   └─ DavixH2I/
 │       ├─ DavixH2I.node.ts
 │       ├─ GenericFunctions.ts
 │       └─ davixH2I.svg
 └─ tests/
     └─ GenericFunctions.test.js

This structure is the foundation for node registration, runtime behavior, and package distribution.

Main implementation files #

The node is implemented primarily through three code areas:

• Node definition and runtime logic: nodes/DavixH2I/DavixH2I.node.ts
• Request and error helpers: nodes/DavixH2I/GenericFunctions.ts
• Credential definition: credentials/DavixH2IApi.credentials.ts

In practice:

• the node file owns UI fields, resource and operation logic, and execution branching
• the helper file owns request preparation, base URL validation, error parsing, and download helper behavior
• the credential file owns the Base URL and API Key credential schema shown in n8n

Node registration and definition #

The implementation specification confirms:

• class name: DavixH2I
• the class implements INodeType
• node metadata is declared in description: INodeTypeDescription
• the description object includes displayName, name, icon, group, version, subtitle, defaults, inputs, outputs, credentials, and properties

The node definition also documents:

• display name: Davix H2I
• icon: file:davixH2I.svg
• group: ['transform']
• version: 1

The node declares one required credential reference:

• davixH2IApi

This means the node is implemented as a single n8n node type with one credential dependency and one UI model that changes dynamically according to the selected resource and operation.

High-level architecture #

The architecture overview documents the runtime flow as:

n8n Workflow → DavixH2I.execute() → davixRequest() / this.helpers.request() → PixLab REST path (/v1/h2i, /v1/image, /v1/pdf, /v1/tools) → response JSON (optional URL download to binary) → n8n output items.

It also describes the structural map:

DavixH2I (INodeType)
 ├─ description
 │   ├─ credentials: davixH2IApi
 │   └─ properties: resource/operation and per-operation fields
 └─ execute()
     ├─ per-item loop
     ├─ local helpers (gatherAllUrls, attachFiles, attachSingleFile, checkTotalBinarySize)
     ├─ resource branches (h2i/image/pdf/tools)
     ├─ request dispatch via davixRequest
     ├─ optional downloadToBinary + prepareBinaryData
     └─ error handling (continueOnFail vs throw)

This is the core implementation model of the repository.

Execution lifecycle #

Execution is implemented in:

async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>

The documented behavior of execute() is:

• read input items with this.getInputData()
• iterate item by item
• read resource and operation through this.getNodeParameter(...)
• branch by resource
• push output items into out
• return [out] at the end

The architecture and limits documentation also confirm that item processing is sequential in a for loop and uses awaited operations for request dispatch and optional file download.

That means:

• the node is per-item in design
• requests are not documented as parallelized inside the node
• output remains item-scoped throughout execution

Local helper functions inside execute() #

The implementation spec documents local helper closures defined inside execute():

• gatherAllUrls
• attachFiles
• attachSingleFile
• checkTotalBinarySize

These support runtime behavior as follows.

gatherAllUrls #

Used to collect output URLs from backend responses before binary-download logic runs. This helper is part of the output and file-download path.

attachFiles #

Used to attach one or more binary inputs to multipart requests. The file-handling documentation confirms that Image and Tools use multipart field name images, while PDF uses multipart field name files.

attachSingleFile #

Used for optional single-file attachment paths such as watermark image uploads. The file-handling documentation identifies watermarkImage as the optional single-file multipart field.

checkTotalBinarySize #

Used to enforce the node-side upload-size guard across attached binary inputs. The limits and error docs confirm that upload-size validation exists in node execution. For exact numeric values, use the shared Errors and Limits documentation.

Resource branching model #

Execution routing uses explicit conditional branching:

• if (resource === 'h2i')
• if (resource === 'image')
• if (resource === 'pdf')
• if (resource === 'tools')

Within those branches:

• H2I uses operation-dependent JSON body construction
• Image uses a switch (action) for per-action form fields
• PDF uses operation-specific if (action === ...) blocks
• Tools uses single vs multitask logic with tool-specific conditional field population

This is the main architectural reason the node can support many operations without being split into multiple node types.

Resource and operation model in implementation terms #

The resource-and-operation model is defined through UI fields and realized at runtime by mapping each resource to a request path and request style.

The resource map is:

• h2i
• image
• pdf
• tools

The runtime endpoint mapping is:

• h2i → POST /v1/h2i
• image → POST /v1/image
• pdf → POST /v1/pdf
• tools → POST /v1/tools

The request-style mapping is:

• H2I → JSON body
• Image → multipart formData
• PDF → multipart formData
• Tools → multipart formData

Together, these mappings define:

• field visibility in the UI
• payload assembly in execution
• endpoint dispatch in the request layer

Request helper implementation #

Request options are centrally normalized in:

buildDavixRequestOptions(options, baseUrl, apiKey)

Documented helper behavior includes:

• combining credential Base URL and endpoint path
• normalizing slashes
• injecting x-api-key
• dispatching through this.helpers.request(...)

The authentication and security docs confirm:

• this.getCredentials('davixH2IApi') is used to read credentials
• baseUrl and apiKey are read from the credential
• authentication is manual header injection, not a credential authenticate block
• Base URL validation enforces HTTPS and rejects embedded URL credentials

That makes GenericFunctions.ts the critical infrastructure layer for outbound communication.

Request construction by resource #

The implementation docs describe request construction per resource.

H2I #

• builds JSON body
• includes fields such as action, HTML, CSS, dimensions, and PDF/image render settings depending on operation
• posts to /v1/h2i

Image #

• builds multipart formData
• attaches files under images
• adds operation-specific parameters depending on the selected Image operation
• posts to /v1/image

PDF #

• builds multipart formData
• attaches files under files
• conditionally adds fields for merge, split, extract, watermark, rotate, metadata, reorder, flatten, encrypt, decrypt, and other PDF operations
• posts to /v1/pdf

Tools #

• builds multipart formData
• attaches files under images
• adds fields according to single-tool or multitask-tool logic
• posts to /v1/tools

The implementation docs also emphasize that the node does not forward the entire input item automatically; it explicitly constructs payloads from declared node parameters.

File and binary implementation model #

The file-handling documentation confirms that the node uses resource-specific binary property fields:

• imageBinaryProps
• pdfBinaryProps
• toolsBinaryProps

The node reads file buffers from incoming item binary data using this.helpers.getBinaryDataBuffer(itemIndex, propertyName), and reads file metadata such as filename and MIME type from the item’s binary object.

The implementation supports:

• multiple file attachment via comma-separated binary property lists
• optional single watermark file attachment through watermarkImage
• optional post-response binary download for H2I, Image, and PDF

That means the node acts as both:

• an uploader of input binaries to the selected API endpoint
• a downloader of output binaries when enabled by the matching output fields

Output implementation #

The output-contract documentation states that:

• one output item is pushed per processed input item on the success path
• output is manually built with out.push(...)
• successful json is the backend response object returned by davixRequest
• optional binary is added only for supported resources and only when download is enabled

Resource-specific output behavior is:

• H2I → JSON, optional binary
• Image → JSON, optional binary, except metadata is JSON-only in practice
• PDF → JSON, optional binary
• Tools → JSON only in the documented model

For implementation and extension work, the most important design fact is that the node returns backend responses unmodified in json rather than normalizing them into a custom node-specific schema.

Error-handling implementation #

The error-handling docs describe a layered failure model:

• validation errors from local checks
• HTTP and API errors from davixRequest()
• post-response errors such as missing output URL when binary download is enabled

The request helper:

• catches request failures
• reads statusCode
• reads backend error body
• parses backend envelope fields such as code, message, hint, and requestId
• throws NodeApiError with constructed details

The execution path:

• wraps each item in try/catch
• if continueOnFail() is enabled, emits an error item with error, optional description, and optional httpCode
• otherwise rethrows the error and stops execution

This per-item error model is a key implementation decision and should be preserved if behavior compatibility matters.

Validation logic and node-enforced constraints #

The limits, error, and security docs confirm several code-backed constraints:

• upload-size validation for binary uploads
• missing binary-property-list validation
• Image Multitask requires at least one selected action
• Tools Single requires a selected tool
• Tools Multitask requires at least one selected tool
• PDF reorder validates order input
• H2I HTML is marked required in the UI definition

From a maintenance perspective, these rules are part of the node’s request-shaping and error-surface contract.

Security implementation #

The security docs confirm the following implementation facts:

• the node uses one credential type with baseUrl and apiKey
• the API key is a password-style field
• the request helper injects x-api-key
• Base URL validation enforces HTTPS
• Base URL validation rejects embedded credentials
• the repository does not document OAuth or Bearer auth for this node
• the node does not document explicit runtime logging in its request path

These are the code-backed security assumptions for maintainers and reviewers.

Observability and support characteristics #

The observability playbook states that this repository does not implement explicit runtime logging in the node code and does not document a node-level debug flag. Error visibility instead comes from:

• NodeApiError and NodeOperationError
• continue-on-fail output
• n8n execution results
• backend-derived error fields surfaced by the request helper

This is relevant for implementation work because debugging this node relies more on execution output and controlled request inspection than on built-in logging instrumentation.

Package, build, and distribution model #

The installation, build, and release documentation confirms:

• package name: n8n-nodes-davix-h2i
• build output goes to dist
• build command: npm run build → tsc && npm run copy:icons
• dev/watch command: npm run dev → tsc --watch
• package main entrypoint: dist/index.js
• declaration output: dist/index.d.ts
• published package files are limited to dist
• distribution model is npm package / n8n community node package

The metadata and governance documentation also confirms:

• package version: 1.0.0
• node definition version: 1
• runtime requirement: Node.js >=20
• no explicit pinned n8n version beyond peerDependencies.n8n-workflow: "*"

Versioning and release facts #

The metadata and build docs confirm:

• current package version: 1.0.0
• node implementation metadata uses version: 1
• GitHub Actions publish automation exists
• publish trigger includes tag pushes matching v*.*.*
• publish command is npm publish --provenance --access public

This is useful context for maintainers preparing release-oriented documentation or build changes.

Safe extension and maintenance considerations #

Based on the implementation docs, safe extension work should preserve these core contracts unless intentionally versioned and documented:

• one credential type for the node
• resource-driven UI model
• per-item sequential execution
• explicit request construction
• backend response pass-through in json
• optional binary attachment behavior for supported resources
• continue-on-fail item-level error behavior

These are the main observable behaviors that users and downstream workflows rely on.