Node SDK for self-hosting and REST API calls

Overview

The Velt Node SDK exposes two independent backends:

Backend	Namespace	Use case
Self-hosting	`sdk.selfHosting.*`	Store Velt data in your own MongoDB or PostgreSQL, plus AWS S3 for attachments
REST API	`sdk.api.*`	Call Velt’s REST APIs directly from your backend

Self-hosting backend (sdk.selfHosting.*) simplifies backend implementation by 90%. Instead of writing custom database queries and storage logic, you:

Pass your DB and storage configs to the SDK
Call the relevant SDK method with the raw request payload
Return the resulting response directly to the client

REST API backend (sdk.api.*) provides parity with Velt’s REST APIs. 19 services, fully-typed TypeScript request objects, and raw Velt API responses. No database or AWS configuration needed.

Installation

Install the driver for the database you self-host on. The core package carries no database driver.

npm install @veltdev/node                 # REST API backend 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 you use S3 for attachments
npm install jose@^5                       # only for the built-in JWT/JWKS verifyToken path

A database config whose driver is not installed fails at initialize() with the command to run, for example MongoDB support requires 'npm install mongodb' or PostgreSQL support requires 'npm install pg'.

Upgrading from 1.x: version 2.0.0 changes these behaviors.

The database driver is checked at initialize(). A config with a database block fails at startup when its driver (mongodb or pg) is not installed. If you only call sdk.api.*, remove the database block instead.
saveAttachment stores a closed set of fields: attachmentId, file (the URL), name, mimeType, and metadata (organizationId, documentId, folderId, attachmentId, commentAnnotationId, apiKey). Other fields, a top-level url, and null metadata keys are no longer stored. A save without a file URL or file data returns 400.
An empty organizationId in getComments, getReactions, getRecorderAnnotations, and getNotifications returns 400 with errorCode: 'INVALID_INPUT'.
An unknown database.type throws at initialize(). A second SDK instance pointed at a different database without await sdk.close() throws at its first sdk.selfHosting.* call.

Requirements

Node.js 18+
TypeScript 5.x (optional; JavaScript is fully supported)
For self-hosting, one of:
- MongoDB 6+ (Percona Server or MongoDB Atlas) with mongodb ^6
- PostgreSQL 14+ with pg ^8.16
@aws-sdk/client-s3 ^3 and jose ^5 (for verifyToken) as optional peer dependencies

Quick Start

Initialize the SDK

Self-hosting
REST API

Self-hosting initialization (MongoDB or PostgreSQL, plus optional AWS S3):

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

const sdk = VeltSDK.initialize({
  database: {
    // MongoDB (default type)
    connection_string: 'mongodb+srv://user:pass@cluster.mongodb.net/velt-db',

    // PostgreSQL: set the type and use a PostgreSQL connection string instead
    // type: 'postgresql',
    // connection_string: 'postgresql://user:pass@host:5432/velt',
  },
  apiKey: 'YOUR_VELT_API_KEY',
  authToken: 'YOUR_VELT_AUTH_TOKEN'
});

REST API initialization needs no database block:

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'] });

Set VELT_API_KEY and VELT_AUTH_TOKEN environment variables as an alternative to passing credentials in the config object. On an SDK initialized without a database block, sdk.selfHosting.* methods throw a VeltDatabaseError saying a database block is required.

Shutdown

Call await sdk.close() when your process exits to release the database connection pool.

Configuration

Environment Variables

Variable	Config key equivalent	Purpose
`VELT_API_KEY`	`apiKey`	Velt API key for authenticating REST API calls
`VELT_AUTH_TOKEN`	`authToken`	Velt auth token for authenticating REST API calls
`VELT_WORKSPACE_ID`	—	Default workspace ID for workspace-scoped operations
`VELT_WORKSPACE_AUTH_TOKEN`	—	Auth token scoped to a specific workspace
`AWS_ACCESS_KEY_ID`	—	AWS access key for S3 attachments
`AWS_SECRET_ACCESS_KEY`	—	AWS secret key for S3 attachments
`AWS_REGION`	—	AWS region for S3
`AWS_S3_BUCKET_NAME`	—	S3 bucket name for attachments
`AWS_S3_ENDPOINT_URL`	—	Custom S3 endpoint (e.g., for MinIO)

Self-Hosting Configuration

Database
AWS (Attachments)
Complete Example
Resolver Auth

Configure the database that stores comments, reactions, and user data. type selects the backend: mongodb (default) or postgresql. Every sdk.selfHosting.* method behaves the same on both.

const sdk = VeltSDK.initialize({
  database: {
    // Option 1: Connection string (the database name comes from its path)
    connection_string: 'mongodb+srv://user:pass@cluster.mongodb.net/velt-db',

    // Option 2: Individual components
    // host: 'localhost:27017',
    // username: 'your-username',
    // password: 'your-password',
    // auth_database: 'admin',
    // database_name: 'velt-db',

    // Optional (defaults shown)
    // type: 'mongodb',
    // use_srv: true,           // use mongodb+srv:// (auto-detected for *.mongodb.net hosts)
    // pool_min_size: 1,
    // pool_max_size: 5,
  }
});

const sdk = VeltSDK.initialize({
  database: {
    type: 'postgresql',
    // Option 1: Connection string (URI or libpq key/value form)
    connection_string: 'postgresql://user:pass@host:5432/velt',

    // Option 2: Individual components
    // host: 'host',            // may include the port, for example 'host:5433'
    // port: 5432,
    // username: 'your-username',
    // password: 'your-password',
    // database_name: 'velt',

    // Optional (defaults shown)
    // schema: 'public',
    // sslmode: 'prefer',       // use 'verify-full' with sslrootcert for remote databases
    // sslrootcert: undefined,  // path to the CA certificate file
    // connect_timeout: 10,     // seconds
    // application_name: 'velt-node/<version>',
    // pool_min_size: 1,
    // pool_max_size: 5,
    // pool_timeout: 10,        // seconds a query waits for a pooled connection
    // manage_schema: true,
    // connection_options: {},  // extra connection parameters passed to node-postgres
  }
});

database_name overrides the database named in connection_string on both backends. pool_min_size and pool_max_size apply to both and are validated at initialize().How PostgreSQL storage works

One table per collection (comment_annotations, reaction_annotations, recorder_annotations, notifications, activities, attachments, users) with a single JSONB data column that holds the document, plus expression indexes on the fields the SDK queries. The collections option renames these tables.
On first connection the SDK creates the schema, tables, and indexes (manage_schema: true). The role needs CREATE on the schema. Concurrent application starts coordinate through a per-schema advisory lock, so they do not race; a process that waits more than 60 seconds skips setup and logs a warning.
For locked-down roles set manage_schema: false and apply the DDL yourself. Generate it for your exact config and hand it to a migration role:

import { Config, postgresSchemaSql } from '@veltdev/node';

console.log(postgresSchemaSql(new Config({ database: { type: 'postgresql', connection_string: 'postgresql://...' } })));

schema is the PostgreSQL schema that holds the tables. It is unrelated to the user_schema option, which maps user fields.
sslmode follows libpq names: disable, allow, prefer, require, verify-ca, verify-full. In Node, prefer (the default) connects without TLS, because node-postgres cannot fall back from TLS to plaintext. require encrypts without verifying the certificate (it verifies the CA when you set sslrootcert), and verify-ca and verify-full verify it. An unknown sslmode fails at initialize(). For any database that is not on the same host, set sslmode: 'verify-full' with sslrootcert: '/path/to/ca.pem'.
Each process opens its own connection pool, so a Node cluster, PM2, or several containers open one pool per worker.
The SDK does not migrate data between MongoDB and PostgreSQL.

Configure AWS S3 for storing file attachments. Alternatively, set the AWS environment variables listed above.

const sdk = VeltSDK.initialize({
  database: {
    host: 'localhost:27017',
    username: 'your-username',
    password: 'your-password',
    auth_database: 'admin',
    database_name: 'velt-db',
  },
  // AWS credentials can also be provided via environment variables
  apiKey: 'YOUR_VELT_API_KEY',
  authToken: 'YOUR_VELT_AUTH_TOKEN'
});

Full configuration with database and credentials. For PostgreSQL, replace the database block with { type: 'postgresql', connection_string: 'postgresql://user:pass@host:5432/velt' }.

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-db',
  },
  apiKey: 'YOUR_VELT_API_KEY',
  authToken: 'YOUR_VELT_AUTH_TOKEN'
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  await sdk.close();
  process.exit(0);
});

Configure resolverAuth to verify the credential the Velt frontend forwards to endpoint-based resolvers. See verifyToken for the full reference, error codes, and security guarantees.

const sdk = VeltSDK.initialize({
  database: {
    host: 'localhost:27017',
    username: 'your-username',
    password: 'your-password',
    auth_database: 'admin',
    database_name: 'velt-db',
  },
  apiKey: 'YOUR_VELT_API_KEY',
  authToken: 'YOUR_VELT_AUTH_TOKEN',
  resolverAuth: {
    jwt: { algorithms: ['RS256'], jwksUrl: 'https://your-idp.example.com/.well-known/jwks.json' },
    // or: verify: async (token, headers) => claims
  },
});

Self-Hosting Backend

Each self-hosting service is loaded asynchronously on first access via await sdk.selfHosting.getXxx(). The service is cached after the first call. await sdk.selfHosting.database returns the connected DatabaseAdapter: the raw adapter for the configured database (MongoDBAdapter or PostgresAdapter), with find, findOne, insertOne, updateOne, updateMany, deleteOne, and deleteMany. The first access connects and creates indexes; later accesses return the same adapter. Use it for a readiness check or to write data the resolvers do not write, such as seeding users. Pass collection names as configured in collections. On PostgreSQL the adapter accepts the query operators the SDK itself uses: equality, $in, $nin, $eq, $ne, $exists, and top-level $and and $or.

const db = await sdk.selfHosting.database;
await db.insertOne('users', { userId: 'user-1', name: 'John Doe', email: 'john@example.com' });

Comments

Access via await sdk.selfHosting.getComments().

`getComments`

Fetches comments for a document from your database.
Params: GetCommentsRequest (SH)
Returns: VeltSelfHostingResponse

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

Response

{
  success: true,
  statusCode: 200,
  data: { /* comment annotations keyed by annotationId */ }
}

`saveComments`

Saves (creates or updates) comment annotations to your database.
Params: SaveCommentsRequest (SH)
Returns: VeltSelfHostingResponse

const commentsService = await sdk.selfHosting.getComments();
const result = await commentsService.saveComments({
  metadata: { organizationId: 'org-123', documentId: 'doc-1' },
  commentAnnotation: {
    'annotation-1': {
      annotationId: 'annotation-1',
      comments: { '123456': { commentId: '123456', commentText: 'Hello' } },
      metadata: {},
    },
  },
});

Response

{ success: true, statusCode: 200, data: { saved: true } }

Resolver contract: When saveComments runs as a save-resolver handler, the inbound event may be a ResolverActions or a CommentResolverSaveEvent member (or a raw string), and the request may include targetComment?: PartialComment — the comment the action occurred on (request context only, never persisted). See SaveCommentResolverRequest.

`deleteComment`

Deletes a single comment annotation from your database.
Params: DeleteCommentRequest (SH)
Returns: VeltSelfHostingResponse

const commentsService = await sdk.selfHosting.getComments();
const result = await commentsService.deleteComment({
  commentAnnotationId: 'annotation-1',
  metadata: { organizationId: 'org-123' },
});

Response

{ success: true, statusCode: 200, data: { deleted: true } }

Reactions

Access via await sdk.selfHosting.getReactions().

`getReactions`

Fetches reactions for a document from your database.
Params: GetReactionsRequest (SH)
Returns: VeltSelfHostingResponse

const reactionsService = await sdk.selfHosting.getReactions();
const result = await reactionsService.getReactions({
  organizationId: 'org-123',
  documentIds: ['doc-1'],
});

Response

{ success: true, statusCode: 200, data: { /* reaction annotations */ } }

`saveReactions`

Persists reactions to your database.
Params: SaveReactionsRequest (SH)
Returns: VeltSelfHostingResponse
The reacting user is set via from (renamed from user in v1.0.5, matching the frontend PartialReactionAnnotation.from).

const reactionsService = await sdk.selfHosting.getReactions();
const result = await reactionsService.saveReactions({
  metadata: { organizationId: 'org-123', documentId: 'doc-1' },
  reactionAnnotation: {
    'reaction-1': { annotationId: 'reaction-1', icon: 'thumbsup', from: { userId: 'u-1' }, metadata: {} },
  },
});

Response

{ success: true, statusCode: 200, data: { saved: true } }

`deleteReaction`

Deletes a single reaction from your database.
Params: DeleteReactionRequest (SH)
Returns: VeltSelfHostingResponse

const reactionsService = await sdk.selfHosting.getReactions();
const result = await reactionsService.deleteReaction({
  reactionAnnotationId: 'reaction-1',
  metadata: { organizationId: 'org-123' },
});

Response

{ success: true, statusCode: 200, data: { deleted: true } }

Attachments

Access via await sdk.selfHosting.getAttachments().

`getAttachment`

Fetches an attachment record by organization and attachment ID.
Params: positional — organizationId (string), attachmentId (number)
Returns: VeltSelfHostingResponse

const attachmentsService = await sdk.selfHosting.getAttachments();
const result = await attachmentsService.getAttachment('org-123', 12345);

Response

{
  success: true,
  statusCode: 200,
  data: {
    attachmentId: 12345,
    file: 'https://s3.amazonaws.com/...',
    name: 'document.pdf',
    mimeType: 'application/pdf',
    metadata: { organizationId: 'org-123', documentId: 'doc-1' }
  }
}

`saveAttachment`

Persists attachment metadata, optionally uploading the file body to S3.
Params: SaveAttachmentRequest (SH) plus optional positional fileData (Buffer), fileName (string), mimeType (string)
Returns: VeltSelfHostingResponse

