@inductiv/node-red-openai-api 6.22.0 → 6.27.0

package/README.md

@@ -4,17 +4,63 @@
 ![GitHub Issues](https://img.shields.io/github/issues/allanbunch/node-red-openai-api)
 ![GitHub Stars](https://img.shields.io/github/stars/allanbunch/node-red-openai-api)
 
-Node-RED node for calling the OpenAI API (and OpenAI-compatible APIs) through a single configurable node.
+This project brings the OpenAI API, and OpenAI-compatible APIs, into Node-RED as workflow-native building blocks.
 
-This package currently targets `openai` Node SDK `^6.22.0`.
+It is not just a thin wrapper around text generation. The node exposes modern AI capabilities inside a runtime people can inspect, route, test, and operate: request and response workflows, tools, conversations, streaming, realtime interactions, webhooks, and related API families that matter in real systems.
 
-## What You Get
+That makes this repository relevant beyond Node-RED alone. It is a practical implementation of how contemporary AI capabilities can live inside an open workflow environment instead of being locked inside a single vendor surface or hidden behind a one-purpose abstraction.
 
-- One `OpenAI API` node with method selection across major API families.
-- One `Service Host` config node for base URL, auth, and org settings.
-- Typed input support for key config fields: `str`, `env`, `msg`, `flow`, `global` (plus `cred` for API key).
-- Backward compatibility handling for older API key storage patterns.
-- Built-in examples for common flows.
+This package currently targets the `openai` Node SDK `^6.27.0`.
+
+## Why This Exists
+
+Modern AI work is no longer just "send a prompt, get a string back."
+
+Real systems now involve:
+
+- tool use
+- multi-step workflows
+- structured payloads
+- streaming responses
+- realtime sessions
+- webhook verification
+- provider compatibility and auth routing
+
+Node-RED is already good at orchestration, automation, event handling, integration, and operational clarity. This project connects those strengths to the OpenAI API surface so teams can build AI workflows in an environment that stays visible and composable.
+
+## Core Model
+
+The node model in this repository is intentionally simple:
+
+- one `OpenAI API` node handles the runtime method call
+- one `Service Host` config node handles API base URL, auth, and organization settings
+- the selected method determines which OpenAI API context is being called
+- request data is passed in through a configurable message property, `msg.payload` by default
+- method-specific details live in the editor help, example flows, and the underlying SDK contract
+
+In practice, that means one node can cover a wide API surface without turning the flow itself into a maze of special-purpose nodes.
+
+## What It Enables
+
+### Request and Response Workflows
+
+Use the node for direct generation, structured Responses API work, chat-style interactions, moderation, embeddings, image work, audio tasks, and other request/response patterns.
+
+### Tool-Enabled and Multi-Step AI Flows
+
+Use Responses tools, conversations, runs, messages, vector stores, files, skills, and related resources as part of larger control loops and operational workflows.
+
+### Streaming and Realtime Work
+
+Use streamed Responses output, Realtime client-secret creation, SIP call operations, and persistent Responses websocket connections where a flow needs more than one-shot request handling.
+
+### Event-Driven Integrations
+
+Use webhook signature verification and payload unwrapping in Node-RED flows that react to upstream platform events.
+
+### OpenAI-Compatible Provider Support
+
+Use the `Service Host` config to target compatible API providers with custom base URLs, custom auth header names, query-string auth routing, and typed configuration values.
 
 ## Requirements
 
@@ -39,13 +85,13 @@ npm i @inductiv/node-red-openai-api
 ## Quick Start
 
 1. Drop an `OpenAI API` node onto your flow.
-2. In the node editor, use the `Service Host` field to either select an existing config node or create one with the `+` button.
-3. In that `Service Host` config, set `API Base` (default: `https://api.openai.com/v1`).
-4. Set `API Key`:
-   - `cred` type for a masked credential value, or
-   - `env/msg/flow/global` and provide a reference name.
-5. Back in the `OpenAI API` node, select your method (for example `create model response`).
-6. Send request params in `msg.payload` (or change the input property on the node).
+2. Create or select a `Service Host` config node.
+3. Set `API Base` to your provider endpoint. The default OpenAI value is `https://api.openai.com/v1`.
+4. Set `API Key` using either:
+   - `cred` for a stored credential value, or
+   - `env`, `msg`, `flow`, or `global` for a runtime reference
+5. Pick a method on the `OpenAI API` node, such as `create model response`.
+6. Send the request payload through `msg.payload`, or change the node's input property if your flow uses a different message shape.
 
 Example `msg.payload` for `create model response`:
 
@@ -56,36 +102,39 @@ Example `msg.payload` for `create model response`:
 }
 ```
 
-Node output is written to `msg.payload`.
-
-## Service Host Configuration
-
-### API Key
+The node writes its output back to `msg.payload`.
 
-- `cred` keeps the value in Node-RED credentials (masked in the editor).
-- `env/msg/flow/global` treats the field as a reference, not a literal key.
-- Existing flows with older key storage formats are still handled.
+## Start Here
 
-### Auth Header
+If you want to understand the shape of this node quickly, these example flows are the best entry points:
 
-- Default value is `Authorization`.
-- You can override it for OpenAI-compatible providers that use a different header name.
-
-### Organization ID
+- [`examples/chat.json`](examples/chat.json)
+  A straightforward API-call flow for getting oriented.
+- [`examples/responses/phase.json`](examples/responses/phase.json)
+  A clean Responses example using newer payload features.
+- [`examples/responses/tool-search.json`](examples/responses/tool-search.json)
+  Shows tool-enabled Responses work in a practical flow.
+- [`examples/responses/computer-use.json`](examples/responses/computer-use.json)
+  Shows the request and follow-up contract for computer-use style workflows.
+- [`examples/responses/websocket.json`](examples/responses/websocket.json)
+  Shows explicit websocket lifecycle handling in one node instance.
+- [`examples/realtime/client-secrets.json`](examples/realtime/client-secrets.json)
+  Shows the Realtime client-secret contract for browser or mobile handoff.
 
-- Optional.
-- Supports typed input (`str/env/msg/flow/global`) like other service fields.
+## Current Alignment Highlights
 
-### Environment Variables
+This repository currently includes:
 
-You can source values from:
+- Responses API support, including `phase`, `prompt_cache_key`, `tool_search`, GA computer-use payloads, cancellation, compaction, input-token counting, and websocket mode
+- Realtime API support, including client-secret creation, SIP call operations, and current SDK-typed model ids such as `gpt-realtime-1.5` and `gpt-audio-1.5`
+- Conversations, Containers, Container Files, Evals, Skills, Videos, and Webhooks support
+- OpenAI-compatible auth routing through the `Service Host` config node
 
-- OS-level environment variables.
-- Node-RED editor environment variables (`User Settings -> Environment`).
+See the in-editor node help for exact method payloads and links to official API documentation.
 
-## Supported API Families
+## API Surface
 
-The method dropdown includes operations across:
+The method picker covers a wide range of OpenAI API families:
 
 - Assistants
 - Audio
@@ -114,46 +163,11 @@ The method dropdown includes operations across:
 - Videos
 - Webhooks
 
-`Graders` are supported through Evals payloads (`testing_criteria`) in the same way the official SDK models them.
-
-See the in-editor node help for method-specific payload fields and links to official API docs.
-
-## Recent Additions
-
-- Added environment variable support for service host configuration values.
-- OpenAI Node SDK upgraded from `4.103.0` to `6.22.0`.
-- Added `responses.cancel`.
-- Added `responses.compact`.
-- Added `responses.input_tokens` counting support.
-- Added Conversations API support:
-  - create/retrieve/modify/delete conversation
-  - create/retrieve/list/delete conversation items
-- Added Containers and Container Files support.
-- Added MCP tool use example flow at `examples/responses/mcp.json`.
-- Added Skills API support:
-  - list/create/retrieve/modify/delete skills
-  - retrieve skill content
-  - list/create/retrieve/delete skill versions
-  - retrieve skill version content
-- Added Evals API support:
-  - list/create/retrieve/modify/delete evals
-  - list/create/retrieve/cancel/delete eval runs
-  - list/retrieve eval run output items
-- Added Realtime API support:
-  - create client secret
-  - accept/hangup/refer/reject SIP calls
-- Added Videos API support:
-  - list/create/retrieve/delete videos
-  - download video content
-  - remix videos
-- Added Webhooks utility support:
-  - unwrap signed webhook payloads
-  - verify webhook signatures
-- Service Host auth routing now applies `Auth Header` configuration at request time.
-
-## Examples
-
-Import-ready example flows are available in `examples/`:
+`Graders` are supported through Evals payloads via `testing_criteria`, in the same way the official SDK models them.
+
+## Example Index
+
+Import-ready example flows live under `examples/`:
 
 - [`examples/assistants.json`](examples/assistants.json)
 - [`examples/audio.json`](examples/audio.json)
@@ -165,9 +179,47 @@ Import-ready example flows are available in `examples/`:
 - [`examples/messages.json`](examples/messages.json)
 - [`examples/models.json`](examples/models.json)
 - [`examples/moderations.json`](examples/moderations.json)
+- [`examples/realtime/client-secrets.json`](examples/realtime/client-secrets.json)
+- [`examples/responses/computer-use.json`](examples/responses/computer-use.json)
+- [`examples/responses/mcp.json`](examples/responses/mcp.json)
+- [`examples/responses/phase.json`](examples/responses/phase.json)
+- [`examples/responses/tool-search.json`](examples/responses/tool-search.json)
+- [`examples/responses/websocket.json`](examples/responses/websocket.json)
 - [`examples/runs.json`](examples/runs.json)
 - [`examples/threads.json`](examples/threads.json)
-- [`examples/responses/mcp.json`](examples/responses/mcp.json)
+
+## Service Host Notes
+
+The `Service Host` config node handles the provider-specific runtime boundary.
+
+- `API Key` supports `cred`, `env`, `msg`, `flow`, and `global`
+- `API Base` can point at OpenAI or a compatible provider
+- `Auth Header` defaults to `Authorization`, but can be changed for provider-specific auth conventions
+- auth can be sent either as a header or as a query-string parameter
+- `Organization ID` is optional and supports typed values like the other service fields
+
+This is the piece that lets one runtime model work cleanly across both OpenAI and compatible API surfaces.
+
+## Repository Shape
+
+This repository is structured so the runtime, editor, examples, and generated artifacts stay understandable:
+
+- [`node.js`](node.js)
+  Node-RED runtime entry point and `Service Host` config-node logic.
+- [`src/`](src)
+  Source modules for method implementations, editor templates, and help content.
+- [`src/lib.js`](src/lib.js)
+  Source entry for the bundled runtime method surface.
+- [`lib.js`](lib.js)
+  Generated runtime bundle built from `src/lib.js`.
+- [`src/node.html`](src/node.html)
+  Source editor template that includes the per-family fragments.
+- [`node.html`](node.html)
+  Generated editor asset built from `src/node.html`.
+- [`examples/`](examples)
+  Import-ready Node-RED flows.
+- [`test/`](test)
+  Node test coverage for editor behavior, auth routing, method mapping, and websocket lifecycle behavior.
 
 ## Development
 
@@ -177,18 +229,23 @@ npm run build
 npm test
 ```
 
-Build output files are generated from `src/`:
+Generated files are part of the project:
 
-- `node.html` (from `src/node.html`)
-- `lib.js` (from `src/lib.js`)
+- `node.html` is built from `src/node.html`
+- `lib.js` is built from `src/lib.js`
+
+If you change source templates or runtime source files, rebuild before review or release.
 
 ## Contributing
 
-PRs are welcome. Please include:
+Contributions are welcome. Keep changes clear, intentional, and proven.
+
+Please include:
 
-- clear scope and rationale,
-- tests for behavior changes,
-- doc updates when user-facing behavior changes.
+- a clear scope and rationale
+- tests for behavior changes
+- a short plain-language comment block at the top of each test file you add or touch
+- doc updates when user-facing behavior changes
 
 ## License
 

package/examples/realtime/client-secrets.json

@@ -0,0 +1,182 @@
+[
+    {
+        "id": "7c28d6f5b81f4cf3",
+        "type": "tab",
+        "label": "Realtime Client Secret Example",
+        "disabled": false,
+        "info": "Realtime client-secret example.\n\nThis flow demonstrates the correct nested request contract for `createRealtimeClientSecret`:\n- client-secret options such as `expires_after` stay at the top level\n- Realtime session configuration lives under `session`\n- two inject nodes show the newer SDK-typed model ids `gpt-realtime-1.5` and `gpt-audio-1.5`",
+        "env": []
+    },
+    {
+        "id": "2b6f81da44f1b506",
+        "type": "comment",
+        "z": "7c28d6f5b81f4cf3",
+        "name": "Set your API key, then run either inject node.",
+        "info": "Before running:\n- open the `OpenAI Auth` config node and set a valid API key\n- this example stores request data in `msg.ai` because the `OpenAI API` node property is configured to `ai`\n- if your node uses the default property, the same shape belongs under `msg.payload`\n\nWhat this flow teaches:\n- `expires_after` remains top-level request metadata\n- Realtime session fields are nested under `session`\n- both `gpt-realtime-1.5` and `gpt-audio-1.5` pass through the existing adapter unchanged",
+        "x": 430,
+        "y": 140,
+        "wires": []
+    },
+    {
+        "id": "d48aabf237113ec2",
+        "type": "comment",
+        "z": "7c28d6f5b81f4cf3",
+        "name": "What is a client secret?",
+        "info": "A Realtime client secret is not your long-lived OpenAI API key.\n\nIt is a short-lived ephemeral token created server-side so a browser or mobile client can connect to the Realtime API without exposing the main API key.\n\nTypical flow:\n- your server or Node-RED flow creates the client secret\n- the returned `value` is passed to a trusted client application\n- that client uses the secret to open a Realtime session before it expires",
+        "x": 430,
+        "y": 200,
+        "wires": []
+    },
+    {
+        "id": "6e1099b8233f4f6f",
+        "type": "inject",
+        "z": "7c28d6f5b81f4cf3",
+        "name": "Create Realtime 1.5 Client Secret",
+        "props": [
+            {
+                "p": "ai.expires_after.anchor",
+                "v": "created_at",
+                "vt": "str"
+            },
+            {
+                "p": "ai.expires_after.seconds",
+                "v": "600",
+                "vt": "num"
+            },
+            {
+                "p": "ai.session.type",
+                "v": "realtime",
+                "vt": "str"
+            },
+            {
+                "p": "ai.session.model",
+                "v": "gpt-realtime-1.5",
+                "vt": "str"
+            },
+            {
+                "p": "ai.session.output_modalities[0]",
+                "v": "audio",
+                "vt": "str"
+            },
+            {
+                "p": "ai.session.instructions",
+                "v": "Speak clearly and keep responses concise.",
+                "vt": "str"
+            }
+        ],
+        "repeat": "",
+        "crontab": "",
+        "once": false,
+        "onceDelay": 0.1,
+        "topic": "",
+        "x": 300,
+        "y": 260,
+        "wires": [
+            [
+                "9df67f8a39c32558"
+            ]
+        ]
+    },
+    {
+        "id": "b7fce6b60f312e8a",
+        "type": "inject",
+        "z": "7c28d6f5b81f4cf3",
+        "name": "Create Audio 1.5 Client Secret",
+        "props": [
+            {
+                "p": "ai.expires_after.anchor",
+                "v": "created_at",
+                "vt": "str"
+            },
+            {
+                "p": "ai.expires_after.seconds",
+                "v": "600",
+                "vt": "num"
+            },
+            {
+                "p": "ai.session.type",
+                "v": "realtime",
+                "vt": "str"
+            },
+            {
+                "p": "ai.session.model",
+                "v": "gpt-audio-1.5",
+                "vt": "str"
+            },
+            {
+                "p": "ai.session.output_modalities[0]",
+                "v": "audio",
+                "vt": "str"
+            },
+            {
+                "p": "ai.session.instructions",
+                "v": "Generate short audio responses.",
+                "vt": "str"
+            }
+        ],
+        "repeat": "",
+        "crontab": "",
+        "once": false,
+        "onceDelay": 0.1,
+        "topic": "",
+        "x": 290,
+        "y": 340,
+        "wires": [
+            [
+                "9df67f8a39c32558"
+            ]
+        ]
+    },
+    {
+        "id": "65c6ad57d8ef6d54",
+        "type": "comment",
+        "z": "7c28d6f5b81f4cf3",
+        "name": "Expected result: debug sidebar shows value, expires_at, and session.",
+        "info": "Successful responses from `createRealtimeClientSecret` return top-level `value`, `expires_at`, and `session` fields.\n\nWhat to inspect in the debug sidebar:\n- `session.type` should be `realtime`\n- `session.model` should match the inject node you sent\n- `value` is the ephemeral client secret to hand to a browser or mobile client",
+        "x": 520,
+        "y": 420,
+        "wires": []
+    },
+    {
+        "id": "9df67f8a39c32558",
+        "type": "OpenAI API",
+        "z": "7c28d6f5b81f4cf3",
+        "name": "Create Realtime Client Secret",
+        "property": "ai",
+        "propertyType": "msg",
+        "service": "40e8a97d10d65e1e",
+        "method": "createRealtimeClientSecret",
+        "x": 600,
+        "y": 300,
+        "wires": [
+            [
+                "86453bdf02676d9f"
+            ]
+        ]
+    },
+    {
+        "id": "86453bdf02676d9f",
+        "type": "debug",
+        "z": "7c28d6f5b81f4cf3",
+        "name": "Realtime Client Secret",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": false,
+        "complete": "true",
+        "targetType": "full",
+        "statusVal": "",
+        "statusType": "auto",
+        "x": 860,
+        "y": 300,
+        "wires": []
+    },
+    {
+        "id": "40e8a97d10d65e1e",
+        "type": "Service Host",
+        "apiBase": "https://api.openai.com/v1",
+        "secureApiKeyHeaderOrQueryName": "Authorization",
+        "organizationId": "",
+        "name": "OpenAI Auth"
+    }
+]

package/examples/responses/computer-use.json

@@ -0,0 +1,142 @@
+[
+    {
+        "id": "45ed920ef7184d5e",
+        "type": "tab",
+        "label": "Computer Use Example",
+        "disabled": false,
+        "info": "Responses computer-use example.\n\nThis flow teaches the request contract rather than claiming to automate the whole browser loop inside Node-RED.\n\nUse it in two stages:\n1. Send the initial request with `tools: [{ type: \"computer\" }]`.\n2. After the model returns a `computer_call`, edit the placeholder `previous_response_id`, `call_id`, and screenshot location in the second inject node, then send the follow-up request with a `computer_call_output` item.\n\nThe actual screenshot capture and action execution still need external orchestration.",
+        "env": []
+    },
+    {
+        "id": "af8473d616d4c73f",
+        "type": "inject",
+        "z": "45ed920ef7184d5e",
+        "name": "Create Computer Request",
+        "props": [
+            {
+                "p": "ai.model",
+                "v": "gpt-5.4",
+                "vt": "str"
+            },
+            {
+                "p": "ai.tools[0]",
+                "v": "{\"type\":\"computer\"}",
+                "vt": "json"
+            },
+            {
+                "p": "ai.input",
+                "v": "Open the target site, inspect the main page, and tell me what action to take next.",
+                "vt": "str"
+            }
+        ],
+        "repeat": "",
+        "crontab": "",
+        "once": false,
+        "onceDelay": 0.1,
+        "topic": "",
+        "x": 320,
+        "y": 220,
+        "wires": [
+            [
+                "1c6d500f04f70757"
+            ]
+        ]
+    },
+    {
+        "id": "f8116f42c7c6774d",
+        "type": "comment",
+        "z": "45ed920ef7184d5e",
+        "name": "Stage 1: set your API key, then run the initial computer request.",
+        "info": "This example teaches the Responses computer-use payload contract.\n\nBefore running:\n- open the `OpenAI Auth` config node and set a valid API key\n- keep or replace `gpt-5.4` as needed\n- understand that this flow does not capture screenshots or execute actions for you\n\nStage 1:\n- send `Create Computer Request`\n- inspect the debug output for a `computer_call` item and note its `call_id`\n- note the response id you need for `previous_response_id` in stage 2",
+        "x": 480,
+        "y": 160,
+        "wires": []
+    },
+    {
+        "id": "66fb2697d4d37b47",
+        "type": "inject",
+        "z": "45ed920ef7184d5e",
+        "name": "Submit Computer Screenshot (edit placeholders)",
+        "props": [
+            {
+                "p": "ai.model",
+                "v": "gpt-5.4",
+                "vt": "str"
+            },
+            {
+                "p": "ai.previous_response_id",
+                "v": "resp_replace_me",
+                "vt": "str"
+            },
+            {
+                "p": "ai.input[0]",
+                "v": "{\"type\":\"computer_call_output\",\"call_id\":\"call_replace_me\",\"output\":{\"type\":\"computer_screenshot\",\"image_url\":\"https://example.com/replace-with-real-screenshot.png\"}}",
+                "vt": "json"
+            }
+        ],
+        "repeat": "",
+        "crontab": "",
+        "once": false,
+        "onceDelay": 0.1,
+        "topic": "",
+        "x": 390,
+        "y": 300,
+        "wires": [
+            [
+                "1c6d500f04f70757"
+            ]
+        ]
+    },
+    {
+        "id": "57a7d580372bcfd8",
+        "type": "comment",
+        "z": "45ed920ef7184d5e",
+        "name": "Stage 2: replace the placeholders before submitting the screenshot payload.",
+        "info": "Before running `Submit Computer Screenshot (edit placeholders)`:\n- replace `resp_replace_me` with the response id from stage 1\n- replace `call_replace_me` with the `computer_call` id returned by the model\n- replace the placeholder screenshot URL with a real screenshot location the model can read\n\nWhat this flow sends back:\n- `previous_response_id`\n- one `computer_call_output` item\n- one `computer_screenshot` payload inside `output`\n\nExpected result:\n- the model continues the computer-use loop using the screenshot you supplied",
+        "x": 500,
+        "y": 360,
+        "wires": []
+    },
+    {
+        "id": "1c6d500f04f70757",
+        "type": "OpenAI API",
+        "z": "45ed920ef7184d5e",
+        "name": "Create Model Response",
+        "property": "ai",
+        "propertyType": "msg",
+        "service": "c23e0df9b74eae30",
+        "method": "createModelResponse",
+        "x": 660,
+        "y": 260,
+        "wires": [
+            [
+                "1b8c5a26f1517ac6"
+            ]
+        ]
+    },
+    {
+        "id": "1b8c5a26f1517ac6",
+        "type": "debug",
+        "z": "45ed920ef7184d5e",
+        "name": "Computer Use Response",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": false,
+        "complete": "true",
+        "targetType": "full",
+        "statusVal": "",
+        "statusType": "auto",
+        "x": 900,
+        "y": 260,
+        "wires": []
+    },
+    {
+        "id": "c23e0df9b74eae30",
+        "type": "Service Host",
+        "apiBase": "https://api.openai.com/v1",
+        "secureApiKeyHeaderOrQueryName": "Authorization",
+        "organizationId": "",
+        "name": "OpenAI Auth"
+    }
+]