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.