@attocash/n8n-nodes-atto 0.4.1 → 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.
Files changed (3) hide show
  1. package/README.md +122 -108
  2. package/dist/package.json +2 -2
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,145 +1,162 @@
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="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 |
80
103
 
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.
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.
85
105
 
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.
106
+ ## Example workflows
87
107
 
88
- ## Example Workflows
108
+ The [`examples`](./examples) directory contains importable workflows:
89
109
 
90
- Importable examples live in [`examples`](./examples):
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.
91
114
 
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.
115
+ Attach your **Atto API** credential after importing a workflow. Replace placeholder addresses before running a transaction operation.
96
116
 
97
- After importing an example, attach your **Atto API** credential and replace any placeholder addresses before running transaction operations.
117
+ ## Security
98
118
 
99
- ## Local Development
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.
120
+
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.
122
+
123
+ ## Compatibility
124
+
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 |
131
+
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.
133
+
134
+ ## Development
100
135
 
101
136
  Install dependencies and run the checks:
102
137
 
103
138
  ```bash
104
- npm install --ignore-scripts
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
- Dependencies ship prebuilt, so lifecycle scripts are disabled to avoid transitive package-manager guard scripts.
113
-
114
- 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:
115
146
 
116
147
  ```bash
117
148
  ATTO_TEST_INTEGRATION=1 npm run test:integration
118
149
  ```
119
150
 
120
- ### Run n8n With Podman
121
-
122
- From this package directory:
151
+ Start the n8n development environment with:
123
152
 
124
153
  ```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
154
+ npm run dev
136
155
  ```
137
156
 
138
- Open `http://localhost:5678`, create a workflow, and add **Atto** or **Atto Trigger**.
139
-
140
- ### Install From A Checkout Inside n8n
157
+ ### Install from a checkout
141
158
 
142
- If you have shell access inside the n8n container:
159
+ If you have shell access inside an n8n container:
143
160
 
144
161
  ```bash
145
162
  cd /tmp
@@ -148,35 +165,32 @@ cd integrations-n8n
148
165
  npm run install:n8n
149
166
  ```
150
167
 
151
- 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:
152
169
 
153
- 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`.
154
173
 
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.
174
+ Set `RUN_TESTS=1` to run the full test suite before installation. Restart n8n when the installer finishes.
161
175
 
162
- ## Maintainers
176
+ See [CONTRIBUTING.md](./CONTRIBUTING.md) for the release process and maintainer setup.
163
177
 
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
- ```
178
+ ## How Commons is used
169
179
 
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.
180
+ Atto Commons supplies the protocol models, address derivation, block construction, hashing, and signing.
171
181
 
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.
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 |
173
187
 
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.
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.
175
189
 
176
- Configure npm Trusted Publishing for `.github/workflows/n8n-node-package.yml`.
190
+ ## Support
177
191
 
178
- ## 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/).
179
195
 
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`.
196
+ This package is available under the [MIT License](./LICENSE).
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.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": [
@@ -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.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": [
@@ -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",