const attachmentsService = await sdk.selfHosting.getAttachments();
const result = await attachmentsService.saveAttachment(
  {
    metadata: { organizationId: 'org-123', documentId: 'doc-1' },
    attachment: {
      attachmentId: 12345,
      name: 'document.pdf',
      mimeType: 'application/pdf',
    },
  },
  fileBuffer,        // optional Buffer for S3 upload
  'document.pdf',    // optional
  'application/pdf'  // optional
);

Response

{ success: true, statusCode: 200, data: { url: 'https://s3.amazonaws.com/...' } }

`deleteAttachment`

Deletes an attachment record (and S3 object, if applicable).
Params: DeleteAttachmentRequest (SH)
Returns: VeltSelfHostingResponse

const attachmentsService = await sdk.selfHosting.getAttachments();
const result = await attachmentsService.deleteAttachment({
  attachmentId: 12345,
  metadata: { organizationId: 'org-123' },
});

Response

{ success: true, statusCode: 200, data: { deleted: true } }

Users

Access via await sdk.selfHosting.getUsers().

`getUsers`

Fetches users from your database.
Params: GetUsersSelfHostingRequest (SH)
Returns: VeltSelfHostingResponse

const usersService = await sdk.selfHosting.getUsers();
const result = await usersService.getUsers({
  organizationId: 'org-123',
  userIds: ['user-1'],
});

Response

{
  success: true,
  statusCode: 200,
  data: [{ userId: 'user-1', name: 'John Doe', email: 'john@example.com' }]
}

`resolveUserIdsByEmail`

Resolves a list of email addresses to their user IDs. Backs the frontend’s anonymous-user data provider.
Params: ResolveUserIdsByEmailRequest
Returns: VeltSelfHostingResponse

const usersService = await sdk.selfHosting.getUsers();
const result = await usersService.resolveUserIdsByEmail({
  organizationId: 'org-123',
  emails: ['alice@example.com', 'bob@example.com'],
});

Custom user_schema field mappings are honoured. Repeated addresses are de-duplicated and empty entries are dropped. Like getUsers, the lookup does not filter by organization. Response data is a map of email to user ID. Addresses that do not match a user are absent from the map:

{
  success: true,
  statusCode: 200,
  data: { 'alice@example.com': 'user-1', 'bob@example.com': 'user-2' }
}

Recorder

Access via await sdk.selfHosting.getRecorder().

`getRecorderAnnotations`

Fetches recorder annotations from your database.
Params: GetRecorderAnnotationsRequest (SH)
Returns: VeltSelfHostingResponse

const recorderService = await sdk.selfHosting.getRecorder();
const result = await recorderService.getRecorderAnnotations({
  organizationId: 'org-123',
  documentIds: ['doc-1'],
});

Response

{ success: true, statusCode: 200, data: { /* recorder annotations */ } }

`saveRecorderAnnotation`

Saves a single recorder annotation.
Params: SaveRecorderAnnotationRequest (SH)
Returns: VeltSelfHostingResponse

const recorderService = await sdk.selfHosting.getRecorder();
const result = await recorderService.saveRecorderAnnotation({
  metadata: { organizationId: 'org-123', documentId: 'doc-1' },
  recorderAnnotation: { annotationId: 'rec-1', metadata: {} },
});

Response

{ success: true, statusCode: 200, data: { saved: true } }

`deleteRecorderAnnotation`

Deletes a recorder annotation.
Params: DeleteRecorderAnnotationRequest (SH)
Returns: VeltSelfHostingResponse

const recorderService = await sdk.selfHosting.getRecorder();
const result = await recorderService.deleteRecorderAnnotation({
  recorderAnnotationId: 'rec-1',
  metadata: { organizationId: 'org-123' },
});

Response

{ success: true, statusCode: 200, data: { deleted: true } }

Notifications

Access via await sdk.selfHosting.getNotifications().

`getNotifications`

Fetches notifications for a user from your database.
Params: GetNotificationsSelfHostingRequest (SH)
Returns: VeltSelfHostingResponse

const notificationsService = await sdk.selfHosting.getNotifications();
const result = await notificationsService.getNotifications({
  organizationId: 'org-123',
  userId: 'user-1',
});

Response

{ success: true, statusCode: 200, data: [/* notifications */] }

`saveNotifications`

Persists one or more notifications to your database.
Params: SaveNotificationsRequest (SH)
Returns: VeltSelfHostingResponse

const notificationsService = await sdk.selfHosting.getNotifications();
await notificationsService.saveNotifications({
  metadata: { organizationId: 'org-123', documentId: 'doc-1' },
  notifications: [{ id: 'n-1', actionUser: { userId: 'user-1' }, displayBodyMessage: 'Hello' }],
});

Response

{ success: true, statusCode: 200, data: { saved: true } }

`deleteNotification`

Deletes a notification from your database.
Params: DeleteNotificationRequest (SH)
Returns: VeltSelfHostingResponse

const notificationsService = await sdk.selfHosting.getNotifications();
await notificationsService.deleteNotification({
  notificationId: 'n-1',
  metadata: { organizationId: 'org-123', userId: 'user-1' },
});

Response

{ success: true, statusCode: 200, data: { deleted: true } }

Activities

Access via await sdk.selfHosting.getActivities().

`getActivities`

Fetches activity logs from your database.
Params: GetActivitiesSelfHostingRequest (SH)
Returns: VeltSelfHostingResponse

const activitiesService = await sdk.selfHosting.getActivities();
const result = await activitiesService.getActivities({
  organizationId: 'org-123',
  documentId: 'doc-1',
});

Response

{ success: true, statusCode: 200, data: [/* activities */] }

`saveActivities`

Persists activity log entries to your database.
Params: SaveActivitiesRequest (SH)
Returns: VeltSelfHostingResponse

const activitiesService = await sdk.selfHosting.getActivities();
await activitiesService.saveActivities({
  metadata: { organizationId: 'org-123', documentId: 'doc-1' },
  activities: [{ id: 'activity-1', featureType: 'comment', actionType: 'comment.add' }],
});

Response

{ success: true, statusCode: 200, data: { saved: true } }

verifyToken

sdk.selfHosting.verifyToken verifies the auth credential the Velt frontend forwards to endpoint-based resolvers. It is database-free (it does not open or query MongoDB), fail-closed (every error path returns { verified: false }, never throws), and authentication only (claims are returned verbatim; it makes no authorization decision).

Optional dependency: npm install jose@^5 (optional peerDependency, pinned ^5 for Node 18 — jose v6 needs the WebCrypto global absent on Node 18). If jose is missing and the built-in JWT path is used, verifyToken returns { verified: false, errorCode: 'DEPENDENCY_MISSING' }. The custom verify callback path needs no dependency.

Configuration

Configure resolverAuth on VeltSDK.initialize. Provide the built-in jwt path, a custom verify callback, or both. When both are set, the custom callback takes priority.

JWT / JWKS
Custom verify callback

const sdk = VeltSDK.initialize({
  database: {
    host: 'localhost:27017',
    username: 'your-username',
    password: 'your-password',
    auth_database: 'admin',
    database_name: 'velt-db',
  },
  apiKey: 'YOUR_VELT_API_KEY',
  authToken: 'YOUR_VELT_AUTH_TOKEN',
  resolverAuth: {
    jwt: {
      algorithms: ['RS256'],        // REQUIRED — algorithm allowlist (pinning)
      jwksUrl: 'https://your-idp.example.com/.well-known/jwks.json',
      // publicKey: '-----BEGIN PUBLIC KEY-----\n...',  // OR a static PEM
      // secret: 'hs256-shared-secret',                 // OR an HMAC secret for HS*
      issuer: 'https://your-idp.example.com/',
      audience: 'your-api-audience',
      leeway: 5,                    // clock tolerance in seconds
      require: ['exp'],             // required claims
    },
    header: 'Authorization',        // default
    scheme: 'Bearer',              // default
  },
});

const sdk = VeltSDK.initialize({
  database: {
    host: 'localhost:27017',
    username: 'your-username',
    password: 'your-password',
    auth_database: 'admin',
    database_name: 'velt-db',
  },
  apiKey: 'YOUR_VELT_API_KEY',
  authToken: 'YOUR_VELT_AUTH_TOKEN',
  resolverAuth: {
    verify: async (token, headers) => {
      // Validate the token yourself; return the claims, or a falsy value to fail closed.
      const claims = await myValidate(token);
      return claims; // { sub: 'user-1', ... }
    },
    header: 'Authorization',
    scheme: 'Bearer',
  },
});

Usage

Call verifyToken from your endpoint-based resolver route, then branch on result.verified.

const result = await sdk.selfHosting.verifyToken({ headers: request.headers });

if (!result.verified) {
  // result.error is a generic, code-based message; result.errorCode is machine-readable
  return response.status(401).json({ error: result.error, code: result.errorCode });
}

const userId = result.claims?.sub;

Per-call options override the configured resolverAuth (the jwt block is deep-merged):

// Pass a raw token directly instead of headers
await sdk.selfHosting.verifyToken({ token: rawToken });

// Override a single jwt option for this call (deep-merged with configured jwt)
await sdk.selfHosting.verifyToken({ headers: request.headers, jwt: { leeway: 30 } });

Signature

verifyToken(
  options?: {
    headers?: Record<string, string | string[] | undefined> | Headers | Iterable<[string, string]>;
    token?: string;
  } & Partial<ResolverAuthConfig>
) => Promise<VerifyTokenResult>

Params: inline options object with headers, token, and per-call ResolverAuthConfig overrides. This parameter shape is not exported as a named SDK type.
Returns: VerifyTokenResult

The verification logic is implemented by the ResolverAuthService class (also exported from @veltdev/node) for advanced callers who need to construct it directly; sdk.selfHosting.verifyToken is the standard entry point.

Error codes

On failure, result.errorCode is one of the ResolverAuthErrorCode values (also exported as the readonly string[] const RESOLVER_AUTH_ERROR_CODES).

Code	When
`NOT_CONFIGURED`	Neither `jwt` nor a `verify` callback is configured.
`MISSING_TOKEN`	No token found in headers, or wrong scheme.
`EXPIRED`	JWT `exp` claim has passed (beyond `leeway`).
`INVALID_SIGNATURE`	Signature verification failed, or malformed token.
`CLAIM_MISMATCH`	Configured `issuer`/`audience` wrong or absent; or a required claim is missing.
`ALGORITHM_NOT_ALLOWED`	`alg=none`; algorithm outside the allowlist; mixed symmetric+asymmetric allowlist; missing allowlist.
`KEY_RESOLUTION_FAILED`	No usable key; JWKS URL is not HTTPS; JWKS fetch failed or returned non-2xx; redirect downgrade detected.
`DEPENDENCY_MISSING`	Built-in JWT path used but `jose` is not installed.
`VERIFICATION_FAILED`	Custom callback threw or returned falsy; unexpected internal error (fail-closed catch-all).

Security guarantees

alg=none is always rejected, even if present in the allowlist.
Mixed symmetric+asymmetric allowlists are refused (prevents HS/RS confusion).
A PEM placed in jwt.secret is refused.
JWKS is fetched only over HTTPS — http is rejected pre-fetch, and a redirect downgrade is rejected.
JWKS responses are cached per URL with a 5-minute TTL (not per kid).
The token-header alg is checked against the allowlist before any JWKS fetch.
The error field is generic and code-based — it never contains the token or secret.

REST API Backend

The sdk.api.* namespace gives you parity with Velt’s REST APIs across 19 services, including token generation with sdk.api.accessControl.generateToken. Each method takes a fully-typed TypeScript request object and returns the raw Velt API response. You only need apiKey and authToken; initialize without a database block. Every sdk.api.* method requires an organizationId in its request payload. Velt enforces data isolation per-organization server-side.

Field Allowlist

The REST add/update methods on activities, commentAnnotations, and notifications accept an optional second argument, FieldFilterOptions. Pass { filterUnknownFields: true } to narrow the request to exactly the fields the corresponding Velt backend endpoint accepts. See the note at the top of each service section for the behavior summary; the per-endpoint field lists are below.

interface FieldFilterOptions {
  /** When true, narrow the request to only the fields the Velt backend endpoint
   *  accepts, silently dropping unknown keys. Fail-open. Defaults to false. */
  filterUnknownFields?: boolean;
}

Exported filter utilities

The field-allowlist module is exported from @veltdev/node so advanced callers can reuse the same logic.

// Functions
pickKnownFields<T extends object>(data: T, keys: readonly string[]): Partial<T>;
filterRequest<T extends object>(request: T, spec: FilterSpec): T;

// Types
interface FilterSpec {
  keys: readonly string[];              // allowed top-level keys at this level (everything else dropped)
  arrays?: Record<string, FilterSpec>;  // known array-of-object fields, filtered per item
  objects?: Record<string, FilterSpec>; // known single-object fields, filtered recursively
}

pickKnownFields(data, keys) — keeps only own-enumerable keys present in keys; values kept by reference (no recursion); non-object/array/null inputs returned unchanged.
filterRequest(request, spec) — applies a FilterSpec recursively; never mutates input; fail-open (returns the original request on any error).
Eight per-method specs are exported: ADD_ACTIVITIES_SPEC, UPDATE_ACTIVITIES_SPEC, ADD_COMMENT_ANNOTATIONS_SPEC, UPDATE_COMMENT_ANNOTATIONS_SPEC, ADD_COMMENTS_SPEC, UPDATE_COMMENTS_SPEC, ADD_NOTIFICATIONS_SPEC, UPDATE_NOTIFICATIONS_SPEC.

Allowlisted fields per endpoint

When filterUnknownFields: true, only these keys survive (unknown keys dropped):

