@heebai/n8n-nodes-heeb 26.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Heeb
+
+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,48 @@
+<!-- vale Vale.Spelling = NO -->
+
+# @heebai/n8n-nodes-heeb
+
+An [n8n](https://n8n.io) community node for the [Heeb](https://heeb.ai) LLM Mentions API.
+
+Heeb measures how a brand is referenced inside AI answers, the way classic SEO tools measure Google rankings. This node submits a query to Heeb, optionally waits for the aggregated result, and returns per-model answers, sources, citations, mentions, and the combined visibility and sentiment scores.
+
+## Installation
+
+Follow the [community nodes installation guide](https://docs.n8n.io/integrations/community-nodes/installation/). In a self-hosted n8n, open **Settings > Community Nodes**, choose **Install**, and enter `@heebai/n8n-nodes-heeb`.
+
+## Credential
+
+Create a **Heeb API** credential and paste an API key from the API Keys page in the Heeb dashboard. The key travels as the `x-api-key` header on every request. The credential test sends one lightweight call to confirm the key is accepted. Leave **Base URL** at `https://heeb.ai` unless you target a proxied deployment.
+
+## Operations
+
+### Submit Query
+
+Submit a prompt, the entity to track, one or more models, and an optional country code.
+
+- With **Wait for Completion** on, the node polls `GET /api/query/{job_id}` until the job settles, then returns the full result. Heeb jobs settle in 30 seconds to 2 minutes; tune **Timeout** and **Poll Interval** to match.
+- With **Wait for Completion** off, the node returns the `job_id` right away. Fetch the result later with **Get Result**.
+
+**Models** is a comma-separated list of Heeb model IDs, for example `openai/gpt-5.6-luna, google/ai-mode`. The sellable catalog changes over time, so read the Heeb docs for the current list rather than pinning one in the workflow.
+
+### Get Result
+
+Fetch a job by its `job_id`. The response is `{ "status": "pending" }` while the job runs, or the aggregated result once it settles.
+
+## Errors
+
+The node maps Heeb failures onto typed n8n errors:
+
+- A rejected API key becomes a node error that points you back to the credential.
+- An out-of-credits response becomes a node error that asks you to top up.
+- A wait that outlives its timeout becomes a node error; the `job_id` stays valid, so fetch it later with **Get Result**.
+
+Turn on **Continue On Fail** to collect errors per item instead of stopping the workflow.
+
+## Setup help
+
+Setup walkthrough and an example workflow you can import: <https://heeb.ai/integrations/n8n>
+
+## License
+
+[MIT](LICENSE)

package/dist/credentials/HeebApi.credentials.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeebApi = void 0;
+class HeebApi {
+    constructor() {
+        this.name = "heebApi";
+        this.displayName = "Heeb API";
+        this.documentationUrl = "https://heeb.ai/docs";
+        this.properties = [
+            {
+                displayName: "API Key",
+                name: "apiKey",
+                type: "string",
+                typeOptions: { password: true },
+                default: "",
+                required: true,
+                description: "Heeb API key, created under API Keys in the Heeb dashboard. Sent as the x-api-key header.",
+            },
+            {
+                displayName: "Base URL",
+                name: "baseUrl",
+                type: "string",
+                default: "https://heeb.ai",
+                description: "Base URL of the Heeb API. Change this only for a self-hosted or proxied deployment.",
+            },
+        ];
+        this.authenticate = {
+            type: "generic",
+            properties: {
+                headers: {
+                    "x-api-key": "={{$credentials.apiKey}}",
+                },
+            },
+        };
+    }
+}
+exports.HeebApi = HeebApi;

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Heeb = exports.HeebApi = void 0;
+var HeebApi_credentials_1 = require("./credentials/HeebApi.credentials");
+Object.defineProperty(exports, "HeebApi", { enumerable: true, get: function () { return HeebApi_credentials_1.HeebApi; } });
+var Heeb_node_1 = require("./nodes/heeb/Heeb.node");
+Object.defineProperty(exports, "Heeb", { enumerable: true, get: function () { return Heeb_node_1.Heeb; } });

package/dist/nodes/heeb/Heeb.node.js

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Heeb = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+const errors_1 = require("./errors");
+const poll_1 = require("./poll");
+const transport_1 = require("./transport");
+class Heeb {
+    constructor() {
+        this.description = {
+            displayName: "Heeb",
+            name: "heeb",
+            icon: "file:heeb.svg",
+            group: ["transform"],
+            version: 1,
+            subtitle: '={{$parameter["operation"]}}',
+            description: "Measure how a brand is mentioned across LLM answers with the Heeb LLM Mentions API",
+            defaults: {
+                name: "Heeb",
+            },
+            inputs: ["main"],
+            outputs: ["main"],
+            credentials: [
+                {
+                    name: "heebApi",
+                    required: true,
+                    testedBy: "heebApiTest",
+                },
+            ],
+            properties: [
+                {
+                    displayName: "Operation",
+                    name: "operation",
+                    type: "options",
+                    noDataExpression: true,
+                    options: [
+                        {
+                            name: "Get Result",
+                            value: "get",
+                            action: "Get a query result by job ID",
+                            description: "Fetch a job result by job_id, pending or settled",
+                        },
+                        {
+                            name: "Submit Query",
+                            value: "submit",
+                            action: "Submit a query",
+                            description: "Submit a query and optionally wait for the aggregated result",
+                        },
+                    ],
+                    default: "submit",
+                },
+                {
+                    displayName: "Prompt",
+                    name: "prompt",
+                    type: "string",
+                    typeOptions: { rows: 2 },
+                    default: "",
+                    required: true,
+                    placeholder: "what are the best running shoes in 2026?",
+                    description: "The buyer question to ask each model",
+                    displayOptions: { show: { operation: ["submit"] } },
+                },
+                {
+                    displayName: "Entity Name",
+                    name: "entityName",
+                    type: "string",
+                    default: "",
+                    required: true,
+                    placeholder: "Nike",
+                    description: "Brand or entity to track in the answers",
+                    displayOptions: { show: { operation: ["submit"] } },
+                },
+                {
+                    displayName: "Entity URL",
+                    name: "entityUrl",
+                    type: "string",
+                    default: "",
+                    required: true,
+                    placeholder: "https://nike.com",
+                    description: "Official URL for the entity",
+                    displayOptions: { show: { operation: ["submit"] } },
+                },
+                {
+                    displayName: "Models",
+                    name: "models",
+                    type: "string",
+                    default: "",
+                    required: true,
+                    placeholder: "openai/gpt-5.6-luna, google/ai-mode",
+                    description: "Comma-separated Heeb model IDs to query. The sellable catalog changes over time; see the Heeb docs for the current list.",
+                    displayOptions: { show: { operation: ["submit"] } },
+                },
+                {
+                    displayName: "Country Code",
+                    name: "country",
+                    type: "string",
+                    default: "US",
+                    description: "ISO country code for the geographic context",
+                    displayOptions: { show: { operation: ["submit"] } },
+                },
+                {
+                    displayName: "Wait for Completion",
+                    name: "waitForCompletion",
+                    type: "boolean",
+                    default: true,
+                    description: "Whether to poll until the job settles and return the full result. Turn off to return the job_id immediately.",
+                    displayOptions: { show: { operation: ["submit"] } },
+                },
+                {
+                    displayName: "Timeout",
+                    name: "timeout",
+                    type: "number",
+                    typeOptions: { minValue: 1 },
+                    default: 120,
+                    description: "Seconds to keep polling before giving up. Heeb jobs usually settle in 30 to 120 seconds.",
+                    displayOptions: {
+                        show: { operation: ["submit"], waitForCompletion: [true] },
+                    },
+                },
+                {
+                    displayName: "Poll Interval",
+                    name: "pollInterval",
+                    type: "number",
+                    typeOptions: { minValue: 1 },
+                    default: 5,
+                    description: "Seconds to wait between result checks while polling",
+                    displayOptions: {
+                        show: { operation: ["submit"], waitForCompletion: [true] },
+                    },
+                },
+                {
+                    displayName: "Job ID",
+                    name: "jobId",
+                    type: "string",
+                    default: "",
+                    required: true,
+                    description: "The job_id returned by Submit Query",
+                    displayOptions: { show: { operation: ["get"] } },
+                },
+            ],
+        };
+        this.methods = {
+            credentialTest: {
+                async heebApiTest(credential) {
+                    const data = credential.data ?? {};
+                    const baseUrl = String(data.baseUrl || transport_1.DEFAULT_BASE_URL).replace(/\/+$/, "");
+                    try {
+                        await this.helpers.request({
+                            method: "GET",
+                            uri: `${baseUrl}/api/query/00000000-0000-0000-0000-000000000000`,
+                            headers: { "x-api-key": String(data.apiKey ?? "") },
+                            json: true,
+                        });
+                        return { status: "OK", message: "Heeb API key is valid" };
+                    }
+                    catch (error) {
+                        const code = Number(error.statusCode ?? error.httpCode ?? error.cause?.statusCode);
+                        if (code === 401 || code === 403) {
+                            return { status: "Error", message: "Invalid Heeb API key" };
+                        }
+                        return { status: "OK", message: "Heeb API key is valid" };
+                    }
+                },
+            },
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const returnData = [];
+        for (let i = 0; i < items.length; i++) {
+            try {
+                const operation = this.getNodeParameter("operation", i);
+                if (operation === "submit") {
+                    const models = this.getNodeParameter("models", i)
+                        .split(",")
+                        .map((model) => model.trim())
+                        .filter(Boolean);
+                    if (models.length === 0) {
+                        throw new n8n_workflow_1.NodeOperationError(this.getNode(), "At least one model is required", { itemIndex: i });
+                    }
+                    const body = {
+                        models,
+                        prompt: this.getNodeParameter("prompt", i),
+                        entity: {
+                            name: this.getNodeParameter("entityName", i),
+                            url: this.getNodeParameter("entityUrl", i),
+                        },
+                        location: this.getNodeParameter("country", i) || "US",
+                    };
+                    const submit = (await transport_1.heebApiRequest.call(this, "POST", "/api/query", body));
+                    if (!this.getNodeParameter("waitForCompletion", i)) {
+                        returnData.push({ json: submit, pairedItem: { item: i } });
+                        continue;
+                    }
+                    const timeoutMs = this.getNodeParameter("timeout", i) * 1000;
+                    const intervalMs = this.getNodeParameter("pollInterval", i) * 1000;
+                    const result = await (0, poll_1.pollForResult)({
+                        jobId: submit.job_id,
+                        fetchOnce: () => transport_1.heebApiRequest.call(this, "GET", `/api/query/${encodeURIComponent(submit.job_id)}`),
+                        timeoutMs,
+                        intervalMs,
+                    });
+                    returnData.push({
+                        json: { job_id: submit.job_id, ...result },
+                        pairedItem: { item: i },
+                    });
+                }
+                else {
+                    const jobId = this.getNodeParameter("jobId", i);
+                    const result = (await transport_1.heebApiRequest.call(this, "GET", `/api/query/${encodeURIComponent(jobId)}`));
+                    returnData.push({ json: result, pairedItem: { item: i } });
+                }
+            }
+            catch (error) {
+                if (this.continueOnFail()) {
+                    returnData.push({
+                        json: { error: error.message },
+                        pairedItem: { item: i },
+                    });
+                    continue;
+                }
+                throw (0, errors_1.wrapHeebError)(this.getNode(), error, i);
+            }
+        }
+        return [returnData];
+    }
+}
+exports.Heeb = Heeb;

package/dist/nodes/heeb/errors.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractApiError = extractApiError;
+exports.heebErrorMessage = heebErrorMessage;
+exports.wrapHeebError = wrapHeebError;
+const n8n_workflow_1 = require("n8n-workflow");
+const poll_1 = require("./poll");
+function extractApiError(body) {
+    if (typeof body === "string") {
+        try {
+            const parsed = JSON.parse(body);
+            if (typeof parsed.error === "string")
+                return parsed.error;
+        }
+        catch { }
+        return body;
+    }
+    if (body !== null && typeof body === "object") {
+        const value = body.error;
+        if (typeof value === "string")
+            return value;
+    }
+    return "";
+}
+function heebErrorMessage(statusCode, body) {
+    const apiError = extractApiError(body);
+    if (statusCode === 401 || statusCode === 403) {
+        return {
+            message: "Heeb rejected the API key",
+            description: "The x-api-key is missing or invalid. Check the API key in the Heeb credential.",
+        };
+    }
+    if (statusCode === 400 && /insufficient balance/i.test(apiError)) {
+        return {
+            message: "Insufficient Heeb credits",
+            description: "The account does not have enough credits for this query. Top up at https://heeb.ai and try again.",
+        };
+    }
+    if (statusCode === 400 && /no jobs? found/i.test(apiError)) {
+        return {
+            message: "Job not found",
+            description: "No job with that job_id exists for this account. Use the job_id returned by Submit Query.",
+        };
+    }
+    if (statusCode === 400) {
+        return {
+            message: apiError || "Heeb rejected the request",
+            description: "The request was invalid. Check the prompt, entity, models and country fields.",
+        };
+    }
+    return {
+        message: apiError || "Heeb request failed",
+        description: apiError
+            ? ""
+            : `Heeb returned an unexpected response${statusCode ? ` (HTTP ${statusCode})` : ""}.`,
+    };
+}
+function pickStatus(error) {
+    const raw = error.httpCode ??
+        error.statusCode ??
+        error.response?.statusCode ??
+        error.cause?.statusCode;
+    const code = Number(raw);
+    return Number.isFinite(code) ? code : undefined;
+}
+function pickBody(error) {
+    return error.response?.body ?? error.cause?.error ?? error.error;
+}
+function wrapHeebError(node, error, itemIndex) {
+    if (error instanceof poll_1.HeebTimeoutError) {
+        return new n8n_workflow_1.NodeOperationError(node, error.message, {
+            description: "The job is still running. Increase the timeout, or fetch it later with the Get Result operation and the returned job_id.",
+            itemIndex,
+        });
+    }
+    const httpError = (error ?? {});
+    const info = heebErrorMessage(pickStatus(httpError), pickBody(httpError));
+    return new n8n_workflow_1.NodeApiError(node, httpError, {
+        message: info.message,
+        description: info.description,
+        itemIndex,
+    });
+}

package/dist/nodes/heeb/heeb.svg

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   viewBox="167.4864 183.648 48.44968 42.538776"
+   width="48.449814"
+   height="42.538776"
+   version="1.1"
+   id="svg1"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <defs
+     id="defs1" />
+  <g
+     id="object-3"
+     transform="matrix(2.2988028,0,0,2.2988028,-217.53218,-238.52254)">
+    <path
+       d="m 185.797,183.648 h -15.536 c -2.139,0.015 -3.466,2.332 -2.397,4.185 l 7.772,12.974 c 1.085,1.792 3.685,1.795 4.775,0.005 l 7.765,-12.964 c 1.083,-1.85 -0.237,-4.179 -2.38,-4.2 z"
+       style="stroke-width:1"
+       id="object-1" />
+  </g>
+</svg>

package/dist/nodes/heeb/poll.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeebTimeoutError = void 0;
+exports.isPending = isPending;
+exports.pollForResult = pollForResult;
+class HeebTimeoutError extends Error {
+    constructor(jobId, timeoutMs) {
+        super(`Heeb job ${jobId} did not settle within ${Math.round(timeoutMs / 1000)}s`);
+        this.jobId = jobId;
+        this.timeoutMs = timeoutMs;
+        this.name = "HeebTimeoutError";
+    }
+}
+exports.HeebTimeoutError = HeebTimeoutError;
+function isPending(response) {
+    return (typeof response === "object" &&
+        response !== null &&
+        response.status === "pending");
+}
+async function pollForResult(options) {
+    const now = options.now ?? (() => Date.now());
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const start = now();
+    for (;;) {
+        const response = await options.fetchOnce();
+        if (!isPending(response)) {
+            return response;
+        }
+        if (now() - start >= options.timeoutMs) {
+            throw new HeebTimeoutError(options.jobId, options.timeoutMs);
+        }
+        await sleep(options.intervalMs);
+    }
+}

package/dist/nodes/heeb/transport.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BASE_URL = void 0;
+exports.heebApiRequest = heebApiRequest;
+exports.DEFAULT_BASE_URL = "https://heeb.ai";
+async function heebApiRequest(method, path, body) {
+    const credentials = await this.getCredentials("heebApi");
+    const baseUrl = String(credentials.baseUrl || exports.DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const options = {
+        method,
+        url: `${baseUrl}${path}`,
+        json: true,
+    };
+    if (body !== undefined) {
+        options.body = body;
+    }
+    return await this.helpers.httpRequestWithAuthentication.call(this, "heebApi", options);
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@heebai/n8n-nodes-heeb",
+	"version": "26.9.1",
+	"description": "n8n community node for the Heeb LLM Mentions API, which measures how a brand is referenced inside AI answers.",
+	"keywords": [
+		"n8n-community-node-package",
+		"n8n",
+		"heeb",
+		"geo",
+		"ai-seo",
+		"llm"
+	],
+	"license": "MIT",
+	"homepage": "https://heeb.ai/integrations/n8n",
+	"author": {
+		"name": "Heeb",
+		"email": "hello@heeb.ai"
+	},
+	"bugs": {
+		"email": "hello@heeb.ai"
+	},
+	"engines": {
+		"node": ">=20.15"
+	},
+	"main": "dist/index.js",
+	"scripts": {
+		"build": "rm -rf dist && tsc && cp nodes/heeb/heeb.svg dist/nodes/heeb/heeb.svg",
+		"dev": "tsc --watch",
+		"test": "bun run build && vitest run",
+		"prepublishOnly": "npm run build"
+	},
+	"files": [
+		"dist"
+	],
+	"n8n": {
+		"n8nNodesApiVersion": 1,
+		"credentials": [
+			"dist/credentials/HeebApi.credentials.js"
+		],
+		"nodes": [
+			"dist/nodes/heeb/Heeb.node.js"
+		]
+	},
+	"peerDependencies": {
+		"n8n-workflow": "*"
+	},
+	"devDependencies": {
+		"@types/node": "^20.19.0",
+		"n8n-workflow": "*",
+		"typescript": "^5.6.3",
+		"vitest": "^3.2.0"
+	}
+}