Velt Node SDK Changelog

​

New Features

• [REST API]: Added typed response envelopes. VeltApiResponse<TResult> is { result?: TResult; error?: VeltApiErrorBody }; TResult is ApiResult for most services, unknown for memory, Approval*Result for approval (listDefinitions and listExecutions page by nextCursor), and AskAiResult for rewriter.askAi. The envelope types and RestUser are exported from the package root. Learn more →

​

Improvements

• [REST API]: Corrected AccessType to 'public' | 'organizationPrivate' | 'restricted'. The removed values 'private' and 'organizationPublic' were always rejected by the API. Learn more →
• [REST API]: Corrected AccessRole to 'editor' | 'viewer'. REST user fields (addUsers, updateUsers, addPermissions, from, assignedTo, actionUser, notifyUsers) now take RestUser, where each contact needs userId and a role needs id. Learn more →
• [Comments]: Marked Location.id as required. Comment annotation status needs id, name and type ('default' | 'ongoing' | 'terminal'), priority needs id and name, visibility needs organizationId for organizationPrivate and userIds for restricted, and pageInfo needs url and path. Learn more →
• [REST API]: Corrected updateActivities: items are identified by id (activityId stays as a deprecated alias), changes is a record keyed by field name (the 2.0.x type declared it as an array), and a custom activity requires targetEntityId. Learn more →
• [REST API]: Corrected createAgent: description, enabled, contextGathering (with strategies) and execution are required, and instructions unless executionStrategy is 'service'. postProcess.pinResolution is rejected by the API and typed never. Learn more →
• [Access Control]: Corrected getPermissions: at least one of folderIds or documentIds is required. Learn more →
• [REST API]: Replaced the shared User with RestUser in REST user fields (addUsers, updateUsers, addPermissions, from, assignedTo, actionUser, notifyUsers). A variable typed as User must match the RestUser shape before you pass it. Runtime behavior is unchanged.
• [REST API]: Changed ActivityInput and CreateAgentRequest to type aliases (unions). An interface can no longer extends them; use an intersection type instead.
• [REST API]: Deprecated the top-level status, message and nextPageToken on VeltApiResponse. The API never sent them; read result.status, result.message and result.nextPageToken. They are removed in the next major.

​

Bug Fixes

• [REST API]: Fixed createAgent calls that followed the 2.0.x type being rejected for missing fields. The type now matches what the API requires. Learn more →

​

Improvements

• [Self Hosting]: Added a typed context field to PartialCommentAnnotation. Velt client 6.0.17+ sends the TipTap anchor text to the comment resolver as context.textEditorConfig.text and reads it back from getComments; saveComments and getComments pass it through unchanged. No API change. Learn more →

​

Improvements

• [Core]: Corrected the README shipped in the npm package. It now covers PostgreSQL, the optional database drivers, and the install error at initialize(). No API change. Learn more →

​

Breaking Changes

• [Core]: The database driver is now checked at initialize(). A config with a database block fails at startup when its driver is not installed, with the command to run, for example PostgreSQL support requires 'npm install pg'. If you only call sdk.api.*, remove the database block. Learn more →
• [Self Hosting]: saveAttachment now stores a closed set of fields: attachmentId, file, name, mimeType, and metadata with its known keys. Other fields, a top-level url, and null metadata keys are no longer stored, and a save without a file URL or file data returns 400. Learn more →
• [Self Hosting]: An empty organizationId in getComments, getReactions, getRecorderAnnotations, and getNotifications now returns 400 with errorCode: 'INVALID_INPUT'. Learn more →
• [Core]: An unknown database.type now throws at initialize(). A second SDK instance pointed at a different database without await sdk.close() now throws at its first sdk.selfHosting.* call. Learn more →

​

New Features

• [Self Hosting]: Added a PostgreSQL backend. Set database: { type: 'postgresql', connection_string: 'postgresql://...' } and every sdk.selfHosting.* method behaves as it does on MongoDB. Each collection is a table with one JSONB data column; the SDK creates the schema, tables, and indexes on first connection (manage_schema: true). Install pg alongside the SDK. Learn more →
• [Self Hosting]: Added postgresSchemaSql(config), which returns the PostgreSQL DDL for your config. Hand it to a migration role when your application role cannot create tables and you set manage_schema: false. Learn more →
• [Self Hosting]: Added resolveUserIdsByEmail() to the users service. It resolves a list of email addresses to user IDs for the frontend’s anonymous-user data provider and returns a map of email to user ID. Learn more →
• [Self Hosting]: Added sdk.selfHosting.database, which resolves to the connected adapter for the configured database. Use it for a readiness check or to write data the resolvers do not write, such as seeding users. Learn more →
• [Core]: Added REST-only initialization. VeltSDK.initialize({ apiKey, authToken }) without a database block now works and serves sdk.api.*. Learn more →

