@latenode-connect/sdk-openai 0.0.0-stage → 0.1.0

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/LICENSE ADDED
@@ -0,0 +1,18 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nocode LTD
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
6
+ associated documentation files (the "Software"), to deal in the Software without restriction, including
7
+ without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8
+ copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
9
+ following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be included in all copies or substantial
12
+ portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
15
+ LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
16
+ EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
17
+ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
18
+ USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,119 @@
1
- # Temporary Holding Version
1
+ # Latenode Connect tools for OpenAI and OpenRouter
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ `@latenode-connect/sdk-openai` supports the OpenAI TypeScript SDK 7.57.0 and compatible 7.x
4
+ versions, with both Chat Completions and Responses wire formats.
5
+
6
+ This adapter exposes the shared Connect discovery toolkit. The agent can find
7
+ applications and tools, select an allowed connection, load paginated options,
8
+ request dynamic fields and execute the exact discovered tool version. You do not
9
+ have to preload every application tool into the model context.
10
+
11
+ ## Setup
12
+
13
+ Install the adapter alongside the Connect SDK and OpenAI SDK.
14
+
15
+ ```sh
16
+ pnpm add @latenode-connect/sdk @latenode-connect/sdk-openai openai@7
17
+ ```
18
+
19
+ ```ts
20
+ import OpenAI from 'openai';
21
+ import { ConnectClient } from '@latenode-connect/sdk';
22
+ import { chatTools, dispatchChat } from '@latenode-connect/sdk-openai';
23
+
24
+ const model = new OpenAI({
25
+ apiKey: process.env.OPENROUTER_API_KEY!,
26
+ baseURL: 'https://openrouter.ai/api/v1',
27
+ maxRetries: 0,
28
+ });
29
+ const connect = new ConnectClient({
30
+ apiKey: process.env.CONNECT_API_KEY!,
31
+ });
32
+ const toolkit = connect.user('your-authenticated-user').agentTools({
33
+ apps: ['google_sheets'],
34
+ });
35
+ const result = await model.chat.completions.create({
36
+ model: 'your-tool-calling-model',
37
+ tools: chatTools(toolkit),
38
+ messages: [{ role: 'user', content: 'Read the requested spreadsheet row.' }],
39
+ });
40
+
41
+ const pending = result.choices[0]?.message.tool_calls ?? [];
42
+ // Persist this identity and the complete pending calls before dispatch.
43
+ const invocationId = 'persisted-logical-turn-id';
44
+ for (const call of pending) {
45
+ if (call.type !== 'function') continue;
46
+ const output = await dispatchChat(toolkit, call, { invocationId });
47
+ // Append output and the assistant message to the next model request.
48
+ }
49
+ ```
50
+
51
+ Keep both API keys on your application server. Connect user identity comes from
52
+ your application's authentication. Filters are immutable toolkit limits:
53
+ `apps` uses stable app slugs; omitted filters do not narrow visibility, empty
54
+ `apps` permits no actions, and empty `connectionIds` leaves only no-auth actions.
55
+ These limits do not change the API key's rights outside this toolkit.
56
+
57
+ The adapter never constructs a model client, chooses a model, performs a model
58
+ request or owns the conversation loop. See [the typed example](examples/agent.mts)
59
+ for bounded Chat and Responses loops using public imports.
60
+
61
+ Without a connection ID allowlist, `create_connection_link` returns an expiring URL for an allowed app. The end user opens the URL to authorize their account. Providing any `connectionIds` list disables this tool.
62
+
63
+ ## Responses and streaming
64
+
65
+ Use `responseTools(toolkit)` in `client.responses.create()` and
66
+ `dispatchResponse(toolkit, call, options)` for complete `function_call` output
67
+ items. It returns a native `function_call_output` with the original **call_id**;
68
+ the output item's `id` is a different identifier and must not be substituted.
69
+ Chat outputs use `role: 'tool'` and `tool_call_id` instead.
70
+
71
+ For streaming, the application accumulates Chat argument fragments until the
72
+ completed function call is available. Dispatch calls only from completed SDK
73
+ messages or after accumulating the completed stream, never `delta.tool_calls`
74
+ directly. Some providers retain an extra `index` field on complete calls; that
75
+ field is not proof that a call is partial. The adapter checks required call
76
+ fields and JSON arguments, but cannot infer stream completion from their shape.
77
+ With Responses, dispatch
78
+ complete items from `response.output_item.done` or the final response, not
79
+ `response.function_call_arguments.delta`. Items marked `in_progress` or
80
+ `incomplete` are rejected without execution. Parsing a valid JSON fragment alone
81
+ does not prove the model finished its call.
82
+
83
+ The adapter does not force strict schema mode: capabilities vary across models
84
+ and OpenRouter providers. The shared toolkit validates arguments and access before
85
+ performing Connect requests. Unknown tool names and malformed JSON produce safe
86
+ `{ ok: false, error }` contents. Invalid invocation or call identities throw an
87
+ English configuration error without echoing input. Signals and `timeoutMs` are
88
+ forwarded to the shared toolkit; cancellation of the model request itself remains
89
+ the application's responsibility.
90
+
91
+ ## Results and recovery
92
+
93
+ Tool contents use `{ ok, data | error }`. Completed execution data has its own
94
+ `status`; transport success does not imply successful execution. Large successful
95
+ results may explicitly omit payload from model context while retaining `runId`
96
+ and bounded file references. Read full results through `user.runs.get(runId)`.
97
+
98
+ Persist `invocationId`, the original tool-call ID and full completed arguments
99
+ before dispatch. Reuse them after recovery. The shared SDK derives the same
100
+ idempotency key; changed arguments with the same identity conflict instead of
101
+ silently starting another operation. New logical calls need new identities.
102
+ No dispatcher generates random replacement IDs or automatically retries writes.
103
+
104
+ Replay retains the backend's 24-hour window and requires the same available
105
+ catalog definition. There is no archive fallback for a retired tool/version.
106
+ Never automatically retry failed or unknown writes under a new identity.
107
+
108
+ ## Development
109
+
110
+ ```sh
111
+ pnpm --filter @latenode-connect/sdk-openai... build
112
+ pnpm --filter @latenode-connect/sdk-openai typecheck
113
+ pnpm --filter @latenode-connect/sdk-openai test
114
+ ```
115
+
116
+ Tests use the real OpenAI client against local Chat/Responses HTTP and Connect
117
+ fixtures. They cover discovery, option pagination, dynamic fields, execution,
118
+ streaming, parallel calls, recovery, cancellation and safe failures. They make no
119
+ live model or provider requests.
@@ -0,0 +1,15 @@
1
+ import type { AgentToolkit, RequestOptions } from '@latenode-connect/sdk';
2
+ import type { ChatCompletionFunctionTool, ChatCompletionMessageFunctionToolCall, ChatCompletionToolMessageParam } from 'openai/resources/chat/completions';
3
+ import type { FunctionTool, ResponseFunctionToolCall, ResponseInputItem } from 'openai/resources/responses/responses';
4
+ export interface OpenAIToolOptions extends RequestOptions {
5
+ /** Persist this logical invocation identity with the application's checkpoint. */
6
+ invocationId: string;
7
+ }
8
+ /** Chat Completions definitions. The application owns its OpenAI/OpenRouter client. */
9
+ export declare function chatTools(toolkit: AgentToolkit): ChatCompletionFunctionTool[];
10
+ /** Responses definitions use a different wire format from Chat Completions. */
11
+ export declare function responseTools(toolkit: AgentToolkit): FunctionTool[];
12
+ /** The caller must supply a complete Chat message call, not a streaming fragment. */
13
+ export declare function dispatchChat(toolkit: AgentToolkit, call: ChatCompletionMessageFunctionToolCall, options: OpenAIToolOptions): Promise<ChatCompletionToolMessageParam>;
14
+ /** Dispatch only a complete Responses function call; call_id differs from item id. */
15
+ export declare function dispatchResponse(toolkit: AgentToolkit, call: ResponseFunctionToolCall, options: OpenAIToolOptions): Promise<ResponseInputItem.FunctionCallOutput>;
package/dist/index.mjs ADDED
@@ -0,0 +1,77 @@
1
+ /** Chat Completions definitions. The application owns its OpenAI/OpenRouter client. */
2
+ export function chatTools(toolkit) {
3
+ return toolkit.definitions.map(definition => ({
4
+ type: 'function',
5
+ function: {
6
+ name: definition.name,
7
+ description: definition.description,
8
+ parameters: definition.inputSchema,
9
+ strict: false,
10
+ },
11
+ }));
12
+ }
13
+ /** Responses definitions use a different wire format from Chat Completions. */
14
+ export function responseTools(toolkit) {
15
+ return toolkit.definitions.map(definition => ({
16
+ type: 'function',
17
+ name: definition.name,
18
+ description: definition.description,
19
+ parameters: definition.inputSchema,
20
+ strict: false,
21
+ }));
22
+ }
23
+ function identity(value, name) {
24
+ if (typeof value !== 'string' || value.length === 0 || value.length > 512)
25
+ throw new TypeError(`${name} must be a non-empty string of at most 512 characters`);
26
+ }
27
+ const invalid = () => ({
28
+ ok: false,
29
+ error: { code: 'invalid_arguments' },
30
+ });
31
+ async function dispatch(toolkit, name, argumentsJson, toolCallId, options, complete) {
32
+ identity(options?.invocationId, 'invocationId');
33
+ identity(toolCallId, 'toolCallId');
34
+ if (!complete ||
35
+ typeof name !== 'string' ||
36
+ !toolkit.definitions.some(definition => definition.name === name) ||
37
+ typeof argumentsJson !== 'string' ||
38
+ argumentsJson.length > 10 * 1024 * 1024)
39
+ return JSON.stringify(invalid());
40
+ let input;
41
+ try {
42
+ input = JSON.parse(argumentsJson);
43
+ }
44
+ catch {
45
+ return JSON.stringify(invalid());
46
+ }
47
+ try {
48
+ const result = await toolkit.call(name, input, {
49
+ invocationId: options.invocationId,
50
+ toolCallId,
51
+ ...(options.signal === undefined ? {} : { signal: options.signal }),
52
+ ...(options.timeoutMs === undefined
53
+ ? {}
54
+ : { timeoutMs: options.timeoutMs }),
55
+ });
56
+ return JSON.stringify(result);
57
+ }
58
+ catch {
59
+ // Never turn an unexpected application exception into model-visible details.
60
+ return JSON.stringify({
61
+ ok: false,
62
+ error: { code: 'tool_execution_failed' },
63
+ });
64
+ }
65
+ }
66
+ /** The caller must supply a complete Chat message call, not a streaming fragment. */
67
+ export async function dispatchChat(toolkit, call, options) {
68
+ const content = await dispatch(toolkit, call?.function?.name, call?.function?.arguments, call?.id, options, call?.type === 'function');
69
+ return { role: 'tool', tool_call_id: call.id, content };
70
+ }
71
+ /** Dispatch only a complete Responses function call; call_id differs from item id. */
72
+ export async function dispatchResponse(toolkit, call, options) {
73
+ const output = await dispatch(toolkit, call?.name, call?.arguments, call?.call_id, options, call?.type === 'function_call' &&
74
+ (call.status === undefined || call.status === 'completed'));
75
+ return { type: 'function_call_output', call_id: call.call_id, output };
76
+ }
77
+ //# sourceMappingURL=index.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"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"}
@@ -0,0 +1,93 @@
1
+ import type OpenAI from 'openai';
2
+ import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions';
3
+ import type { ResponseInputItem } from 'openai/resources/responses/responses';
4
+ import type { AgentToolkit } from '@latenode-connect/sdk';
5
+ import {
6
+ chatTools,
7
+ responseTools,
8
+ dispatchChat,
9
+ dispatchResponse,
10
+ } from '@latenode-connect/sdk-openai';
11
+
12
+ /** The caller supplies the OpenAI/OpenRouter client and a persisted invocation identity. */
13
+ export async function runChat(
14
+ client: OpenAI,
15
+ toolkit: AgentToolkit,
16
+ options: {
17
+ model: string;
18
+ prompt: string;
19
+ invocationId: string;
20
+ signal?: AbortSignal;
21
+ },
22
+ ) {
23
+ const messages: ChatCompletionMessageParam[] = [
24
+ { role: 'user', content: options.prompt },
25
+ ];
26
+ for (let step = 0; step < 12; step++) {
27
+ const result = await client.chat.completions.create(
28
+ {
29
+ model: options.model,
30
+ tools: chatTools(toolkit),
31
+ messages,
32
+ max_completion_tokens: 1024,
33
+ },
34
+ options.signal === undefined ? {} : { signal: options.signal },
35
+ );
36
+ const choice = result.choices[0];
37
+ if (!choice || !['stop', 'tool_calls'].includes(choice.finish_reason))
38
+ throw new Error('The model did not complete its response');
39
+ const message = choice.message;
40
+ messages.push(message);
41
+ if (!message.tool_calls?.length) return message.content;
42
+ // Persist the pending calls and invocationId in your durable checkpoint here.
43
+ for (const call of message.tool_calls) {
44
+ if (call.type !== 'function')
45
+ throw new Error('Unsupported tool call type');
46
+ messages.push(await dispatchChat(toolkit, call, options));
47
+ }
48
+ }
49
+ throw new Error('Agent step limit reached');
50
+ }
51
+
52
+ export async function runResponses(
53
+ client: OpenAI,
54
+ toolkit: AgentToolkit,
55
+ options: {
56
+ model: string;
57
+ prompt: string;
58
+ invocationId: string;
59
+ signal?: AbortSignal;
60
+ },
61
+ ) {
62
+ const input: ResponseInputItem[] = [
63
+ { role: 'user', content: options.prompt },
64
+ ];
65
+ for (let step = 0; step < 12; step++) {
66
+ const result = await client.responses.create(
67
+ {
68
+ model: options.model,
69
+ tools: responseTools(toolkit),
70
+ input,
71
+ max_output_tokens: 1024,
72
+ },
73
+ options.signal === undefined ? {} : { signal: options.signal },
74
+ );
75
+ if (result.status !== 'completed')
76
+ throw new Error('The model did not complete its response');
77
+ for (const item of result.output) {
78
+ if (
79
+ item.type === 'message' ||
80
+ item.type === 'function_call' ||
81
+ item.type === 'reasoning'
82
+ )
83
+ input.push(item);
84
+ else throw new Error('Unsupported response output type');
85
+ }
86
+ const calls = result.output.filter(item => item.type === 'function_call');
87
+ if (!calls.length) return result.output_text;
88
+ // Persist these complete calls and invocationId before any dispatch.
89
+ for (const call of calls)
90
+ input.push(await dispatchResponse(toolkit, call, options));
91
+ }
92
+ throw new Error('Agent step limit reached');
93
+ }
package/package.json CHANGED
@@ -1,6 +1,41 @@
1
1
  {
2
2
  "name": "@latenode-connect/sdk-openai",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
4
+ "type": "module",
5
+ "exports": {
6
+ ".": {
7
+ "types": "./dist/index.d.mts",
8
+ "import": "./dist/index.mjs"
9
+ }
10
+ },
11
+ "files": [
12
+ "dist",
13
+ "examples"
14
+ ],
15
+ "dependencies": {
16
+ "@latenode-connect/sdk": "0.1.0"
17
+ },
18
+ "peerDependencies": {
19
+ "openai": "^7.57.0"
20
+ },
21
+ "devDependencies": {
22
+ "openai": "7.57.0",
23
+ "tsx": "4.23.15",
24
+ "typescript": "5.8.3"
25
+ },
26
+ "license": "MIT",
27
+ "repository": {
28
+ "type": "git",
29
+ "url": "git+https://github.com/latenode-com/latenode-connect-sdk.git",
30
+ "directory": "connect/sdk-openai"
31
+ },
32
+ "publishConfig": {
33
+ "access": "public",
34
+ "registry": "https://registry.npmjs.org/"
35
+ },
36
+ "scripts": {
37
+ "build": "tsc -p tsconfig.json",
38
+ "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p test/types/tsconfig.json",
39
+ "test": "node --import tsx --test test/*.test.mjs"
40
+ }
6
41
  }