Spec (endpoint)	Top-level keys	Nested item filtering
`ADD_ACTIVITIES_SPEC` (`/v2/activities/add`)	`organizationId`, `documentId`, `activities`	`activities[]`: `id`, `featureType`, `actionType`, `actionUser`, `targetEntityId`, `isActivityResolverUsed`, `targetSubEntityId`, `changes`, `entityData`, `entityTargetData`, `displayMessageTemplate`, `displayMessageTemplateData`, `actionIcon`
`UPDATE_ACTIVITIES_SPEC` (`/v2/activities/update`)	`organizationId`, `activities`	`activities[]`: `id`, `changes`, `entityData`, `entityTargetData`, `displayMessageTemplate`, `displayMessageTemplateData`, `actionIcon`
`ADD_COMMENT_ANNOTATIONS_SPEC` (`/v2/commentannotations/add`)	`organizationId`, `documentId`, `commentAnnotations`, `verifyUserPermissions`, `createDocument`, `createOrganization`	`commentAnnotations[]`: `location`, `annotationId`, `targetElement`, `commentData`, `comments`, `status`, `commentType`, `type`, `assignedTo`, `priority`, `context`, `visibility`, `lastUpdated`, `createdAt`, `pageInfo`, `isPageAnnotation`, `positionX`, `positionY`, `screenWidth`, `screenHeight`, `screenScrollHeight`, `screenScrollTop` — its `comments[]`/`commentData[]` use the annotation comment-data set (below)
`UPDATE_COMMENT_ANNOTATIONS_SPEC` (`/v2/commentannotations/update`)	`organizationId`, `documentId`, `annotationIds`, `locationIds`, `userIds`, `updateUsers`, `updatedData`	`updatedData`: `location`, `targetElement`, `from`, `status`, `assignedTo`, `priority`, `context`, `visibility`, `createdAt`, `lastUpdated`
`ADD_COMMENTS_SPEC` (`/v2/commentannotations/comments/add`)	`organizationId`, `documentId`, `annotationId`, `commentData`, `comments`, `verifyUserPermissions`, `createDocument`, `createOrganization`	`commentData[]`/`comments[]`: comment-data set (below)
`UPDATE_COMMENTS_SPEC` (`/v2/commentannotations/comments/update`)	`organizationId`, `documentId`, `annotationId`, `commentIds`, `userIds`, `updatedData`	`updatedData`: `commentText`, `commentHtml`, `from`, `createdAt`, `taggedUserContacts`, `isCommentResolverUsed`, `isCommentTextAvailable`, `lastUpdated`, `context`, `attachments`
`ADD_NOTIFICATIONS_SPEC` (`/v2/notifications/add`)	`organizationId`, `documentId`, `notificationId`, `actionUser`, `isNotificationResolverUsed`, `displayHeadlineMessageTemplate`, `displayHeadlineMessageTemplateData`, `displayBodyMessage`, `displayBodyMessageTemplate`, `displayBodyMessageTemplateData`, `notifyUsers`, `notificationSourceData`, `location`, `metadata`, `notifyAll`, `createDocument`, `createOrganization`, `verifyUserPermissions`, `context`, `isCrossOrganizationEnabled`	the notification is the request itself — nested open-typed dicts pass through whole
`UPDATE_NOTIFICATIONS_SPEC` (`/v2/notifications/update`)	`organizationId`, `documentId`, `locationId`, `userId`, `verifyUserPermissions`, `notifications`	`notifications[]`: `id`, `actionUser`, `displayHeadlineMessageTemplate`, `displayHeadlineMessageTemplateData`, `displayBodyMessage`, `displayBodyMessageTemplate`, `displayBodyMessageTemplateData`, `notifyUsers`, `notificationSourceData`, `location`, `metadata`, `context`, `readByUserIds`, `persistReadForUsers`

The comment-annotation specs above reference two comment-data key sets:

Annotation-level commentData/comments (ANNOTATION_COMMENT_DATA_KEYS): commentText, commentHtml, commentId, from, lastUpdated, createdAt, taggedUserContacts, isCommentResolverUsed, isCommentTextAvailable, triggerNotification, triggerActivities, agent — carries the trigger flags but not context/attachments.
Comments-endpoint commentData/comments (COMMENT_DATA_KEYS): commentText, commentHtml, commentId, from, lastUpdated, createdAt, taggedUserContacts, isCommentResolverUsed, isCommentTextAvailable, context, attachments, agent — carries context/attachments but not the trigger flags.

UPDATE_NOTIFICATIONS_SPEC intentionally excludes isRead/isArchived — they are absent from the backend UpdateNotificationsSchemaV2 and unsupported by /v2/notifications/update, so they are dropped when filtering is on.

Organizations

Namespace: sdk.api.organizations

`addOrganizations`

Creates one or more organizations.
Params: AddOrganizationsRequest
Returns: VeltApiResponse

await sdk.api.organizations.addOrganizations({
  organizations: [{ organizationId: 'org-123', organizationName: 'My Organization' }],
});

Response

{
  result: {
    status: 'success',
    message: 'Organization(s) added successfully.',
    data: {
      'org-123': { success: true, id: '02cf91e5...', message: 'Added Successfully' }
    }
  }
}

`getOrganizations`

Retrieves organizations. Optionally filter by IDs with pagination.
Params: GetOrganizationsRequest
Returns: GetOrganizationsResponse

await sdk.api.organizations.getOrganizations({
  organizationIds: ['org-123'],
  pageSize: 10,
  pageToken: 'next-page-token',
});

Response

{
  result: {
    status: 'success',
    message: 'Organization(s) retrieved successfully.',
    data: [
      { id: 'org-123', organizationName: 'Your Organization Name', disabled: false }
    ],
    nextPageToken: 'pageToken'
  }
}

`updateOrganizations`

Updates organization properties.
Params: UpdateOrganizationsRequest
Returns: VeltApiResponse

await sdk.api.organizations.updateOrganizations({
  organizations: [{ organizationId: 'org-123', organizationName: 'Updated Name' }],
});

Response

{ result: { status: 'success', message: 'Organization(s) updated successfully.', data: {} } }

`deleteOrganizations`

Deletes one or more organizations.
Params: DeleteOrganizationsRequest
Returns: VeltApiResponse

await sdk.api.organizations.deleteOrganizations({ organizationIds: ['org-123'] });

Response

{ result: { status: 'success', message: 'Organization(s) deleted successfully.', data: {} } }

`updateOrganizationDisableState`

Enables or disables one or more organizations.
Params: UpdateOrganizationDisableStateRequest
Returns: VeltApiResponse

await sdk.api.organizations.updateOrganizationDisableState({
  organizationIds: ['org-123'],
  disabled: true,
});

Response

{ result: { status: 'success', message: 'Organization(s) disable state updated.', data: {} } }

Folders

Namespace: sdk.api.folders

`addFolder`

Creates one or more folders inside an organization.
Params: AddFolderRequest
Returns: VeltApiResponse

await sdk.api.folders.addFolder({
  organizationId: 'org-123',
  folders: [{ folderId: 'folder-1', folderName: 'My Folder' }],
  createOrganization: true,
});

Response

{ result: { status: 'success', message: 'Folder(s) added successfully.', data: {} } }

`getFolders`

Retrieves folders. Optionally filter by folder ID with depth control.
Params: GetFoldersRequest
Returns: GetFoldersResponse

await sdk.api.folders.getFolders({
  organizationId: 'org-123',
  folderId: 'folder-1',
  maxDepth: 3,
});

Response

{
  result: {
    status: 'success',
    message: 'Folders retrieved successfully.',
    data: [
      {
        folderId: 'folder-1',
        folderName: 'Folder 1',
        organizationId: 'org-123',
        parentFolderId: 'root',
        createdAt: 1738695615706,
        lastUpdated: 1738696287859
      }
    ]
  }
}

`updateFolder`

Updates folder properties.
Params: UpdateFolderRequest
Returns: VeltApiResponse

await sdk.api.folders.updateFolder({
  organizationId: 'org-123',
  folders: [{ folderId: 'folder-1', folderName: 'Renamed' }],
});

Response

{ result: { status: 'success', message: 'Folder(s) updated successfully.', data: {} } }

`deleteFolder`

Deletes a folder.
Params: DeleteFolderRequest
Returns: VeltApiResponse

await sdk.api.folders.deleteFolder({ organizationId: 'org-123', folderId: 'folder-1' });

Response

{ result: { status: 'success', message: 'Folder deleted successfully.', data: {} } }

`updateFolderAccess`

Updates access type for one or more folders.
Params: UpdateFolderAccessRequest
Returns: VeltApiResponse

await sdk.api.folders.updateFolderAccess({
  organizationId: 'org-123',
  folderIds: ['folder-1'],
  accessType: 'restricted',
});

Response

{ result: { status: 'success', message: 'Folder access updated successfully.', data: {} } }

Documents

Namespace: sdk.api.documents

`addDocuments`

Creates one or more documents.
Params: AddDocumentsRequest
Returns: VeltApiResponse

await sdk.api.documents.addDocuments({
  organizationId: 'org-123',
  documents: [
    { documentId: 'doc-1', documentName: 'My Document' },
    { documentId: 'doc-2', documentName: 'Another Document' },
  ],
  createOrganization: true,
  folderId: 'folder-1',
  createFolder: true,
});

Response

{
  result: {
    status: 'success',
    message: 'Document(s) added successfully.',
    data: {
      'doc-1': { success: true, message: 'Added Successfully' },
      'doc-2': { success: true, message: 'Added Successfully' }
    }
  }
}

`getDocuments`

Retrieves documents with optional filters and pagination.
Params: GetDocumentsRequest
Returns: GetDocumentsResponse

await sdk.api.documents.getDocuments({
  organizationId: 'org-123',
  documentIds: ['doc-1'],
  folderId: 'folder-1',
  pageSize: 10,
});

Response

{
  result: {
    status: 'success',
    message: 'Document(s) retrieved successfully.',
    data: [
      { documentName: 'yourDocumentName', disabled: false, accessType: 'public', id: 'yourDocumentId' }
    ],
    pageToken: 'nextPageToken'
  }
}

`updateDocuments`

Updates document properties.
Params: UpdateDocumentsRequest
Returns: VeltApiResponse

await sdk.api.documents.updateDocuments({
  organizationId: 'org-123',
  documents: [{ documentId: 'doc-1', documentName: 'Renamed' }],
});

Response

{ result: { status: 'success', message: 'Document(s) updated successfully.', data: {} } }

`deleteDocuments`

Deletes one or more documents.
Params: DeleteDocumentsRequest
Returns: VeltApiResponse

await sdk.api.documents.deleteDocuments({
  organizationId: 'org-123',
  documentIds: ['doc-1', 'doc-2'],
});

Response

{ result: { status: 'success', message: 'Document(s) deleted successfully.', data: {} } }

`moveDocuments`

Moves documents into a folder.
Params: MoveDocumentsRequest
Returns: VeltApiResponse

await sdk.api.documents.moveDocuments({
  organizationId: 'org-123',
  documentIds: ['doc-1', 'doc-2'],
  folderId: 'target-folder-id',
});

Response

{ result: { status: 'success', message: 'Document(s) moved successfully.', data: {} } }

`updateDocumentAccess`

Updates access type for one or more documents.
Params: UpdateDocumentAccessRequest
Returns: VeltApiResponse

await sdk.api.documents.updateDocumentAccess({
  organizationId: 'org-123',
  documentIds: ['doc-1', 'doc-2'],
  accessType: 'organizationPrivate',
});

Response

{ result: { status: 'success', message: 'Document access updated successfully.', data: {} } }

`updateDocumentDisableState`

Enables or disables one or more documents.
Params: UpdateDocumentDisableStateRequest
Returns: VeltApiResponse

await sdk.api.documents.updateDocumentDisableState({
  organizationId: 'org-123',
  documentIds: ['doc-1'],
  disabled: true,
});

Response

{ result: { status: 'success', message: 'Document(s) disable state updated.', data: {} } }

`migrateDocuments`

Starts a document migration job.
Params: MigrateDocumentsRequest
Returns: MigrateDocumentsResponse

Note: migrateDocuments is asynchronous and returns a migrationId. Poll completion with migrateDocumentsStatus.

await sdk.api.documents.migrateDocuments({
  organizationId: 'org-123',
  documentId: 'old-doc-id',
  newDocumentId: 'new-doc-id',
});

Response

{
  result: {
    status: 'success',
    message: 'Document migration started successfully.',
    data: { migrationId: 'yourMigrationId' }
  }
}

`migrateDocumentsStatus`

Polls the status of a migration job.
Params: MigrateDocumentsStatusRequest
Returns: MigrateDocumentsStatusResponse

await sdk.api.documents.migrateDocumentsStatus({
  organizationId: 'org-123',
  migrationId: 'migration-1',
});

Response

{
  result: {
    status: 'success',
    message: 'Migration status retrieved successfully.',
    data: { migrationId: 'yourMigrationId', status: 'completed' }
  }
}

`getDocumentsCount`

Return a document count for an organization (optionally scoped to a folder, or narrowed by metadata filters).
Params: GetDocumentsCountRequest
Returns: VeltApiResponse

await sdk.api.documents.getDocumentsCount({ organizationId: 'org-123' });
await sdk.api.documents.getDocumentsCount({ organizationId: 'org-123', folderId: 'folder-1', excludeFolderDocs: true });

// Narrow the count with metadata filters (same shape as getDocuments; max 10).
await sdk.api.documents.getDocumentsCount({
  organizationId: 'org-123',
  filters: [
    { key: 'projectType', operator: '==', value: 'design' },
    { key: 'category', operator: 'in', value: ['a', 'b'] },
  ],
});

filters cannot be combined with excludeFolderDocs — the API rejects the combination. Response

{ result: { status: 'success', message: 'Documents count retrieved successfully.', data: { count: 42 } } }

When filters is supplied, the response data also carries filtersApplied. A false value means the filtered aggregate could not be computed and count is an unfiltered fallback, so check it if you need the count to be exact:

{ result: { status: 'success', message: 'Documents count retrieved successfully.', data: { count: 7, filtersApplied: true } } }

Users

Namespace: sdk.api.users

`addUsers`

Adds one or more users to an organization, document, or folder.
Params: AddUsersRequest
Returns: VeltApiResponse

await sdk.api.users.addUsers({
  organizationId: 'org-123',
  users: [{ userId: 'user-1', name: 'John Doe', email: 'john@example.com', accessRole: 'editor' }],
  createOrganization: true,
});

Response

{ result: { status: 'success', message: 'User(s) added successfully.', data: {} } }

`getUsers`

Retrieves users with optional filters and pagination.
Params: GetUsersRequest
Returns: GetUsersResponse

