> ## Documentation Index > Fetch the complete documentation index at: https://meganharrisonconsulting.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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. This page is generated from the actual `SKILL.md` file on disk. ## Metadata | Field | Value | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Source group | User Skills | | Source root | `/Users/meganharrison/.agents/skills` | | Relative skill path | `velt-node-sdk-best-practices/SKILL.md` | | Actual file | `/Users/meganharrison/.agents/skills/velt-node-sdk-best-practices/SKILL.md` | | 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. | | Docs overview | [User Skills](/skills/user-skills) | ## Why this exists Use this page when you want to review the real instructions behind a skill without leaving the docs site. The content below is copied from the actual `SKILL.md` file, not rewritten by hand. ## Raw SKILL.md ```md theme={null} --- 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: | 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 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 ```