@attocash/n8n-nodes-atto 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,180 +1,196 @@
1
- # @attocash/n8n-nodes-atto
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/attocash/integrations-n8n/main/docs/images/atto-n8n-banner.png" alt="Atto nodes for n8n: payments, accounts, receivables, and live network events" width="100%">
3
+ </p>
2
4
 
3
- [![npm version](https://img.shields.io/npm/v/@attocash/n8n-nodes-atto.svg)](https://www.npmjs.com/package/@attocash/n8n-nodes-atto)
4
- [![n8n Atto Node CI](https://github.com/attocash/integrations/actions/workflows/n8n-node-package.yml/badge.svg)](https://github.com/attocash/integrations/actions/workflows/n8n-node-package.yml)
5
- [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/attocash/integrations/blob/main/LICENSE)
5
+ <p align="center">
6
+ <a href="https://www.npmjs.com/package/@attocash/n8n-nodes-atto"><img src="https://img.shields.io/npm/v/@attocash/n8n-nodes-atto.svg" alt="npm version"></a>
7
+ <a href="https://www.npmjs.com/package/@attocash/n8n-nodes-atto"><img src="https://img.shields.io/npm/dw/@attocash/n8n-nodes-atto.svg" alt="npm weekly downloads"></a>
8
+ <a href="https://github.com/attocash/integrations-n8n/actions/workflows/n8n-node-package.yml"><img src="https://github.com/attocash/integrations-n8n/actions/workflows/n8n-node-package.yml/badge.svg" alt="n8n Atto Node CI"></a>
9
+ <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
10
+ </p>
6
11
 
7
- Use Atto from n8n workflows.
12
+ # Atto for n8n
8
13
 
9
- This package adds action and trigger nodes for Atto addresses, accounts, receivables, transactions, and representatives. Atto Commons provides the protocol model, address derivation, block construction, hashing, and signing. Network calls use n8n's HTTP helpers, and integration tests use the Commons mocks.
14
+ Use Atto in n8n workflows. The package can derive wallet addresses, read network data, sign payments, receive funds, change representatives, and start workflows from live Atto events.
10
15
 
11
- ## Install
16
+ It includes two nodes:
12
17
 
13
- In self-hosted n8n, open **Settings** > **Community Nodes** and install:
18
+ - **Atto** runs wallet, account, receivable, transaction, account-entry, and representative operations.
19
+ - **Atto Trigger** listens to receivable, account, transaction, and account-entry streams.
14
20
 
15
- ```text
16
- @attocash/n8n-nodes-atto
17
- ```
18
-
19
- Restart n8n if the nodes do not appear right away.
21
+ ## Contents
20
22
 
21
- ## What You Can Build
23
+ - [Installation](#installation)
24
+ - [Quick start](#quick-start)
25
+ - [Credentials](#credentials)
26
+ - [Nodes](#nodes)
27
+ - [Example workflows](#example-workflows)
28
+ - [Security](#security)
29
+ - [Compatibility](#compatibility)
30
+ - [Development](#development)
31
+ - [How Commons is used](#how-commons-is-used)
32
+ - [Support](#support)
22
33
 
23
- The package includes two nodes:
34
+ ## Installation
24
35
 
25
- - **Atto**: derive addresses, read account state, list receivables, receive an incoming receivable, list transactions/account entries, send transactions, and change representatives.
26
- - **Atto Trigger**: start workflows from receivables, account updates, transactions, or account entries.
36
+ ### Self-hosted n8n
27
37
 
28
- Typical workflows:
38
+ 1. Open **Settings > Community Nodes**.
39
+ 2. Select **Install**.
40
+ 3. Enter `@attocash/n8n-nodes-atto`.
41
+ 4. Confirm the community-node warning and install the package.
29
42
 
30
- - Receive a payment when a receivable appears.
31
- - Send a payment from the address derived from your credential.
32
- - Build a ping/pong flow that receives an incoming amount and sends the same amount back.
33
- - Watch an address for account entries or transaction updates.
43
+ Restart n8n if the nodes do not appear in the node picker. The [n8n community-node installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) covers other self-hosted installation methods.
34
44
 
35
- ## Credentials
45
+ ## Quick start
36
46
 
37
- Create an **Atto API** credential in n8n.
47
+ 1. Create an **Atto API** credential.
48
+ 2. Set the Node Base URL for the Atto HTTP API.
49
+ 3. Add an **Atto** or **Atto Trigger** node to a workflow.
50
+ 4. Choose a resource and operation, then run the node.
38
51
 
39
- Required for node access:
52
+ Read operations and triggers use the Node Base URL. Sending, receiving, and changing representatives also require the Worker Base URL and wallet material.
40
53
 
41
- - **Node Base URL**: Atto node HTTP API, for example `http://localhost:8080`.
42
- - **Worker Base URL**: Atto work server HTTP API, for example `http://localhost:8085`.
54
+ <p align="center">
55
+ <img src="https://raw.githubusercontent.com/attocash/integrations-n8n/main/docs/images/receivable-workflow.png" alt="An n8n workflow that receives an Atto receivable" width="900">
56
+ </p>
43
57
 
44
- Optional API auth:
58
+ The example above starts when a receivable appears and passes it to **Receivable > Receive**. Import [`examples/incoming-to-receive.json`](./examples/incoming-to-receive.json) to use the same layout.
45
59
 
46
- - **API Key**
47
- - **API Key Header**
48
- - **API Key Prefix**
60
+ ## Credentials
49
61
 
50
- Required for signing actions:
62
+ Create an **Atto API** credential in n8n.
51
63
 
52
- - **Wallet Secret Type**: mnemonic phrase or private key.
53
- - **Wallet Secret**: encrypted by n8n and used only when signing.
54
- - **Key Index**: derivation index for mnemonic secrets.
64
+ | Field | When it is needed |
65
+ | --- | --- |
66
+ | Node Base URL | Network reads, transaction publication, and triggers |
67
+ | Worker Base URL | Send, receive, and representative-change operations |
68
+ | API Key, Header, and Prefix | Optional authentication for Node and Worker requests |
69
+ | Wallet Secret Type and Wallet Secret | Signing and filters that derive an address from credentials |
70
+ | Key Index | Mnemonic-derived addresses; defaults to `0` |
55
71
 
56
- The credential test only checks that **Node Base URL** responds to `GET /`. It does not send the wallet secret.
72
+ The wallet secret can be a 24-word Atto mnemonic or a compatible hex private key. n8n encrypts credential values at rest.
57
73
 
58
- For real funds, store wallet material in n8n credentials. Node-parameter secrets are useful for local derivation and tests, but n8n may keep node parameters in execution records depending on your instance settings.
74
+ The credential test sends `GET /` to the Node Base URL. It does not send the wallet secret or call the Worker Base URL.
59
75
 
60
76
  ## Nodes
61
77
 
62
78
  ### Atto
63
79
 
64
- Resources and operations:
80
+ | Resource | Operations | What it does |
81
+ | --- | --- | --- |
82
+ | Address | Derive | Derives an address and public key from a mnemonic or private key |
83
+ | Account | Get | Reads balance, representative, height, and frontier |
84
+ | Receivable | Get, Receive | Lists pending receivables or publishes a receive transaction |
85
+ | Transaction | Get, Send | Reads transaction streams or publishes a send transaction |
86
+ | Account Entry | Get | Fetches entries by hash or reads a bounded entry stream |
87
+ | Representative | Change | Publishes a representative-change transaction |
65
88
 
66
- - **Address > Derive**: derive an Atto address and public key from a mnemonic or hex private key.
67
- - **Account > Get**: read balance, representative, height, and frontier for an address.
68
- - **Receivable > Get**: collect receivables for the credential-derived address or manual addresses.
69
- - **Receivable > Receive**: receive the receivable from the incoming item.
70
- - **Transaction > Get**: fetch by hash or collect a bounded transaction stream.
71
- - **Transaction > Send**: send from the credential-derived address.
72
- - **Account Entry > Get**: fetch by hash or collect a bounded account-entry stream.
73
- - **Representative > Change**: change the representative for the credential-derived address.
89
+ Send and receive wait up to 60 seconds for publication by default. Stream reads stop when they reach **Max Items** or **Timeout**.
74
90
 
75
- Signing actions derive the source address from the wallet secret and key index. You do not need to pass a manual source address. Send and receive use a 60 second publish timeout by default.
91
+ <p align="center">
92
+ <img src="https://raw.githubusercontent.com/attocash/integrations-n8n/main/docs/images/atto-node-operations.png" alt="The Atto node resource and operation controls in n8n" width="900">
93
+ </p>
76
94
 
77
95
  ### Atto Trigger
78
96
 
79
- Trigger events:
97
+ | Event | Filters |
98
+ | --- | --- |
99
+ | Receivable | Credential-derived address, manual addresses, and minimum amount |
100
+ | Account Update | Credential-derived address, manual addresses, or all accounts |
101
+ | Transaction | Hash, credential-derived address, manual addresses, or all transactions |
102
+ | Account Entry | Hash, credential-derived address, manual addresses, or all entries |
103
+
104
+ Triggers use Atto's NDJSON endpoints. When a stream closes or fails, the node reconnects with exponential backoff from 1 to 30 seconds. Receiving an event resets the delay.
105
+
106
+ ## Example workflows
107
+
108
+ The [`examples`](./examples) directory contains importable workflows:
109
+
110
+ - [`send-transaction.json`](./examples/send-transaction.json) sends Atto from a manual trigger.
111
+ - [`incoming-to-receive.json`](./examples/incoming-to-receive.json) receives an incoming receivable.
112
+ - [`ping-pong-receivable.json`](./examples/ping-pong-receivable.json) receives a payment and sends the same raw amount back.
113
+ - [`receivable-trigger.json`](./examples/receivable-trigger.json) starts a workflow when a receivable appears.
114
+
115
+ Attach your **Atto API** credential after importing a workflow. Replace placeholder addresses before running a transaction operation.
80
116
 
81
- - **Receivable**: fires when a receivable appears for the credential-derived address or manual addresses.
82
- - **Account Update**: fires when account state changes.
83
- - **Transaction**: watches by hash, address stream, or all supported transactions.
84
- - **Account Entry**: watches by hash, address stream, or all supported account entries.
117
+ ## Security
85
118
 
86
- Triggers stay connected to the selected Atto NDJSON endpoint. If a stream closes, the node reconnects with exponential backoff from 1 to 30 seconds; a received event resets the delay.
119
+ Store wallet material in n8n credentials when working with real funds. The node also accepts wallet material as password-type node parameters for local derivation and controlled testing, but your n8n instance may retain node parameters in workflow or execution records.
87
120
 
88
- ## Example Workflows
121
+ The node does not log or return wallet secrets, seeds, private keys, or API keys. Review n8n execution-data retention and access controls before using signing operations in production.
89
122
 
90
- Importable examples live in [`examples`](./examples):
123
+ ## Compatibility
91
124
 
92
- - [`send-transaction.json`](./examples/send-transaction.json): manual trigger to send Atto.
93
- - [`incoming-to-receive.json`](./examples/incoming-to-receive.json): receivable trigger piped into **Receivable > Receive**.
94
- - [`ping-pong-receivable.json`](./examples/ping-pong-receivable.json): receive an incoming amount and send the same raw amount back to the sender.
95
- - [`receivable-trigger.json`](./examples/receivable-trigger.json): trigger-only receivable watcher.
125
+ | Component | Requirement |
126
+ | --- | --- |
127
+ | n8n node metadata | Nodes API v1 |
128
+ | Node.js runtime and development | 22.22.0 or newer |
129
+ | Package manager | npm |
130
+ | Container integration tests | Docker or a local Podman socket |
96
131
 
97
- After importing an example, attach your **Atto API** credential and replace any placeholder addresses before running transaction operations.
132
+ The Node.js requirement is checked when npm installs the package. The official current n8n container image uses a compatible runtime; custom installations must provide Node.js 22.22.0 or newer.
98
133
 
99
- ## Local Development
134
+ ## Development
100
135
 
101
136
  Install dependencies and run the checks:
102
137
 
103
138
  ```bash
104
- npm install
139
+ npm ci --ignore-scripts
105
140
  npm run build
106
- npm test
107
141
  npm run lint
142
+ npm test
108
143
  ```
109
144
 
110
- `npm test` builds the package and runs unit, smoke, and integration tests. The integration test uses `AttoNodeMockAsyncBuilder` and `AttoWorkerMockAsyncBuilder` from `@attocash/commons-test`. It uses Docker when available and falls back to a local Podman socket.
111
-
112
- To require the mock-container integration path:
145
+ `npm test` runs the integration, smoke, trigger, and unit test files in sequence. The integration file records a skip when neither Docker nor a local Podman socket is available. Require the container path with:
113
146
 
114
147
  ```bash
115
148
  ATTO_TEST_INTEGRATION=1 npm run test:integration
116
149
  ```
117
150
 
118
- ### Run n8n With Podman
119
-
120
- From this package directory:
151
+ Start the n8n development environment with:
121
152
 
122
153
  ```bash
123
- npm run build
124
- mkdir -p /tmp/n8n-atto-local/.n8n/nodes/node_modules
125
- podman run --rm -it \
126
- --user 0 \
127
- -p 5678:5678 \
128
- -e N8N_USER_FOLDER=/home/node \
129
- -e N8N_COMMUNITY_PACKAGES_ENABLED=true \
130
- -e N8N_SECURE_COOKIE=false \
131
- -v /tmp/n8n-atto-local:/home/node:Z \
132
- -v "$PWD:/home/node/.n8n/nodes/node_modules/@attocash/n8n-nodes-atto:ro,Z" \
133
- docker.io/n8nio/n8n:latest
154
+ npm run dev
134
155
  ```
135
156
 
136
- Open `http://localhost:5678`, create a workflow, and add **Atto** or **Atto Trigger**.
157
+ ### Install from a checkout
137
158
 
138
- ### Install From A Checkout Inside n8n
139
-
140
- If you have shell access inside the n8n container:
159
+ If you have shell access inside an n8n container:
141
160
 
142
161
  ```bash
143
162
  cd /tmp
144
- git clone https://github.com/attocash/integrations.git
145
- cd integrations/n8n-node
163
+ git clone https://github.com/attocash/integrations-n8n.git
164
+ cd integrations-n8n
146
165
  npm run install:n8n
147
166
  ```
148
167
 
149
- The installer builds, validates, packs, and installs the generated `.tgz` into `${N8N_USER_FOLDER:-$HOME/.n8n}/nodes`.
168
+ The installer builds, validates, packs, and installs the generated tarball. It uses these locations in order:
150
169
 
151
- Optional overrides:
170
+ 1. `N8N_NODES_DIR`, when set.
171
+ 2. `${N8N_USER_FOLDER}/.n8n/nodes`, when `N8N_USER_FOLDER` is set.
172
+ 3. `${HOME}/.n8n/nodes`.
152
173
 
153
- ```bash
154
- N8N_NODES_DIR=/path/to/nodes npm run install:n8n
155
- RUN_TESTS=1 npm run install:n8n
156
- ```
174
+ Set `RUN_TESTS=1` to run the full test suite before installation. Restart n8n when the installer finishes.
157
175
 
158
- Restart n8n after the script finishes.
176
+ See [CONTRIBUTING.md](./CONTRIBUTING.md) for the release process and maintainer setup.
159
177
 
160
- ## Maintainers
178
+ ## How Commons is used
161
179
 
162
- This package is versioned independently from other integrations in this repository. Use normal semver in `n8n-node/package.json`; release tags use the package-specific format `n8n-node-vX.Y.Z`.
180
+ Atto Commons supplies the protocol models, address derivation, block construction, hashing, and signing.
163
181
 
164
- ```bash
165
- cd n8n-node
166
- npm version patch --no-git-tag-version
167
- git add package.json package-lock.json
168
- git commit -m "Release n8n Atto node vX.Y.Z"
169
- git push origin main
170
- ```
182
+ | Package | Role in this repository | Published package |
183
+ | --- | --- | --- |
184
+ | `@attocash/commons-core` | Runtime protocol implementation | Bundled into the built protocol adapter |
185
+ | `@attocash/commons-test` | Node and Worker mocks for integration tests | Not used or installed at runtime |
186
+ | `n8n-workflow` | n8n types and runtime APIs | Provided by n8n as a peer dependency |
171
187
 
172
- On pushes to `main`, GitHub Actions tests and packs the attempted version, uploads the `.tgz` artifact, then waits for approval in the `release` environment. After approval, it creates the tag, publishes `@attocash/n8n-nodes-atto` to npm, and creates the GitHub release.
188
+ Network requests go through n8n's HTTP helpers. The npm package has no production dependencies; Commons Core is bundled once so n8n does not need a separate Commons installation.
173
189
 
174
- Configure npm Trusted Publishing for `.github/workflows/n8n-node-package.yml`.
190
+ ## Support
175
191
 
176
- ## Notes
192
+ - Read the operation notes in [USAGE.md](./USAGE.md).
193
+ - Open a bug or feature request in [GitHub Issues](https://github.com/attocash/integrations-n8n/issues).
194
+ - See the [n8n community-node documentation](https://docs.n8n.io/integrations/community-nodes/).
177
195
 
178
- - Runtime protocol behavior comes from `@attocash/commons-core`; `@attocash/commons-test` is used only by integration tests.
179
- - Commons Core is bundled once into the built protocol adapter, so the published n8n package has no runtime dependencies beyond n8n.
180
- - Hex private keys must use the format accepted by `AttoPrivateKey.Companion.parse`.
196
+ This package is available under the [MIT License](./LICENSE).
@@ -8,7 +8,7 @@ class AttoApi {
8
8
  light: 'file:../nodes/Atto/atto.svg',
9
9
  dark: 'file:../nodes/Atto/atto.dark.svg',
10
10
  };
11
- documentationUrl = 'https://github.com/attocash/integrations/blob/main/n8n-node/USAGE.md';
11
+ documentationUrl = 'https://github.com/attocash/integrations-n8n/blob/main/USAGE.md';
12
12
  properties = [
13
13
  {
14
14
  displayName: 'Node Base URL',
@@ -6,12 +6,12 @@
6
6
  "resources": {
7
7
  "credentialDocumentation": [
8
8
  {
9
- "url": "https://github.com/attocash/integrations/tree/main/n8n-node#credentials"
9
+ "url": "https://github.com/attocash/integrations-n8n#credentials"
10
10
  }
11
11
  ],
12
12
  "primaryDocumentation": [
13
13
  {
14
- "url": "https://github.com/attocash/integrations/blob/main/n8n-node/USAGE.md"
14
+ "url": "https://github.com/attocash/integrations-n8n/blob/main/USAGE.md"
15
15
  }
16
16
  ]
17
17
  }
@@ -6,12 +6,12 @@
6
6
  "resources": {
7
7
  "credentialDocumentation": [
8
8
  {
9
- "url": "https://github.com/attocash/integrations/tree/main/n8n-node#credentials"
9
+ "url": "https://github.com/attocash/integrations-n8n#credentials"
10
10
  }
11
11
  ],
12
12
  "primaryDocumentation": [
13
13
  {
14
- "url": "https://github.com/attocash/integrations/blob/main/n8n-node/USAGE.md"
14
+ "url": "https://github.com/attocash/integrations-n8n/blob/main/USAGE.md"
15
15
  }
16
16
  ]
17
17
  }
package/dist/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@attocash/n8n-nodes-atto",
3
- "version": "0.4.0",
3
+ "version": "0.4.2",
4
4
  "description": "Atto cryptocurrency wallet, transaction, account, and trigger nodes for n8n, powered by Atto Commons",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -24,14 +24,13 @@
24
24
  "name": "Atto",
25
25
  "email": "contact@atto.cash"
26
26
  },
27
- "homepage": "https://github.com/attocash/integrations/tree/main/n8n-node#readme",
27
+ "homepage": "https://github.com/attocash/integrations-n8n#readme",
28
28
  "repository": {
29
29
  "type": "git",
30
- "url": "git+https://github.com/attocash/integrations.git",
31
- "directory": "n8n-node"
30
+ "url": "git+https://github.com/attocash/integrations-n8n.git"
32
31
  },
33
32
  "bugs": {
34
- "url": "https://github.com/attocash/integrations/issues"
33
+ "url": "https://github.com/attocash/integrations-n8n/issues"
35
34
  },
36
35
  "publishConfig": {
37
36
  "access": "public",
@@ -51,18 +50,18 @@
51
50
  "install:n8n": "sh scripts/install-into-n8n.sh",
52
51
  "lint": "n8n-node lint",
53
52
  "lint:fix": "n8n-node lint --fix",
54
- "test": "npm run build && node --test test/*.test.mjs",
53
+ "test": "npm run build && node scripts/run-tests.mjs",
55
54
  "test:integration": "npm run build && ATTO_TEST_INTEGRATION=1 node --test test/integration.test.mjs",
56
55
  "validate:local": "node scripts/validate-local.mjs",
57
56
  "validate:release-tag": "node scripts/validate-release-tag.mjs"
58
57
  },
59
58
  "engines": {
60
- "node": ">=22.16"
59
+ "node": ">=22.22.0"
61
60
  },
62
61
  "devDependencies": {
63
62
  "@attocash/commons-core": "7.0.2",
64
63
  "@attocash/commons-test": "7.0.2",
65
- "@n8n/node-cli": "0.32.1",
64
+ "@n8n/node-cli": "0.41.2",
66
65
  "@types/node": "^22.15.21",
67
66
  "esbuild": "0.27.1",
68
67
  "eslint": "9.29.0",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@attocash/n8n-nodes-atto",
3
- "version": "0.4.0",
3
+ "version": "0.4.2",
4
4
  "description": "Atto cryptocurrency wallet, transaction, account, and trigger nodes for n8n, powered by Atto Commons",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -24,14 +24,13 @@
24
24
  "name": "Atto",
25
25
  "email": "contact@atto.cash"
26
26
  },
27
- "homepage": "https://github.com/attocash/integrations/tree/main/n8n-node#readme",
27
+ "homepage": "https://github.com/attocash/integrations-n8n#readme",
28
28
  "repository": {
29
29
  "type": "git",
30
- "url": "git+https://github.com/attocash/integrations.git",
31
- "directory": "n8n-node"
30
+ "url": "git+https://github.com/attocash/integrations-n8n.git"
32
31
  },
33
32
  "bugs": {
34
- "url": "https://github.com/attocash/integrations/issues"
33
+ "url": "https://github.com/attocash/integrations-n8n/issues"
35
34
  },
36
35
  "publishConfig": {
37
36
  "access": "public",
@@ -51,18 +50,18 @@
51
50
  "install:n8n": "sh scripts/install-into-n8n.sh",
52
51
  "lint": "n8n-node lint",
53
52
  "lint:fix": "n8n-node lint --fix",
54
- "test": "npm run build && node --test test/*.test.mjs",
53
+ "test": "npm run build && node scripts/run-tests.mjs",
55
54
  "test:integration": "npm run build && ATTO_TEST_INTEGRATION=1 node --test test/integration.test.mjs",
56
55
  "validate:local": "node scripts/validate-local.mjs",
57
56
  "validate:release-tag": "node scripts/validate-release-tag.mjs"
58
57
  },
59
58
  "engines": {
60
- "node": ">=22.16"
59
+ "node": ">=22.22.0"
61
60
  },
62
61
  "devDependencies": {
63
62
  "@attocash/commons-core": "7.0.2",
64
63
  "@attocash/commons-test": "7.0.2",
65
- "@n8n/node-cli": "0.32.1",
64
+ "@n8n/node-cli": "0.41.2",
66
65
  "@types/node": "^22.15.21",
67
66
  "esbuild": "0.27.1",
68
67
  "eslint": "9.29.0",