await sdk.api.users.getUsers({
  organizationId: 'org-123',
  userIds: ['user-1'],
  documentId: 'doc-1',
  pageSize: 100,
  allDocuments: true,
  groupByDocumentId: true,
});

Response

{
  result: {
    status: 'success',
    message: 'User(s) retrieved successfully.',
    data: [
      { email: 'userEmail@domain.com', name: 'userName', userId: 'yourUserId' }
    ],
    nextPageToken: 'pageToken'
  }
}

`updateUsers`

Updates user properties.
Params: UpdateUsersRequest
Returns: VeltApiResponse

await sdk.api.users.updateUsers({
  organizationId: 'org-123',
  users: [{ userId: 'user-1', name: 'Jane Doe', accessRole: 'viewer' }],
});

Response

{ result: { status: 'success', message: 'User(s) updated successfully.', data: {} } }

`deleteUsers`

Removes users from an organization.
Params: DeleteUsersRequest
Returns: VeltApiResponse

await sdk.api.users.deleteUsers({ organizationId: 'org-123', userIds: ['user-1'] });

Response

{ result: { status: 'success', message: 'User(s) deleted successfully.', data: {} } }

`getUsersCount`

Count users in an org (optionally scoped to a document or all documents).
Params: GetUsersCountRequest
Returns: VeltApiResponse

await sdk.api.users.getUsersCount({ organizationId: 'org-123', allDocuments: true });

Response

{ result: { status: 'success', message: 'Users count retrieved successfully.', data: { count: 12 } } }

`getDocUsers`

Get document-level users (optionally including involved documents).
Params: GetDocUsersRequest
Returns: VeltApiResponse

await sdk.api.users.getDocUsers({ organizationId: 'org-123', userIds: ['user-1'] });

Response

{
  result: {
    status: 'success',
    message: 'Document users retrieved successfully.',
    data: [{ userId: 'user-1', name: 'John Doe', email: 'john@example.com' }]
  }
}

`addUserInvite`

Create an org/doc/folder user invite.
Params: AddUserInviteRequest
Returns: VeltApiResponse

await sdk.api.users.addUserInvite({ email: 'invitee@example.com', organizationId: 'org-123', type: 'doc_user', documentId: 'doc-1' });

Response

{ result: { status: 'success', message: 'User invite created successfully.', data: {} } }

`respondToUserInvite`

Accept/reject/withdraw an invite.
Params: RespondToUserInviteRequest
Returns: VeltApiResponse

await sdk.api.users.respondToUserInvite({ email: 'invitee@example.com', organizationId: 'org-123', type: 'doc_user', documentId: 'doc-1', status: 'ACCEPTED', user: { userId: 'user-9', name: 'New User', email: 'invitee@example.com' }, authToken: 'user-auth-token' });

Response

{ result: { status: 'success', message: 'Invite response recorded successfully.', data: {} } }

`getUserInvites`

List invites for an org (paged).
Params: GetUserInvitesRequest
Returns: VeltApiResponse

await sdk.api.users.getUserInvites({ organizationId: 'org-123' });

Response

{
  result: {
    status: 'success',
    message: 'User invites retrieved successfully.',
    data: [{ email: 'invitee@example.com', type: 'doc_user', status: 'PENDING' }],
    nextPageToken: 'pageToken'
  }
}

`getUserInvitations`

List invitations for a specific email (paged, filterable).
Params: GetUserInvitationsRequest
Returns: VeltApiResponse

await sdk.api.users.getUserInvitations({ organizationId: 'org-123', email: 'invitee@example.com' });

Response

{
  result: {
    status: 'success',
    message: 'User invitations retrieved successfully.',
    data: [{ organizationId: 'org-123', type: 'doc_user', status: 'PENDING' }],
    nextPageToken: 'pageToken'
  }
}

`getInvitedPendingUsersCount`

Count pending invited users by invite type.
Params: GetInvitedPendingUsersCountRequest
Returns: VeltApiResponse

await sdk.api.users.getInvitedPendingUsersCount({ organizationId: 'org-123', type: 'org_user' });

Response

{ result: { status: 'success', message: 'Pending invited users count retrieved successfully.', data: { count: 3 } } }

User Groups

Namespace: sdk.api.userGroups

`addUserGroups`

Creates one or more user groups.
Params: AddUserGroupsRequest
Returns: VeltApiResponse

await sdk.api.userGroups.addUserGroups({
  organizationId: 'org-123',
  organizationUserGroups: [{ groupId: 'engineering', groupName: 'Engineering' }],
  createOrganization: true,
});

Response

{ result: { status: 'success', message: 'User group(s) added successfully.', data: {} } }

`addUsersToGroup`

Adds users to an existing group.
Params: AddUsersToGroupRequest
Returns: VeltApiResponse

await sdk.api.userGroups.addUsersToGroup({
  organizationId: 'org-123',
  organizationUserGroupId: 'engineering',
  userIds: ['user-1', 'user-2'],
});

Response

{ result: { status: 'success', message: 'Users added to group successfully.', data: {} } }

`deleteUsersFromGroup`

Removes users from a group, or removes all users.
Params: DeleteUsersFromGroupRequest
Returns: VeltApiResponse

await sdk.api.userGroups.deleteUsersFromGroup({
  organizationId: 'org-123',
  organizationUserGroupId: 'engineering',
  userIds: ['user-1'],
});

Response

{ result: { status: 'success', message: 'Users removed from group successfully.', data: {} } }

Notifications

Namespace: sdk.api.notifications

Filtering unknown fields: The add/update methods below accept an optional options?: FieldFilterOptions second argument. When { filterUnknownFields: true } is passed, unknown/custom keys are dropped before the request is sent, narrowing the payload to exactly the fields the Velt backend endpoint accepts. Open-typed objects (actionUser, context, metadata, user objects) pass through whole. Filtering is fail-open: if it errors, the original payload is sent, so a write is never blocked. UPDATE_NOTIFICATIONS_SPEC intentionally excludes isRead/isArchived — they are unsupported by /v2/notifications/update, so they are dropped when filtering is on. See Field Allowlist for the full per-endpoint field list.

`addNotifications`

Adds one or more notifications targeted to specific users.
Params: AddNotificationsRequest
Returns: VeltApiResponse
Accepts an optional options?: FieldFilterOptions second argument — pass { filterUnknownFields: true } to drop unknown fields before sending (see the note above).

await sdk.api.notifications.addNotifications({
  organizationId: 'org-123',
  documentId: 'doc-1',
  actionUser: { userId: 'user-1', name: 'John Doe', email: 'john@example.com' },
  displayHeadlineMessageTemplate: '{actionUser} commented on your document',
  displayBodyMessage: 'Check out the new comment',
  notifyUsers: [{ userId: 'user-2', name: 'Jane Doe' }],
  createOrganization: true,
  createDocument: true,
});

Response

{ result: { status: 'success', message: 'Notification(s) added successfully.', data: {} } }

`getNotifications`

Gets notifications for a user with optional filters and pagination.
Params: GetNotificationsRequest
Returns: GetNotificationsResponse
Velt filters results by comment visibility: a notification for a private comment is returned only to users who can see that comment.

await sdk.api.notifications.getNotifications({
  organizationId: 'org-123',
  userId: 'user-2',
  pageSize: 10,
  order: 'desc',
});

Response

{
  result: {
    status: 'success',
    message: 'Notification(s) retrieved successfully.',
    data: [
      {
        id: 'notificationId',
        notificationSource: 'custom',
        actionUser: { userId: 'user-1', name: 'John Doe', email: 'john@example.com' },
        displayBodyMessage: 'Check out the new comment',
        displayHeadlineMessageTemplate: '{actionUser} commented on your document',
        timestamp: 1722409519944
      }
    ],
    pageToken: 'nextPageToken'
  }
}

`updateNotifications`

Updates existing notifications (e.g., mark as read).
Params: UpdateNotificationsRequest
Returns: VeltApiResponse
Accepts an optional options?: FieldFilterOptions second argument — pass { filterUnknownFields: true } to drop unknown fields before sending (see the note above).

await sdk.api.notifications.updateNotifications({
  organizationId: 'org-123',
  userId: 'user-2',
  notifications: [{ notificationId: 'n-1', read: true }],
});

Response

{ result: { status: 'success', message: 'Notification(s) updated successfully.', data: {} } }

`deleteNotifications`

Deletes one or more notifications.
Params: DeleteNotificationsRequest
Returns: VeltApiResponse

await sdk.api.notifications.deleteNotifications({
  organizationId: 'org-123',
  userId: 'user-2',
  notificationIds: ['n-1'],
});

Response

{ result: { status: 'success', message: 'Notification(s) deleted successfully.', data: {} } }

`getNotificationConfig`

Gets notification preferences for a user.
Params: GetNotificationConfigRequest
Returns: GetNotificationConfigResponse

await sdk.api.notifications.getNotificationConfig({
  organizationId: 'org-123',
  userId: 'user-1',
});

Response

{
  result: {
    status: 'success',
    message: 'User config fetched successfully.',
    data: [
      {
        config: { inbox: 'ALL', email: 'ALL' },
        metadata: { organizationId: 'org-123', apiKey: 'API_KEY', documentId: 'doc-1', userId: 'user-1' }
      }
    ]
  }
}

`setNotificationConfig`

Sets notification preferences for one or more users.
Params: SetNotificationConfigRequest
Returns: VeltApiResponse

await sdk.api.notifications.setNotificationConfig({
  organizationId: 'org-123',
  userIds: ['user-1', 'user-2'],
  config: { inbox: 'ALL', email: 'MINE', slack: 'NONE' },
});

Response

{ result: { status: 'success', message: 'User config set successfully.', data: {} } }

Comment Annotations

Namespace: sdk.api.commentAnnotations

Filtering unknown fields: The add/update methods below accept an optional options?: FieldFilterOptions second argument. When { filterUnknownFields: true } is passed, request entity collections are narrowed to only the fields the Velt backend endpoint accepts, dropping unknown/custom keys before the request is sent. Open-typed objects (from, context, metadata, user objects) pass through whole — their nested contents are never filtered. Filtering is fail-open: if it errors, the original payload is sent, so a write is never blocked. See Field Allowlist for the full per-endpoint field list.

// Extra fields (internalId) are dropped before the request is sent.
await sdk.api.commentAnnotations.addCommentAnnotations(
  {
    organizationId: 'org-123',
    documentId: 'doc-1',
    commentAnnotations: [
      {
        location: { id: 'section-1' },
        commentData: [{ commentText: 'Review this', from: { userId: 'user-1' } }],
        internalId: 'app-specific-field', // dropped when filtering is enabled
      },
    ],
  },
  { filterUnknownFields: true },
);

`addCommentAnnotations`

Creates comment annotations on a document.
Params: AddCommentAnnotationsRequest
Returns: VeltApiResponse
Accepts an optional options?: FieldFilterOptions second argument — pass { filterUnknownFields: true } to drop unknown fields before sending (see the note above).

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

Response

{ result: { status: 'success', message: 'Annotation(s) added successfully.', data: {} } }

`getCommentAnnotations`

Retrieves comment annotations for a document with optional filters and pagination.
Params: GetCommentAnnotationsRequest
Returns: GetCommentAnnotationsResponse

await sdk.api.commentAnnotations.getCommentAnnotations({
  organizationId: 'org-123',
  documentId: 'doc-1',
  statusIds: ['OPEN'],
  pageSize: 10,
});

Agent filters Scope a listing to agent-authored annotations with one of agentId, executionId, agentType, agentSource, agentSuggestions, or agentComments. Supply at most one per request.

// All annotations authored by a specific agent
await sdk.api.commentAnnotations.getCommentAnnotations({
  organizationId: 'org-123',
  documentId: 'doc-1',
  agentId: 'agent-7',
});

// Only fresh (unaccepted) agent suggestions
await sdk.api.commentAnnotations.getCommentAnnotations({
  organizationId: 'org-123',
  documentId: 'doc-1',
  agentSuggestions: true,
});

Agent filtering is annotation-scoped and requires advanced queries to be enabled on your workspace. When they are not enabled, the API fails closed rather than returning unfiltered results.

Response

{
  result: {
    status: 'success',
    message: 'Annotations fetched successfully.',
    data: [
      {
        type: 'comment',
        comments: [
          {
            commentId: 123456,
            commentText: 'This is a sample comment text.',
            commentHtml: '<p>This is a sample comment text.</p>',
            from: { userId: 'user123', name: 'John Doe', email: 'john.doe@example.com' },
            createdAt: 1687344600000
          }
        ],
        status: { id: 'OPEN', name: 'Open', type: 'default' }
      }
    ]
  }
}

`getCommentAnnotationsCount`

Gets total and unread annotation counts per document.
Params: GetCommentAnnotationsCountRequest
Returns: GetCommentAnnotationsCountResponse

await sdk.api.commentAnnotations.getCommentAnnotationsCount({
  organizationId: 'org-123',
  documentIds: ['doc-1', 'doc-2'],
  userId: 'user-1',
});

The count endpoint does not support agent filtering, and agent filter fields sent to it are ignored rather than rejected — you would receive unfiltered totals with no error. To count an agent-scoped subset, call getCommentAnnotations with an agent filter and count the result.

Response

{
  result: {
    status: 'success',
    message: 'Comment count retrieved successfully.',
    data: {
      'doc-1': { total: 4, unread: 2 },
      'doc-2': { total: 2, unread: 0 }
    }
  }
}

`updateCommentAnnotations`

Updates fields on existing annotations (e.g., resolve them).
Params: UpdateCommentAnnotationsRequest
Returns: VeltApiResponse
Accepts an optional options?: FieldFilterOptions second argument — pass { filterUnknownFields: true } to drop unknown fields before sending (see the note above).

await sdk.api.commentAnnotations.updateCommentAnnotations({
  organizationId: 'org-123',
  documentId: 'doc-1',
  annotationIds: ['annotation-id-1'],
  updatedData: { status: { id: 'RESOLVED', name: 'Resolved', type: 'terminal' } },
});

Response

{ result: { status: 'success', message: 'Annotation(s) updated successfully.', data: {} } }

