> ## Documentation Index > Fetch the complete documentation index at: https://velt.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Velt Node SDK Changelog > Release Notes of changes added to the Velt Node.js/TypeScript SDK (@veltdev/node) ### Libraries * `@veltdev/node` ### 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 →](/docs/backend-sdks/node#comment-annotations) ### 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 →](/docs/backend-sdks/node#comment-annotations) * **`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 →](/docs/backend-sdks/node#gdpr) * **`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 →](/docs/backend-sdks/node#access-control) ### 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 →](/docs/backend-sdks/node#comment-annotations) ### 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 →](/docs/backend-sdks/node#approval-workflows) ### 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 →](/docs/backend-sdks/node#approval-workflows) * **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 →](/docs/backend-sdks/node#approval-workflows) * **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 →](/docs/backend-sdks/node#approval-workflows) * **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 →](/docs/backend-sdks/node#approval-workflows) * **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 →](/docs/backend-sdks/node#approval-workflows) * **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 →](/docs/backend-sdks/node#comment-annotations) * **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 →](/docs/backend-sdks/node#comment-annotations) * **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 →](/docs/backend-sdks/node#agents) * **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 →](/docs/backend-sdks/node#agents) * **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 →](/docs/backend-sdks/node#agents) * **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 →](/docs/backend-sdks/node#documents) * **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 →](/docs/backend-sdks/node#memory) ### 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 →](/docs/backend-sdks/node#comments) * **`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 →](/docs/backend-sdks/node#comments) * **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 →](/docs/backend-sdks/node#verifytoken) ### 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 →](/docs/backend-sdks/node#reactions) ### 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 →](/docs/backend-sdks/node#field-allowlist) * **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 →](/docs/backend-sdks/node#field-allowlist) ### 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 →](/docs/backend-sdks/node#agents) * **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 →](/docs/backend-sdks/node#memory) * **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 →](/docs/backend-sdks/node#approval-workflows) * **CRDT — `deleteCrdtData`**: `sdk.api.crdt` gains `deleteCrdtData` to delete CRDT editor data for a document (omit `editorIds` to delete all editors). [Learn more →](/docs/backend-sdks/node#crdt) * **Documents — `getDocumentsCount`**: `sdk.api.documents` gains `getDocumentsCount` to return a document count for an organization, with optional folder scoping. [Learn more →](/docs/backend-sdks/node#documents) * **Users — counts, document users & invites**: `sdk.api.users` gains 7 methods: `getUsersCount`, `getDocUsers`, `addUserInvite`, `respondToUserInvite`, `getUserInvites`, `getUserInvitations`, and `getInvitedPendingUsersCount`. [Learn more →](/docs/backend-sdks/node#users) * **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 →](/docs/backend-sdks/node#workspace) ### 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 →](/docs/backend-sdks/node#workspace) ### 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 →](/docs/backend-sdks/node#partialcommentannotation) * **`PartialTargetTextRange` interface**: New `PartialTargetTextRange` interface with `partialTargetTextRangeFromDict` / `partialTargetTextRangeToDict` serializers for structured text-range data. [Learn more →](/docs/backend-sdks/node#partialtargettextrange) * **`PartialComment` round-trip helpers**: `PartialComment` gains `partialCommentFromDict` / `partialCommentToDict` helpers that pass through unknown keys, preserving forward compatibility. [Learn more →](/docs/backend-sdks/node#partialcomment) * **`sdkVersion` on `BaseMetadata`**: `BaseMetadata` now includes an `sdkVersion` field. `baseMetadataFromDict` / `baseMetadataToDict` serializers are exposed on the public package surface. [Learn more →](/docs/backend-sdks/node#basemetadata)