Velt Node SDK

Velt is an SDK to add collaborative features to your product within minutes. Example: Comments like Figma, Frame.io, Google Docs or Sheets, Recording like Loom, Huddles like Slack, and much more.

@veltdev/node is the official backend SDK for Velt. Use it to power a self-hosted Velt backend or to call Velt's REST APIs directly from any Node.js or TypeScript service.

The SDK exposes two independent backends:

| Backend | Namespace | Use case | | ---------------- | ------------------- | --------------------------------------------------------- | | Self-hosting | sdk.selfHosting.* | Store Velt data in your own MongoDB or PostgreSQL + AWS S3 | | REST API | sdk.api.* | Call Velt's REST APIs directly — no database required |

• Self-hosting (sdk.selfHosting.*) simplifies backend implementation by up to 90%. Pass your DB and storage configs to the SDK, call the relevant method with the raw request payload, and return the response directly to the client.
• REST API (sdk.api.*) provides fully-typed TypeScript request objects across all Velt REST services, returning raw Velt API responses. No database or AWS configuration needed.

Features

With Velt you can add powerful collaboration features to your backend extremely fast:

• Comments like Figma, Frame.io, Google Docs, Sheets and more
• Recording like Loom (audio, video, screen)
• In-app and off-app notifications
• @mentions and assignment
• Presence, Cursors, Live Selection
• Live state sync and multiplayer editing with conflict resolution (CRDT)
• Activities, reactions, access control, and GDPR data tooling
• Workspace, API key, domain, and webhook management
• ... and so much more

Installation

npm install @veltdev/node

The database drivers are optional peer dependencies. Install only what you use:

npm install @veltdev/node                    # REST API only
npm install @veltdev/node mongodb            # + self-hosting on MongoDB
npm install @veltdev/node pg                 # + self-hosting on PostgreSQL
npm install @aws-sdk/client-s3               # only if using S3 for attachments

A database block whose driver is not installed fails at initialize() with the install command (MongoDB support requires 'npm install mongodb' / PostgreSQL support requires 'npm install pg').

Requirements

• Node.js 18+
• TypeScript 5.x (optional — JavaScript is fully supported)
• For self-hosting: MongoDB 6+ (Percona Server or MongoDB Atlas) with mongodb ^6, or PostgreSQL 14+ with pg ^8.16
• @aws-sdk/client-s3 ^3 for S3 attachment uploads (optional)

Quick Start

Initialize the SDK

Self-hosting (MongoDB + optional AWS):

import { VeltSDK } from '@veltdev/node';

const sdk = VeltSDK.initialize({
  database: {
    host: 'localhost:27017',
    username: 'your-username',
    password: 'your-password',
    auth_database: 'admin',
    database_name: 'velt-integration',
  },
  apiKey: 'YOUR_VELT_API_KEY',       // or set VELT_API_KEY
  authToken: 'YOUR_VELT_AUTH_TOKEN', // or set VELT_AUTH_TOKEN
});

Self-hosting on PostgreSQL: only the database block changes; the SDK creates its tables and indexes on first connect (manage_schema: false turns that off):

const sdk = VeltSDK.initialize({
  database: {
    type: 'postgresql',
    connection_string: 'postgresql://user:pass@host:5432/velt',
    sslmode: 'verify-full',              // 'prefer' (default) does not verify the certificate
    sslrootcert: '/path/to/ca.pem',
  },
  apiKey: 'YOUR_VELT_API_KEY',
  authToken: 'YOUR_VELT_AUTH_TOKEN',
});

REST API only (no database needed):

import { VeltSDK } from '@veltdev/node';

const sdk = VeltSDK.initialize({
  apiKey: 'YOUR_VELT_API_KEY',
  authToken: 'YOUR_VELT_AUTH_TOKEN',
});

// All sdk.api.* services are now available
const result = await sdk.api.organizations.getOrganizations({
  organizationIds: ['org-123'],
});

Self-hosting example

Each self-hosting service is loaded asynchronously on first access and cached afterward:

const comments = await sdk.selfHosting.getComments();

const result = await comments.getComments({
  organizationId: 'org-123',
  documentIds: ['doc-1'],
});

REST API example

Each sdk.api.* method takes a single typed request object — pass plain object literals, no class instantiation required:

await sdk.api.commentAnnotations.addCommentAnnotations({
  organizationId: 'org-123',
  documentId: 'doc-1',
  commentAnnotations: [{
    location: { id: 'section-1', locationName: 'Introduction' },
    commentData: [{
      commentText: 'This needs review',
      from: { userId: 'user-1', name: 'John Doe', email: '[email protected]' },
    }],
  }],
});

Minting a user token

Token minting is a call to api.velt.dev and needs no database. It is available as sdk.api.token (recommended) and, unchanged, as sdk.selfHosting.token. Both behave identically:

const result = await sdk.api.token.getToken('org-123', 'user-1', '[email protected]');
// { success: true, data: { token: '...' } }   or   { success: false, error: '...', errorCode: '...' }

Shutdown

Call await sdk.close() during graceful shutdown to release the database connection pool:

await sdk.close();

Documentation

• Read the Node SDK documentation for the full setup guide, configuration reference, and a complete list of sdk.selfHosting.* and sdk.api.* methods with request/response examples.
• Browse the broader Velt documentation for guides and frontend SDK references.

Use cases

• Explore use cases to learn how collaboration could look on your product.
• Figma Template: visualize what collaboration features could look like on your product.

Releases

• See the latest changes.

Security

• Velt is SOC2 Type 2 and HIPAA compliant. Learn more

Community

• X: updates, announcements, and general Velt tips.
• Discord: ask questions and share tips.

License

MIT

Support

For issues and questions, contact [email protected] or visit docs.velt.dev.