Velt Node SDK Changelog

​

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 →