@andreswagner/node-red-contrib-wxo-agent 0.1.4

package/LICENSE

@@ -0,0 +1,178 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (which shall not include Communications that are clearly marked or
+   otherwise designated in writing by the copyright owner as "Not a Work").
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is clearly marked or otherwise designated
+   in writing by the copyright owner as "Not a Contribution".
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed as
+       modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+

package/README.md

@@ -0,0 +1,388 @@
+# node-red-contrib-wxo-agent
+
+Node-RED node for invoking IBM watsonx Orchestrate agents. Easily integrate AI orchestration capabilities into your Node-RED flows with support for multi-turn conversations and flexible input formats.
+
+## Installation
+
+Install from npm:
+
+```bash
+npm install node-red-contrib-wxo-agent
+```
+
+Or install via Node-RED's Manage Palette:
+1. Open Node-RED
+2. Go to ☰ → Manage palette
+3. Search for `node-red-contrib-wxo-agent`
+4. Click Install
+
+After installation, restart Node-RED to load the new nodes.
+
+## Quick Start
+
+1. **Install the package** (see Installation above)
+2. **Add credentials**: Drag the WxO Agent node to your flow, edit it, and configure your IBM Cloud API Key and Watson Orchestrate instance URL
+3. **Select an agent**: The agent dropdown will populate automatically
+4. **Send a message**: Use `msg.payload = "Hello"` to send a simple message
+
+## Usage
+
+### 1. Configure Credentials
+
+1. Drag the **WxO Agent** node onto your flow
+2. Double-click to edit
+3. Click the pencil icon next to Credentials to add new credentials
+4. Enter your IBM Cloud API Key
+5. Enter your Watson Orchestrate API URL (full instance URL, e.g., `https://api.us-south.watson-orchestrate.cloud.ibm.com/instances/your-instance-id`)
+
+### 2. Select an Agent
+
+After configuring credentials, the Agent dropdown will automatically populate with available agents. Click the refresh button to reload the list.
+
+### 3. Send Messages
+
+You can send messages in two formats:
+
+**Simple string** (recommended for basic use):
+```javascript
+msg.payload = "What can you help me with?";
+return msg;
+```
+
+**Full API request object** (for advanced use with additional parameters):
+```javascript
+msg.payload = {
+  "messages": [
+    {
+      "role": "user",
+      "content": "Hello"
+    }
+  ],
+  "additional_parameters": {
+    "id": 4013386960470016
+  },
+  "context": {
+    "id": 4234274192490496
+  },
+  "stream": false
+};
+return msg;
+```
+
+### 4. Multi-turn Conversations
+
+The node outputs `msg.topic` with the thread ID, which is automatically used in subsequent messages to continue the conversation:
+
+```javascript
+// First message starts a new conversation
+msg.payload = "Hello";
+return msg;
+
+// Subsequent messages use the thread ID from msg.topic
+msg.payload = "Tell me more";
+// msg.topic is automatically preserved for conversation continuity
+return msg;
+```
+
+To force a new conversation:
+```javascript
+msg.wxo_new_session = true;
+msg.payload = "Start fresh";
+return msg;
+```
+
+## Example Flows
+
+### Multi-turn Conversation Example
+
+This example demonstrates a complete multi-turn conversation with automatic thread ID preservation and error handling.
+
+**To use this flow:**
+
+1. Copy the flow JSON below
+2. In Node-RED, go to ☰ → Import
+3. Paste the JSON and click "Import"
+4. Configure the flow:
+   - Edit each **WxO Agent** node
+   - Replace `YOUR_CREDENTIALS_ID` with your actual credentials configuration ID
+   - Replace `YOUR_AGENT_ID` with your agent ID
+   - Update `Your Agent Name` with your agent's display name
+5. Deploy and click the **Start Conversation** inject button
+
+**What this flow demonstrates:**
+- Simple string input to start a conversation
+- Automatic thread ID preservation in `msg.topic` for conversation continuity
+- Multi-turn conversation where the agent remembers context from previous messages
+- Error handling with a Catch node
+- Debug output showing just the agent's response text
+
+**Flow JSON:**
+
+```json
+[
+  {
+    "id": "flow-example-1",
+    "type": "tab",
+    "label": "WxO Agent Example - Multi-turn Conversation",
+    "disabled": false,
+    "info": "Example flow demonstrating multi-turn conversation with thread ID preservation",
+    "env": []
+  },
+  {
+    "id": "inject-1",
+    "type": "inject",
+    "z": "flow-example-1",
+    "name": "Start Conversation",
+    "props": [{"p": "payload"}],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "topic": "",
+    "payload": "Hi, my name is Bob!",
+    "payloadType": "str",
+    "x": 140,
+    "y": 100,
+    "wires": [["wxo-agent-1"]]
+  },
+  {
+    "id": "wxo-agent-1",
+    "type": "wxo-agent",
+    "z": "flow-example-1",
+    "name": "WxO Agent",
+    "wxoCredentials": "YOUR_CREDENTIALS_ID",
+    "agentId": "YOUR_AGENT_ID",
+    "agentName": "Your Agent Name",
+    "timeout": 30000,
+    "x": 350,
+    "y": 100,
+    "wires": [["debug-1", "function-1"]]
+  },
+  {
+    "id": "debug-1",
+    "type": "debug",
+    "z": "flow-example-1",
+    "name": "Agent Response",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "payload.choices[0].message.content",
+    "targetType": "msg",
+    "statusVal": "",
+    "statusType": "auto",
+    "x": 550,
+    "y": 100,
+    "wires": []
+  },
+  {
+    "id": "function-1",
+    "type": "function",
+    "z": "flow-example-1",
+    "name": "Continue Conversation",
+    "func": "// msg.topic contains the thread ID from the previous response\n// This is automatically preserved for conversation continuity\nmsg.payload = \"What's my name?\";\nreturn msg;",
+    "outputs": 1,
+    "timeout": 0,
+    "noerr": 0,
+    "initialize": "",
+    "finalize": "",
+    "libs": [],
+    "x": 200,
+    "y": 180,
+    "wires": [["wxo-agent-2"]]
+  },
+  {
+    "id": "wxo-agent-2",
+    "type": "wxo-agent",
+    "z": "flow-example-1",
+    "name": "WxO Agent",
+    "wxoCredentials": "YOUR_CREDENTIALS_ID",
+    "agentId": "YOUR_AGENT_ID",
+    "agentName": "Your Agent Name",
+    "timeout": 30000,
+    "x": 350,
+    "y": 180,
+    "wires": [["debug-2"]]
+  },
+  {
+    "id": "debug-2",
+    "type": "debug",
+    "z": "flow-example-1",
+    "name": "Follow-up Response",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "payload.choices[0].message.content",
+    "targetType": "msg",
+    "statusVal": "",
+    "statusType": "auto",
+    "x": 570,
+    "y": 180,
+    "wires": []
+  },
+  {
+    "id": "catch-1",
+    "type": "catch",
+    "z": "flow-example-1",
+    "name": "Error Handler",
+    "scope": ["wxo-agent-1", "wxo-agent-2"],
+    "uncaught": false,
+    "x": 350,
+    "y": 260,
+    "wires": [["debug-error"]]
+  },
+  {
+    "id": "debug-error",
+    "type": "debug",
+    "z": "flow-example-1",
+    "name": "Error Output",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "error",
+    "targetType": "msg",
+    "statusVal": "",
+    "statusType": "auto",
+    "x": 550,
+    "y": 260,
+    "wires": []
+  }
+]
+```
+
+**Note:** The `msg.topic` property is automatically set by the WxO Agent node with the thread ID from the API response. When you pass `msg` to the next agent node, the thread ID is automatically preserved, enabling conversation continuity. The function node in this example demonstrates this - it receives the message with `msg.topic` already set and simply updates the payload for the follow-up question.
+
+## Input
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `payload` | string/object | Message to send to the agent. Can be:<br>- Simple string (e.g., `"Hello"`)<br>- Full API request object with `messages` array (see official API docs) |
+| `topic` | string | (Optional) Thread ID for conversation continuation |
+| `wxo_new_session` | boolean | (Optional) Force new conversation |
+
+## Output
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `payload` | object | Full API response object (OpenAI-compatible format) |
+| `topic` | string | Thread ID for conversation continuation |
+
+The `payload` object is the complete API response and includes:
+- `id`: string - Unique response identifier
+- `object`: string - Response type (e.g., "chat.completion")
+- `created`: number - Unix timestamp
+- `model`: string - Model used for response
+- `choices`: array - Response choices containing:
+  - `message`: object with `role` and `content` (the agent's response text)
+  - `finish_reason`: string
+- `thread_id`: string - Conversation thread ID for multi-turn
+
+Access the agent's response text via: `msg.payload.choices[0].message.content`
+
+## Error Handling
+
+On error, the node outputs:
+
+```javascript
+msg.error = {
+  code: "ERROR_CODE",
+  message: "Human readable message",
+  details: { /* API response */ },
+  recoverable: true/false
+}
+```
+
+Use a Catch node to handle errors in your flow.
+
+## Features
+
+- ✅ Simple string or full API request object input
+- ✅ Automatic authentication with IBM Cloud IAM
+- ✅ Multi-turn conversation support via `msg.topic`
+- ✅ Agent selection from dropdown
+- ✅ Comprehensive error handling
+- ✅ OpenAI-compatible response format
+
+## Requirements
+
+- Node-RED 3.0.0 or higher
+- Node.js 18.0.0 or higher
+- IBM Cloud account with watsonx Orchestrate access
+- Valid IBM Cloud API Key
+
+## Development
+
+For developers contributing to this package:
+
+### Running Tests
+
+1. Copy the environment template:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Edit `.env` with your actual credentials:
+   ```
+   # Required for API integration tests
+   IBM_CLOUD_API_KEY=your-api-key
+   WXO_BASE_URL=https://api.us-south.watson-orchestrate.cloud.ibm.com/instances/your-instance-id
+   
+   # Optional: Required only for NPM publication testing (T031)
+   NPM_USERNAME=your-npm-username
+   NPM_TOKEN=your-npm-token
+   # NPM_REGISTRY=https://registry.npmjs.org/  # Optional: if using private registry
+   ```
+
+3. Run the tests:
+   ```bash
+   npm install
+   npm test
+   ```
+
+### Test Structure
+
+The test suite includes:
+
+- **Unit Tests** (`tests/unit/`): Component/library tests for underlying logic
+  - Token manager, API client, input parsing, etc.
+  - These test the core functionality without Node-RED runtime
+
+- **Integration Tests** (`tests/integration/`): Node-RED node tests using `node-red-node-test-helper`
+  - Test the actual node behavior in Node-RED runtime
+  - Create test flows and assert node properties and output
+  - Follow Node-RED's recommended testing approach
+
+The tests use real API calls to verify functionality. Tests will skip gracefully if credentials are not configured.
+
+### NPM Publication
+
+For instructions on testing and publishing the package to NPM, see [NPM_PUBLICATION.md](./NPM_PUBLICATION.md).
+
+Quick verification:
+```bash
+# Setup package metadata (author and repository) - auto-detects from git
+npm run setup-metadata
+
+# Verify NPM publication requirements
+npm run verify-npm
+
+# Verify Node-RED Library requirements (includes LICENSE, author, repository)
+npm run verify-library
+```
+
+**Important**: After publishing to NPM, register your node with the [Node-RED Flow Library](https://flows.nodered.org/add/node) to make it discoverable in Node-RED's Manage Palette.
+
+## Support
+
+For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/your-username/node-red-contrib-wxo-agent) (update with actual repository URL when available).
+
+## License
+
+Apache-2.0
+
+---
+
+**Note**: This package is published to npm as `node-red-contrib-wxo-agent`. For development installation from a local path, see the Development section above.
+

package/WxO.svg

@@ -0,0 +1,31 @@
+<svg id="watsonxOrchestrate" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 32 32">
+  <defs>
+    <linearGradient id="91vs45zuba" x1="-1255.959" y1="-5638.355" x2="-1255.959" y2="-5630.355" gradientTransform="matrix(1 0 0 -1 1259.459 -5613.355)" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-opacity="0"/>
+      <stop offset=".83"/>
+    </linearGradient>
+    <linearGradient id="q8jdu6hf5b" x1="-1236.667" y1="-5652.015" x2="-1239.915" y2="-5646.39" gradientTransform="matrix(1 0 0 -1 1255.541 -5629.251)" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-opacity="0"/>
+      <stop offset=".7"/>
+    </linearGradient>
+    <linearGradient id="1ai661jxzc" x1="-1817.959" y1="-1524.355" x2="-1817.959" y2="-1516.355" gradientTransform="matrix(1 0 0 -1 1846.459 -1509.355)" xlink:href="#91vs45zuba"/>
+    <linearGradient id="ho9vmd9vod" x1="-1798.667" y1="-1538.015" x2="-1801.915" y2="-1532.39" gradientTransform="matrix(-1 0 0 1 -1785.541 1547.251)" xlink:href="#q8jdu6hf5b"/>
+    <linearGradient id="7wtfcdzjif" x1="0" y1="32" x2="32" y2="0" gradientUnits="userSpaceOnUse">
+      <stop offset=".1" stop-color="#a56eff"/>
+      <stop offset=".9" stop-color="#0f62fe"/>
+    </linearGradient>
+    <mask id="blf0dpbsne" x="0" y="0" width="32" height="32" maskUnits="userSpaceOnUse">
+      <path d="M30.851 14H28.83C27.863 7.78 22.487 3 16 3 11.38 3 7.326 5.429 5.02 9.07A7.939 7.939 0 0 1 9 8c3.719 0 6.845 2.555 7.737 6H14.65c-.826-2.327-3.043-4-5.65-4a5.958 5.958 0 0 0-4.78 2.407l-2.525-.842C3.591 5.456 9.275 1 16 1c7.591 0 13.868 5.674 14.851 13zm-3.071 5.593A5.957 5.957 0 0 1 23 22c-2.607 0-4.824-1.673-5.65-4h-2.087c.892 3.445 4.017 6 7.737 6a7.941 7.941 0 0 0 3.98-1.07C24.674 26.571 20.62 29 16 29 9.513 29 4.137 24.22 3.17 18H1.149C2.132 25.326 8.408 31 16 31c6.725 0 12.409-4.456 14.305-10.565l-2.525-.842z" style="fill:#fff;stroke-width:0"/>
+      <path style="fill:url(#91vs45zuba);stroke-width:0" d="M0 17h7v8H0z"/>
+      <path style="fill:url(#q8jdu6hf5b);stroke-width:0" d="M21 17.5h-6V25l6-3.5v-4z"/>
+      <path transform="rotate(-180 28.5 11)" style="fill:url(#1ai661jxzc);stroke-width:0" d="M25 7h7v8h-7z"/>
+      <path style="fill:url(#ho9vmd9vod);stroke-width:0" d="M11 14.5h6V7l-6 3.5v4z"/>
+    </mask>
+  </defs>
+  <g style="mask:url(#blf0dpbsne)">
+    <path style="fill:url(#7wtfcdzjif);stroke-width:0" d="M0 0h32v32H0z"/>
+  </g>
+  <circle cx="30" cy="16" r="2" style="fill:#001d6c;stroke-width:0"/>
+  <circle cx="2" cy="16" r="2" style="fill:#001d6c;stroke-width:0"/>
+  <circle cx="16" cy="16" r="2" style="fill:#001d6c;stroke-width:0"/>
+</svg>