How do I install the Velt Node Sdk Best Practices skill?

Run npx skillmds@latest add velt-js/velt-node-sdk-best-practices in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Velt Node Sdk Best Practices safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Velt Node Sdk Best Practices?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Velt Node Sdk Best Practices free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

Who published Velt Node Sdk Best Practices?

velt-js (@velt-js) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Velt Node Sdk Best Practices by velt-js

Name: Velt Node Sdk Best Practices
Author: velt-js

Velt Node Sdk Best Practices

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.

velt-js 43a42ed 14 files · 61.8 KB Updated Sep 17, 2026

File contents

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:

Backend	Success envelope	Failure
`sdk.api.*`	`{ result: { status: 'success', message, data, ... } }`	Throws `VeltApiError`
`sdk.selfHosting.*`	`{ success: true, statusCode: 200, data }`	`{ success: false, statusCode, error, errorCode }` (or throws `VeltSDKError` subclass)

Rule Categories

Priority	Category	Impact	Prefix
1	Initialization & lifecycle	CRITICAL	`init-`
2	sdk.api.* (REST backend)	HIGH	`api-`
3	sdk.selfHosting.* (MongoDB + S3)	HIGH	`selfhost-`
4	Cross-cutting pitfalls	MEDIUM	`pitfalls-`

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 18 namespaces; organizationId is required on every method
api-field-allowlist — Pass { filterUnknownFields: true } as the second arg to the activities/commentAnnotations/notifications add/update methods to drop unknown keys before the REST write (opt-in, fail-open); reuse via exported pickKnownFields / filterRequest / FilterSpec

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

---name: velt-node-sdk-best-practicesdescription: 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---# Velt Node SDK Best PracticesImplementation 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:| Backend | Success envelope | Failure ||---|---|---|| `sdk.api.*` | `{ result: { status: 'success', message, data, ... } }` | Throws `VeltApiError` || `sdk.selfHosting.*` | `{ success: true, statusCode: 200, data }` | `{ success: false, statusCode, error, errorCode }` (or throws `VeltSDKError` subclass) |## Rule Categories| Priority | Category | Impact | Prefix ||---|---|---|---|| 1 | Initialization & lifecycle | CRITICAL | `init-` || 2 | sdk.api.* (REST backend) | HIGH | `api-` || 3 | sdk.selfHosting.* (MongoDB + S3) | HIGH | `selfhost-` || 4 | Cross-cutting pitfalls | MEDIUM | `pitfalls-` |## 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 18 namespaces; `organizationId` is required on every method- `api-field-allowlist` — Pass `{ filterUnknownFields: true }` as the second arg to the activities/commentAnnotations/notifications add/update methods to drop unknown keys before the REST write (opt-in, fail-open); reuse via exported `pickKnownFields` / `filterRequest` / `FilterSpec`### 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 UseRead 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

Frequently asked questions