@attocash/n8n-nodes-atto 0.4.1 → 0.4.3

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.
Files changed (4) hide show
  1. package/README.md +123 -108
  2. package/dist/nodes/AttoTrigger/AttoTrigger.node.js +0 -1
  3. package/dist/package.json +2 -2
  4. package/package.json +2 -2
package/README.md CHANGED
@@ -1,145 +1,163 @@
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-n8n/actions/workflows/n8n-node-package.yml/badge.svg)](https://github.com/attocash/integrations-n8n/actions/workflows/n8n-node-package.yml)
5
- [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/attocash/integrations-n8n/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="Pipeline status"></a>
9
+ <a href="https://atto.cash"><img src="https://img.shields.io/badge/website-atto.cash-FAB005.svg" alt="Atto website"></a>
10
+ <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
11
+ </p>
6
12
 
7
- Use Atto from n8n workflows.
13
+ # Atto for n8n
8
14
 
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.
15
+ 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
16
 
11
- ## Install
17
+ It includes two nodes:
12
18
 
13
- In self-hosted n8n, open **Settings** > **Community Nodes** and install:
19
+ - **Atto** runs wallet, account, receivable, transaction, account-entry, and representative operations.
20
+ - **Atto Trigger** listens to receivable, account, transaction, and account-entry streams.
14
21
 
15
- ```text
16
- @attocash/n8n-nodes-atto
17
- ```
18
-
19
- Restart n8n if the nodes do not appear right away.
22
+ ## Contents
20
23
 
21
- ## What You Can Build
24
+ - [Installation](#installation)
25
+ - [Quick start](#quick-start)
26
+ - [Credentials](#credentials)
27
+ - [Nodes](#nodes)
28
+ - [Example workflows](#example-workflows)
29
+ - [Security](#security)
30
+ - [Compatibility](#compatibility)
31
+ - [Development](#development)
32
+ - [How Commons is used](#how-commons-is-used)
33
+ - [Support](#support)
22
34
 
23
- The package includes two nodes:
35
+ ## Installation
24
36
 
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.
37
+ ### Self-hosted n8n
27
38
 
28
- Typical workflows:
39
+ 1. Open **Settings > Community Nodes**.
40
+ 2. Select **Install**.
41
+ 3. Enter `@attocash/n8n-nodes-atto`.
42
+ 4. Confirm the community-node warning and install the package.
29
43
 
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.
44
+ 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
45
 
35
- ## Credentials
46
+ ## Quick start
36
47
 
37
- Create an **Atto API** credential in n8n.
48
+ 1. Create an **Atto API** credential.
49
+ 2. Set the Node Base URL for the Atto HTTP API.
50
+ 3. Add an **Atto** or **Atto Trigger** node to a workflow.
51
+ 4. Choose a resource and operation, then run the node.
38
52
 
39
- Required for node access:
53
+ Read operations and triggers use the Node Base URL. Sending, receiving, and changing representatives also require the Worker Base URL and wallet material.
40
54
 
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`.
55
+ <p align="center">
56
+ <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">
57
+ </p>
43
58
 
44
- Optional API auth:
59
+ 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
60
 
46
- - **API Key**
47
- - **API Key Header**
48
- - **API Key Prefix**
61
+ ## Credentials
49
62
 
50
- Required for signing actions:
63
+ Create an **Atto API** credential in n8n.
51
64
 
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.
65
+ | Field | When it is needed |
66
+ | --- | --- |
67
+ | Node Base URL | Network reads, transaction publication, and triggers |
68
+ | Worker Base URL | Send, receive, and representative-change operations |
69
+ | API Key, Header, and Prefix | Optional authentication for Node and Worker requests |
70
+ | Wallet Secret Type and Wallet Secret | Signing and filters that derive an address from credentials |
71
+ | Key Index | Mnemonic-derived addresses; defaults to `0` |
55
72
 
56
- The credential test only checks that **Node Base URL** responds to `GET /`. It does not send the wallet secret.
73
+ The wallet secret can be a 24-word Atto mnemonic or a compatible hex private key. n8n encrypts credential values at rest.
57
74
 
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.
75
+ The credential test sends `GET /` to the Node Base URL. It does not send the wallet secret or call the Worker Base URL.
59
76
 
60
77
  ## Nodes
61
78
 
62
79
  ### Atto
63
80
 
64
- Resources and operations:
81
+ | Resource | Operations | What it does |
82
+ | --- | --- | --- |
83
+ | Address | Derive | Derives an address and public key from a mnemonic or private key |
84
+ | Account | Get | Reads balance, representative, height, and frontier |
85
+ | Receivable | Get, Receive | Lists pending receivables or publishes a receive transaction |
86
+ | Transaction | Get, Send | Reads transaction streams or publishes a send transaction |
87
+ | Account Entry | Get | Fetches entries by hash or reads a bounded entry stream |
88
+ | Representative | Change | Publishes a representative-change transaction |
65
89
 
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.
90
+ Send and receive wait up to 60 seconds for publication by default. Stream reads stop when they reach **Max Items** or **Timeout**.
74
91
 
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.
92
+ <p align="center">
93
+ <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">
94
+ </p>
76
95
 
77
96
  ### Atto Trigger
78
97
 
79
- Trigger events:
98
+ | Event | Filters |
99
+ | --- | --- |
100
+ | Receivable | Credential-derived address, manual addresses, and minimum amount |
101
+ | Account Update | Credential-derived address, manual addresses, or all accounts |
102
+ | Transaction | Hash, credential-derived address, manual addresses, or all transactions |
103
+ | Account Entry | Hash, credential-derived address, manual addresses, or all entries |
80
104
 
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.
105
+ 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.
85
106
 
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.
107
+ ## Example workflows
87
108
 
88
- ## Example Workflows
109
+ The [`examples`](./examples) directory contains importable workflows:
89
110
 
90
- Importable examples live in [`examples`](./examples):
111
+ - [`send-transaction.json`](./examples/send-transaction.json) sends Atto from a manual trigger.
112
+ - [`incoming-to-receive.json`](./examples/incoming-to-receive.json) receives an incoming receivable.
113
+ - [`ping-pong-receivable.json`](./examples/ping-pong-receivable.json) receives a payment and sends the same raw amount back.
114
+ - [`receivable-trigger.json`](./examples/receivable-trigger.json) starts a workflow when a receivable appears.
91
115
 
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.
116
+ Attach your **Atto API** credential after importing a workflow. Replace placeholder addresses before running a transaction operation.
96
117
 
97
- After importing an example, attach your **Atto API** credential and replace any placeholder addresses before running transaction operations.
118
+ ## Security
98
119
 
99
- ## Local Development
120
+ 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.
121
+
122
+ 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.
123
+
124
+ ## Compatibility
125
+
126
+ | Component | Requirement |
127
+ | --- | --- |
128
+ | n8n node metadata | Nodes API v1 |
129
+ | Node.js runtime and development | 22.22.0 or newer |
130
+ | Package manager | npm |
131
+ | Container integration tests | Docker or a local Podman socket |
132
+
133
+ 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.
134
+
135
+ ## Development
100
136
 
101
137
  Install dependencies and run the checks:
102
138
 
103
139
  ```bash
104
- npm install --ignore-scripts
140
+ npm ci --ignore-scripts
105
141
  npm run build
106
- npm test
107
142
  npm run lint
143
+ npm test
108
144
  ```
109
145
 
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
- Dependencies ship prebuilt, so lifecycle scripts are disabled to avoid transitive package-manager guard scripts.
113
-
114
- To require the mock-container integration path:
146
+ `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:
115
147
 
116
148
  ```bash
117
149
  ATTO_TEST_INTEGRATION=1 npm run test:integration
118
150
  ```
119
151
 
120
- ### Run n8n With Podman
121
-
122
- From this package directory:
152
+ Start the n8n development environment with:
123
153
 
124
154
  ```bash
125
- npm run build
126
- mkdir -p /tmp/n8n-atto-local/.n8n/nodes/node_modules
127
- podman run --rm -it \
128
- --user 0 \
129
- -p 5678:5678 \
130
- -e N8N_USER_FOLDER=/home/node \
131
- -e N8N_COMMUNITY_PACKAGES_ENABLED=true \
132
- -e N8N_SECURE_COOKIE=false \
133
- -v /tmp/n8n-atto-local:/home/node:Z \
134
- -v "$PWD:/home/node/.n8n/nodes/node_modules/@attocash/n8n-nodes-atto:ro,Z" \
135
- docker.io/n8nio/n8n:latest
155
+ npm run dev
136
156
  ```
137
157
 
138
- Open `http://localhost:5678`, create a workflow, and add **Atto** or **Atto Trigger**.
139
-
140
- ### Install From A Checkout Inside n8n
158
+ ### Install from a checkout
141
159
 
142
- If you have shell access inside the n8n container:
160
+ If you have shell access inside an n8n container:
143
161
 
144
162
  ```bash
145
163
  cd /tmp
@@ -148,35 +166,32 @@ cd integrations-n8n
148
166
  npm run install:n8n
149
167
  ```
150
168
 
151
- The installer builds, validates, packs, and installs the generated `.tgz` into `${N8N_USER_FOLDER:-$HOME/.n8n}/nodes`.
169
+ The installer builds, validates, packs, and installs the generated tarball. It uses these locations in order:
152
170
 
153
- Optional overrides:
171
+ 1. `N8N_NODES_DIR`, when set.
172
+ 2. `${N8N_USER_FOLDER}/.n8n/nodes`, when `N8N_USER_FOLDER` is set.
173
+ 3. `${HOME}/.n8n/nodes`.
154
174
 
155
- ```bash
156
- N8N_NODES_DIR=/path/to/nodes npm run install:n8n
157
- RUN_TESTS=1 npm run install:n8n
158
- ```
159
-
160
- Restart n8n after the script finishes.
175
+ Set `RUN_TESTS=1` to run the full test suite before installation. Restart n8n when the installer finishes.
161
176
 
162
- ## Maintainers
177
+ See [CONTRIBUTING.md](./CONTRIBUTING.md) for the release process and maintainer setup.
163
178
 
164
- Use conventional commits to select the next release version. Release-producing changes use the `n8n-node` scope:
165
-
166
- ```bash
167
- git commit -m "fix(n8n-node): describe the fix"
168
- ```
179
+ ## How Commons is used
169
180
 
170
- On pushes to `main`, GitHub Actions calculates the next version from the latest `n8n-node-vX.Y.Z` tag and tests the attempted package. When the manifests need updating, CI commits both files on `release/n8n-node-vX.Y.Z` and opens a release PR. After that protected PR is reviewed and merged, the next `main` run verifies the committed version, waits for approval in the `release` environment, creates the matching tag and GitHub release, and publishes the tested `.tgz` to npm.
181
+ Atto Commons supplies the protocol models, address derivation, block construction, hashing, and signing.
171
182
 
172
- Do not bump `package.json` manually. Snapshot versions exist only in their workflow runners; successful releases commit the version through the protected release PR so the repository and npm stay synchronized.
183
+ | Package | Role in this repository | Published package |
184
+ | --- | --- | --- |
185
+ | `@attocash/commons-core` | Runtime protocol implementation | Bundled into the built protocol adapter |
186
+ | `@attocash/commons-test` | Node and Worker mocks for integration tests | Not used or installed at runtime |
187
+ | `n8n-workflow` | n8n types and runtime APIs | Provided by n8n as a peer dependency |
173
188
 
174
- Allow GitHub Actions to create pull requests under **Settings → Actions → General → Workflow permissions**. A version PR created with `GITHUB_TOKEN` may require a maintainer to approve its workflow run before the required `test / test` check starts.
189
+ 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.
175
190
 
176
- Configure npm Trusted Publishing for `.github/workflows/n8n-node-package.yml`.
191
+ ## Support
177
192
 
178
- ## Notes
193
+ - Read the operation notes in [USAGE.md](./USAGE.md).
194
+ - Open a bug or feature request in [GitHub Issues](https://github.com/attocash/integrations-n8n/issues).
195
+ - See the [n8n community-node documentation](https://docs.n8n.io/integrations/community-nodes/).
179
196
 
180
- - Runtime protocol behavior comes from `@attocash/commons-core`; `@attocash/commons-test` is used only by integration tests.
181
- - Commons Core is bundled once into the built protocol adapter, so the published n8n package has no runtime dependencies beyond n8n.
182
- - Hex private keys must use the format accepted by `AttoPrivateKey.Companion.parse`.
197
+ This package is available under the [MIT License](./LICENSE).
package/dist/nodes/AttoTrigger/AttoTrigger.node.js CHANGED
@@ -50,7 +50,6 @@ class AttoTrigger {
50
50
  },
51
51
  inputs: [],
52
52
  outputs: [n8n_workflow_1.NodeConnectionTypes.Main],
53
- usableAsTool: true,
54
53
  credentials: [
55
54
  {
56
55
  name: 'attoApi',
package/dist/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@attocash/n8n-nodes-atto",
3
- "version": "0.4.1",
3
+ "version": "0.4.3",
4
4
  "description": "Atto cryptocurrency wallet, transaction, account, and trigger nodes for n8n, powered by Atto Commons",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -56,7 +56,7 @@
56
56
  "validate:release-tag": "node scripts/validate-release-tag.mjs"
57
57
  },
58
58
  "engines": {
59
- "node": ">=22.16"
59
+ "node": ">=22.22.0"
60
60
  },
61
61
  "devDependencies": {
62
62
  "@attocash/commons-core": "7.0.2",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@attocash/n8n-nodes-atto",
3
- "version": "0.4.1",
3
+ "version": "0.4.3",
4
4
  "description": "Atto cryptocurrency wallet, transaction, account, and trigger nodes for n8n, powered by Atto Commons",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -56,7 +56,7 @@
56
56
  "validate:release-tag": "node scripts/validate-release-tag.mjs"
57
57
  },
58
58
  "engines": {
59
- "node": ">=22.16"
59
+ "node": ">=22.22.0"
60
60
  },
61
61
  "devDependencies": {
62
62
  "@attocash/commons-core": "7.0.2",