`deleteCommentAnnotations`

Deletes comment annotations.
Params: DeleteCommentAnnotationsRequest
Returns: VeltApiResponse

await sdk.api.commentAnnotations.deleteCommentAnnotations({
  organizationId: 'org-123',
  documentId: 'doc-1',
  annotationIds: ['annotation-id-1'],
});

Agent filters agentSuggestions, agentId, and agentUrls narrow a delete to agent-authored annotations. They combine, so you can scope a sweep precisely — for example, “this agent’s still-pending suggestions on these pages”, which leaves a concurrent crawl’s freshly-created annotations untouched.

await sdk.api.commentAnnotations.deleteCommentAnnotations({
  organizationId: 'org-123',
  documentId: 'doc-1',
  agentId: 'agent-7',
  agentSuggestions: true,
  agentUrls: ['https://app.example.com/page-1', 'https://app.example.com/page-2'],
});

agentUrls matches annotations scoped to any of the supplied pages.

Agent filters require advanced queries to be enabled on your workspace. When they are not enabled — or when none of the supplied agentUrls resolve — the API fails closed and deletes nothing, rather than widening to a document-wide delete.

Response

{ result: { status: 'success', message: 'Annotation(s) deleted successfully.', data: {} } }

`addComments`

Adds comments to an existing annotation.
Params: AddCommentsRequest
Returns: VeltApiResponse
Accepts an optional options?: FieldFilterOptions second argument — pass { filterUnknownFields: true } to drop unknown fields before sending (see the note above).

await sdk.api.commentAnnotations.addComments({
  organizationId: 'org-123',
  documentId: 'doc-1',
  annotationId: 'annotation-id-1',
  commentData: [{
    commentText: 'I agree, let me fix this',
    from: { userId: 'user-2', name: 'Jane Doe' },
  }],
});

Response

{ result: { status: 'success', message: 'Comment(s) added successfully.', data: {} } }

`getComments`

Retrieves comments within a specific annotation.
Params: GetCommentsRequest
Returns: GetCommentsResponse

await sdk.api.commentAnnotations.getComments({
  organizationId: 'org-123',
  documentId: 'doc-1',
  annotationId: 'annotation-id-1',
  userIds: ['user-1'],
});

Response

{
  result: {
    status: 'success',
    message: 'Comments(s) retrieved successfully.',
    data: [
      {
        commentId: 153783,
        commentText: 'Sample Comment Text',
        commentHtml: '<div>Hello Updated 2</div>',
        from: { userId: 'yourUserId', name: 'User Name', email: 'user@example.com' },
        lastUpdated: '2024-06-20T09:53:42.258Z',
        status: 'added',
        type: 'text'
      }
    ]
  }
}

`updateComments`

Updates comments within a specific annotation.
Params: UpdateCommentsRequest
Returns: VeltApiResponse
Accepts an optional options?: FieldFilterOptions second argument — pass { filterUnknownFields: true } to drop unknown fields before sending (see the note above).

await sdk.api.commentAnnotations.updateComments({
  organizationId: 'org-123',
  documentId: 'doc-1',
  annotationId: 'annotation-id-1',
  commentIds: [123456],
  updatedData: { commentText: 'Updated text', commentHtml: '<p>Updated text</p>' },
});

Response

{ result: { status: 'success', message: 'Comment(s) updated successfully.', data: {} } }

`deleteComments`

Deletes individual comments from an annotation.
Params: DeleteCommentsRequest
Returns: VeltApiResponse

await sdk.api.commentAnnotations.deleteComments({
  organizationId: 'org-123',
  documentId: 'doc-1',
  annotationId: 'annotation-id-1',
  commentIds: [123456],
});

Response

{ result: { status: 'success', message: 'Comment(s) deleted successfully.', data: {} } }

Activities

Namespace: sdk.api.activities

Filtering unknown fields: The add/update methods below accept an optional options?: FieldFilterOptions second argument. When { filterUnknownFields: true } is passed, request entity collections are narrowed to only the fields the Velt backend endpoint accepts, dropping unknown/custom keys before the request is sent. Open-typed objects (actionUser, entityData, context, metadata) pass through whole — their nested contents are never filtered. Filtering is fail-open: if it errors, the original payload is sent, so a write is never blocked. See Field Allowlist for the full per-endpoint field list.

`addActivities`

Logs activity events.
Params: AddActivitiesRequest
Returns: VeltApiResponse
Accepts an optional options?: FieldFilterOptions second argument — pass { filterUnknownFields: true } to drop unknown fields before sending (see the note above).

await sdk.api.activities.addActivities({
  organizationId: 'org-123',
  documentId: 'doc-456',
  activities: [{
    featureType: 'comment',
    actionType: 'comment.add',
    actionUser: { userId: 'user-1', name: 'John Doe', email: 'john@example.com' },
    displayMessageTemplate: '{{user}} added a comment',
  }],
});

Response

{ result: { status: 'success', message: 'Activity(s) added successfully.', data: {} } }

`getActivities`

Retrieves activity events with optional filters and pagination.
Params: GetActivitiesRequest
Returns: GetActivitiesResponse

await sdk.api.activities.getActivities({
  organizationId: 'org-123',
  documentId: 'doc-456',
  featureTypes: ['comment'],
  order: 'desc',
  pageSize: 50,
});

Response

{
  result: {
    status: 'success',
    message: 'Activity(s) retrieved successfully.',
    data: [
      {
        id: 'activity-001',
        featureType: 'comment',
        actionType: 'comment.add',
        actionUser: { userId: 'user-1', email: 'user@example.com', name: 'User Name' },
        targetEntityId: 'annotation-789',
        displayMessageTemplate: '{{user}} added a comment',
        metadata: { apiKey: 'yourApiKey', documentId: 'doc-456', organizationId: 'org-123' },
        timestamp: 1722409519944
      }
    ],
    pageToken: 'nextPageToken'
  }
}

`updateActivities`

Updates existing activity events.
Params: UpdateActivitiesRequest
Returns: VeltApiResponse
Accepts an optional options?: FieldFilterOptions second argument — pass { filterUnknownFields: true } to drop unknown fields before sending (see the note above).

await sdk.api.activities.updateActivities({
  organizationId: 'org-123',
  activities: [{ id: 'activity-001', displayMessageTemplate: '{{user}} updated the comment' }],
});

Response

{ result: { status: 'success', message: 'Activity(s) updated successfully.', data: {} } }

`deleteActivities`

Deletes activity events for a document.
Params: DeleteActivitiesRequest
Returns: VeltApiResponse

await sdk.api.activities.deleteActivities({
  organizationId: 'org-123',
  documentId: 'doc-456',
});

Response

{ result: { status: 'success', message: 'Activity(s) deleted successfully.', data: {} } }

Access Control

Namespace: sdk.api.accessControl

`addPermissions`

Grants a user access to one or more resources.
Params: AddPermissionsRequest
Returns: VeltApiResponse

await sdk.api.accessControl.addPermissions({
  user: { userId: 'user-1' },
  permissions: {
    resources: [
      { type: 'organization', id: 'org-123', accessRole: 'editor' },
      { type: 'document', id: 'doc-1', organizationId: 'org-123', accessRole: 'viewer', expiresAt: 1728902400 },
    ],
  },
});

Response

{ result: { status: 'success', message: 'Permissions added successfully.', data: {} } }

`getPermissions`

Retrieves permissions for users on resources.
Params: GetPermissionsRequest
Returns: GetPermissionsResponse

await sdk.api.accessControl.getPermissions({
  organizationId: 'org-123',
  userIds: ['user-1'],
  documentIds: ['doc-1'],
});

By default the API errors if any supplied folder or document ID does not resolve. Pass skipResourceExistenceValidation: true to skip that check and return whatever permissions exist:

await sdk.api.accessControl.getPermissions({
  organizationId: 'org-123',
  userIds: ['user-1'],
  documentIds: ['doc-1', 'doc-might-not-exist'],
  skipResourceExistenceValidation: true,
});

Response

{
  result: {
    status: 'success',
    message: 'User permissions retrieved successfully.',
    data: {
      'user-1': {
        documents: { 'doc-1': { accessRole: 'viewer', accessType: 'restricted' } },
        organization: { 'org-123': { accessRole: 'editor' } }
      }
    }
  }
}

`removePermissions`

Revokes a user’s access to one or more resources.
Params: RemovePermissionsRequest
Returns: VeltApiResponse

await sdk.api.accessControl.removePermissions({
  userId: 'user-1',
  permissions: {
    resources: [
      { type: 'organization', id: 'org-123' },
      { type: 'document', id: 'doc-1', organizationId: 'org-123' },
    ],
  },
});

Response

{ result: { status: 'success', message: 'Permissions removed successfully.', data: {} } }

`generateSignature`

Generates a signed payload for the Permission Provider flow.
Params: GenerateSignatureRequest
Returns: GenerateSignatureResponse

await sdk.api.accessControl.generateSignature({
  permissions: [{
    userId: 'user-1',
    resourceId: 'doc-1',
    type: 'document',
    hasAccess: true,
    accessRole: 'viewer',
  }],
});

Response

{
  result: {
    status: 'success',
    message: 'Signature generated successfully.',
    data: { signature: 'a1b2c3d4e5f6...' }
  }
}

`generateToken`

Generates a JWT auth token for a user with embedded permissions.
Calls POST /v2/auth/generate_token, the endpoint documented in the Generate Token REST API and used by the JWT guide.
Expects GenerateTokenRequest { userId: string; userProperties: { name?, email?, photoUrl?, color?, textColor?, ... }; permissions: { resources?: Resource[] } }, passed as a request object like every other sdk.api.* method.
Returns the raw Velt API envelope VeltApiResponse: { result: { status, message, data: { token } } }.
Params: GenerateTokenRequest
Returns: GenerateTokenResponse

await sdk.api.accessControl.generateToken({
  userId: 'user-1',
  userProperties: { name: 'John Doe', email: 'john@example.com', isAdmin: false },
  permissions: {
    resources: [
      { type: 'organization', id: 'org-123', accessRole: 'viewer' },
      { type: 'document', id: 'doc-1', organizationId: 'org-123', accessRole: 'editor' },
    ],
  },
});

Response