​

Improvements

• [Core]: Made both database drivers optional peer dependencies. Install @veltdev/node alone for the REST API backend, and add mongodb or pg for self-hosting. Learn more →
• [Self Hosting]: A MongoDB connection_string alone is now enough; the database name comes from its path. An explicit database_name overrides the database in the connection string on both backends. Learn more →
• [Self Hosting]: pool_min_size and pool_max_size now apply to MongoDB as well as PostgreSQL and are validated at initialize(). MongoDB defaults are unchanged. Learn more →

​

Bug Fixes

• [Core]: Fixed import { VeltSDK } from '@veltdev/node' failing on Node 18 and on Node 20 before 20.19. ES module imports now load on every supported Node version. No API change.
• [Self Hosting]: Fixed an issue where two concurrent saves of the same annotation on MongoDB could fail with a duplicate-key error. The losing write is now retried once and both succeed. No API change.

​

Breaking Changes

• Removed request fields that the API does not accept: Seven fields are removed from request types because the API ignored them — they never had the effect their names implied. Each has a documented replacement:

  Removed	From	Use instead
  agentFields	GetCommentAnnotationsRequest, GetCommentAnnotationsCountRequest	The agent filters below (list only; counts do not support agent filtering)
  veltUserIds, veltAllOrganizations	DeleteAllUserDataRequest	The same fields on GetAllUserDataRequest
  resources	AddPermissionsRequest, RemovePermissionsRequest	permissions.resources (nested, as the API expects)
  skipResourceExistenceValidation	AddPermissionsRequest	The same field on GetPermissionsRequest

  No working request changes behaviour — these fields were inert. TypeScript will flag every affected call site at compile time. Learn more →

​

New Features

• Agent filters on getCommentAnnotations: sdk.api.commentAnnotations.getCommentAnnotations() now accepts agentId, executionId, agentType, agentSource, agentSuggestions, and agentComments to scope a listing to agent-authored annotations. Supply at most one per request. Agent filtering is annotation-scoped and requires advanced queries to be enabled on your workspace. Learn more →
• veltUserIds, veltAllOrganizations and uniqueId on getAllUserData: sdk.api.gdpr.getAllUserData() accepts veltUserIds to fetch data for a set of Velt-side user IDs, veltAllOrganizations to span every organization rather than one, and uniqueId as a correlation value echoed back on the response. Learn more →
• skipResourceExistenceValidation on getPermissions: sdk.api.accessControl.getPermissions() accepts skipResourceExistenceValidation to skip the existence check on the supplied folder/document IDs. When false (the default) the API errors if any ID does not resolve. Learn more →

​

Bug Fixes

• Agent-filtered annotation counts no longer return unfiltered totals: getCommentAnnotationsCount() previously accepted an agentFields filter that the API silently ignored, so the returned count covered all annotations rather than the agent-scoped subset — with nothing in the response to indicate it. The count endpoint does not support agent filtering; to count a filtered subset, list with the agent filters above and count the result. Learn more →

​

Breaking Changes

• Approval loop types removed: ApprovalLoop, ApprovalLoopRejectTrigger, ApprovalLoopExhaustionPolicy, ApprovalHumanNodeOnReject, and ApprovalHumanNodeOnRejectLoopBack are removed. Loop regions are no longer part of the workflow definition contract — the API had already been rejecting definitions that carried a loops array or a per-node onReject, so no working definition changes behaviour. Express loops as edges instead: an on: 'reject' back-edge carrying a loop object, for example { from: 'review', to: 'draft', on: 'reject', loop: { maxIterations: 3 } }. Learn more →

​

New Features

