langgenius/dify
1
0
Fork 0
mirror of https://github.com/langgenius/dify.git synced 2026-07-20 19:50:06 -04:00
Code Issues 775 Packages Projects Releases 10 Wiki Activity

refactor(sdk): Node.js SDK TypeScript rewrite with full Service API coverage #21231

New Issue
Closed
opened 2026-02-21 20:11:31 -05:00 by yindo · 0 comments
yindo commented 2026-02-21 20:11:31 -05:00
Owner
Copy Link
Copy Source

Originally created by @lyzno1 on GitHub (Dec 23, 2025).

Summary

Refactor and enhance the Node.js SDK (sdks/nodejs-client) to achieve feature parity with the Python SDK and complete coverage of the Dify Service API.

Current State

The existing Node.js SDK has limited coverage and several architectural issues:

  • Partial API coverage: Missing Knowledge Base, Workspace, Annotations, Conversation Variables endpoints
  • No TypeScript source: JavaScript-only with minimal type definitions
  • Inconsistent method placement: CompletionClient.runWorkflow duplicates WorkflowClient
  • Missing streaming support: No SSE parsing helpers for event: lines
  • No error hierarchy: Generic errors without proper mapping (401→AuthenticationError, 429→RateLimitError, etc.)
  • No retry/timeout handling: Missing exponential backoff and rate limit respect
  • Parameter bugs: getConversations uses wrong pagination param, getSuggested sends user in body instead of query

Requirements

1. Complete Service API Coverage

Category Endpoints
App Core /parameters, /meta, /info, /site
Files & Audio /files/upload, /files/{id}/preview, /audio-to-text, /text-to-audio
Chat + Chatflow /chat-messages, /conversations, /messages, conversation variables, annotations
Completion /completion-messages, /completion-messages/{id}/stop
Workflow /workflows/run, /workflows/{id}/run, /workflows/logs, /workflows/tasks/{id}/stop
Knowledge Base Datasets, Documents, Segments, Child Chunks, Metadata, Tags, Hit Testing, RAG Pipeline
Workspace /workspaces/current/models/model-types/{type}

2. TypeScript-First Architecture

src/
├── client/          # Client classes (base, chat, completion, workflow, knowledge-base, workspace)
├── http/            # HTTP layer (client, retry, sse, form-data)
├── types/           # TypeScript interfaces for requests/responses
└── errors/          # Error class hierarchy

3. Configuration Parity with Python SDK

type DifyClientConfig = {
  apiKey: string;
  baseUrl?: string;      // default: https://api.dify.ai/v1
  timeout?: number;      // seconds, default: 60
  maxRetries?: number;   // default: 3
  retryDelay?: number;   // seconds, default: 1
  enableLogging?: boolean;
};

4. Error Handling

Map HTTP errors to typed exceptions:

  • 401 → AuthenticationError
  • 429 → RateLimitError (with retryAfter)
  • 422 → ValidationError
  • 400 (upload) → FileUploadError
  • Network errors → NetworkError
  • Timeout → TimeoutError

5. Streaming Support

  • SSE parser supporting both data: and event: lines
  • AsyncIterable interface for streaming responses
  • Binary streaming for text-to-audio
  • Helper methods: stream.toText(), stream.toReadable()

6. Parameter Validation

  • Required fields validated at method level via ensureNonEmptyString
  • Generic validation for max string length, list/dict sizes
  • Proper user parameter placement (query vs body vs form)

Non-Functional Requirements

  • ESM-only distribution (type: "module")
  • Node.js 18+ support
  • Generated .d.ts type definitions
  • Comprehensive unit tests with mocked HTTP
  • Backward compatibility with deprecation warnings

References

  • Service API: api/controllers/service_api/
