velt-node-sdk-best-practices

name: velt-node-sdk-best-practices description: Velt Node SDK (@veltdev/node) implementation patterns for Node.js / TypeScript backends. Use whenever the user is writing server-side code that integrates with Velt — initializing VeltSDK, calling sdk.api.* (REST API services like Organizations, Documents, Comment Annotations, etc.) or sdk.selfHosting.* (MongoDB+S3 self-hosted services like Comments, Reactions, Attachments), generating JWT auth tokens for the frontend SDK from Node, configuring MongoDB or AWS S3 for self-hosting, handling the SDK's typed error classes (VeltSDKError, VeltDatabaseError, VeltValidationError, VeltTokenError, VeltApiError), debugging response-envelope mismatches between the two backends, or shipping Node code that talks to Velt in any way. Triggers on any mention of @veltdev/node, VeltSDK, sdk.api, sdk.selfHosting, Velt server-side Node.js, MongoDB-backed Velt storage, or env-var auth (VELT_API_KEY / VELT_AUTH_TOKEN) — even if the user doesn't say "Node SDK" explicitly. license: MIT metadata: author: velt version: "0.2.0"

Velt Node SDK Best Practices

Implementation guide for @veltdev/node. The SDK has two independent backends that share the same VeltSDK instance but differ in initialization requirements, lazy-load patterns, and response shapes — most bugs stem from blurring that line.

When to Apply

• Initializing VeltSDK.initialize(...) in a Node service
• Calling any method under sdk.api.* or sdk.selfHosting.*
• Generating Velt auth tokens server-side (getToken) for the frontend
• Configuring MongoDB or AWS S3 for self-hosting
• Catching and discriminating SDK errors
• Debugging "result.success is undefined" / "is not a function" / "cannot find module mongodb" symptoms

The two-backend mental model

sdk.api.* is a thin typed wrapper over the Velt REST API. No database needed; service instances are available synchronously after init.

sdk.selfHosting.* is a server-side persistence layer that requires database config; service instances are lazy-loaded via await sdk.selfHosting.getXxx() and cached.

The two return different response envelopes — that's the single highest-impact thing to internalize:

Rule Categories

Quick Reference

1. Initialization & lifecycle

• init-dual-mode — Pick the right VeltSDK.initialize shape (REST-only vs self-hosting) and wire await sdk.close() on shutdown

2. sdk.api.* (REST backend)

• api-envelope-and-services — Use the { result: { status, data } } envelope; service-by-service method index for all 17 namespaces; organizationId is required on every method

3. sdk.selfHosting.* (MongoDB + S3)

• selfhost-lazy-load-and-services — Lazy-load with await sdk.selfHosting.getXxx(); flat envelope with success + errorCode; per-service method index for all 7 services
• selfhost-attachments-positional — saveAttachment(request, fileBuffer?, fileName?, mimeType?) mixes a request object with positional file args; getAttachment(orgId, attachmentId) is purely positional

4. Cross-cutting pitfalls

• pitfalls-token-and-envelopes — getToken is positional on both backends; sdk.selfHosting.token is a sync property (no getToken loader); error classes (VeltSDKError + 4 subclasses) discriminate via instanceof

How to Use

Read the relevant rule based on what you're writing. The pitfalls-token-and-envelopes rule is worth reading even for unfamiliar tasks — it captures the highest-density "things that silently do the wrong thing".

Compiled Documents

• AGENTS.md — Compressed index of all rules (start here)
• AGENTS.full.md — Full verbose guide