• Approval Workflows — notification nodes: New ApprovalNotificationNode and ApprovalNotificationNodeConfig send a formatted email or Slack message built from upstream step output. recipients is required for channel: 'email', slackTarget for channel: 'slack', and format accepts 'text', 'html', or 'slack-blocks' (Slack only). Learn more →
• Approval Workflows — installable-app triggers: New ApprovalAppTrigger binds a definition to a connected GitHub App or Vercel Integration, with repoFilter, projectFilter, allowedEvents, and payloadFilters (ApprovalAppTriggerPayloadFilter) to gate on values inside the provider’s webhook body. A trigger drives at most one mechanism — inboundWebhook, schedule, and appTrigger are mutually exclusive. Learn more →
• Approval Workflows — scheduled triggers: New ApprovalScheduleTrigger starts an execution on a cron schedule, with cron, timezone (IANA), enabled, and an optional static payloadTemplate merged into the dispatched trigger context. Learn more →
• Approval Workflows — purge on deleteDefinition: Pass purge: true to hard-delete a definition and its version snapshots instead of leaving a tombstone. Both paths free the definition ID for re-creation; the response echoes purged so you can tell which ran. Learn more →
• Approval Workflows — static agent-node URLs: Agent nodes accept a static url, and urlPath is relaxed from required to optional. One of the two must be present; url takes precedence when both are supplied. Learn more →
• Comment Annotations — agent-scoped delete filters: deleteCommentAnnotations() accepts agentSuggestions (fresh, unaccepted suggestions), agentId (a specific agent’s annotations), and agentUrls (a list of page URLs, matched as an OR-group). All three combine, so a crawl can delete “this agent’s still-pending suggestions for these pages” without affecting a concurrent batch. They require advanced queries on your workspace; when unavailable the API fails closed rather than widening to a document-wide delete. Learn more →
• Comment Annotations — suggestion payloads: New CommentAnnotationSuggestion and CommentAnnotationSuggestionStatus types, plus pageInfo, on the add and update paths. On add, status is server-owned and always stamped 'pending'; on update (updatedData.suggestion) the object is replaced wholesale and status is honored. documentIds is also accepted on the annotation count request. Learn more →
• Agents — per-execution AI configuration: New AgentAiConfig on an agent’s execution settings (provider, responseMimeType, maxToolTurns), and AgentAiConfigOverride with AgentLlmProvider ('gemini' | 'claude' | 'openai') on runExecution() for per-run overrides including a defaultModels per-provider policy map. The override requires at least one field — an empty object is rejected. Learn more →
• Agents — deviceType and annotationVisibility: runExecution() accepts deviceType ('mobile' | 'desktop', defaults to desktop) to choose the emulated device, and annotationVisibility ('public' | 'private', defaults to private) to control who can see the annotations the run creates. Learn more →
• Agents — partial execution status: AgentExecutionStatus adds 'partial' for a mixed outcome, where the run produced usable results but at least one URL or batch failed. It is distinct from 'error', which is reserved for total failures. Learn more →
• Documents — metadata filters on getDocumentsCount: getDocumentsCount() accepts the same filters array as getDocuments() (up to 10 entries; keys auto-prefixed with metadata. unless already prefixed). It cannot be combined with excludeFolderDocs. When filters are sent the response includes filtersApplied — a false value means the filtered aggregate failed and count is an unfiltered fallback. Learn more →
• Memory — includeRules on searchKnowledge: Set includeRules: true to additionally search the workspace’s extracted-rules corpus and merge those hits with knowledge-chunk results. Each result then carries a kind of 'chunk' or 'rule', and rule hits also carry ruleId and an optional category. Omitting it returns the previous chunk-only shape, and limit becomes the combined cap across both corpora. Learn more →

​

New Features

• CommentResolverSaveEvent enum: New enum with 14 additional non-core comment save events (status change, priority change, assign, approve, comment-level reactions, subscribe/unsubscribe, and more) that the Velt frontend can opt into sending to the save resolver endpoint via ResolverConfig.additionalSaveEvents. The event field on SaveCommentResolverRequest is widened from ResolverActions to ResolverActions | CommentResolverSaveEvent | string — fully additive, so every existing value remains assignable. New export from @veltdev/node. Learn more →
• targetComment on SaveCommentResolverRequest: New optional targetComment?: PartialComment field carrying the comment the action occurred on, resolved by the frontend from commentId. It is request context for your handler only and is never persisted by saveComments. Learn more →
• Resolver token verify helper (sdk.selfHosting.verifyToken): New fail-closed helper that verifies the auth credential the Velt frontend forwards to endpoint-based resolvers. The helper itself does not open or query MongoDB; in @veltdev/node@1.0.7, VeltSDK.initialize still validates the top-level database config before you can access sdk.selfHosting. Supports built-in JWT/JWKS verification (via the optional jose peer dependency, pinned to ^5 for Node 18) and custom callbacks, and is authentication only — it never makes an authorization decision. Configured via the new optional resolverAuth on VeltConfig. New exports: VerifyTokenResult, RESOLVER_AUTH_ERROR_CODES, ResolverAuthErrorCode, ResolverAuthConfig, ResolverAuthJwtConfig, ResolverAuthVerifyCallback, ResolverAuthService. Learn more →