Originally created by @lyzno1 on GitHub (Dec 23, 2025). ## Summary Refactor and enhance the Node.js SDK (`sdks/nodejs-client`) to achieve feature parity with the Python SDK and complete coverage of the Dify Service API. ## Current State The existing Node.js SDK has limited coverage and several architectural issues: - **Partial API coverage**: Missing Knowledge Base, Workspace, Annotations, Conversation Variables endpoints - **No TypeScript source**: JavaScript-only with minimal type definitions - **Inconsistent method placement**: `CompletionClient.runWorkflow` duplicates `WorkflowClient` - **Missing streaming support**: No SSE parsing helpers for `event:` lines - **No error hierarchy**: Generic errors without proper mapping (401→AuthenticationError, 429→RateLimitError, etc.) - **No retry/timeout handling**: Missing exponential backoff and rate limit respect - **Parameter bugs**: `getConversations` uses wrong pagination param, `getSuggested` sends user in body instead of query ## Requirements ### 1. Complete Service API Coverage | Category | Endpoints | |----------|-----------| | **App Core** | `/parameters`, `/meta`, `/info`, `/site` | | **Files & Audio** | `/files/upload`, `/files/{id}/preview`, `/audio-to-text`, `/text-to-audio` | | **Chat + Chatflow** | `/chat-messages`, `/conversations`, `/messages`, conversation variables, annotations | | **Completion** | `/completion-messages`, `/completion-messages/{id}/stop` | | **Workflow** | `/workflows/run`, `/workflows/{id}/run`, `/workflows/logs`, `/workflows/tasks/{id}/stop` | | **Knowledge Base** | Datasets, Documents, Segments, Child Chunks, Metadata, Tags, Hit Testing, RAG Pipeline | | **Workspace** | `/workspaces/current/models/model-types/{type}` | ### 2. TypeScript-First Architecture ``` src/ ├── client/ # Client classes (base, chat, completion, workflow, knowledge-base, workspace) ├── http/ # HTTP layer (client, retry, sse, form-data) ├── types/ # TypeScript interfaces for requests/responses └── errors/ # Error class hierarchy ``` ### 3. Configuration Parity with Python SDK ```typescript type DifyClientConfig = { apiKey: string; baseUrl?: string; // default: https://api.dify.ai/v1 timeout?: number; // seconds, default: 60 maxRetries?: number; // default: 3 retryDelay?: number; // seconds, default: 1 enableLogging?: boolean; }; ``` ### 4. Error Handling Map HTTP errors to typed exceptions: - `401` → `AuthenticationError` - `429` → `RateLimitError` (with `retryAfter`) - `422` → `ValidationError` - `400` (upload) → `FileUploadError` - Network errors → `NetworkError` - Timeout → `TimeoutError` ### 5. Streaming Support - SSE parser supporting both `data:` and `event:` lines - `AsyncIterable` interface for streaming responses - Binary streaming for `text-to-audio` - Helper methods: `stream.toText()`, `stream.toReadable()` ### 6. Parameter Validation - Required fields validated at method level via `ensureNonEmptyString` - Generic validation for max string length, list/dict sizes - Proper `user` parameter placement (query vs body vs form) ## Non-Functional Requirements - ESM-only distribution (`type: "module"`) - Node.js 18+ support - Generated `.d.ts` type definitions - Comprehensive unit tests with mocked HTTP - Backward compatibility with deprecation warnings ## References - Service API: `api/controllers/service_api/`
yindo added the 💪 enhancement label 2026-02-21 20:11:31 -05:00
yindo closed this issue 2026-02-21 20:11:31 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Knowledge Pipeline
Proposal
WIP
cloud
dependencies
feat:webapp
good first issue
outdated
performance
pull-request
Mirrored from GitHub Pull Request
 python:uv
refactor
size:L
stale
status: accepting prs
status: blocked
status: in discussion
stt & tts
vulnerablity
web
wont-fix
🌊 feat:workflow
🌚 invalid
🐞 bug
👻 feat:rag
💪 enhancement
📚 documentation
🔨 feat:tools
🙋‍♂️ question
🙏 help wanted
🤔 cant-reproduce
🤖 feat:agent
No Label 💪 enhancement
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langgenius/dify#21231
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?