n8n-nodes-fluidx

Community n8n node for the fluidX revXR THE EYE API. Adds a single fluidX node that exposes:

Once installed it appears in n8n's node search as fluidX.

Requirements

• Node.js 20.15 or newer.
• An n8n version that supports community nodes (self-hosted, or n8n Cloud where the node is
  installable from the verified-node catalogue).
• A fluidX tenant API key. Media → Download additionally requires a TENANT_ADMIN key.

Install

A) Via the community node UI (recommended)

In n8n: Settings → Community Nodes → Install and enter:

n8n-nodes-fluidx

B) Local development against your n8n instance

git clone <this-repo> n8n-nodes-fluidx
cd n8n-nodes-fluidx
npm install
npm run build
# link it into your n8n custom-nodes folder
npm link
cd ~/.n8n/custom
npm link n8n-nodes-fluidx
# restart n8n

Credentials

After install, create a new credential of type fluidX API with:

• Base URL — your fluidX root, e.g. https://live.fluidx.digital
• API Key — your tenant API key (sent as x-api-key)

The credential test hits GET /api/healthz against the configured Base URL.

Build

npm install
npm run build      # compiles TS + copies SVG icons
npm run dev        # watch mode
npm run lint

Output goes to dist/. The n8n block in package.json points at
dist/credentials/FluidXApi.credentials.js and dist/nodes/FluidX/FluidX.node.js.

Endpoints covered

Session summary (plain text)

Media → Get Summary calls an endpoint that answers with text/plain, not JSON. The node
normalises that into named fields, so the summary is a proper string on the output item:

{
  "sessionId": "faf5ef0c-...",
  "summary": "photo-123.png\nTitle: ...\nDescription: ...\n",
  "data": "photo-123.png\nTitle: ...\nDescription: ...\n"
}

Use {{ $json.summary }}. data holds the identical string under the field name n8n's generic
HTTP Request node uses for non-JSON responses, so an existing workflow that reads data keeps
working.

Up to and including 0.4.1 the raw text was pushed as the item JSON itself, which n8n surfaces as
a character-indexed object ({"0":"T","1":"i", ...}) that no expression can read sensibly. If you
built a workflow against that shape, switch it to {{ $json.summary }}.

Downloading media (binary)

Media → Download streams the original binary of a captured photo or video and writes it
to a binary property on the output item (default field name data), so you can pipe it
straight into Write Binary File, Move Binary Data, email attachments, S3, etc.

Parameters:

• Source — how to address the media:
  • By ID — build the request from Session ID, Media ID and Type (+ optional Format).
  • By URL — paste a ready download URL (e.g. a photoRefs[].url / videoRefs[].url
    link from a session response). The API key is still sent automatically, so you don't need a
    separate HTTP Request node with header auth.
• Session ID / Media ID — identify the captured media (By ID mode).
• Type — Photo or Video (By ID mode).
• Format — video only; WebM (default) or MP4 transcode. Ignored for photos.
• URL — the download link (By URL mode).
• Put Output In Field — name of the binary property to write to (default data).
• File Name — optional; otherwise derived from the media ID, type, and the response
  Content-Type (e.g. photo-77.png, video-12.webm).

The endpoint requires a TENANT_ADMIN API key.

The JSON side of the output item carries { sessionId, mediaId, type, fileName }; the actual
bytes live in the binary property.

Discovering media IDs

A Session → Get (or Create) response includes photoRefs and videoRefs arrays, each entry
having an id and a ready url that already points at /api/fx/ext/media/download. You can
either:

1. By ID — feed each id into a Media → Download node (it builds the request for you), or
2. By URL — pass the url straight into a Media → Download node in By URL mode
   (e.g. {{ $json.url }}). This is the one-node equivalent of a generic HTTP Request node
   with header auth.

Releasing

Releases are managed locally with release-it and published from CI with npm provenance.

# interactive (asks which version bump to use)
npm run release

# non-interactive bumps
npm run release:patch
npm run release:minor
npm run release:major

# preview without changing anything
npm run release:dry

release-it will: run lint + build, bump the version in package.json, update CHANGELOG.md from conventional commits, commit, tag (vX.Y.Z), push, and create the GitHub release. The pushed tag triggers .github/workflows/publish.yml, which runs npm publish with provenance — required for n8n's verified-node program.

Prerequisites:

• Run on the main branch with a clean working tree.
• Authenticate with GitHub so a release can be created: either export GITHUB_TOKEN, or use GITHUB_TOKEN="$(gh auth token)" npm run release.
• The NPM_TOKEN secret must be set in the GitHub repo so the publish workflow can authenticate.

If the publish job fails with npm error code E404 on PUT https://registry.npmjs.org/n8n-nodes-fluidx,
the package is not missing — that is npm's response to an expired or revoked publish token. Rotate
the NPM_TOKEN secret and re-run the failed job; no new tag or version bump is needed. npm granular access tokens expire after at most 90 days, so expect this roughly quarterly
until the workflow is migrated to trusted publishing
(OIDC), which needs no token at all.

Use Conventional Commits (feat:, fix:, ci:, docs:, etc.) so the changelog and version bump are derived correctly.

License

MIT