​

Breaking Changes

• PartialReactionAnnotation.user renamed to from: The reacting-user field on PartialReactionAnnotation is renamed from user to from, matching the Velt frontend SDK’s PartialReactionAnnotation.from (and ReactionAnnotation.from). This affects self-hosting reaction resolvers (sdk.selfHosting.getReactions()): saveReactions() now persists the reacting user under from, and resolved reactions expose from. Code that reads or writes the reacting user must use from instead of user. Learn more →

​

New Features

• Opt-in field allowlist for REST add/update methods: The add/update methods on activities, commentAnnotations (including comment-level add/update), and notifications now accept an optional FieldFilterOptions second argument. Passing { filterUnknownFields: true } narrows the request to exactly the fields the backend endpoint accepts and silently drops unknown keys. It is off by default, fail-open (a filter error never blocks a write), and top-level scoped, so nested open-typed objects like actionUser and context pass through whole. Learn more →
• New field-allowlist exports: A new field-allowlist module exported from @veltdev/node exposes the filter primitives (filterRequest, pickKnownFields), the FilterSpec and FieldFilterOptions types, and the per-method specs (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) so advanced callers can reuse the same fail-open filtering logic. Learn more →

​

New Features

• AI Agents API (sdk.api.agents): New AgentsService for managing AI agents, versioned config, agent groups, executions, analytics, and prompt tooling (24 methods). Also exported directly from @veltdev/node. Learn more →
• Memory API (sdk.api.memory): New MemoryService for semantic search over judgments, knowledge-base ingestion/management, reviewer profiles, patterns/stats, alerting, and maintenance jobs (24 methods, all types Memory-prefixed). Also exported from @veltdev/node. Learn more →
• Approval Workflows API (sdk.api.approval): New ApprovalService for defining approval/review workflows (graphs of agent, human, and webhook nodes) and dispatching/resolving executions and steps (14 methods, routes under /v2/workflow/*, all types Approval-prefixed). Also exported from @veltdev/node. Learn more →
• CRDT — deleteCrdtData: sdk.api.crdt gains deleteCrdtData to delete CRDT editor data for a document (omit editorIds to delete all editors). Learn more →
• Documents — getDocumentsCount: sdk.api.documents gains getDocumentsCount to return a document count for an organization, with optional folder scoping. Learn more →
• Users — counts, document users & invites: sdk.api.users gains 7 methods: getUsersCount, getDocUsers, addUserInvite, respondToUserInvite, getUserInvites, getUserInvitations, and getInvitedPendingUsersCount. Learn more →
• Workspace — domain requests, key config, service configs & advanced webhooks: sdk.api.workspace gains 19 methods spanning additional-URL/domain requests, API key copy + config, notification/permission-provider/activity service configs, and the advanced (Svix) webhook endpoint suite. Learn more →

​

Improvements

• getApiKeyMetadata now targets the apikeyconfig endpoint: sdk.api.workspace.getApiKeyMetadata() now posts to /v2/workspace/apikeyconfig/get (was /v2/workspace/apikeymetadata/get). The method name and signature are unchanged, so no caller changes are required. Learn more →

​

New Features

• PartialCommentAnnotation typed fields: PartialCommentAnnotation gains four new typed fields — from, assignedTo, targetTextRange, and resolvedByUserId. resolvedByUserId uses three-state semantics (absent / explicit null / string) to correctly round-trip unresolve actions without dropping null. Learn more →
• PartialTargetTextRange interface: New PartialTargetTextRange interface with partialTargetTextRangeFromDict / partialTargetTextRangeToDict serializers for structured text-range data. Learn more →
• PartialComment round-trip helpers: PartialComment gains partialCommentFromDict / partialCommentToDict helpers that pass through unknown keys, preserving forward compatibility. Learn more →
• sdkVersion on BaseMetadata: BaseMetadata now includes an sdkVersion field. baseMetadataFromDict / baseMetadataToDict serializers are exposed on the public package surface. Learn more →