{
  result: {
    status: 'success',
    message: 'Token generated successfully.',
    data: { token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' }
  }
}

CRDT

Namespace: sdk.api.crdt Supports text, map, array, and xml CRDT data types.

`addCrdtData`

Stores CRDT (Yjs) editor data for a document.
Params: AddCrdtDataRequest
Returns: VeltApiResponse

await sdk.api.crdt.addCrdtData({
  organizationId: 'org-123',
  documentId: 'doc-1',
  editorId: 'my-collab-note',
  data: 'Hello, collaborative world!',
  type: 'text',
});

Response

{ result: { status: 'success', message: 'CRDT data added successfully.', data: {} } }

`getCrdtData`

Retrieves CRDT data for a document, optionally filtered by editor.
Params: GetCrdtDataRequest
Returns: GetCrdtDataResponse

await sdk.api.crdt.getCrdtData({
  organizationId: 'org-123',
  documentId: 'doc-1',
  editorId: 'my-collab-note',
});

Response

{
  result: {
    status: 'success',
    message: 'CRDT data retrieved successfully.',
    data: [
      {
        data: 'Hello, collaborative world!',
        id: 'my-collab-note',
        lastUpdate: '2025-01-20T10:30:00.000Z',
        lastUpdatedBy: 'user-123',
        sessionId: 'session-abc-456'
      }
    ]
  }
}

`updateCrdtData`

Updates existing CRDT editor data.
Params: UpdateCrdtDataRequest
Returns: VeltApiResponse

await sdk.api.crdt.updateCrdtData({
  organizationId: 'org-123',
  documentId: 'doc-1',
  editorId: 'my-collab-note',
  data: 'Updated collaborative content!',
  type: 'text',
});

Response

{ result: { status: 'success', message: 'CRDT data updated successfully.', data: {} } }

`deleteCrdtData`

Delete CRDT editor data for a document. Omit editorIds to delete CRDT data for all editors of the document.
Params: DeleteCrdtDataRequest
Returns: VeltApiResponse

await sdk.api.crdt.deleteCrdtData({ organizationId: 'org-123', documentId: 'doc-1', editorIds: ['my-collab-note'] });
await sdk.api.crdt.deleteCrdtData({ organizationId: 'org-123', documentId: 'doc-1' });

Response

{ result: { status: 'success', message: 'CRDT data deleted successfully.', data: {} } }

Presence

Namespace: sdk.api.presence

`addPresence`

Adds users to presence on a document.
Params: AddPresenceRequest
Returns: VeltApiResponse

await sdk.api.presence.addPresence({
  organizationId: 'org-123',
  documentId: 'doc-456',
  users: [
    { userId: 'user-1', name: 'John Doe', email: 'john@example.com', status: 'online' },
    { userId: 'user-2', name: 'Jane Doe', status: 'away' },
  ],
});

Response

{ result: { status: 'success', message: 'Presence added successfully.', data: {} } }

`updatePresence`

Updates presence status for one or more users.
Params: UpdatePresenceRequest
Returns: VeltApiResponse

await sdk.api.presence.updatePresence({
  organizationId: 'org-123',
  documentId: 'doc-456',
  users: [{ userId: 'user-1', status: 'away' }],
});

Response

{ result: { status: 'success', message: 'Presence updated successfully.', data: {} } }

`deletePresence`

Removes users from presence on a document.
Params: DeletePresenceRequest
Returns: VeltApiResponse

await sdk.api.presence.deletePresence({
  organizationId: 'org-123',
  documentId: 'doc-456',
  userIds: ['user-1', 'user-2'],
});

Response

{ result: { status: 'success', message: 'Presence removed successfully.', data: {} } }

Livestate

Namespace: sdk.api.livestate

`broadcastEvent`

Broadcasts an ephemeral live-state event to all clients on a document.
Params: BroadcastEventRequest
Returns: VeltApiResponse

await sdk.api.livestate.broadcastEvent({
  organizationId: 'org-123',
  documentId: 'doc-1',
  liveStateDataId: 'my-live-state',
  data: { status: 'active', message: 'Hello World' },
  merge: true,
});

Response

{ result: { status: 'success', message: 'Event broadcast successfully.', data: {} } }

Recordings

Namespace: sdk.api.recordings

`getRecordings`

Retrieves recording metadata for an organization or document with optional filtering and pagination.
Params: GetRecordingsRequest
Returns: GetRecordingsResponse

await sdk.api.recordings.getRecordings({
  organizationId: 'org-123',
  documentId: 'doc-456',
  recordingIds: ['rec-1'],
  pageSize: 10,
  pageToken: 'next-page-token',
});

Response

{
  result: {
    status: 'success',
    message: 'Recorder annotations retrieved successfully.',
    data: [
      {
        type: 'recorder',
        recordingType: 'screen',
        mode: 'floating',
        metadata: { apiKey: 'YOUR_API_KEY', documentId: 'doc-456', organizationId: 'org-123' },
        recordedTime: { duration: 4204.55, display: '00:00:04' },
        displayName: 'Screen Recording 1773814490242.mp4',
        annotationId: 'ypvmVTROaNU1qP4kq7Cc',
        attachments: [{
          attachmentId: 875113,
          url: 'https://storage.googleapis.com/...',
          mimeType: 'video/mp4',
          name: 'recording_1773814490242.mp4',
          type: 'mp4',
          size: 103551
        }],
        latestVersion: 5
      }
    ],
    pageToken: 'nextPageToken'
  }
}

Rewriter

Namespace: sdk.api.rewriter Supports OpenAI, Anthropic, and Gemini models.

`askAi`

Calls the Velt AI rewriter with a model, prompt, and text.
Params: AskAiRequest
Returns: AskAiResponse

Note: askAi may take several seconds to respond. The SDK does not enforce a client-side timeout.

await sdk.api.rewriter.askAi({
  model: 'gpt-4o',
  prompt: 'Fix the grammar and spelling in the following text.',
  text: 'Their going to the store to by some apples.',
});

Response

{
  result: {
    success: true,
    text: 'The rewritten or processed text returned by the model.'
  }
}

Namespace: sdk.api.gdpr

`deleteAllUserData`

Requests deletion of all data associated with one or more users.
Params: DeleteAllUserDataRequest
Returns: VeltApiResponse

Note: deleteAllUserData is asynchronous and returns a job ID. Poll completion with getDeleteUserDataStatus.

await sdk.api.gdpr.deleteAllUserData({
  userIds: ['user-1', 'user-2'],
  organizationIds: ['org-123'],
});

Response

{
  result: {
    status: 'success',
    message: 'User data deletion job queued.',
    data: { jobId: 'delete-job-id' }
  }
}

`getAllUserData`

Exports all data for a single user (paginated).
Params: GetAllUserDataRequest
Returns: GetAllUserDataResponse

await sdk.api.gdpr.getAllUserData({
  organizationId: 'org-123',
  userId: 'user-1',
  pageToken: 'next-page-token',
});

Pass veltUserIds to export data for a set of Velt-side user IDs instead of the single userId, veltAllOrganizations to span every organization rather than just organizationId, and uniqueId as a correlation value echoed back on the response:

await sdk.api.gdpr.getAllUserData({
  organizationId: 'org-123',
  userId: 'user-1',
  veltUserIds: ['velt-user-1', 'velt-user-2'],
  veltAllOrganizations: true,
  uniqueId: 'export-request-42',
});

Response

{
  result: {
    status: 'success',
    message: 'Data fetched successfully.',
    data: {
      comments: [/* up to 100 items */],
      reactions: [/* up to 100 items */],
      recordings: [/* up to 100 items */],
      notifications: [/* up to 100 items */]
    },
    nextPageToken: 'bhdwdqwjs298e39e479ddkeuw==329'
  }
}

`getDeleteUserDataStatus`

Polls the status of a deletion job.
Params: GetDeleteUserDataStatusRequest
Returns: GetDeleteUserDataStatusResponse

await sdk.api.gdpr.getDeleteUserDataStatus({ jobId: 'job-id-from-delete-call' });

Response

{
  result: {
    status: 'success',
    message: 'Data fetched successfully.',
    data: {
      isDeleteCompleted: true,
      tasksLeft: 0,
      lastTaskCompletedTime: 1748972106739
    }
  }
}

Workspace

Namespace: sdk.api.workspace

`createWorkspace`

Creates a new Velt workspace.
Params: CreateWorkspaceRequest
Returns: VeltApiResponse

await sdk.api.workspace.createWorkspace({
  ownerEmail: 'owner@example.com',
  workspaceName: 'My Workspace',
  name: 'John Doe',
});

Response

{ result: { status: 'success', message: 'Workspace created successfully.', data: {} } }

`getWorkspace`

Retrieves details for the current workspace.
Params: empty object {}
Returns: GetWorkspaceResponse

await sdk.api.workspace.getWorkspace({});

Response

{
  result: {
    status: 'success',
    message: 'Workspace retrieved successfully.',
    data: {
      id: 'workspace_abc123',
      name: 'My Workspace',
      owner: { email: 'owner@example.com', id: 'owner_id_123', name: 'John Doe', avatar: '' },
      authToken: 'eyJhbGciOiJSUzI1NiIs...',
      apiKeyList: {
        velt_api_key_1: { apiKeyName: 'John Doe Test API Key', id: 'velt_api_key_1', type: 'testing' }
      }
    }
  }
}

`createApiKey`

Creates a new API key for the workspace.
Params: CreateApiKeyRequest
Returns: VeltApiResponse

await sdk.api.workspace.createApiKey({
  ownerEmail: 'owner@example.com',
  type: 'production',
  createAuthToken: true,
  apiKeyName: 'Production Key',
  allowedDomains: ['example.com', '*.example.com'],
});

Response

{
  result: {
    status: 'success',
    message: 'API key created successfully.',
    data: { apiKey: 'velt_api_key_2', authToken: 'eyJhbGciOi...' }
  }
}

`updateApiKey`

Renames an existing API key.
Params: UpdateApiKeyRequest
Returns: VeltApiResponse

await sdk.api.workspace.updateApiKey({ apiKey: 'velt_api_key_1', apiKeyName: 'Renamed Key' });

Response

{ result: { status: 'success', message: 'API key updated successfully.', data: {} } }

`getApiKeys`

Lists all API keys with optional pagination.
Params: GetApiKeysRequest
Returns: GetApiKeysResponse

await sdk.api.workspace.getApiKeys({ pageSize: 50, pageToken: 'next-page-token' });

Response

{
  result: {
    status: 'success',
    message: 'API keys retrieved successfully.',
    data: [
      { id: 'velt_api_key_1', apiKeyName: 'Production Key', type: 'production' },
      { id: 'velt_api_key_2', apiKeyName: 'Testing Key', type: 'testing' }
    ],
    nextPageToken: 'eyJsYXN0SWQiOiJ2ZWx0X2FwaV9rZXlfMiJ9'
  }
}

`getApiKeyMetadata`

Gets metadata for the current API key.
Now posts to /v2/workspace/apikeyconfig/get (previously /v2/workspace/apikeymetadata/get); the method name and signature (GetApiKeyMetadataRequest, which is {}) are unchanged — no caller changes required.
Params: empty object {}
Returns: GetApiKeyMetadataResponse

await sdk.api.workspace.getApiKeyMetadata({});

Response

{
  result: {
    status: 'success',
    message: 'API key metadata retrieved successfully.',
    data: {
      defaultDocumentAccessType: 'public',
      planInfo: { type: 'sdk test' },
      ownerEmail: 'owner@example.com'
    }
  }
}

`resetAuthToken`

Rotates the auth token for an API key.
Params: ResetAuthTokenRequest
Returns: VeltApiResponse

await sdk.api.workspace.resetAuthToken({ apiKey: 'velt_api_key_1' });

Response

{
  result: {
    status: 'success',
    message: 'Auth token reset successfully.',
    data: { authToken: 'eyJhbGciOi...' }
  }
}

`getAuthTokens`

Lists auth tokens for an API key.
Params: GetAuthTokensRequest
Returns: GetAuthTokensResponse

await sdk.api.workspace.getAuthTokens({ apiKey: 'velt_api_key_1' });

Response

{
  result: {
    status: 'success',
    message: 'Auth tokens retrieved successfully.',
    data: {
      apiKey: 'velt_api_key_1',
      authTokens: [
        { token: 'eyJhbGciOiJSUzI1NiIs...', name: 'Default Auth Token', domains: [] }
      ]
    }
  }
}

`addDomains`

Adds allowed domains to the workspace allow-list.
Params: AddDomainsRequest
Returns: VeltApiResponse

await sdk.api.workspace.addDomains({ domains: ['example.com', '*.firebase.com'] });

Response

{ result: { status: 'success', message: 'Domains added successfully.', data: {} } }

`deleteDomains`

Removes allowed domains.
Params: DeleteDomainsRequest
Returns: VeltApiResponse

await sdk.api.workspace.deleteDomains({ domains: ['example.com'] });

Response

{ result: { status: 'success', message: 'Domains deleted successfully.', data: {} } }

`getDomains`

Lists allowed domains.
Params: empty object {}
Returns: GetDomainsResponse

await sdk.api.workspace.getDomains({});

Response

{
  result: {
    status: 'success',
    message: 'Allowed domains retrieved successfully.',
    data: { allowedDomains: ['localhost', '127.0.0.1', 'example.com'] }
  }
}

`getEmailStatus`

Checks email verification status for an owner.
Params: GetEmailStatusRequest
Returns: GetEmailStatusResponse

await sdk.api.workspace.getEmailStatus({ ownerEmail: 'owner@example.com' });

Response

{
  result: {
    status: 'success',
    message: 'Email verified and workspace reactivated',
    data: { verified: true }
  }
}

`sendLoginLink`

Sends a passwordless login link to a user.
Params: SendLoginLinkRequest
Returns: VeltApiResponse

await sdk.api.workspace.sendLoginLink({
  email: 'user@example.com',
  continueUrl: 'https://app.example.com/dashboard',
});

Response

{ result: { status: 'success', message: 'Login link sent.', data: {} } }

`getEmailConfig`

Retrieves email service configuration.
Params: empty object {}
Returns: GetEmailConfigResponse

await sdk.api.workspace.getEmailConfig({});

Response

{
  result: {
    status: 'success',
    message: 'Email configuration retrieved successfully.',
    data: {
      useEmailService: false,
      emailServiceConfig: { type: 'default', apiKey: '', fromEmail: '', fromCompany: '', commentTemplateId: '', tagTemplateId: '' }
    }
  }
}

`updateEmailConfig`

Updates email service configuration.
Params: UpdateEmailConfigRequest
Returns: VeltApiResponse

await sdk.api.workspace.updateEmailConfig({
  useEmailService: true,
  emailServiceConfig: { type: 'sendgrid', apiKey: 'sg-key', fromEmail: 'noreply@example.com' },
});

Response

{ result: { status: 'success', message: 'Email config updated successfully.', data: {} } }

`getWebhookConfig`

Retrieves webhook configuration.
Params: empty object {}
Returns: GetWebhookConfigResponse

await sdk.api.workspace.getWebhookConfig({});

Response

{
  result: {
    status: 'success',
    message: 'Webhook configuration retrieved successfully.',
    data: {
      useWebhookService: false,
      webhookServiceConfig: { authToken: '', rawNotificationUrl: '', processedNotificationUrl: '' }
    }
  }
}

`updateWebhookConfig`

Updates webhook configuration.
Params: UpdateWebhookConfigRequest
Returns: VeltApiResponse

await sdk.api.workspace.updateWebhookConfig({
  useWebhookService: true,
  webhookServiceConfig: {
    authToken: 'webhook-secret',
    rawNotificationUrl: 'https://example.com/webhook/raw',
    processedNotificationUrl: 'https://example.com/webhook/processed',
  },
});

Response

{ result: { status: 'success', message: 'Webhook config updated successfully.', data: {} } }

`getRequestedDomains`

List requested additional domains.
Params: GetRequestedDomainsRequest
Returns: VeltApiResponse

await sdk.api.workspace.getRequestedDomains({});

Response

{ result: { status: 'success', message: 'Requested domains retrieved successfully.', data: [] } }

`acceptRejectAdditionalUrlRequest`

Accept/reject an additional-URL request.
Params: AcceptRejectAdditionalUrlRequest
Returns: VeltApiResponse

await sdk.api.workspace.acceptRejectAdditionalUrlRequest({ action: 'accept', id: 'req-1', clientDocId: 'doc-1' });

Response

{ result: { status: 'success', message: 'Additional URL request updated successfully.', data: {} } }

`createDomainRequest`

Create a domain request.
Params: CreateDomainRequest
Returns: VeltApiResponse

await sdk.api.workspace.createDomainRequest({ domain: 'https://example.com', clientDocumentId: 'doc-1', organizationId: 'org-123' });

Response

{ result: { status: 'success', message: 'Domain request created successfully.', data: {} } }

`copyApiKey`

Copy configuration from one API key to another.
Params: CopyApiKeyRequest
Returns: VeltApiResponse

await sdk.api.workspace.copyApiKey({ sourceApiKey: 'velt_api_key_1', targetApiKey: 'velt_api_key_2' });

Response

{ result: { status: 'success', message: 'API key configuration copied successfully.', data: {} } }

`updateApiKeyConfig`

Update API key config (private comments, JWT, AI model keys, etc.).
Params: UpdateApiKeyConfigRequest
Returns: VeltApiResponse

await sdk.api.workspace.updateApiKeyConfig({ requireJwtToken: true, defaultDocumentAccessType: 'organizationPrivate' });

Response

{ result: { status: 'success', message: 'API key config updated successfully.', data: {} } }

`getNotificationConfig`

Get workspace notification service config.
Params: GetWorkspaceNotificationConfigRequest
Returns: VeltApiResponse

await sdk.api.workspace.getNotificationConfig({});

Response

{ result: { status: 'success', message: 'Notification config retrieved successfully.', data: {} } }

`updateNotificationConfig`

Update notification service config.
Params: UpdateWorkspaceNotificationConfigRequest
Returns: VeltApiResponse

await sdk.api.workspace.updateNotificationConfig({ useNotificationService: true });

Response

{ result: { status: 'success', message: 'Notification config updated successfully.', data: {} } }

`getPermissionProviderConfig`

Get permission-provider config.
Params: GetPermissionProviderConfigRequest
Returns: VeltApiResponse

await sdk.api.workspace.getPermissionProviderConfig({});

Response

{ result: { status: 'success', message: 'Permission provider config retrieved successfully.', data: {} } }

`updatePermissionProviderConfig`

Update permission-provider config.
Params: UpdatePermissionProviderConfigRequest
Returns: VeltApiResponse

await sdk.api.workspace.updatePermissionProviderConfig({ usePermissionProvider: true });

Response

{ result: { status: 'success', message: 'Permission provider config updated successfully.', data: {} } }

`getActivityConfig`

Get activity service config.
Params: GetActivityConfigRequest
Returns: VeltApiResponse

await sdk.api.workspace.getActivityConfig({});

Response

{ result: { status: 'success', message: 'Activity config retrieved successfully.', data: {} } }

`updateActivityConfig`

Update activity service config.
Params: UpdateActivityConfigRequest
Returns: VeltApiResponse

await sdk.api.workspace.updateActivityConfig({ activityServiceConfig: { isEnabled: true } });

Response

{ result: { status: 'success', message: 'Activity config updated successfully.', data: {} } }

`ensureWorkspaceAuthToken`

Ensure a workspace auth token exists.
Params: EnsureWorkspaceAuthTokenRequest
Returns: VeltApiResponse

await sdk.api.workspace.ensureWorkspaceAuthToken({});

Response

{ result: { status: 'success', message: 'Workspace auth token ensured successfully.', data: { authToken: 'eyJhbGciOi...' } } }

`getAdvancedWebhookConfig`

Get advanced webhook config.
Params: GetAdvancedWebhookConfigRequest
Returns: VeltApiResponse

await sdk.api.workspace.getAdvancedWebhookConfig({});

Response

{ result: { status: 'success', message: 'Advanced webhook config retrieved successfully.', data: {} } }

`updateAdvancedWebhookConfig`

Update advanced webhook config.
Params: UpdateAdvancedWebhookConfigRequest
Returns: VeltApiResponse

await sdk.api.workspace.updateAdvancedWebhookConfig({ isEnabled: true });

Response

{ result: { status: 'success', message: 'Advanced webhook config updated successfully.', data: {} } }

`getAdvancedWebhookEndpoints`

List advanced webhook endpoints (paged).
Params: GetAdvancedWebhookEndpointsRequest
Returns: VeltApiResponse

await sdk.api.workspace.getAdvancedWebhookEndpoints({});

Response

{
  result: {
    status: 'success',
    message: 'Advanced webhook endpoints retrieved successfully.',
    data: [{ id: 'endpoint-1', url: 'https://example.com/webhooks/velt' }],
    nextPageToken: 'pageToken'
  }
}

`createAdvancedWebhookEndpoint`

Create an advanced webhook endpoint.
Params: CreateAdvancedWebhookEndpointRequest
Returns: VeltApiResponse

await sdk.api.workspace.createAdvancedWebhookEndpoint({ url: 'https://example.com/webhooks/velt', filterTypes: ['comment.added', 'comment.resolved'] });

Response

{ result: { status: 'success', message: 'Advanced webhook endpoint created successfully.', data: { id: 'endpoint-1' } } }

`updateAdvancedWebhookEndpoint`

Update an advanced webhook endpoint.
Params: UpdateAdvancedWebhookEndpointRequest
Returns: VeltApiResponse

await sdk.api.workspace.updateAdvancedWebhookEndpoint({ endpointId: 'endpoint-1', url: 'https://example.com/webhooks/velt-v2' });

Response

{ result: { status: 'success', message: 'Advanced webhook endpoint updated successfully.', data: {} } }

`deleteAdvancedWebhookEndpoint`

Delete an advanced webhook endpoint.
Params: DeleteAdvancedWebhookEndpointRequest
Returns: VeltApiResponse

await sdk.api.workspace.deleteAdvancedWebhookEndpoint({ endpointId: 'endpoint-1' });

Response

{ result: { status: 'success', message: 'Advanced webhook endpoint deleted successfully.', data: {} } }

`getAdvancedWebhookEndpointSecret`

Get an endpoint’s signing secret.
Params: GetAdvancedWebhookEndpointSecretRequest
Returns: VeltApiResponse

await sdk.api.workspace.getAdvancedWebhookEndpointSecret({ endpointId: 'endpoint-1' });

Response

{ result: { status: 'success', message: 'Endpoint secret retrieved successfully.', data: { secret: 'whsec_...' } } }

Custom agent config supports the rest-api context-gathering strategy and the mcp-tools execution strategy. Secret-bearing REST API and MCP auth fields are encrypted at rest and redacted on read paths. Create and update-version payloads reject server-managed fields such as managedBy, metadata.type, metadata.category, metadata.internal, and metadata.apiKey; strategies that require instructions (ai, service+ai, stagehand-agent) reject empty instructions.

Approval Workflows

Namespace: sdk.api.approval A new service for defining approval/review workflows (graphs of agent, human, webhook, and notification nodes) and dispatching/resolving their executions and steps. 14 methods (routes live under /v2/workflow/*). Every type is Approval-prefixed. ApprovalService is also exported directly from @veltdev/node.

Routing and loops

Routing is expressed entirely as edges. Each edge carries a semantic on role — 'approve', 'reject', 'custom' (with a when predicate), or 'exhausted' — and endpoints may be a bare node ID or an object targeting a node or a parallel group. Loops are edges too: an on: 'reject' back-edge carrying a loop object sends work back for rework with an iteration cap.

edges: [
  { from: 'draft', to: 'review', on: 'approve' },
  // Send rejected work back to 'draft', at most 3 times.
  { from: 'review', to: 'draft', on: 'reject', loop: { maxIterations: 3 } },
  // Fan out from a node into a parallel group on a custom predicate.
  {
    from: { kind: 'node', nodeId: 'review' },
    to: { kind: 'group', groupId: 'legal-and-brand' },
    on: 'custom',
    when: "output.decision == 'escalate'",
  },
]

Notification nodes

A notification node sends a formatted email or Slack message built from upstream step output.

nodes: [
  {
    nodeId: 'notify-ops',
    type: 'notification',
    config: {
      channel: 'slack',
      slackTarget: 'C0123456',           // channel ID or an incoming-webhook URL
      bodyTemplate: 'Review completed for {{document.title}}',
      format: 'slack-blocks',
    },
  },
]

recipients is required when channel is 'email'; slackTarget is required when it is 'slack'. format accepts 'text', 'html', or 'slack-blocks' — the last is valid only for Slack.

Triggers

A trigger starts an execution. Each trigger drives at most one mechanism — inboundWebhook, schedule, and appTrigger are mutually exclusive, and the API rejects a trigger that combines them.

triggers: [
  // Run on a cron schedule, in a named IANA timezone.
  {
    triggerId: 'weekly-audit',
    schedule: { cron: '0 9 * * 1', timezone: 'America/New_York', enabled: true },
  },
  // Start from a connected GitHub App or Vercel Integration.
  {
    triggerId: 'deploy-gate',
    appTrigger: {
      provider: 'github',
      installationRef: '41234567',
      repoFilter: ['acme/web', 'acme/api'],
      allowedEvents: ['workflow_run'],
      // Fire only when ALL payload filters match.
      payloadFilters: [
        { path: 'workflow_run.name', in: ['deploy'] },
        { path: 'workflow_run.conclusion', in: ['success'] },
      ],
    },
  },
]

An appTrigger carries no secret — the connected app is authenticated at the app-level webhook. payloadFilters resolve dot-paths against the provider’s raw webhook body, so you can gate on a specific workflow name plus its conclusion.

`createDefinition`

Create a workflow definition (nodes, edges, groups, triggers).
Params: ApprovalCreateDefinitionRequest
Returns: VeltApiResponse

await sdk.api.approval.createDefinition({
  definitionId: 'doc-publish-review',
  name: 'Document Publish Review',
  scope: { level: 'organization', organizationId: 'org-123' },
  nodes: [
    { nodeId: 'review', type: 'human', config: { reviewers: [{ userId: 'user-1', mandatory: true }], commentBody: 'Please review before publishing.' } },
    { nodeId: 'rework', type: 'agent', config: { agentId: '__mock__', urlPath: 'documentUrl' } },
  ],
  edges: [{ from: 'review', to: 'rework', on: 'reject' }],
});

`updateDefinition`

Update a definition (create shape + optimistic ifVersion).
Params: ApprovalUpdateDefinitionRequest
Returns: VeltApiResponse

await sdk.api.approval.updateDefinition({
  definitionId: 'doc-publish-review',
  name: 'Document Publish Review v2',
  nodes: [
    { nodeId: 'review', type: 'human', config: { reviewers: [{ userId: 'user-1', mandatory: true }], commentBody: 'Please review before publishing.' } },
    { nodeId: 'rework', type: 'agent', config: { agentId: '__mock__', urlPath: 'documentUrl' } },
  ],
  edges: [{ from: 'review', to: 'rework', on: 'reject' }],
  ifVersion: 1,
});

`deleteDefinition`

Delete a definition.
Params: ApprovalDeleteDefinitionRequest
Returns: VeltApiResponse

await sdk.api.approval.deleteDefinition({ definitionId: 'doc-publish-review' });

// Hard-delete the definition document and its version snapshots.
await sdk.api.approval.deleteDefinition({ definitionId: 'doc-publish-review', purge: true });

By default a delete leaves a tombstone. purge: true removes the definition and its version snapshots outright. Both paths free the definition ID for re-creation, and the response echoes purged so you can tell which ran.

`getDefinition`

Get a single definition.
Params: ApprovalGetDefinitionRequest
Returns: VeltApiResponse

await sdk.api.approval.getDefinition({ definitionId: 'doc-publish-review' });

`listDefinitions`

List definitions (paged).
Params: ApprovalListDefinitionsRequest
Returns: VeltApiResponse

await sdk.api.approval.listDefinitions({});

`dispatchExecution`

Dispatch (start) an execution of a definition.
Params: ApprovalDispatchExecutionRequest
Returns: VeltApiResponse

const exec = await sdk.api.approval.dispatchExecution({ definitionId: 'doc-publish-review', organizationId: 'org-123', documentId: 'doc-1' });

`cancelExecution`

Cancel a running execution.
Params: ApprovalCancelExecutionRequest
Returns: VeltApiResponse

await sdk.api.approval.cancelExecution({ executionId: 'exec-1' });

`getExecution`

Get a single execution.
Params: ApprovalGetExecutionRequest
Returns: VeltApiResponse

await sdk.api.approval.getExecution({ executionId: 'exec-1' });

`getExecutionEvents`

Get a page of an execution’s lifecycle events.
Params: ApprovalGetExecutionEventsRequest
Returns: VeltApiResponse

await sdk.api.approval.getExecutionEvents({ executionId: 'exec-1' });

`listExecutions`

List executions.
Params: ApprovalListExecutionsRequest
Returns: VeltApiResponse

await sdk.api.approval.listExecutions({});

`cancelStep`

Admin step-level cancel.
Params: ApprovalCancelStepRequest
Returns: VeltApiResponse

await sdk.api.approval.cancelStep({ executionId: 'exec-1', stepId: 'review', actorId: 'user-1' });

`resolveStep`

Admin force-resolve a hung step.
Params: ApprovalResolveStepRequest
Returns: VeltApiResponse

await sdk.api.approval.resolveStep({ executionId: 'exec-1', stepId: 'review', action: 'force-approve', actorId: 'user-1' });

`recordAgentResolution`

Record one resolution against a blocking-agent step’s aggregator.
Params: ApprovalRecordAgentResolutionRequest
Returns: VeltApiResponse

await sdk.api.approval.recordAgentResolution({ executionId: 'exec-1', stepId: 'review', responseId: 'resp-1', resolution: 'resolved', actorId: 'user-1' });

`recordReviewerDecision`

Record one reviewer’s decision against a human step’s aggregator.
Params: ApprovalRecordReviewerDecisionRequest
Returns: VeltApiResponse

await sdk.api.approval.recordReviewerDecision({ executionId: 'exec-1', stepId: 'review', reviewerId: 'user-1', decision: 'approve' });

Node & Graph Types

These node/graph/config interfaces are referenced by the request types above. They are not standalone data-model entries.

type JsonAst = Record<string, unknown>;
interface ApprovalScope { level: 'apiKey' | 'organization' | 'document'; organizationId?: string; documentId?: string; }
interface ApprovalAgentResolutionPolicy { kind: 'allResolved' | 'minResolved'; minCount?: number; } // minCount req. when 'minResolved' (1..500)
interface ApprovalAgentNodeConfig { agentId: string; urlPath: string; /* 1..500 */ crossPageExecute?: boolean; maxUrlsToProcess?: number; /* positive int, max 500 */ userContextMapping?: Record<string, string>; pollIntervalMs?: number; /* 5000..60000 */ promptOverride?: string; /* max 8000 */ inputMapping?: Record<string, string>; requireNonEmptyOutput?: boolean; agentMaxRuntimeMs?: number; /* positive int, max 24h */ blocking?: boolean; resolutionPolicy?: ApprovalAgentResolutionPolicy; /* required when blocking */ }
interface ApprovalHumanReviewer { userId: string; mandatory: boolean; }
interface ApprovalHumanNodeConfig { reviewerIds?: string[]; /* mutually exclusive with reviewers; 1..50 */ reviewers?: ApprovalHumanReviewer[]; /* unique userIds; >=1 mandatory; 1..50 */ reviewerEmails?: string[]; /* max 50 */ commentBody?: string; /* max 8000 */ } // reject path is an outgoing on:'reject' edge
interface ApprovalWebhookNodeConfig { url: string; /* https, allowed host, max 2000 */ method?: 'GET' | 'POST'; mode?: 'sync' | 'async'; authMode?: 'hmac' | 'token' | 'none'; authTokenHeader?: string; /* required when authMode === 'token'; max 500 */ timeoutMs?: number; /* 1000..60000 */ expectedStatusCodes?: number[]; /* each 100..599; max 20 */ bodyTemplate?: 'envelope' | 'pass-through' | 'none'; /* 'none' requires method GET */ requestHeaders?: Record<string, string>; /* reserved/x-velt-* headers rejected; values max 2000 */ }
interface ApprovalAgentNode { nodeId: string; type: 'agent'; config: ApprovalAgentNodeConfig; slaMs?: number; requireNonEmptyOutput?: boolean; name?: string; /* 1..200 */ description?: string; /* max 2000 */ }
interface ApprovalHumanNode { nodeId: string; type: 'human'; config: ApprovalHumanNodeConfig; slaMs?: number; requireNonEmptyOutput?: boolean; name?: string; /* 1..200 */ description?: string; /* max 2000 */ }
interface ApprovalWebhookNode { nodeId: string; type: 'webhook'; config: ApprovalWebhookNodeConfig; slaMs?: number; requireNonEmptyOutput?: boolean; name?: string; /* 1..200 */ description?: string; /* max 2000 */ }
type ApprovalNode = ApprovalAgentNode | ApprovalHumanNode | ApprovalWebhookNode;
type ApprovalEdgeEndpoint = string | { kind: 'node'; nodeId: string } | { kind: 'group'; groupId: string };
interface ApprovalEdge { from: ApprovalEdgeEndpoint; to: ApprovalEdgeEndpoint; on?: 'approve' | 'reject' | 'always' | 'exhausted' | 'custom'; /* default 'always' */ when?: string; /* JSON-AST; only valid when on==='custom' */ loop?: { maxIterations: number /* 1..20 */ }; /* only on an on:'reject' back-edge */ }
type ApprovalQuorumPolicy = 'waitAll' | 'cancelOnQuorum' | 'joinOnQuorum';
interface ApprovalGroup { groupId: string; /* 1..64 */ memberNodeIds: string[]; /* 1..500 */ expectedSteps: number; /* 1..500 */ quorum: number; /* 1..500 */ onQuorumMet?: ApprovalQuorumPolicy; requiredNodeIds?: string[]; /* max 500 */ }
interface ApprovalCompiledForwardEdge { from: string; to: string; role: 'approve' | 'reject' | 'always' | 'exhausted' | 'custom'; when: JsonAst | null; fromGroupId?: string; toGroupId?: string; }
interface ApprovalCompiledLoop { loopId: string; entryNodeId: string; bodyNodeIds: string[]; maxIterations: number; onExhausted: { routeToNodeId: string } | null; }
interface ApprovalCompiledGraph { forwardEdges: ApprovalCompiledForwardEdge[]; loops: ApprovalCompiledLoop[]; } // read-only on DefinitionView responses
interface ApprovalInboundWebhookTrigger { authMode: 'hmac' | 'bearer'; secret: string; /* 16..512 */ idempotencyHeader?: string; /* 1..128 */ idempotencyBodyPath?: string; /* 1..256 */ payloadMapping?: 'pass-through' | 'wrap'; }
interface ApprovalTrigger { triggerId: string; /* 1..128 */ eventName?: string; /* max 128 */ filters?: Record<string, unknown>; inboundWebhook?: ApprovalInboundWebhookTrigger; }
interface ApprovalWebhookConfig { url: string; secret: string; eventTypes?: string[]; } // url https/max2000; secret 16..512; eventTypes each 1..128, max 50

Error Handling

The SDK exports five typed error classes:

Class	Extends	When thrown
`VeltSDKError`	`Error`	Base class for all SDK errors
`VeltDatabaseError`	`VeltSDKError`	Database connection or query failures
`VeltValidationError`	`VeltSDKError`	Missing or invalid request parameters
`VeltTokenError`	`VeltSDKError`	Token generation failures
`VeltApiError`	`VeltSDKError`	REST API call failures

import { VeltSDK, VeltDatabaseError, VeltApiError } from '@veltdev/node';

try {
  const result = await sdk.api.organizations.getOrganizations({ organizationIds: ['org-123'] });
} catch (err) {
  if (err instanceof VeltApiError) {
    console.error('API call failed:', err.message);
  } else if (err instanceof VeltDatabaseError) {
    console.error('Database error:', err.message);
  } else {
    throw err;
  }
}

Common self-hosting error codes returned in the response errorCode field:

INVALID_INPUT — Request data is malformed or missing required fields
INTERNAL_ERROR — Server-side error during processing
NOT_FOUND — Requested resource was not found

Data Models

Key interfaces and serializer helpers exported from @veltdev/node. All symbols are available at the package top level:

import {
  PartialCommentAnnotation, partialCommentAnnotationFromDict, partialCommentAnnotationToDict,
  PartialTargetTextRange, partialTargetTextRangeFromDict, partialTargetTextRangeToDict,
  PartialComment, partialCommentFromDict, partialCommentToDict,
  BaseMetadata, baseMetadataFromDict, baseMetadataToDict,
} from '@veltdev/node';

PartialUser and PartialAttachment referenced in the interfaces below are minimal pass-through shapes. PartialUser is { userId: string } (any additional fields the frontend sends are preserved but not strongly typed). Full user/attachment shapes are documented in the central Data Models reference.

PartialCommentAnnotation

Represents a single comment annotation thread. Used as the payload shape when reading or writing annotation data in self-hosting event handlers.

interface PartialCommentAnnotation {
  annotationId: string;
  metadata?: BaseMetadata;
  comments?: Record<string, PartialComment>;
  from?: PartialUser;              // Typed in v1.0.2; previously pass-through
  assignedTo?: PartialUser;        // Typed in v1.0.2; previously pass-through
  targetTextRange?: PartialTargetTextRange;  // Typed in v1.0.2; previously pass-through
  resolvedByUserId?: string | null; // Three-state — see resolvedByUserId Semantics below
  [key: string]: unknown;          // Unknown keys are preserved on round-trip
}

Field	Type	Notes
`annotationId`	`string`	Required. Stable identifier for the annotation thread.
`metadata`	`BaseMetadata`	Optional context (document, org, API key).
`comments`	`Record<string, PartialComment>`	Keyed by `commentId` string.
`from`	`PartialUser`	User who created the annotation.
`assignedTo`	`PartialUser`	User currently assigned to the annotation.
`targetTextRange`	`PartialTargetTextRange`	Text selection the annotation is anchored to.
`resolvedByUserId`	`string \| null`	Three-state field — see below.
`[key]`	`unknown`	Extra keys pass through serialization unchanged.

Serializers:

declare function partialCommentAnnotationFromDict(data: Record<string, unknown>): PartialCommentAnnotation;
declare function partialCommentAnnotationToDict(annotation: PartialCommentAnnotation): Record<string, unknown>;

PartialTargetTextRange

The text selection an annotation is anchored to. New interface in v1.0.2.

interface PartialTargetTextRange {
  text: string;
}

Field	Type	Notes
`text`	`string`	Required. The selected text content the annotation references.

Serializers:

declare function partialTargetTextRangeFromDict(data: Record<string, unknown>): PartialTargetTextRange;
declare function partialTargetTextRangeToDict(range: PartialTargetTextRange): Record<string, unknown>;

resolvedByUserId Semantics

resolvedByUserId on PartialCommentAnnotation is a three-state field. TypeScript has no sentinel value, so the three states map to property presence and value:

State	Representation	Meaning
Absent	Property not set on the object	No resolution information — do not write to the database
Explicit `null`	`resolvedByUserId: null`	Annotation was un-resolved (cleared)
String	`resolvedByUserId: "user-123"`	Resolved by the user with this ID

Use Object.hasOwn (or 'resolvedByUserId' in annotation) to distinguish absent from explicit null:

const annotation = partialCommentAnnotationFromDict(payload);

if (!Object.hasOwn(annotation, 'resolvedByUserId')) {
  // Field absent — skip; do not overwrite existing resolution state
} else if (annotation.resolvedByUserId === null) {
  // Explicit null — un-resolve the annotation
} else {
  // String — mark resolved by annotation.resolvedByUserId
}

PartialComment

A single comment within an annotation thread. Round-trip serializers preserve unknown keys, so custom fields added by your application are not dropped.

interface PartialComment {
  commentId: string | number;
  commentHtml?: string;
  commentText?: string;
  attachments?: Record<string, PartialAttachment>;
  from?: PartialUser;
  to?: PartialUser[];
  taggedUserContacts?: PartialTaggedUserContacts[];
  [key: string]: unknown;   // Pass-through for unknown keys
}

Field	Type	Notes
`commentId`	`string \| number`	Required. Unique within the annotation.
`commentHtml`	`string`	Raw HTML body of the comment.
`commentText`	`string`	Plain-text body, used for search and notifications.
`attachments`	`Record<string, PartialAttachment>`	Keyed by attachment ID.
`from`	`PartialUser`	Author of the comment.
`to`	`PartialUser[]`	Explicit recipients (direct-mention replies).
`taggedUserContacts`	`PartialTaggedUserContacts[]`	Users @-mentioned in the comment body.
`[key]`	`unknown`	Extra keys pass through serialization unchanged.

Serializers (new in v1.0.2):

declare function partialCommentFromDict(data: Record<string, unknown>): PartialComment;
declare function partialCommentToDict(comment: PartialComment): Record<string, unknown>;

BaseMetadata

Contextual identifiers attached to annotations and events. Provides both Velt-internal IDs and your application’s client-facing IDs for the same resources.

interface BaseMetadata {
  apiKey?: string;
  documentId?: string;
  clientDocumentId?: string;
  organizationId?: string;
  clientOrganizationId?: string;
  folderId?: string;
  veltFolderId?: string;
  documentMetadata?: Record<string, unknown>;
  sdkVersion?: string | null;   // New in v1.0.2
}

Field	Type	Notes
`apiKey`	`string`	Velt project API key.
`documentId`	`string`	Velt-internal document identifier.
`clientDocumentId`	`string`	Your application’s document identifier.
`organizationId`	`string`	Velt-internal organization identifier.
`clientOrganizationId`	`string`	Your application’s organization identifier.
`folderId`	`string`	Your application’s folder identifier.
`veltFolderId`	`string`	Velt-internal folder identifier.
`documentMetadata`	`Record<string, unknown>`	Arbitrary key-value metadata attached to the document.
`sdkVersion`	`string \| null`	SDK version string. `null` means version is known to be absent. New in v1.0.2.

Serializers (exposed on public surface in v1.0.2):

declare function baseMetadataFromDict(data: Record<string, unknown>): BaseMetadata;
declare function baseMetadataToDict(meta: BaseMetadata): Record<string, unknown>;

Distribution

The package ships both CommonJS (CJS) and ES Module (ESM) bundles with rolled-up .d.ts type definitions, making it compatible with all modern Node.js project setups.

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

// CommonJS
const { VeltSDK } = require('@veltdev/node');

​Overview

​Installation

​Requirements

​Quick Start

​Initialize the SDK

​Shutdown

​Configuration

​Environment Variables

​Self-Hosting Configuration

​Self-Hosting Backend

​Comments

​getComments

​saveComments

​deleteComment

​Reactions

​getReactions

​saveReactions

​deleteReaction

​Attachments

​getAttachment

​saveAttachment

​deleteAttachment

​Users

​getUsers

​resolveUserIdsByEmail

​Recorder

​getRecorderAnnotations

​saveRecorderAnnotation

​deleteRecorderAnnotation

​Notifications

​getNotifications

​saveNotifications

​deleteNotification

​Activities

​getActivities

​saveActivities

​verifyToken

​Configuration

​Usage

​Error codes

​Security guarantees

​REST API Backend

​Field Allowlist

​Exported filter utilities

​Allowlisted fields per endpoint

​Organizations

​addOrganizations

​getOrganizations

​updateOrganizations

​deleteOrganizations

​updateOrganizationDisableState

​Folders

​addFolder

​getFolders

​updateFolder

​deleteFolder

​updateFolderAccess

​Documents

​addDocuments

​getDocuments

​updateDocuments

​deleteDocuments

​moveDocuments

​updateDocumentAccess

​updateDocumentDisableState

​migrateDocuments

​migrateDocumentsStatus

​getDocumentsCount

​Users

​addUsers

​getUsers

​updateUsers

​deleteUsers

​getUsersCount

​getDocUsers

​addUserInvite

​respondToUserInvite

​getUserInvites

​getUserInvitations

​getInvitedPendingUsersCount

Overview

Installation

Requirements

Quick Start

Initialize the SDK

Shutdown

Configuration

Environment Variables

Self-Hosting Configuration

Self-Hosting Backend

Comments

`getComments`

`saveComments`

`deleteComment`

Reactions

`getReactions`

`saveReactions`

`deleteReaction`

Attachments

`getAttachment`

`saveAttachment`

`deleteAttachment`

Users

`getUsers`

`resolveUserIdsByEmail`

Recorder

`getRecorderAnnotations`

`saveRecorderAnnotation`

`deleteRecorderAnnotation`

Notifications

`getNotifications`

`saveNotifications`

`deleteNotification`

Activities

`getActivities`

`saveActivities`

verifyToken

Configuration

Usage

Error codes

Security guarantees

REST API Backend

Field Allowlist

Exported filter utilities

Allowlisted fields per endpoint

Organizations

`addOrganizations`

`getOrganizations`

`updateOrganizations`

`deleteOrganizations`

`updateOrganizationDisableState`

Folders

`addFolder`

`getFolders`

`updateFolder`

`deleteFolder`

`updateFolderAccess`

Documents

`addDocuments`

`getDocuments`

`updateDocuments`

`deleteDocuments`

`moveDocuments`

`updateDocumentAccess`

`updateDocumentDisableState`

`migrateDocuments`

`migrateDocumentsStatus`

`getDocumentsCount`

Users

`addUsers`

`getUsers`

`updateUsers`

`deleteUsers`

`getUsersCount`

`getDocUsers`

`addUserInvite`

`respondToUserInvite`

`getUserInvites`

`getUserInvitations`

`getInvitedPendingUsersCount`