@loewencreville/n8n-nodes-ttn 1.0.0

package/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright 2026 Loewen Creville
+
+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,273 @@
+# n8n-nodes-ttn
+
+Community [n8n](https://n8n.io/) nodes for [The Things Stack](https://www.thethingsindustries.com/) (TTS) — also known as **The Things Network (TTN)** on the public cloud.
+
+Connect your LoRaWAN applications to n8n workflows: receive real-time uplinks via webhooks, read stored messages, send downlinks, and monitor devices and gateways through the TTS API.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Credentials](#credentials)
+- [Nodes](#nodes)
+  - [TTN (main node)](#ttn-main-node)
+  - [TTN Trigger (webhook)](#ttn-trigger-webhook)
+- [Usage examples](#usage-examples)
+- [Compatibility](#compatibility)
+- [Development](#development)
+- [Resources](#resources)
+- [Version history](#version-history)
+- [License](#license)
+
+## Installation
+
+Follow the [n8n community nodes installation guide](https://docs.n8n.io/integrations/community-nodes/installation/).
+
+**npm package:** `n8n-nodes-ttn`
+
+```bash
+# In n8n: Settings → Community Nodes → Install → enter "n8n-nodes-ttn"
+```
+
+For self-hosted n8n with a custom nodes folder (Docker volume, etc.):
+
+```bash
+git clone https://github.com/etoilary974-ship-it/TTN_Node.git
+cd TTN_Node
+npm install
+npm run build
+# Copy dist/ + package.json to your n8n custom nodes directory, then restart n8n.
+# Or use: npm run deploy
+```
+
+## Credentials
+
+### The Things Stack API (`ttnApi`)
+
+| Field | Description |
+|-------|-------------|
+| **Server URL** | Base URL of your TTS deployment, **without** `/api`. Examples: `https://eu1.cloud.thethings.network`, `https://<tenant>.thethings.industries`, or your self-hosted URL. See [TTS deployments](https://www.thethingsindustries.com/docs/getting-started/cloud-hosted/). |
+| **API key (Application Server)** | An **Application Server** API key (`NNSXS…` format). Sent as `Authorization: Bearer`. Must have rights for the applications, devices, and operations you use. |
+
+**Create an API key** in the TTS console: *User settings → API keys*, or per application under *API keys*. See the official guides:
+
+- [API authentication](https://www.thethingsindustries.com/docs/reference/api/authentication/)
+- [API key rights](https://www.thethingsindustries.com/docs/reference/api/using-terraform-provider/#generate-api-key)
+
+**Required rights by operation:**
+
+| Operation | Typical API key rights |
+|-----------|------------------------|
+| List applications / devices | `applications:list`, `applications.devices:list` |
+| Get device info / status | `applications.devices:get`, `applications.devices:read` |
+| Send downlink | `applications.devices:downlink` |
+| Storage (Get Last Uplink) | Application Server key with Storage access on the target application |
+| List / status gateways | `gateways:list`, `gateways:read` (Gateway Server) |
+
+The credential test calls `GET /api/v3/applications` to verify connectivity.
+
+> **Storage vs webhooks:** [Storage](https://www.thethingsindustries.com/docs/integrations/storage/) reads historical uplinks from the TTS database. [Webhooks](https://www.thethingsindustries.com/docs/integrations/webhooks/) push events to n8n in real time. Enable Storage on your application in TTS if you use **Get Last Uplink**.
+
+## Nodes
+
+All TTN nodes share the same icon and appear grouped in the n8n node picker under **TTN**.
+
+### TTN (main node)
+
+Unified action node with three resources.
+
+#### Data
+
+| Operation | TTS API | Description |
+|-----------|---------|-------------|
+| **Get Last Uplink** | `GET …/packages/storage/uplink_message` | Reads the [Storage integration](https://www.thethingsindustries.com/docs/integrations/storage/) uplink stream (`Accept: text/event-stream`). One n8n item per uplink received. Requires Storage enabled on the application. |
+| **List Devices** | `GET /api/v3/applications/{app}/devices` | Lists devices in an application. |
+| **Get Device Info** | `GET /api/v3/applications/{app}/devices/{device}` | Full device registry object. |
+| **Get Device Status** | Registry + `last_seen_at` | Online/offline status with configurable threshold. **Summary** returns `{ device_id, online, last_seen }`; **Detailed** includes timestamps and threshold settings. |
+| **List Applications** | `GET /api/v3/applications` | Applications visible to the API key. |
+
+**Get Last Uplink options:**
+
+- **Storage scope** — single device or whole application.
+- **`Last` window** — same duration format as the TTS console (`1h`, `24h`, `168h`, …). See [Storage API](https://www.thethingsindustries.com/docs/integrations/storage/).
+- **Uplink output shape** — Decoded Payload + Meta, Decoded Payload only, or Full Storage record.
+
+#### Devices
+
+| Operation | TTS API | Description |
+|-----------|---------|-------------|
+| **Send Downlink** | `POST …/down/push` | Enqueues a downlink on the device queue. |
+
+Downlink parameters match [The Things Stack downlink fields](https://www.thethingsindustries.com/docs/reference/api/application_server/#message-types):
+
+- **FPort** (1–223)
+- **Payload type** — Hex (`frm_payload`, base64-encoded by the node) or JSON (`decoded_payload`)
+- **Priority** — `LOWEST` … `HIGHEST`
+- **Confirmed downlink** — requires device ACK
+
+#### Gateways
+
+| Operation | TTS API | Description |
+|-----------|---------|-------------|
+| **List Gateways** | `GET /api/v3/gateways` (or per user / organization) | Scope: all gateways visible to the key, a specific user, or an organization. Optional antenna location. |
+| **Get Gateway Status** | `GET /api/v3/gs/gateways/{id}/connection/stats` | Last activity, uptime, `since_last_uplink`, online/offline (configurable threshold). |
+
+Dynamic dropdowns (applications, devices, gateways) support [n8n expressions](https://docs.n8n.io/code/expressions/) for dynamic IDs.
+
+API errors from TTS are mapped to readable messages with gRPC codes and suggested actions.
+
+---
+
+### TTN Trigger (webhook)
+
+Pick **TTN → Triggers → Webhook · Receive Events** in the node picker.
+
+Receives real-time POST webhooks from TTS — the recommended way to react to uplinks and other events. HTTP method is fixed to **POST**.
+
+#### TTS console setup
+
+1. Open your application in [TTS Console](https://console.cloud.thethings.network/).
+2. Go to **Integrations → Webhooks**.
+3. Set **Base URL** to your n8n webhook URL (test or production).
+4. Format: **JSON**. Method: **POST**.
+5. Under **Enabled event types**, check the events you need (e.g. **Uplink message**).
+
+Full guide: [TTS Webhooks integration](https://www.thethingsindustries.com/docs/integrations/webhooks/)
+
+#### Node parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| **Webhook path** | Path suffix after the n8n base URL (default: `ttn-uplink`). Must match the path configured in TTS. |
+| **Application (API)** | Optional filter: loads devices via API; webhook `application_id` must match when set. |
+| **Allowed devices** | Optional: only matching `device_id` values start the workflow (others get HTTP 200, no run). |
+| **Event type** | Uplink message, Normalized uplink, Join accept, Downlink ack/nack/sent/failed/queued, Location solved, Service data, or All. |
+| **Output format** | For uplinks: Sensor Data, Sensor Values Only, Full Event. For other events: Event Summary or Full Event. |
+| **When JSON does not match event type** | **Do not start workflow** (recommended) — avoids duplicate runs when TTS sends uplink + normalized payload to the same URL. |
+
+Credentials are optional on the trigger (only needed for the application/device filter dropdowns).
+
+> **Legacy nodes:** `TTN: Uplink Trigger (legacy)` and `TTN: Downlink (legacy)` remain installed for backward compatibility but are hidden from the picker. New workflows should use **TTN** and **TTN Trigger**.
+
+## Usage examples
+
+### Real-time sensor data (webhook)
+
+```
+TTN Trigger (Webhook · Receive Events)
+  → Event type: Uplink message
+  → Output format: Sensor Data
+  → [your logic: Slack, database, etc.]
+```
+
+Output shape (`Sensor Data`):
+
+```json
+{
+  "device_id": "my-sensor",
+  "application_id": "my-app",
+  "received_at": "2026-06-07T12:00:00.000Z",
+  "f_port": 1,
+  "data": { "temperature": 22.5, "humidity": 60 }
+}
+```
+
+### Send a downlink command
+
+```
+TTN → Devices → Send Downlink
+  → Application: my-app
+  → Device: my-sensor
+  → FPort: 10
+  → Payload type: Hex
+  → Payload: 0102FF
+```
+
+See [Scheduling downlinks](https://www.thethingsindustries.com/docs/reference/api/application_server/#downlinkmessage) in the TTS docs.
+
+### Read recent uplinks from Storage
+
+```
+TTN → Data → Get Last Uplink
+  → Storage scope: One Device
+  → Last window: Last 12 Hours
+  → Uplink output shape: Decoded Payload + Meta
+```
+
+Requires [Storage integration](https://www.thethingsindustries.com/docs/integrations/storage/) enabled on the application.
+
+### Monitor device connectivity
+
+```
+TTN → Data → Get Device Status
+  → Status mode: Summary
+  → Offline threshold: 24 hours
+```
+
+### Check gateway health
+
+```
+TTN → Gateways → Get Gateway Status
+  → Gateway IDs: [your-gateway]
+  → Status mode: Detailed
+```
+
+## Compatibility
+
+| Requirement | Version |
+|-------------|---------|
+| n8n | Community nodes supported (tested with recent self-hosted releases) |
+| Node.js | ≥ 22 (development / CI) |
+| The Things Stack | v3 API (`/api/v3/…`) — public TTN cloud, Cloud Hosted, and self-hosted |
+
+No runtime npm dependencies — only `n8n-workflow` as a peer dependency.
+
+## Development
+
+```bash
+npm install
+npm run dev      # Start n8n with hot reload
+npm run lint     # ESLint (n8n node rules)
+npm run build    # Compile to dist/
+npm run deploy   # Build + copy to custom n8n folder
+npm run release  # Version bump, changelog, tag, publish
+```
+
+Requires Node.js 22+. See [n8n node development](https://docs.n8n.io/integrations/creating-nodes/).
+
+## Resources
+
+### n8n
+
+- [Community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)
+- [Install community nodes](https://docs.n8n.io/integrations/community-nodes/installation/)
+- [Building custom nodes](https://docs.n8n.io/integrations/creating-nodes/)
+
+### The Things Stack / TTN
+
+- [The Things Stack documentation](https://www.thethingsindustries.com/docs/)
+- [TTS Console (public cloud)](https://console.cloud.thethings.network/)
+- [API authentication](https://www.thethingsindustries.com/docs/reference/api/authentication/)
+- [Webhooks integration](https://www.thethingsindustries.com/docs/integrations/webhooks/)
+- [Storage integration](https://www.thethingsindustries.com/docs/integrations/storage/)
+- [Application Server API (devices, downlinks)](https://www.thethingsindustries.com/docs/reference/api/application_server/)
+- [Gateway Server API](https://www.thethingsindustries.com/docs/reference/api/gateway_server/)
+- [LoRaWAN concepts](https://www.thethingsindustries.com/docs/concepts/lorawan/)
+
+### This project
+
+- [GitHub repository](https://github.com/etoilary974-ship-it/TTN_Node)
+- [Changelog](CHANGELOG.md)
+- [Report an issue](https://github.com/etoilary974-ship-it/TTN_Node/issues)
+
+## Version history
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.
+
+| Version | Highlights |
+|---------|------------|
+| **0.2.0** | Unified operation labels, downlink preview, webhook picker fix, `@n8n/node-cli`, ESLint, Node 22 |
+| **0.1.0** | Initial release: TTN node, webhook trigger, credentials, CI/CD |
+
+## License
+
+[MIT](LICENSE.md) — Copyright Loewen Creville

package/dist/credentials/ttnApi.credentials.d.ts

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

package/dist/credentials/ttnApi.credentials.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ttnApi = exports.TtnApi = void 0;
+class TtnApi {
+    constructor() {
+        this.name = 'ttnApi';
+        this.displayName = 'The Things Stack API';
+        this.documentationUrl = 'https://www.thethingsindustries.com/docs/reference/api/authentication/';
+        this.properties = [
+            {
+                displayName: 'Server URL',
+                name: 'serverUrl',
+                type: 'string',
+                placeholder: 'https://eu1.cloud.thethings.network',
+                description: 'Base URL of your The Things Stack deployment (public cloud, Cloud Hosted, or self-hosted), without an /api path.',
+                required: true,
+                default: '',
+            },
+            {
+                displayName: 'API key (Application Server)',
+                name: 'apiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                description: '**Application Server** key (NNSXS… format), `Authorization: Bearer` header: applications, devices, status, downlinks, and **Storage** (`GET …/packages/storage/uplink_message`) when your key has the right rights.',
+                required: true,
+                default: '',
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Authorization: '=Bearer {{ $credentials.apiKey }}',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.serverUrl}}',
+                method: 'GET',
+                url: '/api/v3/applications',
+                headers: {
+                    Accept: 'application/json',
+                },
+            },
+        };
+    }
+}
+exports.TtnApi = TtnApi;
+exports.ttnApi = TtnApi;
+//# sourceMappingURL=ttnApi.credentials.js.map

package/dist/credentials/ttnApi.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttnApi.credentials.js","sourceRoot":"","sources":["../../credentials/ttnApi.credentials.ts"],"names":[],"mappings":";;;AAOA,MAAa,MAAM;IAAnB;QACC,SAAI,GAAG,QAAQ,CAAC;QAChB,gBAAW,GAAG,sBAAsB,CAAC;QACrC,qBAAgB,GACf,wEAAwE,CAAC;QAC1E,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,qCAAqC;gBAClD,WAAW,EACV,kHAAkH;gBACnH,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,EAAE;aACX;YACD;gBACC,WAAW,EAAE,8BAA8B;gBAC3C,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,WAAW,EACV,qNAAqN;gBACtN,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,EAAE;aACX;SACD,CAAC;QACF,iBAAY,GAAyB;YACpC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACX,OAAO,EAAE;oBACR,aAAa,EAAE,mCAAmC;iBAClD;aACD;SACD,CAAC;QACF,SAAI,GAA2B;YAC9B,OAAO,EAAE;gBACR,OAAO,EAAE,6BAA6B;gBACtC,MAAM,EAAE,KAAK;gBACb,GAAG,EAAE,sBAAsB;gBAC3B,OAAO,EAAE;oBACR,MAAM,EAAE,kBAAkB;iBAC1B;aACD;SACD,CAAC;IACH,CAAC;CAAA;AA7CD,wBA6CC;AAGkB,wBAAM"}

package/dist/icons/ttnNodeIcon.dark.svg

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- TTN cloud mark, colors for dark UI -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+	<g transform="translate(256,256) scale(0.785) translate(-638,-299.5)">
+		<path fill="#5CB8FF" d="M891,381.9c1.4,17.2-4,33.4-15,45.8c-11.8,13.2-29.4,20.4-49.2,20.4H398.2l0,0c-0.2,0-0.4,0-0.6,0h-0.2H397l0,0c-17.4-0.2-33.8-7-46-19.2c-13-12.8-20-30-20.2-48.2l0,0c0-33.8,23-61.2,54.4-66.4c4.2-28.2,28.8-51.2,59.2-56c1.8-11.2,7.2-22,15.8-30.8c12.4-12.8,29.2-20,46.4-20c22.2,0,41.6,12,52,30c12.2-43.6,52.2-75.6,99.6-75.6c51.8,0,95,38.4,102.2,88.4c26-19.4,60.6-17.6,86.6,6.8l-2.8-2.4c20.8,16.8,28,39.6,27,58.8c-0.6,11.4-4.4,21.4-11.2,29.6c6.6,2.2,12,6,17.2,11.2c7.2,7.2,12.2,16.2,13.6,26.2l0,0C890.8,380.9,890.8,381.3,891,381.9C891,381.3,891,381.5,891,381.9z M923.2,220.5c-15.2-20.6-37.8-35.8-62.6-42.2c-5.6-1.2-11.4,2.6-12.6,8c-2.2,5.6,1.4,12.8,7.4,14c25,6.6,46.6,24.2,58,47.4c9.4,19,11.8,41.4,6.6,62c-1.4,5.8,2.8,12,8.8,12.8c5.4,1.6,11.4-1.6,13.2-6.8C950.2,283.5,943.2,247.3,923.2,220.5z M851.8,217.3c-8.6-1.6-15.2,9-11.4,16.4c1.4,3.2,4.6,5.4,8,6.2c13,3.4,24.4,12.4,30.4,24.4c5.4,10.6,6.6,23,3.6,34.4c-1.6,5.8,2.6,12.2,8.6,13.2c5.4,1.6,11.8-1.6,13.4-7.2c5.6-20.4,1.4-43.2-11-60.2C883.4,230.9,868.4,220.5,851.8,217.3z"/>
+	</g>
+</svg>

package/dist/icons/ttnNodeIcon.svg

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- TTN cloud mark only, square canvas for n8n node icon -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+	<g transform="translate(256,256) scale(0.785) translate(-638,-299.5)">
+		<path fill="#0D83D0" d="M891,381.9c1.4,17.2-4,33.4-15,45.8c-11.8,13.2-29.4,20.4-49.2,20.4H398.2l0,0c-0.2,0-0.4,0-0.6,0h-0.2H397l0,0c-17.4-0.2-33.8-7-46-19.2c-13-12.8-20-30-20.2-48.2l0,0c0-33.8,23-61.2,54.4-66.4c4.2-28.2,28.8-51.2,59.2-56c1.8-11.2,7.2-22,15.8-30.8c12.4-12.8,29.2-20,46.4-20c22.2,0,41.6,12,52,30c12.2-43.6,52.2-75.6,99.6-75.6c51.8,0,95,38.4,102.2,88.4c26-19.4,60.6-17.6,86.6,6.8l-2.8-2.4c20.8,16.8,28,39.6,27,58.8c-0.6,11.4-4.4,21.4-11.2,29.6c6.6,2.2,12,6,17.2,11.2c7.2,7.2,12.2,16.2,13.6,26.2l0,0C890.8,380.9,890.8,381.3,891,381.9C891,381.3,891,381.5,891,381.9z M923.2,220.5c-15.2-20.6-37.8-35.8-62.6-42.2c-5.6-1.2-11.4,2.6-12.6,8c-2.2,5.6,1.4,12.8,7.4,14c25,6.6,46.6,24.2,58,47.4c9.4,19,11.8,41.4,6.6,62c-1.4,5.8,2.8,12,8.8,12.8c5.4,1.6,11.4-1.6,13.2-6.8C950.2,283.5,943.2,247.3,923.2,220.5z M851.8,217.3c-8.6-1.6-15.2,9-11.4,16.4c1.4,3.2,4.6,5.4,8,6.2c13,3.4,24.4,12.4,30.4,24.4c5.4,10.6,6.6,23,3.6,34.4c-1.6,5.8,2.6,12.2,8.6,13.2c5.4,1.6,11.8-1.6,13.4-7.2c5.6-20.4,1.4-43.2-11-60.2C883.4,230.9,868.4,220.5,851.8,217.3z"/>
+	</g>
+</svg>

package/dist/nodes/ttn_node/ttn.node.d.ts

@@ -0,0 +1,14 @@
+import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+import { ttnGetApplications, ttnGetDevices, ttnGetGateways } from './ttnShared.js';
+export declare class Ttn implements INodeType {
+    description: INodeTypeDescription;
+    methods: {
+        loadOptions: {
+            getApplications: typeof ttnGetApplications;
+            getDevices: typeof ttnGetDevices;
+            getGateways: typeof ttnGetGateways;
+        };
+    };
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}
+export { Ttn as ttn };