> ## Documentation Index > Fetch the complete documentation index at: https://velt-claude-ui-customization-docs-review-m7hwcn.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Data models # Comments ### Threads #### CommentAnnotation *** | Property | Type | Required | Description | | ------------------------- | ------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `annotationId` | `string` | Yes | Unique identifier for the comment pin annotation. Auto generated | | `comments` | `Comment[]` | Yes | The list of all comments part of this annotation | | `commentCategories` | `CustomCategory[]` | Yes | The list of categories that this comment pin annotation belongs to | | `from` | `User` | Yes | The user who created this comment pin annotation | | `color` | `string` | No | Color used for the comment pin annotation | | `resolved` | `boolean` | No | Whether the comment annotation is marked resolved. Deprecated | | `inProgress` | `boolean` | No | Whether the comment annotation is marked as in progress. Deprecated | | `lastUpdated` | `any` | No | Timestamp when the comment annotation was last updated. Auto generated | | `createdAt` | `any` | No | Timestamp when the comment annotation was created. Auto generated | | `position` | `CursorPosition \| null` | No | Cursor position relative to the comment annotation | | `locationId` | `number \| null` | No | Unique location id generated from provided location | | `location` | `Location \| null` | No | Set location to identify user on sub document | | `type` | `string` | No | Type of the comment annotation | | `commentType` | `string` | No | Secondary discriminator for the comment annotation; `'suggestion'` marks it as a suggestion (agent- or human-authored). Either `type` or `commentType` set to `'suggestion'` renders the suggestion card | | `selectAllContent` | `boolean` | No | If true, sets text comment annotation on all the text content | | `approved` | `boolean` | No | Whether the comment annotation is approved | | `status` | `CustomStatus` | Yes | Status of the comment annotation. Default: CommentAnnotationStatusMap.OPEN | | `annotationIndex` | `number` | No | Index of current annotation in the list | | `annotationNumber` | `number` | No | Fixed annotation number that persists across sessions. Used for referencing specific comments | | `pageInfo` | `PageInfo` | No | Page information related to the comment annotation | | `assignedTo` | `User` | No | User to whom the comment annotation is assigned | | `priority` | `CustomPriority` | No | Priority level of the comment annotation | | `ghostComment` | `GhostComment \| null` | No | Placeholder for a non-existing comment | | `context` | `any` | No | Custom context data provided by the user | | `resolvedByUserId` | `string` | No | ID of the user who resolved the comment | | `resolvedByUser` | [`User`](#user) | No | User object who resolved the comment annotation | | `subscribedUsers` | `CommentAnnotationSubscribedUsers` | No | Users who explicitly subscribe to the comment | | `unsubscribedUsers` | `CommentAnnotationUnsubscribedUsers` | No | Users who explicitly unsubscribe to the comment | | `multiThreadAnnotationId` | `string` | No | ID of the multithread annotation group it belongs to, if created in multithread mode | | `isDraft` | `boolean` | No | Indicates if the comment annotation is in draft state | | `customList` | `CustomAnnotationDropdownItem[]` | No | Custom list of items for the comment annotation | | `targetElementId` | `string` | No | ID of the target element for the comment annotation if available | | `viewedBy` | [`Users[]`](#user) | No | List of users who have viewed/read this comment annotation | | `unread` | `boolean` | No | Whether the annotation is unread by current user | | `visibilityConfig` | [`CommentAnnotationVisibilityConfig`](#commentannotationvisibilityconfig) | No | Human-readable visibility configuration for the annotation. Contains type, organizationId, organizationIds, and userIds. Defaults to `{ type: 'public' }` for new annotations without explicit visibility. | | `agent` | [`CommentAnnotationAgent`](#commentannotationagent) | No | Present when the annotation was authored by an AI agent. Carries the agent identity (rendered in the Suggestion card's agent header variant) and the structured result rendered in the card body. | | `sourceType` | `string` | No | Origin of the annotation. Selects the agent-identity vs human-author header variant rendered for suggestion comments. | | `suggestion` | [`CommentAnnotationSuggestion`](#commentannotationsuggestion) | No | Suggestion state for typed-suggestion annotations. Mutated by [`acceptSuggestion()`](/api-reference/sdk/api/api-methods#acceptsuggestion) / [`rejectSuggestion()`](/api-reference/sdk/api/api-methods#rejectsuggestion). | | `basicAnchorData` | `{ xpath: string; topPercentage: number; leftPercentage: number }` | No | Client-safe anchor data derived from the target element's xpath. `xpath` is sourced from `targetElement.anchor.fXPath`, falling back to the legacy `targetElement.fXpath`. `topPercentage` and `leftPercentage` default to `0` when not set. Omitted entirely when no xpath source is present. | | `involvedUserIds` | `string[]` | No | All user IDs involved in the annotation (subscribed + unsubscribed participants). Read-only, server-derived. | | `mentionedUserIds` | `string[]` | No | User IDs @mentioned across the annotation's comments. Read-only, server-derived. | #### Enum | Enum Name | Event Type | Description | | ------------------------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `ADD_COMMENT_ANNOTATION` | `addCommentAnnotation` | Add a new comment annotation | | `ADD_COMMENT_ANNOTATION_DRAFT` | `addCommentAnnotationDraft` | Triggered when comment annotation draft is created | | `ADD_COMMENT_DRAFT` | `addCommentDraft` | Triggered when a user abandons a reply or edit composer without saving (e.g., clicks outside the dialog, closes the sidebar, or navigates away) | | `DELETE_COMMENT_ANNOTATION` | `deleteCommentAnnotation` | Delete a comment annotation | | `VISIBILITY_OPTION_CLICKED` | `visibilityOptionClicked` | Triggered when user selects a visibility option from the banner | | `COMMENT_SAVE_TRIGGERED` | `commentSaveTriggered` | Triggered when comment save is initiated | #### GhostComment *** Placeholder set when an annotation has lost its DOM target (e.g., the element was deleted or viewed on a different device group). | Property | Type | Required | Description | | --------------- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `targetElement` | `TargetElement \| null` | No | The original target element reference. | | `message` | `string` | No | Human-readable message explaining why the comment is a ghost. | | `type` | `string` | No | Ghost-comment type (e.g., `"differentDevice"`, `"elementDeleted"`). | | `isSameGroup` | `boolean` | No | Whether the comment was created from the same device group (`['mobile', 'tablet']` or `['desktop', 'monitor']`). | #### AddCommentAnnotationEvent *** | Property | Type | Required | Description | | ------------------- | ------------------------ | -------- | ----------------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | | `addContext` | `(context: any) => void` | Yes | Function to add custom metadata | | `elementRef` | `{ xpath: string }` | No | Reference to DOM element where comment annotation was added | #### AddCommentAnnotationDraftEvent *** | Property | Type | Required | Description | | ------------ | ---------------------------------------------------------- | -------- | --------------------------------------------- | | `addContext` | `(context:` [`CommentContext`](#commentcontext)`) => void` | No | Function to add context during draft creation | #### AddCommentDraftEvent *** | Property | Type | Required | Description | | ------------------- | ----------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the comment annotation to which the abandoned draft belongs | | `commentAnnotation` | [`CommentAnnotation`](#commentannotation) | Yes | The full comment annotation object (parent thread) | | `comment` | [`Comment`](#comment) | Yes | Snapshot of the unsaved composer content. In reply mode, contains pending text/HTML/attachments/recordings with `from`/`createdAt` set to current user/time. In edit mode, merges original comment fields with unsaved edits — `commentId` preserved. | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### DeleteCommentAnnotationEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### CommentBubbleClickedEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | No | Event metadata | #### SidebarOpenEvent *** Fired when the comment sidebar opens. Subscribe via `commentElement.on('sidebarOpen')`. | Property | Type | Required | Description | | ---------- | ----------------------------------------- | -------- | -------------- | | `metadata` | [`VeltEventMetadata`](#velteventmetadata) | No | Event metadata | #### SidebarCloseEvent *** Fired when the comment sidebar closes. Subscribe via `commentElement.on('sidebarClose')`. | Property | Type | Required | Description | | ---------- | ----------------------------------------- | -------- | -------------- | | `metadata` | [`VeltEventMetadata`](#velteventmetadata) | No | Event metadata | #### CommentClickEvent *** Fired when a comment is clicked in the sidebar list. Subscribe via `commentElement.on('commentClick')`. | Property | Type | Required | Description | | ----------------- | ----------------------------------------- | -------- | -------------------------------------------- | | `documentId` | `string \| null` | No | ID of the document the comment belongs to | | `location` | [`Location`](#location) `\| null` | No | Location of the clicked comment | | `targetElementId` | `string \| null` | No | ID of the element the comment is anchored to | | `context` | `{ [key: string]: any }` | No | Custom context attached to the comment | | `annotation` | [`CommentAnnotation`](#commentannotation) | No | The clicked comment annotation object | | `metadata` | [`VeltEventMetadata`](#velteventmetadata) | No | Event metadata | #### CommentNavigationButtonClickEvent *** Fired when the navigation ("go to") button on a sidebar comment is clicked. Subscribe via `commentElement.on('commentNavigationButtonClick')`. Extends [`CommentClickEvent`](#commentclickevent) with no additional fields. #### CommentEventTypes *** The following V2 comment sidebar event constants were added in v6.0.0-beta.2. ```ts theme={null} const CommentEventTypes = { SIDEBAR_OPEN: 'sidebarOpen', SIDEBAR_CLOSE: 'sidebarClose', COMMENT_CLICK: 'commentClick', COMMENT_NAVIGATION_BUTTON_CLICK: 'commentNavigationButtonClick', }; ``` #### CommentEventTypesMap *** The following V2 comment sidebar events map to typed payload objects on the `commentElement.on()` bus. | Event Type | Event Object | | ------------------------------ | ------------------------------------------------------------------------- | | `sidebarOpen` | [`SidebarOpenEvent`](#sidebaropenevent) | | `sidebarClose` | [`SidebarCloseEvent`](#sidebarcloseevent) | | `commentClick` | [`CommentClickEvent`](#commentclickevent) | | `commentNavigationButtonClick` | [`CommentNavigationButtonClickEvent`](#commentnavigationbuttonclickevent) | #### CommentSavedEvent *** | Property | Type | Required | Description | | ------------------- | ----------------------------------------- | -------- | ----------------------------------- | | `annotationId` | `string` | Yes | ID of the saved annotation | | `commentAnnotation` | [`CommentAnnotation`](#commentannotation) | Yes | The saved comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### VisibilityOptionClickedEvent *** | Property | Type | Required | Description | | ------------------- | ------------------------------------------------------------- | -------- | ------------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the annotation whose visibility was changed | | `commentAnnotation` | [`CommentAnnotation`](#commentannotation) | Yes | Full annotation at the time of the visibility selection | | `visibility` | [`CommentVisibilityOptionType`](#commentvisibilityoptiontype) | Yes | Selected visibility level | | `users` | `any[]` | No | Populated only when `visibility === 'restricted'` | | `metadata` | `VeltEventMetadata` | No | Event metadata | #### CommentSaveTriggeredEvent *** | Property | Type | Required | Description | | ------------------- | ----------------------------------------- | -------- | -------------------------------- | | `annotationId` | `string` | Yes | ID of the annotation being saved | | `commentAnnotation` | [`CommentAnnotation`](#commentannotation) | Yes | Full annotation at save time | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### CommentContext *** Custom context data for comment annotations. ```typescript theme={null} type CommentContext = any; ``` #### CommentContextProviderResponse *** Return type for context provider function. Can return context synchronously or asynchronously. ```typescript theme={null} type CommentContextProviderResponse = CommentContext | null | undefined; ``` #### CommentContextProvider *** Function type for providing context based on document and location. ```typescript theme={null} type CommentContextProvider = ( documentId: string, location?: Location, ) => CommentContextProviderResponse | Promise; ``` #### ContextOptions *** Options for configuring context matching behavior on comment components. | Property | Type | Required | Description | | -------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | `partialMatch` | `boolean` | No | When `true`, comments match if they contain all specified context fields (extra fields are ignored). Defaults to full match. | #### CommentVisibilityType *** Visibility level used by **API methods** such as [`updateVisibility()`](/api-reference/sdk/api/api-methods#updatevisibility) and [`enablePrivateMode()`](/api-reference/sdk/api/api-methods#enableprivatemode) via [`CommentVisibilityConfig`](#commentvisibilityconfig). ```typescript theme={null} type CommentVisibilityType = "public" | "organizationPrivate" | "restricted"; ``` | Value | Description | | ----------------------- | ----------------------------------------------------------- | | `'public'` | Comment visible to all users | | `'organizationPrivate'` | Comment visible only to users in the specified organization | | `'restricted'` | Comment visible only to specified users (private) | The visibility system uses two separate sets of values: - **API methods** use [`CommentVisibilityConfig`](#commentvisibilityconfig) with [`CommentVisibilityType`](#commentvisibilitytype) values: `'public'`, `'organizationPrivate'`, `'restricted'` (3 values — `'restricted'` covers both self-only and selected-people, distinguished by whether `userIds` is provided). - **UI wireframes** use the [`CommentVisibilityOption`](#commentvisibilityoption) enum with 4 values: `'restrictedSelf'`, `'restrictedSelectedPeople'`, `'organizationPrivate'`, `'public'`. These are the `type` prop values on visibility banner dropdown wireframe items. #### CommentVisibilityOption *** Enum for **UI wireframe** visibility levels, used as the `type` prop on visibility banner dropdown content items. These are more granular than the API-level [`CommentVisibilityType`](#commentvisibilitytype) — the API's single `'restricted'` value maps to two UI options (`'restrictedSelf'` and `'restrictedSelectedPeople'`). ```typescript theme={null} export declare enum CommentVisibilityOption { RESTRICTED_SELF = "restrictedSelf", RESTRICTED_SELECTED_PEOPLE = "restrictedSelectedPeople", ORGANIZATION_PRIVATE = "organizationPrivate", PUBLIC = "public", } ``` | Value | Description | API Equivalent | | ---------------------------- | ------------------------------------------- | ---------------------------------------------- | | `RESTRICTED_SELF` | Visible only to the comment author | `'restricted'` with `userIds: [currentUserId]` | | `RESTRICTED_SELECTED_PEOPLE` | Visible only to specifically selected users | `'restricted'` with `userIds: [...]` | | `ORGANIZATION_PRIVATE` | Visible to users in the organization | `'organizationPrivate'` | | `PUBLIC` | Visible to all users | `'public'` | #### CommentVisibilityOptionType *** String union type derived from [`CommentVisibilityOption`](#commentvisibilityoption) enum values. Used in UI wireframe components. ```typescript theme={null} export type CommentVisibilityOptionType = `${CommentVisibilityOption}`; // = 'restrictedSelf' | 'restrictedSelectedPeople' | 'organizationPrivate' | 'public' ``` #### CommentVisibilityConfig *** Configuration object for **API methods** that update comment visibility. Uses [`CommentVisibilityType`](#commentvisibilitytype) values — not [`CommentVisibilityOption`](#commentvisibilityoption) values. | Property | Type | Required | Description | | ----------------- | ------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | [`CommentVisibilityType`](#commentvisibilitytype) | Yes | Visibility level: `'public'`, `'organizationPrivate'`, or `'restricted'`. | | `annotationId` | `string` | Yes | Annotation ID of the comment to update visibility. | | `organizationId` | `string` | No | Organization ID. Used when `type` is `'organizationPrivate'`. If neither `organizationId` nor `organizationIds` is provided, the comment defaults to the logged-in user's own organization. | | `organizationIds` | `string[]` | No | Organization IDs for `organizationPrivate` visibility; visible to all listed orgs; merged + de-duplicated with `organizationId`. | | `userIds` | `string[]` | No | User IDs who can see the comment. Used when `type` is `'restricted'`. The current user is automatically appended if not present. | #### PrivateModeConfig *** Configuration for enabling private mode via **API methods**. Subset of [`CommentVisibilityConfig`](#commentvisibilityconfig) — excludes `annotationId`. Uses [`CommentVisibilityType`](#commentvisibilitytype) values. As of v5.0.3, `PrivateModeConfig` also accepts `organizationId` / `organizationIds` for multi-org private mode. ```typescript theme={null} type PrivateModeConfig = Omit; ``` | Property | Type | Required | Description | | ----------------- | ------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | `type` | [`CommentVisibilityType`](#commentvisibilitytype) | Yes | Visibility level applied when private mode is active. | | `organizationId` | `string` | No | Organization ID. Used when `type` is `'organizationPrivate'`. | | `organizationIds` | `string[]` | No | Organization IDs for `organizationPrivate` visibility; visible to all listed orgs; merged + de-duplicated with `organizationId`. | | `userIds` | `string[]` | No | User IDs who can see comments. Used when `type` is `'restricted'`. The current user is automatically appended if not present. | #### OrgContact *** A single team / organization entry offered in the comment dialog's "Selected Teams" visibility picker. Supplied via [`updateOrgList()`](/api-reference/sdk/api/api-methods#updateorglist). ```typescript theme={null} class OrgContact { /** Unique organization identifier you use to identify the team / organization. */ id: string; /** The team / organization's display name (shown in the "Selected Teams" picker). */ name?: string; } ``` | Property | Type | Required | Description | | -------- | -------- | -------- | ---------------------------------------------------------------------------- | | `id` | `string` | Yes | Unique organization identifier you use to identify the team / organization. | | `name` | `string` | No | The team / organization's display name shown in the "Selected Teams" picker. | #### UpdateOrgListConfig *** Config passed to [`updateOrgList()`](/api-reference/sdk/api/api-methods#updateorglist) to set the teams shown in the "Selected Teams" visibility picker. ```typescript theme={null} interface UpdateOrgListConfig { /** The list of organizations / teams to offer in the "Selected Teams" picker. */ orgList: OrgContact[]; } ``` | Property | Type | Required | Description | | --------- | ----------------------------- | -------- | -------------------------------------------------------------------------- | | `orgList` | [`OrgContact[]`](#orgcontact) | Yes | The list of organizations / teams to offer in the "Selected Teams" picker. | #### CommentAnnotationVisibilityConfig *** Human-readable visibility configuration stored on a comment annotation. | Property | Type | Required | Description | | ----------------- | ------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | [`CommentVisibilityType`](#commentvisibilitytype) | Yes | The visibility type for the comment annotation. | | `organizationId` | `string` | No | The organization ID for organization-private visibility. | | `organizationIds` | `string[]` | No | Organization IDs for `organizationPrivate` visibility (display-only mirror of `CommentVisibilityConfig.organizationIds`; visible to all listed orgs). | | `userIds` | `string[]` | No | User IDs that can see the comment (display-only mirror of the self tokens in `context.accessFields`). For non-public comments this ALWAYS includes the author's `userId`, reflecting the author self-token invariant. | #### CommentAnnotationSubscribedUsers *** | Property | Type | Required | Description | | ------------ | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userIdHash` | `string` | Yes | The user ID of the subscribed user | | `user` | `User` | Yes | The user object of the subscribed user | | `type` | `'manual' \| 'auto'` | Yes | Manual: if the user used the UI option to subscribe; Auto: When the system automatically adds the user to the subscribed list. eg: when the user creates a comment annotation | #### CommentAnnotationUnsubscribedUsers *** | Property | Type | Required | Description | | ------------ | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userIdHash` | `string` | Yes | The user ID of the unsubscribed user | | `user` | `User` | Yes | The user object of the unsubscribed user | | `type` | `'manual' \| 'auto'` | Yes | Manual: if the user used the UI option to unsubscribe; Auto: When the system automatically removes the user from the unsubscribed list. eg: when the comment where user was tagged is deleted | #### CommentAnnotationAgent *** Identity and structured output for an AI agent that authored a comment annotation. Present on [`CommentAnnotation.agent`](#commentannotation) when the annotation is agent-authored. Drives the Suggestion card header (agent variant) and body. | Property | Type | Required | Description | | ------------- | ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | No | Agent display name shown in the suggestion header. | | `photoUrl` | `string` | No | Agent avatar URL. Falls back to a default agent icon when missing. | | `result` | [`AgentResult`](#agentresult) | No | Structured output produced by the agent. | | `agentFields` | `string[]` | No | Agent field tags. Used to filter annotation/count queries via `agentFields` on [`CommentRequestQuery`](#commentrequestquery). | #### AgentResult *** Structured output produced by an AI agent for a suggestion comment. | Property | Type | Required | Description | | -------- | -------- | -------- | ---------------------------------------------------------------------------------------------- | | `title` | `string` | No | Bold title rendered at the top of the Suggestion card body. Sourced from `agent.result.title`. | #### AgentData *** AI-agent identity and output for an agent-authored [`Comment`](#comment) (set on `Comment.agent` when `Comment.sourceType` is `'agent'`). Read-only from the SDK. | Property | Type | Required | Description | | ------------- | -------------------- | -------- | -------------------------------------------------------------------- | | `agentName` | `string` | No | Agent identifier. Always retained for agent-field querying. | | `name` | `string` | No | Agent display name. | | `avatar` | `string` | No | Agent avatar URL. | | `result` | `{ title?: string }` | No | Structured agent output; `title` is rendered in the suggestion card. | | `agentFields` | `string[]` | No | Agent field tags used to filter annotation/count queries. | #### CommentAnnotationSuggestion *** Suggestion state for a typed-suggestion annotation. Mutated by [`acceptSuggestion()`](/api-reference/sdk/api/api-methods#acceptsuggestion) and [`rejectSuggestion()`](/api-reference/sdk/api/api-methods#rejectsuggestion). | Property | Type | Required | Description | | -------------- | --------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `status` | `'pending' \| 'accepted' \| 'rejected'` | Yes | Current suggestion state. Transitions are forward-only from `pending`, making repeat accept/reject calls idempotent. | | `rejectReason` | `string` | No | Reason recorded when the suggestion is rejected. | | `resolvedBy` | `string` | No | ID of the user who accepted or rejected the suggestion. | | `resolvedAt` | `number` | No | Timestamp (epoch milliseconds) when the suggestion was accepted or rejected. | #### AddCommentAnnotationRequest *** | Property | Type | Required | Description | | ------------ | ------------------- | -------- | ------------------ | | `annotation` | `CommentAnnotation` | Yes | Comment annotation | | `options` | `RequestOptions` | No | Request options | #### DeleteCommentAnnotationRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### SubmitCommentRequest *** | Property | Type | Required | Description | | ------------------------- | -------- | -------- | ------------------------------------------- | | `targetComposerElementId` | `string` | Yes | Unique identifier of the composer to submit | #### ClearComposerRequest *** | Property | Type | Required | Description | | ------------------------- | -------- | -------- | ------------------------------------------ | | `targetComposerElementId` | `string` | Yes | Unique identifier of the composer to clear | #### GetComposerDataRequest *** | Property | Type | Required | Description | | ------------------------- | -------- | -------- | ------------------------------------------ | | `targetComposerElementId` | `string` | Yes | Unique identifier of the composer to query | #### PageModeComposerConfig *** | Property | Type | Required | Description | | ----------------- | -------------------------------- | -------- | --------------------------------------------------------------------- | | `context` | `{ [key: string]: any } \| null` | No | Custom context data for page mode composer | | `targetElementId` | `string \| null` | No | Target element ID to bind with comment annotation | | `clearContext` | `boolean` | No | When `false`, preserves context after submission. Defaults to `true`. | #### AssignToConfig *** | Property | Type | Required | Description | | -------- | -------------------------- | -------- | ------------------------------------------------------------------- | | `type` | `'dropdown' \| 'checkbox'` | Yes | Assignment UI mode: dropdown for menu, checkbox for self-assignment | #### FormatConfig *** Configuration for text formatting toolbar options in comment composers. | Property | Type | Required | Description | | --------------- | --------------------- | -------- | ------------------------------------------------- | | `bold` | `{ enable: boolean }` | No | Enable or disable bold formatting option | | `italic` | `{ enable: boolean }` | No | Enable or disable italic formatting option | | `underline` | `{ enable: boolean }` | No | Enable or disable underline formatting option | | `strikethrough` | `{ enable: boolean }` | No | Enable or disable strikethrough formatting option | #### CommentRequestQuery *** | Property | Type | Required | Description | | --------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `organizationId` | `string` | No | Organization ID to filter comment annotations by organization | | `documentIds` | `string[]` | No | Array of document IDs to query. | | `locationIds` | `string[]` | No | Array of location IDs to filter by | | `statusIds` | `string[]` | No | Array of status IDs to filter by | | `folderId` | `string` | No | Folder ID to filter comment annotations by folder | | `allDocuments` | `boolean` | No | If true, includes all documents in the query | | `locationId` | `string` | No | Single location ID to filter by (alternative to `locationIds`) | | `aggregateDocuments` | `boolean` | No | If true, aggregates comment annotation counts across multiple documents | | `filterGhostComments` | `boolean` | No | If true, excludes ghost (deleted or orphaned) comments from the results | | `batchedPerDocument` | `boolean` | No | Enable batched listener for large document lists (50+ docs) | | `debounceMs` | `number` | No | Debounce delay for auto-batching updates in milliseconds (default: 5000ms) | | `agentFields` | `string[]` | No | Filters queries to annotations where `agent.agentFields` contains any provided value; when set, unread count equals total count | #### GetCommentAnnotationsCountResponse *** | Property | Type | Required | Description | | -------- | ------------------------------------------------- | -------- | --------------------------------------------------------------- | | `data` | `Record \| null` | Yes | Map of document IDs to their comment counts. Null while loading | #### GetCommentAnnotationsResponse *** | Property | Type | Required | Description | | -------- | --------------------------------------------- | -------- | ------------------------------------------------------------ | | `data` | `Record \| null` | Yes | Map of document IDs to their annotations. Null while loading | #### FetchCommentAnnotationsRequest *** | Property | Type | Required | Description | | ------------------ | ----------------- | -------- | -------------------------------------------------------------- | | `createdAfter` | `number` | No | Filter annotations created after this timestamp | | `createdBefore` | `number` | No | Filter annotations created before this timestamp | | `updatedAfter` | `number` | No | Filter annotations updated after this timestamp | | `updatedBefore` | `number` | No | Filter annotations updated before this timestamp | | `statusIds` | `string[]` | No | Filter annotations by status IDs | | `order` | `'asc' \| 'desc'` | No | Sort order for annotations | | `pageToken` | `string` | No | Token for fetching next page of results | | `allDocuments` | `boolean` | No | Whether to fetch annotations from all documents | | `pageSize` | `number` | No | Number of results per page | | `organizationId` | `string` | No | Organization ID to fetch annotations from | | `locationId` | `string` | No | Location ID to filter annotations by | | `documentIds` | `string[]` | No | Array of specific document IDs to fetch from | | `folderId` | `string` | No | Folder ID to fetch annotations from | | `resolvedBy` | `string` | No | Filter comments by user who resolved the comment | | `userIds` | `string[]` | No | Filter comments by comment annotation author | | `mentionedUserIds` | `string[]` | No | Filter comments where provided users are tagged in the comment | #### FetchCommentAnnotationsResponse *** | Property | Type | Required | Description | | --------------- | --------------------------------------------- | -------- | -------------------------------------------------------------- | | `data` | `Record \| null` | Yes | Map of document IDs to their annotations. `Null` while loading | | `nextPageToken` | `string` | Yes | Token for fetching next page of results | #### GetCommentResolverRequest *** | Property | Type | Required | Description | | ---------------------- | ---------- | -------- | -------------------------------------------------------------------- | | `organizationId` | `string` | Yes | Organization ID to fetch comments from | | `commentAnnotationIds` | `string[]` | No | Array of comment annotation IDs to fetch comments from | | `documentIds` | `string[]` | No | Array of document IDs to fetch comments from | | `folderId` | `string` | No | Folder ID to fetch comments from | | `allDocuments` | `boolean` | No | Whether to fetch comments from all documents within the given folder | #### SaveCommentResolverRequest *** | Property | Type | Required | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `commentAnnotation` | `{ [key: string]: PartialCommentAnnotation }` | Yes | Map of comment annotation data to save | | `metadata` | `BaseMetadata` | No | Additional metadata for the request. eg: apikey, organizationId, documentId, etc. | | `event` | [`ResolverActions`](#resolveractions) \| [`CommentResolverSaveEvent`](#commentresolversaveevent) \| `string` | No | The save event. One of the 4 core PII events (`ResolverActions`) or, when opted in via `additionalSaveEvents`, a non-core annotation-level event (`CommentResolverSaveEvent`). Also accepts raw strings for forward-compatibility. | | `commentId` | `string` | No | ID of the comment to save | | `targetComment` | [`PartialComment`](#partialcomment) | No | The comment the action occurred on, resolved by the frontend from `commentId` against the payload's `commentAnnotation[*].comments` map. A convenience alias for data already in the payload (no new data egress) and request context only — never persisted by `saveComments`. Omitted when `commentId` is absent or unmatched. | #### DeleteCommentResolverRequest *** | Property | Type | Required | Description | | --------------------- | ----------------- | -------- | --------------------------------------------------------------------------------- | | `commentAnnotationId` | `string` | Yes | ID of the comment annotation to delete | | `metadata` | `BaseMetadata` | No | Additional metadata for the request. eg: apikey, organizationId, documentId, etc. | | `event` | `ResolverActions` | No | Event name that caused the delete request | #### CustomAnnotationDropdownData *** | Property | Type | Required | Description | | ------------- | -------------------------------- | -------- | ----------------------------------------------------------- | | `type` | `'multi' \| 'single'` | Yes | The type of the custom annotation dropdown | | `placeholder` | `string` | Yes | The placeholder text for the dropdown. Defaults to 'Select' | | `data` | `CustomAnnotationDropdownItem[]` | Yes | An array of dropdown items | #### CustomAnnotationDropdownItem *** | Property | Type | Required | Description | | -------- | -------- | -------- | ------------------------------------------- | | `id` | `string` | Yes | The unique identifier for the dropdown item | | `label` | `string` | Yes | The display text for the dropdown item | #### GetCommentAnnotationsResponse *** | Property | Type | Required | Description | | -------- | ------------------------------------- | -------- | ------------------------------------------------ | | `data` | `Record` | Yes | Map of document IDs to their comment annotations | #### CommentAnnotationsCount *** | Property | Type | Required | Description | | -------- | -------- | -------- | ------------------------- | | `unread` | `number` | Yes | Number of unread comments | | `total` | `number` | Yes | Total number of comments | #### GetCommentAnnotationsCountResponse *** | Property | Type | Required | Description | | -------- | ----------------------------------------- | -------- | ------------------------------------------- | | `data` | `Record` | Yes | Map of document IDs to their comment counts | ### Slate #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | --------- | -------- | ---------------------------------------------------- | | `editor` | `Editor` | Yes | Slate editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `unknown` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------------------------------- | -------- | -------------------------------------------- | | `editor` | `Editor` | Yes | Slate editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | [`CommentAnnotation`](#commentannotation)`[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### VeltCommentsElement *** Slate element type representing a comment with optional annotation ID. | Property | Type | Required | Description | | -------------- | --------------- | -------- | ---------------------------------------- | | `type` | `'veltComment'` | Yes | Discriminator for Velt comment elements. | | `children` | `Descendant[]` | Yes | Slate child nodes. | | `annotationId` | `string` | No | Associated CommentAnnotation ID. | ### Tiptap #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | -------------------------- | -------- | ---------------------------------------------------- | | `editor` | `Editor` | Yes | Tiptap editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `Editor` | Yes | Tiptap editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### TiptapVeltCommentsOptions *** | Property | Type | Required | Description | | ------------------ | --------------------- | -------- | ------------------------------------------------------------ | | `HTMLAttributes` | `Record` | No | Attributes applied to rendered comment nodes/marks. | | `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks across edits. Default: `true`. | | `editorId` | `string` | No | ID to scope Velt operations to a specific editor instance. | #### CommentAnnotationContext *** Context object for comment annotations. Contains text editor configuration and any additional custom metadata. | Property | Type | Required | Description | | ------------------ | ------------------ | -------- | ---------------------------------------------------------- | | `textEditorConfig` | `TextEditorConfig` | No | Text editor configuration (auto-generated by the library). | | `[key: string]` | `unknown` | No | Any additional custom properties you want to attach. | #### ContextOptions *** Options that control how annotation context matching behaves. | Property | Type | Required | Description | | -------------- | --------- | -------- | ----------------------------------------------------------------- | | `partialMatch` | `boolean` | No | When `true`, annotations match if the context is a partial match. | #### TextEditorConfig *** Nested in `CommentAnnotationContext`. | Property | Type | Required | Description | | ------------------ | -------- | -------- | ------------------------------------------------- | | `text` | `string` | Yes | The selected text content. | | `occurrence` | `number` | Yes | The occurrence index of the text in the document. | | `editorId` | `string` | No | The editor ID associated with this comment. | | `targetTextNodeId` | `string` | No | ID of the target text node container. | ### Lexical #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | --------- | -------- | ---------------------------------------------------- | | `editor` | `Editor` | Yes | Lexical editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `unknown` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `Editor` | Yes | Lexical editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### CommentNode *** Inline Lexical element representing a comment with optional annotation IDs. | Property | Type | Required | Description | | ------------------------- | ------------------------- | -------- | --------------------------------------------------- | | `type` | `'comment'` | Yes | Discriminator for Velt comment nodes. | | `children` | `SerializedLexicalNode[]` | Yes | Lexical child nodes (from `SerializedElementNode`). | | `annotationId` | `string` | No | Associated `CommentAnnotation` ID. | | `multiThreadAnnotationId` | `string` | No | Associated multi-thread annotation ID. | ### Plate #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | -------------------------- | -------- | ---------------------------------------------------- | | `editor` | `PlateEditor` | Yes | Plate editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `PlateEditor` | Yes | Plate editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### VeltCommentsPluginConfig *** | Property | Type | Required | Description | | ------------------ | --------- | -------- | ------------------------------------------------------------------------ | | `editorId` | `string` | No | Unique identifier for this editor instance (for multi-editor scenarios). | | `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks in the document. Default: `true`. | #### VeltCommentsElement *** Plate element type representing a comment with optional annotation IDs. | Property | Type | Required | Description | | ------------------------- | --------------- | -------- | ----------------------------------------- | | `type` | `'veltComment'` | Yes | Element type identifier. | | `children` | `Descendant[]` | Yes | Child nodes (text content). | | `annotationId` | `string` | No | The Velt annotation ID. | | `multiThreadAnnotationId` | `string` | No | Multi-thread annotation ID if applicable. | ### CodeMirror #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | -------------------------- | -------- | ---------------------------------------------------- | | `editor` | `EditorView` | Yes | CodeMirror EditorView instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `EditorView` | Yes | CodeMirror EditorView instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### CodemirrorVeltCommentsConfig *** Configuration options for the `CodemirrorVeltComments()` extension. | Property | Type | Required | Description | | ------------------ | --------- | -------- | ------------------------------------------------------------------------ | | `editorId` | `string` | No | Unique identifier for this editor instance (for multi-editor scenarios). | | `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks in the document. Default: `true`. | ### Ace #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | -------------------------- | -------- | ---------------------------------------------------- | | `editor` | `Ace.Editor` | Yes | Ace Editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `Ace.Editor` | Yes | Ace Editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### AceVeltCommentsConfig *** Configuration options for the `AceVeltComments()` function. | Property | Type | Required | Description | | ------------------ | --------- | -------- | ------------------------------------------------------------------------ | | `editorId` | `string` | No | Unique identifier for this editor instance (for multi-editor scenarios). | | `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks in the document. Default: `true`. | ### Quill #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | -------------------------- | -------- | ---------------------------------------------------- | | `editor` | `Quill` | Yes | Quill editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `Quill` | Yes | Quill editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### QuillVeltCommentsConfig *** Configuration options for the `QuillVeltComments` module. | Property | Type | Required | Description | | ------------------ | --------- | -------- | ------------------------------------------------------------------------ | | `editorId` | `string` | No | Unique identifier for this editor instance (for multi-editor scenarios). | | `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks in the document. Default: `true`. | ### Apryse #### ApryseVeltCommentsConfig *** Configuration options for `ApryseVeltComments.configure()`. | Property | Type | Required | Description | | ---------- | -------- | -------- | ------------------------------------------------------------------------------------------------ | | `editorId` | `string` | No | Unique identifier for this WebViewer instance (for multi-viewer scenarios). Default: `'apryse'`. | #### AddCommentArgs *** Request interface for the `addComment()` function. | Property | Type | Required | Description | | ---------- | ------------------- | -------- | ---------------------------------------------------- | | `instance` | `WebViewerInstance` | Yes | The Apryse WebViewer instance to add the comment in. | #### AddCommentResult *** Return shape from `addComment()` when the call succeeds (otherwise `null`). | Property | Type | Required | Description | | ------------------ | ----------------------------------------- | -------- | ---------------------------------------------------- | | `veltAnnotationId` | `string` | Yes | The Velt annotation id assigned by the SDK. | | `textEditorConfig` | [`TextEditorConfig`](#texteditorconfig-1) | Yes | The durable logical anchor stored on the annotation. | #### RenderCommentsArgs *** Request interface for the `renderComments()` function. | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------- | | `instance` | `WebViewerInstance` | Yes | The Apryse WebViewer instance. | | `commentAnnotations` | `CommentAnnotation[]` | Yes | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### AttachedExtension *** Handle returned by `ApryseVeltComments.configure(...).attach(instance)`. | Property | Type | Required | Description | | -------- | ------------ | -------- | ------------------------------------------------------------ | | `detach` | `() => void` | Yes | Removes every Apryse listener and clears per-instance state. | #### TextEditorConfig *** Logical anchor stored in `annotation.context.textEditorConfig`. Designed to survive document edits and mode switches (viewer ↔ docxEditor) — physical positions are re-derived at render time. | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------------------------------------ | | `editorId` | `string` | Yes | The editor id associated with this comment. | | `text` | `string` | Yes | The (canonicalized) selected text. | | `pageNumber` | `number` | Yes | 1-based page number where the comment lives. | | `occurrence` | `number` | Yes | 1-based count of this exact text on the page. Re-validated on each edit. | ### DraftJS #### DraftJSEditor *** Editor wrapper object passed to the DraftJS Velt comment helpers. | Property | Type | Required | Description | | ---------------- | ------------------------------ | -------- | ----------------------------------- | | `editorState` | `EditorState` | Yes | Current DraftJS editor state. | | `setEditorState` | `(state: EditorState) => void` | Yes | Function used to update the editor. | #### DraftJSVeltEditorProps *** Props for the `DraftJSVeltEditor` React wrapper. | Property | Type | Required | Description | | ------------- | ------------------------------ | -------- | ----------------------------------------------------------------------------- | | `editorState` | `EditorState` | Yes | Current DraftJS editor state. | | `onChange` | `(state: EditorState) => void` | Yes | Callback invoked when the editor state changes. | | `editorId` | `string` | No | Optional editor ID used to scope operations for multi-editor pages. | | `...props` | `EditorProps` | No | Other standard DraftJS `Editor` props, such as `placeholder` or `spellCheck`. | #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | --------------------------------- | -------- | ---------------------------------------------------- | | `editor` | [`DraftJSEditor`](#draftjseditor) | Yes | DraftJS editor wrapper object. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `unknown` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------------------- | -------- | -------------------------------------------- | | `editor` | [`DraftJSEditor`](#draftjseditor) | Yes | DraftJS editor wrapper object. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). ### ProseMirror #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | --------------------------------------------------------- | -------- | ---------------------------------------------------- | | `editor` | `EditorView` | Yes | ProseMirror editor view instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | [`CommentAnnotationContext`](#commentannotationcontext-1) | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `EditorView` | Yes | ProseMirror editor view instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### VeltCommentsPluginConfig *** Configuration options for the `VeltCommentsPlugin()` function. | Property | Type | Required | Description | | ------------------ | --------- | -------- | ------------------------------------------------------------------------------ | | `editorId` | `string` | No | Unique identifier for this editor instance. Use it for multi-editor scenarios. | | `persistVeltMarks` | `boolean` | No | Reserved for API parity. ProseMirror highlights are always view-only overlays. | #### CommentAnnotationContext *** Context object for comment annotations. Contains text editor configuration and any additional custom metadata. | Property | Type | Required | Description | | ------------------ | ----------------------------------------- | -------- | -------------------------------------------------------- | | `textEditorConfig` | [`TextEditorConfig`](#texteditorconfig-2) | No | Text editor configuration auto-generated by the library. | | `[key: string]` | `unknown` | No | Any additional custom properties you want to attach. | #### TextEditorConfig *** Nested in `CommentAnnotationContext`. | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------------- | | `text` | `string` | Yes | The selected text content. | | `occurrence` | `number` | Yes | The occurrence index of the text in the document. | | `editorId` | `string` | No | The editor ID associated with this comment. | #### SelectionContext *** Context extracted from the current ProseMirror editor selection. | Property | Type | Required | Description | | ------------ | -------- | -------- | -------------------------------------------------------------------------- | | `text` | `string` | Yes | Selected text content. | | `from` | `number` | Yes | ProseMirror start position of the selection. | | `to` | `number` | Yes | ProseMirror end position of the selection. | | `occurrence` | `number` | Yes | 1-based index of `text` among all matches in the document. | | `locationId` | `string` | No | Optional Velt location id derived from a `data-velt-location-id` ancestor. | ### TinyMCE #### AddCommentRequest *** Request interface for the TinyMCE `addComment()` function. The library automatically writes `context.textEditorConfig` with the selected text, its 1-based occurrence index in the document, and the editor ID when one is provided. | Property | Type | Required | Description | | ---------- | --------------------------------------------------------- | -------- | ---------------------------------------------------- | | `editor` | `Editor` | Yes | TinyMCE editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | [`CommentAnnotationContext`](#commentannotationcontext-2) | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** Request interface for the TinyMCE `renderComments()` function. Comments are resolved back to TinyMCE DOM ranges and rendered as view-only overlay elements. | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `Editor` | Yes | TinyMCE editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### TinymceVeltCommentsConfig *** Configuration options for the TinyMCE Velt comments plugin. In TinyMCE init options, `editorId` maps to `velt_comments_editor_id` and `persistVeltMarks` maps to `velt_comments_persist_marks`. | Property | Type | Required | Description | | ------------------ | --------- | -------- | ------------------------------------------------------------------------------ | | `editorId` | `string` | No | Unique identifier for this editor instance. Use it for multi-editor scenarios. | | `persistVeltMarks` | `boolean` | No | Reserved for API parity. TinyMCE highlights are always view-only overlays. | #### CommentAnnotationContext *** Context object for comment annotations. Contains text editor configuration and any additional custom metadata. | Property | Type | Required | Description | | ------------------ | ----------------------------------------- | -------- | -------------------------------------------------------- | | `textEditorConfig` | [`TextEditorConfig`](#texteditorconfig-3) | No | Text editor configuration auto-generated by the library. | | `[key: string]` | `unknown` | No | Any additional custom properties you want to attach. | #### TextEditorConfig *** Nested in `CommentAnnotationContext`. | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------------------------------ | | `text` | `string` | Yes | The selected text content. | | `occurrence` | `number` | Yes | The 1-based occurrence index of the selected text in the document. | | `editorId` | `string` | No | The editor ID associated with this comment. | ### CKEditor #### AddCommentRequest *** Request interface for the CKEditor `addComment()` function. | Property | Type | Required | Description | | ---------- | ---------------------------------------------------------------- | -------- | ---------------------------------------------------- | | `editor` | `Editor` | Yes | CKEditor 5 editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | [`CommentAnnotationContext`](#ckeditor-commentannotationcontext) | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** Request interface for the CKEditor `renderComments()` function. | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `Editor` | Yes | CKEditor 5 editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### VeltCommentsPluginConfig *** Configuration options for `config.veltComments` in the CKEditor editor config. | Property | Type | Required | Description | | ------------------ | --------- | -------- | ---------------------------------------------------------------------- | | `editorId` | `string` | No | Unique identifier for this editor instance. | | `persistVeltMarks` | `boolean` | No | Reserved for API parity; highlights are always rendered as an overlay. | #### CommentAnnotationContext *** Context object merged into the Velt comment annotation by `addComment()`. | Property | Type | Required | Description | | ------------------ | ------------------------------------------------ | -------- | --------------------------------------------------------- | | `textEditorConfig` | [`TextEditorConfig`](#ckeditor-texteditorconfig) | No | Text editor configuration auto-generated by the library. | | `[key: string]` | `unknown` | No | Additional custom properties to attach to the annotation. | #### TextEditorConfig *** Logical text anchor stored in `annotation.context.textEditorConfig`. | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------------- | | `text` | `string` | Yes | The selected text content. | | `occurrence` | `number` | Yes | The occurrence index of the text in the document. | | `editorId` | `string` | No | The editor ID associated with this comment. | ### Monaco #### AddCommentRequest *** Request interface for the Monaco `addComment()` function. The library automatically writes `context.textEditorConfig` with the selected text, its 1-based occurrence index in the document, and the editor ID when one is provided. | Property | Type | Required | Description | | ---------- | --------------------------------------------------------- | -------- | ---------------------------------------------------- | | `editor` | `MonacoEditor` | Yes | Monaco editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | [`CommentAnnotationContext`](#commentannotationcontext-3) | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** Request interface for the Monaco `renderComments()` function. Comments are resolved back to Monaco ranges and rendered as view-only overlay elements. | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `MonacoEditor` | Yes | Monaco editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### MonacoVeltCommentsConfig *** Configuration options for the `registerVeltComments()` function. | Property | Type | Required | Description | | ------------------ | --------- | -------- | ------------------------------------------------------------------------------ | | `editorId` | `string` | No | Unique identifier for this editor instance. Use it for multi-editor scenarios. | | `persistVeltMarks` | `boolean` | No | Reserved for API parity. Monaco highlights are always view-only overlays. | #### VeltCommentsHandle *** Return value from `registerVeltComments()`. | Property | Type | Required | Description | | --------- | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------- | | `dispose` | `() => void` | Yes | Removes Monaco listeners, tracking decorations, overlay elements, and local selected-comment subscriber cleanup. | #### CommentAnnotationContext *** Context object for comment annotations. Contains text editor configuration and any additional custom metadata. | Property | Type | Required | Description | | ------------------ | ----------------------------------------- | -------- | -------------------------------------------------------- | | `textEditorConfig` | [`TextEditorConfig`](#texteditorconfig-4) | No | Text editor configuration auto-generated by the library. | | `[key: string]` | `unknown` | No | Any additional custom properties you want to attach. | #### TextEditorConfig *** Nested in `CommentAnnotationContext`. | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------------------------------ | | `text` | `string` | Yes | The selected text content. | | `occurrence` | `number` | Yes | The 1-based occurrence index of the selected text in the document. | | `editorId` | `string` | No | The editor ID associated with this comment. | #### SelectionContext *** Context extracted from the current Monaco editor selection. | Property | Type | Required | Description | | ------------ | --------------- | -------- | ---------------------------------------------------------- | | `text` | `string` | Yes | Selected text content. | | `range` | `monaco.IRange` | Yes | Monaco range for the selection. | | `occurrence` | `number` | Yes | 1-based index of `text` among all matches in the document. | | `locationId` | `string` | No | Optional Velt location id. | #### AnchorEntry *** Internal anchor data tracked for Monaco comment rendering. | Property | Type | Required | Description | | ------------------------- | --------- | -------- | ------------------------------------------------- | | `decorationId` | `string` | Yes | Monaco decoration ID used to track the anchor. | | `text` | `string` | Yes | Anchor text. | | `occurrence` | `number` | Yes | 1-based occurrence index of the anchor text. | | `multiThreadAnnotationId` | `string` | No | Velt annotation ID associated with the anchor. | | `isSelected` | `boolean` | Yes | Whether the anchor is currently selected in Velt. | #### SyncAnchor *** Resolved Monaco anchor data used while synchronizing Velt comment annotations to editor ranges. | Property | Type | Required | Description | | ------------------------- | --------------- | -------- | ------------------------------------------------- | | `id` | `string` | Yes | Anchor ID. | | `range` | `monaco.IRange` | Yes | Current Monaco range for the anchor. | | `text` | `string` | Yes | Anchor text. | | `occurrence` | `number` | Yes | 1-based occurrence index of the anchor text. | | `multiThreadAnnotationId` | `string` | No | Velt annotation ID associated with the anchor. | | `isSelected` | `boolean` | Yes | Whether the anchor is currently selected in Velt. | ### SuperDoc #### AddCommentArgs *** Request interface for the SuperDoc `addComment()` function. | Property | Type | Required | Description | | ---------- | ------------------ | -------- | ----------------------------- | | `instance` | `SuperDocInstance` | Yes | The SuperDoc editor instance. | #### AddCommentResult *** Return shape from SuperDoc `addComment()` when the call succeeds. The function returns `null` when no text is selected or Velt is not loaded. | Property | Type | Required | Description | | ------------------ | ----------------------------------------- | -------- | ---------------------------------------------------- | | `veltAnnotationId` | `string` | Yes | The Velt annotation id assigned by the SDK. | | `textEditorConfig` | [`TextEditorConfig`](#texteditorconfig-5) | Yes | The durable logical anchor stored on the annotation. | #### RenderCommentsArgs *** Request interface for the SuperDoc `renderComments()` function. | Property | Type | Required | Description | | -------------------- | ------------------------------------------ | -------- | -------------------------------- | | `instance` | `SuperDocInstance` | Yes | The SuperDoc editor instance. | | `commentAnnotations` | `CommentAnnotation[] \| null \| undefined` | Yes | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### SuperDocVeltCommentsConfig *** Configuration options for `SuperDocVeltComments.configure()`. | Property | Type | Required | Description | | ------------------------- | --------- | -------- | ------------------------------------------------------------------ | | `editorId` | `string` | No | Unique identifier for this editor instance. Default: `'superdoc'`. | | `scrollToSelectedComment` | `boolean` | No | Scroll a selected thread's text into view. Default: `true`. | #### AttachedExtension *** Handle returned by `SuperDocVeltComments.configure(...).attach(instance)`. | Property | Type | Required | Description | | -------- | ------------ | -------- | -------------------------------------------------------------- | | `detach` | `() => void` | Yes | Removes every SuperDoc listener and clears per-instance state. | #### TextEditorConfig *** Logical anchor stored in `annotation.context.textEditorConfig`. Physical rectangles are re-derived at render time from the live document, so pixel coordinates and raw editor positions are not persisted. | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------------------- | | `editorId` | `string` | Yes | The editor id associated with this comment. | | `documentId` | `string` | No | Optional host document id. Velt already scopes per doc. | | `text` | `string` | Yes | The canonicalized selected text. | | `occurrence` | `number` | Yes | 1-based count of this exact text in the document. | ### Nutrient #### AddCommentArgs *** Request interface for the Nutrient `addComment()` function. | Property | Type | Required | Description | | ---------- | ------------------ | -------- | ----------------------------- | | `instance` | `NutrientInstance` | Yes | The Nutrient viewer instance. | #### AddCommentResult *** Return shape from Nutrient `addComment()` when the call succeeds. The function returns `null` when no text is selected or Velt is not loaded. | Property | Type | Required | Description | | ------------------ | ------------------------------------------------ | -------- | ---------------------------------------------------- | | `veltAnnotationId` | `string` | Yes | The Velt annotation id assigned by the SDK. | | `textEditorConfig` | [`TextEditorConfig`](#nutrient-texteditorconfig) | Yes | The durable logical anchor stored on the annotation. | #### RenderCommentsArgs *** Request interface for the Nutrient `renderComments()` function. | Property | Type | Required | Description | | -------------------- | ------------------------------------------ | -------- | -------------------------------- | | `instance` | `NutrientInstance` | Yes | The Nutrient viewer instance. | | `commentAnnotations` | `CommentAnnotation[] \| null \| undefined` | Yes | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### NutrientVeltCommentsConfig *** Configuration options for `NutrientVeltComments.configure()`. | Property | Type | Required | Description | | ------------------------- | --------- | -------- | ------------------------------------------------------------------ | | `editorId` | `string` | No | Unique identifier for this viewer instance. Default: `'nutrient'`. | | `scrollToSelectedComment` | `boolean` | No | Scroll a selected thread's text into view. Default: `true`. | #### AttachedExtension *** Handle returned by `NutrientVeltComments.configure(...).attach(instance)`. | Property | Type | Required | Description | | -------- | ------------ | -------- | -------------------------------------------------------------- | | `detach` | `() => void` | Yes | Removes every Nutrient listener and clears per-instance state. | #### TextEditorConfig *** Logical anchor stored in `annotation.context.textEditorConfig`. Physical rectangles are re-derived at render time from the live PDF text, so pixel coordinates and raw viewer positions are not persisted. | Property | Type | Required | Description | | ------------ | -------- | -------- | --------------------------------------------- | | `editorId` | `string` | Yes | The editor id associated with this comment. | | `text` | `string` | Yes | The canonicalized selected text. | | `pageNumber` | `number` | Yes | 1-based page number where the comment lives. | | `occurrence` | `number` | Yes | 1-based count of this exact text on the page. | ### SpreadJS #### AddCommentArgs *** Request interface for the SpreadJS `addComment()` function. | Property | Type | Required | Description | | ---------- | ---------------- | -------- | ------------------------------- | | `instance` | `SpreadInstance` | Yes | The SpreadJS workbook instance. | #### AddCommentResult *** Return shape from SpreadJS `addComment()` when the call succeeds. The function returns `null` when no cell/range is selected or Velt is not loaded. | Property | Type | Required | Description | | ------------------ | ------------------------------------------------ | -------- | ---------------------------------------------------- | | `veltAnnotationId` | `string` | Yes | The Velt annotation id assigned by the SDK. | | `textEditorConfig` | [`TextEditorConfig`](#spreadjs-texteditorconfig) | Yes | The durable logical anchor stored on the annotation. | #### RenderCommentsArgs *** Request interface for the SpreadJS `renderComments()` function. | Property | Type | Required | Description | | -------------------- | ------------------------------------------ | -------- | -------------------------------- | | `instance` | `SpreadInstance` | Yes | The SpreadJS workbook instance. | | `commentAnnotations` | `CommentAnnotation[] \| null \| undefined` | Yes | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### SpreadJSVeltCommentsConfig *** Configuration options for `SpreadJSVeltComments.configure()`. | Property | Type | Required | Description | | ------------------------- | --------- | -------- | ---------------------------------------------------------------------------------- | | `editorId` | `string` | No | Unique identifier for this workbook instance. Default: `'spreadjs'`. | | `scrollToSelectedComment` | `boolean` | No | Activate a selected thread's sheet and scroll its cell into view. Default: `true`. | #### AttachedExtension *** Handle returned by `SpreadJSVeltComments.configure(...).attach(instance)`. | Property | Type | Required | Description | | -------- | ------------ | -------- | -------------------------------------------------------------- | | `detach` | `() => void` | Yes | Removes every SpreadJS listener and clears per-instance state. | #### TextEditorConfig *** Logical anchor stored in `annotation.context.textEditorConfig`. Physical rectangles are re-derived at render time with `Worksheet.getCellRect`, so pixel coordinates are not persisted. | Property | Type | Required | Description | | ------------ | -------- | -------- | --------------------------------------------------------------------- | | `editorId` | `string` | Yes | The editor id associated with this comment. | | `documentId` | `string` | No | Optional host workbook/document id. Velt already scopes per document. | | `sheetName` | `string` | Yes | Authoritative sheet identity; survives sheet reordering. | | `sheetIndex` | `number` | No | Sheet index hint only; `sheetName` wins on mismatch. | | `row` | `number` | Yes | 0-based top-left row of the anchored cell/range. | | `col` | `number` | Yes | 0-based top-left column of the anchored cell/range. | | `rowCount` | `number` | Yes | Row span; `1` means a single cell. | | `colCount` | `number` | Yes | Column span; `1` means a single cell. | ### Messages #### ENUMs | Enum Name | Event Type | Description | | ---------------- | --------------- | -------------------------- | | `ADD_COMMENT` | `addComment` | Add a new comment | | `UPDATE_COMMENT` | `updateComment` | Update an existing comment | | `DELETE_COMMENT` | `deleteComment` | Delete a comment | #### Comment *** | Property | Type | Required | Description | | ----------------------- | -------------------------------------- | -------- | ------------------------------------------------------------------------ | | `commentId` | `number` | Yes | Unique identifier for the comment pin annotation. Auto generated. | | `type` | `'text' \| 'voice'` | Yes | This determines the comment content type. Default is 'text'. | | `commentText` | `string` | Yes | The actual text content of the comment. | | `commentHtml` | `string` | No | Same comment text but formatted in HTML. | | `replaceContentHtml` | `string` | No | HTML content to replace the comment text when user accepts the comment. | | `replaceContentText` | `string` | No | Text content to replace the comment text when user accepts the comment. | | `commentVoiceUrl` | `string` | No | URL of the voice recording for the comment, if available. | | `from` | `User` | Yes | The user who created this comment. | | `to` | `User[]` | No | List of users that were @mentioned in this comment. | | `lastUpdated` | `Date` | No | Timestamp of when this comment was last updated. Auto generated. | | `editedAt` | `any` | No | Timestamp of when this comment was edited. Auto generated. | | `createdAt` | `any` | No | Timestamp of when this comment was created. Auto generated. | | `isEdited` | `boolean` | No | Whether the comment has been edited. Auto generated. | | `status` | `'added' \| 'updated'` | Yes | Status of the comment indicating whether it was newly added or updated. | | `attachments` | `Attachment[]` | Yes | List of attachments associated with the comment. | | `recorders` | `RecordedData[]` | Yes | List of recorded data associated with the comment. | | `reactionAnnotationIds` | `string[]` | Yes | List of annotation IDs for reactions to the comment. | | `reactionAnnotations` | \[`ReactionAnnotation[]`] | No | List of reaction annotations associated with the comment. | | `taggedUserContacts` | `AutocompleteUserContactReplaceData[]` | Yes | List of users that were @mentioned in this comment with UI metadata. | | `customList` | `AutocompleteReplaceData[]` | Yes | List of custom list items added to the comment. | | `isDraft` | `boolean` | Yes | Whether the comment is in draft state. | | `sourceType` | `string` | No | Origin of the comment; `'agent'` indicates AI-agent-authored. Read-only. | | `agent` | [`AgentData`](#agentdata) | No | AI agent identity + output for an agent-authored comment. Read-only. | | `metadata` | `any` | No | Customer-supplied metadata bag, persisted as-is when provided. | #### AddCommentEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `commentId` | `number` | Yes | ID of the comment | | `comment` | `Comment` | Yes | Comment Object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### UpdateCommentEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `commentId` | `number` | Yes | ID of the comment | | `comment` | `Comment` | Yes | Comment Object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### DeleteCommentEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `commentId` | `number` | Yes | ID of the comment | | `comment` | `Comment` | Yes | Comment Object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### AddCommentRequest *** | Property | Type | Required | Description | | -------------- | ----------------------------------------------------- | -------- | --------------------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `comment` | `Comment` | Yes | Comment object | | `assignedTo` | `User` | No | Assigned user | | `assigned` | `boolean` | No | Whether the comment is assigned | | `visibility` | [`CommentVisibilityConfig`](#commentvisibilityconfig) | No | Set visibility at comment creation time | | `options` | `RequestOptions` | No | Request options | #### UpdateCommentRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `comment` | `Comment` | Yes | Comment object | | `merge` | `boolean` | No | Merge comments | | `options` | `RequestOptions` | No | Request options | #### DeleteCommentRequest *** | Property | Type | Required | Description | | ------------------------------ | ---------------- | -------- | ------------------------ | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `skipDeleteThreadConfirmation` | `boolean` | No | Skip delete confirmation | | `options` | `RequestOptions` | No | Request options | #### GetCommentRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | ### @Mentions #### ENUMs | Enum Name | Event Type | Description | | -------------------------------- | ------------------------------ | ------------------------------------------------------------------ | | `ASSIGN_USER` | `assignUser` | Assign a user to a comment | | `SUBSCRIBE_COMMENT_ANNOTATION` | `subscribeCommentAnnotation` | Subscribe to a comment annotation | | `UNSUBSCRIBE_COMMENT_ANNOTATION` | `unsubscribeCommentAnnotation` | Unsubscribe from a comment annotation | | `AUTOCOMPLETE_SEARCH` | `autocompleteSearch` | When user starts searching for a contact in the @mentions dropdown | #### AssignUserRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `assignedTo` | `UserContact` | Yes | User to assign | | `options` | `RequestOptions` | No | Request options | #### GetContactListResponse *** | Property | Type | Required | Description | | -------------------- | ------------- | -------- | -------------------------------------------------- | | `organizationUsers` | `User[]` | No | List of users in the organization | | `folderUsers` | `User[]` | No | List of users added to the folder | | `documentUsers` | `User[]` | No | List of users added to the document | | `userGroups` | `UserGroup[]` | No | List of user groups in the organization | | `updatedContactList` | `User[]` | No | List of contacts updated via updateContactList API | #### SubscribeCommentAnnotationRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### UnsubscribeCommentAnnotationRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### AutocompleteItem *** | Property | Type | Required | Description | | ------------- | -------- | -------- | ------------------------- | | `id` | `string` | Yes | Unique identifier | | `name` | `string` | Yes | Name of the item | | `description` | `string` | No | Optional description | | `icon` | `object` | No | Optional icon information | | `icon.url` | `string` | No | URL of the icon | | `link` | `string` | No | Link associated with item | #### AutocompleteUserContactReplaceData *** | Property | Type | Required | Description | | --------- | -------- | -------- | ----------------------------------------------------------------- | | `text` | `string` | Yes | The text displayed in the comment that represents the tagged user | | `userId` | `string` | Yes | The user ID of the tagged user | | `contact` | `User` | No | The user object of the tagged user | #### AutocompleteReplaceData *** | Property | Type | Required | Description | | -------- | ------------------ | -------- | ----------------------------------------------------------------- | | `text` | `string` | Yes | The text displayed in the comment that represents the custom item | | `custom` | `AutocompleteItem` | Yes | The custom item object associated with this text | #### AutocompleteItem *** | Property | Type | Required | Description | | ------------- | -------------------------------- | -------- | -------------------------------------------------------------- | | `id` | `string` | Yes | Unique identifier for the autocomplete item | | `name` | `string` | Yes | Name or label of the autocomplete item | | `description` | `string` | No | Additional description of the autocomplete item | | `icon` | `{ url?: string, svg?: string }` | No | Icon associated with the autocomplete item (URL or inline SVG) | | `groupId` | `string` | No | Optional group id to categorize this item | | `link` | `string` | No | Optional link associated with the autocomplete item | #### AutocompleteData *** | Property | Type | Required | Description | | ------------- | ---------------------------------- | -------- | -------------------------------------------------- | | `hotkey` | `string` | Yes | The hotkey or trigger for this autocomplete data | | `description` | `string` | No | Optional description of the autocomplete data | | `type` | `'custom' \| 'contact' \| 'group'` | Yes | The type of autocomplete data. Default is 'custom' | | `groups` | `AutocompleteGroup[]` | No | Optional groups used to categorize items | | `data` | `AutocompleteItem[]` | Yes | An array of AutocompleteItem objects | #### AutocompleteGroup *** | Property | Type | Required | Description | | -------- | -------- | -------- | --------------------- | | `id` | `string` | Yes | Unique group id | | `name` | `string` | Yes | Display name of group | #### AutocompleteChipConfig *** Wireframe-template context for the inline mention chip rendered in the composer. Injected as the `chip` iteration variable inside `` and its tooltip child tags. | Property | Type | Required | Description | | ------------- | ---------------------------------- | -------- | --------------------------------------------------------- | | `label` | `string` | No | Display label of the chip (shown inline in the composer). | | `name` | `string` | No | Name of the mentioned user, group, or custom item. | | `description` | `string` | No | Secondary text (e.g. email address). | | `icon` | `{ url?: string, svg?: string }` | No | Avatar or icon for the chip tooltip. | | `type` | `'contact' \| 'custom' \| 'group'` | No | The kind of mention this chip represents. | #### FlattenedItem *** A visible-option row produced after grouping and flattening the autocomplete contact list. Used internally by virtual scroll; exposed via `componentConfig.flattenedItems`. | Property | Type | Required | Description | | --------------- | ----------------------------------------------- | -------- | -------------------------------------------------- | | `id` | `string` | Yes | Unique identifier for the flattened row. | | `originalItem` | [`SelectorDataListItem`](#selectordatalistitem) | Yes | The underlying selectable item. | | `isGroupHeader` | `boolean` | No | True when this row is a group header. | | `isGroupMember` | `boolean` | No | True when this row belongs to a group. | | `isNewContact` | `boolean` | No | True when this row is the "add new contact" entry. | | `disabled` | `boolean` | No | Whether this row is disabled. | | `group` | [`GroupData`](#groupdata) | No | Group this row belongs to, if any. | | `groupName` | `string` | No | Display name of the group, if any. | #### GroupData *** A mention group object used in the autocomplete panel when group mentions are enabled. | Property | Type | Required | Description | | --------- | ------------------------------------------------- | -------- | ----------------------------------- | | `id` | `string` | Yes | Unique identifier for the group. | | `name` | `string` | Yes | Display name of the group. | | `members` | [`SelectorDataListItem[]`](#selectordatalistitem) | No | Array of selectable items in group. | #### SelectorDataListItem *** A selectable item in the autocomplete panel — represents a user contact, a group, or a custom autocomplete entry. Exposed as the `option` iteration variable inside ``. | Property | Type | Required | Description | | ------------- | --------------------------------------- | -------- | ----------------------------------------------------- | | `type` | `'contact' \| 'group' \| 'custom'` | Yes | The kind of item. | | `contact` | [`UserContact`](#usercontact) | No | User contact data (when `type` is `'contact'`). | | `group` | `OrganizationUserGroup` | No | Organization group data (when `type` is `'group'`). | | `customGroup` | `{ id: string; name: string }` | No | Lightweight custom group info. | | `custom` | [`AutocompleteItem`](#autocompleteitem) | No | Custom autocomplete item (when `type` is `'custom'`). | | `disabled` | `boolean` | No | Whether selection is disabled for this item. | #### AutoCompleteScrollConfig *** Configuration for virtual scroll behavior in autocomplete dropdown. | Property | Type | Required | Description | | ------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `itemSize` | `number` | No | Specifies the fixed height of each item in pixels | | `minBufferPx` | `number` | No | The minimum amount of content buffer (in pixels) that must be rendered beyond the visible viewport. If the buffer falls below this amount, the viewport will render more items | | `maxBufferPx` | `number` | No | The maximum amount of content buffer (in pixels) to render when the `minBufferPx` threshold is crossed. The viewport renders items until the buffer reaches this size | | `templateCacheSize` | `number` | No | Adjusts the size of the view cache. By default, previously created views are cached for reuse; setting this to `0` disables caching, which can be useful if your templates are memory-intensive | #### AssignUserEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `assignedTo` | `UserContact` | Yes | User being assigned | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | No | Event metadata | #### SubscribeCommentAnnotationEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### UnsubscribeCommentAnnotationEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### AutocompleteSearchEvent *** | Property | Type | Required | Description | | ------------ | -------------------------------------- | -------- | -------------------------------------------------------------------- | | `event` | `KeyboardEvent \| InputEvent \| Event` | Yes | The triggering event | | `searchText` | `string` | Yes | The search text entered | | `type` | `'contact' \| 'custom'` | No | Type of autocomplete search. Whether is the @mentions or custom list | | `metadata` | `VeltEventMetadata` | No | Event metadata | #### LinkClickedEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | -------------------------------- | | `text` | `string` | Yes | The clicked link text | | `link` | `string` | Yes | The clicked URL | | `commentAnnotation` | `CommentAnnotation` | Yes | Related comment annotation | | `commentId` | `number` | Yes | The comment id within the thread | | `metadata` | `VeltEventMetadata` | No | Event metadata | ### Custom List #### ENUMs | Enum Name | Event Type | Description | | --------------------- | -------------------- | ---------------------------------------------------------------------- | | `AUTOCOMPLETE_SEARCH` | `autocompleteSearch` | When user starts searching for a list item in the custom list dropdown | #### AutocompleteSearchEvent *** | Property | Type | Required | Description | | ------------ | -------------------------------------- | -------- | -------------------------------------------------------------------- | | `event` | `KeyboardEvent \| InputEvent \| Event` | Yes | The triggering event | | `searchText` | `string` | Yes | The search text entered | | `type` | `'contact' \| 'custom'` | No | Type of autocomplete search. Whether is the @mentions or custom list | | `metadata` | `VeltEventMetadata` | No | Event metadata | ### Attachments #### ENUMs | Enum Name | Event Type | Description | | ----------------------------- | --------------------------- | ---------------------------------------------------- | | `ADD_ATTACHMENT` | `addAttachment` | Add an attachment to a comment | | `DELETE_ATTACHMENT` | `deleteAttachment` | Delete an attachment from a comment | | `ATTACHMENT_DOWNLOAD_CLICKED` | `attachmentDownloadClicked` | Triggered when attachment download button is clicked | #### Attachment *** | Property | Type | Required | Description | | -------------------------- | -------- | -------- | ---------------------------------------------------- | | `attachmentId` | `number` | Yes | Unique identifier for the attachment. Auto-generated | | `name` | `string` | No | File name of the attachment | | `bucketPath` | `string` | No | Path to the file in storage bucket | | `size` | `number` | No | File size of the attachment | | `type` | `string` | No | File type of the attachment | | `url` | `string` | No | Download URL of the attachment | | `thumbnail` | `string` | No | Thumbnail image in base64 format | | `thumbnailWithPlayIconUrl` | `string` | No | URL of the thumbnail with a play icon overlay | | `metadata` | `any` | No | Additional metadata of the attachment | | `mimeType` | `any` | No | MIME type of the attachment | #### FileData *** Pending file selection staged in the comment composer before upload. | Property | Type | Required | Description | | ----------- | --------- | -------- | ---------------------------------------- | | `file` | `File` | Yes | The browser `File` object. | | `url` | `string` | Yes | Object URL for local preview. | | `uploaded` | `boolean` | No | Whether the file has finished uploading. | | `uploading` | `boolean` | No | Whether the file is currently uploading. | | `fileType` | `string` | Yes | MIME type or file-extension string. | #### InvalidFileData *** Rejected file selection in the comment composer (failed validation). | Property | Type | Required | Description | | -------------- | -------- | -------- | ---------------------------------------- | | `file` | `File` | Yes | The browser `File` object. | | `url` | `string` | Yes | Object URL for local preview. | | `errorMessage` | `string` | Yes | Human-readable validation error message. | #### AddAttachmentRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `files` | `File[]` | Yes | Array of files | | `options` | `RequestOptions` | No | Request options | #### DeleteAttachmentRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `attachmentId` | `number` | Yes | ID of the attachment | | `options` | `RequestOptions` | No | Request options | #### GetAttachmentRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `options` | `RequestOptions` | No | Request options | #### UploadFileData *** Configuration object for programmatically adding file attachments to the comment composer. | Property | Type | Required | Description | | ----------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | `files` | `File[]` | Yes | Array of File objects to attach to the comment composer | | `annotationId` | `string` | No | ID of the target comment annotation. Use this to add attachments to an existing comment thread | | `targetElementId` | `string` | No | ID of the target element where the comment composer is attached. Use this to add attachments to a specific element | #### AddAttachmentResponse *** | Property | Type | Required | Description | | ---------------- | ------------ | -------- | ----------------- | | `valid` | `boolean` | Yes | Validity status | | `file` | `File` | No | File object | | `maxAllowedSize` | `number` | Yes | Max allowed size | | `error` | `string` | No | Error message | | `attachment` | `Attachment` | No | Attachment object | #### DeleteAttachmentResolverRequest *** | Property | Type | Required | Description | | -------------- | ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `attachmentId` | `number` | Yes | ID of the attachment | | `metadata` | `AttachmentResolverMetadata` | No | Metadata for the request. Contains only: `apiKey`, `documentId`, `organizationId`, and `folderId` (when present). Internal fields are stripped (v5.0.2-beta.11+). | | `event` | `ResolverActions` | No | Event that triggered the delete | #### SaveAttachmentResolverRequest *** | Property | Type | Required | Description | | ------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `attachment` | `ResolverAttachment` | Yes | Attachment object to save | | `metadata` | `AttachmentResolverMetadata` | No | Metadata for the request. Contains: `apiKey`, `documentId`, `organizationId`, `folderId` (when present), `attachmentId`, and `commentAnnotationId`. | | `event` | `ResolverActions` | No | Event that triggered the save | #### AddAttachmentEvent *** | Property | Type | Required | Description | | ------------------- | ------------------------- | -------- | ----------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `attachments` | `AddAttachmentResponse[]` | Yes | Array of attachment responses | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### AddAttachmentResponse *** | Property | Type | Required | Description | | ---------------- | ------------ | -------- | --------------------------- | | `valid` | `boolean` | Yes | Whether attachment is valid | | `file` | `File` | No | File object | | `maxAllowedSize` | `number` | Yes | Maximum allowed file size | | `error` | `string` | No | Error message if invalid | | `attachment` | `Attachment` | No | Attachment object | #### DeleteAttachmentEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `attachment` | `Attachment` | Yes | Attachment Object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### AttachmentDownloadClickedEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------------- | | `annotationId` | `string` | Yes | ID of the comment annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Full comment annotation object | | `attachment` | `Attachment` | Yes | The attachment that was clicked | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | ### Reactions #### ENUMs | Enum Name | Event Type | Description | | ----------------- | ---------------- | -------------------------------- | | `ADD_REACTION` | `addReaction` | Add a reaction to a comment | | `DELETE_REACTION` | `deleteReaction` | Delete a reaction from a comment | | `TOGGLE_REACTION` | `toggleReaction` | Toggle a reaction on a comment | #### AddReactionRequest *** | Property | Type | Required | Description | | -------------- | -------------------------------------------------------- | -------- | ----------------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `reaction` | `{ reactionId: string; customReaction?: ReactionItem; }` | Yes | Reaction object with reactionId and optional customReaction | | `options` | `RequestOptions` | No | Request options | #### DeleteReactionRequest *** | Property | Type | Required | Description | | -------------- | -------------------------------------------------------- | -------- | ----------------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `reaction` | `{ reactionId: string; customReaction?: ReactionItem; }` | Yes | Reaction object with reactionId and optional customReaction | | `options` | `RequestOptions` | No | Request options | #### ToggleReactionRequest *** | Property | Type | Required | Description | | -------------- | -------------------------------------------------------- | -------- | ----------------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `reaction` | `{ reactionId: string; customReaction?: ReactionItem; }` | Yes | Reaction object with reactionId and optional customReaction | | `options` | `RequestOptions` | No | Request options | #### ReactionItem *** | Property | Type | Required | Description | | -------- | -------- | -------- | --------------------------- | | `url` | `string` | No | URL of the reaction image | | `svg` | `string` | No | SVG markup for the reaction | | `emoji` | `string` | No | Emoji character | #### GetReactionResolverRequest *** | Property | Type | Required | Description | | ----------------------- | ---------- | -------- | ------------------------------------------------------------------- | | `organizationId` | `string` | Yes | ID of the organization to fetch reactions from | | `reactionAnnotationIds` | `string[]` | No | Array of reaction annotation IDs to fetch reactions from | | `documentIds` | `string[]` | No | Array of document IDs to fetch reactions from | | `folderId` | `string` | No | ID of the folder to fetch reactions from | | `allDocuments` | `boolean` | No | Whether to get reactions from all documents within the given folder | #### SaveReactionResolverRequest *** | Property | Type | Required | Description | | -------------------- | ---------------------------------------------- | -------- | --------------------------------------------------------------------------------- | | `reactionAnnotation` | `{ [key: string]: PartialReactionAnnotation }` | Yes | Map of reaction annotation id to reaction annotation data | | `metadata` | `BaseMetadata` | No | Additional metadata for the request. eg: apikey, organizationId, documentId, etc. | | `event` | `ResolverActions` | No | Event name that caused the save request | #### DeleteReactionResolverRequest *** | Property | Type | Required | Description | | ---------------------- | ----------------- | -------- | --------------------------------------------------------------------------------- | | `reactionAnnotationId` | `string` | Yes | ID of the reaction annotation | | `metadata` | `BaseMetadata` | No | Additional metadata for the request. eg: apikey, organizationId, documentId, etc. | | `event` | `ResolverActions` | No | Event name that caused the delete request | #### AddReactionEvent *** | Property | Type | Required | Description | | ------------------- | -------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `commentId` | `number` | Yes | ID of the comment | | `reaction` | `ReactionAnnotation` | Yes | Reaction Object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### DeleteReactionEvent *** | Property | Type | Required | Description | | ------------------- | -------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `commentId` | `number` | Yes | ID of the comment | | `reaction` | `ReactionAnnotation` | Yes | Reaction Object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### ToggleReactionEvent *** | Property | Type | Required | Description | | ------------------- | -------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `commentId` | `number` | Yes | ID of the comment | | `reaction` | `ReactionAnnotation` | Yes | Reaction Object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### ReactionPinType *** Display location for pinned reactions. ```typescript theme={null} type ReactionPinType = "timeline" | "comment" | "standalone"; ``` * `'timeline'`: Pin reaction to timeline view * `'comment'`: Pin reaction to comment context * `'standalone'`: Display reaction independently #### ReactionAnnotation *** A reaction annotation represents a placed emoji reaction on a document, comment, or inline element. | Property | Type | Required | Description | | --------------------- | ------------------------ | -------- | ---------------------------------------------------------------------------- | | `annotationId` | `string` | Yes | Unique identifier for the reaction annotation (auto-generated). | | `from` | `User` | No | User who created the reaction annotation. | | `reactions` | `Reaction[]` | No | List of individual reactions on this annotation. | | `commentAnnotationId` | `string` | No | Connected comment annotation id, when the reaction is on a comment. | | `targetElement` | `TargetElement \| null` | No | Target element the reaction is placed on. | | `targetElementId` | `string \| null` | No | Target element id provided by the user. | | `position` | `CursorPosition \| null` | No | Cursor position where the reaction was placed. | | `locationId` | `number \| null` | No | Unique location id generated from the provided location. | | `location` | `Location \| null` | No | Location to identify the user on a sub-document. | | `type` | `string` | No | Annotation type. Defaults to `'reaction'`. | | `annotationIndex` | `number` | No | Index of this annotation in the available list (1-based). | | `pageInfo` | `PageInfo` | No | Page metadata for the annotation. | | `icon` | `string` | No | Icon identifier for the reaction. | | `iconUrl` | `string` | No | URL of a custom reaction icon image. | | `iconEmoji` | `string` | No | Emoji character used as the reaction icon. | | `lastUpdated` | `any` | No | Timestamp when the annotation was last updated (auto-generated). | | `metadata` | `ReactionMetadata` | No | Custom metadata attached to the annotation. | | `context` | `Context` | No | Context object for the annotation. | | `involvedUserIds` | `string[]` | No | All user IDs involved in the reaction annotation. Read-only, server-derived. | #### Reaction *** A single reaction entry within a `ReactionAnnotation`. | Property | Type | Required | Description | | ------------- | -------- | -------- | -------------------------------------------------------- | | `variant` | `string` | No | Emoji variant identifier. | | `from` | `User` | Yes | User who added the reaction. | | `lastUpdated` | `Date` | No | Timestamp when this reaction was added (auto-generated). | #### ReactionMetadata *** Custom metadata for a reaction annotation. Extends [`BaseMetadata`](#basemetadata) with an open index signature. ```typescript theme={null} class ReactionMetadata extends BaseMetadata { [key: string]: any; } ``` ### Status & Priority #### ENUMs | Enum Name | Event Type | Description | | ---------------------------- | -------------------------- | ----------------------------------------------- | | `UPDATE_STATUS` | `updateStatus` | Update the status of a comment | | `RESOLVE_COMMENT` | `resolveComment` | Resolve a comment | | `UPDATE_PRIORITY` | `updatePriority` | Update the priority of a comment | | `APPROVE_COMMENT_ANNOTATION` | `approveCommentAnnotation` | Approve a comment annotation | | `ACCEPT_COMMENT_ANNOTATION` | `acceptCommentAnnotation` | Accept a comment annotation | | `REJECT_COMMENT_ANNOTATION` | `rejectCommentAnnotation` | Reject a comment annotation | | `SUGGESTION_ACCEPTED` | `suggestionAccepted` | Suggestion accepted (agent- or human-authored). | | `SUGGESTION_REJECTED` | `suggestionRejected` | Suggestion rejected (agent- or human-authored). | #### UpdateStatusRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `status` | `CustomStatus` | Yes | Status value | | `options` | `RequestOptions` | No | Request options | #### ResolveCommentAnnotationRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### UpdatePriorityRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `priority` | `CustomPriority` | No | Priority object | | `options` | `RequestOptions` | No | Request options | #### ApproveCommentAnnotationRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### AcceptCommentAnnotationRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### RejectCommentAnnotationRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### AcceptSuggestionRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### RejectSuggestionRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | ----------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `rejectReason` | `string` | No | Optional reason for rejection | | `options` | `RequestOptions` | No | Request options | #### CustomPriority *** | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------- | | `id` | `string` | Yes | Unique identifier for the custom priority | | `color` | `string` | Yes | Color associated with the custom priority | | `name` | `string` | Yes | Name or label of the custom priority | | `lightColor` | `string` | No | Light color variant for the custom priority | #### CustomStatus *** | Property | Type | Required | Description | | ------------ | ------------ | -------- | -------------------------------------------------------------- | | `id` | `string` | Yes | Unique identifier for the custom status | | `color` | `string` | Yes | Text and comment pin color associated with the custom status | | `name` | `string` | Yes | Name or label of the custom status | | `type` | `StatusType` | Yes | Type of the status (`default`, `ongoing`, or `terminal`) | | `lightColor` | `string` | No | Background color on the status indicator for the custom status | | `iconUrl` | `string` | No | URL to an icon image for the custom status | #### UpdateStatusEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `newStatus` | `CustomStatus` | Yes | New status object | | `oldStatus` | `CustomStatus` | Yes | Previous status object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### ResolveCommentEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### UpdatePriorityEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `newPriority` | `CustomPriority` | No | New Priority object | | `oldPriority` | `CustomPriority` | No | Previous Priority object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### ApproveCommentAnnotationEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### AcceptCommentAnnotationEvent *** | Property | Type | Required | Description | | -------------------- | ------------------- | -------- | ----------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | | `actionUser` | `User` | Yes | User who performed the action | | `replaceContentHtml` | `string` | No | HTML content to replace with | | `replaceContentText` | `string` | No | Text content to replace with | #### RejectCommentAnnotationEvent *** | Property | Type | Required | Description | | -------------------- | ------------------- | -------- | ----------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | | `actionUser` | `User` | Yes | User who performed the action | | `replaceContentHtml` | `string` | No | HTML content to replace with | | `replaceContentText` | `string` | No | Text content to replace with | #### SuggestionAcceptEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### SuggestionRejectEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ----------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `rejectReason` | `string` | No | Reason provided for rejection | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | ### Comment Dialog Primitives Types for the 92+ primitive components used to build custom comment dialog interfaces. See [`Primitive components`](/ui-customization/reference/primitives) for the complete component list and [`Primitives`](/ui-customization/primitives) for usage guidance. #### CommentDialogCommonProps Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Base props inherited by all Comment Dialog primitive components. | Property | Type | Required | Description | | -------------------------- | --------- | -------- | -------------------------------------------------- | | `annotationId` | `string` | No | Annotation ID (required in standalone mode) | | `defaultCondition` | `boolean` | No | When false, always shows component (default: true) | | `inlineCommentSectionMode` | `boolean` | No | Enables inline comment section mode | | `commentPinSelected` | `boolean` | No | Comment pin selection state | | `fullExpanded` | `boolean` | No | Full expansion state | #### CommentDialogContextWrapperProps Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for the VeltCommentDialogContextWrapper component. | Property | Type | Required | Description | | -------------------- | --------- | -------- | ------------------------------------ | | `annotationId` | `string` | Yes | Annotation ID for children | | `commentId` | `string` | No | Comment ID for children | | `attachmentId` | `string` | No | Attachment ID for children | | `commentPinSelected` | `boolean` | No | Selection state for children | | `[key: string]` | `any` | No | Custom attributes passed via context | #### ThreadCardProps Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for VeltCommentDialogThreadCard with priority-based comment lookup. | Property | Type | Required | Description | | -------------- | -------- | -------- | ------------------------------------ | | `commentObj` | `object` | No | Direct comment object (Priority 1) | | `commentId` | `number` | No | Comment ID for lookup (Priority 2) | | `commentIndex` | `number` | No | Index in comments array (Priority 3) | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### CommentIndexProps Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for thread card sub-components that require a comment index. | Property | Type | Required | Description | | -------------- | -------- | -------- | ------------------------- | | `commentIndex` | `number` | No | Index of comment in array | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### ComposerProps Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for VeltCommentDialogComposer with placeholder and edit mode options. | Property | Type | Required | Description | | ------------------------- | --------- | -------- | ----------------------------------------------------------------- | | `placeholder` | `string` | No | Primary placeholder (Priority 1) | | `commentPlaceholder` | `string` | No | Placeholder for new comment | | `replyPlaceholder` | `string` | No | Placeholder for reply | | `editPlaceholder` | `string` | No | Placeholder for edit mode | | `editMode` | `boolean` | No | Enables edit mode | | `commentObj` | `object` | No | Comment object for edit mode | | `commentIndex` | `number` | No | Index of comment being edited | | `targetComposerElementId` | `string` | No | Unique identifier for programmatic submission via submitComment() | | `context` | `object` | No | Custom context data to attach to comment | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### ComposerInputProps Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for VeltCommentDialogComposerInput. | Property | Type | Required | Description | | ------------- | -------- | -------- | ---------------------- | | `placeholder` | `string` | No | Input placeholder text | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### StatusDropdownItemProps Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for VeltCommentDialogStatusDropdownContentItem with priority-based status lookup. | Property | Type | Required | Description | | ------------- | -------- | -------- | ------------------------------------ | | `statusObj` | `object` | No | Direct status object (Priority 1) | | `statusId` | `string` | No | Status ID for lookup (Priority 2) | | `statusIndex` | `number` | No | Index in statuses array (Priority 3) | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### PriorityDropdownItemProps Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for VeltCommentDialogPriorityDropdownContentItem with priority-based priority lookup. | Property | Type | Required | Description | | --------------- | -------- | -------- | -------------------------------------- | | `priorityObj` | `object` | No | Direct priority object (Priority 1) | | `priorityId` | `string` | No | Priority ID for lookup (Priority 2) | | `priorityIndex` | `number` | No | Index in priorities array (Priority 3) | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### OptionsDropdownProps Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for VeltCommentDialogOptionsDropdown with feature enable flags. | Property | Type | Required | Description | | ------------------------------ | --------- | -------- | -------------------------------- | | `commentIndex` | `number` | No | Index of comment for options | | `enableAssignment` | `boolean` | No | Enable assignment option | | `allowAssignment` | `boolean` | No | V4 alias for enableAssignment | | `enableEdit` | `boolean` | No | Enable edit option | | `allowEdit` | `boolean` | No | V4 alias for enableEdit | | `enableNotifications` | `boolean` | No | Enable notifications option | | `allowNotifications` | `boolean` | No | V4 alias for enableNotifications | | `allowToggleNotification` | `boolean` | No | V4 alias for enableNotifications | | `enablePrivateMode` | `boolean` | No | Enable private mode option | | `allowPrivateMode` | `boolean` | No | V4 alias for enablePrivateMode | | `allowChangeCommentAccessMode` | `boolean` | No | V4 alias for enablePrivateMode | | `enableMarkAsRead` | `boolean` | No | Enable mark as read option | | `allowMarkAsRead` | `boolean` | No | V4 alias for enableMarkAsRead | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### CustomAnnotationItemProps Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for custom annotation dropdown items. | Property | Type | Required | Description | | -------- | -------- | -------- | ---------------- | | `item` | `object` | No | Item data object | | `index` | `number` | No | Item index | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### ReplyAvatarsListItemProps Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for VeltCommentDialogReplyAvatarsListItem. | Property | Type | Required | Description | | -------- | --------------- | -------- | --------------------- | | `user` | [`User`](#user) | Yes | User data object | | `index` | `number` | Yes | Index of user in list | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### CommentDialogSuggestionProps ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogsuggestion) Props for VeltCommentDialogSuggestion and its sub-components. Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### IVeltCommentDialogThreadCardReactionPinProps *** Props for VeltCommentDialogThreadCard.ReactionPin to display specific pinned reactions. | Property | Type | Required | Description | | ------------ | -------- | -------- | --------------------------------------------- | | `reactionId` | `string` | No | Unique reaction identifier to pin and display | #### IVeltCommentDialogThreadCardReactionsProps *** Props for VeltCommentDialogThreadCard.Reactions to filter displayed reactions. | Property | Type | Required | Description | | -------------------- | ---------- | -------- | ------------------------------------ | | `excludeReactionIds` | `string[]` | No | Reaction IDs to exclude from display | #### IVeltCommentDialogThreadCardReactionToolProps *** Props for VeltCommentDialogThreadCard.ReactionTool to filter reaction picker options. | Property | Type | Required | Description | | -------------------- | ---------- | -------- | ----------------------------------- | | `excludeReactionIds` | `string[]` | No | Reaction IDs to exclude from picker | ### Recordings #### ENUMs | Enum Name | Event Type | Description | | ------------------ | ----------------- | --------------------------------- | | `DELETE_RECORDING` | `deleteRecording` | Delete a recording from a comment | #### GetRecordingRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `options` | `RequestOptions` | No | Request options | #### DeleteRecordingRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `recorderId` | `string` | Yes | ID of the recorder | | `options` | `RequestOptions` | No | Request options | #### DeleteRecordingEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `commentId` | `number` | Yes | ID of the comment | | `recording` | `RecordedData` | Yes | Recording data | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | ### Deep Links #### ENUMs | Enum Name | Event Type | Description | | ----------- | ---------- | ----------------------------- | | `COPY_LINK` | `copyLink` | Copy a deep link to a comment | #### GetLinkRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### CopyLinkRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### CopyLinkEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `link` | `string` | Yes | Copied link | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### GetLinkResponse *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `link` | `string \| null` | Yes | Generated link | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | ### Access #### ENUMs | Enum Name | Event Type | Description | | --------------- | -------------- | ------------------------------------ | | `UPDATE_ACCESS` | `updateAccess` | Update access settings for a comment | #### UpdateAccessRequest *** | Property | Type | Required | Description | | -------------- | ------------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `accessMode` | `CommentAccessMode` | Yes | Access mode | | `options` | `RequestOptions` | No | Request options | #### UpdateAccessEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `newAccessMode` | `CommentAccessMode` | No | New access mode | | `oldAccessMode` | `CommentAccessMode` | No | Previous access mode | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### UserPermissionAccessRole *** String-literal union used for resource access roles: ```typescript theme={null} type UserPermissionAccessRole = 'editor' | 'viewer'; ``` * `'editor'`: Write access * `'viewer'`: Read-only access #### UserPermissionAccessRoleResult *** ```typescript theme={null} type UserPermissionAccessRoleResult = | 'does_not_exist' | 'permission_denied' | 'something_went_wrong'; ``` Error codes returned when permission resolution fails: * `does_not_exist`: The requested resource (organization, folder, or document) does not exist * `permission_denied`: The user does not have permission to access the requested resource * `something_went_wrong`: An unexpected error occurred during permission resolution #### GetUserPermissionsRequest *** | Property | Type | Required | Description | | ---------------- | ---------- | -------- | -------------------------------------------- | | `organizationId` | `string` | No | Organization to scope the permission lookup. | | `folderIds` | `string[]` | No | Folder IDs to include in the lookup. | | `documentIds` | `string[]` | No | Document IDs to include in the lookup. | #### UserPermissionInfo *** | Property | Type | Required | Description | | ------------ | -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `accessRole` | `UserPermissionAccessRole` | No | Access role for the resource. | | `accessType` | `string` | No | The effective access type for the resource: `'public'`, `'restricted'`, or `'organizationPrivate'`. Documents inside folders inherit the folder's `accessType`. Also present on `PERMISSION_DENIED` entries. | | `expiresAt` | `number` | No | Expiry (Unix ms) for temporary access, if applicable. | | `error` | `string` | No | Error message if permission resolution failed. | | `errorCode` | `UserPermissionAccessRoleResult` | No | Error code indicating the type of permission resolution failure. | | `context` | `{ accessFields?: string[] }` | No | Context access information with accessFields array. | #### GetUserPermissionsResponse *** Map of user IDs to their resolved permissions across organization, folders, and documents. | Property | Type | Required | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------- | | `[userId: string]` | `{ folders?: Record; organization?: Record; documents?: Record; }` | Yes | Permissions for a user, keyed by resource scope and ID. | ### UI #### AssignToType *** UI mode for assignment functionality. ```typescript theme={null} type AssignToType = "dropdown" | "checkbox"; ``` * `'dropdown'`: Default assignment menu with team member selection * `'checkbox'`: Quick self-assignment toggle mode #### ENUMs | Enum Name | Event Type | Description | | ------------------------ | ---------------------- | -------------------------------------------------------------------- | | `COMPOSER_CLICKED` | `composerClicked` | Triggered when comment composer is clicked | | `COMMENT_PIN_CLICKED` | `commentPinClicked` | Triggered when a comment pin is clicked | | `COMPOSER_TEXT_CHANGE` | `composerTextChange` | Triggered when text changes in a comment composer | | `COMMENT_TOOL_CLICKED` | `commentToolClicked` | Past-tense alias for `commentToolClick` | | `SIDEBAR_BUTTON_CLICKED` | `sidebarButtonClicked` | Past-tense alias for `sidebarButtonClick` | | `COMMENT_SAVE_TRIGGERED` | `commentSaveTriggered` | Triggered immediately when save button is clicked, before async save | #### ComposerClickedEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | --------------------------------------------------------------------------------------- | | `commentAnnotation` | `CommentAnnotation` | No | Comment annotation object. This is `undefined` if it's a new comment annotation object. | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### ComposerTextChangeEvent *** | Property | Type | Required | Description | | ------------------------- | ----------------------------------------- | -------- | ---------------------------------------------------------------- | | `text` | `string` | Yes | Current text content in the composer | | `annotation` | [`CommentAnnotation`](#commentannotation) | Yes | Full draft annotation with attachments, recordings, tagged users | | `targetComposerElementId` | `string` | Yes | Unique identifier of the composer that triggered the event | | `metadata` | [`VeltEventMetadata`](#velteventmetadata) | No | Event metadata including document and location context | #### CommentPinClickedEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | No | Event metadata | #### CommentToolClickedEvent *** | Property | Type | Required | Description | | ----------------- | -------------------------------- | -------- | ------------------------------------------------ | | `context` | `{ [key: string]: any } \| null` | No | Custom context data when comment tool is clicked | | `metadata` | `VeltEventMetadata` | No | Event metadata | | `targetElementId` | `string` | No | ID of the target element if available | #### SidebarButtonClickedEvent *** | Property | Type | Required | Description | | ---------- | ------------------- | -------- | -------------- | | `metadata` | `VeltEventMetadata` | No | Event metadata | ### Comment Sidebar #### CommentCountType *** Union type for specifying comment count display mode. ```typescript theme={null} type CommentCountType = "total" | "unread"; ``` * `'total'`: Shows total count of all comments * `'unread'`: Shows count of unread comments only #### SidebarFilterCriteria *** Filter criteria for minimal filter dropdown in sidebar. ```typescript theme={null} type SidebarFilterCriteria = | "status" | "priority" | "category" | "people" | "assignedToMe"; ``` Available filter criteria for sidebar filtering. #### SidebarSortingCriteria *** Sorting criteria for minimal filter dropdown in sidebar and multi-thread comment dialog. ```typescript theme={null} type SidebarSortingCriteria = 'date' | 'unread' | null; ``` * `'date'`: Sort by date * `'unread'`: Sort by unread status * `null`: No sorting applied #### SortBy *** The default sort key for the Comment Sidebar V2 (`sortBy` on [`VeltCommentsSidebarV2Props`](#veltcommentssidebarv2props)). A built-in preset (e.g. `'date'`, `'unread'`) or a custom field key / dot-path (e.g. `'comments.createdAt'`). ```typescript theme={null} type SortBy = string; ``` #### SortOrder *** The default sort direction for the Comment Sidebar V2 (`sortOrder` on [`VeltCommentsSidebarV2Props`](#veltcommentssidebarv2props)). ```typescript theme={null} type SortOrder = 'asc' | 'desc'; ``` #### CommentSidebarSystemFiltersOperator *** String-literal union used to combine system filters: ```typescript theme={null} type CommentSidebarSystemFiltersOperator = 'and' | 'or'; ``` * `'and'`: An annotation must match every active system filter. * `'or'`: An annotation can match any active system filter. #### ENUMs | Enum Name | Event Type | Description | | ----------------------------- | -------------------------- | --------------------------------------------------- | | `COMMENT_SIDEBAR_DATA_INIT` | `commentSidebarDataInit` | Triggered when comment sidebar data is first loaded | | `COMMENT_SIDEBAR_DATA_UPDATE` | `commentSidebarDataUpdate` | Triggered when comment sidebar data is updated | #### CommentStatus *** String-literal union describing comment lifecycle events. This is distinct from [`CustomStatus`](#customstatus), which describes a comment annotation's displayed status. As of **v6.0.0-beta.3**, import `CommentStatus` with `import type` from `@veltdev/types` and pass one of its string values. The package does not expose a runtime `CommentStatus` object. | String value | Description | | ---------------------- | ------------------------------------- | | `'newlyAdded'` | A comment was newly added. | | `'added'` | A comment was added. | | `'updated'` | A comment was updated. | | `'deleted'` | A comment was deleted. | | `'approved'` | A comment was approved. | | `'assigned'` | A comment was assigned. | | `'statusChanged'` | A comment status changed. | | `'priorityChanged'` | A comment priority changed. | | `'accessModeChanged'` | A comment access mode changed. | | `'customListChanged'` | A custom-list value changed. | | `'accepted'` | A suggestion was accepted. | | `'rejected'` | A suggestion was rejected. | | `'reactionAdded'` | A reaction was added. | | `'reactionDeleted'` | A reaction was deleted. | | `'subscribed'` | A user subscribed. | | `'unsubscribed'` | A user unsubscribed. | | `'suggestionAccepted'` | A suggestion annotation was accepted. | | `'suggestionRejected'` | A suggestion annotation was rejected. | #### CommentPriority *** | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------ | | `color` | `string` | Yes | Primary color for the priority. | | `id` | `string` | Yes | Unique identifier for the priority. | | `lightColor` | `string` | Yes | Light variant of the priority color. | | `name` | `string` | Yes | Display name of the priority. | #### CustomFilter *** | Property | Type | Required | Description | | -------- | -------- | -------- | --------------------------------------- | | `id` | `string` | Yes | Unique identifier for the custom filter | | `color` | `string` | Yes | Color associated with the custom filter | | `name` | `string` | Yes | Name or label of the custom filter | #### CustomCategory *** | Property | Type | Required | Description | | -------- | -------- | -------- | ----------------------------------------- | | `id` | `string` | Yes | Unique identifier for the custom category | | `color` | `string` | Yes | Color associated with the custom category | | `name` | `string` | Yes | Name or label of the custom category | #### CommentSidebarDataInitEvent *** | Property | Type | Required | Description | | ----------------------------- | ------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- | | `buttonContext` | `VeltButtonContext` | Yes | Button context | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | | `commentAnnotation` | `CommentAnnotation` | No | Comment annotation object | | `comment` | `Comment` | No | Comment object | | `index` | `number` | No | Index value | | `commentAnnotations` | `CommentAnnotation[]` | No | Array of comment annotations | | `systemFilteredAnnotations` | `CommentAnnotation[]` | No | Filtered comment annotations | | `unreadCommentAnnotationsMap` | `{ [commentAnnotationId: string]: number }` | No | Map of unread comment counts | | `customFilters` | `CustomFilters` | No | Custom filters applied in the Comment Sidebar. Only available when custom sidebar filters are used. | #### CommentSidebarDataUpdateEvent *** | Property | Type | Required | Description | | ----------------------------- | ------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- | | `buttonContext` | `VeltButtonContext` | Yes | Button context | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | | `commentAnnotation` | `CommentAnnotation` | No | Comment annotation object | | `comment` | `Comment` | No | Comment object | | `index` | `number` | No | Index value | | `commentAnnotations` | `CommentAnnotation[]` | No | Array of comment annotations | | `systemFilteredAnnotations` | `CommentAnnotation[]` | No | Filtered comment annotations | | `unreadCommentAnnotationsMap` | `{ [commentAnnotationId: string]: number }` | No | Map of unread comment counts | | `customFilters` | `CustomFilters` | No | Custom filters applied in the Comment Sidebar. Only available when custom sidebar filters are used. | #### FullscreenClickEvent *** Emitted by the `fullscreenClick` event when the Comment Sidebar V2 fullscreen toggle is clicked. | Property | Type | Required | Description | | ------------ | ------------------- | -------- | ----------------------------------------------------------- | | `fullScreen` | `boolean` | Yes | Fullscreen state after the toggle. `true` = now fullscreen. | | `metadata` | `VeltEventMetadata` | No | Event metadata. | #### CommentSidebarFilterConfig *** | Property | Type | Required | Description | | --------------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ | | `location` | `FilterTypeConfig` | No | Configuration for the location filter type. | | `document` | `FilterTypeConfig` | No | Configuration for the document filter type. Only use it if you are using multiple documents or folders | | `people` | `FilterTypeConfig` | No | Configuration for the author filter type. | | `tagged` | `FilterTypeConfig` | No | Configuration for the tagged/mentioned filter type. | | `assigned` | `FilterTypeConfig` | No | Configuration for the assigned filter type. | | `involved` | `FilterTypeConfig` | No | Configuration for the involved filter type (author, mentioned, assigned). | | `priority` | `FilterTypeConfig` | No | Configuration for the priority filter type. | | `category` | `FilterTypeConfig` | No | Configuration for the category filter type. | | `commentType` | `FilterTypeConfig` | No | Configuration for the comment type filter. | | `version` | `FilterTypeConfig` | No | Configuration for the version filter type. | | `status` | `FilterTypeConfig` | No | Configuration for the status filter type. | | `[key: string]` | `FilterTypeConfig \| undefined` | No | Custom filter type configurations. | #### FilterTypeConfig *** | Property | Type | Required | Description | | ---------------- | ---------------------- | -------- | --------------------------------------------------------------------------------------------- | | `name` | `string` | No | The name of the filter type | | `enable` | `boolean` | No | Enables or disables the filter type | | `multiSelection` | `boolean` | No | Allows multiple selections if set to true | | `enableGrouping` | `boolean` | No | Enables grouping within the filter type if set to true | | `placeholder` | `string` | No | The placeholder text for the filter type. Used when `filterOptionLayout` is set to `dropdown` | | `id` | `string` | No | The unique identifier for the filter type | | `type` | `'custom' \| 'system'` | No | The type of filter - custom or system | | `options` | `FilterOption[]` | No | Array of filter options available for this filter type | #### CommentSidebarGroupConfig *** | Property | Type | Required | Description | | --------------- | ----------------------------------------------------------- | -------- | ---------------------------- | | `enable` | `boolean` | No | Enables or disables grouping | | `name` | `string` | No | The name of the group | | `[key: string]` | `{ id?: string, name?: string }[] \| string[] \| undefined` | No | Custom filter configurations | #### FilterField *** Declarative definition of a single filterable field in the Comment Sidebar V2 filter dropdown. | Property | Type | Required | Description | | -------------- | --------------------------------------------- | -------- | --------------------------------------------------------------------------------------- | | `field` | `string` | Yes | Field identifier. Use a [`BuiltInFilterFieldId`](#builtinfilterfieldid) or a custom id. | | `label` | `string` | No | Display label for the field. | | `select` | `'single' \| 'multi'` | No | Single- or multi-select behavior. | | `searchable` | `boolean` | No | Show a search box within the field's options. | | `showCounts` | `boolean` | No | Show per-option result counts. | | `icon` | `string` | No | Icon identifier for the field. | | `valuePath` | `string` | No | Dot-path into the annotation for a custom field value. | | `includeUnset` | `boolean` | No | Include annotations with no value for this field. | | `placeholder` | `string` | No | Placeholder text for the field's search box. | | `groupable` | `boolean` | No | Allow grouping the list by this field. | | `order` | `string[]` | No | Explicit ordering of option ids. | | `options` | [`SidebarFilterValue[]`](#sidebarfiltervalue) | No | Predefined selectable options for the field. | #### SidebarFilterValue *** A single selectable option within a [`FilterField`](#filterfield). Carries the option's id, display label, and optional count/icon used to render and match the option. #### SidebarMinimalFilterConfig *** Configuration for one dropdown in the Comment Sidebar V2 `minimal-filters` bar. | Property | Type | Required | Description | | --------- | ------------------------------------------------------------------------- | -------- | --------------------------------------------------------------- | | `type` | [`SidebarFilterDropdownType`](#sidebarfilterdropdowntype) | No | Dropdown kind. Defaults vary by usage. | | `label` | `string` | No | Display label for the dropdown. | | `field` | `string` | No | Field identifier for a single-field dropdown. | | `fields` | [`FilterField[]`](#filterfield) | No | Fields shown in a `filter` dropdown. | | `sorts` | `(string \| `[`SidebarSortConfig`](#sidebarsortconfig)`)[]` | No | Sort options shown in a `sort` dropdown. | | `actions` | `(string \| `[`SidebarQuickFilterConfig`](#sidebarquickfilterconfig)`)[]` | No | Quick filters/actions shown in a `quick` or `actions` dropdown. | #### SidebarSortConfig *** A single sort option in a Comment Sidebar V2 sort dropdown. | Property | Type | Required | Description | | -------- | ----------------- | -------- | ------------------------------------------------ | | `label` | `string` | No | Display label for the sort option. | | `preset` | `string` | No | Built-in sort preset, e.g. `'date'`, `'unread'`. | | `path` | `string` | No | Dot-path for a custom-field sort. | | `field` | `string` | No | Field identifier to sort by. | | `order` | `'asc' \| 'desc'` | No | Sort direction. | #### SidebarQuickFilterConfig *** A single quick filter (predicate) in a Comment Sidebar V2 quick/actions dropdown. | Property | Type | Required | Description | | ------------ | --------------------------------------------------- | -------- | --------------------------------------------------------- | | `label` | `string` | No | Display label for the quick filter. | | `preset` | `string` | No | Built-in preset, e.g. `'open'`, `'resolved'`, `'unread'`. | | `path` | `string` | No | Dot-path for a single-predicate match. | | `field` | `string` | No | Field identifier for a single-predicate match. | | `value` | `any` | No | Literal value to match, e.g. a userId `"1.1"`. | | `conditions` | [`SidebarQuickCondition[]`](#sidebarquickcondition) | No | Multiple predicates evaluated together. | | `operator` | `'and' \| 'or'` | No | How `conditions` are combined. | #### SidebarQuickCondition *** A single predicate within a [`SidebarQuickFilterConfig`](#sidebarquickfilterconfig). | Property | Type | Required | Description | | -------- | -------- | -------- | -------------------------------------- | | `path` | `string` | No | Dot-path into the annotation to match. | | `field` | `string` | No | Field identifier to match. | | `value` | `any` | Yes | Value to match against. | #### SidebarAnnotationGroup *** A resolved group of annotations rendered as a collapsible section in the Comment Sidebar V2 list. | Property | Type | Required | Description | | --------------- | ------------------------------------------- | -------- | -------------------------------------------------- | | `id` | `string` | Yes | Unique group identifier. | | `label` | `string` | Yes | Group display label. | | `count` | `number` | Yes | Number of annotations in the group. | | `isExpanded` | `boolean` | Yes | Whether the group is currently expanded. | | `isCurrentPage` | `boolean` | No | Whether the group corresponds to the current page. | | `annotations` | [`CommentAnnotation[]`](#commentannotation) | Yes | Annotations contained in the group. | #### SidebarListRow *** A flattened row in the Comment Sidebar V2 list: either a group header or an annotation belonging to a group. ```typescript theme={null} type SidebarListRow = | { type: 'group'; group: SidebarAnnotationGroup } | { type: 'annotation'; annotation: CommentAnnotation; groupId: string }; ``` #### FilterFieldOperator *** Boolean operator used to combine filter predicates. ```typescript theme={null} type FilterFieldOperator = 'and' | 'or'; ``` #### SidebarFilterDropdownType *** Kind of dropdown rendered in the Comment Sidebar V2 `minimal-filters` bar. ```typescript theme={null} type SidebarFilterDropdownType = 'filter' | 'sort' | 'quick' | 'actions'; ``` #### BUILT\_IN\_FILTER\_FIELD\_IDS *** The built-in filterable field ids recognized by the Comment Sidebar V2 filter pipeline. ```typescript theme={null} const BUILT_IN_FILTER_FIELD_IDS = [ 'status', 'priority', 'category', 'people', 'assigned', 'tagged', 'involved', 'location', 'version', 'document', ] as const; type BuiltInFilterFieldId = typeof BUILT_IN_FILTER_FIELD_IDS[number]; ``` #### BuiltInFilterFieldId *** Union of the built-in filter field ids. Derived from [`BUILT_IN_FILTER_FIELD_IDS`](#built_in_filter_field_ids). #### SectionControlChip *** A control chip rendered in the Comment Sidebar V2 section header. ```typescript theme={null} type SectionControlChip = { id: string; label: string; isAll: boolean }; ``` #### SectionAllOption *** Configuration for the "All" option in a Comment Sidebar V2 section control. ```typescript theme={null} type SectionAllOption = { show: boolean; label: string }; ``` #### SidebarSortCriterion *** A resolved sort criterion produced from a [`SidebarSortConfig`](#sidebarsortconfig). Exported as a helper type for the Comment Sidebar V2 sort pipeline. #### SidebarQuickPredicate *** A resolved quick-filter predicate produced from a [`SidebarQuickFilterConfig`](#sidebarquickfilterconfig). Exported as a helper type for the Comment Sidebar V2 quick-filter pipeline. #### FacetContext *** Context passed to a [`FilterFieldResolver`](#filterfieldresolver) when building options for a custom filterable field. | Property | Type | Required | Description | | ------------- | ------------------------------------------- | -------- | --------------------------------------------- | | `annotations` | [`CommentAnnotation[]`](#commentannotation) | Yes | Annotations available to build facet options. | | `field` | [`FilterField`](#filterfield) | Yes | The field definition being resolved. | #### FilterFieldResolver *** Registers a custom filterable field in the Comment Sidebar V2 pipeline by supplying option-building and matching logic. | Property | Type | Required | Description | | -------------- | -------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------- | | `id` | `string` | Yes | Field id this resolver handles. | | `optionSource` | `'catalog' \| 'scan'` | Yes | Whether options come from a catalog or by scanning annotations. | | `buildOptions` | `(ctx:` [`FacetContext`](#facetcontext)`) =>` [`SidebarFilterValue[]`](#sidebarfiltervalue) | Yes | Builds selectable options for the field. | | `matches` | `(annotation:` [`CommentAnnotation`](#commentannotation)`, selectedValueIds: string[]) => boolean` | Yes | Returns whether an annotation matches the selected option ids. | #### CommentSidebarFilters *** For location and user filters, provide at least one documented identity field in each object. | Property | Type | Required | Description | | --------------- | ----------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `location` | `{ id?: string \| number; locationName?: string }[]` | No | Filter by location identity. `id` takes precedence; a non-empty `locationName` is used when `id` is absent. | | `document` | `{ id: string }[]` | No | Filter by document ids | | `people` | `{ userId?: string; email?: string }[]` | No | Filter by comment author. `email` is used when `userId` is absent. | | `tagged` | `{ userId?: string; email?: string }[]` | No | Filter by tagged or mentioned users. `email` is used when `userId` is absent. | | `assigned` | `{ userId?: string; email?: string }[]` | No | Filter by assigned users. `email` is used when `userId` is absent. | | `involved` | `{ userId?: string; email?: string }[]` | No | Filter by involved users (author, mentioned, or assigned). `email` is used when `userId` is absent. | | `priority` | `string[]` | No | Filter by priority ids | | `status` | `string[]` | No | Filter by status ids | | `category` | `string[]` | No | Filter by category ids | | `version` | `{ id: string }[]` | No | Filter by version ids | | `accessModes` | [`CommentAccessMode`](#commentaccessmode)`[]` | No | Filter by access mode. Recognizes both legacy `iam.accessMode` and `visibilityConfig` (`restricted`, `organizationPrivate` → `'private'`; `public` → `'public'`). | | `[key: string]` | `string[] \| { id?: string; name?: string }[] \| undefined` | No | Custom field selections represented by string values or objects containing `id` and `name`. | #### CommentAccessMode *** `type CommentAccessMode = 'public' | 'private'` | Value | Description | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `'public'` | Matches annotations visible to all users; `visibilityConfig.type === 'public'` wins over the legacy flag, and annotations with no `visibilityConfig` and a `'public'` or unset legacy `iam.accessMode` are treated as Public. | | `'private'` | Matches annotations with `restricted` or `organizationPrivate` visibility; also includes legacy annotations with `iam.accessMode === 'private'` when `visibilityConfig` is unset. | #### CommentSidebarData *** | Property | Type | Required | Description | | ------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | `groupId` | `string` | No | ID of the group. Defaults to 'others' | | `groupName` | `string` | No | Name of the group. Defaults to 'Others' | | `isExpanded` | `boolean` | No | Whether the group is expanded. In V2, an omitted value is resolved from user overrides and the current grouping default. | | `annotations` | `CommentAnnotation[]` | Yes | List of CommentAnnotations in the group | #### Options *** | Property | Type | Required | Description | | ---------- | --------- | -------- | ------------------------------------------- | | `grouping` | `boolean` | No | Whether to group the data. Defaults to true | #### CustomFilterOption *** | Property | Type | Required | Description | | ---------- | --------- | -------- | ----------------------------------------------- | | `id` | `string` | Yes | Unique identifier for the filter option | | `name` | `string` | Yes | Display name for the filter option | | `selected` | `boolean` | Yes | Whether the filter option is currently selected | #### CustomFilters *** | Property | Type | Required | Description | | --------------- | ---------------------- | -------- | ------------------------------------------------- | | `[key: string]` | `CustomFilterOption[]` | No | Custom filter configurations mapped by filter key | #### FilterOption *** | Property | Type | Required | Description | | -------- | -------- | -------- | --------------------------------------- | | `id` | `string` | Yes | Unique identifier for the filter option | | `name` | `string` | Yes | Display name for the filter option | #### CustomFilter *** | Property | Type | Required | Description | | -------- | ------ | -------- | ---------------------------------------- | | `id` | string | Yes | Unique identifier for the custom filter. | | `color` | string | Yes | Color associated with the custom filter. | | `name` | string | Yes | Name or label of the custom filter. | #### CustomPriority *** | Property | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------- | | `id` | string | Yes | Unique identifier for the custom priority. | | `color` | string | Yes | Color associated with the custom priority. | | `name` | string | Yes | Name or label of the custom priority. | | `lightColor` | string | No | Light color variant for the custom priority. | #### CustomStatus *** | Property | Type | Required | Description | | ------------ | ---------- | -------- | --------------------------------------------------------- | | `id` | string | Yes | Unique identifier for the custom status. | | `color` | string | Yes | Color associated with the custom status. | | `name` | string | Yes | Name or label of the custom status. | | `type` | StatusType | Yes | Type of the status (`default`, `ongoing`, or `terminal`). | | `lightColor` | string | No | Light color for the custom status. | | `iconUrl` | string | No | URL to an icon image for the custom status. | #### CustomCategory *** | Property | Type | Required | Description | | -------- | ------ | -------- | ------------------------------------------ | | `id` | string | Yes | Unique identifier for the custom category. | | `color` | string | Yes | Color associated with the custom category. | | `name` | string | Yes | Name or label of the custom category. | ### ConfirmDialogComponentConfig *** Passed to `componentConfig` on the confirm dialog wireframe. Provides context about which delete flow opened the dialog. ```typescript theme={null} export class ConfirmDialogComponentConfig { closeDialog?: Function = () => {}; darkMode?: boolean = false; variant?: string = ''; type?: string = ''; } ``` | Property | Type | Required | Description | | ------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `closeDialog` | `Function` | No | Callback to close the dialog programmatically. Defaults to a no-op. | | `darkMode` | `boolean` | No | Whether dark mode is active. Defaults to `false`. | | `variant` | `string` | No | Visual variant string passed by the SDK. Defaults to `''`. | | `type` | `string` | No | Flow context for the dialog. SDK passes `'comment'` (delete-comment) or `'reply'` (delete-reply). Any non-empty string value produces a `velt-confirm-dialog--{type}` CSS modifier class on the dialog root. Defaults to `''`. | ### Component Props #### VeltCommentsProps *** | Property | Type | Required | Description | | ------------------------ | ------------------------------- | -------- | ----------------------------------------------------------------------------------------------- | | `assignToType` | [`AssignToType`](#assigntotype) | No | Assignment UI mode: `'dropdown'` (default) or `'checkbox'` | | `editPlaceholder` | `string` | No | Fallback placeholder text shown in the edit composer for any comment or reply | | `editCommentPlaceholder` | `string` | No | Placeholder when editing the first comment in a thread. Takes precedence over `editPlaceholder` | | `editReplyPlaceholder` | `string` | No | Placeholder when editing a reply (index > 0). Takes precedence over `editPlaceholder` | **Edit placeholder priority order**: `editCommentPlaceholder` / `editReplyPlaceholder` (selected by comment index) → `editPlaceholder` → existing `placeholder` prop → SDK defaults. Props set on the root container propagate to all dialogs automatically. #### VeltCommentDialogProps *** Props accepted by the `VeltCommentDialog` component. The React TypeScript interface exposes the full attribute set of the underlying `` HTML element. | Property | Type | Required | Description | | --------------------------- | ---------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- | | `annotationId` | `string` | No | ID of the comment annotation to render | | `multiThreadAnnotationId` | `string` | No | ID of the multi-thread annotation to render | | `darkMode` | `boolean` | No | Enables dark mode styling | | `readOnly` | `boolean` | No | Disables user interaction | | `sidebarMode` | `boolean` | No | Renders the dialog in sidebar-mode layout | | `isFocusedThreadEnabled` | `boolean` | No | Enables the focused-thread view | | `openAnnotationInFocusMode` | `boolean` | No | Opens the annotation in focus mode | | `expandOnSelection` | `boolean` | No | Expands the dialog when the annotation is selected | | `inlineCommentMode` | `boolean` | No | Renders the dialog in inline comment mode | | `inboxMode` | `boolean` | No | Renders the dialog in inbox mode | | `isInsidePdfViewer` | `boolean` | No | Indicates the dialog is rendered inside a PDF viewer | | `multiThread` | `boolean` | No | Enables multi-thread behavior | | `commentComposerMode` | `boolean` | No | Renders the dialog as a composer only | | `dialogSelection` | `boolean` | No | Marks the dialog as selected | | `dialogMode` | `boolean` | No | Renders the component in dialog mode | | `focusedThreadMode` | `boolean` | No | Renders the dialog in focused-thread mode | | `pageModeComposer` | `boolean` | No | Renders the dialog as a page-mode composer | | `messageTruncation` | `boolean` | No | Truncates long comment messages | | `initialEditCommentIndex` | `number \| string \| null` | No | Index of the comment to open in edit mode initially | | `messageTruncationLines` | `number \| string` | No | Number of lines to show before truncating a message | | `variant` | `string` | No | Visual variant for the component | | `composerPosition` | `string` | No | Position of the composer within the dialog | | `sortBy` | `string` | No | Field to sort comments by | | `sortOrder` | `string` | No | Sort order for comments | | `commentPinType` | `'bubble' \| 'pin' \| 'chart' \| 'text'` | No | Type of comment pin associated with the dialog | | `containerComponentId` | `string` | No | ID of the container component the dialog belongs to | | `targetElementId` | `string` | No | ID of the target element the dialog is bound to | | `targetComposerElementId` | `string` | No | Unique identifier for programmatic submission via `submitComment()` | | `locationVersion` | `string` | No | Location version for the dialog | | `locationDisplayName` | `string` | No | Display name of the location | | `context` | `any` | No | Custom context data for the dialog | | `commentPlaceholder` | `string` | No | Placeholder text for the comment composer | | `replyPlaceholder` | `string` | No | Placeholder text for the reply composer | | `editPlaceholder` | `string` | No | Fallback placeholder text shown in the edit composer for any comment or reply | | `editCommentPlaceholder` | `string` | No | Placeholder when editing the first comment in a thread. Takes precedence over `editPlaceholder` | | `editReplyPlaceholder` | `string` | No | Placeholder when editing a reply (index > 0). Takes precedence over `editPlaceholder` | **Edit placeholder priority order**: `editCommentPlaceholder` / `editReplyPlaceholder` (selected by comment index) → `editPlaceholder` → existing `placeholder` prop → SDK defaults. #### VeltCommentToolProps *** | Property | Type | Required | Description | | --------------------------- | --------- | -------- | -------------------------------------------- | | `contextInPageModeComposer` | `boolean` | No | Enable passing context to page mode composer | | `context` | `any` | No | Context data to pass when sidebar opens | #### VeltCommentComposerProps *** | Property | Type | Required | Description | | ------------------------- | --------- | -------- | ----------------------------------------------------------------- | | `context` | `any` | No | Custom context data for the comment composer | | `locationId` | `string` | No | Location identifier for the comment | | `documentId` | `string` | No | Document identifier for the comment | | `folderId` | `string` | No | Folder identifier for the comment | | `placeholder` | `string` | No | Custom placeholder text for composer input | | `targetComposerElementId` | `string` | No | Unique identifier for programmatic submission via submitComment() | | `readOnly` | `boolean` | No | Enable read-only mode for composer | #### VeltCommentsSidebarProps *** | Property | Type | Required | Description | | --------------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------- | | `openAnnotationInFocusMode` | `boolean` | No | Opens annotation in focus mode when enabled. Requires `focusedThreadMode` to be enabled | | `commentPlaceholder` | `string` | No | Custom placeholder text for comment input field | | `replyPlaceholder` | `string` | No | Custom placeholder text for reply input field | | `pageModePlaceholder` | `string` | No | Custom placeholder text for page mode input | | `editPlaceholder` | `string` | No | Fallback placeholder text shown in the edit composer for any comment or reply | | `editCommentPlaceholder` | `string` | No | Placeholder when editing the first comment in a thread. Takes precedence over `editPlaceholder` | | `editReplyPlaceholder` | `string` | No | Placeholder when editing a reply (index > 0). Takes precedence over `editPlaceholder` | | `version` | `string` | No | When set to `"2"`, renders the V2 sidebar implementation | #### VeltCommentsSidebarV2Props *** | Property | Type | Required | Description | | ------------------------------ | ---------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pageMode` | `boolean` | No | Enable page-mode composer | | `focusedThreadMode` | `boolean` | No | Enable focused-thread view on comment click | | `readOnly` | `boolean` | No | Enable read-only mode | | `embedMode` | `string \| null` | No | Embeds the sidebar inline within a container | | `floatingMode` | `boolean` | No | Renders the sidebar as a floating overlay | | `position` | `'right' \| 'left'` | No | Sidebar position. Narrowed from `string` to `'right' \| 'left'`. | | `variant` | `string` | No | Sidebar variant, e.g., `'sidebar'`, `'inline'` | | `forceClose` | `boolean` | No | Force-close the sidebar. Default `true`. | | `version` | `string` | No | When `"2"`, routes `VeltCommentsSidebar` to the V2 implementation | | `fullScreen` | `boolean` | No | Adds a fullscreen toggle button to the header. Default `false`. | | `fullExpanded` | `boolean` | No | Render the sidebar fully expanded. Default `false`. | | `shadowDom` | `boolean` | No | Render the sidebar body inside a shadow root for style isolation. Input default `false`; effective default on (V1 parity) unless disabled via `shadow-dom="false"` / `disableSidebarShadowDOM()`. | | `filters` | `string \| FilterField[] \| CommentSidebarFilters` | No | Main Filter panel fields or active selected values. Included selection keys replace their values; omitted keys are preserved. Default `[]`. | | `miniFilters` | `string \| FilterField[]` | No | Single header funnel dropdown (one section per field). Default `[]`. | | `minimalFilters` | `string \| SidebarMinimalFilterConfig[]` | No | Multiple configurable header dropdowns (`filter`/`sort`/`quick`/`actions`). Default `[]`. | | `filterOperator` | `'and' \| 'or'` | No | How selections across different fields combine. Default `'and'`. | | `filterPanelLayout` | `'bottomSheet' \| 'menu'` | No | Main Filter panel layout. Default `'bottomSheet'`. | | `filterOptionLayout` | `'dropdown' \| 'checkbox'` | No | Option control rendering. Default `'dropdown'`. | | `filterCount` | `boolean` | No | Show absolute per-option facet counts in filter dropdowns. Counts stay stable as users apply search text, quick filters, or other category selections. Default `true`. | | `filterGhostCommentsInSidebar` | `boolean` | No | Include ghost comments in the list. Default `false`. | | `systemFiltersOperator` | [`CommentSidebarSystemFiltersOperator`](#commentsidebarsystemfiltersoperator) | No | Operator applied across different filter fields. Values within one field use OR. Effective default `'and'`. | | `sortBy` | [`SortBy`](#sortby) | No | Default sort field (sets the default sort, not a UI dropdown). Unset by default. | | `sortOrder` | [`SortOrder`](#sortorder) | No | Default sort order. Unset by default. | | `defaultMinimalFilter` | `'all' \| 'read' \| 'unread' \| 'resolved' \| 'open' \| 'assignedToMe' \| 'reset'` | No | Default active quick filter. Unset by default. | | `customActions` | `boolean` | No | Enable custom actions. Default `false`. | | `excludeLocationIds` | `string[]` | No | Location ids to exclude from the list. Default `[]`. | | `sidebarButtonCountType` | `'default' \| 'filter'` | No | `'filter'` makes the comment-sidebar button badge track the live filtered count instead of the total. Unset by default. | | `groupConfig` | `{ enable?: boolean; name?: string; groupBy?: string }` | No | Grouping config; defaults to grouping by location when enabled. Unset by default. | | `currentLocationSuffix` | `boolean` | No | Append a current-location suffix. Default `false`. | | `dialogVariant` | `string` | No | Variant for the embedded comment dialog. Default `'sidebar'`. | | `focusedThreadDialogVariant` | `string` | No | Variant for the focused-thread dialog. Default `'sidebar'`. | | `pageModeComposerVariant` | `string` | No | Variant for the page-mode composer. Default `'sidebar'`. | | `dialogSelection` | `boolean` | No | Allow selecting a dialog from the list. Default `true`. | | `expandOnSelection` | `boolean` | No | Expand the dialog on selection. Default `true`. | | `openAnnotationInFocusMode` | `boolean` | No | Open annotations in focus mode. Default `false`. | | `searchPlaceholder` | `string` | No | Placeholder text for the search box. Default `'Search comments'`. | | `pageModePlaceholder` | `string` | No | Placeholder for the page-mode composer. Default `''`. | | `commentPlaceholder` | `string` | No | Placeholder for the comment composer. Default `''`. | | `replyPlaceholder` | `string` | No | Placeholder for the reply composer. Default `''`. | | `editPlaceholder` | `string` | No | Fallback placeholder shown in the edit composer. Default `''`. | | `editCommentPlaceholder` | `string` | No | Placeholder when editing the first comment. Default `''`. | | `editReplyPlaceholder` | `string` | No | Placeholder when editing a reply. Default `''`. | | `context` | `object` | No | Context data (JSON) passed to the sidebar. Default `null`. | | `measuredSize` | `number` | No | Estimated row size (px) used by virtual scrolling. Default `220`. | | `minBufferPx` | `number` | No | Minimum virtual-scroll buffer in px. Default `1000`. | | `maxBufferPx` | `number` | No | Maximum virtual-scroll buffer in px. Default `2000`. | | `urlNavigation` | `boolean` | No | Enable URL-based navigation to comments. Default `false`. | | `queryParamsComments` | `boolean` | No | Sync the selected comment to URL query params. Default `false`. | | `onFullscreenClick` | `(data: any) => void` | No | Fires when the fullscreen toggle button is clicked. | #### VeltInlineCommentsSectionProps *** | Property | Type | Required | Description | | ------------------------ | --------- | -------- | ----------------------------------------------------------------------------------------------- | | `commentPlaceholder` | `string` | No | Custom placeholder text for comment input field | | `replyPlaceholder` | `string` | No | Custom placeholder text for reply input field | | `composerPlaceholder` | `string` | No | Custom placeholder text for composer input field | | `editPlaceholder` | `string` | No | Fallback placeholder text shown in the edit composer for any comment or reply | | `editCommentPlaceholder` | `string` | No | Placeholder when editing the first comment in a thread. Takes precedence over `editPlaceholder` | | `editReplyPlaceholder` | `string` | No | Placeholder when editing a reply (index > 0). Takes precedence over `editPlaceholder` | | `readOnly` | `boolean` | No | Enable read-only mode for inline comments section | # Area #### AreaAnnotation *** | Property | Type | Required | Description | | ------------------- | ------------------------------------------------- | -------- | ------------------------------------------------------------------- | | `annotationId` | `string` | Yes | Unique identifier for the area pin annotation. Auto generated | | `from` | [`User`](#user) | Yes | The user who created this area pin annotation | | `color` | `string` | No | Color used for the area pin annotation | | `lastUpdated` | `any` | No | Timestamp when the area annotation was last updated. Auto generated | | `targetElement` | `TargetElement \| null` | No | The original target element reference | | `targetElements` | `(TargetElement \| null)[]` | No | Target elements of attached annotation | | `position` | `CursorPosition \| null` | No | Cursor position relative to the area annotation | | `locationId` | `number \| null` | No | Unique location id generated from provided location | | `location` | `Location \| null` | No | Set location to identify user on sub document | | `type` | `string` | No | Type of the annotation. Defaults to `'area'` | | `props` | `AnnotationProperty` | Yes | Annotation properties | | `annotationIndex` | `number` | No | Index of current annotation in the list. Starts from 1 | | `pageInfo` | [`PageInfo`](#pageinfo) | No | Page information related to the area annotation | | `areaProperties` | [`AreaProperty`](#areaproperty) | No | Geometry data for the area | | `targetAnnotations` | [`AreaTargetAnnotation[]`](#areatargetannotation) | Yes | Linked annotations (e.g. comments) attached to this area | | `metadata` | [`AreaMetadata`](#areametadata) | No | Custom metadata for the area annotation | #### AreaStatus *** ```typescript theme={null} type AreaStatus = 'added' | 'updated' | 'deleted'; ``` | String value | Description | | ------------ | ------------------------------- | | `'added'` | An area annotation was added. | | `'updated'` | An area annotation was updated. | | `'deleted'` | An area annotation was deleted. | #### AreaProperty *** | Property | Type | Required | Description | | --------------- | -------- | -------- | ------------------------- | | `targetElement` | `string` | No | Target element selector | | `handle1` | `any` | No | First resize handle data | | `handle2` | `any` | No | Second resize handle data | | `coordinates` | `any` | No | Area coordinates data | #### AreaTargetAnnotation *** | Property | Type | Required | Description | | -------------- | -------- | -------- | ------------------------------------------------------ | | `type` | `string` | No | Type of the annotation (e.g. comment, tag) | | `annotationId` | `string` | No | Unique identifier for the annotation | | `position` | `string` | No | Position reference to show this annotation on the area | #### AreaMetadata *** Extends [`BaseMetadata`](#basemetadata). | Property | Type | Required | Description | | --------------- | ----- | -------- | ---------------------------- | | `[key: string]` | `any` | No | Additional custom properties | # Arrows #### ArrowAnnotation *** | Property | Type | Required | Description | | ----------------- | ------------------------------------------- | -------- | -------------------------------------------------------------------- | | `annotationId` | `string` | Yes | Unique identifier for the arrow pin annotation. Auto generated | | `from` | [`User`](#user) | Yes | The user who created this arrow pin annotation | | `color` | `string` | No | Color used for the arrow pin annotation | | `lastUpdated` | `any` | No | Timestamp when the arrow annotation was last updated. Auto generated | | `targetElement` | `TargetElement \| null` | No | Target element of attached annotation | | `position` | `CursorPosition \| null` | No | Cursor position relative to the arrow annotation | | `locationId` | `number \| null` | No | Unique location id generated from provided location | | `location` | `Location \| null` | No | Set location to identify user on sub document | | `type` | `string` | No | Type of the annotation. Default: `'arrow'` | | `props` | [`AnnotationProperty`](#annotationproperty) | No | Annotation display properties (viewport, arrow length/angle) | | `annotationIndex` | `number` | No | Index of current annotation in the list. Starts from 1 | | `pageInfo` | [`PageInfo`](#pageinfo) | No | Page information related to the arrow annotation | #### AnnotationProperty *** | Property | Type | Required | Description | | -------------------- | -------- | -------- | -------------------- | | `viewportWidth` | `number` | No | Viewport width | | `viewportHeight` | `number` | No | Viewport height | | `screenWidth` | `number` | No | Screen width | | `screenHeight` | `number` | No | Screen height | | `screenScrollHeight` | `number` | No | Screen scroll height | | `arrowLength` | `number` | No | Length of the arrow | | `arrowAngle` | `number` | No | Angle of the arrow | # Recorder | Enum Name | Event Type | Description | | -------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TRANSCRIPTION_DONE` | `transcriptionDone` | Triggered when a transcription is generated and ready | | `RECORDING_DONE_LOCAL` | `recordingDoneLocal` | Triggered immediately after a recording annotation is saved locally — before cloud upload and transcription begin. Only fires when `sourceFeature === 'recording'`. | | `RECORDING_DONE` | `recordingDone` | Triggered when a recording is completed | | `RECORDING_DELETE` | `deleteRecording` | Triggered when a recording is deleted | | `RECORDING_EDIT_DONE` | `recordingEditDone` | Triggered when a recording is edited and saved | | `RECORDING_SAVE_INITIATED` | `recordingSaveInitiated` | Triggered when a recording saved is initiated | | `ERROR` | `error` | Triggered when an error occurs during recording operations | ### Recorder Data #### RecorderRequestQuery *** | Property | Type | Required | Description | | ------------- | ---------- | -------- | ------------------------------ | | `recorderIds` | `string[]` | Yes | Array of recorder IDs to query | #### DeleteRecordingsRequest *** | Property | Type | Required | Description | | ------------------- | --------------------------- | -------- | ---------------------------------------------------------- | | `recorderId` | `string` | Yes | ID of the recorder | | `from` | `User \| null` | No | The user who created the recorder | | `metadata` | `RecorderMetadata` | No | Metadata for the recording | | `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version | | `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets | | `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the latest version of the recording | #### GetRecordingDataResponse *** | Property | Type | Required | Description | | ------------------- | --------------------------- | -------- | ---------------------------------------------------------- | | `recorderId` | `string` | Yes | ID of the recorder | | `from` | `User \| null` | No | The user who created the recorder | | `metadata` | `RecorderMetadata` | No | Metadata for the recording | | `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version | | `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets | | `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the latest version of the recording | ### DeleteRecordingsResponse *** | Property | Type | Required | Description | | ------------------- | --------------------------- | -------- | ---------------------------------------------------------- | | `recorderId` | `string` | Yes | ID of the recorder | | `from` | `User \| null` | No | The user who created the recorder | | `metadata` | `RecorderMetadata` | No | Metadata for the recording | | `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version | | `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets | | `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the latest version of the recording | ### Recorder Configuration #### RecorderQualityConstraints *** | Property | Type | Required | Description | | -------- | ----------------------------------- | -------- | ------------------------------------------------------------- | | `safari` | `RecorderQualityConstraintsOptions` | No | Constraints specific to the Safari browser. | | `other` | `RecorderQualityConstraintsOptions` | No | Constraints for other browsers (e.g., Chrome, Firefox, Edge). | #### RecorderEncodingOptions *** | Property | Type | Required | Description | | -------- | ---------------------- | -------- | ------------------------------------------------------------------ | | `safari` | `MediaRecorderOptions` | No | Encoding options specific to the Safari browser. | | `other` | `MediaRecorderOptions` | No | Encoding options for other browsers (e.g., Chrome, Firefox, Edge). | #### RecordingDoneLocalEvent *** | Property | Type | Required | Description | | ------------------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `recorderId` | `string` | Yes | ID of the recorder | | `from` | `User \| null` | No | The user who created the recorder | | `metadata` | `RecorderMetadata` | No | Metadata for the recording | | `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets. The URL in `assets[0].url` is a local blob URL at this point — the permanent CDN URL is not yet available. | | `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets | | `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the recording | | `sourceFeature` | `string` | No | The feature that triggered the event. Always `'recording'` for this event. | #### RecordingDoneEvent *** | Property | Type | Required | Description | | ------------------- | --------------------------- | -------- | ------------------------------------------------ | | `recorderId` | `string` | Yes | ID of the recorder | | `from` | `User \| null` | No | The user who created the recorder | | `metadata` | `RecorderMetadata` | No | Metadata for the recording | | `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version | | `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets | | `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the recording | #### RecordingDeleteEvent *** | Property | Type | Required | Description | | ------------------- | --------------------------- | -------- | ------------------------------------------------ | | `recorderId` | `string` | Yes | ID of the recorder | | `from` | `User \| null` | No | The user who created the recorder | | `metadata` | `RecorderMetadata` | No | Metadata for the recording | | `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version | | `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets | | `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the recording | #### RecordingEditDoneEvent *** | Property | Type | Required | Description | | ------------------- | --------------------------- | -------- | ------------------------------------------------ | | `recorderId` | `string` | Yes | ID of the recorder | | `from` | `User \| null` | No | The user who created the recorder | | `metadata` | `RecorderMetadata` | No | Metadata for the recording | | `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version | | `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets | | `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the recording | #### RecordingSaveInitiatedEvent *** | Property | Type | Required | Description | | -------------- | -------------------- | -------- | ---------------------------------------------------------------------------- | | `annotationId` | `string` | No | ID of the annotation. This property is only available when `type` is 'edit'. | | `message` | `string` | Yes | A descriptive message about the save initiation. | | `type` | `'edit' \| 'record'` | Yes | Specifies whether the save was initiated for an 'edit' or a new 'recording'. | #### RecordingStartedEvent *** | Property | Type | Required | Description | | -------- | -------------------------------- | -------- | ----------------------------------- | | `type` | `'audio' \| 'video' \| 'screen'` | Yes | The type of recording that started. | #### RecordingPausedEvent *** | Property | Type | Required | Description | | -------- | -------------------------------- | -------- | -------------------------------------- | | `type` | `'audio' \| 'video' \| 'screen'` | Yes | The type of recording that was paused. | #### RecordingResumedEvent *** | Property | Type | Required | Description | | -------- | -------------------------------- | -------- | --------------------------------------- | | `type` | `'audio' \| 'video' \| 'screen'` | Yes | The type of recording that was resumed. | #### RecordingCancelledEvent *** | Property | Type | Required | Description | | -------- | -------------------------------- | -------- | ----------------------------------------- | | `type` | `'audio' \| 'video' \| 'screen'` | Yes | The type of recording that was cancelled. | #### RecordingStoppedEvent *** | Property | Type | Required | Description | | -------- | -------------------------------- | -------- | --------------------------------------- | | `type` | `'audio' \| 'video' \| 'screen'` | Yes | The type of recording that was stopped. | #### TranscriptionDoneEvent *** | Property | Type | Required | Description | | ------------------- | --------------------------- | -------- | ------------------------------------------------ | | `recorderId` | `string` | Yes | ID of the recorder | | `from` | `User \| null` | No | The user who created the recorder | | `metadata` | `RecorderMetadata` | No | Metadata for the recording | | `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version | | `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets | | `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the recording | #### RecordingErrorEvent *** | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------------------------------------------------------- | | `type` | `string` | Yes | The type of error that occurred. eg: `editFailed`, `recordingFailed`, `transcriptionFailed` | | `message` | `string` | Yes | A descriptive message about the error. | | `recorderId` | `string` | No | ID of the recorder, if the error is specific to one. | #### RecorderConfig *** | Property | Type | Required | Description | | ----------------- | -------------------------------------------------------- | -------- | ------------------------------ | | `type` | `{ audio?: boolean, video?: boolean, screen?: boolean }` | Yes | Types of media to be recorded | | `recorderOptions` | `MediaRecorderOptions` | No | Options for the media recorder | #### RecordedData *** | Property | Type | Required | Description | | -------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------- | | `id` | `string` | Yes | Annotation ID of recorder annotation | | `tag` | `string` | Yes | Recorder player tag containing recorder annotation id which can be added anywhere on the DOM | | `type` | `string` | Yes | Type of recorded data. Possible values are 'audio', 'video', and 'screen' | | `thumbnailUrl` | `string` | No | URL of the thumbnail image for the recorded data | | `thumbnailWithPlayIconUrl` | `string` | No | URL of the thumbnail image with a play icon overlay | | `videoUrl` | `string` | No | URL of the recorded video | | `audioUrl` | `string` | No | URL of the recorded audio | | `videoPlayerUrl` | `string` | No | URL of the hosted website to open video in a new tab | | `getThumbnailTag` | `function` | Yes | A method that returns an HTML string for displaying the thumbnail with a link to the video player | #### RecordedRawData *** | Property | Type | Required | Description | | -------------- | ------------------------------------------------- | -------- | ------------------------------------------- | | `blob` | `Blob` | Yes | Blob object of recorded data | | `url` | `string` | Yes | Base64 URL of recorded data | | `type` | `'audio' \| 'video' \| 'screen'` | Yes | Type of recorded data | | `thumbnail` | `string` | No | Base64 encoded thumbnail of one video frame | | `recordedTime` | `{ duration?: number; display?: string } \| null` | No | Recorded time details | #### RecorderInitData *** | Property | Type | Required | Description | | ------------------ | ------------------------------------------------------------- | -------- | ------------------------------- | | `status` | `Observable` | Yes | Media recorder status | | `stream` | `MediaStream` | No | Media recorder stream | | `recordedTime` | `Observable<{ duration?: number; display?: string } \| null>` | Yes | Recorded time observable | | `type` | `'audio' \| 'video' \| 'screen'` | Yes | Type of media recorder | | `recordedRawData$` | `Observable<`[`RecordedRawData`](#recordedrawdata)` \| null>` | Yes | Observable of recorded raw data | #### RecorderAnnotation *** \| Property | Type | Required | Description | \| ------------------------ | ------------- | -------- | ------------------------------------------------------------------------------------- | --- | \| `annotationId` | String | Yes | Unique identifier for the recorder annotation, automatically generated. | \| `from` | `User` | Yes | The user who created the recorder annotation. | \| `color` | String | No | Color used for the annotation. | \| `lastUpdated` | Any | No | Timestamp of the last update, automatically generated. | | \| `locationId` | Number | No | Unique location ID from provided location. | \| `location` | `Location` | No | Location to identify user on sub document. | \| `type` | String | No | Type of annotation. | \| `recordingType` | String | Yes | Type of recording for the annotation. | \| `mode` | String | Yes | Mode of the recorder annotation, 'floating' or 'thread'. | \| `approved` | Boolean | No | Indicates if the annotation is approved. | \| `attachment` | Attachment | No | Attachment for recorded media. Deprecated. | \| `attachments` | Attachment\[] | Yes | List of attachments for the annotation. | \| `annotationIndex` | Number | No | Index of the annotation in a list. | \| `pageInfo` | PageInfo | No | Information about the page where the annotation is made. | \| `recordedTime` | Object | No | Recorded time details. | \| `transcription` | Transcription | No | Transcription of the recorded media. | \| `isRecorderResolverUsed` | `boolean` | No | True while PII is being fetched from the recorder resolver; use for loading states. | \| `isUrlAvailable` | `boolean` | No | True once the recording URL is available (not a local blob); use for upload progress. | #### RecorderDataTranscriptSegment *** | Property | Type | Required | Description | | -------------------- | ------ | -------- | --------------------------------------- | | `startTime` | String | Yes | Start time of the transcription segment | | `endTime` | String | Yes | End time of the transcription segment | | `startTimeInSeconds` | Number | Yes | Start time of the segment in seconds | | `endTimeInSeconds` | Number | Yes | End time of the segment in seconds | | `text` | String | Yes | Transcribed text content of the segment | #### RecorderDataTranscription *** | Property | Type | Required | Description | | -------------------- | --------------------------------- | -------- | ---------------------------------------- | | `transcriptSegments` | `RecorderDataTranscriptSegment[]` | No | Array of transcription segments | | `vttFileUrl` | String | No | URL to the VTT format transcription file | | `contentSummary` | String | No | Summary of the transcribed content | #### RecorderDataAsset *** | Property | Type | Required | Description | | ----------------- | --------------------------- | -------- | --------------------------------------------------------------- | | `version` | `number` | No | Version of the asset. | | `url` | `string` | Yes | URL to the recorded media | | `mimeType` | `string` | No | MIME type of the recorded media | | `fileName` | `string` | No | Name of the recorded file | | `fileSizeInBytes` | `number` | No | File size in bytes | | `fileFormat` | `RecorderFileFormat` | No | The format/extension of the file. Example: 'mp3', 'mp4', 'webm' | | `thumbnailUrl` | `string` | No | URL to the thumbnail image | | `transcription` | `RecorderDataTranscription` | No | Transcription data for the recording | #### RecorderData *** | Property | Type | Required | Description | | ------------------- | --------------------------- | -------- | ---------------------------------------------------------- | | `recorderId` | `string` | Yes | ID of the recorder | | `from` | `User \| null` | No | The user who created the recorder | | `metadata` | `RecorderMetadata` | No | Metadata for the recording | | `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version | | `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets | | `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the latest version of the recording | #### MediaPreviewConfig *** | Property | Type | Required | Description | | ---------------- | ----------- | -------- | --------------------------------- | | `audio` | Object | No | Configuration for audio preview | | `audio.enabled` | boolean | No | Whether audio preview is enabled | | `audio.deviceId` | string | No | Device ID for audio input | | `video` | Object | No | Configuration for video preview | | `video.enabled` | boolean | No | Whether video preview is enabled | | `video.deviceId` | string | No | Device ID for video input | | `screen` | Object | No | Configuration for screen preview | | `screen.enabled` | boolean | No | Whether screen preview is enabled | | `screen.stream` | MediaStream | No | MediaStream for screen sharing | #### MediaRecorderOptions *** | Property | Type | Required | Description | | -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------- | | `audioBitsPerSecond` | `number` | No | Controls the audio encoding quality by setting the number of bits used per second for audio. | | `videoBitsPerSecond` | `number` | No | Controls the video encoding quality by setting the number of bits used per second for video. | #### RecorderQualityConstraintsOptions *** | Property | Type | Required | Description | | -------- | ----------------------- | -------- | ---------------------------------------------- | | `video` | `MediaTrackConstraints` | No | Specifies the constraints for the video track. | | `audio` | `MediaTrackConstraints` | No | Specifies the constraints for the audio track. | #### MediaTrackConstraints *** | Property | Type | Required | Description | | ------------------ | ------------------ | -------- | ---------------------------------------------------------------- | | `aspectRatio` | `ConstrainDouble` | No | Controls the width-to-height ratio of the captured video stream. | | `frameRate` | `ConstrainDouble` | No | Determines the number of frames per second for the video stream. | | `height` | `ConstrainULong` | No | Sets the vertical resolution (in pixels) of the video stream. | | `width` | `ConstrainULong` | No | Sets the horizontal resolution (in pixels) of the video stream. | | `autoGainControl` | `ConstrainBoolean` | No | Enables/disables automatic volume adjustment for audio input. | | `echoCancellation` | `ConstrainBoolean` | No | Enables/disables the removal of audio echo effects. | | `noiseSuppression` | `ConstrainBoolean` | No | Enables/disables the filtering of background noise from audio. | | `sampleRate` | `ConstrainULong` | No | Controls the number of audio samples taken per second. | #### ConstrainDouble *** | Property | Type | Required | Description | | -------- | -------- | -------- | -------------------------------------------------------------------- | | `min` | `number` | No | The minimum acceptable value. | | `max` | `number` | No | The maximum acceptable value. | | `ideal` | `number` | No | The preferred value that the browser will try to match if possible. | | `exact` | `number` | No | A mandatory value that must be matched exactly or the request fails. | #### ConstrainULong *** | Property | Type | Required | Description | | -------- | -------- | -------- | -------------------------------------------------------------------- | | `min` | `number` | No | The minimum acceptable value. | | `max` | `number` | No | The maximum acceptable value. | | `ideal` | `number` | No | The preferred value that the browser will try to match if possible. | | `exact` | `number` | No | A mandatory value that must be matched exactly or the request fails. | #### ConstrainBoolean *** | Property | Type | Required | Description | | -------- | --------- | -------- | -------------------------------------------------------------------- | | `ideal` | `boolean` | No | The preferred value that the browser will try to match if possible. | | `exact` | `boolean` | No | A mandatory value that must be matched exactly or the request fails. | #### RecorderDevicePermissionOptions *** | Property | Type | Required | Description | | -------- | ------- | -------- | ------------------------------------------------------ | | `audio` | boolean | No | Whether to request permission for audio input devices. | | `video` | boolean | No | Whether to request permission for video input devices. | ### RecorderElement Interface #### RecorderElement *** Interface representing the Recorder element object that provides methods for controlling recording behavior, Picture-in-Picture mode, and permissions. | Method | Parameters | Returns | Description | | ------------------------- | --------------- | --------------- | ------------------------------------------------------------- | | `setMaxLength` | `value: number` | `void` | Sets the maximum recording duration in seconds | | `enablePictureInPicture` | None | `void` | Enables Picture-in-Picture mode for recordings | | `disablePictureInPicture` | None | `void` | Disables Picture-in-Picture mode for recordings | | `openPictureInPicture` | None | `void` | Opens the Picture-in-Picture window for the current recording | | `exitPictureInPicture` | None | `void` | Exits the Picture-in-Picture window | | `requestScreenPermission` | None | `Promise` | Requests screen capture permissions for recording preview | # Notifications #### Notification *** | Property | Type | Required | Description | | ------------------------------------ | ----------------------------------- | -------- | ----------------------------------------------------------------------------- | | `id` | `string` | Yes | Notification ID | | `notificationSource` | `string` | Yes | Notification source. e.g., 'comment', 'custom', etc. | | `actionType` | `string` | No | Action that triggered the notification. e.g., 'added' | | `isUnread` | `boolean` | No | Whether the notification is unread for the user | | `actionUser` | `User` | No | The user who triggered the action | | `timestamp` | `number` | No | Timestamp of the notification | | `displayHeadlineMessage` | `string` | No | The headline message of the notification | | `displayBodyMessage` | `string` | No | The body message of the notification | | `displayHeadlineMessageTemplate` | `string` | No | The template of the headline message | | `displayHeadlineMessageTemplateData` | `object` | No | The data used to fill the headline message template | | `forYou` | `boolean` | No | Whether the notification is for the current logged-in user | | `targetAnnotationId` | `string` | No | ID of the annotation that triggered the notification | | `notificationSourceData` | `any` | No | The data of the notification source. e.g., `CommentAnnotation` | | `metadata` | `NotificationMetadata` | No | Metadata for the current notification. e.g., `documentId` | | `notifyUsers` | `{ [emailHash: string]: boolean }` | No | Map of email hashes to boolean values indicating whether to notify the user | | `notifyUsersByUserId` | `{ [userIdHash: string]: boolean }` | No | Map of user ID hashes to boolean values indicating whether to notify the user | | `isNotificationResolverUsed` | `boolean` | No | `true` when the notification was enriched via the notification resolver | #### NotificationMetadata *** | Property | Type | Required | Description | | ---------------------- | ---------- | -------- | -------------------------------------------------- | | `apiKey` | `string` | No | Your API key | | `clientOrganizationId` | `string` | No | The organization ID that you set | | `organizationId` | `string` | No | The organization ID generated by us | | `clientDocumentId` | `string` | No | The document ID that you set | | `documentId` | `string` | No | The document ID generated by us | | `locationId` | `number` | No | The unique location ID | | `location` | `Location` | No | The location object | | `documentMetadata` | `Object` | No | Contains the complete document metadata object | | `organizationMetadata` | `Object` | No | Contains the complete organization metadata object | #### SettingsUpdatedEvent *** | Property | Type | Required | Description | | ------------ | ---------------------------- | -------- | ------------------------------------------------ | | `settings` | `NotificationSettingsConfig` | Yes | The updated notification settings configuration. | | `isMutedAll` | `boolean` | Yes | Whether all notifications are muted. | | Enum Name | Event Type | Description | | ------------------ | ----------------- | ---------------------------------------------------- | | `SETTINGS_UPDATED` | `settingsUpdated` | Triggered when the notification settings are updated | #### NotificationSettingsConfig *** Sets what notifications the user will receive on the provided channel. | Property | Type | Required | Description | | --------------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `[key: string]` | `NotificationSettingsItemType` | No | Dynamic key-value pairs for notification settings configuration. The key represents the channel ID and the value represents the one of the NotificationSettingsItemType. | #### NotificationSettingsItemType *** Decides what notifications the user will receive on the current channel. Type: `'ALL' | 'MINE' | 'NONE' | string` **Description:** * `ALL`: Subscribes the user to all notifications whether or not the user is involved in the notification on the current document. * `MINE`: Subscribes the user to notifications that are related to the current user on the current document. * `NONE`: Subscribes the user to no notifications on this channel on the current document. #### NotificationInitialSettingsConfig *** | Property | Type | Required | Description | | --------- | --------------------------- | -------- | ------------------------------------------------------ | | `name` | `string` | No | Display name for the notification channel. | | `id` | `string` | Yes | Unique channel ID for the notification channel. | | `default` | `string` | No | Default value for the notification channel. | | `enable` | `boolean` | No | Whether the notification channel is enabled. | | `values` | `NotificationConfigValue[]` | No | Array of possible values for the notification channel. | #### NotificationConfigValue *** | Property | Type | Required | Description | | -------- | ------------------------------ | -------- | ----------------------------------------- | | `id` | `NotificationSettingsItemType` | Yes | Unique id for the configuration value. | | `name` | `string` | No | Display name for the configuration value. | #### NotificationTabConfig *** | Property | Type | Required | Description | | ----------- | --------- | -------- | ----------------------- | | `forYou` | `boolean` | No | Show the For-you tab. | | `people` | `boolean` | No | Show the People tab. | | `documents` | `boolean` | No | Show the Documents tab. | | `all` | `boolean` | No | Show the All tab. | #### GetNotificationsDataQuery *** | Property | Type | Required | Description | | -------- | ---------------------------------- | -------- | --------------------------------------------------------- | | `type` | `'all' \| 'forYou' \| 'documents'` | No | Filter for notification type: all, for you, or documents. | #### CrossOrganizationConfig *** Configuration for cross-organization "For You" notifications. Merges For You notifications from other organizations the user belongs to. Used with [`enableCrossOrganization()`](/async-collaboration/notifications/customize-behavior#enablecrossorganization). | Property | Type | Required | Description | | ------------------------ | ----------------------- | -------- | -------------------------------------------------------------------------------- | | `enabled` | `boolean` | No | Enable or disable cross-org notifications. Defaults to `true` when opted in. | | `organizationIds` | `string[]` | No | Allowlist of org IDs to include. When omitted, all indexed orgs are eligible. | | `excludeOrganizationIds` | `string[]` | No | Org IDs to exclude. The current org is always excluded regardless of this field. | | `feeds` | `('forYou' \| 'all')[]` | No | Feed targets. Only `'forYou'` is supported; `'all'` is ignored with a warning. | #### FirestorePaths *** Self-hosting configuration that maps Velt collections to custom Firestore paths. Only the field relevant to cross-organization notifications is shown below; additional path fields exist for other self-hosted collections. | Property | Type | Required | Description | | ----------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userNotificationIndex` | `string` | No | Path to the global, per-user notification index collection (org-independent). Required for cross-organization "For You" notifications. See [Cross-Organization Notifications](/self-host-data/notifications#cross-organization-notifications). | #### NotificationSettingsLayout *** Layout mode for notification settings UI. Type: `'accordion' | 'dropdown'` **Description:** * `accordion`: Settings displayed in expandable accordion (default) * `dropdown`: Settings displayed in dropdown menu #### NotificationServiceConfig *** Top-level org-scoped config for notification delay and batching. Set in the Velt Console under workspace notification settings. | Property | Type | Required | Description | | ------------- | ----------------------------- | -------- | -------------------------------------------------------- | | `delayConfig` | [`DelayConfig`](#delayconfig) | No | Controls whether notifications are held before delivery. | | `batchConfig` | [`BatchConfig`](#batchconfig) | No | Controls grouping of notifications into batched digests. | #### DelayConfig *** Controls the hold period applied to notifications before they are evaluated for batching or delivery. | Property | Type | Required | Default | Description | | -------------- | --------- | -------- | ------- | ------------------------------------------------------------------ | | `isEnabled` | `boolean` | No | `false` | Enables the delay pipeline for this organization. | | `delaySeconds` | `number` | No | — | Seconds to hold a notification before proceeding to batch or send. | #### BatchConfig *** Configures batching windows per grouping scope. Each scope is independently configured via [`BatchWindowConfig`](#batchwindowconfig). | Property | Type | Required | Description | | ---------- | ----------------------------------------- | -------- | ------------------------------------------------------ | | `document` | [`BatchWindowConfig`](#batchwindowconfig) | No | Batching window applied per document. | | `user` | [`BatchWindowConfig`](#batchwindowconfig) | No | Batching window applied per user across all documents. | #### BatchWindowConfig *** Defines the time window and activity cap for a single batching scope. | Property | Type | Required | Description | | -------------------- | --------- | -------- | ------------------------------------------------------------------------------ | | `isEnabled` | `boolean` | No | Enables batching for this scope. | | `batchWindowSeconds` | `number` | No | Duration in seconds to collect activities before flushing the batch. | | `maxActivities` | `number` | No | Maximum activities per batch; flush triggers early when this count is reached. | ### Notification Primitives Types for the primitive components used to build custom notification interfaces. See [Notifications Primitives](/ui-customization/features/async/notifications/notifications-panel/primitives) for usage examples and [`Primitives catalog`](/ui-customization/reference/primitives) for the complete component list. #### NotificationsPrimitiveCommonProps ## [Usage Examples →](/ui-customization/features/async/notifications/notifications-panel/primitives#common-inputs) Base props inherited by all Notification primitive components. | Property | Type | Required | Description | | -------------------- | --------- | -------- | ------------------------------------------------------------ | | `variant` | `string` | No | Visual variant of the primitive component | | `darkMode` | `boolean` | No | Renders the component in dark mode when true | | `shadowDom` | `boolean` | No | Renders the component inside a Shadow DOM when true | | `parentLocalUIState` | `object` | No | Local UI state passed down from a parent primitive component | # Activity Logs #### ActivityFeatureType *** Feature area that generated an activity log record. ```typescript theme={null} type ActivityFeatureType = | "comment" | "reaction" | "recorder" | "crdt" | "custom"; ``` | Value | Description | | ------------ | --------------------------------------------------------- | | `'comment'` | Activity log from the Comments feature | | `'reaction'` | Activity log from the Reactions feature | | `'recorder'` | Activity log from the Recorder feature | | `'crdt'` | Activity log from the CRDT (collaborative editor) feature | | `'custom'` | Activity log created by the host application | #### ActivitySubscribeConfig *** Filter config passed to `getAllActivities()` to scope the activity log feed. | Property | Type | Required | Description | | --------------------- | ----------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- | | `organizationId` | `string` | No | Scope feed to a specific organization ID | | `documentIds` | `string[]` | No | Filter to specific document IDs | | `currentDocumentOnly` | `boolean` | No | When `true`, limits feed to the current document. Auto-switches when `setDocument()` is called | | `maxDays` | `number` | No | Maximum age in days for returned activity logs (default: 30) | | `featureTypes` | [`ActivityFeatureType[]`](#activityfeaturetype) | No | Filter by feature area | | `excludeFeatureTypes` | [`ActivityFeatureType[]`](#activityfeaturetype) | No | Exclude specific feature areas | | `actionTypes` | `string[]` | No | Filter by action type; use the exported action type constants | | `excludeActionTypes` | `string[]` | No | Exclude specific action types | | `userIds` | `string[]` | No | Filter to activity logs by specific user IDs | | `excludeUserIds` | `string[]` | No | Exclude activity logs by specific user IDs | #### ActivityRecord *** Core activity log object returned from the activity log feed. Generic params: `TEntity` (entity data shape), `TTarget` (target entity data shape). | Property | Type | Required | Description | | ---------------------------- | --------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | Yes | Unique activity log ID | | `featureType` | [`ActivityFeatureType`](#activityfeaturetype) | Yes | Feature area that generated this activity log | | `actionType` | `string` | Yes | Specific action that occurred | | `eventType` | `string` | No | Sub-event type within the action | | `actionUser` | [`User`](#user) | Yes | User who performed the action | | `timestamp` | `number` | Yes | Unix timestamp of the activity log | | `metadata` | [`ActivityMetadata`](#activitymetadata) | Yes | Feature-specific extensible metadata | | `targetEntityId` | `string` | No | ID of the entity this activity log targets | | `targetSubEntityId` | `string \| null` | No | ID of a sub-entity within the target | | `changes` | [`ActivityChanges`](#activitychanges) | No | Before/after field changes | | `entityData` | `TEntity` | No | Full entity object at time of action | | `entityTargetData` | `TTarget` | No | Full target entity object at time of action | | `displayMessageTemplate` | `string` | No | Template string with `{{variable}}` placeholders | | `displayMessageTemplateData` | `Record` | No | Data to resolve the display message template | | `displayMessage` | `string` | No | Resolved human-readable display message. Computed client-side — never stored in Firestore | | `actionIcon` | `string` | No | Icon URL or identifier for the action | | `immutable` | `boolean` | No | When `true`, the record cannot be updated or deleted via REST API | | `isActivityResolverUsed` | `boolean` | No | `true` when PII was stripped by the activity data provider. Can be used to show a loading state while resolver re-hydration is pending. | #### ActivityChanges *** Map of field names to their before/after change values. ```typescript theme={null} interface ActivityChanges { [key: string]: ActivityChange | undefined; } ``` #### ActivityChange *** Before/after values for a single changed field. Generic param `T` is the field value type. | Property | Type | Required | Description | | -------- | ----------- | -------- | ----------------------------- | | `from` | `T \| null` | No | Field value before the action | | `to` | `T \| null` | No | Field value after the action | #### ActivityMetadata *** Extensible metadata attached to an activity log record. Extends `BaseMetadata` with open index signature for feature-specific fields. | Property | Type | Required | Description | | ---------------------- | ------------------ | -------- | --------------------------------- | | `apiKey` | `string` | No | Inherited from `BaseMetadata` | | `documentId` | `string` | No | Inherited from `BaseMetadata` | | `organizationId` | `string` | No | Inherited from `BaseMetadata` | | `clientOrganizationId` | `string` | No | Inherited from `BaseMetadata` | | `folderId` | `string` | No | Inherited from `BaseMetadata` | | `veltFolderId` | `string` | No | Inherited from `BaseMetadata` | | `documentMetadata` | `DocumentMetadata` | No | Inherited from `BaseMetadata` | | `sdkVersion` | `string \| null` | No | Inherited from `BaseMetadata` | | `[key: string]` | `any` | No | Feature-specific extension fields | #### CreateActivityData *** Payload for `createActivity()`. Use `featureType: 'custom'` and `actionType: 'custom'` for non-Velt events. Generic params: `TEntity` (entity data shape), `TTarget` (target entity data shape). | Property | Type | Required | Description | | ---------------------------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | | `id` | `string` | No | Optional Firestore document ID for idempotent writes | | `featureType` | [`ActivityFeatureType`](#activityfeaturetype) | Yes | Feature type; use `'custom'` for non-Velt events | | `actionType` | `string` | Yes | Action identifier; use `'custom'` for non-Velt events | | `eventType` | `string` | No | Sub-event type within the action | | `targetEntityId` | `string` | No | Required only when `featureType` is `'custom'`. Optional for `comment`, `reaction`, `recorder`, `crdt`. | | `targetSubEntityId` | `string \| null` | No | ID of a sub-entity within the target | | `changes` | [`ActivityChanges`](#activitychanges) | No | Before/after field changes to record | | `entityData` | `TEntity` | No | Full entity object at time of action | | `entityTargetData` | `TTarget` | No | Full target entity object at time of action | | `actionIcon` | `string` | No | Icon URL or identifier — typically for custom activities | | `displayMessageTemplate` | `string` | No | Template string with `{{variable}}` placeholders — only for custom activities | | `displayMessageTemplateData` | `Record` | No | Template variable values — only for custom activities | #### ActivityDateGroup *** A date-bucketed group used by the Activity Log wireframe for display purposes. | Property | Type | Required | Description | | -------------- | ------------------------------------- | -------- | ------------------------------------------------- | | `dateKey` | `string` | Yes | ISO date key (e.g. `'2026-03-11'`) | | `displayLabel` | `string` | Yes | Human-readable label (e.g. `'TODAY'`, `'24 FEB'`) | | `activities` | [`ActivityRecord[]`](#activityrecord) | Yes | Items in this group, sorted descending | | `totalCount` | `number` | Yes | Pre-truncation count | #### ActivityScrollItem *** A discriminated union used internally by the Activity Log virtual-scroll list. Each item's `type` field determines the wireframe slot it renders into. | `type` | Other fields | Description | | --------------- | ---------------------------------------------------------- | -------------------------------------- | | `'date-header'` | `dateGroup: ActivityDateGroup` | Renders a date-group header row | | `'activity'` | `activity: ActivityRecord`, `dateGroup: ActivityDateGroup` | Renders a single activity row | | `'show-more'` | `dateGroup: ActivityDateGroup` | Renders the "Show more" expand control | #### ActivityFilterOption *** A filter option in the Activity Log dropdown. Not to be confused with the comment sidebar [`FilterOption`](#filteroption). | Property | Type | Required | Description | | -------- | -------------------------------------------------------- | -------- | ---------------------------------------------------------- | | `label` | `string` | Yes | Human-readable label (e.g. `'All Activity'`, `'Comments'`) | | `value` | `'all'` \| [`ActivityFeatureType`](#activityfeaturetype) | Yes | Filter value used by `activeFilter` | | `icon` | `string \| undefined` | No | Optional icon hint | ### Activity Log Action Type Constants Pre-defined `actionType` string constants for each feature's activity log records. Import these to build type-safe `actionTypes` filters in [`ActivitySubscribeConfig`](#activitysubscribeconfig). #### CommentActivityActionTypes *** Action type constants for Comment feature activity logs. Union type: `CommentActivityActionType`. | Constant | Value | Description | | -------------------- | ----------------------------------------- | ------------------------------------------- | | `ANNOTATION_ADD` | `'comment_annotation.add'` | A comment annotation was added | | `ANNOTATION_DELETE` | `'comment_annotation.delete'` | A comment annotation was deleted | | `COMMENT_ADD` | `'comment.add'` | A comment was added | | `COMMENT_UPDATE` | `'comment.update'` | A comment was updated | | `COMMENT_DELETE` | `'comment.delete'` | A comment was deleted | | `STATUS_CHANGE` | `'comment_annotation.status_change'` | Comment annotation status changed | | `PRIORITY_CHANGE` | `'comment_annotation.priority_change'` | Comment annotation priority changed | | `ASSIGN` | `'comment_annotation.assign'` | Comment annotation was assigned | | `ACCESS_MODE_CHANGE` | `'comment_annotation.access_mode_change'` | Comment annotation access mode changed | | `CUSTOM_LIST_CHANGE` | `'comment_annotation.custom_list_change'` | Comment annotation custom list changed | | `APPROVE` | `'comment_annotation.approve'` | Comment annotation was approved | | `ACCEPT` | `'comment.accept'` | A comment was accepted | | `REJECT` | `'comment.reject'` | A comment was rejected | | `REACTION_ADD` | `'comment.reaction_add'` | A reaction was added to a comment | | `REACTION_DELETE` | `'comment.reaction_delete'` | A reaction was removed from a comment | | `SUBSCRIBE` | `'comment_annotation.subscribe'` | User subscribed to a comment annotation | | `UNSUBSCRIBE` | `'comment_annotation.unsubscribe'` | User unsubscribed from a comment annotation | #### RecorderActivityActionTypes *** Action type constants for Recorder feature activity logs. Union type: `RecorderActivityActionType`. | Constant | Value | Description | | ------------------ | -------------------- | ----------------------- | | `RECORDING_ADD` | `'recording.add'` | A recording was added | | `RECORDING_DELETE` | `'recording.delete'` | A recording was deleted | #### ReactionActivityActionTypes *** Action type constants for Reaction feature activity logs. Union type: `ReactionActivityActionType`. | Constant | Value | Description | | ----------------- | ------------------- | ---------------------- | | `REACTION_ADD` | `'reaction.add'` | A reaction was added | | `REACTION_DELETE` | `'reaction.delete'` | A reaction was deleted | #### CrdtActivityActionTypes *** Action type constants for CRDT feature activity logs. Union type: `CrdtActivityActionType`. | Constant | Value | Description | | ------------- | -------------------- | --------------------------- | | `EDITOR_EDIT` | `'crdt.editor_edit'` | A CRDT editor edit occurred | # Single Editor Mode #### AccessRequestEvent *** This event object is related to requests for editor access. It is emitted for `accessRequested`, `accessRequestCanceled`, `accessAccepted`, and `accessRejected` events. | Property | Type | Required | Description | | ------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------ | | `viewer` | `User` | No | The user who is the current viewer and is involved in the access request. | | `editor` | `User` | No | The user who is the current editor at the time of the event. | | `timestamp` | `number` | No | UNIX timestamp (in milliseconds) of when the event occurred. | | `status` | `string` | No | The status of the access request (e.g., "requested", "canceled", "accepted", "rejected" ). | | `totalUsers` | `number` | No | Total number of users currently present on the document. | | `presenceSnippylyUserIds` | `string[]` | No | Velt internal user IDs of currently present users. | | `presenceClientUserIds` | `string[]` | No | Client-provided user IDs of currently present users. | #### SEMEvent *** This event object is related to editor/viewer assignments and editor status changes. It is emitted for `editorAssigned`, `viewerAssigned`, and `editorOnDifferentTabDetected` events. | Property | Type | Required | Description | | ------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------- | | `viewer` | `User` | No | The user who is the current viewer at the time of the event. | | `editor` | `User` | No | The user who is the current editor at the time of the event. | | `timestamp` | `number` | No | UNIX timestamp (in milliseconds) of when the event occurred. | | `role` | `string` | No | The role relevant to the event, typically "editor" or "viewer" for assignment events. | | `totalUsers` | `number` | No | Total number of users currently present on the document. | | `presenceSnippylyUserIds` | `string[]` | No | Velt internal user IDs of currently present users. | | `presenceClientUserIds` | `string[]` | No | Client-provided user IDs of currently present users. | #### SingleEditorLiveStateData *** | Property | Type | Required | Description | | --------------------- | ---------------- | -------- | ----------------------------------------- | | `editor` | `User \| null` | No | The user who is currently editing, if any | | `requestEditorAccess` | `Object \| null` | No | Details about a request for editor access | | `tabId` | `string \| null` | No | The identifier of the tab, if applicable | #### RequestEditorAccess *** | Property | Type | Required | Description | | --------------------- | ------------------------------------------------------ | -------- | ------------------------------------------------------- | | `user` | `User` | Yes | The user requesting editor access | | `requestedAt` | `any` | Yes | The timestamp when the access was requested | | `status` | `'pending' \| 'accepted' \| 'rejected' \| 'cancelled'` | Yes | The status of the access request | | `editorAccessTimeout` | `number` | Yes | Timeout duration for the editor access | | `tabId` | `string \| null` | No | The identifier of the tab related to the access request | #### SingleEditorConfig *** | Property | Type | Required | Description | | ----------------- | --------- | -------- | -------------------------------------------------------------------------------------------- | | `customMode` | `boolean` | No | Enables/disables custom mode. In custom mode, input elements are not disabled for the viewer | | `singleTabEditor` | `boolean` | Yes | Enables/disables editor mode on a single tab only | #### UserEditorAccess *** | Property | Type | Required | Description | | ---------------------- | --------- | -------- | ---------------------------------------------------------- | | `isEditor` | `boolean` | No | Indicates whether the user has editor privileges | | `isEditorOnCurrentTab` | `boolean` | No | Indicates whether the user is an editor on the current tab | #### EditorAccessTimer *** | Property | Type | Required | Description | | -------------- | --------------------------------------- | -------- | ---------------------------------------------------------- | | `state` | `'idle' \| 'inProgress' \| 'completed'` | Yes | The state of the Editor Access Request timer | | `durationLeft` | `number` | No | Duration left for the editor access timer to be completed. | # Live State Data #### LiveStateData *** | Property | Type | Required | Description | | ----------------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | | `id` | `string` | Yes | A unique identifier likely used for quick reference and indexing. It's an MD5 hash of `liveStateDataId` | | `liveStateDataId` | `string` | Yes | A unique identifier for the state data being synced | | `data` | `string \| number \| boolean \| JSON` | Yes | The actual data you want to synchronize across clients | | `lastUpdated` | `any` | Yes | A timestamp or similar data indicating the last time the state data was updated | | `updatedBy` | `User` | Yes | The user who last updated the state data | | `tabId` | `string \| null` | No | An identifier that could be used to associate the state data with a specific tab or instance | #### LiveStateDataMap *** | Property | Type | Required | Description | | ------------------------------- | ----------------------------------------------- | -------- | --------------------------------------------------------------------------------------- | | `custom` | `{ [liveStateDataId: string]: LiveStateData; }` | No | Map of all unique LiveStateData set by you on the given document. | | `default` | Object | No | Map of all unique LiveStateData set by the default editor on the given document. | | `default.singleEditor` | `SingleEditorLiveStateData` | No | Part of `default`, representing single editor live state data. | | `default.autoSyncState` | Object | | Part of `default`, representing auto synchronization state. | | `default.autoSyncState.current` | `LiveStateData` | No | Part of `autoSyncState`, current live state data. | | `default.autoSyncState.history` | `[liveStateDataId: string]: LiveStateData` | No | Part of `autoSyncState`, map of historical live state data keyed by live state data ID. | #### LiveStateData *** | Property | Type | Required | Description | | --------------- | ------- | -------- | ----------------------------------------- | | `id` | string | Yes | Unique identifier for the live state data | | `locationName` | string | Yes | Name of the location | | `version` | Version | Yes | Version information | | `[key: string]` | any | Yes | Additional dynamic properties | #### SetLiveStateDataConfig *** | Property | Type | Required | Description | | -------- | --------- | -------- | ------------------------------------------------------------- | | `merge` | `boolean` | No | Whether to merge data with existing data. Default is `false`. | #### FetchLiveStateDataRequest *** | Property | Type | Required | Description | | ----------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | `liveStateDataId` | `string` | No | Unique identifier for the specific live state data to fetch. If not provided, all live state data will be fetched. | #### ServerConnectionState *** ```typescript theme={null} type ServerConnectionState = | 'online' | 'offline' | 'pendingInit' | 'pendingData'; ``` | String value | Description | | --------------- | -------------------------------------------- | | `'online'` | Server connection is online and active. | | `'offline'` | Server connection is offline. | | `'pendingInit'` | Server connection initialization is pending. | | `'pendingData'` | Server is waiting for data. | # Client #### Client Events | Event Type | Event Name | Description | Event Object | | --------------------- | -------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------- | | `USER_UPDATE` | `userUpdate` | Fired when the Velt user logs in, logs out, or changes. | [UserUpdateEvent](#userupdateevent) | | `INIT_UPDATE` | `initUpdate` | Initialization lifecycle updates (documents/locations set/unset, user init). | [InitUpdateEvent](#initupdateevent) | | `DOCUMENT_INIT` | `documentInit` | Document initialization status changes. | [DocumentInitEvent](#documentinitevent) | | `ERROR` | `error` | Error events emitted by the SDK (e.g., token issues, retry limits). | [ErrorEvent](#errorevent) | | `VELT_BUTTON_CLICK` | `veltButtonClick` | Fired when a Velt Button is clicked. | [VeltButtonClickEvent](#veltbuttonclickevent) | | `PERMISSION_PROVIDER` | `permissionProvider` | Permission Provider events for access requests, results, and errors. | [PermissionProviderEvent](#permissionproviderevent) | | `DATA_PROVIDER` | `dataProvider` | Data Provider events for debugging get, save, and delete operations. | [DataProviderEvent](#dataproviderevent) | #### InitUpdateEvent *** | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------------------------------------ | | `event` | `string` | Yes | The event name (see sub-events table below) | | `methodName` | `string` | No | The method that triggered this event (see `InitUpdateMethodNames` below) | | `source` | `string` | No | Source of the event | | `payload` | `any` | No | Additional event payload data | **InitUpdateMethodNames:** | Method Name | Description | | ------------------------ | ----------------------------------- | | `setDocuments` | `setDocuments()` was called | | `setRootDocument` | `setRootDocument()` was called | | `setDocumentId` | `setDocumentId()` was called | | `unsetDocumentId` | `unsetDocumentId()` was called | | `unsetDocuments` | `unsetDocuments()` was called | | `setLocation` | `setLocation()` was called | | `setLocations` | `setLocations()` was called | | `setRootLocation` | `setRootLocation()` was called | | `addLocation` | `addLocation()` was called | | `removeLocation` | `removeLocation()` was called | | `removeLocations` | `removeLocations()` was called | | `unsetLocationIds` | `unsetLocationIds()` was called | | `removeLocationsSuccess` | Locations were successfully removed | **Sub-events (event field values):** | Sub-event (string) | Description | | -------------------------- | --------------------------------------------------------------------------------------- | | `userUpdate` | User initialized or updated as part of init | | `setDocumentsTriggered` | A document(s) set action was triggered (`setDocument`, `setDocuments`, `setDocumentId`) | | `setRootDocumentTriggered` | Root document set was triggered (`setRootDocument`) | | `setDocumentsSuccess` | Documents successfully set | | `unsetDocumentsTriggered` | Unset document(s) was triggered (`unsetDocumentId`, `unsetDocuments`) | | `unsetDocumentsSuccess` | Documents successfully unset | | `setLocationsTriggered` | A location(s) set action was triggered (`setLocation`, `setLocations`) | | `setRootLocationTriggered` | Root location set was triggered (`setRootLocation`) | | `setLocationsSuccess` | Locations successfully set | | `unsetLocationsTriggered` | Unsetting location IDs was triggered (`unsetLocationIds`) | #### PermissionProviderEvent *** This event follows the `BaseResolverEvent` structure (see [DataProviderEvent](#dataproviderevent) for the base structure). | Event Type | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------ | | `resourceAccessRequestFormed` | Triggered when a permission request is formed internally before being sent | | `resourceAccessRequestTriggered` | Triggered when a permission request is actually triggered and sent | | `resourceAccessResult` | Triggered when a permission check result is received from your server | | `resourceAccessError` | Triggered when an error occurs during permission checking | | `resourceAccessResultFromCache` | Triggered when a permission result is retrieved from cache instead of making a new request | | `revokeAccessOnDocumentUnsetTriggered` | Triggered when permissions are automatically revoked due to document unset trigger | | `revokeAccessOnDocumentUnsetFormed` | Triggered when a revoke access on document unset request is formed | | `revokeAccessOnDocumentUnsetResult` | Triggered when revoke access on document unset completes successfully | | `revokeAccessOnDocumentUnsetError` | Triggered when an error occurs during revoke access on document unset | | `revokeAccessOnUserLogoutTriggered` | Triggered when permissions are automatically revoked due to user logout trigger | | `revokeAccessOnUserLogoutFormed` | Triggered when a revoke access on user logout request is formed | | `revokeAccessOnUserLogoutResult` | Triggered when revoke access on user logout completes successfully | | `revokeAccessOnUserLogoutError` | Triggered when an error occurs during revoke access on user logout | #### DataProviderEvent *** The `dataProvider` event emits different resolver event types depending on the data provider being used. All resolver events share a common base structure: **BaseResolverEvent Structure:** | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------ | | `event` | `object` | Yes | The event type object (varies by resolver) | | `methodName` | `string` | No | The method that triggered this event | | `moduleName` | `string` | No | The module that triggered this event | | `source` | `string` | No | `'internal'` or `'external'` | | `timestamp` | `number` | No | Timestamp of the event | | `uniqueId` | `string` | No | Unique identifier for the event | | `payload` | `any` | No | Additional event payload data | *** #### UserResolverEvent | Event Type | Description | | -------------------------------- | --------------------------------------------------------------- | | `userResolutionRequestFormed` | Triggered when a user resolution request is formed internally | | `userResolutionRequestTriggered` | Triggered when a user resolution request is sent | | `userResolutionResult` | Triggered when user resolution completes successfully | | `userResolutionError` | Triggered when an error occurs during user resolution | | `userResolutionResultFromCache` | Triggered when a user resolution result is retrieved from cache | **UserResolverModuleName:** | Module Name | Description | | ----------------------- | -------------------------------- | | `identify/authProvider` | From identify or auth provider | | `getTemporaryUsers` | From getting temporary users | | `getUsers` | From getting users | | `getHuddleUsers` | From getting huddle users | | `getSingleEditorUsers` | From getting single editor users | *** #### CommentResolverEvent | Event Type | Description | | ----------------------------------- | ------------------------------------------------------------------ | | `commentResolutionRequestFormed` | Triggered when a comment resolution request is formed internally | | `commentResolutionRequestTriggered` | Triggered when a comment resolution request is sent | | `commentResolutionResult` | Triggered when comment resolution completes successfully | | `commentResolutionError` | Triggered when an error occurs during comment resolution | | `commentResolutionResultFromCache` | Triggered when a comment resolution result is retrieved from cache | | `commentSaveRequestFormed` | Triggered when a comment save request is formed internally | | `commentSaveRequestTriggered` | Triggered when a comment save request is sent | | `commentSaveResult` | Triggered when comment save completes successfully | | `commentSaveError` | Triggered when an error occurs during comment save | | `commentDeleteRequestFormed` | Triggered when a comment delete request is formed internally | | `commentDeleteRequestTriggered` | Triggered when a comment delete request is sent | | `commentDeleteResult` | Triggered when comment delete completes successfully | | `commentDeleteError` | Triggered when an error occurs during comment delete | **CommentResolverModuleName:** | Module Name | Description | | ----------------------- | -------------------------------- | | `setDocuments` | From setDocuments call | | `getCommentAnnotations` | From getting comment annotations | | `getNotifications` | From getting notifications | *** #### AttachmentResolverEvent | Event Type | Description | | ---------------------------------- | ---------------------------------------------------------------- | | `attachmentSaveRequestFormed` | Triggered when an attachment save request is formed internally | | `attachmentSaveRequestTriggered` | Triggered when an attachment save request is sent | | `attachmentSaveResult` | Triggered when attachment save completes successfully | | `attachmentSaveError` | Triggered when an error occurs during attachment save | | `attachmentDeleteRequestFormed` | Triggered when an attachment delete request is formed internally | | `attachmentDeleteRequestTriggered` | Triggered when an attachment delete request is sent | | `attachmentDeleteResult` | Triggered when attachment delete completes successfully | | `attachmentDeleteError` | Triggered when an error occurs during attachment delete | *** #### ReactionResolverEvent | Event Type | Description | | ------------------------------------ | ------------------------------------------------------------------- | | `reactionResolutionRequestFormed` | Triggered when a reaction resolution request is formed internally | | `reactionResolutionRequestTriggered` | Triggered when a reaction resolution request is sent | | `reactionResolutionResult` | Triggered when reaction resolution completes successfully | | `reactionResolutionError` | Triggered when an error occurs during reaction resolution | | `reactionResolutionResultFromCache` | Triggered when a reaction resolution result is retrieved from cache | | `reactionSaveRequestFormed` | Triggered when a reaction save request is formed internally | | `reactionSaveRequestTriggered` | Triggered when a reaction save request is sent | | `reactionSaveResult` | Triggered when reaction save completes successfully | | `reactionSaveError` | Triggered when an error occurs during reaction save | | `reactionDeleteRequestFormed` | Triggered when a reaction delete request is formed internally | | `reactionDeleteRequestTriggered` | Triggered when a reaction delete request is sent | | `reactionDeleteResult` | Triggered when reaction delete completes successfully | | `reactionDeleteError` | Triggered when an error occurs during reaction delete | **ReactionResolverModuleName:** | Module Name | Description | | ------------------------ | --------------------------------- | | `setDocuments` | From setDocuments call | | `getReactionAnnotations` | From getting reaction annotations | *** #### RecorderResolverEvent | Event Type | Description | | ------------------------------------ | ------------------------------------------------------------- | | `recorderResolutionRequestFormed` | Triggered when a recorder get request is formed internally | | `recorderResolutionRequestTriggered` | Triggered when a recorder get request is sent | | `recorderResolutionResult` | Triggered when recorder get completes successfully | | `recorderResolutionError` | Triggered when an error occurs during recorder get | | `recorderResolutionResultFromCache` | Triggered when a recorder get result is retrieved from cache | | `recorderSaveRequestFormed` | Triggered when a recorder save request is formed internally | | `recorderSaveRequestTriggered` | Triggered when a recorder save request is sent | | `recorderSaveResult` | Triggered when recorder save completes successfully | | `recorderSaveError` | Triggered when an error occurs during recorder save | | `recorderDeleteRequestFormed` | Triggered when a recorder delete request is formed internally | | `recorderDeleteRequestTriggered` | Triggered when a recorder delete request is sent | | `recorderDeleteResult` | Triggered when recorder delete completes successfully | | `recorderDeleteError` | Triggered when an error occurs during recorder delete | #### Error Codes | Code | Meaning (summary) | | ------------------ | ---------------------------------- | | `token_expired` | The auth token is no longer valid. | | `too_many_retries` | Retried and hit the retry limit. | #### DocumentMetadata *** | Property | Type | Required | Description | | ---------------- | -------------------------------------------- | -------- | ---------------------------------------------------- | | `documentId` | `string` | Yes | Unique document id generated from client document id | | `documentName` | `string` | No | Display name of the document | | `folderId` | `string` | No | ID of the folder containing this document | | `apiKey` | `string` | No | API key associated with the document | | `organizationId` | `string` | Yes | Organization ID that owns this document | | `locations` | `{ [locationId: number]: LocationMetadata }` | No | Location metadata for this document | ### Folders #### FetchFoldersRequest *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | -------------------------------------------- | | `organizationId` | `string` | Yes | Organization ID to fetch folders from | | `folderId` | `string` | No | Parent folder ID to fetch child folders from | #### FetchFoldersResponse *** | Property | Type | Required | Description | | --------------- | ---------------------------------------- | -------- | --------------------------------------------------------- | | `data` | `Record \| null` | Yes | Map of folder IDs to their metadata. `Null` while loading | | `nextPageToken` | `string` | Yes | Token for fetching next page of results | ### Documents #### FetchDocumentsRequest *** | Property | Type | Required | Description | | ---------------- | ---------- | -------- | ------------------------------------------------------------------------ | | `organizationId` | `string` | No | Organization ID to fetch documents from | | `documentIds` | `string[]` | No | Array of specific document IDs to fetch | | `folderId` | `string` | No | Folder ID to fetch documents from | | `allDocuments` | `boolean` | No | Whether to fetch all documents. Use with `organizationId` or `folderId`. | #### FetchDocumentsResponse *** | Property | Type | Required | Description | | --------------- | -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `data` | `Record \| null` | Yes | Map of document groups to arrays of [DocumentMetadata](/api-reference/sdk/models/data-models#documentmetadata). `null` while loading. | | `nextPageToken` | `string` | Yes | Token for fetching next page of results. Default page size is 1000. | #### DocumentInitEvent *** * `DocumentInitEvent` can be of type: `boolean | undefined` * This represents the document initialization status. #### ErrorEvent *** | Property | Type | Required | Description | | -------------- | ---------- | -------- | -------------------------------------- | | `event` | `string` | No | The error event name | | `sourceMethod` | `string` | No | The method that triggered the error | | `documentIds` | `string[]` | No | Document IDs associated with the error | | `userId` | `string` | No | User ID associated with the error | | `timestamp` | `number` | No | Timestamp of the error | | `error` | `string` | No | Error details | | `code` | `string` | No | Error code | | `message` | `string` | No | Error message | | `source` | `string` | No | Source of the error | #### List of error codes: | Code | Description | | -------------------------------- | -------------------------------------------- | | `token_expired` | The JWT token has expired | | `same_user_editor_current_tab` | Same user is already editor in current tab | | `same_user_editor_different_tab` | Same user is already editor in different tab | | `another_user_editor` | Another user is already editor | #### SetUserAsEditorResponse *** | Property | Type | Required | Description | | -------- | ------------ | -------- | ----------------------------------------- | | `error` | `ErrorEvent` | No | Present when the action cannot be applied | #### LiveStateSingleEditorExternalUserPresence *** | Property | Type | Required | Description | | --------------------------- | ---------- | -------- | ------------------------------------------------------ | | `sameUserPresentOnTab` | `boolean` | No | True if the same user is present on a different tab | | `differentUserPresentOnTab` | `boolean` | No | True if a different user is present on a different tab | | `userIds` | `string[]` | No | User IDs of users present on a different tab | #### UserUpdateEvent *** * `UserUpdateEvent` will return data of type: `User | null` * If there is no user, it will return `null` else it will return the user object. #### VeltButtonClickEvent *** | Property | Type | Required | Description | | ----------------------------- | ------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `buttonContext` | `VeltButtonContext` | Yes | Button context | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | | `commentAnnotation` | `CommentAnnotation` | No | Comment annotation object | | `comment` | `Comment` | No | Comment object | | `index` | `number` | No | Index of the repeated component the button is in. eg: Comment, Notification component. | | `commentAnnotations` | `CommentAnnotation[]` | No | Array of comment annotations | | `systemFilteredAnnotations` | `CommentAnnotation[]` | No | Filtered comment annotations | | `unreadCommentAnnotationsMap` | `{ [commentAnnotationId: string]: number }` | No | Map of unread comment counts | | `notification` | `Notification` | No | Notification object | | `notifications` | `Notification[]` | No | Array of notifications | | `customFilters` | `CustomFilters` | No | Custom filters applied in the Comment Sidebar. Only available when custom sidebar filters are used and when the button is in the sidebar. | #### PermissionProviderEvent *** | Property | Type | Required | Description | | ---------- | ----------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | | `type` | `string` | Yes | Event type: `'request'`, `'result'`, or `'error'` | | `userId` | `string` | Yes | User ID making the permission request | | `resource` | `{ id: string; type: string; context?: { access: { [key: string]: string \| number } } }` | Yes | Resource being accessed. Includes optional `context` field with access information set during setDocuments. | | `result` | `boolean` | No | Permission result (present when type is `'result'`) | | `error` | `string` | No | Error message (present when type is `'error'`) | #### RevokeAccessEvent *** | Property | Type | Required | Description | | -------------- | -------- | -------- | --------------------------------------------------------------- | | `userId` | `string` | Yes | User ID whose access is being revoked | | `resourceType` | `string` | Yes | Type of resource: `'document'`, `'folder'`, or `'organization'` | | `resourceId` | `string` | Yes | ID of the resource | | `trigger` | `string` | Yes | Trigger type: `'documentUnset'` or `'userLogout'` | | `timestamp` | `number` | Yes | Unix timestamp when revocation occurred | #### Config | Property | Type | Required | Description | | ----------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `urlAllowList` | string\[] | No | Restricts Velt features to specific pages by specifying partial URL strings. | | `featureAllowList` | FeatureType\[] | No | Allow-list of Velt features permitted to run. In the modular SDK it also controls chunk preloading: when set, only the listed feature chunks are preloaded (others load on demand via `preload*()` / `getXElement()`); when omitted (default `undefined`), all lazy feature chunks are preloaded in the background, preserving pre-modular behavior. Calling `preload*()` or `getXElement()` for an omitted feature auto-enables it. | | `userPlanAllowList` | string\[] | No | Restricts Velt features to specific user plans. | | `userIdAllowList` | string\[] | No | Restricts Velt features to specific users. | | `usePrefersColorScheme` | boolean | No | If set to true, listens to changes on the `prefers-color-scheme` media query to set the global theme of Velt components. | | `globalStyles` | boolean | No | Controls whether Velt's global CSS styles are loaded. Default: true | Valid modular feature keys for `featureAllowList` are: `'comment'`, `'cursor'`, `'presence'`, `'huddle'`, `'recorder'`, `'notification'`, `'reaction'`, `'arrow'`, `'tag'`, `'rewriter'`, `'selection'`, `'area'`, `'activity'`, `'views'`, `'userInvite'`, `'userRequest'`, `'videoPlayer'`, `'crdt'`, and `'liveStateSync'`. Use these strings when configuring modular chunk preloading. The `Features` enum below documents public enum values; `Features.LIVE_SELECTION` remains `'liveSelection'` for backward compatibility, while the v6 modular allow-list key for Live Selection is `'selection'`. #### Features *** | Property | Type | Required | Description | | ----------------- | ----------------- | -------- | -------------------------------------------------- | | `AREA` | `'area'` | No | Area feature for drawing areas/rectangles | | `ARROW` | `'arrow'` | No | Arrow feature for drawing arrows | | `AUDIO_HUDDLE` | `'audioHuddle'` | No | Audio huddle feature for voice conversations | | `COMMENT` | `'comment'` | No | Comment feature for adding comments | | `CRDT` | `'crdt'` | No | CRDT feature (lazy chunk `velt-crdt.js`) | | `CURSOR` | `'cursor'` | No | Cursor feature for showing user cursors | | `HUDDLE` | `'huddle'` | No | Huddle feature for video conversations | | `LIVE_STATE_SYNC` | `'liveStateSync'` | No | Live state sync feature | | `PRESENCE` | `'presence'` | No | Presence feature for showing online users | | `TAG` | `'tag'` | No | Tag feature for adding tags | | `RECORDER` | `'recorder'` | No | Recorder feature for recording sessions | | `REWRITER` | `'rewriter'` | No | Rewriter feature for text rewriting | | `LIVE_SELECTION` | `'liveSelection'` | No | Live selection feature for showing user selections | #### VeltEventMetadata *** | Property | Type | Required | Description | | ---------------------- | -------------------------------- | -------- | --------------------- | | `organizationMetadata` | `OrganizationMetadata` \| `null` | No | Organization metadata | | `documentMetadata` | `DocumentMetadata` \| `null` | No | Document metadata | | `location` | `Location` \| `null` | No | Location information | #### VeltButtonContext *** | Property | Type | Required | Description | | ----------------- | ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------ | | `type` | `'button' \| 'button-toggle' \| 'multi-select' \| 'single-select'` | No | Type of button (default: 'button') | | `groupId` | `string` | No | ID of the button group | | `selections` | `VeltButtonSelectionMap` | No | Map of button selections grouped by button groupIds. For buttons without a group, the groupdId will be 'ungrouped' | | `clickedButtonId` | `string` | No | ID of the clicked button | #### VeltButtonSelectionMap *** | Property | Type | Required | Description | | ------------------- | --------------------------------- | -------- | ------------------------------------ | | `[groupId: string]` | `{ [buttonId: string]: boolean }` | No | Map of button selections for a group | #### UpdateDocumentsRequest *** | Property | Type | Required | Description | | ---------------- | ----------------------------- | -------- | --------------------------------------------- | | `organizationId` | `string` | No | Unique identifier for the organization. | | `folderId` | `string` | No | Unique identifier for the folder. | | `documents` | `UpdateDocumentMetadata[]` | No | Array of document metadata objects to update. | #### UpdateDocumentMetadata *** \| Property | Type | Required | Description | \| --------------- | -------- | -------- | ----------------------------------- | ------------------------------------------------------- | \| `documentId` | `string` | Yes | Unique identifier for the document. | \| `[key: string]` | `T | string` | No | Additional custom properties for the document metadata. | #### Metadata *** | Property | Type | Required | Description | | --------------- | ---------------------- | -------- | ------------------------------------------------------- | | `apiKey` | `string` | Yes | API key associated with the event. | | `pageInfo` | `PageInfo` | No | Information about the page where the event occurred. | | `folderId` | `string` | No | Unique identifier for the folder. | | `locations` | `object` | No | Object containing location data indexed by location ID. | | `document` | `DocumentMetadata` | No | Document metadata associated with the event. | | `organization` | `OrganizationMetadata` | No | Organization metadata associated with the event. | | `[key: string]` | `any` | No | Additional custom properties. | #### DocumentMetadata *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | --------------------------------------- | | `documentId` | `string` | Yes | Unique identifier for the document. | | `documentName` | `string` | No | Name of the document. | | `organizationId` | `string` | No | Unique identifier for the organization. | | `folderId` | `string` | No | Unique identifier for the folder. | | `[key: string]` | `any` | No | Additional custom properties. | #### OrganizationMetadata *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | --------------------------------------- | | `organizationId` | `string` | Yes | Unique identifier for the organization. | | `[key: string]` | `any` | No | Additional custom properties. | #### PageInfo *** Page info attached to newly created data. Set via [`setPageInfo()`](/api-reference/sdk/api/api-methods#setpageinfo); readable via `documentMetadata.pageInfo` at `setDocumentId`/`setDocuments` call time. | Property | Type | Required | Description | | ------------- | ----------------------------- | -------- | ----------------------------------------- | | `url` | `string` | No | Full URL of the page. | | `path` | `string` | No | Path of the page. | | `queryParams` | `string` | No | Query parameters of the page URL. | | `baseUrl` | `string` | No | Base URL of the page. | | `title` | `string` | No | Title of the page. | | `arrowUrl` | `string` | No | URL associated with arrow annotations. | | `areaUrl` | `string` | No | URL associated with area annotations. | | `commentUrl` | `string` | No | URL associated with comment annotations. | | `tagUrl` | `string` | No | URL associated with tag annotations. | | `recorderUrl` | `string` | No | URL associated with recordings. | | `screenWidth` | `number` | No | Screen width of the page, in pixels. | | `deviceInfo` | [`IDeviceInfo`](#ideviceinfo) | No | Device information captured for the page. | #### IDeviceInfo *** Device information captured by the SDK and attached to [`PageInfo`](#pageinfo). Populated automatically from the browser environment. | Property | Type | Required | Description | | ---------------- | -------- | -------- | ---------------------------------------- | | `userAgent` | `string` | No | User agent string of the browser. | | `browserName` | `string` | No | Browser name, e.g. `Chrome`. | | `browserVersion` | `string` | No | Browser version. | | `deviceType` | `string` | No | Device type, e.g. `desktop` or `mobile`. | | `osName` | `string` | No | Operating system name, e.g. `macOS`. | | `osVersion` | `string` | No | Operating system version. | | `screenWidth` | `number` | No | Screen width of the device, in pixels. | | `screenHeight` | `number` | No | Screen height of the device, in pixels. | #### VeltAuthTokenRequest *** | Property | Type | Required | Description | | ---------------- | --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `apiKey` | `string` | Yes | **API Key**. Must be provided, cannot be empty or whitespace only. | | `userId` | `string` | Yes | **User ID**. Must be provided, cannot be empty or whitespace only. | | `userProperties` | `UserProperties` | No | Additional user information to embed in the auth token. See below for details. | | `permissions` | `{ resources: Resource[] }` | No | Permissions configuration. Defines what resources the user can access and their access levels. If not provided, defaults to no resource access. | #### UserProperties *** | Property | Type | Required | Description | | --------------- | --------- | -------- | ------------------------------------------------------------------------------------ | | `isAdmin` | `boolean` | No | Whether the user is an admin. | | `name` | `string` | No | User's display name. If provided, cannot be empty or whitespace only. | | `email` | `string` | No | User's email address. If provided, cannot be empty and must be a valid email format. | | `[key: string]` | `any` | No | Allows flexibility for custom user attributes. | #### Permissions *** | Property | Type | Required | Description | | ----------- | ------------ | -------- | ----------------------------------------------------------------------------------------- | | `resources` | `Resource[]` | No | Array of resources the user has permission to access. Defaults to empty array if not set. | #### Resource *** Each resource represents something the user can access (organization, folder, or document). | Property | Type | Required | Description | | ---------------- | ------------------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `'organization' \| 'folder' \| 'document'` | Yes | Resource type. Must be one of: 'organization', 'folder', or 'document'. Determines the scope and level of access. | | `id` | `string` | Yes | Unique identifier for the specific resource. Cannot be whitespace only. For organization: the organization ID. For folder: the folder ID. For document: the document ID. | | `organizationId` | `string` | Conditionally | Organization ID. **Required** for `folder` and `document` types. Optional for `organization` type. Must be provided and non-empty for folder/document resources. Links the resource to a specific organization. | | `expiresAt` | `number` | No | Expiration timestamp (Unix timestamp). If provided, must be a positive integer, greater than the current time, and a valid number. Used for temporary access grants. | #### BaseMetadata *** | Property | Type | Required | Description | | ---------------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------- | | `apiKey` | `string` | No | API key associated with the request. | | `documentId` | `string` | No | Unique identifier for the document. | | `clientDocumentId` | `string` | No | Client-side document identifier (original value supplied by your application). | | `organizationId` | `string` | No | Unique identifier for the organization. | | `clientOrganizationId` | `string` | No | Client-side organization identifier (original value supplied by your application). | | `folderId` | `string` | No | Your application's folder identifier. | | `veltFolderId` | `string` | No | Velt-generated internal folder identifier. | | `documentMetadata` | `Record` | No | Arbitrary document-level metadata pass-through. | | `sdkVersion` | `string \| null` | No | Version of the Velt SDK that produced the request. *Added in `@veltdev/node` v1.0.2.* | #### Document *** | Property | Type | Required | Description | | ---------- | ------------------ | -------- | ------------------------------------- | | `id` | `string` | Yes | Unique identifier for the document | | `metadata` | `DocumentMetadata` | Yes | Metadata associated with the document | #### DocumentAccessType *** ```typescript theme={null} type DocumentAccessType = | 'public' | 'restricted' | 'organizationPrivate'; ``` | String value | Description | | ----------------------- | ----------------------------------------------------------- | | `'public'` | Anyone with document access can open the document. | | `'restricted'` | Only explicitly allowed users can open the document. | | `'organizationPrivate'` | Users in the document's organization can open the document. | #### SetDocumentsRequestOptions *** | Property | Type | Required | Description | | ----------------------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `organizationId` | `string` | No | Organization ID for the documents | | `folderId` | `string` | No | Subscribe to all or provided documents in the given folder | | `locationId` | `string` | No | Filter and subscribe to document data for a specific location | | `allDocuments` | `boolean` | No | Subscribe to all documents in the folder. Use this when folderId is provided | | `rootDocumentId` | `string` | No | The unique identifier of the root document. Used to specify the root document when multiple documents are subscribed. | | `context` | [`SetDocumentsContext`](#setdocumentscontext) | No | Filter comments by custom context fields. Fetches comments matching all provided field values (AND logic across fields). When Permission Provider is enabled with `isContextEnabled: true`, each context value triggers a separate permission request. | | `debounceTime` | `number` | No | Per-call override for the debounce window (in ms) before emitting the document subscription. Overrides the global default for this call only. | | `optimisticPermissions` | `boolean` | No | When `false`, waits for permission validation to complete before returning. Defaults to `true` (optimistic). | #### FolderMetadata *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------------------------ | | `folderId` | `string` | No | Unique identifier for the folder | | `parentFolderId` | `string` | No | ID of the parent folder | | `folderName` | `string` | No | Display name of the folder | | `createdAt` | `number` | No | Timestamp when folder was created | | `lastUpdated` | `number` | No | Timestamp when folder was last updated | | `apiKey` | `string` | No | API key associated with the folder | | `organizationId` | `string` | No | Organization ID that the folder belongs to | #### CustomCss *** | Property | Type | Required | Description | | -------- | ------------------ | -------- | --------------------------------------------------------------------- | | `type` | 'link' \| 'styles' | Yes | The type of custom CSS, either a link to a CSS file or inline styles. | | `value` | string | Yes | The value of the custom CSS, either a URL or CSS styles. | ### Debug Info #### VeltDebugInfo *** | Property | Type | Required | Description | | ------------- | -------------------------------------------------------------------- | -------- | ---------------------------------------------- | | `veltVersion` | `string` | No | The version of the Velt SDK currently running | | `apiKey` | `string` | No | The API key used to initialize the Velt client | | `serverMap` | [`DebugInfoMap`](/api-reference/sdk/models/data-models#debuginfomap) | No | Debug information from the server-side state | | `clientMap` | [`DebugInfoMap`](/api-reference/sdk/models/data-models#debuginfomap) | No | Debug information from the client-side state | #### DebugInfoMap *** | Property | Type | Required | Description | | -------------- | ------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------ | | `organization` | [`OrganizationMetadata`](/api-reference/sdk/models/data-models#organizationmetadata) | No | Metadata about the current organization | | `documents` | [`DocumentMetadata[]`](/api-reference/sdk/models/data-models#documentmetadata) | No | Array of document metadata for all active documents | | `locations` | [`Location[]`](/api-reference/sdk/models/data-models#location) | No | Array of location information for all active locations | | `folder` | [`FolderMetadata`](/api-reference/sdk/models/data-models#foldermetadata) | No | Metadata about the current folder | | `user` | [`User`](/api-reference/sdk/models/data-models#user) | No | The currently authenticated user | ## Location #### Location | Property | Type | Required | Description | | --------------- | ------------------ | -------- | --------------------------------------------------------------------------------------------------- | | `id` | `string \| number` | No | Unique identifier for the location. An id of `0` is valid and takes precedence over `locationName`. | | `locationName` | `string` | No | Name of the location. A non-empty name identifies the location when `id` is omitted. | | `version` | `Version` | No | Version information provided by the user. | | `[key: string]` | `any` | No | Additional dynamic properties for the location. | #### UpdateLocationsRequest *** | Property | Type | Required | Description | | ---------------- | ----------------------------- | -------- | ---------------------------------------------- | | `organizationId` | `string` | No | Unique identifier for the organization. | | `documentIds` | `string[]` | No | Array of document IDs to update locations for. | | `locations` | `UpdateLocationMetadata[]` | No | Array of location metadata objects to update. | #### UpdateLocationMetadata *** \| Property | Type | Required | Description | \| --------------- | -------- | -------- | ----------------------------------- | ------------------------------------------------------- | \| `id` | `string` | Yes | Unique identifier for the location. | \| `[key: string]` | `T | string` | No | Additional custom properties for the location metadata. | #### LocationMetadata *** | Property | Type | Required | Description | | ------------ | ------------------ | -------- | ------------------------------------------------------------- | | `locationId` | number | No | Unique location id generated from client location information | | `location` | `Location` \| null | No | Location object provided by a client | #### SetLocationsRequestOptions *** | Property | Type | Required | Description | | ---------------- | --------- | -------- | ---------------- | | `rootLocationId` | `string` | No | Root location. | | `appendLocation` | `boolean` | No | Merge locations. | # Self Hosting #### PartialUser *** | Property | Type | Required | Description | | -------- | -------- | -------- | ------------------------------ | | `userId` | `string` | Yes | Unique identifier for the user | #### PartialReactionAnnotation *** | Property | Type | Required | Description | | --------------- | -------------- | -------- | -------------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the reaction annotation | | `metadata` | `BaseMetadata` | No | Additional metadata | | `icon` | `string` | No | Icon for the reaction | | `from` | `PartialUser` | No | User who created the reaction annotation | | `[key: string]` | `any` | No | Additional custom fields configured via `fieldsToRemove` | #### ResolverActions *** A string-literal union that defines the actions that can trigger resolver events. As of **v6.0.0-beta.3**, `ResolverActions`, `CommentResolverSaveEvent`, and 14 other type-signature enums are `as const` objects with string-literal union types instead of runtime `enum`s. Import them with `import type` and pass the string literal value (e.g. `'reaction.add'`) rather than `ResolverActions.REACTION_ADD`. The declaration keys below show how the former enum members map to the string values you pass. | Declaration key | String value | Description | | ---------------------------- | ------------------------------ | ------------------------------------------------------ | | `COMMENT_ANNOTATION_ADD` | `'comment_annotation.add'` | Triggered when a new comment annotation is added | | `COMMENT_ANNOTATION_DELETE` | `'comment_annotation.delete'` | Triggered when a comment annotation is deleted | | `COMMENT_ADD` | `'comment.add'` | Triggered when a new comment is added to an annotation | | `COMMENT_DELETE` | `'comment.delete'` | Triggered when a comment is deleted from an annotation | | `COMMENT_UPDATE` | `'comment.update'` | Triggered when a comment is updated | | `REACTION_ADD` | `'reaction.add'` | Triggered when a reaction is added to a comment | | `REACTION_DELETE` | `'reaction.delete'` | Triggered when a reaction is removed from a comment | | `ATTACHMENT_ADD` | `'attachment.add'` | Triggered when an attachment is added to a comment | | `ATTACHMENT_DELETE` | `'attachment.delete'` | Triggered when an attachment is deleted from a comment | | `RECORDER_ANNOTATION_ADD` | `'recorder_annotation.add'` | Triggered when a recorder annotation is added | | `RECORDER_ANNOTATION_UPDATE` | `'recorder_annotation.update'` | Triggered when a recorder annotation is updated | | `RECORDER_ANNOTATION_DELETE` | `'recorder_annotation.delete'` | Triggered when a recorder annotation is deleted | | `ACTIVITY_SAVE` | `'activity.save'` | Triggered when an activity record is saved | #### CommentResolverSaveEvent *** Non-core, annotation-level comment save events that customers can opt into receiving via [`ResolverConfig.additionalSaveEvents`](#resolverconfig), beyond the 4 core PII events. May appear as the `event` value on [`SaveCommentResolverRequest`](#savecommentresolverrequest). | Name | Value | Description | | -------------------- | ----------------------------------------- | ------------------------------------------------------ | | `STATUS_CHANGE` | `'comment_annotation.status_change'` | Triggered when the annotation status changes | | `PRIORITY_CHANGE` | `'comment_annotation.priority_change'` | Triggered when the annotation priority changes | | `ASSIGN` | `'comment_annotation.assign'` | Triggered when the annotation is assigned | | `ACCESS_MODE_CHANGE` | `'comment_annotation.access_mode_change'` | Triggered when the annotation access mode changes | | `CUSTOM_LIST_CHANGE` | `'comment_annotation.custom_list_change'` | Triggered when an annotation custom list value changes | | `APPROVE` | `'comment_annotation.approve'` | Triggered when the annotation is approved | | `ACCEPT` | `'comment.accept'` | Triggered when a comment suggestion is accepted | | `REJECT` | `'comment.reject'` | Triggered when a comment suggestion is rejected | | `SUGGESTION_ACCEPT` | `'comment_annotation.suggestion_accept'` | Triggered when an annotation suggestion is accepted | | `SUGGESTION_REJECT` | `'comment_annotation.suggestion_reject'` | Triggered when an annotation suggestion is rejected | | `REACTION_ADD` | `'comment.reaction_add'` | Triggered when a reaction is added to a comment | | `REACTION_DELETE` | `'comment.reaction_delete'` | Triggered when a reaction is removed from a comment | | `SUBSCRIBE` | `'comment_annotation.subscribe'` | Triggered when a user subscribes to the annotation | | `UNSUBSCRIBE` | `'comment_annotation.unsubscribe'` | Triggered when a user unsubscribes from the annotation | The comment-level reaction values `'comment.reaction_add'` and `'comment.reaction_delete'` are distinct from the reaction resolver values `'reaction.add'` and `'reaction.delete'`. #### AdditionalSaveEventConfig *** Element type of [`ResolverConfig.additionalSaveEvents`](#resolverconfig). | Property | Type | Required | Description | | -------- | ------------------------------------------------------- | -------- | -------------------------------------------------------------------------------- | | `event` | [`CommentResolverSaveEvent`](#commentresolversaveevent) | Yes | The non-core annotation-level event to opt into delivering to the save endpoint. | #### UserResolverModuleName *** Enum defining module names for user-related resolver operations. Used in data provider events to identify which module triggered the resolver call. [Self-Host User Data →](/self-host-data/users#debugging) | Name | Value | Description | | ------------------------- | ------------------------- | -------------------------------------------------------- | | `IDENTIFY` | `'identify/authProvider'` | Resolver module for identifying and authenticating users | | `GET_TEMPORARY_USERS` | `'getTemporaryUsers'` | Resolver module for fetching temporary user data | | `GET_USERS` | `'getUsers'` | Resolver module for fetching user data | | `GET_HUDDLE_USERS` | `'getHuddleUsers'` | Resolver module for fetching huddle participant data | | `GET_SINGLE_EDITOR_USERS` | `'getSingleEditorUsers'` | Resolver module for fetching single editor user data | #### CommentResolverModuleName *** Enum defining module names for comment-related resolver operations. Used in data provider events to identify which module triggered the resolver call. [Self-Host Comment Data →](/self-host-data/comments#debugging) | Name | Value | Description | | ------------------------- | ------------------------- | -------------------------------------------------- | | `SET_DOCUMENTS` | `'setDocuments'` | Resolver module for setting comment documents | | `GET_COMMENT_ANNOTATIONS` | `'getCommentAnnotations'` | Resolver module for fetching comment annotations | | `GET_NOTIFICATIONS` | `'getNotifications'` | Resolver module for fetching comment notifications | #### ReactionResolverModuleName *** Enum defining module names for reaction-related resolver operations. Used in data provider events to identify which module triggered the resolver call. [Self-Host Reaction Data →](/self-host-data/reactions#debugging) | Name | Value | Description | | -------------------------- | -------------------------- | ------------------------------------------------- | | `SET_DOCUMENTS` | `'setDocuments'` | Resolver module for setting reaction documents | | `GET_REACTION_ANNOTATIONS` | `'getReactionAnnotations'` | Resolver module for fetching reaction annotations | #### RecorderResolverModuleName *** Enum defining module names for recorder-related resolver operations. Used in data provider events to identify which module triggered the resolver call. [Self-Host Recording Data →](/self-host-data/recordings#debugging) | Name | Value | Description | | -------------------------- | -------------------------- | ------------------------------------------------- | | `GET_RECORDER_ANNOTATIONS` | `'getRecorderAnnotations'` | Resolver module for fetching recorder annotations | #### RecorderResolverSource *** Enum defining the source of a recorder resolver lifecycle event. | Name | Value | Description | | ------------------------------ | ------------------------------ | ---------------------------------------------------- | | `RESOLVE_RECORDER_ANNOTATIONS` | `'resolveRecorderAnnotations'` | Source for resolving (fetching) recorder annotations | | `SAVE_RECORDER_ANNOTATION` | `'saveRecorderAnnotation'` | Source for saving a recorder annotation | | `DELETE_RECORDER_ANNOTATION` | `'deleteRecorderAnnotation'` | Source for deleting a recorder annotation | | `FORMAT_RESPONSE` | `'formatResponse'` | Source for formatting the resolver response | | `INIT_DOCUMENTS` | `'initDocuments'` | Source for initializing documents | | `SET_DATA` | `'setData'` | Source for setting recorder data | | `UPDATE_DATA` | `'updateData'` | Source for updating recorder data | | `DELETE_DATA` | `'deleteData'` | Source for deleting recorder data | #### RecorderResolverEventType *** Union type for all recorder resolver lifecycle event type strings. | Value | Description | | -------------------------------------- | ----------------------------------------------- | | `'recorderResolutionRequestFormed'` | A recorder get request was formed internally | | `'recorderResolutionRequestTriggered'` | A recorder get request was sent | | `'recorderResolutionResult'` | Recorder get completed successfully | | `'recorderResolutionError'` | An error occurred during recorder get | | `'recorderResolutionResultFromCache'` | A recorder get result was retrieved from cache | | `'recorderSaveRequestFormed'` | A recorder save request was formed internally | | `'recorderSaveRequestTriggered'` | A recorder save request was sent | | `'recorderSaveResult'` | Recorder save completed successfully | | `'recorderSaveError'` | An error occurred during recorder save | | `'recorderDeleteRequestFormed'` | A recorder delete request was formed internally | | `'recorderDeleteRequestTriggered'` | A recorder delete request was sent | | `'recorderDeleteResult'` | Recorder delete completed successfully | | `'recorderDeleteError'` | An error occurred during recorder delete | #### PartialComment *** | Property | Type | Required | Description | | -------------------- | ----------------------------------- | -------- | -------------------------------------------------------------------------------------- | | `commentId` | `string \| number` | Yes | Unique identifier for the comment | | `commentHtml` | `string` | No | HTML content of the comment | | `commentText` | `string` | No | Plain text content of the comment | | `attachments` | `Record` | No | Map of attachment IDs to partial attachment data | | `from` | `PartialUser` | No | User who created the comment | | `to` | `PartialUser[]` | No | Users the comment is directed to | | `taggedUserContacts` | `PartialTaggedUserContacts[]` | No | Tagged user contacts in the comment | | `[key: string]` | `unknown` | No | Index signature; unknown keys are preserved by the `@veltdev/node` round-trip helpers. | `@veltdev/node` v1.0.2 exposes `partialCommentFromDict` and `partialCommentToDict` round-trip helpers that preserve unknown keys for forward compatibility. #### PartialTaggedUserContacts *** | Property | Type | Required | Description | | --------- | ------------- | -------- | ------------------------------------- | | `userId` | `string` | Yes | Unique identifier for the tagged user | | `contact` | `PartialUser` | No | Contact details of the tagged user | | `text` | `string` | No | Display text for the tagged user | #### PartialCommentAnnotation *** | Property | Type | Required | Description | | ------------------ | -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the comment annotation | | `metadata` | `BaseMetadata` | No | Additional metadata | | `comments` | `Record` | No | Map of comment IDs to partial comments data | | `from` | `PartialUser` | No | User who created the annotation. *Typed in `@veltdev/node` v1.0.2 (was previously pass-through).* | | `assignedTo` | `PartialUser` | No | User the annotation is assigned to. *Typed in `@veltdev/node` v1.0.2.* | | `targetTextRange` | `PartialTargetTextRange` | No | Text range the annotation is anchored to. *Typed in `@veltdev/node` v1.0.2.* | | `resolvedByUserId` | `string \| null` | No | ID of the resolving user. Three-state semantics in `@veltdev/node` v1.0.2: omit = no change, `null` = unresolve, string = resolve. See [Node SDK Data Models](/backend-sdks/node#resolvedbyuserid-semantics). | | `[key: string]` | `unknown` | No | Index signature; unknown keys are preserved by the `@veltdev/node` round-trip helpers. | `@veltdev/node` v1.0.2 exposes `partialCommentAnnotationFromDict` and `partialCommentAnnotationToDict` round-trip helpers. #### PartialTargetTextRange *** | Property | Type | Required | Description | | -------- | -------- | -------- | ----------------------------------------------------- | | `text` | `string` | Yes | The selected text snippet the comment is anchored to. | *Introduced in `@veltdev/node` v1.0.2.* The SDK exposes `partialTargetTextRangeFromDict` and `partialTargetTextRangeToDict` serializers. #### PartialAttachment *** | Property | Type | Required | Description | | -------------- | -------- | -------- | -------------------------------- | | `url` | `string` | Yes | URL of the attachment | | `name` | `string` | Yes | Name of the attachment | | `attachmentId` | `number` | Yes | Unique identifier for attachment | #### ResolverAttachment *** | Property | Type | Required | Description | | -------------- | ---------------------------- | -------- | -------------------------------- | | `attachmentId` | `number` | Yes | Unique identifier for attachment | | `file` | `File` | Yes | File to be uploaded | | `name` | `string` | No | File name | | `metadata` | `AttachmentResolverMetadata` | No | Metadata of the attachment | | `mimeType` | `string` | No | Mime type of the attachment | #### AttachmentResolverMetadata *** As of v5.0.2-beta.11, the `metadata` object passed to `AttachmentDataProvider.delete()` contains only `apiKey`, `documentId`, `organizationId`, and `folderId`. The `attachmentId` and `commentAnnotationId` fields are no longer forwarded to the delete callback. They remain available in the `save()` callback metadata. | Property | Type | Required | Description | | --------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------ | | `organizationId` | `string \| null` | Yes | ID of the organization | | `documentId` | `string \| null` | Yes | ID of the document | | `folderId` | `string \| null` | No | ID of the folder | | `attachmentId` | `number \| null` | No | ID of the attachment. Not present in `delete()` callbacks (v5.0.2-beta.11+). | | `commentAnnotationId` | `string \| null` | No | ID of the comment annotation. Not present in `delete()` callbacks (v5.0.2-beta.11+). | | `apiKey` | `string \| null` | Yes | API key for authentication | #### VeltDataProvider *** | Property | Type | Required | Description | | --------------- | ------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------- | | `comment` | `CommentAnnotationDataProvider` | No | Provider for comment annotation data | | `user` | `UserDataProvider` | No | Provider for user data | | `reaction` | `ReactionAnnotationDataProvider` | No | Provider for reaction annotation data | | `attachment` | `AttachmentDataProvider` | No | Provider for file attachment data | | `recorder` | `RecorderAnnotationDataProvider` | No | Provider for recording annotation PII data | | `activity` | [`ActivityAnnotationDataProvider`](#activityannotationdataprovider) | No | Provider for activity log PII data | | `notification` | [`NotificationDataProvider`](#notificationdataprovider) | No | Provider for custom notification PII data | | `anonymousUser` | [`AnonymousUserDataProvider`](#anonymoususerdataprovider) | No | Provider to resolve email → userId mappings for anonymous users tagged by email in comments. | #### ResolverEndpointConfig *** Config-based resolver endpoint configuration. SDK handles HTTP requests, headers, and response formatting automatically. | Property | Type | Required | Description | | ------------- | ------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `string` | Yes | Backend endpoint URL for resolver operation | | `headers` | `Record \| (() => Promise>)` | No | Static headers object (captured once) OR an async function resolved on every request — including each retry — so a short-lived per-request token is always fresh. | | `credentials` | `'include' \| 'same-origin' \| 'omit'` | No | Forwarded to `fetch()` for cookie/session auth on resolver endpoints. Omitted when unset (fetch keeps its `'same-origin'` default — byte-identical to prior behavior). Use `'include'` for cross-origin cookie/session auth. | #### ResolverConfig *** | Property | Type | Required | Description | | ---------------------- | ----------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `resolveTimeout` | `number` | No | Timeout duration (in milliseconds) for resolver operations | | `saveRetryConfig` | `RetryConfig` | No | Retry configuration for save operations | | `deleteRetryConfig` | `RetryConfig` | No | Retry configuration for delete operations | | `getRetryConfig` | `RetryConfig` | No | Retry configuration for get operations. Currently not supported for UserDataProvider. | | `resolveUsersConfig` | `ResolveUsersConfig` | No | Configuration for resolving users | | `getConfig` | `ResolverEndpointConfig` | No | Config-based endpoint for fetch operations | | `saveConfig` | `ResolverEndpointConfig` | No | Config-based endpoint for save operations | | `deleteConfig` | `ResolverEndpointConfig` | No | Config-based endpoint for delete operations | | `additionalFields` | `string[]` | No | Custom fields copied to resolver payloads but retained in Velt's storage | | `fieldsToRemove` | `string[]` | No | Fields stripped from Velt's storage before writing to your resolver endpoint | | `additionalSaveEvents` | [`AdditionalSaveEventConfig[]`](#additionalsaveeventconfig) | No | Opt-in list of additional (non-core) annotation-level save events delivered to the existing save endpoint, beyond the 4 core PII events. Absent/empty ⇒ no extra events (default, backward-compatible). | #### ResolverResponse *** Generic response format for backend endpoints and data providers. **Permission Provider Update (v4.5.8-beta.2)**: For Permission Provider backend endpoints, the `signature` field is no longer required. The SDK now handles validation internally. | Property | Type | Required | Description | | ------------ | --------- | -------- | -------------------------------------------------------------------------------- | | `data` | `T` | No | Response data of generic type T | | `success` | `boolean` | Yes | Whether the operation was successful. Must be `true` for successful responses | | `message` | `string` | No | Optional message describing the result | | `timestamp` | `number` | No | Optional timestamp of the response | | `statusCode` | `number` | Yes | HTTP status code. Must be `200` for Velt to accept the response | | `signature` | `string` | No | Cryptographic signature (deprecated for Permission Provider as of v4.5.8-beta.2) | #### RetryConfig *** | Property | Type | Required | Description | | ----------------- | --------- | -------- | -------------------------------------------- | | `retryCount` | `number` | No | Number of retry attempts | | `retryDelay` | `number` | No | Delay between retry attempts in milliseconds | | `revertOnFailure` | `boolean` | No | Whether to revert changes on failure | #### ResolveUsersConfig *** | Property | Type | Required | Description | | -------------- | --------- | -------- | ------------------------------------- | | `organization` | `boolean` | No | Whether to resolve organization users | | `folder` | `boolean` | No | Whether to resolve folder users | | `document` | `boolean` | No | Whether to resolve document users | #### CommentAnnotationDataProvider *** | Property | Type | Required | Description | | -------- | ------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------- | | `get` | `(request: GetCommentResolverRequest) => Promise>>` | No | Function to fetch comment annotations | | `save` | `(request: SaveCommentResolverRequest) => Promise>` | No | Function to save comment annotations | | `delete` | `(request: DeleteCommentResolverRequest) => Promise>` | No | Function to delete comment annotations | | `config` | `ResolverConfig` | No | Configuration for the data provider | #### PartialCommentAnnotationResult *** Resolver result payload for comment annotation data after PII stripping. | Property | Type | Required | Description | | -------------- | ------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------ | | `strippedData` | `Record \| null` | Yes | Annotation data with configured PII fields stripped | | `originalData` | [`CommentAnnotation`](#commentannotation) \| `null` | Yes | Original annotation data before PII stripping | | `eventType` | [`ResolverActions`](#resolveractions) \| [`CommentResolverSaveEvent`](#commentresolversaveevent) | No | Resolver action or opted-in comment save event that produced this result | #### ReactionAnnotationDataProvider *** | Property | Type | Required | Description | | -------- | --------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `get` | `(request: GetReactionResolverRequest) => Promise>>` | No | Function to fetch reaction annotations | | `save` | `(request: SaveReactionResolverRequest) => Promise>` | No | Function to save reaction annotations | | `delete` | `(request: DeleteReactionResolverRequest) => Promise>` | No | Function to delete reaction annotations | | `config` | `ResolverConfig` | No | Configuration for the data provider. Supports `fieldsToRemove` to strip top-level custom fields from Velt's storage and restore them on read. | #### UserDataProvider *** | Property | Type | Required | Description | | -------- | ------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------- | | `get` | `(userIds: string[]) => Promise \| ResolverResponse>>` | No | Function to fetch user data by user IDs. Both response formats are supported for backward compatibility. | | `config` | `ResolverConfig` | No | Configuration for the data provider. Use `getConfig` for config-based approach. | #### GetUserResolverRequest *** Request format used by config-based user resolver endpoints. | Property | Type | Required | Description | | ---------------- | ---------- | -------- | -------------------------- | | `organizationId` | `string` | Yes | ID of the organization | | `userIds` | `string[]` | Yes | Array of user IDs to fetch | #### AttachmentDataProvider *** | Property | Type | Required | Description | | -------- | --------------------------------------------------------------------------------------------------- | -------- | ----------------------------------- | | `save` | `(request: SaveAttachmentResolverRequest) => Promise>` | No | Function to save attachment data | | `delete` | `(request: DeleteAttachmentResolverRequest) => Promise>` | No | Function to delete attachment data | | `config` | `ResolverConfig` | No | Configuration for the data provider | #### SaveAttachmentResolverData *** | Property | Type | Required | Description | | -------- | -------- | -------- | --------------------------- | | `url` | `string` | Yes | URL of the saved attachment | #### UploadFileOptions *** | Property | Type | Required | Description | | ----------------------- | --------- | -------- | ------------------------------------------------------------------------------------------- | | `file` | `File` | Yes | File object to upload | | `useAttachmentResolver` | `boolean` | No | Whether to route upload through the attachment resolver | | `metadata` | `any` | No | Custom metadata to pass to the upload handler | | `attachmentScope` | `string` | No | Routes upload to the named `AttachmentDataProvider` scope (e.g., `'default'`, `'recorder'`) | #### RecorderAnnotationDataProvider *** | Property | Type | Required | Description | | -------------- | --------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `get` | `(request: GetRecorderResolverRequest) => Promise>>` | No | Function to fetch recorder annotation PII data | | `save` | `(request: SaveRecorderResolverRequest) => Promise>` | No | Function to save recorder annotation PII data | | `delete` | `(request: DeleteRecorderResolverRequest) => Promise>` | No | Function to delete recorder annotation PII data | | `config` | `ResolverConfig` | No | Configuration for the data provider. Supports `fieldsToRemove` to strip top-level custom fields from Velt's storage and restore them on read. | | `uploadChunks` | `boolean` | No | Whether to upload recording in chunks | | `storage` | `AttachmentDataProvider` | No | Storage provider for recording media files | #### NotificationDataProvider *** Provider for custom notification PII data. Only `notificationSource === 'custom'` notifications are routed through this resolver. | Property | Type | Required | Description | | -------- | ------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------ | | `get` | `(request: GetNotificationResolverRequest) => Promise>>` | No | Fetch notification data from your backend | | `delete` | `(request: DeleteNotificationResolverRequest) => Promise>` | No | Delete notification data from your backend | | `config` | [`NotificationResolverConfig`](#notificationresolverconfig) | No | Configuration for the data provider | #### NotificationResolverConfig *** | Property | Type | Required | Description | | ------------------- | --------------------------------------------------- | -------- | ----------------------------------------------- | | `resolveTimeout` | `number` | No | Timeout in milliseconds for resolver operations | | `getRetryConfig` | [`RetryConfig`](#retryconfig) | No | Retry configuration for get operations | | `deleteRetryConfig` | [`RetryConfig`](#retryconfig) | No | Retry configuration for delete operations | | `getConfig` | [`ResolverEndpointConfig`](#resolverendpointconfig) | No | Config-based endpoint for fetch operations | | `deleteConfig` | [`ResolverEndpointConfig`](#resolverendpointconfig) | No | Config-based endpoint for delete operations | #### GetNotificationResolverRequest *** | Property | Type | Required | Description | | ----------------- | ---------- | -------- | ---------------------------------- | | `organizationId` | `string` | Yes | ID of the organization | | `notificationIds` | `string[]` | Yes | Array of notification IDs to fetch | #### DeleteNotificationResolverRequest *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | -------------------------------- | | `notificationId` | `string` | Yes | ID of the notification to delete | | `organizationId` | `string` | Yes | ID of the organization | #### PartialNotification *** Partial notification data returned by the notification resolver. All fields are optional except `notificationId`. | Property | Type | Required | Description | | ------------------------------------ | ----------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------- | | `notificationId` | `string` | Yes | ID of the notification | | `displayHeadlineMessageTemplate` | `string` | No | Template string for the notification headline message | | `displayHeadlineMessageTemplateData` | `{ actionUser?: User; recipientUser?: User; actionMessage?: string; [key: string]: any }` | No | Data to populate the headline message template | | `displayBodyMessage` | `string` | No | Body message of the notification | | `displayBodyMessageTemplate` | `string` | No | Template string for the notification body message | | `displayBodyMessageTemplateData` | `{ [key: string]: any }` | No | Data to populate the body message template | | `notificationSourceData` | `any` | No | Custom source data for the notification | | `[key: string]` | `any` | No | Additional custom fields | #### GetRecorderResolverRequest *** | Property | Type | Required | Description | | ----------------------- | ---------- | -------- | ------------------------------------- | | `organizationId` | `string` | Yes | ID of the organization | | `recorderAnnotationIds` | `string[]` | No | Recorder annotation IDs to fetch | | `documentIds` | `string[]` | No | Document IDs to filter annotations by | #### SaveRecorderResolverRequest *** | Property | Type | Required | Description | | -------------------- | ------------------------------------------- | -------- | --------------------------------------------------------- | | `recorderAnnotation` | `Record` | Yes | Map of annotation IDs to partial recorder annotation data | | `event` | `ResolverActions` | No | Resolver action that triggered the save | | `metadata` | `BaseMetadata` | No | Additional metadata | #### SaveRecorderResolverData *** | Property | Type | Required | Description | | --------------- | -------------------- | -------- | -------------------------------------------------- | | `transcription` | `Transcription` | No | Updated transcription for the recording | | `attachment` | `Attachment \| null` | No | Primary attachment (deprecated; use `attachments`) | | `attachments` | `Attachment[]` | No | List of updated attachments for the recording | #### DeleteRecorderResolverRequest *** | Property | Type | Required | Description | | ---------------------- | ----------------- | -------- | ----------------------------------------- | | `recorderAnnotationId` | `string` | Yes | ID of the recorder annotation to delete | | `metadata` | `BaseMetadata` | No | Additional metadata | | `event` | `ResolverActions` | No | Resolver action that triggered the delete | #### PartialRecorderAnnotation *** | Property | Type | Required | Description | | ----------------------- | ------------------------------------------------------ | -------- | --------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the recorder annotation | | `metadata` | `BaseMetadata` | No | Additional metadata | | `from` | `User` | No | User who created the recorder annotation | | `transcription` | `Transcription` | No | Transcription of the recorded media | | `attachment` | `Attachment \| null` | No | Primary attachment (deprecated; use `attachments`) | | `attachments` | `Attachment[]` | No | List of attachments for the recording | | `chunkUrls` | `Record` | No | Map of chunk index to chunk URL for chunked uploads | | `recordingEditVersions` | `Record` | No | Map of edit version index to edit version data | | `[key: string]` | `any` | No | Additional custom fields | #### PartialRecorderAnnotationEditVersion *** | Property | Type | Required | Description | | --------------- | -------------------- | -------- | ----------------------------------------- | | `from` | `User` | No | User who created this edit version | | `attachment` | `Attachment \| null` | No | Attachment for this edit version | | `attachments` | `Attachment[]` | No | List of attachments for this edit version | | `transcription` | `Transcription` | No | Transcription for this edit version | #### PartialRecorderAnnotationResult *** | Property | Type | Required | Description | | -------------- | --------------------------------------------------- | -------- | --------------------------------------------- | | `strippedData` | `Record \| null` | Yes | Annotation data with PII stripped | | `originalData` | `RecorderAnnotation \| null` | Yes | Original annotation data before PII stripping | | `eventType` | `ResolverActions` | No | Resolver action that produced this result | #### ActivityAnnotationDataProvider *** | Property | Type | Required | Description | | -------- | ----------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------ | | `get` | `(request: GetActivityResolverRequest) => Promise>>` | No | Function to fetch activity PII from your backend for re-hydration | | `save` | `(request: SaveActivityResolverRequest) => Promise>` | No | Function to store activity PII fields stripped before Velt writes to its backend | | `config` | `ResolverConfig` | No | Configuration for the data provider. Supports `resolveTimeout` and `fieldsToRemove`. | #### GetActivityResolverRequest *** | Property | Type | Required | Description | | ---------------- | ---------- | -------- | ------------------------------------------ | | `organizationId` | `string` | No | ID of the organization | | `activityIds` | `string[]` | No | Activity record IDs to fetch PII for | | `documentIds` | `string[]` | No | Document IDs to filter activity records by | #### SaveActivityResolverRequest *** | Property | Type | Required | Description | | ---------- | --------------------------------------- | -------- | ------------------------------------------------------- | | `activity` | `Record` | Yes | Map of activity record IDs to their stripped PII fields | | `event` | `string` | No | Resolver action that triggered the save | | `metadata` | `BaseMetadata` | No | Additional metadata | #### PartialActivityRecord *** Stripped activity record containing only PII fields routed to your data provider. | Property | Type | Required | Description | | ---------------------------- | ------------------------- | -------- | -------------------------------------------------------- | | `id` | `string` | Yes | Activity record ID | | `metadata` | `BaseMetadata` | No | Additional metadata attached to the activity record | | `changes` | `ActivityChanges` | No | Change snapshot captured at the time of the activity | | `entityData` | `unknown` | No | Feature-specific entity snapshot (e.g., comment body) | | `entityTargetData` | `unknown` | No | Target entity snapshot (e.g., the element commented on) | | `displayMessageTemplateData` | `Record` | No | Template variable values | | `[key: string]` | `any` | No | Additional custom fields configured via `fieldsToRemove` | #### AnonymousUserDataProvider *** | Property | Type | Required | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------ | | `resolveUserIdsByEmail` | `(request:` [`ResolveUserIdsByEmailRequest`](#resolveuseridsbyemailrequest)`) => Promise>>` | Yes | Callback to resolve email addresses to user IDs. | | `config` | [`AnonymousUserDataProviderConfig`](#anonymoususerdataproviderconfig) | No | Optional configuration for timeout and retry. | #### AnonymousUserDataProviderConfig *** | Property | Type | Required | Description | | ---------------- | ----------------------------- | -------- | ------------------------------------------------------- | | `resolveTimeout` | `number` | No | Timeout in milliseconds for the resolve call. | | `getRetryConfig` | [`RetryConfig`](#retryconfig) | No | Retry configuration with `retryCount` and `retryDelay`. | #### ResolveUserIdsByEmailRequest *** | Property | Type | Required | Description | | ---------------- | ---------- | -------- | ------------------------------------ | | `organizationId` | `string` | Yes | The organization ID. | | `documentId` | `string` | No | The document ID. | | `folderId` | `string` | No | The folder ID. | | `emails` | `string[]` | Yes | Array of email addresses to resolve. | # Presence #### PresenceUser *** | Property | Type | Required | Description | | ------------------ | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- | | `userId` | `string` | Yes | Unique user identifier | | `name` | `string` | No | User's full name (Default: Random avatar name) | | `email` | `string` | No | User's email address | | `photoUrl` | `string` | No | User's display picture URL (Default: Random avatar image) | | `onlineStatus` | `string` | Yes | Online status (active, away, offline) (Auto generated) | | `color` | `string` | No | Assigned color for the user (Auto generated) | | `timestamp` | `any` | Yes | Server Timestamp | | `type` | `string` | No | User type | | `selections` | `any` | No | User selections | | `documentParamsId` | `number \| null` | No | Deprecated unique document params ID | | `documentParams` | `object \| null` | No | Deprecated document params | | `locationId` | `number \| null` | No | Unique location ID | | `location` | `Location \| null` | No | Location of user on sub document | | `isReadOnly` | `boolean` | No | Indicates if user is readonly | | `isAnonymous` | `boolean` | No | If user can only view comments (Anonymous) | | `pageInfo` | `PageInfo` | Yes | Information about the page | | `isUserIdle` | `boolean` | No | Indicates if user is idle. This is based on the `inactivityTime` configured in the Presence feature. (Auto generated) | | `isTabAway` | `boolean` | No | Indicates if user's tab is unfocused. (Auto generated) | | `localOnly` | `boolean` | No | Whether this custom user is local-only (not persisted to DB). Only applicable to users added via addUser API. | | `initial` | `string` | No | Avatar initial. Defaults to first character of name, uppercased. Only applicable to users added via addUser API. | #### PresenceUserStateChangeEvent *** This event object is emitted when a user's online status changes to online. | Property | Type | Required | Description | | -------- | -------------- | -------- | ----------------------------------------------------------------------- | | `user` | `PresenceUser` | Yes | The current user's Presence object. | | `state` | `string` | Yes | The new presence state of the user (e.g., `online`, `offline`, `away`). | #### ENUMs | Enum Name | Event Type | Description | | ------------------- | ----------------- | ------------------------------------------------------------------------- | | `USER_STATE_CHANGE` | `userStateChange` | Triggered when a user's online status changes to online, offline, or away | #### PresenceRequestQuery *** | Property | Type | Required | Description | | ---------------- | ---------- | -------- | ---------------------------------------------------------------------------- | | `documentId` | `string` | No | ID of the document to query presence for. | | `organizationId` | `string` | No | ID of the organization to query presence for. | | `statuses` | `string[]` | No | Array of user statuses to filter by (e.g., `['online', 'away', 'offline']`). | #### GetPresenceDataResponse *** | Property | Type | Required | Description | | -------- | ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------- | | `data` | `PresenceUser[] \| null` | Yes | Array of [PresenceUser](/api-reference/sdk/models/data-models#presenceuser) objects. `null` while loading. | #### HeartbeatConfig *** | Property | Type | Required | Description | | -------- | -------- | -------- | ----------------------------------------------------------------------------------------------------- | | `userId` | `string` | No | User ID to retrieve heartbeat data for. If not provided, returns heartbeat data for the current user. | #### GetHeartbeatResponse *** | Property | Type | Required | Description | | -------- | --------------------- | -------- | ----------------------------------------------------------------------------------------------- | | `data` | `Heartbeat[] \| null` | Yes | Array of heartbeat data for the specified user. Returns null if no heartbeat data is available. | # Webhooks #### WebhookV2Payload *** | Property | Type | Required | Description | | -------------------------------------- | ------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------- | | `event` | `string` | Yes | The event type that triggered the webhook. | | `actionType` | `string` | Yes | The specific action that occurred. | | `source` | `string` | Yes | The source of the event. | | `data` | `CommentPayload \| HuddlePayload \| CRDTPayload \| RecorderPayload` | Yes | The payload data containing event-specific information. | | `webhookId` | `string` | Yes | Unique identifier for the webhook. | | `usersOrganizationNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user org-level notification preferences keyed by userId. | | `usersDocumentNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user document-level notification preferences keyed by userId. | #### WebhookV2PayloadEncoded *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------------- | | `encodedPayload` | `string` | Yes | Base64 encoded webhook payload. | #### WebhookV2PayloadEncrypted *** | Property | Type | Required | Description | | --------------- | -------- | -------- | ------------------------------------- | | `encryptedData` | `string` | Yes | Encrypted webhook data. | | `encryptedKey` | `string` | Yes | Encrypted encryption key. | | `iv` | `string` | Yes | Initialization vector for decryption. | #### CommentPayload *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ---------------------------------------------------------- | | `commentAnnotation` | `CommentAnnotation` | No | The comment annotation associated with the event. | | `targetComment` | `Comment` | No | The target comment for the event. | | `actionUser` | `User` | No | The user who performed the action. | | `metadata` | `Metadata` | No | Additional metadata about the event context. | | `oldStatus` | `CommentStatus` | No | Previous status of the comment (for status change events). | | `newStatus` | `CommentStatus` | No | New status of the comment (for status change events). | | `newPriority` | `CommentPriority` | No | New priority of the comment (for priority change events). | #### HuddlePayload *** | Property | Type | Required | Description | | ------------ | ---------- | -------- | -------------------------------------------- | | `actionUser` | `User` | No | The user who performed the action. | | `metadata` | `Metadata` | No | Additional metadata about the event context. | #### CRDTPayload *** | Property | Type | Required | Description | | ------------------------ | ---------------- | -------- | ---------------------------------------------------------------------------- | | `actionUser` | `User` | No | The user who performed the action. | | `metadata` | `Metadata` | No | Additional metadata about the event context. | | `crdtData` | `object` | Yes | Contains the CRDT data and update information. | | `crdtData.id` | `string` | Yes | The editor/store ID for the CRDT instance. | | `crdtData.data` | `unknown` | Yes | The CRDT data. Can be any supported type: array, map, text, xml, or xmltext. | | `crdtData.lastUpdatedBy` | `string` | Yes | User ID who made the update. | | `crdtData.sessionId` | `string \| null` | No | Session ID if available. | | `crdtData.lastUpdate` | `string` | Yes | Timestamp of the last update. | #### RecorderPayload *** Payload delivered with `recorder.done` webhook events. | Property | Type | Required | Description | | ------------------- | --------------------------------------------------------- | -------- | ------------------------------------------------ | | `actionUser` | `User` | No | The user who triggered the recording action. | | `metadata` | `MetadataExternal` | No | Additional metadata about the event context. | | `recorderId` | `string` | No | The ID of the recorder instance. | | `from` | `User \| null` | No | The user who created the recording. | | `assets` | [`RecorderDataAsset[]`](#recorderdataasset) | No | The latest processed assets for the recording. | | `assetsAllVersions` | [`RecorderDataAsset[]`](#recorderdataasset) | No | All historical asset versions for the recording. | | `transcription` | [`RecorderDataTranscription`](#recorderdatatranscription) | No | Top-level transcription data for the recording. | #### RecorderDataAsset *** | Property | Type | Required | Description | | ----------------- | --------------------------------------------------------- | -------- | ------------------------------------------- | | `version` | `number` | No | Asset version number. | | `url` | `string` | Yes | Download URL for the recording asset. | | `mimeType` | `string` | No | MIME type of the asset (e.g., `video/mp4`). | | `fileName` | `string` | No | File name of the asset. | | `fileSizeInBytes` | `number` | No | File size in bytes. | | `fileFormat` | `'mp3' \| 'mp4' \| 'webm'` | No | File format of the asset. | | `thumbnailUrl` | `string` | No | URL for the recording thumbnail. | | `transcription` | [`RecorderDataTranscription`](#recorderdatatranscription) | Yes | Transcription data for this asset version. | #### RecorderDataTranscription *** | Property | Type | Required | Description | | -------------------- | ------------------------------------------------------------------- | -------- | ---------------------------------------------- | | `transcriptSegments` | [`RecorderDataTranscriptSegment[]`](#recorderdatatranscriptsegment) | No | Time-coded transcript segments. | | `vttFileUrl` | `string` | No | URL of the VTT subtitle file. | | `contentSummary` | `string` | No | AI-generated summary of the recording content. | #### RecorderDataTranscriptSegment *** | Property | Type | Required | Description | | -------------------- | -------- | -------- | ----------------------------------------- | | `startTime` | `string` | Yes | Segment start time as a formatted string. | | `endTime` | `string` | Yes | Segment end time as a formatted string. | | `startTimeInSeconds` | `number` | Yes | Segment start time in seconds. | | `endTimeInSeconds` | `number` | Yes | Segment end time in seconds. | | `text` | `string` | Yes | Transcript text for this segment. | #### RecorderTrigger *** Controls which Recorder webhook events fire for a workspace. Set via `triggers.recorder` in your workspace configuration. | Property | Type | Required | Description | | -------- | --------- | -------- | ------------------------------------------------------------------------------------- | | `done` | `boolean` | No | Whether to fire the `recorder.done` event when a recording finishes. Default: `true`. | #### TriggersConfig *** Controls which webhook events fire for a workspace. Each property maps to a feature-specific trigger configuration. | Property | Type | Required | Description | | ---------- | ------------------------------------- | -------- | -------------------------------------------------- | | `comment` | [`CommentTrigger`](#commenttrigger) | No | Trigger configuration for comment webhook events. | | `huddle` | [`HuddleTrigger`](#huddletrigger) | No | Trigger configuration for huddle webhook events. | | `recorder` | [`RecorderTrigger`](#recordertrigger) | No | Trigger configuration for recorder webhook events. | #### CommentTrigger *** Controls which Comment webhook events fire for a workspace. | Property | Type | Required | Description | | -------- | --------- | -------- | ------------------------------------------------------- | | `add` | `boolean` | No | Whether to fire comment add events. Default: `true`. | | `update` | `boolean` | No | Whether to fire comment update events. Default: `true`. | | `delete` | `boolean` | No | Whether to fire comment delete events. Default: `true`. | #### HuddleTrigger *** Controls which Huddle webhook events fire for a workspace. | Property | Type | Required | Description | | -------- | --------- | -------- | ------------------------------------------------------ | | `add` | `boolean` | No | Whether to fire huddle add events. Default: `true`. | | `update` | `boolean` | No | Whether to fire huddle update events. Default: `true`. | | `delete` | `boolean` | No | Whether to fire huddle delete events. Default: `true`. | #### Attendee *** Extends [`User`](#user) with huddle-specific state. Used in cursor and huddle wireframe configs (e.g. `componentConfig.attendeesByUserId`, `componentConfig.huddleAttendees`). | Property | Type | Required | Description | | -------------------- | --------------------------------------------------------------------------- | -------- | ------------------------------------------------------- | | `state` | `{ audioState: boolean, videoState: boolean, screenSharingState: boolean }` | No | Current media state of the attendee. | | `timestamp` | `number` | No | Timestamp of the attendee record. | | `initialHuddleMode` | `{ audioState?: boolean, videoState?: boolean, screenSharing?: boolean }` | No | Media state the attendee joined with. | | `streamMetadata` | `any` | No | Metadata attached to the attendee's media stream. | | `initialHuddleType` | `'audio' \| 'video' \| 'presentation'` | No | The huddle type the attendee initially joined. | | `huddleOnCursorMode` | `boolean` | No | Whether the attendee has huddle-on-cursor mode enabled. | `Attendee` inherits all properties from [`User`](#user) (e.g. `userId`, `name`, `photoUrl`, `email`, `color`). #### WebhookV1Payload *** All basic webhook payloads share these common fields: | Property | Type | Required | Description | | -------------------------------------- | ------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- | | `webhookId` | `string` | Yes | Unique identifier for the webhook. | | `actionType` | `string` | Yes | The specific action that occurred in the event. | | `notificationSource` | `string` | Yes | Source of the notification: `comment`, `huddle`, `crdt`, or `recorder`. | | `actionUser` | `User` | No | The user who performed the action. | | `metadata` | `Metadata` | No | Additional metadata providing context for the event. | | `platform` | `'sdk'` | No | Set to `'sdk'` if the event originated from SDK actions. | | `usersOrganizationNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user org-level notification preferences keyed by userId. | | `usersDocumentNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user document-level notification preferences keyed by userId. | #### WebhookV1PayloadEncoded *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------------- | | `encodedPayload` | `string` | Yes | Base64 encoded webhook payload. | #### WebhookV1PayloadEncrypted *** | Property | Type | Required | Description | | --------------- | -------- | -------- | ------------------------------------- | | `encryptedData` | `string` | Yes | Encrypted webhook data. | | `encryptedKey` | `string` | Yes | Encrypted encryption key. | | `iv` | `string` | Yes | Initialization vector for decryption. | **Comment Basic Webhook Payload** Additional fields present when `notificationSource` is `comment`: | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------- | | `commentAnnotation` | `CommentAnnotation` | Yes | The comment annotation associated with the event. | | `targetComment` | `Comment` | No | The target comment. Not present for annotation-level events (e.g., resolve, delete thread). | | `newPriority` | `CommentPriority` | No | New priority. Present on `priorityChanged` events. | | `oldStatus` | `CommentStatus` | No | Previous status. Present on `statusChanged` events. | | `newStatus` | `CommentStatus` | No | New status. Present on `statusChanged` events. | | `assigned` | `boolean` | No | Whether the comment is assigned. Present on `assigned` events. | **Huddle Basic Webhook Payload** No additional fields beyond the common fields when `notificationSource` is `huddle`. **CRDT Basic Webhook Payload** Additional fields present when `notificationSource` is `crdt`: | Property | Type | Required | Description | | ------------------------ | ---------------- | -------- | ---------------------------------------------------------------------------- | | `crdtData` | `object` | Yes | Contains the CRDT data and update information. | | `crdtData.id` | `string` | Yes | The editor/store ID for the CRDT instance. | | `crdtData.data` | `unknown` | Yes | The CRDT data. Can be any supported type: array, map, text, xml, or xmltext. | | `crdtData.lastUpdatedBy` | `string` | Yes | User ID who made the update. | | `crdtData.sessionId` | `string \| null` | No | Session ID if available. | | `crdtData.lastUpdate` | `string` | Yes | Timestamp of the last update. | | `accessDeniedUsers` | `array` | No | List of users denied access. | #### UserNotificationsConfig *** Per-user notification preferences included in webhook payloads when a notification config scope is active. Exactly one of the two fields is present per payload depending on whether org-level or document-level config is in use. | Property | Type | Required | Description | | -------------------------------------- | ------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------ | | `usersOrganizationNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user org-level notification preferences, keyed by userId. | | `usersDocumentNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user document-level notification preferences, keyed by userId. | #### NotificationChannelConfig *** Per-channel notification preference map for a single user. Keys are channel identifiers; values are the preference level for that channel. ```typescript theme={null} type NotificationChannelConfig = Record; ``` | Key (channel) | Value | Description | | ------------- | --------------------------- | ------------------------------------- | | `inbox` | `'ALL' \| 'MINE' \| 'NONE'` | In-app inbox notification preference. | | `email` | `'ALL' \| 'MINE' \| 'NONE'` | Email notification preference. | | Value | Description | | ------ | -------------------------------------------------------------------- | | `ALL` | Receive notifications for all activity. | | `MINE` | Receive notifications only for activity directly involving the user. | | `NONE` | Receive no notifications for this channel. | # Misc #### RequestOptions *** | Property | Type | Required | Description | | ------------ | -------- | -------- | ----------- | | `documentId` | `string` | No | Document ID | #### SelectedAnnotationsMap *** Map of currently selected annotations, keyed by `annotationId`. Used across multiple features (comments, arrows, recorders, tags, rewriters). | Property | Type | Required | Description | | ------------------------ | ----------------------------------------- | -------- | ---------------------------------------------------------------------------- | | `[annotationId: string]` | [`CommentAnnotation`](#commentannotation) | No | Maps annotation IDs to their CommentAnnotation objects. Truthy when selected | #### CommentSelectionChangeData *** | Property | Type | Required | Description | | ------------ | ------------------- | -------- | -------------------------------------- | | `selected` | `boolean` | Yes | Whether a comment is selected | | `annotation` | `CommentAnnotation` | Yes | Object data of the selected annotation | #### ContactListScopeForOrganizationUsers *** ```typescript theme={null} type ContactListScopeForOrganizationUsers = | 'all' | 'organization' | 'organizationUserGroup' | 'document' | 'folder'; ``` | String value | Description | | ------------------------- | ------------------------------ | | `'all'` | Show all contacts. | | `'organization'` | Show organization contacts. | | `'organizationUserGroup'` | Show organization user groups. | | `'document'` | Show document contacts. | | `'folder'` | Show folder contacts. | #### CursorUser *** | Property | Type | Required | Description | | -------------- | ------------------------ | -------- | --------------------------------------------------------------------------------------- | | `userId` | `string` | Yes | Unique user identifier that you use to identify your user. | | `name` | `string` | No | Your user's full name. Default: Random avatar name. | | `email` | `string` | No | Your user's email address. | | `photoUrl` | `string` | No | Your user's display picture URL. Default: Random avatar image. | | `comment` | `string` | No | Short comment that user can add to their live cursor. | | `onlineStatus` | `string` | Yes | User's online status (active, inactive, offline). Auto generated. | | `color` | `string` | No | A random color assigned to the user for the session, used on avatar border/live cursor. | | `timestamp` | `any` | Yes | Server Timestamp. | | `type` | `string` | No | User type. | | `locationId` | `number \| null` | No | Unique location id from provided location. | | `location` | `Location \| null` | No | Location to identify user on sub document. | | `position` | `CursorPosition \| null` | No | User's cursor position on their screen. | | `isReadOnly` | `boolean` | No | Indicates if user is readonly. | | `isAnonymous` | `boolean` | No | Indicates if user is anonymous and can only view comments. | #### CursorPosition *** | Property | Type | Required | Description | | ------------------ | -------- | -------- | --------------------------------------------------------------- | | `top` | `number` | Yes | Position top of cursor on viewer user's screen. | | `left` | `number` | Yes | Position left of cursor on viewer user's screen. | | `parentScaleX` | `number` | No | Scale factor of the parent element in X direction (transforms). | | `parentScaleY` | `number` | No | Scale factor of the parent element in Y direction (transforms). | | `transformContext` | `any` | No | Transform context information for handling transforms. | #### Selection *** | Property | Type | Required | Description | | ----------------- | ----------------------------------- | -------- | ---------------------------------------------------- | | `user` | `User` | No | User focused on specific element or text. | | `type` | `'focus' \| 'click' \| 'selection'` | No | Type of event through which the selection was fired. | | `targetElement` | `string \| null` | No | XPath of highlighted element. | | `targetTextRange` | `TargetTextRange \| null` | No | Selected text range to highlight. | | `pageInfo` | `PageInfo` | No | Page information where the selection occurred. | | `timestamp` | `number` | Yes | Timestamp when the selection was created. | #### UserIndicatorPosition *** ```typescript theme={null} type UserIndicatorPosition = 'start' | 'end'; ``` | String value | Description | | ------------ | ------------------------------------------------- | | `'start'` | Indicator anchored at the start of the selection. | | `'end'` | Indicator anchored at the end of the selection. | #### UserIndicatorType *** ```typescript theme={null} type UserIndicatorType = 'avatar' | 'label'; ``` | String value | Description | | ------------ | ---------------------------------------- | | `'avatar'` | Show the user's avatar on the indicator. | | `'label'` | Show the user's name label. | #### FlockOptions *** | Property | Type | Required | Description | | -------------------------- | ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `useHistoryAPI` | `boolean` | Yes | Indicates whether the application should use the HTML5 History API for navigation | | `onNavigate` | `(url: PageInfo) => void` | No | A callback function that is called when navigation occurs. It takes a `PageInfo` object as its argument, which contains details about the new page | | `disableDefaultNavigation` | `boolean` | Yes | If `true`, the application's default navigation handling is disabled, perhaps to be managed manually or by another system | | `darkMode` | `boolean` | Yes | A flag indicating whether the application should display in dark mode, a display preference that may be more comfortable for users in low-light conditions | #### Version *** | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------- | | `id` | string | Yes | Unique identifier for the version | | `name` | string | Yes | Name of the version | #### displayHeadlineMessageTemplateData *** | Property | Type | Required | Description | | --------------- | -------- | -------- | --------------------------------------- | | `actionUser` | `User` | No | The user who performed the action | | `recipientUser` | `User` | No | The user receiving the notification | | `actionMessage` | `string` | No | The message describing the action | | `project` | `string` | No | The project related to the notification | | `[key: string]` | `any` | No | Any additional custom properties | #### PageInfo *** | Property | Type | Required | Description | | ------------- | ----------------------------- | -------- | -------------------------------------- | | `url` | `string` | No | URL of the webpage | | `path` | `string` | No | Path of the webpage excluding base url | | `queryParams` | `string` | No | Query parameters of the page URL | | `baseUrl` | `string` | No | Base URL (domain) of a webpage | | `title` | `string` | No | Title of the webpage | | `arrowUrl` | `string` | No | Reference url of an arrow annotation | | `areaUrl` | `string` | No | Reference url of an area annotation | | `commentUrl` | `string` | No | Reference url of a comment annotation | | `tagUrl` | `string` | No | Reference url of a tag annotation | | `recorderUrl` | `string` | No | Reference url of a recorder annotation | | `screenWidth` | `number` | No | User's screen width. Auto generated. | | `deviceInfo` | [`IDeviceInfo`](#ideviceinfo) | No | Device information. Auto generated. | #### `getThumbnailTag` Method The `getThumbnailTag` method takes an optional `url` parameter and returns an HTML string. It creates an anchor tag linking to the `videoPlayerUrl` and embeds an image tag using either the provided `url`, `thumbnailWithPlayIconUrl`, or `thumbnailUrl` (in that order of preference). #### RewriterAnnotation *** | Property | Type | Required | Description | | ------------------------ | ----------------------- | -------- | ------------------------------------------------------------------------------------- | | `annotationId` | String | Yes | Unique identifier for the rewriter annotation, automatically generated. | | `from` | `User` | Yes | The user who created this rewriter annotation. | | `color` | String | No | Color used for the rewriter annotation. | | `lastUpdated` | Any | No | Timestamp when the rewriter annotation was last updated, automatically generated. | | `documentParamsId` | Number \| null | No | Unique document params ID, deprecated, use `locationId` instead. | | `documentParams` | `Location` \| null | No | Document params to identify user on sub document, deprecated, use `location` instead. | | `locationId` | Number \| null | No | Unique location ID generated from provided location. | | `location` | Location \| null | No | Set location to identify user on sub document. | | `type` | String | No | Type of annotation. | | `rewriterType` | String | Yes | Type of rewriter for the annotation, either 'generic' or 'copywriter'. | | `targetTextRange` | TargetTextRange \| null | No | Selected text range of rewriter annotation. | | `annotationIndex` | Number | No | Index of the current annotation in the list of annotations. | | `pageInfo` | `PageInfo` | No | Information about the page where the annotation is made. | | `selectedRewriterOption` | String | No | Selected rewriter option used in the annotation. | #### TextSelectedEvent *** Emitted by `rewriterElement.on('textSelected')` when the user selects text in a Rewriter-enabled region. | Property | Type | Required | Description | | ----------------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `selectionId` | `string` | Yes | Unique identifier for this selection instance. | | `text` | `string` | Yes | The raw text content of the user's selection. | | `targetTextRange` | `TargetTextRange` | Yes | DOM range describing the selected text position. Same type as [`RewriterAnnotation.targetTextRange`](#rewriterannotation). | #### RewriterAskAiRequest *** Request object for `rewriterElement.askAi()`. Proxies a text-generation call through Velt's backend. | Property | Type | Required | Description | | -------------- | --------------------- | -------- | --------------------------------------------------------------------------- | | `model` | [`AiModel`](#aimodel) | Yes | AI model identifier. Use a known string literal or any custom model string. | | `prompt` | `string` | Yes | Instruction or system prompt sent to the model. | | `selectedText` | `string` | Yes | The text the model should act on. | #### RewriterAskAiResponse *** Response from `rewriterElement.askAi()`. | Property | Type | Required | Description | | --------- | --------- | -------- | -------------------------------------------- | | `text` | `string` | Yes | Generated text returned by the AI model. | | `success` | `boolean` | Yes | Whether the request completed without error. | | `error` | `string` | No | Error message if `success` is `false`. | #### AiModel *** Open union type for AI model identifiers. Accepts any `OpenAiModel`, `AnthropicModel`, or `GeminiModel` string literal, or any arbitrary string for unlisted models. ```typescript theme={null} type AiModel = OpenAiModel | AnthropicModel | GeminiModel | (string & NonNullable); ``` #### OpenAiModel *** Known OpenAI model identifiers accepted by [`RewriterAskAiRequest`](#rewriteraskairequest). ```typescript theme={null} type OpenAiModel = | 'gpt-5.4' | 'gpt-5.4-pro' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-5' | 'gpt-4.1' | 'gpt-4o' | 'gpt-4o-mini' | 'gpt-4-turbo' | 'o3-pro' | 'o3' | 'o3-mini' | 'o4-mini'; ``` #### AnthropicModel *** Known Anthropic model identifiers accepted by [`RewriterAskAiRequest`](#rewriteraskairequest). ```typescript theme={null} type AnthropicModel = | 'claude-opus-4-6' | 'claude-sonnet-4-6' | 'claude-haiku-4-5' | 'claude-sonnet-4-5' | 'claude-opus-4-5' | 'claude-opus-4-1' | 'claude-sonnet-4-0' | 'claude-opus-4-0'; ``` #### GeminiModel *** Known Google Gemini model identifiers accepted by [`RewriterAskAiRequest`](#rewriteraskairequest). ```typescript theme={null} type GeminiModel = | 'gemini-3.1-pro-preview' | 'gemini-3-flash-preview' | 'gemini-3.1-flash-lite-preview' | 'gemini-2.5-flash' | 'gemini-2.5-flash-lite' | 'gemini-2.5-pro'; ``` #### RewriterReplaceTextRequest *** Request object for `rewriterElement.replaceText()`. | Property | Type | Required | Description | | -------- | ----------------------------------------- | -------- | ---------------------------------------------- | | `text` | `string` | Yes | Replacement text to insert into the DOM. | | `event` | [`TextSelectedEvent`](#textselectedevent) | Yes | The selection event that identifies the range. | #### RewriterReplaceTextResponse *** Response from `rewriterElement.replaceText()`. | Property | Type | Required | Description | | -------------- | --------- | -------- | -------------------------------------- | | `success` | `boolean` | Yes | Whether the replacement succeeded. | | `originalText` | `string` | Yes | The text that was replaced. | | `replacedText` | `string` | Yes | The text that was inserted. | | `error` | `string` | No | Error message if `success` is `false`. | #### RewriterAddCommentRequest *** Request object for `rewriterElement.addComment()`. | Property | Type | Required | Description | | -------- | ----------------------------------------- | -------- | -------------------------------------------------------- | | `text` | `string` | Yes | Initial comment body text. | | `event` | [`TextSelectedEvent`](#textselectedevent) | Yes | The selection event that anchors the comment annotation. | #### RewriterAddCommentResponse *** Response from `rewriterElement.addComment()`. | Property | Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------------- | | `success` | `boolean` | Yes | Whether the comment was created successfully. | | `annotationId` | `string` | No | ID of the created comment annotation. | | `commentText` | `string` | No | The text stored on the created comment. | | `error` | `string` | No | Error message if `success` is `false`. | #### RewriterEventTypesMap *** Maps Rewriter event action names to their corresponding event payload types. Used internally by the `on()` method to provide typed event subscriptions. | Property | Type | Required | Description | | -------------- | ----------------------------------------- | -------- | ----------------------------------------- | | `textSelected` | [`TextSelectedEvent`](#textselectedevent) | Yes | Payload emitted when a user selects text. | #### SyncVideoPlayer *** | Property | Type | Required | Description | | ------------------ | -------------------- | -------- | ----------------------------------------------------- | | `playerId` | String | No | The identifier for the video player instance. | | `src` | String | No | The source URL of the video. | | `sources` | String\[] | No | An array of source URLs for the video. | | `lastUpdated` | Number | No | The timestamp of when the player was last updated. | | `lastUpdatedBy` | `User` | No | The user who last updated the player. | | `lastUpdatedEvent` | String | No | The name of the event that triggered the last update. | | `playerState` | SyncVideoPlayerState | Yes | The state object of the video player. | #### SyncVideoPlayerState *** | Property | Type | Required | Description | | ------------- | ------- | -------- | -------------------------------------------- | | `playing` | Boolean | No | Indicates if the video is currently playing. | | `currentTime` | Number | No | The current playback time of the video. | | `muted` | Boolean | No | Indicates if the video is muted. | | `volume` | Number | No | The volume level of the video. | | `speed` | Number | No | The playback rate of the video. | #### Toast *** | Property | Type | Required | Default Value | Description | | ---------- | -------------------- | -------- | ------------- | ------------------------------------------------------------------------ | | `id` | Number | No | None | A unique identifier for the toast notification. | | `message` | String | Yes | None | The message content displayed in the toast notification. | | `type` | 'success' \| 'error' | Yes | None | The type of toast notification, indicating success or error. | | `duration` | Number | No | 3000 | The length of time the toast notification is displayed, in milliseconds. | #### Transcription *** | Property | Type | Required | Description | | ---------------------- | ------ | -------- | ----------------------------------------------------- | | `from` | User | Yes | The user who created the transcription. | | `lastUpdated` | Number | No | Timestamp of when the transcription was last updated. | | `srtBucketPath` | String | No | Bucket path of the SRT file. | | `srtUrl` | String | No | URL to the SRT format transcription file. | | `transcriptedText` | String | No | The text that has been transcribed. | | `transcriptionLatency` | Number | No | Time taken in ms to transcribe the recording. | | `vttBucketPath` | String | No | Bucket path of the VTT file. | | `vttUrl` | String | No | URL to the VTT format transcription file. | #### User *** | Property | Type | Required | Description | | ---------------- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | `userId` | string | Yes | Unique user identifier used to identify your user. | | `name` | string | No | The full name of your user. Defaults to a random avatar name if not provided. | | `photoUrl` | string | No | The display picture URL of your user. Defaults to a random avatar image if not provided. | | `email` | string | No | Required for sending email or Slack notifications to users about comments and mentions. | | `plan` | string | No | The product plan the user is on. | | `organizationId` | string | Yes | organizationId to which the user belongs. | | `color` | string | No | A color assigned to the user for the current session, used for avatar border, live cursor, selection etc. | | `textColor` | string | No | Used in the text color of the user's intial when photoUrl is not present. | | `type` | string | No | The type of user. | | `isReadOnly` | boolean | No | Indicates if the user has read-only access. | | `isAnonymous` | boolean | No | Indicates if the user is anonymous and can only view comments. | | `isGuest` | boolean | No | Indicates if the user is a guest. | | `isAdmin` | boolean | No | Use this to set the user as an admin. You also need to ensure that the jwt token you generate also has this property set to true. | | `groupId` | string | No | \[DEPRECATED] A domain name or identifier used to cluster a group of users who work together. | | `clientGroupId` | string | No | \[DEPRECATED] The original groupId provided by the user. | | `initial` | string | No | First letter of the user's first name. | | `accessRole` | "viewer" \| "editor" | No | Optional access role for this resource. Allowed values: “viewer” \| “editor”. Default: "editor". | **Access Control** - Set `accessRole` to `viewer` (read-only) or `editor` (read/write) on each resource to define the user's capabilities for that resource. - `accessRole` can only be set via the v2 Users and Auth Permissions REST APIs. Frontend SDK methods do not accept or change `accessRole`. - Relevant endpoints: `/v2/users/add`, `/v2/users/update`, `/v2/auth/permissions/add`, `/v2/auth/generate_token`. - See the [Access Control overview](/key-concepts/overview#access-control) for concepts and detailed guidance. #### Attendee *** Extends [`User`](#user) with huddle-specific state. Used by `componentConfig.huddleAttendees`, `componentConfig.attendee` (per-tile), and `componentConfig.screenSharing.attendee`. | Property | Type | Required | Description | | -------------------- | --------------------------------------------------------------------------- | -------- | ---------------------------------------------------------- | | *...User fields* | | | All properties from [`User`](#user) are inherited. | | `state` | `{ audioState: boolean, videoState: boolean, screenSharingState: boolean }` | No | Attendee's current audio, video, and screen-sharing state. | | `timestamp` | `number` | No | Timestamp of when the attendee joined the huddle. | | `initialHuddleMode` | `{ audioState?: boolean, videoState?: boolean, screenSharing?: boolean }` | No | The initial huddle mode requested by the attendee on join. | | `initialHuddleType` | `'audio' \| 'video' \| 'presentation'` | No | The huddle type the attendee joined with. | | `huddleOnCursorMode` | `boolean` | No | Whether cursor-mode huddle is active for this attendee. | #### HuddleMessage *** A text message sent within a huddle's in-call chat panel (``). | Property | Type | Required | Description | | ----------- | --------------- | -------- | ------------------------------ | | `id` | `number` | Yes | Unique message identifier. | | `message` | `string` | No | The message text content. | | `timestamp` | `number` | No | Timestamp of when it was sent. | | `from` | [`User`](#user) | No | The user who sent the message. | #### UserContact *** A user object in a contact-selection context, such as autocomplete panels and assignment pickers. Shares the same shape as [`User`](#user). #### UserContactSelectedPayload *** | Property | Type | Required | Description | | ----------------------- | ----------------------------- | -------- | ------------------------------------- | | `contact` | [`UserContact`](#usercontact) | Yes | Selected user contact details. | | `isOrganizationContact` | boolean | Yes | Is user part of organization contact. | | `isDocumentContact` | boolean | Yes | Is user part of document contact. | | `documentAccessType` | string | Yes | Document access type. | #### UserContactUs *** | Property | Type | Required | Description | | ------------- | ------------------------ | -------- | ------------------------------------------------ | | `id` | string | No | Unique identifier of the feedback. | | `apiKey` | string \| null | No | API key of the client. | | `emailId` | string | No | Email address of the feedback provider. | | `message` | string | No | Content of the user's feedback message. | | `from` | User \| null | No | User who submitted the feedback. | | `lastUpdated` | any | No | Timestamp of when the feedback was last updated. | | `metadata` | DocumentMetadata \| null | No | Metadata associated with the document. | | `pageInfo` | PageInfo | No | Information about the user's current page. | #### UserFeedback *** | Property | Type | Required | Description | | ------------- | ------------------------ | -------- | ------------------------------------------------ | | `id` | string | No | Unique identifier of the feedback. | | `apiKey` | string \| null | No | API key of the client. | | `emailId` | string | No | Email address of the feedback provider. | | `message` | string | No | Content of the user's feedback message. | | `from` | User \| null | No | User who submitted the feedback. | | `lastUpdated` | any | No | Timestamp of when the feedback was last updated. | | `metadata` | DocumentMetadata \| null | No | Metadata associated with the document. | | `pageInfo` | PageInfo | No | Information about the user's current page. | #### UnreadCommentsCount *** | Property | Type | Required | Description | | -------- | -------- | -------- | ----------------------------------------- | | `count` | `number` | Yes | The number of unread comments or threads. | #### UserGroup *** | Property | Type | Required | Description | | ----------- | -------- | -------- | ---------------------------------------- | | `groupId` | `string` | Yes | Unique identifier for the user group | | `groupName` | `string` | Yes | Display name of the user group | | `users` | `User[]` | No | Array of users that belong to this group | #### VeltResetButtonStateConfig *** | Property | Type | Required | Description | | -------- | -------- | -------- | ------------------------------------------------------------------------------- | | `id` | `string` | No | The ID of the button to reset. If not provided, resets all buttons | | `group` | `string` | No | The group ID of buttons to reset. If not provided, resets buttons in all groups | #### VeltAuthProvider *** | Property | Type | Required | Description | | --------------- | ----------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- | | `user` | `User` | Yes | The user object to authenticate. | | `options` | `Options` | No | Additional options for authentication (e.g., `authToken`, `forceReset`). | | `retryConfig` | `{ retryCount?: number; retryDelay?: number; }` | No | Configuration for retrying token generation (number of retries and delay in ms). | | `generateToken` | `() => Promise` | No | Async function to generate a Velt JWT token. Called automatically when a token is required. | #### AuthRetryConfig *** | Property | Type | Required | Description | | ------------ | -------- | -------- | ----------------------------------------------------- | | `retryCount` | `number` | No | Number of times to retry token generation on failure. | | `retryDelay` | `number` | No | Delay in milliseconds between retry attempts. | #### RevokeAccessOn *** Configuration for automatic access revocation triggers. | Property | Type | Required | Description | | -------------------------- | ----------------------------------------- | -------- | -------------------------------------------------------------------------------------- | | `type` | [RevokeAccessOnType](#revokeaccessontype) | Yes | Type of trigger that will revoke access. Options: `document_unset` or `user_logout` | | `revokeOrganizationAccess` | `boolean` | No | Whether to also revoke organization-level permissions when triggered. Default: `false` | #### RevokeAccessOnType *** String-literal union specifying when to automatically revoke permissions. ```typescript theme={null} type RevokeAccessOnType = 'document_unset' | 'user_logout'; ``` | String value | Description | | ------------------ | --------------------------------------------------------- | | `'document_unset'` | Revoke access when the user unsets or leaves a document. | | `'user_logout'` | Revoke access when the user logs out of the organization. | #### PermissionSource *** String-literal union identifying which SDK action triggered the permission check. This helps debug and trace permission request origins. | String value | Description | | ------------------------------- | --------------------------------------------------------------------------- | | `'setDocuments'` | Permission check triggered by `setDocuments()`. | | `'identify'` | Permission check triggered by `identify()`. | | `'getNotifications'` | Permission check triggered by notification fetching. | | `'setNotifications'` | Permission check triggered by notification settings. | | `'revokeAccessOnUserLogout'` | Permission check triggered while revoking access after user logout. | | `'revokeAccessOnDocumentUnset'` | Permission check triggered while revoking access after a document is unset. | #### PermissionResourceType *** String-literal union defining the resources that can be validated through Permission Provider. ```typescript theme={null} type PermissionResourceType = | 'folder' | 'document' | 'organization' | 'context'; ``` | String value | Description | | ---------------- | ----------------------------------------------------------------- | | `'folder'` | Folder-level resource permissions. | | `'document'` | Document-level resource permissions. | | `'organization'` | Organization-level resource permissions. | | `'context'` | Context-based resource permissions when `isContextEnabled: true`. | #### VeltPermissionProvider *** Configuration interface for Permission Provider. Velt validates access requests in real-time by querying your backend endpoint configured in the [Velt Console](https://console.velt.dev). The SDK automatically handles permission caching, validation, and synchronization. | Property | Type | Required | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `isContextEnabled` | `boolean` | No | Enable context-based permission requests. When enabled, the backend receives individual permission requests for each context value when using context filtering. Default: `false`. Added in v4.5.8-beta.4. | | `retryConfig` | [AuthRetryConfig](#authretryconfig) | No | Configuration for retrying failed permission requests. Defaults to 3 retries with 2000ms delay. | | `forceRefresh` | `boolean` | No | Set to `true` if access control changes frequently. Forces re-validation on each access check in the current session. Default: `false` | | `revokeAccessOn` | [RevokeAccessOn\[\]](#revokeaccesson) | No | Configure automatic access revocation triggers. Revokes permissions when specified events occur (e.g., document unset or user logout). | | `dev` | `boolean` | No | Opt-in: resolve permissions in the browser for local testing. Honored only for dev/test API keys; production keys always use the server-side provider. Default: `false`. | | `endpointConfig` | [ResolverEndpointConfig](#resolverendpointconfig) | No | URL resolver for the dev resolver. SDK POSTs `{ data: { requests:` [PermissionQuery\[\]](#permissionquery) `} }` to the URL. Supports static or async headers and optional `credentials` through `ResolverEndpointConfig`. Takes precedence over `resolvePermissions`. | | `resolvePermissions` | `(request:` [PermissionResolverRequest](#permissionresolverrequest)`) => Promise<`[PermissionResult\[\]](#permissionresult) `\|` [ResolverResponse](#resolverresponse)`>` | No | In-browser callback resolver. Invoked with the same request envelope as the server-side provider. | | `resolveTimeout` | `number` | No | Per-call deadline in milliseconds for the dev resolver. Default: `60000`. | The dev resolver fails closed: resolver errors, timeouts, and malformed payloads all deny access. When both are set, `endpointConfig.url` takes precedence over `resolvePermissions`. A one-shot `console.warn` fires when the dev resolver is active or when `dev: true` is set without a usable resolver. #### PermissionQuery *** Request structure for permission queries sent to the Permission Provider. | Property | Type | Required | Description | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userId` | `string` | Yes | ID of the user requesting access to the resource. | | `resource` | `{ type:` [PermissionResourceType](#permissionresourcetype)`; id: string; source:` [PermissionSource](#permissionsource)`; organizationId: string; context?:` [Context](#context)`; parentFolderId?: string }` | Yes | Resource the user is requesting access to. The `type` uses [`PermissionResourceType`](#permissionresourcetype). The `source` field identifies which SDK method triggered the permission check. The optional `context` field is present only when `isContextEnabled: true` and contains context values set during setDocuments. Includes `organizationId` for context. The optional `parentFolderId` field is set when the document was created via `setDocuments()` with a `folderId` option — it forwards the folder context through the permission request so the document is created and attached to its parent folder. | #### PermissionResolverRequest *** Request envelope passed to dev permission resolvers ([`resolvePermissions`](#veltpermissionprovider)). Byte-identical to the server-side Real-Time Permission Provider contract, so an existing `/api/check-permissions` handler works unchanged from either caller. | Property | Type | Required | Description | | --------------- | --------------------------------------- | -------- | -------------------------------------------------- | | `data.requests` | [PermissionQuery\[\]](#permissionquery) | Yes | Permission queries to resolve in a single request. | #### PermissionResult *** Individual permission decision for a user's access to a specific resource. | Property | Type | Required | Description | | ---------------- | ----------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- | | `userId` | `string` | Yes | Unique identifier of the user requesting access. | | `resourceId` | `string` | Yes | Unique identifier of the resource being accessed. | | `type` | [PermissionResourceType](#permissionresourcetype) | Yes | Type of resource being accessed. Can be `folder`, `document`, `organization`, or `context`. | | `organizationId` | `string` | Yes | Organization ID associated with the resource. | | `accessRole` | [UserPermissionAccessRole](#userpermissionaccessrole) | No | Access role granted to the user for this resource. | | `expiresAt` | `number` | No | Unix timestamp (in milliseconds) when the permission expires. | | `hasAccess` | `boolean` | Yes | Whether the user has access to the requested resource. | #### SignatureResult *** Response structure returned from the [Generate Signature API](/api-reference/rest-apis/v2/auth/generate-signature). | Property | Type | Required | Description | | ----------------------- | -------- | -------- | ------------------------------------------- | | `result.status` | `string` | Yes | Status of the response. Always `"success"`. | | `result.message` | `string` | Yes | Success message. | | `result.data.signature` | `string` | Yes | Generated authorization signature string. | **Example:** ```json theme={null} { "result": { "status": "success", "message": "Signature generated successfully.", "data": { "signature": "03638f2191bf59c0e536e5b31cbde86df5f44b03fc8e82ee9a8bed7eb324f252" } } } ``` #### PermissionData *** Individual permission decision for a user-resource pair. | Property | Type | Required | Description | | ------------ | ------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `userId` | `string` | Yes | ID of the user this permission applies to. | | `resourceId` | `string` | Yes | ID of the resource (document, folder, or organization). | | `type` | `'document' \| 'folder' \| 'organization'` | Yes | Type of the resource. | | `hasAccess` | `boolean` | Yes | Whether the user has access to the resource. | | `accessRole` | `'viewer' \| 'editor'` | No | Access role for the user. Only applicable for document resources. `viewer` can view and comment, `editor` can edit content. | | `expiresAt` | `number` | No | UTC timestamp in milliseconds when this permission expires. Velt will revalidate access after expiration. | #### Context *** The `Context` interface is used in Permission Provider backend requests for context-based permission validation. Each context value is sent as an individual permission request. | Property | Type | Required | Description | | -------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `access` | `{ [key: string]: string \| number }` | Yes | Key-value pairs for context-based permissions. Keys are custom field names, values are single strings or numbers representing the specific context value being validated. | **Usage:** The `Context` interface is used in: * Backend Permission Provider requests when `isContextEnabled: true` * Each context value from frontend methods triggers a separate permission request with this format **Integration with Permission Provider:** When you enable context-based permissions (`isContextEnabled: true`), Velt automatically converts array values from [`SetDocumentsContext`](#setdocumentscontext) into individual permission requests using the `Context` interface format. #### SetDocumentsContext *** The `SetDocumentsContext` interface is used for filtering comments and notifications based on custom context fields when calling frontend SDK methods. This enables precise filtering based on your application's data model. | Property | Type | Required | Description | | -------- | -------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `access` | `{ [key: string]: Array }` | Yes | Key-value pairs for filtering. Keys are custom field names, values are arrays of strings or numbers to filter by. Multiple values in an array use OR logic. | **Usage:** The `SetDocumentsContext` interface is used in: * `setDocuments()` method to fetch comments filtered by context * `identify()` method to filter notifications by context * Frontend SDK methods that require context filtering **Filtering Logic:** * **Within a field (OR logic)**: When multiple values are provided for a single field, comments/notifications matching any value are returned * **Across fields (AND logic)**: When multiple fields are provided, comments/notifications must match all field values **Permission Provider Integration:** When Permission Provider is enabled with `isContextEnabled: true`, each value in the arrays is sent as a separate permission request to your backend using the [`Context`](#context) interface format. This allows granular access control at the context value level. #### Options *** | Property | Type | Required | Description | | ------------------------ | --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `authToken` | `string` | No | The authentication token for the user. | | `forceReset` | `boolean` | No | If true, forces the user to re-login. | | `throwError` | `boolean` | No | If true, throws error if user authentication fails. Default: false. | | `context` | [`SetDocumentsContext`](#setdocumentscontext) | No | Filter notifications by custom context fields. Fetches notifications matching any of the provided values (OR logic within a field). When Permission Provider is enabled with `isContextEnabled: true`, each context value triggers a separate permission request. | | `replaceContacts` | `boolean` | No | If true, replaces the user's personal and group contacts with the ones provided. | | `replacePrivateContacts` | `boolean` | No | If true, replaces the user's personal contacts with the ones provided. | | `replaceGroupContacts` | `boolean` | No | If true, replaces the user's group contacts with the ones provided. | # React Flow Collaboration #### VeltReactFlowCrdtExtensionConfig *** Configuration for the `useVeltReactFlowCrdtExtension` React hook. | Property | Type | Required | Description | | -------------- | -------- | -------- | ------------------------------------------------------------------- | | `editorId` | `string` | Yes | Unique document identifier for synchronization. | | `initialNodes` | `Node[]` | Yes | Initial set of nodes. Applied only when no server-side data exists. | | `initialEdges` | `Edge[]` | Yes | Initial set of edges. Applied only when no server-side data exists. | | `debounceMs` | `number` | No | Debounce time for update propagation in milliseconds. | #### VeltReactFlowCrdtExtensionResponse *** Interface extending [`VeltReactFlowAppState`](#appstate). | Property | Type | Description | | --------------- | ------------------------- | -------------------------------------- | | `store` | `Store` | ReactFlow CRDT store instance. | | `nodes` | `Node[]` | Array of nodes in the flow diagram. | | `edges` | `Edge[]` | Array of edges connecting the nodes. | | `onNodesChange` | `OnNodesChange` | Callback for handling node changes. | | `onEdgesChange` | `OnEdgesChange` | Callback for handling edge changes. | | `onConnect` | `OnConnect` | Callback for handling new connections. | | `setNodes` | `(nodes: Node[]) => void` | Function to set all nodes at once. | | `setEdges` | `(edges: Edge[]) => void` | Function to set all edges at once. | #### VeltReactFlowStoreConfig *** | Property | Type | Required | Description | | -------------- | -------- | -------- | ------------------------------------------------------------------- | | `editorId` | `string` | Yes | Unique ID for this collaborative React Flow instance. | | `veltClient` | `Velt` | Yes | Client from `useVeltClient()` for auth/session and syncing. | | `initialNodes` | `Node[]` | Yes | Initial set of nodes. Applied only when no server-side data exists. | | `initialEdges` | `Edge[]` | Yes | Initial set of edges. Applied only when no server-side data exists. | | `debounceMs` | `number` | No | Debounce time for updates (milliseconds). | #### AppState *** | Property | Type | Description | | --------------- | ------------------------- | -------------------------------------- | | `nodes` | `Node[]` | Array of nodes in the flow diagram. | | `edges` | `Edge[]` | Array of edges connecting the nodes. | | `onNodesChange` | `OnNodesChange` | Callback for handling node changes. | | `onEdgesChange` | `OnEdgesChange` | Callback for handling edge changes. | | `onConnect` | `OnConnect` | Callback for handling new connections. | | `setNodes` | `(nodes: Node[]) => void` | Function to set all nodes at once. | | `setEdges` | `(edges: Edge[]) => void` | Function to set all edges at once. | #### Node (React Flow) *** | Property | Type | Required | Description | | ---------- | -------------------------- | -------- | -------------------------------------------- | | `id` | `string` | Yes | Unique node identifier. | | `type` | `string` | No | React Flow node type (e.g., `"input"`). | | `data` | `{ label?: string }` | No | Freeform node data (label used in examples). | | `position` | `{ x: number; y: number }` | Yes | Canvas position in px. | | `origin` | `[number, number]` | No | Optional anchor origin used in examples. | #### Edge (React Flow) *** | Property | Type | Required | Description | | -------- | -------- | -------- | --------------- | | `id` | `string` | Yes | Unique edge id. | | `source` | `string` | Yes | Source node id. | | `target` | `string` | Yes | Target node id. | #### NodeChange *** | Property | Type | Required | Description | | -------- | ------------------------------- | --------------- | ----------------------------- | | `type` | `'add' \| 'update' \| 'remove'` | Yes | Kind of change. | | `item` | `Node` | Yes (for `add`) | Node to add (as in examples). | #### EdgeChange *** | Property | Type | Required | Description | | -------- | ------------------------------- | --------------- | ----------------------------- | | `type` | `'add' \| 'update' \| 'remove'` | Yes | Kind of change. | | `item` | `Edge` | Yes (for `add`) | Edge to add (as in examples). | #### Connection *** | Property | Type | Required | Description | | -------- | -------- | -------- | -------------------------------------- | | `source` | `string` | Yes | Source node id. | | `target` | `string` | Yes | Target node id. | | *…* | *varies* | No | Other React Flow fields as applicable. | #### ConnectionState (used in onConnectEnd) *** | Property | Type | Required | Description | | ---------- | ---------------- | -------- | -------------------------------------------- | | `isValid` | `boolean` | Yes | Whether the provisional connection is valid. | | `fromNode` | `{ id: string }` | Yes | Node the drag originated from. | # CodeMirror Collaboration ## v2 API #### UseCollaborationConfig (CodeMirror) *** Configuration for the `useCollaboration` React hook for CodeMirror collaborative editing. | Property | Type | Required | Description | | -------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------ | | `editorId` | `string` | Yes | Unique identifier for this collaborative session. | | `initialContent` | `string` | No | Text content applied once for brand-new documents. | | `debounceMs` | `number` | No | Throttle interval (ms) for backend writes. Default: `0`. | | `forceResetInitialContent` | `boolean` | No | If `true`, always clear and re-apply `initialContent`. Default: `false`. | | `veltClient` | `Velt` | No | Explicit Velt client. Falls back to `VeltProvider` context. | | `onError` | `(error: Error) => void` | No | Error callback. | #### UseCollaborationReturn (CodeMirror) *** Return value of the `useCollaboration` hook for CodeMirror. | Property | Type | Description | | ------------ | --------------------------------- | ---------------------------------------------------------------------- | | `primitives` | `CollaborationPrimitives \| null` | Yjs primitives for CodeMirror. `null` while loading. | | `isLoading` | `boolean` | `true` until CollaborationManager is initialized. | | `isSynced` | `boolean` | `true` after the initial sync with the backend completes. | | `status` | `SyncStatus` | Connection status: `'connecting'`, `'connected'`, or `'disconnected'`. | | `error` | `Error \| null` | Most recent error, or `null`. | | `manager` | `CollaborationManager \| null` | Escape hatch to the underlying manager. `null` before initialization. | #### CollaborationPrimitives *** Yjs primitives returned by `useCollaboration` for CodeMirror integration. Pass these to `yCollab()` from `y-codemirror.next`. | Property | Type | Description | | ------------- | ----------------------- | ------------------------------------------------------- | | `ytext` | `Y.Text \| null` | Y.Text bound to the document. Pass to `yCollab()`. | | `awareness` | `Awareness` | Awareness instance for cursor/presence tracking. | | `undoManager` | `Y.UndoManager \| null` | Collaborative undo manager (tracks local changes only). | | `doc` | `Y.Doc` | Underlying Yjs document. | #### CollaborationConfig (CodeMirror) *** Configuration for the non-React `createCollaboration()` factory function for CodeMirror. | Property | Type | Required | Description | | -------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------- | | `editorId` | `string` | Yes | Unique editor/document identifier for syncing. | | `veltClient` | `Velt` | Yes | Velt client instance — must have an authenticated user. | | `initialContent` | `string` | No | Plain text content applied once for brand-new (empty) documents. | | `debounceMs` | `number` | No | Throttle interval (ms) for backend writes. `0` = immediate. Default: `0`. | | `onError` | `(error: Error) => void` | No | Callback for non-fatal errors (sync failures, recovery attempts). | | `forceResetInitialContent` | `boolean` | No | If `true`, always reset to `initialContent` on init. Default: `false`. | #### CollaborationManager (CodeMirror) *** Manages the CRDT lifecycle for collaborative CodeMirror editing. Returned by `useCollaboration` (React) via `manager`, or by `createCollaboration` (non-React). | Method / Property | Type / Signature | Description | | ------------------------------ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `getCollaborationPrimitives()` | `CollaborationPrimitives` | Returns Yjs primitives (`ytext`, `awareness`, `undoManager`, `doc`) for `yCollab()`. Non-React only. | | `initialized` | `boolean` | Whether `initialize()` has completed. | | `synced` | `boolean` | Whether initial sync with the backend has completed. | | `status` | `SyncStatus` | Current connection status. | | `onStatusChange(cb)` | `(cb: (status: SyncStatus) => void) => Unsubscribe` | Subscribe to connection status changes. | | `onSynced(cb)` | `(cb: (synced: boolean) => void) => Unsubscribe` | Subscribe to sync state changes. | | `saveVersion(name)` | `(name: string) => Promise` | Save a named snapshot. Returns the version ID. | | `getVersions()` | `Promise` | List all saved versions. | | `restoreVersion(id)` | `(versionId: string) => Promise` | Restore to a saved version. Returns `true` on success. | | `setStateFromVersion(version)` | `(version: Version) => Promise` | Apply a Version object's state locally. | | `getDoc()` | `Y.Doc` | Get the underlying Yjs document. | | `getText()` / `getYText()` | `Y.Text \| null` | Get the Y.Text bound to the document content. React uses `getText()`, non-React uses `getYText()`. | | `getProvider()` | `SyncProvider` | Get the sync provider. | | `getAwareness()` | `Awareness` | Get the Yjs Awareness instance. | | `getStore()` | `Store` | Get the core CRDT Store. | | `getUndoManager()` | `Y.UndoManager \| null` | Get the Y.UndoManager for undo/redo operations. | | `destroy()` | `void` | Full cleanup. Automatic on editor destroy or component unmount. Safe to call multiple times. | #### SyncStatus (CodeMirror) *** Connection status for a collaborative CodeMirror session. ```typescript theme={null} type SyncStatus = 'connecting' | 'connected' | 'disconnected'; ``` #### Version (CodeMirror) *** A saved snapshot of the collaborative document state (from `@veltdev/crdt`). | Property | Type | Description | | ------------- | ------------------------ | ------------------------------------ | | `versionId` | `string` | Unique version identifier. | | `versionName` | `string` | Human-readable version name. | | `timestamp` | `number` | Creation timestamp (ms since epoch). | | `state` | `Uint8Array \| number[]` | Encoded Yjs document state. | #### Unsubscribe (CodeMirror) *** Callback returned by `manager.onStatusChange()` and `manager.onSynced()`. Call it to stop listening. ```typescript theme={null} type Unsubscribe = () => void; ``` ## v1 API (deprecated) The v1 CodeMirror API is deprecated. Use the v2 `useCollaboration` hook (React) or `createCollaboration` (non-React) for all new integrations. #### VeltCodeMirrorCrdtExtensionConfig (deprecated) *** Configuration for the legacy `useVeltCodeMirrorCrdtExtension` React hook. | Property | Type | Required | Description | | ---------------- | -------- | -------- | -------------------------------------------------------------------------- | | `editorId` | `string` | Yes | Unique document identifier for synchronization. | | `initialContent` | `string` | No | Initial CodeMirror document. Applied only when no server-side data exists. | | `debounceMs` | `number` | No | Debounce time for update propagation in milliseconds. | | `veltClient` | `Velt` | No | Velt client instance. | #### VeltCodeMirrorCrdtExtensionResponse (deprecated) *** Response returned by the legacy `useVeltCodeMirrorCrdtExtension`. | Property | Type | Description | | ----------- | ----------------------------- | ----------------------------------------------------- | | `store` | `VeltCodeMirrorStore \| null` | CodeMirror CRDT store instance. | | `isLoading` | `boolean` | `false` once store is initialized, `true` by default. | #### VeltCodeMirrorStoreConfig (deprecated) *** | Property | Type | Required | Description | | ------------------- | ------------------------ | -------- | --------------------------------------------------------------------- | | `editorId` | `string` | Yes | Unique document identifier for synchronization. | | `veltClient` | `Velt` | Yes | Velt client for Velt SDK integration. | | `initialContent` | `string` | No | Initial editor content. Applied only when no server-side data exists. | | `debounceMs` | `number` | No | Debounce time for updates (milliseconds). | | `onSynced` | `(doc?: Y.Doc) => void` | No | Called once when initial sync completes. | | `onConnectionError` | `(error: Error) => void` | No | Called on connection errors. | # BlockNote Collaboration ## v2 API #### UseCollaborationConfig (BlockNote) *** Configuration for the `useCollaboration` React hook for BlockNote collaborative editing. | Property | Type | Required | Description | | -------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------ | | `editorId` | `string` | Yes | Unique identifier for this collaborative session. | | `initialContent` | `any[]` | No | Block content applied once for brand-new documents. | | `debounceMs` | `number` | No | Throttle interval (ms) for backend writes. Default: `0`. | | `forceResetInitialContent` | `boolean` | No | If `true`, always clear and re-apply `initialContent`. Default: `false`. | | `veltClient` | `Velt` | No | Explicit Velt client. Falls back to `VeltProvider` context. | | `showCursorLabels` | `’activity’ \| ‘always’` | No | Cursor label display mode. Default: `’activity’`. | | `onError` | `(error: Error) => void` | No | Error callback. | #### UseCollaborationReturn (BlockNote) *** Return value of the `useCollaboration` hook for BlockNote. | Property | Type | Description | | --------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------- | | `collaborationConfig` | `BlockNoteCollaborationConfig \| null` | BlockNote collaboration config. `null` while loading, stable reference once ready. | | `isLoading` | `boolean` | `true` until CollaborationManager is initialized. | | `isSynced` | `boolean` | `true` after the initial sync with the backend completes. | | `status` | `SyncStatus` | Connection status: `’connecting’`, `’connected’`, or `’disconnected’`. | | `error` | `Error \| null` | Most recent error, or `null`. | | `manager` | `CollaborationManager \| null` | Escape hatch to the underlying manager. `null` before initialization. | | `saveVersion` | `(name: string) => Promise` | Save a named version snapshot. Returns the version ID, or empty string on failure. | | `getVersions` | `() => Promise` | List all saved versions. Returns empty array on failure. | | `restoreVersion` | `(versionId: string) => Promise` | Restore to a saved version. Returns `true` on success, `false` on failure. | #### BlockNoteCollaborationConfig *** Configuration object passed to `useCreateBlockNote({ collaboration: ... })`. | Property | Type | Description | | ------------------ | --------------------------------- | ---------------------------------------------------------- | | `provider` | `SyncProvider` | The Yjs sync provider instance. | | `fragment` | `Y.XmlFragment` | The Y.XmlFragment bound to BlockNote’s document-store key. | | `user` | `{ name: string; color: string }` | User identity for cursor rendering. | | `showCursorLabels` | `’activity’ \| ‘always’` | Cursor label display mode. | #### CollaborationConfig (BlockNote) *** Configuration for the non-React `createCollaboration()` factory function for BlockNote. | Property | Type | Required | Description | | -------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------- | | `editorId` | `string` | Yes | Unique editor/document identifier for syncing. | | `veltClient` | `Velt` | Yes | Velt client instance — must have an authenticated user. | | `initialContent` | `any[]` | No | Block content applied once for brand-new (empty) documents. | | `debounceMs` | `number` | No | Throttle interval (ms) for backend writes. `0` = immediate. Default: `0`. | | `onError` | `(error: Error) => void` | No | Callback for non-fatal errors (sync failures, recovery attempts). | | `forceResetInitialContent` | `boolean` | No | If `true`, always reset to `initialContent` on init. Default: `false`. | #### CollaborationManager (BlockNote) *** Manages the CRDT lifecycle for collaborative BlockNote editing. Returned by `useCollaboration` (React) via `manager`, or by `createCollaboration` (non-React). | Method / Property | Type / Signature | Description | | ------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `getCollaborationConfig(opts?)` | `BlockNoteCollaborationConfig \| null` | Returns the BlockNote collaboration config. Non-React: pass optional `{ showCursorLabels }`. | | `initialized` | `boolean` | Whether `initialize()` has completed. | | `synced` | `boolean` | Whether initial sync with the backend has completed. | | `status` | `SyncStatus` | Current connection status. | | `onStatusChange(cb)` | `(cb: (status: SyncStatus) => void) => Unsubscribe` | Subscribe to connection status changes. | | `onSynced(cb)` | `(cb: (synced: boolean) => void) => Unsubscribe` | Subscribe to sync state changes. | | `saveVersion(name)` | `(name: string) => Promise` | Save a named snapshot. Returns the version ID, or empty string on failure. | | `getVersions()` | `Promise` | List all saved versions. Returns empty array on failure. | | `restoreVersion(id)` | `(versionId: string) => Promise` | Restore to a saved version. Returns `true` on success, `false` on failure. | | `setStateFromVersion(version)` | `(version: Version) => Promise` | Apply a version’s state locally. | | `getDoc()` | `Y.Doc \| null` | Get the underlying Yjs document. | | `getXmlFragment()` | `Y.XmlFragment \| null` | Get the XmlFragment bound to BlockNote’s `document-store` key. | | `getProvider()` | `SyncProvider \| null` | Get the sync provider. | | `getAwareness()` | `Awareness \| null` | Get the Yjs Awareness instance. | | `getStore()` | `Store \| null` | Get the core CRDT Store. | | `destroy()` | `void` | Full cleanup. Automatic on editor destroy or component unmount. Safe to call multiple times. | #### SyncStatus (BlockNote) *** Connection status of the CRDT sync provider. ```typescript theme={null} type SyncStatus = 'connecting' | 'connected' | 'disconnected'; ``` #### Unsubscribe (BlockNote) *** Callback returned by `onStatusChange()` and `onSynced()`. Call it to stop listening. ```typescript theme={null} type Unsubscribe = () => void; ``` #### Version (BlockNote) *** A saved snapshot of the document state (from `@veltdev/crdt`). | Property | Type | Description | | ------------- | ------------------------ | ------------------------------------ | | `versionId` | `string` | Unique version identifier. | | `versionName` | `string` | Human-readable version name. | | `timestamp` | `number` | Creation timestamp (ms since epoch). | | `state` | `Uint8Array \| number[]` | Encoded Yjs document state. | ## v1 API (deprecated) The v1 BlockNote API is deprecated. Use the v2 `useCollaboration` hook (React) or `createCollaboration` (non-React) for all new integrations. #### VeltBlockNoteCrdtExtensionConfig (deprecated) *** Configuration for the legacy `useVeltBlockNoteCrdtExtension` React hook. | Property | Type | Required | Description | | ---------------- | -------- | -------- | ----------------------------------------------------- | | `editorId` | `string` | Yes | Unique document identifier for synchronization. | | `initialContent` | `string` | No | Initial BlockNote document (JSON string of blocks). | | `debounceMs` | `number` | No | Debounce time for update propagation in milliseconds. | #### VeltBlockNoteCrdtExtensionResponse (deprecated) *** Response returned by the legacy `useVeltBlockNoteCrdtExtension`. | Property | Type | Description | | --------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `collaborationConfig` | `{ fragment: any; provider: any; user: { name: string; color: string } } \| null` | Configuration object to pass into BlockNote’s `useCreateBlockNote({ collaboration })`. | | `store` | `VeltBlockNoteStore \| null` | BlockNote CRDT store instance. | | `isLoading` | `boolean` | `false` once store is initialized, `true` by default. | #### VeltBlockNoteStoreConfig (deprecated) *** Configuration for creating a legacy BlockNote collaboration store. | Property | Type | Required | Description | | ------------------- | ------------------------ | -------- | ---------------------------------------------------------------------------------------- | | `editorId` | string | Yes | Unique document identifier used for syncing. | | `initialContent` | string | No | JSON string representing an array of blocks to seed the doc (parsed into Y.XmlFragment). | | `collection` | string | No | Backend collection name (e.g., persistence). Defaults internally. | | `debounceMs` | number | No | Debounce (ms) for update batching. | | `onSynced` | `(doc?: Y.Doc) => void` | No | Called after initial sync completes. | | `onConnectionError` | `(error: Error) => void` | No | Called if a connection error occurs. | | `veltClient` | `Velt` | No | Velt client used for auth/session context and user resolution. | # Tiptap Collaboration ## v2 API #### UseCollaborationConfig *** Configuration for the `useCollaboration` React hook that enables real-time collaborative editing on TipTap. | Property | Type | Required | Description | | -------------------------- | ------------------------ | -------- | ---------------------------------------------------------------------------- | | `editorId` | `string` | Yes | Unique identifier for this collaborative session. | | `initialContent` | `string` | No | HTML content applied once for brand-new documents. Default: empty paragraph. | | `debounceMs` | `number` | No | Throttle interval (ms) for backend writes. Default: `0`. | | `forceResetInitialContent` | `boolean` | No | If `true`, always clear and re-apply `initialContent`. Default: `false`. | | `veltClient` | `Velt` | No | Explicit Velt client. Falls back to `VeltProvider` context. | | `onError` | `(error: Error) => void` | No | Error callback. | #### UseCollaborationReturn *** Return value of the `useCollaboration` hook. | Property | Type | Description | | ----------- | ------------------------------ | ------------------------------------------------------------------------------- | | `extension` | `Extension \| null` | TipTap Extension bundling Yjs binding + cursor rendering. `null` while loading. | | `isLoading` | `boolean` | `true` until CollaborationManager is initialized. | | `isSynced` | `boolean` | `true` after the initial sync with the backend completes. | | `status` | `SyncStatus` | Connection status: `'connecting'`, `'connected'`, or `'disconnected'`. | | `error` | `Error \| null` | Most recent error, or `null`. | | `manager` | `CollaborationManager \| null` | Escape hatch to the underlying manager. `null` before initialization. | #### SyncStatus *** Connection status type for the collaborative session. ```typescript theme={null} type SyncStatus = 'connecting' | 'connected' | 'disconnected'; ``` #### Version *** Represents a named snapshot of the document state. | Property | Type | Description | | ------------- | ------------------------ | --------------------------------------------- | | `versionId` | `string` | Unique identifier for the version. | | `versionName` | `string` | Human-readable name for the version. | | `timestamp` | `number` | Unix timestamp of when the version was saved. | | `state` | `number[] \| Uint8Array` | Serialized Yjs document state. | #### CollaborationConfig *** Configuration for the non-React `createCollaboration()` factory function. | Property | Type | Required | Description | | -------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------- | | `editorId` | `string` | Yes | Unique editor/document identifier for syncing. | | `veltClient` | `Velt` | Yes | Velt client instance — must have an authenticated user. | | `initialContent` | `string` | No | HTML content applied once for brand-new (empty) documents. | | `debounceMs` | `number` | No | Throttle interval (ms) for backend writes. `0` = immediate. Default: `0`. | | `onError` | `(error: Error) => void` | No | Callback for non-fatal errors (sync failures, recovery attempts). | | `forceResetInitialContent` | `boolean` | No | If `true`, always reset to `initialContent` on init. Default: `false`. | #### CollaborationManager *** Manages the CRDT lifecycle for collaborative TipTap editing. Returned by `useCollaboration` (React) via `manager`, or by `createCollaboration` (non-React). | Method / Property | Type / Signature | Description | | ------------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `createExtension()` | `Extension` | Returns a TipTap Extension bundling Yjs binding + cursor rendering. Non-React only. | | `initialized` | `boolean` | Whether `initialize()` has completed. | | `synced` | `boolean` | Whether initial sync with the backend has completed. | | `status` | `SyncStatus` | Current connection status. | | `onStatusChange(cb)` | `(cb: (status: SyncStatus) => void) => Unsubscribe` | Subscribe to connection status changes. | | `onSynced(cb)` | `(cb: (synced: boolean) => void) => Unsubscribe` | Subscribe to sync state changes. | | `saveVersion(name)` | `(name: string) => Promise` | Save a named snapshot. Returns the version ID. | | `getVersions()` | `Promise` | List all saved versions. | | `restoreVersion(id)` | `(versionId: string) => Promise` | Restore to a saved version. Returns `true` on success. | | `setStateFromVersion(version)` | `(version: Version) => Promise` | Apply a Version object's state locally. | | `getDoc()` | `Y.Doc` | Get the underlying Yjs document. | | `getXmlFragment()` | `Y.XmlFragment \| null` | Get the XmlFragment bound to TipTap content. | | `getProvider()` | `SyncProvider` | Get the sync provider. | | `getAwareness()` | `Awareness` | Get the Yjs Awareness instance. | | `getStore()` | `Store` | Get the core CRDT Store. | | `destroy()` | `void` | Full cleanup. Automatic on editor destroy or component unmount. Safe to call multiple times. | #### Unsubscribe *** Cleanup function returned by subscription methods. ```typescript theme={null} type Unsubscribe = () => void; ``` ## v1 API (deprecated) The v1 Tiptap API is deprecated. Use the v2 `useCollaboration` hook (React) or `createCollaboration` (non-React) for all new integrations. #### VeltTiptapCrdtExtensionConfig (deprecated) *** Configuration for the legacy Tiptap CRDT extension. | Property | Type | Required | Description | | ------------------- | ------------------------ | -------- | --------------------------------------------------------------------- | | `editorId` | `string` | Yes | Unique document identifier for synchronization. | | `initialContent` | `string` | No | Initial editor content. Applied only when no server-side data exists. | | `debounceMs` | `number` | No | Debounce time for update propagation (ms). | | `onSynced` | `(doc?: Y.Doc) => void` | No | Called after initial sync completes. | | `onConnectionError` | `(error: Error) => void` | No | Called if a connection error occurs. | | `veltClient` | `Velt` | No | Velt client instance. | #### VeltTiptapCrdtExtensionResponse (React, deprecated) *** Response from the React `useVeltTiptapCrdtExtension()` hook. | Property | Type | Description | | ----------- | ------------------------- | ----------------------------------------------------- | | `VeltCrdt` | `Extension \| null` | Tiptap Velt CRDT Extension. | | `store` | `VeltTipTapStore \| null` | Tiptap CRDT store instance. | | `isLoading` | `boolean` | `false` once store is initialized, `true` by default. | #### VeltTiptapCrdtExtensionResponse (non-React, deprecated) *** Response from the non-React `createVeltTiptapCrdtExtension()` callback. | Property | Type | Description | | ---------- | ------------------------- | --------------------------------------- | | `VeltCrdt` | `Extension \| null` | TipTap extension to add to the editor. | | `store` | `VeltTipTapStore \| null` | Store instance for version management. | | `error` | `string \| null` | Error message if initialization failed. | #### VeltTipTapStoreConfig (deprecated) *** Configuration for creating a legacy Tiptap collaboration store (used by non-React `createVeltTipTapStore`). | Property | Type | Required | Description | | ------------------- | ------------------------ | -------- | ------------------------------------------------------------------------------ | | `editorId` | `string` | Yes | Unique document identifier for synchronization. Use a different ID per editor. | | `veltClient` | `Velt` | No | Velt client instance. | | `initialContent` | `string` | No | Initial editor content. Applied only when no server-side data exists. | | `debounceMs` | `number` | No | Debounce time for updates in milliseconds | | `onSynced` | `(doc?: Y.Doc) => void` | No | Called once when initial sync completes. | | `onConnectionError` | `(error: Error) => void` | No | Called on connection errors. | #### VeltTipTapStore (deprecated) *** Represents the legacy Tiptap collaboration store instance. Public API surface only; all other fields are private. | Method / Property | Type / Signature | Description | | ------------------------- | ------------------------------------- | --------------------------------------------------------- | | `constructor` | `(config: VeltTipTapStoreConfig)` | Creates a new store wrapper over Yjs + persistence. | | `initialize()` | `Promise` | Initializes the underlying Store and triggers callbacks. | | `getStore()` | `Store` | Returns the underlying CRDT store instance. | | `getYText()` (deprecated) | `Y.Text \| null` | Legacy text accessor; usually returns null (XML is used). | | `getYXml()` | `Y.XmlFragment \| null` | Accessor for XML fragment in the Yjs document. | | `getYDoc()` | `Y.Doc` | Accessor for the Yjs document. | | `isConnected()` | `boolean` | Collaboration readiness flag (initialized). | | `setStateFromVersion()` | `(version: Version) => Promise` | Restores document to a specific version. | | `destroy()` | `void` | Cleans up resources and marks instance uninitialized. | | `getCollabExtension()` | `Extension` | Tiptap Extension configured with current Yjs doc. | #### createVeltTipTapStore (deprecated) *** Legacy factory method that constructs a `VeltTipTapStore`, calls `initialize()`, and returns it. Use `createCollaboration()` for new non-React integrations. | Parameter | Type | Required | Description | | --------- | ----------------------- | -------- | ------------------------------------ | | `config` | `VeltTipTapStoreConfig` | Yes | Configuration options for the store. | | Returns | Type | Description | | ------- | ---------------------------------- | --------------------------------------- | | result | `Promise` | Initialized store or `null` on failure. | # Core Collaboration ## v2 API #### UseStoreConfig`` *** Configuration for the `useStore` React hook. | Property | Type | Required | Description | | -------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------- | | `storeId` | `string` | Yes | Unique document identifier. | | `type` | `FieldKind` | Yes | Yjs data type: `'text'`, `'map'`, `'array'`, `'xml'`, or `'xmltext'`. | | `initialValue` | `T` | No | Initial value applied if remote state is empty. | | `debounceMs` | `number` | No | Throttle interval (ms) for backend writes. `0` = immediate. Default: `0`. | | `enablePresence` | `boolean` | No | Enable presence tracking. Default: `true`. | | `forceResetInitialContent` | `boolean` | No | If `true`, always reset to `initialValue` on init. Default: `false`. | | `onError` | `(error: Error) => void` | No | Error callback for store initialization failures. | | `veltClient` | `Velt` | No | Velt client instance. Falls back to `VeltProvider` context. | #### UseStoreReturn`` *** Return value of `useStore()`. | Property | Type | Description | | --------------------- | ------------------------------------------------- | ---------------------------------------------- | | `value` | `T \| null` | Current store value, reactively updated. | | `versions` | `Version[]` | List of saved versions. | | `isLoading` | `boolean` | `true` while the store is initializing. | | `isSynced` | `boolean` | `true` when the store is connected and synced. | | `status` | `SyncStatus` | Connection status. | | `error` | `Error \| null` | Error object if initialization failed. | | `store` | `Store \| null` | Underlying store instance for advanced use. | | `update` | `(newValue: T) => void` | Replace the entire store value. | | `saveVersion` | `(versionName: string) => Promise` | Save a named snapshot. | | `getVersions` | `() => Promise` | List all saved versions. | | `getVersionById` | `(versionId: string) => Promise` | Get a specific version by ID. | | `restoreVersion` | `(versionId: string) => Promise` | Restore to a saved version. | | `setStateFromVersion` | `(version: Version) => Promise` | Apply a version's state to the document. | #### StoreConfig`` *** Configuration for `createVeltStore()` (non-React). | Property | Type | Required | Description | | -------------------------- | ------------------------------------- | -------- | -------------------------------------------------------------------------- | | `id` | `string` | Yes | Unique document identifier. | | `type` | `'array' \| 'map' \| 'text' \| 'xml'` | Yes | Yjs data type for the store. | | `initialValue` | `T` | No | Initial value applied if remote state is empty. | | `veltClient` | `Velt` | No | Velt client instance (required for sync). | | `debounceMs` | `number` | No | Throttle interval (ms) for backend writes. Default: `0`. | | `enablePresence` | `boolean` | No | Enable presence tracking. Default: `true`. | | `forceResetInitialContent` | `boolean` | No | If `true`, always reset to `initialValue` on init. Default: `false`. | | `contentKey` | `string` | No | Content key for Yjs shared types. Default: `'content'`. | | `userId` | `string` | No | User identifier for update attribution. | | `collection` | `string` | No | Collection/namespace for document grouping. | | `logLevel` | `LogLevel` | No | Log level: `'silent'`, `'error'`, `'warn'`, `'debug'`. Default: `'error'`. | #### FieldKind *** ```typescript theme={null} type FieldKind = 'text' | 'map' | 'array' | 'xml' | 'xmltext'; ``` #### AwarenessState *** Base shape of the local awareness state. ```typescript theme={null} interface AwarenessState { user?: { userId: string; name: string; color: string }; cursor?: { anchor: number; head: number }; [key: string]: unknown; } ``` #### UseAwarenessReturn`` *** Return value of `useAwareness()`. | Property | Type | Description | | --------------- | ---------------------------- | --------------------------------------- | | `remoteStates` | `RemoteAwarenessState[]` | Awareness states of all remote peers. | | `localState` | `T \| null` | Current local awareness state. | | `setLocalState` | `(state: T \| null) => void` | Set or clear the local awareness state. | #### SyncStatus *** ```typescript theme={null} type SyncStatus = 'connecting' | 'connected' | 'disconnected'; ``` #### RemoteAwarenessState`` *** A remote client's awareness state, tagged with their Yjs client ID. ```typescript theme={null} type RemoteAwarenessState = T & { clientId: number; }; ``` #### Version (CRDT) *** A saved snapshot of the store state. | Property | Type | Required | Description | | ------------- | ------------------------ | -------- | ------------------------------------ | | `versionId` | `string` | Yes | Unique version identifier. | | `versionName` | `string` | Yes | Human-readable version name. | | `timestamp` | `number` | No | Creation timestamp (ms since epoch). | | `state` | `Uint8Array \| number[]` | Yes | Encoded Yjs document state. | #### LogLevel *** ```typescript theme={null} type LogLevel = 'silent' | 'error' | 'warn' | 'debug'; ``` ## v1 API (deprecated) The v1 `useVeltCrdtStore` hook is deprecated. Use the v2 `useStore` hook for all new React integrations. The non-React `createVeltStore` API remains unchanged. #### useVeltCrdtStore (deprecated) *** | Property | Type | Description | | --------------------- | ------------------------------------------ | ------------------------------------------- | | `value` | `T \| null` | Current value of the store. | | `versions` | `Version[]` | List of all stored versions. | | `store` | `Store \| null` | The underlying Velt Store instance. | | `update` | `(newValue: T) => void` | Updates the store value. | | `saveVersion` | `(name: string) => Promise` | Saves a new version and returns its ID. | | `getVersions` | `() => Promise` | Fetches all versions. | | `getVersionById` | `(id: string) => Promise` | Fetches a specific version by ID. | | `restoreVersion` | `(id: string) => Promise` | Restores the store to a specific version. | | `setStateFromVersion` | `(version: Version) => Promise` | Sets the store state from a version object. | # Encryption #### EncryptConfig *** | Property | Type | Required | Description | | -------- | -------- | -------- | ---------------------------------------------------- | | `data` | `T` | Yes | The payload to encrypt. | | `type` | `string` | No | Optional type hint to select an encryption strategy. | #### DecryptConfig *** | Property | Type | Required | Description | | -------- | -------- | -------- | --------------------------------------------------- | | `data` | `R` | Yes | The payload to decrypt. | | `type` | `string` | No | Optional type hint to select a decryption strategy. | #### VeltEncryptionProvider *** | Property | Type | Required | Description | | --------- | ------------------------------------------ | -------- | -------------------------------------------------------------------------- | | `encrypt` | `(config: EncryptConfig) => Promise` | Yes | Asynchronous function that encrypts data and returns the encrypted result. | | `decrypt` | `(config: DecryptConfig) => Promise` | Yes | Asynchronous function that decrypts data and returns the original value. | #### CrdtUpdateDataEvent *** Event emitted when CRDT data changes occur, triggered by webhook notifications. | Property | Type | Required | Description | | ------------ | ------------------------------------------------- | -------- | -------------------------------- | | `methodName` | `string` | Yes | Method that triggered the update | | `uniqueId` | `string` | Yes | Unique identifier for the event | | `timestamp` | `number` | Yes | Unix timestamp of the event | | `source` | `string` | Yes | Source of the data change | | `payload` | [`CrdtUpdateDataPayload`](#crdtupdatedatapayload) | Yes | Data change payload | #### CrdtUpdateDataPayload *** Payload containing details of the CRDT data update. | Property | Type | Required | Description | | --------------- | ---------------- | -------- | -------------------------------- | | `id` | `string` | Yes | Store identifier | | `data` | `unknown` | Yes | Updated data value | | `lastUpdatedBy` | `string` | Yes | User ID who made the last update | | `sessionId` | `string \| null` | Yes | Session ID or null | | `lastUpdate` | `string` | Yes | ISO timestamp of last update | #### CrdtPushMessageQuery *** Query to push a raw Yjs message into the unified message stream for a given document. | Property | Type | Required | Description | | ------------- | ----------------------- | -------- | ------------------------------------------------------------------------------ | | `id` | `string` | Yes | Document or store identifier | | `data` | `number[]` | Yes | Raw Yjs message bytes | | `yjsClientId` | `number` | Yes | Yjs client ID of the sender | | `messageType` | `'sync' \| 'awareness'` | No | Message type; defaults to `'sync'` | | `eventData` | `unknown` | No | Optional arbitrary event payload | | `type` | `string` | No | Yjs data type: `'text'`, `'map'`, `'array'`, `'xml'`, `'xmltext'` | | `contentKey` | `string` | No | Content key used in Y.Doc shared types | | `source` | `string` | No | Editor/library source identifier (e.g., `'tiptap'`, `'plate'`, `'codemirror'`) | #### CrdtOnMessageQuery *** Query to subscribe to incoming messages on the unified message stream. | Property | Type | Required | Description | | ---------- | ------------------------------------ | -------- | ----------------------------------------------------- | | `id` | `string` | Yes | Document or store identifier | | `callback` | `(message: CrdtMessageData) => void` | Yes | Called with each received message | | `afterTs` | `number` | No | Only deliver messages with timestamp after this value | #### CrdtMessageData *** Data object representing a single message received from the unified message stream. | Property | Type | Required | Description | | ------------- | ---------- | -------- | --------------------------------------------- | | `data` | `number[]` | Yes | Raw Yjs message bytes | | `yjsClientId` | `number` | Yes | Yjs client ID of the sender | | `timestamp` | `number` | Yes | Unix timestamp when the message was persisted | #### CrdtGetMessagesQuery *** Query to retrieve historical messages from the unified message stream. | Property | Type | Required | Description | | --------- | -------- | -------- | ---------------------------------------------------- | | `id` | `string` | Yes | Document or store identifier | | `afterTs` | `number` | No | Only return messages with timestamp after this value | #### CrdtGetSnapshotQuery *** Query to retrieve the latest CRDT state snapshot for a document. | Property | Type | Required | Description | | -------- | -------- | -------- | ---------------------------- | | `id` | `string` | Yes | Document or store identifier | #### CrdtSnapshotData *** Snapshot of the CRDT document state at a point in time. | Property | Type | Required | Description | | ----------- | ------------------------ | -------- | ------------------------------------------ | | `state` | `Uint8Array \| number[]` | No | Encoded Yjs document state | | `vector` | `Uint8Array \| number[]` | No | Encoded Yjs state vector | | `timestamp` | `number` | No | Unix timestamp when the snapshot was saved | #### CrdtSaveSnapshotQuery *** Query to persist a CRDT state snapshot for a document. | Property | Type | Required | Description | | ------------ | ------------------------ | -------- | ----------------------------------------------------- | | `id` | `string` | Yes | Document or store identifier | | `state` | `Uint8Array \| number[]` | Yes | Encoded Yjs document state to persist | | `vector` | `Uint8Array \| number[]` | Yes | Encoded Yjs state vector to persist | | `type` | `string` | No | Custom type label for the snapshot | | `contentKey` | `string` | No | Key identifying a sub-section of the document content | | `source` | `string` | No | Identifies the origin of this snapshot | #### CrdtPruneMessagesQuery *** Query to delete historical messages older than a given timestamp from the message stream. | Property | Type | Required | Description | | ---------- | -------- | -------- | ---------------------------------------------------- | | `id` | `string` | Yes | Document or store identifier | | `beforeTs` | `number` | Yes | Delete all messages with timestamp before this value | # Provider Configuration #### VeltProviderConfig *** Configuration object passed to `VeltProvider` (React) or `initVelt()` (other frameworks) to customize SDK behavior, proxy routing, and security. | Property | Type | Required | Description | | ---------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------- | | `proxyDomain` | `string` | No | Base URL for proxying the Velt SDK via your own CDN or server. | | `proxyConfig` | [`ProxyConfig`](#proxyconfig) | No | Fine-grained proxy routing for individual Velt service hosts. Replaces `apiProxyDomain`. | | `apiProxyDomain` | `string` | No | **Deprecated.** Use `proxyConfig.apiHost` instead. Single proxy URL for all Velt API calls. | | `integrity` | `boolean` | No | Enable Subresource Integrity (SRI) check on the SDK bundle. Default: `false`. | #### ProxyConfig *** Fine-grained proxy routing configuration for individual Velt service hosts. Introduced in v5.0.2-beta.11. Replaces the single `apiProxyDomain` field. ```typescript theme={null} export interface ProxyConfig { cdnHost?: string; apiHost?: string; v2DbHost?: string; v1DbHost?: string; storageHost?: string; authHost?: string; forceLongPolling?: boolean; } ``` | Property | Type | Required | Description | | ------------------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `cdnHost` | `string` | No | Proxy host for Velt CDN assets (SDK bundle, static resources). Replaces `https://cdn.velt.dev`. | | `apiHost` | `string` | No | Proxy host for Velt API calls. Replaces the deprecated `apiProxyDomain` field. Forwards to `https://api.velt.dev`. | | `v2DbHost` | `string` | No | Proxy host for persistence (Velt v2 database). Your proxy should forward to the persistence endpoint. | | `v1DbHost` | `string` | No | Proxy host for ephemeral Database (Velt v1 database). Replaces the `firebaseio.com` domain. When set, the SDK host-locks RTDB to prevent redirect to shard servers. See [Proxy Server](/security/proxy-server#v1dbhost). | | `storageHost` | `string` | No | Proxy host for File Storage. Replaces `firebasestorage.googleapis.com`. | | `authHost` | `string` | No | Proxy host for Auth. Replaces `identitytoolkit.googleapis.com` and `securetoken.googleapis.com`. Cached in `localStorage` at init time to apply before token refresh on page reload. | | `forceLongPolling` | `boolean` | No | Force long-polling for persistence and Realtime Database connections instead of WebSockets. Default: `false`. | `apiProxyDomain` is deprecated as of v5.0.2-beta.11. Migrate to `proxyConfig.apiHost` for equivalent behavior. All other host overrides require the new `proxyConfig` fields. # Suggestions ### Core Types #### SuggestionStatus *** Lifecycle states for a suggestion. Transitions are forward-only. ```typescript theme={null} type SuggestionStatus = 'pending' | 'accepted' | 'rejected' | 'stale' | 'apply_failed'; ``` | Value | Description | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `'pending'` | Suggestion created; awaiting a resolution action | | `'accepted'` | Suggestion accepted; your `suggestionApproved` handler applies the change | | `'rejected'` | Suggestion explicitly rejected | | `'stale'` | Target DOM node could not be resolved at accept time; suggestion invalidated | | `'apply_failed'` | The accept handler threw while applying the change. Represented via [`ApprovedSuggestion`](#approvedsuggestiont); surfaced as a status only (no dedicated event in v1). | #### SuggestionMode *** v1 exports this type for forward compatibility. It is not currently consumed by any public method parameter or return type. ```typescript theme={null} type SuggestionMode = 'suggesting' | 'editing'; ``` #### SuggestionTargetType *** v1 always resolves to `'custom'`. ```typescript theme={null} type SuggestionTargetType = 'custom'; ``` #### SuggestionData *** Stored on `CommentAnnotation.suggestion` when `annotation.type === 'suggestion'`. SDK-managed; read via [`SuggestionElement`](#suggestionelement) API. | Property | Type | Required | Description | | --------------- | ----------------------------------------------- | -------- | ----------------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the parent `CommentAnnotation` | | `targetId` | `string` | Yes | ID of the registered suggestion target | | `targetType` | [`SuggestionTargetType`](#suggestiontargettype) | Yes | v1: always `'custom'` | | `status` | [`SuggestionStatus`](#suggestionstatus) | Yes | Current lifecycle state | | `oldValue` | `unknown` | Yes | Target value captured at suggestion creation | | `newValue` | `unknown` | Yes | Proposed replacement value | | `summary` | `string` | No | Human-readable description of the change | | `metadata` | `Record` | No | Arbitrary caller-supplied metadata | | `driftDetected` | `boolean` | No | True when target value changed after suggestion was created | | `createdBy` | `User` | Yes | User who created the suggestion | | `createdAt` | `number` | Yes | Unix timestamp (ms) of creation | | `resolvedBy` | `User` | No | User who approved or rejected the suggestion | | `resolvedAt` | `number` | No | Unix timestamp (ms) of resolution | | `rejectReason` | `string \| null` | No | Reason provided when rejecting; `null` when no reason given | #### Suggestion\ *** Discriminated union resolved by `status`. Use [`SuggestionStatus`](#suggestionstatus) to narrow to a variant. ```typescript theme={null} type Suggestion = | PendingSuggestion | ApprovedSuggestion | RejectedSuggestion | StaleSuggestion; ``` ### Variant Types #### PendingSuggestion\ *** Narrowed `Suggestion` when `status === 'pending'`. | Property | Type | Required | Description | | --------------- | ----------------------------------------------- | -------- | ----------------------------------------- | | `status` | `'pending'` | Yes | Discriminant | | `annotationId` | `string` | Yes | Parent annotation ID | | `targetId` | `string` | Yes | Registered target ID | | `targetType` | [`SuggestionTargetType`](#suggestiontargettype) | Yes | v1: always `'custom'` | | `oldValue` | `T` | Yes | Captured value at suggestion creation | | `newValue` | `T` | Yes | Proposed value | | `summary` | `string` | No | Human-readable description of the change | | `metadata` | `Record` | No | Caller-supplied metadata | | `driftDetected` | `boolean` | No | True if target has changed since snapshot | | `createdBy` | `User` | Yes | Author of the suggestion | | `createdAt` | `number` | Yes | Unix timestamp (ms) of creation | #### ApprovedSuggestion\ *** Narrowed `Suggestion` when `status === 'accepted'` (also covers `'apply_failed'`). Adds `resolvedBy` and `resolvedAt`. | Property | Type | Required | Description | | --------------- | ----------------------------------------------- | -------- | ------------------------------------------- | | `status` | `'accepted' \| 'apply_failed'` | Yes | Discriminant | | `annotationId` | `string` | Yes | Parent annotation ID | | `targetId` | `string` | Yes | Registered target ID | | `targetType` | [`SuggestionTargetType`](#suggestiontargettype) | Yes | v1: always `'custom'` | | `oldValue` | `T` | Yes | Captured value at suggestion creation | | `newValue` | `T` | Yes | Accepted value | | `summary` | `string` | No | Description of the change | | `metadata` | `Record` | No | Caller-supplied metadata | | `driftDetected` | `boolean` | No | True if target value changed since snapshot | | `createdBy` | `User` | Yes | Author of the suggestion | | `createdAt` | `number` | Yes | Unix timestamp (ms) of creation | | `resolvedBy` | `User` | Yes | User who approved the suggestion | | `resolvedAt` | `number` | Yes | Unix timestamp (ms) of approval | #### RejectedSuggestion\ *** Narrowed `Suggestion` when `status === 'rejected'`. Adds `resolvedBy`, `resolvedAt`, and `rejectReason`. | Property | Type | Required | Description | | --------------- | ----------------------------------------------- | -------- | ---------------------------------------------------------- | | `status` | `'rejected'` | Yes | Discriminant | | `annotationId` | `string` | Yes | Parent annotation ID | | `targetId` | `string` | Yes | Registered target ID | | `targetType` | [`SuggestionTargetType`](#suggestiontargettype) | Yes | v1: always `'custom'` | | `oldValue` | `T` | Yes | Captured value at suggestion creation | | `newValue` | `T` | Yes | Proposed value (not applied) | | `summary` | `string` | No | Description of the change | | `metadata` | `Record` | No | Caller-supplied metadata | | `driftDetected` | `boolean` | No | True if target value changed since snapshot | | `createdBy` | `User` | Yes | Author of the suggestion | | `createdAt` | `number` | Yes | Unix timestamp (ms) of creation | | `resolvedBy` | `User` | Yes | User who rejected the suggestion | | `resolvedAt` | `number` | Yes | Unix timestamp (ms) of rejection | | `rejectReason` | `string \| null` | Yes | Reason provided for rejection; `null` when no reason given | #### StaleSuggestion\ *** Narrowed `Suggestion` when `status === 'stale'`. A reviewer clicks Accept, but the target DOM node cannot be resolved at approve time, so the SDK routes the outcome to `stale` instead of `approved`. This variant does not carry `resolvedBy` or `resolvedAt` because the final state is determined by the SDK, not by the reviewer's intent. | Property | Type | Required | Description | | --------------- | ----------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | | `status` | `'stale'` | Yes | Discriminant | | `annotationId` | `string` | Yes | Parent annotation ID | | `targetId` | `string` | Yes | Registered target ID | | `targetType` | [`SuggestionTargetType`](#suggestiontargettype) | Yes | v1: always `'custom'` | | `oldValue` | `T` | Yes | Captured value at suggestion creation | | `newValue` | `T` | Yes | Proposed value | | `summary` | `string` | No | Description of the change | | `metadata` | `Record` | No | Caller-supplied metadata | | `driftDetected` | `boolean` | No | Whether the target value had changed since snapshot; may not be evaluated if the target is unresolvable | | `createdBy` | `User` | Yes | Author of the suggestion | | `createdAt` | `number` | Yes | Unix timestamp (ms) of creation | ### Config Types #### RegisterTargetConfig\ *** Passed to [`registerTarget()`](/api-reference/sdk/api/api-methods#registertarget) to associate a getter with a target ID. | Property | Type | Required | Description | | ---------- | ----------------------------------- | -------- | ------------------------------------------------------------------ | | `targetId` | `string` | Yes | Unique identifier matching `data-velt-suggestion-target` attribute | | `getter` | [`TargetGetter`](#targetgettert) | Yes | Function returning the current value of the target | #### EnableSuggestionModeConfig *** Optional config passed to [`enableSuggestionMode()`](/api-reference/sdk/api/api-methods#enablesuggestionmode-1). | Property | Type | Required | Description | | -------------------- | --------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `onTargetEditStart` | [`TargetEditStartHandler`](#targeteditstarthandlert) | No | Called when user begins editing a suggestion target | | `onTargetEditCommit` | [`TargetEditCommitHandler`](#targeteditcommithandlert) | No | Called when an edit is committed as a suggestion | | `autoCommit` | `boolean` | No | Whether detected edits auto-commit as suggestions using the SDK's default summary. Default: `true`. Pass `false` for detect-only mode — the `targetEditCommit` event still fires, but nothing commits until you call `commitSuggestion` on the event payload. Ignored when `onTargetEditCommit` is provided. | #### CommitSuggestionConfig\ *** Passed to [`commitSuggestion()`](/api-reference/sdk/api/api-methods#commitsuggestion). | Property | Type | Required | Description | | ------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `targetId` | `string` | Yes | ID of the target being committed | | `newValue` | `T` | Yes | Proposed value to store in the suggestion | | `summary` | `string` | No | Human-readable description of the change. Becomes the plain text of the suggestion's first comment. | | `summaryHtml` | `string` | No | HTML body for the suggestion's first comment (for example, a color-coded diff). Sanitized with DOMPurify at render time — inline `style` is kept; scripts and event handlers are stripped. | | `metadata` | `Record` | No | Arbitrary caller-supplied metadata | ### Handler Types #### TargetGetter\ *** Synchronous function that returns the current value of a registered target. ```typescript theme={null} type TargetGetter = () => T; ``` #### TargetEditDetails\ *** Passed to [`TargetEditStartHandler`](#targeteditstarthandlert) and [`TargetEditCommitHandler`](#targeteditcommithandlert). | Property | Type | Required | Description | | ---------- | ------------- | -------- | ----------------------------------------------------- | | `targetId` | `string` | Yes | ID of the target being edited | | `oldValue` | `T` | Yes | Target value at the time editing started | | `newValue` | `T` | Yes | Current value when the edit is being committed | | `element` | `HTMLElement` | No | DOM element tagged with `data-velt-suggestion-target` | #### TargetEditStartResult *** Return value from [`TargetEditStartHandler`](#targeteditstarthandlert). Currently informational; reserved for future overrides. ```typescript theme={null} type TargetEditStartResult = void; ``` #### TargetEditCommitResult *** Optional return from [`TargetEditCommitHandler`](#targeteditcommithandlert) — and optional argument to [`TargetEditCommitBuilder`](#targeteditcommitbuilder) — to override `summary`, `summaryHtml`, or `metadata` on commit. | Property | Type | Required | Description | | ------------- | ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `summary` | `string` | No | Override for the suggestion summary | | `summaryHtml` | `string` | No | Override for the suggestion's HTML body. Sanitized with DOMPurify at render time — see [`CommitSuggestionConfig`](#commitsuggestionconfigt). | | `metadata` | `Record` | No | Override for the suggestion metadata | #### TargetEditStartHandler\ *** ```typescript theme={null} type TargetEditStartHandler = ( details: TargetEditDetails, ) => TargetEditStartResult | Promise; ``` #### TargetEditCommitHandler\ *** ```typescript theme={null} type TargetEditCommitHandler = ( details: TargetEditDetails, ) => TargetEditCommitResult | null | void | Promise; ``` #### TargetEditCommitBuilder *** Pre-bound function attached to [`TargetEditCommitEvent`](#targeteditcommitevent) payloads to programmatically finalize the suggestion. ```typescript theme={null} type TargetEditCommitBuilder = (result?: TargetEditCommitResult) => Promise<{ id: string }>; ``` ### Filter Type #### SuggestionGetSuggestionsFilter *** Optional filter passed to [`getSuggestions()`](/api-reference/sdk/api/api-methods#getsuggestions) and [`getSuggestions$()`](/api-reference/sdk/api/api-methods#getsuggestions-1). | Property | Type | Required | Description | | ---------- | --------------------------------------- | -------- | ------------------------------------------- | | `targetId` | `string` | No | Limit results to a specific target ID | | `status` | [`SuggestionStatus`](#suggestionstatus) | No | Limit results to a specific lifecycle state | ### Element #### SuggestionElement *** Singleton object returned by `client.getSuggestionElement()`. Provides all Suggestions API methods. See [API Methods](/api-reference/sdk/api/api-methods#suggestions) for the full method list. ### Event Payload Types #### SuggestionCreatedEvent *** | Property | Type | Required | Description | | ------------ | --------------------------------------------------- | -------- | ------------------------------------ | | `suggestion` | [`PendingSuggestion`](#pendingsuggestiont) | Yes | The newly created pending suggestion | #### SuggestionApprovedEvent *** | Property | Type | Required | Description | | ------------ | ----------------------------------------------------- | -------- | ----------------------- | | `suggestion` | [`ApprovedSuggestion`](#approvedsuggestiont) | Yes | The approved suggestion | #### SuggestionRejectedEvent *** | Property | Type | Required | Description | | ------------ | ----------------------------------------------------- | -------- | ----------------------- | | `suggestion` | [`RejectedSuggestion`](#rejectedsuggestiont) | Yes | The rejected suggestion | #### SuggestionStaleEvent *** | Property | Type | Required | Description | | ------------ | ----------------------------------------------- | -------- | ------------------------------------------------------------------------- | | `suggestion` | [`StaleSuggestion`](#stalesuggestiont) | Yes | The suggestion marked stale because target DOM node could not be resolved | #### TargetEditStartEvent *** | Property | Type | Required | Description | | --------- | --------------------------------------------------- | -------- | ------------------------------------------ | | `details` | [`TargetEditDetails`](#targeteditdetailst) | Yes | Edit details including targetId and values | #### TargetEditCommitEvent *** | Property | Type | Required | Description | | ------------------ | ----------------------------------------------------- | -------- | --------------------------- | | `details` | [`TargetEditDetails`](#targeteditdetailst) | Yes | Edit details at commit time | | `commitSuggestion` | [`TargetEditCommitBuilder`](#targeteditcommitbuilder) | Yes | Pre-bound commit function | ### Maps and Constants #### SuggestionEventTypesMap *** Maps event type string keys to their payload types. ```typescript theme={null} interface SuggestionEventTypesMap { suggestionCreated: SuggestionCreatedEvent; suggestionApproved: SuggestionApprovedEvent; suggestionRejected: SuggestionRejectedEvent; suggestionStale: SuggestionStaleEvent; targetEditStart: TargetEditStartEvent; targetEditCommit: TargetEditCommitEvent; } ``` #### SuggestionEventTypes *** Constant object enumerating all valid event type strings. ```typescript theme={null} const SuggestionEventTypes = { SUGGESTION_CREATED: 'suggestionCreated', SUGGESTION_APPROVED: 'suggestionApproved', SUGGESTION_REJECTED: 'suggestionRejected', SUGGESTION_STALE: 'suggestionStale', TARGET_EDIT_START: 'targetEditStart', TARGET_EDIT_COMMIT: 'targetEditCommit', } as const; ``` #### SuggestionEventType *** String union of all valid event type keys. ```typescript theme={null} type SuggestionEventType = keyof SuggestionEventTypesMap; // = 'suggestionCreated' | 'suggestionApproved' | 'suggestionRejected' // | 'suggestionStale' | 'targetEditStart' | 'targetEditCommit' ``` ### Utility #### Unsubscribe *** A function that removes a subscription when called. Exported for convenience and forward compatibility. ```typescript theme={null} type Unsubscribe = () => void; ``` In v1, [`registerTarget()`](/api-reference/sdk/api/api-methods#registertarget) returns `void` — remove a registration with [`unregisterTarget()`](/api-reference/sdk/api/api-methods#unregistertarget). [`on()`](/api-reference/sdk/api/api-methods#on-6) returns an `Observable`; unsubscribe via its subscription. ## Python SDK Types Request and response types used by the [Velt Python SDK](/backend-sdks/python). Field details below mirror the dataclass definitions in `velt-py`. ### VeltApiResponse Standard envelope for all `sdk.api.*` REST methods. Success and error are mutually exclusive. ```python theme={null} # Success { 'result': { 'status': 'success', 'message': '...', 'data': { ... } } } # Error { 'error': { 'message': '...', 'status': 'INTERNAL', 'details': { ... } } } ``` ### VeltSelfHostingResponse Standard envelope for all `sdk.selfHosting.*` methods. ```python theme={null} # Success { 'success': True, 'statusCode': 200, 'data': { ... } } # Error { 'success': False, 'statusCode': 500, 'error': '...', 'errorCode': 'INTERNAL_ERROR' } ``` ### AddActivitiesRequest Request payload for `sdk.api.activities.addActivities`. | Field | Type | Required | Description | | ---------------- | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | Yes | Document ID. | | `activities` | `list[dict]` | Yes | Array of activity log objects to create. Each activity supports `id` (optional, for idempotent writes), `featureType` (required: `"comment"`, `"reaction"`, `"recorder"`, `"crdt"`, or `"custom"`), `actionType` (required), `actionUser` (required), `targetEntityId` (required when `featureType` is `"custom"`), `targetSubEntityId`, `changes` (map of `field` → `{from, to}`), `entityData`, `entityTargetData`, `displayMessageTemplate`, `displayMessageTemplateData`, `actionIcon`, `isActivityResolverUsed`. | ### AddCommentAnnotationsRequest Request payload for `sdk.api.commentAnnotations.addCommentAnnotations`. | Field | Type | Required | Description | | ----------------------- | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | Yes | Document ID. | | `verifyUserPermissions` | `bool` | No | When `True`, verifies the user has access before creating annotations. Default: `False`. | | `commentAnnotations` | `list[dict]` | Yes | Annotation objects. Each supports `annotationId` (optional custom ID), `location` (`{id, locationName}`), `targetElement` (`{elementId, targetText, occurrence, selectAllContent}`), `commentData` (required: array of comments with `commentText`/`commentHtml`, required `from`, optional `commentId`, `context`, `triggerNotification`, `triggerActivities`, `taggedUserContacts`, `createdAt`, `lastUpdated`), `status` (`{id, name, type, color, lightColor, svg, iconUrl}`), `assignedTo`, `context`, `priority`, `createdAt`, `lastUpdated`. | ### AddCommentsRequest Request payload for `sdk.api.commentAnnotations.addComments`. | Field | Type | Required | Description | | ----------------------- | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `createOrganization` | `bool` | No | Auto-create the organization if it does not exist. | | `documentId` | `str` | Yes | Document ID. | | `createDocument` | `bool` | No | Auto-create the document if it does not exist. | | `annotationId` | `str` | Yes | Target annotation ID. | | `verifyUserPermissions` | `bool` | No | When `True`, verifies the user has access before adding comments. | | `commentData` | `list[dict]` | Yes | Comments with at least `commentText`/`commentHtml` and `from`. Same fields as the `commentData` items in `AddCommentAnnotationsRequest`. | ### AddCrdtDataRequest Request payload for `sdk.api.crdt.addCrdtData`. | Field | Type | Required | Description | | ---------------- | --------------------- | -------- | ------------------------------------------ | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | Yes | Document ID. | | `editorId` | `str` | Yes | Editor identifier within the document. | | `data` | `str \| dict \| list` | Yes | CRDT payload. Shape depends on `type`. | | `type` | `str` | Yes | One of `text`, `map`, `array`, or `xml`. | | `contentKey` | `str` | No | Optional sub-key within the editor's data. | ### AddDocumentsRequest Request payload for `sdk.api.documents.addDocuments`. | Field | Type | Required | Description | | -------------------- | ------------ | -------- | ------------------------------------------------------ | | `organizationId` | `str` | Yes | Organization ID. | | `createOrganization` | `bool` | No | Auto-create the organization if it does not exist. | | `documents` | `list[dict]` | Yes | Document objects with `documentId` and `documentName`. | | `folderId` | `str` | No | Folder to place the documents in. | | `createFolder` | `bool` | No | Auto-create the folder if it does not exist. | ### AddDomainsRequest Request payload for `sdk.api.workspace.addDomains`. | Field | Type | Required | Description | | --------- | ----------- | -------- | -------------------------------------------------------------------------------------- | | `domains` | `list[str]` | Yes | Domains to add to the workspace allow-list. Wildcards (`*.example.com`) are supported. | ### AddFolderRequest Request payload for `sdk.api.folders.addFolder`. | Field | Type | Required | Description | | ---------------- | ------------ | -------- | --------------------------------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `folders` | `list[dict]` | Yes | Folder objects with `folderId` (required), `folderName`, and optional `parentFolderId`. | ### AddNotificationsRequest Request payload for `sdk.api.notifications.addNotifications`. | Field | Type | Required | Description | | ------------------------------------ | ------------ | -------- | ------------------------------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `createOrganization` | `bool` | No | Auto-create the organization if it does not exist. | | `documentId` | `str` | Yes | Document ID. | | `createDocument` | `bool` | No | Auto-create the document if it does not exist. | | `actionUser` | `dict` | Yes | The user who triggered the notification. | | `verifyUserPermissions` | `bool` | No | When `True`, verifies the action user has access before sending the notification. | | `notificationId` | `str` | No | Custom notification ID. If omitted, Velt generates one. | | `isNotificationResolverUsed` | `bool` | No | Set when self-hosting notifications via a resolver. | | `displayHeadlineMessageTemplate` | `str` | No | Headline template — supports `{actionUser}`, `{recipientUser}`, and custom variables. | | `displayHeadlineMessageTemplateData` | `dict` | No | Values for the headline template variables. | | `displayBodyMessage` | `str` | No | Body of the notification. | | `notifyUsers` | `list[dict]` | Yes | Recipients of the notification. | | `notifyAll` | `bool` | No | Notify all users on the document. | | `notificationSource` | `str` | No | Source feature (e.g. `comment`, `custom`). | | `notificationSourceData` | `dict` | No | Source-specific payload (e.g. annotation snapshot). | | `context` | `dict` | No | Custom key/value metadata. | ### AddOrganizationsRequest Request payload for `sdk.api.organizations.addOrganizations`. | Field | Type | Required | Description | | --------------- | ------------ | -------- | --------------------------------------------------------------------------- | | `organizations` | `list[dict]` | Yes | Array of organization objects with `organizationId` and `organizationName`. | ### AddPermissionsRequest Request payload for `sdk.api.accessControl.addPermissions`. | Field | Type | Required | Description | | ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user` | `dict` | Yes | User object containing `userId`. | | `permissions` | `dict` | Yes | Object with `resources`: an array of resource objects. Each resource has `type` (`organization`, `document`, or `folder`), `id`, optional `organizationId` (required when `type` is `document` or `folder`), optional `accessRole` (`viewer` or `editor`, default `editor`), and optional `expiresAt` Unix-seconds timestamp. | ### AddPresenceRequest Request payload for `sdk.api.presence.addPresence`. | Field | Type | Required | Description | | ---------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | Yes | Document ID. | | `users` | `list[dict]` | Yes | Users with at least `userId`. May include `name`, `email`, `status` (`online`, `away`, `offline`). | ### AddUserGroupsRequest Request payload for `sdk.api.userGroups.addUserGroups`. | Field | Type | Required | Description | | ------------------------ | ------------ | -------- | -------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `createOrganization` | `bool` | No | Auto-create the organization if it does not exist. | | `organizationUserGroups` | `list[dict]` | Yes | Group objects with `groupId` and `groupName`. | ### AddUsersRequest Request payload for `sdk.api.users.addUsers`. | Field | Type | Required | Description | | -------------------- | ------------ | -------- | ------------------------------------------------------------------------------------ | | `organizationId` | `str` | Yes | Organization ID. | | `createOrganization` | `bool` | No | Auto-create the organization if it does not exist. | | `documentId` | `str` | No | Scope the users to a specific document. | | `createDocument` | `bool` | No | Auto-create the document if it does not exist. | | `folderId` | `str` | No | Scope the users to a specific folder. | | `createFolder` | `bool` | No | Auto-create the folder if it does not exist. | | `users` | `list[dict]` | Yes | User objects with at least `userId`. May include `name`, `email`, `accessRole`, etc. | ### AddUsersToGroupRequest Request payload for `sdk.api.userGroups.addUsersToGroup`. | Field | Type | Required | Description | | ------------------------- | ----------- | -------- | --------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `organizationUserGroupId` | `str` | Yes | Target user group ID. | | `userIds` | `list[str]` | Yes | IDs of users to add. | ### AskAiRequest Request payload for `sdk.api.rewriter.askAi`. | Field | Type | Required | Description | | -------- | ----- | -------- | --------------------------------- | | `model` | `str` | Yes | Model identifier (e.g. `gpt-4o`). | | `prompt` | `str` | Yes | Instruction for the model. | | `text` | `str` | Yes | Input text to transform. | ### AskAiResponse Response payload for `sdk.api.rewriter.askAi`. ```python theme={null} { 'result': { 'success': True, 'text': 'The rewritten or processed text returned by the model.' } } ``` ### BroadcastEventRequest Request payload for `sdk.api.livestate.broadcastEvent`. | Field | Type | Required | Description | | ----------------- | ------ | -------- | ---------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | Yes | Document ID. | | `liveStateDataId` | `str` | Yes | Identifier for the livestate channel. | | `data` | `dict` | Yes | Arbitrary JSON-serializable payload. | | `merge` | `bool` | No | Merge with existing data instead of replacing. Default: `False`. | ### CreateApiKeyRequest Request payload for `sdk.api.workspace.createApiKey`. | Field | Type | Required | Description | | ------------------------------ | ----------- | -------- | ------------------------------------------------------------------------------- | | `ownerEmail` | `str` | Yes | Email of the API key owner. | | `type` | `str` | Yes | Key type (e.g. `production`, `testing`). | | `createAuthToken` | `bool` | No | Generate an auth token alongside the key. | | `apiKeyName` | `str` | No | Display name for the key. | | `planInfo` | `dict` | No | Plan metadata for the key. | | `customPlanInfo` | `bool` | No | Whether `customPlanInfoData` should be honored. | | `customPlanInfoData` | `dict` | No | Custom plan configuration. | | `allowedDomains` | `list[str]` | No | Domains allowed to use this key. | | `addLocalHostToAllowedDomains` | `bool` | No | Convenience flag to whitelist localhost. | | `useEmailService` | `bool` | No | Enable email service for this key. | | `useWebhookService` | `bool` | No | Enable webhook service for this key. | | `emailServiceConfig` | `dict` | No | Provider config (e.g. SendGrid `apiKey`, `fromEmail`). | | `webhookServiceConfig` | `dict` | No | Webhook config (`authToken`, `rawNotificationUrl`, `processedNotificationUrl`). | ### CreateWorkspaceRequest Request payload for `sdk.api.workspace.createWorkspace`. | Field | Type | Required | Description | | --------------- | ----- | -------- | ------------------------------- | | `ownerEmail` | `str` | Yes | Email of the workspace owner. | | `name` | `str` | No | Display name of the owner. | | `workspaceName` | `str` | No | Display name for the workspace. | | `avatar` | `str` | No | Owner avatar URL. | ### DeleteActivitiesRequest Request payload for `sdk.api.activities.deleteActivities`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | -------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | No | Delete all activity logs associated with this document. | | `activityIds` | `list[str]` | No | Delete specific activity logs by ID. | | `targetEntityId` | `str` | No | Delete all activity logs associated with this entity ID. | At least one of `documentId`, `targetEntityId`, or `activityIds` must be provided. ### DeleteAllUserDataRequest Request payload for `sdk.api.gdpr.deleteAllUserData`. | Field | Type | Required | Description | | ----------------- | ----------- | -------- | ------------------------------------------------------------ | | `userIds` | `list[str]` | Yes | Users whose data should be deleted. | | `organizationIds` | `list[str]` | No | Restrict deletion to these organizations. Speeds up the job. | ### DeleteAttachmentResolverRequest Request payload for `sdk.selfHosting.attachments.deleteAttachment`. | Field | Type | Required | Description | | ---------------- | ----- | -------- | --------------------------------------- | | `organizationId` | `str` | Yes | Organization the attachment belongs to. | | `documentId` | `str` | Yes | Document the attachment belongs to. | | `attachmentId` | `str` | Yes | ID of the attachment to delete. | ### DeleteCommentAnnotationsRequest Request payload for `sdk.api.commentAnnotations.deleteCommentAnnotations`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | ----------------------------------------------------------- | | `organizationId` | `str` | No | Organization ID. | | `documentId` | `str` | Yes | Document ID. | | `locationIds` | `list[str]` | No | Restrict deletion to specific location IDs. | | `annotationIds` | `list[str]` | No | IDs of annotations to delete. | | `userIds` | `list[str]` | No | Restrict deletion to annotations created by specific users. | ### DeleteCommentResolverRequest Request payload for `sdk.selfHosting.comments.deleteComment`. | Field | Type | Required | Description | | ---------------- | ----- | -------- | ------------------------------------ | | `organizationId` | `str` | Yes | Organization the comment belongs to. | | `documentId` | `str` | Yes | Document the comment lives on. | | `annotationId` | `str` | Yes | Annotation containing the comment. | | `commentId` | `int` | Yes | ID of the comment to delete. | ### DeleteCommentsRequest Request payload for `sdk.api.commentAnnotations.deleteComments`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | ---------------------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | Yes | Document ID. | | `annotationId` | `str` | Yes | Annotation to delete comments from. | | `commentIds` | `list[int]` | No | IDs of comments to delete. Omit to delete all comments under the annotation. | ### DeleteDocumentsRequest Request payload for `sdk.api.documents.deleteDocuments`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | --------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentIds` | `list[str]` | Yes | IDs of documents to delete. | ### DeleteDomainsRequest Request payload for `sdk.api.workspace.deleteDomains`. | Field | Type | Required | Description | | --------- | ----------- | -------- | ------------------------------------------------ | | `domains` | `list[str]` | Yes | Domains to remove from the workspace allow-list. | ### DeleteFolderRequest Request payload for `sdk.api.folders.deleteFolder`. | Field | Type | Required | Description | | ---------------- | ----- | -------- | --------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `folderId` | `str` | Yes | ID of the folder to delete. | ### DeleteNotificationsRequest Request payload for `sdk.api.notifications.deleteNotifications`. | Field | Type | Required | Description | | ----------------- | ----------- | -------- | --------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | No | Restrict deletion to a specific document. | | `locationId` | `str` | No | Restrict deletion to a specific location. | | `userId` | `str` | No | Restrict deletion to notifications targeted at a specific user. | | `notificationIds` | `list[str]` | No | IDs of notifications to delete. | ### DeleteOrganizationsRequest Request payload for `sdk.api.organizations.deleteOrganizations`. | Field | Type | Required | Description | | ----------------- | ----------- | -------- | ------------------------------- | | `organizationIds` | `list[str]` | Yes | IDs of organizations to delete. | ### DeletePresenceRequest Request payload for `sdk.api.presence.deletePresence`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | ------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | Yes | Document ID. | | `userIds` | `list[str]` | Yes | IDs of users to remove from presence. | ### DeleteReactionResolverRequest Request payload for `sdk.selfHosting.reactions.deleteReaction`. | Field | Type | Required | Description | | ---------------- | ----- | -------- | ------------------------------------- | | `organizationId` | `str` | Yes | Organization the reaction belongs to. | | `documentId` | `str` | Yes | Document the reaction lives on. | | `reactionId` | `str` | Yes | ID of the reaction to delete. | ### DeleteUsersFromGroupRequest Request payload for `sdk.api.userGroups.deleteUsersFromGroup`. | Field | Type | Required | Description | | ------------------------- | ----------- | -------- | --------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `organizationUserGroupId` | `str` | Yes | Target user group ID. | | `userIds` | `list[str]` | Yes | IDs of users to remove. | | `deleteAll` | `bool` | Yes | Remove every user from the group when `True`. | ### DeleteUsersRequest Request payload for `sdk.api.users.deleteUsers`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | -------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | No | Restrict deletion to users on a specific document. | | `folderId` | `str` | No | Restrict deletion to users in a specific folder. | | `userIds` | `list[str]` | Yes | IDs of users to remove. | ### GenerateSignatureRequest Request payload for `sdk.api.accessControl.generateSignature`. | Field | Type | Required | Description | | ------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `permissions` | `list[dict]` | Yes | Array of permission decisions. Each entry requires `userId`, `resourceId`, `type` (`document`, `folder`, or `organization`), `hasAccess`. Optional: `accessRole` (`viewer` or `editor`, document only) and `expiresAt` (UTC ms). | ### GenerateSignatureResponse Response payload for `sdk.api.accessControl.generateSignature`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Signature generated successfully.', 'data': { 'signature': 'a1b2c3d4e5f6...' } } } ``` ### GenerateTokenRequest Request payload for `sdk.api.accessControl.generateToken`. | Field | Type | Required | Description | | ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userId` | `str` | Yes | User the token is issued for. | | `userProperties` | `dict` | Yes | Object with required `name` and `email`, plus optional `isAdmin`. | | `permissions` | `dict` | Yes | Object with `resources`: array of resource objects (`type`, `id`, optional `organizationId` (required for `document`/`folder`), optional `accessRole`, optional `expiresAt`). | ### GenerateTokenResponse Response payload for `sdk.api.accessControl.generateToken`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Token generated successfully.', 'data': { 'token': 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' } } } ``` ### GetActivitiesRequest Request payload for `sdk.api.activities.getActivities`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | ------------------------------------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | No | Filter activities to a specific document. | | `targetEntityId` | `str` | No | Filter activities to a specific entity (e.g. annotation ID). | | `featureTypes` | `list[str]` | No | Filter by feature type. One or more of `comment`, `reaction`, `recorder`, `crdt`, `custom`. | | `actionTypes` | `list[str]` | No | Filter by action type (e.g. `["comment.add"]`). | | `userId` | `str` | No | Filter by acting user. | | `activityIds` | `list[str]` | No | Fetch specific activities by ID. | | `order` | `str` | No | Order results by timestamp. `asc` or `desc`. Default: `desc`. | | `pageSize` | `int` | No | Number of items per page. Default: 1000. Minimum: 1. | | `pageToken` | `str` | No | Encrypted pagination token from a previous response. | ### GetActivitiesResponse Response payload for `sdk.api.activities.getActivities`. ```python theme={null} { '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', 'displayMessageTemplateData': {'user': {'userId': 'user-1', 'name': 'User Name'}}, 'metadata': {'apiKey': 'yourApiKey', 'documentId': 'doc-456', 'organizationId': 'org-123'}, 'timestamp': 1722409519944 } ], 'pageToken': 'nextPageToken' } } ``` ### GetAllUserDataRequest Request payload for `sdk.api.gdpr.getAllUserData`. | Field | Type | Required | Description | | ---------------- | ----- | -------- | -------------------------------------- | | `organizationId` | `str` | Yes | Organization to query. | | `userId` | `str` | Yes | User whose data should be exported. | | `pageToken` | `str` | No | Pagination token from a previous call. | ### GetAllUserDataResponse Response payload for `sdk.api.gdpr.getAllUserData`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Data fetched successfully.', 'data': { 'comments': [], # Up to 100 items per page. 'reactions': [], # Up to 100 items per page. 'recordings': [], # Up to 100 items per page. 'notifications': [] # Up to 100 items per page. }, 'nextPageToken': 'bhdwdqwjs298e39e479ddkeuw==329' # null when there are no more pages. } } ``` ### GetApiKeyMetadataRequest Request payload for `sdk.api.workspace.getApiKeyMetadata`. | Field | Type | Required | Description | | ----- | ---- | -------- | ------------------------------------------------------------------------------ | | — | — | — | Empty request — no body fields. Workspace is identified by API key in headers. | ### GetApiKeysRequest Request payload for `sdk.api.workspace.getApiKeys`. | Field | Type | Required | Description | | ----------- | ----------- | -------- | ---------------------------------------- | | `apiKeys` | `list[str]` | No | Restrict result to specific API key IDs. | | `pageSize` | `int` | No | Number of results per page. | | `pageToken` | `str` | No | Pagination token from a previous call. | ### GetApiKeysResponse Response payload for `sdk.api.workspace.getApiKeys`. ```python theme={null} { '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' } } ``` ### GetApiKeyMetadataResponse Response payload for `sdk.api.workspace.getApiKeyMetadata`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'API key metadata retrieved successfully.', 'data': { 'defaultDocumentAccessType': 'public', 'planInfo': {'type': 'sdk test'}, 'ownerEmail': 'owner@example.com' } } } ``` ### GetAuthTokensRequest Request payload for `sdk.api.workspace.getAuthTokens`. | Field | Type | Required | Description | | -------- | ----- | -------- | -------------------------------- | | `apiKey` | `str` | Yes | API key to list auth tokens for. | ### GetAuthTokensResponse Response payload for `sdk.api.workspace.getAuthTokens`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Auth tokens retrieved successfully.', 'data': { 'apiKey': 'velt_api_key_1', 'authTokens': [ {'token': 'eyJhbGciOiJSUzI1NiIs...', 'name': 'Default Auth Token', 'domains': []} ] } } } ``` ### GetCommentAnnotationsCountRequest Request payload for `sdk.api.commentAnnotations.getCommentAnnotationsCount`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | ---------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentIds` | `list[str]` | Yes | Document IDs to count annotations for. Limit: 30 IDs per call. | | `userId` | `str` | Yes | ID of the user requesting the counts (used to compute unread). | | `statusIds` | `list[str]` | No | Filter counts by annotation status (e.g. `OPEN`, `IN_PROGRESS`). | ### GetCommentAnnotationsCountResponse Response payload for `sdk.api.commentAnnotations.getCommentAnnotationsCount`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Comment count retrieved successfully.', 'data': { 'DOC_1': {'total': 4, 'unread': 2}, 'DOC_2': {'total': 2, 'unread': 0} } } } ``` ### GetCommentAnnotationsRequest Request payload for `sdk.api.commentAnnotations.getCommentAnnotations`. | Field | Type | Required | Description | | ------------------- | ----------- | -------- | ---------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | No | Single document ID. Use `documentIds` for multiple. | | `documentIds` | `list[str]` | No | Up to 30 document IDs. Omit to fetch from all documents. | | `groupByDocumentId` | `bool` | No | Return data grouped by document ID. | | `locationIds` | `list[str]` | No | Filter by location IDs. Limit: 30. | | `folderId` | `str` | No | Filter annotations by folder. | | `annotationIds` | `list[str]` | No | Filter by annotation IDs. Limit: 30. | | `userIds` | `list[str]` | No | Filter by users who created the annotations. Limit: 30. | | `statusIds` | `list[str]` | No | Filter by annotation status IDs. | | `updatedAfter` | `int` | No | Filter annotations updated after this ms-epoch timestamp. | | `updatedBefore` | `int` | No | Filter annotations updated before this ms-epoch timestamp. | | `createdAfter` | `int` | No | Filter annotations created after this ms-epoch timestamp. | | `createdBefore` | `int` | No | Filter annotations created before this ms-epoch timestamp. | | `pageSize` | `int` | No | Items per page. Default: 1000. | | `pageToken` | `str` | No | Page token from a previous call. | ### GetCommentAnnotationsResponse Response payload for `sdk.api.commentAnnotations.getCommentAnnotations`. Includes annotation metadata, page info, full author user objects, subscribed users, embedded comments (with attachments and reaction annotations), and status. With `groupByDocumentId`, `data` is a dict keyed by document ID instead of a list. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Annotation(s) fetched successfully.', 'data': [ { 'annotationId': 'yourAnnotationId', 'annotationNumber': 2, 'type': 'comment', 'createdAt': 1777973713421, 'lastUpdated': 1777978714209, 'hasDraftComments': False, 'context': {'access': {'default': 'velt'}, 'accessFields': ['default:velt']}, 'visibilityConfig': {'type': 'public'}, 'metadata': {'apiKey': '...', 'organizationId': '...', 'documentId': '...'}, 'pageInfo': {'url': '...', 'commentUrl': '...', 'deviceInfo': {'browserName': 'Chrome'}}, 'from': {'userId': 'user123', 'name': 'John Doe', 'email': 'john.doe@example.com'}, 'subscribedUsers': {'...': {'user': {'userId': 'user123'}, 'type': 'auto'}}, 'comments': [ { 'commentId': 123456, 'commentText': 'This is a sample comment text.', 'commentHtml': '

This is a sample comment text.

', 'createdAt': 1777973714914, 'lastUpdated': '2026-05-05T09:35:15.048Z', 'reactionAnnotationIds': ['reactionAnnotationId1'], 'reactionAnnotations': [{'annotationId': 'reactionAnnotationId1', 'icon': 'RAISED_HANDS', 'fromUsers': [...]}], 'from': {'userId': 'user123', 'name': 'John Doe'} } ], 'status': {'id': 'OPEN', 'name': 'Open', 'type': 'default', 'color': '...', 'lightColor': '...', 'svg': '...'} } ], 'nextPageToken': 'pageToken' } } ``` ### GetCommentResolverRequest Request payload for `sdk.selfHosting.comments.getComments`. | Field | Type | Required | Description | | ---------------- | ----- | -------- | ------------------------------------ | | `organizationId` | `str` | Yes | Organization the comments belong to. | | `documentId` | `str` | Yes | Document the comments live on. | ### GetCommentsRequest Request payload for `sdk.api.commentAnnotations.getComments`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | ------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | Yes | Document ID. | | `annotationId` | `str` | Yes | Annotation to fetch comments from. | | `userIds` | `list[str]` | Yes | Filter to comments authored by these users. | | `commentIds` | `list[int]` | No | Filter to specific comment IDs. | ### GetCommentsResponse Response payload for `sdk.api.commentAnnotations.getComments`. Returns the same comment shape embedded in `GetCommentAnnotationsResponse` (text, html, attachments, reactions, author). ```python theme={null} { 'result': { 'status': 'success', 'message': 'Comments retrieved successfully.', 'data': [ { 'commentId': 123456, 'type': 'text', 'commentText': 'This is a sample comment text.', 'commentHtml': '

This is a sample comment text.

', 'createdAt': 1777973714914, 'lastUpdated': '2026-05-05T09:35:15.048Z', 'reactionAnnotationIds': ['reactionAnnotationId1'], 'reactionAnnotations': [{'annotationId': 'reactionAnnotationId1', 'icon': 'RAISED_HANDS', 'fromUsers': [...]}], 'from': {'userId': 'user123', 'name': 'John Doe', 'email': 'john.doe@example.com'} } ] } } ``` ### GetCrdtDataRequest Request payload for `sdk.api.crdt.getCrdtData`. | Field | Type | Required | Description | | ---------------- | ----- | -------- | ------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | Yes | Document ID. | | `editorId` | `str` | No | Specific editor; omit to fetch all editors. | ### GetCrdtDataResponse Response payload for `sdk.api.crdt.getCrdtData`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'CRDT data retrieved successfully.', 'data': [ { 'data': 'Hello, collaborative world!', # text | map | array | xml — depends on store type 'id': 'my-collab-note', 'lastUpdate': '2025-01-20T10:30:00.000Z', 'lastUpdatedBy': 'user-123', 'sessionId': 'session-abc-456' } ] } } ``` ### GetDeleteUserDataStatusRequest Request payload for `sdk.api.gdpr.getDeleteUserDataStatus`. | Field | Type | Required | Description | | ------- | ----- | -------- | --------------------------------------- | | `jobId` | `str` | Yes | Job ID returned by `deleteAllUserData`. | ### GetDeleteUserDataStatusResponse Response payload for `sdk.api.gdpr.getDeleteUserDataStatus`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Data fetched successfully.', 'data': { 'isDeleteCompleted': True, 'tasksLeft': 0, 'lastTaskCompletedTime': 1748972106739 } } } ``` ### GetDocumentsRequest Request payload for `sdk.api.documents.getDocuments`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | ---------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentIds` | `list[str]` | No | Filter by specific document IDs. | | `folderId` | `str` | No | Restrict to documents in a folder. | ### GetDocumentsResponse Response payload for `sdk.api.documents.getDocuments`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Document(s) retrieved successfully.', 'data': [ { 'documentName': 'yourDocumentName', 'disabled': False, 'accessType': 'public', 'id': 'yourDocumentId' } ], 'pageToken': 'nextPageToken' } } ``` ### GetDomainsRequest Request payload for `sdk.api.workspace.getDomains`. | Field | Type | Required | Description | | ----- | ---- | -------- | ------------------------------------------------------------------------------ | | — | — | — | Empty request — no body fields. Workspace is identified by API key in headers. | ### GetDomainsResponse Response payload for `sdk.api.workspace.getDomains`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Allowed domains retrieved successfully.', 'data': { 'allowedDomains': ['localhost', '127.0.0.1', 'example.com'] } } } ``` ### GetEmailConfigRequest Request payload for `sdk.api.workspace.getEmailConfig`. | Field | Type | Required | Description | | ----- | ---- | -------- | ------------------------------------------------------------------------------ | | — | — | — | Empty request — no body fields. Workspace is identified by API key in headers. | ### GetEmailConfigResponse Response payload for `sdk.api.workspace.getEmailConfig`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Email configuration retrieved successfully.', 'data': { 'useEmailService': False, 'emailServiceConfig': { 'type': 'default', 'apiKey': '', 'fromEmail': '', 'fromCompany': '', 'commentTemplateId': '', 'tagTemplateId': '' } } } } ``` ### GetEmailStatusRequest Request payload for `sdk.api.workspace.getEmailStatus`. | Field | Type | Required | Description | | ------------ | ----- | -------- | ----------------------- | | `ownerEmail` | `str` | Yes | Email address to check. | ### GetEmailStatusResponse Response payload for `sdk.api.workspace.getEmailStatus`. Message reflects verification state. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Email verified and workspace reactivated', 'data': { 'verified': True } } } ``` ### GetFoldersRequest Request payload for `sdk.api.folders.getFolders`. | Field | Type | Required | Description | | ---------------- | ----- | -------- | ---------------------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `folderId` | `str` | No | Restrict to a specific folder and its subfolders. Omit to fetch all folders. | ### GetFoldersResponse Response payload for `sdk.api.folders.getFolders`. Top-level folders include nested `subFolders` arrays when applicable. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Folders retrieved successfully.', 'data': [ { 'folderId': 'folderId1', 'folderName': 'Folder 1', 'organizationId': 'yourOrganizationId', 'parentFolderId': 'root', 'createdAt': 1738695077691, 'lastUpdated': 1738695077691, 'subFolders': [ { 'folderId': 'childFolderId1', 'folderName': 'Child Folder 1', 'parentFolderId': 'folderId1', 'createdAt': 1738695615706, 'lastUpdated': 1738698727591 } ] } ] } } ``` ### GetNotificationConfigRequest Request payload for `sdk.api.notifications.getNotificationConfig`. | Field | Type | Required | Description | | ----------------------- | ----------- | -------- | ------------------------------------------ | | `organizationId` | `str` | Yes | Organization ID. | | `documentIds` | `list[str]` | No | Restrict to specific documents. | | `userId` | `str` | Yes | User whose preferences should be returned. | | `getOrganizationConfig` | `bool` | No | Also include org-level defaults. | ### GetNotificationConfigResponse Response payload for `sdk.api.notifications.getNotificationConfig`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'User config fetched successfully.', 'data': [ { 'config': {'inbox': 'ALL', 'email': 'ALL'}, 'metadata': { 'organizationId': 'org1', 'apiKey': 'API_KEY', 'documentId': 'doc1', 'userId': 'USER_ID1' } } ] } } ``` ### GetNotificationsRequest Request payload for `sdk.api.notifications.getNotifications`. | Field | Type | Required | Description | | ----------------- | ----------- | -------- | ------------------------------------------------------ | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | No | Restrict to notifications on a specific document. | | `locationId` | `str` | No | Restrict to notifications at a specific location. | | `userId` | `str` | No | Restrict to notifications targeted at a specific user. | | `notificationIds` | `list[str]` | No | Fetch specific notifications by ID. | | `pageSize` | `int` | No | Number of items per page. | | `pageToken` | `str` | No | Pagination token from a previous call. | | `order` | `str` | No | Sort order, `asc` or `desc`. | ### GetNotificationsResponse Response payload for `sdk.api.notifications.getNotifications`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Notification(s) retrieved successfully.', 'data': [ { 'id': 'notificationId', 'notificationSource': 'custom', 'notificationSourceData': {}, 'actionUser': {'email': 'user@example.com', 'name': 'User Name', 'userId': 'yourUserId'}, 'displayBodyMessage': 'This is body message (Secondary message)', 'displayHeadlineMessageTemplate': 'Template with {actionUser}, {recipientUser}, {customVar}', 'displayHeadlineMessageTemplateData': { 'actionUser': {'email': 'user@example.com', 'name': 'User Name', 'userId': 'yourUserId'}, 'recipientUser': {'email': 'recipient@example.com', 'name': 'Recipient Name', 'userId': 'recipientUserId'} }, 'metadata': {'apiKey': '...', 'documentId': '...', 'organizationId': '...'}, 'notifyUsers': {'yourNotifyUserId': True}, 'notifyUsersByUserId': {'yourNotifyUserById': True}, 'timestamp': 1722409519944 } ], 'pageToken': 'nextPageToken' } } ``` ### GetOrganizationsRequest Request payload for `sdk.api.organizations.getOrganizations`. | Field | Type | Required | Description | | ----------------- | ----------- | -------- | ---------------------------------------------------------------------- | | `organizationIds` | `list[str]` | No | Filter by organization IDs. Limit: 30 IDs per call. Omit to fetch all. | | `pageSize` | `int` | No | Number of items per page. Default: 1000. | | `pageToken` | `str` | No | Pagination token returned by a previous call. | ### GetOrganizationsResponse Response payload for `sdk.api.organizations.getOrganizations`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Organization(s) retrieved successfully.', 'data': [ { 'id': 'yourOrganizationId', 'organizationName': 'Your Organization Name', 'disabled': False # other metadata fields may be included here } # ... more organizations if multiple were retrieved ], 'nextPageToken': 'pageToken' } } ``` ### GetPermissionsRequest Request payload for `sdk.api.accessControl.getPermissions`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | ------------------------------------------- | | `organizationId` | `str` | Yes | Organization to query. | | `userIds` | `list[str]` | Yes | Users whose permissions should be returned. | | `folderIds` | `list[str]` | No | Include these folders in the result. | | `documentIds` | `list[str]` | No | Include these documents in the result. | ### GetPermissionsResponse Response payload for `sdk.api.accessControl.getPermissions`. Keyed by `userId`. When using Access Context, includes `context.accessFields` listing the context values the user has access to. ```python theme={null} { 'result': { 'status': 'success', 'message': 'User permissions retrieved successfully.', 'data': { '1.1': { 'folders': { 'folder2': {'accessRole': 'editor', 'accessType': 'restricted'} }, 'documents': { 'document1': {'accessRole': 'viewer', 'accessType': 'restricted'} }, 'organization': { 'org1': {'accessRole': 'editor'} } } } } } ``` ### GetReactionResolverRequest Request payload for `sdk.selfHosting.reactions.getReactions`. | Field | Type | Required | Description | | ---------------- | ----- | -------- | ------------------------------------- | | `organizationId` | `str` | Yes | Organization the reactions belong to. | | `documentId` | `str` | Yes | Document the reactions live on. | ### GetRecordingsRequest Request payload for `sdk.api.recordings.getRecordings`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | ---------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | No | Restrict to recordings on a specific document. | | `recordingIds` | `list[str]` | No | Filter by specific recording IDs. | | `pageSize` | `int` | No | Number of results per page. Minimum: 1. | | `pageToken` | `str` | No | Pagination cursor returned from a previous response. | ### GetRecordingsResponse Response payload for `sdk.api.recordings.getRecordings`. ```python theme={null} { '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' } } ``` ### GetUserResolverRequest Request payload for `sdk.selfHosting.users.getUsers`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | --------------------------------- | | `organizationId` | `str` | Yes | Organization the users belong to. | | `userIds` | `list[str]` | No | Filter by specific user IDs. | ### GetUsersRequest Request payload for `sdk.api.users.getUsers`. | Field | Type | Required | Description | | -------------------------- | ----------- | -------- | ----------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | No | Restrict to users on a specific document. | | `folderId` | `str` | No | Restrict to users in a specific folder. | | `userIds` | `list[str]` | No | Filter by specific user IDs. | | `organizationUserGroupIds` | `list[str]` | No | Filter by user-group IDs. | | `allDocuments` | `bool` | No | Return users across all documents. | | `groupByDocumentId` | `bool` | No | Group results by `documentId`. | | `pageSize` | `int` | No | Items per page. | | `pageToken` | `str` | No | Pagination token from a previous call. | ### GetUsersResponse Response payload for `sdk.api.users.getUsers`. With `groupByDocumentId`, `data` is a dict keyed by document ID instead of a list. ```python theme={null} { 'result': { 'status': 'success', 'message': 'User(s) retrieved successfully.', 'data': [ {'email': 'userEmail@domain.com', 'name': 'userName', 'userId': 'yourUserId'} ], 'nextPageToken': 'pageToken' } } ``` ### GetWebhookConfigRequest Request payload for `sdk.api.workspace.getWebhookConfig`. | Field | Type | Required | Description | | ----- | ---- | -------- | ------------------------------------------------------------------------------ | | — | — | — | Empty request — no body fields. Workspace is identified by API key in headers. | ### GetWebhookConfigResponse Response payload for `sdk.api.workspace.getWebhookConfig`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Webhook configuration retrieved successfully.', 'data': { 'useWebhookService': False, 'webhookServiceConfig': { 'authToken': '', 'rawNotificationUrl': '', 'processedNotificationUrl': '' } } } } ``` ### GetWorkspaceRequest Request payload for `sdk.api.workspace.getWorkspace`. | Field | Type | Required | Description | | ----- | ---- | -------- | ------------------------------------------------------------------------------ | | — | — | — | Empty request — no body fields. Workspace is identified by API key in headers. | ### GetWorkspaceResponse Response payload for `sdk.api.workspace.getWorkspace`. ```python theme={null} { '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' } } } } } ``` ### MigrateDocumentsRequest Request payload for `sdk.api.documents.migrateDocuments`. | Field | Type | Required | Description | | ---------------- | ----- | -------- | ------------------------------------- | | `organizationId` | `str` | Yes | Organization the document belongs to. | | `documentId` | `str` | Yes | Existing document ID. | | `newDocumentId` | `str` | Yes | New document ID to migrate to. | ### MigrateDocumentsResponse Response payload for `sdk.api.documents.migrateDocuments`. Returns a `migrationId` to poll via `migrateDocumentsStatus`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Document migration started successfully.', 'data': { 'migrationId': 'yourMigrationId' } } } ``` ### MigrateDocumentsStatusRequest Request payload for `sdk.api.documents.migrateDocumentsStatus`. | Field | Type | Required | Description | | ---------------- | ----- | -------- | -------------------------------------- | | `organizationId` | `str` | Yes | Organization the migration belongs to. | | `migrationId` | `str` | Yes | ID returned from `migrateDocuments`. | ### MigrateDocumentsStatusResponse Response payload for `sdk.api.documents.migrateDocumentsStatus`. ```python theme={null} { 'result': { 'status': 'success', 'message': 'Migration status retrieved successfully.', 'data': { 'migrationId': 'yourMigrationId', 'status': 'completed' # or 'in_progress' } } } ``` ### MoveDocumentsRequest Request payload for `sdk.api.documents.moveDocuments`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | ------------------------------------- | | `organizationId` | `str` | Yes | Organization the documents belong to. | | `documentIds` | `list[str]` | Yes | IDs of documents to move. | | `folderId` | `str` | Yes | Destination folder ID. | ### RemovePermissionsRequest Request payload for `sdk.api.accessControl.removePermissions`. | Field | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userId` | `str` | Yes | User whose permissions should be revoked. | | `permissions` | `dict` | Yes | Object with `resources`: array of resource objects. Each resource has `type` (`organization`, `document`, or `folder`), `id`, and optional `organizationId` (required when `type` is `document`). | ### ResetAuthTokenRequest Request payload for `sdk.api.workspace.resetAuthToken`. | Field | Type | Required | Description | | -------- | ----- | -------- | ------------------------------------------- | | `apiKey` | `str` | Yes | API key whose auth token should be rotated. | ### SaveAttachmentResolverRequest Request payload for `sdk.selfHosting.attachments.saveAttachment`. | Field | Type | Required | Description | | ---------------- | ------ | -------- | ----------------------------------------------- | | `organizationId` | `str` | Yes | Organization the attachment belongs to. | | `documentId` | `str` | Yes | Document the attachment belongs to. | | `attachmentId` | `str` | Yes | Unique ID for the attachment. | | `metadata` | `dict` | No | Arbitrary metadata to store alongside the file. | ### SaveCommentResolverRequest Request payload for `sdk.selfHosting.comments.saveComments`. | Field | Type | Required | Description | | -------------------- | ------------ | -------- | ------------------------------------ | | `organizationId` | `str` | Yes | Organization the comments belong to. | | `documentId` | `str` | Yes | Document the comments live on. | | `commentAnnotations` | `list[dict]` | Yes | Annotation/comment data to upsert. | ### SaveReactionResolverRequest Request payload for `sdk.selfHosting.reactions.saveReactions`. | Field | Type | Required | Description | | ---------------- | ------------ | -------- | ------------------------------------- | | `organizationId` | `str` | Yes | Organization the reactions belong to. | | `documentId` | `str` | Yes | Document the reactions live on. | | `reactions` | `list[dict]` | Yes | Reaction objects to upsert. | ### SendLoginLinkRequest Request payload for `sdk.api.workspace.sendLoginLink`. | Field | Type | Required | Description | | ------------- | ----- | -------- | --------------------------------- | | `email` | `str` | Yes | Recipient email address. | | `continueUrl` | `str` | Yes | URL to redirect to after sign-in. | ### SetNotificationConfigRequest Request payload for `sdk.api.notifications.setNotificationConfig`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | ----------------------------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization the users belong to. | | `documentIds` | `list[str]` | No | Restrict the config update to specific documents. | | `userIds` | `list[str]` | Yes | Users whose preferences should be updated. | | `config` | `dict` | Yes | Map of channel → level (e.g. `inbox`, `email`, `slack` set to `ALL`/`MINE`/`NONE`). | ### UpdateActivitiesRequest Request payload for `sdk.api.activities.updateActivities`. | Field | Type | Required | Description | | ---------------- | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `activities` | `list[dict]` | Yes | Activity objects to update; each must include `id` and may set `changes`, `entityData`, `entityTargetData`, `displayMessageTemplate`, `displayMessageTemplateData`, `actionIcon`. | ### UpdateApiKeyRequest Request payload for `sdk.api.workspace.updateApiKey`. | Field | Type | Required | Description | | ------------ | ----- | -------- | ------------------ | | `apiKey` | `str` | Yes | API key to update. | | `apiKeyName` | `str` | Yes | New display name. | ### UpdateCommentAnnotationsRequest Request payload for `sdk.api.commentAnnotations.updateCommentAnnotations`. | Field | Type | Required | Description | | ---------------- | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | Yes | Document ID. | | `locationIds` | `list[str]` | No | Filter target annotations by location IDs. | | `userIds` | `list[str]` | No | Filter target annotations by author user IDs. | | `annotationIds` | `list[str]` | No | IDs of annotations to update. | | `updatedData` | `dict` | No | Fields to update on each annotation. Supports `location`, `targetElement`, `from`, `status` (`{id, name, type, color, lightColor, svg, iconUrl}`), `assignedTo`, `context`, `priority`. | | `updateUsers` | `list[dict]` | No | Replace users in matched annotations: each item has required `oldUser` (`{userId}`) and `newUser` (`{userId, name?, email?}`). | ### UpdateCommentsRequest Request payload for `sdk.api.commentAnnotations.updateComments`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | ----------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | Yes | Document ID. | | `annotationId` | `str` | Yes | Annotation containing the comments. | | `commentIds` | `list[int]` | Yes | IDs of comments to update. | | `updatedData` | `dict` | Yes | Fields to update on each comment. | ### UpdateCrdtDataRequest Request payload for `sdk.api.crdt.updateCrdtData`. | Field | Type | Required | Description | | ---------------- | --------------------- | -------- | ------------------------------------------ | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | Yes | Document ID. | | `editorId` | `str` | Yes | Editor identifier within the document. | | `data` | `str \| dict \| list` | Yes | New CRDT payload. Shape depends on `type`. | | `type` | `str` | Yes | One of `text`, `map`, `array`, or `xml`. | | `contentKey` | `str` | No | Optional sub-key within the editor's data. | ### UpdateDocumentAccessRequest Request payload for `sdk.api.documents.updateDocumentAccess`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | ------------------------------------------------------------------------ | | `organizationId` | `str` | Yes | Organization the documents belong to. | | `documentIds` | `list[str]` | Yes | IDs of documents to update. | | `accessType` | `str` | Yes | One of `organizationPrivate`, `restricted`, `public`. Default: `public`. | ### UpdateDocumentDisableStateRequest Request payload for `sdk.api.documents.updateDocumentDisableState`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | ---------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization the documents belong to. | | `documentIds` | `list[str]` | Yes | IDs of documents to update. | | `disabled` | `bool` | Yes | `True` to disable, `False` to re-enable. Default: `False`. | ### UpdateDocumentsRequest Request payload for `sdk.api.documents.updateDocuments`. | Field | Type | Required | Description | | ---------------- | ------------ | -------- | ----------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documents` | `list[dict]` | Yes | Document objects keyed by `documentId` with updated fields. | ### UpdateEmailConfigRequest Request payload for `sdk.api.workspace.updateEmailConfig`. | Field | Type | Required | Description | | -------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | `useEmailService` | `bool` | No | Whether the email service is enabled. | | `emailServiceConfig` | `dict` | No | Provider-specific config (e.g. SendGrid `type`, `apiKey`, `fromEmail`, `fromCompany`, `commentTemplateId`, `tagTemplateId`). | ### UpdateFolderAccessRequest Request payload for `sdk.api.folders.updateFolderAccess`. | Field | Type | Required | Description | | ---------------- | ----------- | -------- | --------------------------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization the folders belong to. | | `folderIds` | `list[str]` | Yes | IDs of folders whose access should change. | | `accessType` | `str` | Yes | Allowed values: `organizationPrivate`, `restricted`, `public`. Default: `public`. | ### UpdateFolderRequest Request payload for `sdk.api.folders.updateFolder`. | Field | Type | Required | Description | | ---------------- | ------------ | -------- | ----------------------------------------------------------------------------------- | | `organizationId` | `str` | Yes | Organization the folders belong to. | | `folders` | `list[dict]` | Yes | Folder objects with `folderId` (required), `folderName`, optional `parentFolderId`. | ### UpdateNotificationsRequest Request payload for `sdk.api.notifications.updateNotifications`. | Field | Type | Required | Description | | ----------------------- | ------ | -------- | ----------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | No | Restrict update to a specific document. | | `locationId` | `str` | No | Restrict update to a specific location. | | `userId` | `str` | No | Restrict update to notifications for a specific user. | | `verifyUserPermissions` | `bool` | No | When `True`, verifies access before applying updates. | | `notifications` | `dict` | No | Map of notification IDs to fields to update. | ### UpdateOrganizationDisableStateRequest Request payload for `sdk.api.organizations.updateOrganizationDisableState`. | Field | Type | Required | Description | | ----------------- | ----------- | -------- | ----------------------------------------------- | | `organizationIds` | `list[str]` | Yes | IDs of organizations to update. | | `disabled` | `bool` | Yes | `True` to disable access, `False` to re-enable. | ### UpdateOrganizationsRequest Request payload for `sdk.api.organizations.updateOrganizations`. | Field | Type | Required | Description | | --------------- | ------------ | -------- | ---------------------------------------------------------------------------- | | `organizations` | `list[dict]` | Yes | Array of organization objects keyed by `organizationId` with updated fields. | ### UpdatePresenceRequest Request payload for `sdk.api.presence.updatePresence`. | Field | Type | Required | Description | | ---------------- | ------------ | -------- | ------------------------------------------------------------ | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | Yes | Document ID. | | `users` | `list[dict]` | Yes | Users keyed by `userId` with updated fields (e.g. `status`). | ### UpdateUsersRequest Request payload for `sdk.api.users.updateUsers`. | Field | Type | Required | Description | | ---------------- | ------------ | -------- | --------------------------------------------------- | | `organizationId` | `str` | Yes | Organization ID. | | `documentId` | `str` | No | Restrict update to users on a specific document. | | `folderId` | `str` | No | Restrict update to users in a specific folder. | | `users` | `list[dict]` | Yes | User objects keyed by `userId` with updated fields. | ### UpdateWebhookConfigRequest Request payload for `sdk.api.workspace.updateWebhookConfig`. | Field | Type | Required | Description | | ---------------------- | ------ | -------- | -------------------------------------------------------------------------- | | `useWebhookService` | `bool` | No | Whether webhook delivery is enabled. | | `webhookServiceConfig` | `dict` | No | Config with `authToken`, `rawNotificationUrl`, `processedNotificationUrl`. | ## Node SDK Types Request and response types used by the [Velt Node SDK](/backend-sdks/node). Field shapes mirror the TypeScript interfaces published in `@veltdev/node`. Types whose name ends in `(SH)` belong to the `sdk.selfHosting.*` namespace; all others belong to `sdk.api.*`. ### `VeltApiResponse` (Node) Standard envelope for all `sdk.api.*` REST methods. Success and error are mutually exclusive. ```ts theme={null} // Success { result: { status: 'success', message: '...', data: { /* method-specific */ } } } // Error { error: { message: '...', status: 'INTERNAL', details: { /* per-key error info */ } } } ``` ### `VeltSelfHostingResponse` (Node) Standard envelope for all `sdk.selfHosting.*` methods. ```ts theme={null} // Success { success: true, statusCode: 200, data: { /* method-specific */ } } // Error { success: false, statusCode: 500, error: '...', errorCode: 'INTERNAL_ERROR' } ``` ### `AddActivitiesRequest` (Node) Request payload for `sdk.api.activities.addActivities`. | Field | Type | Required | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document the activities belong to. | | `activities` | `Array<{ featureType: string; actionType: string; actionUser: { userId: string; name?: string; email?: string }; displayMessageTemplate: string }>` | Yes | Activity events to log. | ### `AddCommentAnnotationsRequest` (Node) Request payload for `sdk.api.commentAnnotations.addCommentAnnotations`. | Field | Type | Required | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ----------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document the annotations belong to. | | `commentAnnotations` | `Array<{ location: { id: string; locationName: string }; commentData: Array<{ commentText: string; commentHtml: string; from: { userId: string; name: string; email: string } }> }>` | Yes | Annotations to create. | ### `AddCommentsRequest` (Node) Request payload for `sdk.api.commentAnnotations.addComments`. | Field | Type | Required | Description | | ---------------- | ------------------------------------------------------------------------- | -------- | ----------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document the annotation belongs to. | | `annotationId` | `string` | Yes | Annotation to add comments to. | | `commentData` | `Array<{ commentText: string; from: { userId: string; name?: string } }>` | Yes | Comments to add. | ### `AddCrdtDataRequest` (Node) Request payload for `sdk.api.crdt.addCrdtData`. | Field | Type | Required | Description | | ---------------- | ------------------------------------- | -------- | ------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document the editor belongs to. | | `editorId` | `string` | Yes | Editor instance ID. | | `data` | `string \| object` | Yes | Initial editor content. | | `type` | `'text' \| 'map' \| 'array' \| 'xml'` | Yes | CRDT data type. | ### `AddDocumentsRequest` (Node) Request payload for `sdk.api.documents.addDocuments`. | Field | Type | Required | Description | | -------------------- | ------------------------------------------------------ | -------- | ---------------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the documents. | | `documents` | `Array<{ documentId: string; documentName?: string }>` | Yes | Documents to create. | | `createOrganization` | `boolean` | No | Auto-create the organization if missing. | | `folderId` | `string` | No | Folder to create the documents in. | | `createFolder` | `boolean` | No | Auto-create the folder if missing. | ### `AddDomainsRequest` (Node) Request payload for `sdk.api.workspace.addDomains`. | Field | Type | Required | Description | | --------- | ---------- | -------- | ----------------- | | `domains` | `string[]` | Yes | Domains to allow. | ### `AddFolderRequest` (Node) Request payload for `sdk.api.folders.addFolder`. | Field | Type | Required | Description | | -------------------- | -------------------------------------------------- | -------- | ---------------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the folders. | | `folders` | `Array<{ folderId: string; folderName?: string }>` | Yes | Folders to create. | | `createOrganization` | `boolean` | No | Auto-create the organization if missing. | ### `AddNotificationsRequest` (Node) Request payload for `sdk.api.notifications.addNotifications`. | Field | Type | Required | Description | | -------------------------------- | --------------------------------------------------- | -------- | -------------------------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document the notification is about. | | `actionUser` | `{ userId: string; name?: string; email?: string }` | Yes | User who triggered the notification. | | `displayHeadlineMessageTemplate` | `string` | Yes | Headline template (supports `{actionUser}` token). | | `displayBodyMessage` | `string` | Yes | Body text shown in the notification. | | `notifyUsers` | `Array<{ userId: string; name?: string }>` | Yes | Recipients. | | `createOrganization` | `boolean` | No | Auto-create the organization if missing. | | `createDocument` | `boolean` | No | Auto-create the document if missing. | ### `AddOrganizationsRequest` (Node) Request payload for `sdk.api.organizations.addOrganizations`. | Field | Type | Required | Description | | --------------- | -------------------------------------------------------------- | -------- | ------------------------ | | `organizations` | `Array<{ organizationId: string; organizationName?: string }>` | Yes | Organizations to create. | ### `AddPermissionsRequest` (Node) Request payload for `sdk.api.accessControl.addPermissions`. | Field | Type | Required | Description | | ------------- | --------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------- | | `user` | `{ userId: string }` | Yes | User to grant access to. | | `permissions` | `{ resources: Array<{ type: string; id: string; organizationId?: string; accessRole: string; expiresAt?: number }> }` | Yes | Resources and roles to grant. | ### `AddPresenceRequest` (Node) Request payload for `sdk.api.presence.addPresence`. | Field | Type | Required | Description | | ---------------- | ---------------------------------------------------------------------------------------------------- | -------- | ---------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document to set presence on. | | `users` | `Array<{ userId: string; name?: string; email?: string; status?: 'online' \| 'away' \| 'offline' }>` | Yes | Users to add. | ### `AddUserGroupsRequest` (Node) Request payload for `sdk.api.userGroups.addUserGroups`. | Field | Type | Required | Description | | ------------------------ | ------------------------------------------------ | -------- | ---------------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the groups. | | `organizationUserGroups` | `Array<{ groupId: string; groupName?: string }>` | Yes | Groups to create. | | `createOrganization` | `boolean` | No | Auto-create the organization if missing. | ### `AddUsersRequest` (Node) Request payload for `sdk.api.users.addUsers`. | Field | Type | Required | Description | | -------------------- | --------------------------------------------------------------------------------------------- | -------- | ---------------------------------------- | | `organizationId` | `string` | Yes | Organization to add users to. | | `users` | `Array<{ userId: string; name?: string; email?: string; accessRole?: 'editor' \| 'viewer' }>` | Yes | Users to add. | | `createOrganization` | `boolean` | No | Auto-create the organization if missing. | ### `AddUsersToGroupRequest` (Node) Request payload for `sdk.api.userGroups.addUsersToGroup`. | Field | Type | Required | Description | | ------------------------- | ---------- | -------- | --------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the group. | | `organizationUserGroupId` | `string` | Yes | Target group. | | `userIds` | `string[]` | Yes | Users to add. | ### `AskAiRequest` (Node) Request payload for `sdk.api.rewriter.askAi`. | Field | Type | Required | Description | | -------- | -------- | -------- | ------------------------------------------------------------------------- | | `model` | `string` | Yes | Model identifier (e.g., `gpt-4o`, `claude-3-5-sonnet`, `gemini-1.5-pro`). | | `prompt` | `string` | Yes | Instruction for the model. | | `text` | `string` | Yes | Source text to rewrite. | ### `AskAiResponse` (Node) Response shape for `sdk.api.rewriter.askAi`. ```ts theme={null} { result: { success: true, text: 'The rewritten or processed text returned by the model.' } } ``` ### `BroadcastEventRequest` (Node) Request payload for `sdk.api.livestate.broadcastEvent`. | Field | Type | Required | Description | | ----------------- | --------- | -------- | ---------------------------------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document to broadcast on. | | `liveStateDataId` | `string` | Yes | Live-state channel ID. | | `data` | `object` | Yes | Payload to broadcast. | | `merge` | `boolean` | No | If `true`, merge with existing state instead of replacing. | ### `CreateApiKeyRequest` (Node) Request payload for `sdk.api.workspace.createApiKey`. | Field | Type | Required | Description | | ----------------- | ------------------------------- | -------- | -------------------------------- | | `ownerEmail` | `string` | Yes | Email of the workspace owner. | | `type` | `'production' \| 'development'` | Yes | API key type. | | `createAuthToken` | `boolean` | No | Also mint an auth token. | | `apiKeyName` | `string` | No | Display name. | | `allowedDomains` | `string[]` | No | Domains allowed to use this key. | ### `CreateWorkspaceRequest` (Node) Request payload for `sdk.api.workspace.createWorkspace`. | Field | Type | Required | Description | | --------------- | -------- | -------- | ------------------------------- | | `ownerEmail` | `string` | Yes | Email of the workspace owner. | | `workspaceName` | `string` | Yes | Display name for the workspace. | | `name` | `string` | Yes | Owner's full name. | ### `DeleteActivitiesRequest` (Node) Request payload for `sdk.api.activities.deleteActivities`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | ---------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document to delete activities for. | ### `DeleteAllUserDataRequest` (Node) Request payload for `sdk.api.gdpr.deleteAllUserData`. | Field | Type | Required | Description | | ----------------- | ---------- | -------- | ----------------------------------------- | | `userIds` | `string[]` | Yes | Users whose data should be deleted. | | `organizationIds` | `string[]` | No | Restrict deletion to these organizations. | ### `DeleteAttachmentRequest` SH (Node) Request payload for `sdk.selfHosting.getAttachments().deleteAttachment`. | Field | Type | Required | Description | | -------------- | ---------------------------- | -------- | --------------------- | | `attachmentId` | `number` | Yes | Attachment to delete. | | `metadata` | `{ organizationId: string }` | Yes | Organization context. | ### `DeleteCommentAnnotationsRequest` (Node) Request payload for `sdk.api.commentAnnotations.deleteCommentAnnotations`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | ----------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document the annotations belong to. | | `annotationIds` | `string[]` | Yes | Annotations to delete. | ### `DeleteCommentRequest` SH (Node) Request payload for `sdk.selfHosting.getComments().deleteComment`. | Field | Type | Required | Description | | --------------------- | ---------------------------- | -------- | ----------------------------- | | `commentAnnotationId` | `string` | Yes | Comment annotation to delete. | | `metadata` | `{ organizationId: string }` | Yes | Organization context. | ### `DeleteCommentsRequest` (Node) Request payload for `sdk.api.commentAnnotations.deleteComments`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | ---------------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document the comments belong to. | | `annotationId` | `string` | Yes | Annotation that contains the comments. | | `commentIds` | `number[]` | No | Comments to delete (omit to delete all). | ### `DeleteDocumentsRequest` (Node) Request payload for `sdk.api.documents.deleteDocuments`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | ------------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the documents. | | `documentIds` | `string[]` | Yes | Documents to delete. | ### `DeleteDomainsRequest` (Node) Request payload for `sdk.api.workspace.deleteDomains`. | Field | Type | Required | Description | | --------- | ---------- | -------- | ------------------ | | `domains` | `string[]` | Yes | Domains to remove. | ### `DeleteFolderRequest` (Node) Request payload for `sdk.api.folders.deleteFolder`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | ---------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the folder. | | `folderId` | `string` | Yes | Folder to delete. | ### `DeleteNotificationRequest` SH (Node) Request payload for `sdk.selfHosting.getNotifications().deleteNotification`. | Field | Type | Required | Description | | ---------------- | -------------------------------------------- | -------- | ----------------------------------- | | `notificationId` | `string` | Yes | Notification to delete. | | `metadata` | `{ organizationId: string; userId: string }` | Yes | Organization and recipient context. | ### `DeleteNotificationsRequest` (Node) Request payload for `sdk.api.notifications.deleteNotifications`. | Field | Type | Required | Description | | ----------------- | ---------- | -------- | --------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `userId` | `string` | Yes | Owner of the notifications. | | `notificationIds` | `string[]` | Yes | Notifications to delete. | ### `DeleteOrganizationsRequest` (Node) Request payload for `sdk.api.organizations.deleteOrganizations`. | Field | Type | Required | Description | | ----------------- | ---------- | -------- | ------------------------------- | | `organizationIds` | `string[]` | Yes | IDs of organizations to delete. | ### `DeletePresenceRequest` (Node) Request payload for `sdk.api.presence.deletePresence`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | --------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document to remove presence from. | | `userIds` | `string[]` | Yes | Users to remove. | ### `DeleteReactionRequest` SH (Node) Request payload for `sdk.selfHosting.getReactions().deleteReaction`. | Field | Type | Required | Description | | ---------------------- | ---------------------------- | -------- | ------------------------------ | | `reactionAnnotationId` | `string` | Yes | Reaction annotation to delete. | | `metadata` | `{ organizationId: string }` | Yes | Organization context. | ### `DeleteRecorderAnnotationRequest` SH (Node) Request payload for `sdk.selfHosting.getRecorder().deleteRecorderAnnotation`. | Field | Type | Required | Description | | ---------------------- | ---------------------------- | -------- | ------------------------------ | | `recorderAnnotationId` | `string` | Yes | Recorder annotation to delete. | | `metadata` | `{ organizationId: string }` | Yes | Organization context. | ### `DeleteUsersFromGroupRequest` (Node) Request payload for `sdk.api.userGroups.deleteUsersFromGroup`. | Field | Type | Required | Description | | ------------------------- | ---------- | -------- | ---------------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the group. | | `organizationUserGroupId` | `string` | Yes | Target group. | | `userIds` | `string[]` | Yes | Users to remove. | | `deleteAll` | `boolean` | No | Remove all users from group when `true`. | ### `DeleteUsersRequest` (Node) Request payload for `sdk.api.users.deleteUsers`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | ---------------------------------- | | `organizationId` | `string` | Yes | Organization to remove users from. | | `userIds` | `string[]` | Yes | Users to remove. | ### `GenerateSignatureRequest` (Node) Request payload for `sdk.api.accessControl.generateSignature`. | Field | Type | Required | Description | | ------------- | ----------------------------------------------------------------------------------------------------- | -------- | -------------------- | | `permissions` | `Array<{ userId: string; resourceId: string; type: string; hasAccess: boolean; accessRole: string }>` | Yes | Permissions to sign. | ### `GenerateSignatureResponse` (Node) Response shape for `sdk.api.accessControl.generateSignature`. ```ts theme={null} { result: { status: 'success', message: 'Signature generated successfully.', data: { signature: 'a1b2c3d4e5f6...' } } } ``` ### `GenerateTokenRequest` (Node) Request payload for `sdk.api.accessControl.generateToken`. | Field | Type | Required | Description | | ---------------- | ------------------------------------------------------------------------------------------------- | -------- | ---------------------------------- | | `userId` | `string` | Yes | User to mint the token for. | | `userProperties` | `{ name?: string; email?: string; isAdmin?: boolean }` | No | User profile properties. | | `permissions` | `{ resources: Array<{ type: string; id: string; organizationId?: string; accessRole: string }> }` | No | Permissions to embed in the token. | ### `GenerateTokenResponse` (Node) Response shape for `sdk.api.accessControl.generateToken`. ```ts theme={null} { result: { status: 'success', message: 'Token generated successfully.', data: { token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' } } } ``` ### `GetActivitiesRequest` (Node) Request payload for `sdk.api.activities.getActivities`. | Field | Type | Required | Description | | ---------------- | ----------------- | -------- | --------------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document to query. | | `featureTypes` | `string[]` | No | Filter activities by feature types. | | `order` | `'asc' \| 'desc'` | No | Sort order for results. | | `pageSize` | `number` | No | Maximum number of activities to return. | ### `GetActivitiesResponse` (Node) Response shape for `sdk.api.activities.getActivities`. ```ts theme={null} { 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' } } ``` ### `GetActivitiesSelfHostingRequest` SH (Node) Request payload for `sdk.selfHosting.getActivities().getActivities`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | ----------------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | No | Filter activities to a specific document. | ### `GetAllUserDataRequest` (Node) Request payload for `sdk.api.gdpr.getAllUserData`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------------------------------ | | `organizationId` | `string` | Yes | Organization to export from. | | `userId` | `string` | Yes | User to export. | | `pageToken` | `string` | No | Pagination cursor returned from a previous call. | ### `GetAllUserDataResponse` (Node) Response shape for `sdk.api.gdpr.getAllUserData`. ```ts theme={null} { 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' } } ``` ### `GetApiKeyMetadataResponse` (Node) Response shape for `sdk.api.workspace.getApiKeyMetadata`. ```ts theme={null} { result: { status: 'success', message: 'API key metadata retrieved successfully.', data: { defaultDocumentAccessType: 'public', planInfo: { type: 'sdk test' }, ownerEmail: 'owner@example.com' } } } ``` ### `GetApiKeysRequest` (Node) Request payload for `sdk.api.workspace.getApiKeys`. | Field | Type | Required | Description | | ----------- | -------- | -------- | ------------------ | | `pageSize` | `number` | No | Results per page. | | `pageToken` | `string` | No | Pagination cursor. | ### `GetApiKeysResponse` (Node) Response shape for `sdk.api.workspace.getApiKeys`. ```ts theme={null} { 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' } } ``` ### `GetAuthTokensRequest` (Node) Request payload for `sdk.api.workspace.getAuthTokens`. | Field | Type | Required | Description | | -------- | -------- | -------- | ----------------- | | `apiKey` | `string` | Yes | API key to query. | ### `GetAuthTokensResponse` (Node) Response shape for `sdk.api.workspace.getAuthTokens`. ```ts theme={null} { result: { status: 'success', message: 'Auth tokens retrieved successfully.', data: { apiKey: 'velt_api_key_1', authTokens: [ { token: 'eyJhbGciOiJSUzI1NiIs...', name: 'Default Auth Token', domains: [] } ] } } } ``` ### `GetCommentAnnotationsCountRequest` (Node) Request payload for `sdk.api.commentAnnotations.getCommentAnnotationsCount`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | ----------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentIds` | `string[]` | Yes | Documents to count annotations for. | | `userId` | `string` | No | Filter counts to a specific user. | ### `GetCommentAnnotationsCountResponse` (Node) Response shape for `sdk.api.commentAnnotations.getCommentAnnotationsCount`. ```ts theme={null} { result: { status: 'success', message: 'Comment count retrieved successfully.', data: { 'doc-1': { total: 4, unread: 2 }, 'doc-2': { total: 2, unread: 0 } } } } ``` ### `GetCommentAnnotationsRequest` (Node) Request payload for `sdk.api.commentAnnotations.getCommentAnnotations`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | ---------------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document to query. | | `statusIds` | `string[]` | No | Filter annotations by status IDs. | | `pageSize` | `number` | No | Maximum number of annotations to return. | ### `GetCommentAnnotationsResponse` (Node) Response shape for `sdk.api.commentAnnotations.getCommentAnnotations`. ```ts theme={null} { result: { status: 'success', message: 'Annotations fetched successfully.', data: [ { type: 'comment', comments: [ { commentId: 123456, commentText: 'This is a sample comment text.', commentHtml: '

This is a sample comment text.

', from: { userId: 'user123', name: 'John Doe', email: 'john.doe@example.com' }, createdAt: 1687344600000 } ], status: { id: 'OPEN', name: 'Open', type: 'default' } } ] } } ``` ### `GetCommentsRequest` (Node) Request payload for `sdk.api.commentAnnotations.getComments`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | -------------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document to query. | | `annotationId` | `string` | Yes | Annotation that contains the comments. | | `userIds` | `string[]` | No | Filter comments by user IDs. | ### `GetCommentsRequest` SH (Node) Request payload for `sdk.selfHosting.getComments().getComments`. | Field | Type | Required | Description | | ---------------------- | ---------- | -------- | --------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `commentAnnotationIds` | `string[]` | No | Specific annotation IDs to fetch. | | `documentIds` | `string[]` | No | Documents to fetch comments for. | ### `GetCommentsResponse` (Node) Response shape for `sdk.api.commentAnnotations.getComments`. ```ts theme={null} { result: { status: 'success', message: 'Comments(s) retrieved successfully.', data: [ { commentId: 153783, commentText: 'Sample Comment Text', commentHtml: '
Hello Updated 2
', from: { userId: 'yourUserId', name: 'User Name', email: 'user@example.com' }, lastUpdated: '2024-06-20T09:53:42.258Z', status: 'added', type: 'text' } ] } } ``` ### `GetCrdtDataRequest` (Node) Request payload for `sdk.api.crdt.getCrdtData`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | ---------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document to query. | | `editorId` | `string` | No | Filter to a specific editor. | ### `GetCrdtDataResponse` (Node) Response shape for `sdk.api.crdt.getCrdtData`. ```ts theme={null} { 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' } ] } } ``` ### `GetDeleteUserDataStatusRequest` (Node) Request payload for `sdk.api.gdpr.getDeleteUserDataStatus`. | Field | Type | Required | Description | | ------- | -------- | -------- | ----------------------------------------- | | `jobId` | `string` | Yes | Job ID returned from `deleteAllUserData`. | ### `GetDeleteUserDataStatusResponse` (Node) Response shape for `sdk.api.gdpr.getDeleteUserDataStatus`. ```ts theme={null} { result: { status: 'success', message: 'Data fetched successfully.', data: { isDeleteCompleted: true, tasksLeft: 0, lastTaskCompletedTime: 1748972106739 } } } ``` ### `GetDocumentsRequest` (Node) Request payload for `sdk.api.documents.getDocuments`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | -------------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the documents. | | `documentIds` | `string[]` | No | Documents to fetch. | | `folderId` | `string` | No | Folder to scope the query to. | | `pageSize` | `number` | No | Maximum number of documents to return. | ### `GetDocumentsResponse` (Node) Response shape for `sdk.api.documents.getDocuments`. ```ts theme={null} { result: { status: 'success', message: 'Document(s) retrieved successfully.', data: [ { documentName: 'yourDocumentName', disabled: false, accessType: 'public', id: 'yourDocumentId' } ], pageToken: 'nextPageToken' } } ``` ### `GetDomainsResponse` (Node) Response shape for `sdk.api.workspace.getDomains`. ```ts theme={null} { result: { status: 'success', message: 'Allowed domains retrieved successfully.', data: { allowedDomains: ['localhost', '127.0.0.1', 'example.com'] } } } ``` ### `GetEmailConfigResponse` (Node) Response shape for `sdk.api.workspace.getEmailConfig`. ```ts theme={null} { result: { status: 'success', message: 'Email configuration retrieved successfully.', data: { useEmailService: false, emailServiceConfig: { type: 'default', apiKey: '', fromEmail: '', fromCompany: '', commentTemplateId: '', tagTemplateId: '' } } } } ``` ### `GetEmailStatusRequest` (Node) Request payload for `sdk.api.workspace.getEmailStatus`. | Field | Type | Required | Description | | ------------ | -------- | -------- | --------------- | | `ownerEmail` | `string` | Yes | Email to check. | ### `GetEmailStatusResponse` (Node) Response shape for `sdk.api.workspace.getEmailStatus`. ```ts theme={null} { result: { status: 'success', message: 'Email verified and workspace reactivated', data: { verified: true } } } ``` ### `GetFoldersRequest` (Node) Request payload for `sdk.api.folders.getFolders`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | ----------------------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the folder. | | `folderId` | `string` | No | Folder to fetch. | | `maxDepth` | `number` | No | Maximum nesting depth to include in the result. | ### `GetFoldersResponse` (Node) Response shape for `sdk.api.folders.getFolders`. ```ts theme={null} { result: { status: 'success', message: 'Folders retrieved successfully.', data: [ { folderId: 'folder-1', folderName: 'Folder 1', organizationId: 'org-123', parentFolderId: 'root', createdAt: 1738695615706, lastUpdated: 1738696287859 } ] } } ``` ### `GetNotificationConfigRequest` (Node) Request payload for `sdk.api.notifications.getNotificationConfig`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | -------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `userId` | `string` | Yes | User whose preferences to fetch. | ### `GetNotificationConfigResponse` (Node) Response shape for `sdk.api.notifications.getNotificationConfig`. ```ts theme={null} { 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' } } ] } } ``` ### `GetNotificationsRequest` (Node) Request payload for `sdk.api.notifications.getNotifications`. | Field | Type | Required | Description | | ---------------- | ----------------- | -------- | ---------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `userId` | `string` | Yes | User whose notifications to fetch. | | `pageSize` | `number` | No | Results per page. | | `order` | `'asc' \| 'desc'` | No | Sort order. | ### `GetNotificationsResponse` (Node) Response shape for `sdk.api.notifications.getNotifications`. ```ts theme={null} { 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' } } ``` ### `GetNotificationsSelfHostingRequest` SH (Node) Request payload for `sdk.selfHosting.getNotifications().getNotifications`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | ---------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `userId` | `string` | Yes | User whose notifications to fetch. | ### `GetOrganizationsRequest` (Node) Request payload for `sdk.api.organizations.getOrganizations`. | Field | Type | Required | Description | | ----------------- | ---------- | -------- | ------------------------------------------------ | | `organizationIds` | `string[]` | No | IDs of organizations to fetch (omit to get all). | | `pageSize` | `number` | No | Maximum number of organizations to return. | | `pageToken` | `string` | No | Token for fetching the next page of results. | ### `GetOrganizationsResponse` (Node) Response shape for `sdk.api.organizations.getOrganizations`. ```ts theme={null} { result: { status: 'success', message: 'Organization(s) retrieved successfully.', data: [ { id: 'yourOrganizationId', organizationName: 'Your Organization Name', disabled: false } ], nextPageToken: 'pageToken' } } ``` ### `GetPermissionsRequest` (Node) Request payload for `sdk.api.accessControl.getPermissions`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | -------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `userIds` | `string[]` | No | Filter to these users. | | `documentIds` | `string[]` | No | Filter to these documents. | ### `GetPermissionsResponse` (Node) Response shape for `sdk.api.accessControl.getPermissions`. ```ts theme={null} { result: { status: 'success', message: 'User permissions retrieved successfully.', data: { 'user-1': { folders: { 'folder-1': { accessRole: 'editor', accessType: 'restricted' } }, documents: { 'doc-1': { accessRole: 'viewer', accessType: 'restricted' } }, organization: { 'org-123': { accessRole: 'editor' } } } } } } ``` ### `GetReactionsRequest` SH (Node) Request payload for `sdk.selfHosting.getReactions().getReactions`. | Field | Type | Required | Description | | ----------------------- | ---------- | -------- | ------------------------------------------ | | `organizationId` | `string` | Yes | Organization context. | | `reactionAnnotationIds` | `string[]` | No | Specific reaction annotation IDs to fetch. | | `documentIds` | `string[]` | No | Documents to fetch reactions for. | ### `GetRecorderAnnotationsRequest` SH (Node) Request payload for `sdk.selfHosting.getRecorder().getRecorderAnnotations`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | -------------------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentIds` | `string[]` | No | Documents to fetch recorder annotations for. | ### `GetRecordingsRequest` (Node) Request payload for `sdk.api.recordings.getRecordings`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | -------------------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | No | Document to fetch recordings for. | | `recordingIds` | `string[]` | No | Specific recording IDs to fetch. | | `pageSize` | `number` | No | Maximum number of recordings to return. | | `pageToken` | `string` | No | Token for fetching the next page of results. | ### `GetRecordingsResponse` (Node) Response shape for `sdk.api.recordings.getRecordings`. ```ts theme={null} { 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' } } ``` ### `GetUsersRequest` (Node) Request payload for `sdk.api.users.getUsers`. | Field | Type | Required | Description | | ------------------- | ---------- | -------- | -------------------------------------------- | | `organizationId` | `string` | Yes | Organization to query. | | `userIds` | `string[]` | No | Users to fetch. | | `documentId` | `string` | No | Scope query to a single document. | | `pageSize` | `number` | No | Maximum number of users to return. | | `allDocuments` | `boolean` | No | Include users across all documents. | | `groupByDocumentId` | `boolean` | No | Return results grouped by document ID. | | `pageToken` | `string` | No | Token for fetching the next page of results. | ### `GetUsersResponse` (Node) Response shape for `sdk.api.users.getUsers`. ```ts theme={null} { result: { status: 'success', message: 'User(s) retrieved successfully.', data: [ { email: 'userEmail@domain.com', name: 'userName', userId: 'yourUserId' } ], nextPageToken: 'pageToken' } } ``` ### `GetUsersSelfHostingRequest` SH (Node) Request payload for `sdk.selfHosting.getUsers().getUsers`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | ------------------------ | | `organizationId` | `string` | Yes | Organization context. | | `userIds` | `string[]` | No | Specific users to fetch. | ### `GetWebhookConfigResponse` (Node) Response shape for `sdk.api.workspace.getWebhookConfig`. ```ts theme={null} { result: { status: 'success', message: 'Webhook configuration retrieved successfully.', data: { useWebhookService: false, webhookServiceConfig: { authToken: '', rawNotificationUrl: '', processedNotificationUrl: '' } } } } ``` ### `GetWorkspaceResponse` (Node) Response shape for `sdk.api.workspace.getWorkspace`. ```ts theme={null} { 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' } } } } } ``` ### `MigrateDocumentsRequest` (Node) Request payload for `sdk.api.documents.migrateDocuments`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the document. | | `documentId` | `string` | Yes | Existing document ID to migrate from. | | `newDocumentId` | `string` | Yes | New document ID to migrate to. | ### `MigrateDocumentsResponse` (Node) Response shape for `sdk.api.documents.migrateDocuments`. ```ts theme={null} { result: { status: 'success', message: 'Document migration started successfully.', data: { migrationId: 'yourMigrationId' } } } ``` ### `MigrateDocumentsStatusRequest` (Node) Request payload for `sdk.api.documents.migrateDocumentsStatus`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | ---------------------------------------- | | `organizationId` | `string` | Yes | Organization that started the migration. | | `migrationId` | `string` | Yes | Job ID returned from `migrateDocuments`. | ### `MigrateDocumentsStatusResponse` (Node) Response shape for `sdk.api.documents.migrateDocumentsStatus`. ```ts theme={null} { result: { status: 'success', message: 'Migration status retrieved successfully.', data: { migrationId: 'yourMigrationId', status: 'completed' } } } ``` ### `MoveDocumentsRequest` (Node) Request payload for `sdk.api.documents.moveDocuments`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | ------------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the documents. | | `documentIds` | `string[]` | Yes | Documents to move. | | `folderId` | `string` | Yes | Destination folder. | ### `RemovePermissionsRequest` (Node) Request payload for `sdk.api.accessControl.removePermissions`. | Field | Type | Required | Description | | ------------- | ----------------------------------------------------------------------------- | -------- | --------------------------- | | `userId` | `string` | Yes | User to revoke access from. | | `permissions` | `{ resources: Array<{ type: string; id: string; organizationId?: string }> }` | Yes | Resources to revoke. | ### `ResetAuthTokenRequest` (Node) Request payload for `sdk.api.workspace.resetAuthToken`. | Field | Type | Required | Description | | -------- | -------- | -------- | ------------------------------------------- | | `apiKey` | `string` | Yes | API key whose auth token should be rotated. | ### `ResolverAuthConfig` (Node) The `resolverAuth` option on `VeltConfig`, configuring `sdk.selfHosting.verifyToken`. See [`verifyToken`](/backend-sdks/node#verifytoken). | Field | Type | Required | Description | | -------- | ---------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- | | `jwt` | [`ResolverAuthJwtConfig`](#resolverauthjwtconfig-node) | No | Built-in JWT/JWKS verification config. | | `verify` | [`ResolverAuthVerifyCallback`](#resolverauthverifycallback-node) | No | Custom verification callback. Takes priority over the built-in `jwt` path when both are configured. | | `header` | `string` | No | Header to read the token from. Default `'Authorization'`. | | `scheme` | `string` | No | Auth scheme prefix. Default `'Bearer'`. Set to `''` to read the raw header value. | ### `ResolverAuthErrorCode` (Node) A union of the 9 machine-readable failure codes returned on [`VerifyTokenResult.errorCode`](#verifytokenresult-node). The same values are 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). | ### `ResolverAuthJwtConfig` (Node) Built-in JWT/JWKS verification config — the `jwt` field on [`ResolverAuthConfig`](#resolverauthconfig-node). | Field | Type | Required | Description | | ------------ | ----------------------------------- | ----------- | --------------------------------------------------------------------------------------- | | `algorithms` | `string[]` | Conditional | Algorithm allowlist (algorithm pinning). Required when using the built-in JWT verifier. | | `jwksUrl` | `string` | No | HTTPS JWKS endpoint (one of jwksUrl / publicKey / secret). | | `publicKey` | `string \| Record` | No | Static PEM public key or JWK object. | | `secret` | `string \| Uint8Array` | No | HMAC secret for HS\* algorithms. | | `issuer` | `string` | No | Expected `iss`; enforced when set. | | `audience` | `string \| string[]` | No | Expected `aud`; enforced when set. | | `leeway` | `number` | No | Clock tolerance in seconds. | | `require` | `string[]` | No | Required claims (e.g. `['exp']`). | ### `ResolverAuthVerifyCallback` (Node) Custom verification callback — the `verify` field on [`ResolverAuthConfig`](#resolverauthconfig-node). Return an object to populate `claims`, a truthy non-object value to accept with `claims` undefined, or a falsy value to fail closed. ```ts theme={null} type ResolverAuthVerifyCallback = ( token: string, headers?: Record | Headers | Iterable<[string, string]> ) => unknown | Promise; ``` Returning falsy (or throwing) fails closed with [`errorCode`](#resolverautherrorcode-node) `VERIFICATION_FAILED`. ### `SaveActivitiesRequest` SH (Node) Request payload for `sdk.selfHosting.getActivities().saveActivities`. | Field | Type | Required | Description | | ------------ | ------------------------------------------------ | -------- | ---------------------------------- | | `metadata` | `{ organizationId: string; documentId: string }` | Yes | Organization and document context. | | `activities` | `Array` | Yes | Activity events to persist. | ### `SaveAttachmentRequest` SH (Node) Request payload for `sdk.selfHosting.getAttachments().saveAttachment`. | Field | Type | Required | Description | | ------------ | ------------------------------------------------------------------------ | -------- | ---------------------------------- | | `metadata` | `{ organizationId: string; documentId: string }` | Yes | Organization and document context. | | `attachment` | `{ attachmentId: number; name: string; mimeType: string; size: number }` | Yes | Attachment metadata. | ### `SaveCommentsRequest` SH (Node) Request payload for `sdk.selfHosting.getComments().saveComments`. | Field | Type | Required | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------ | | `metadata` | `{ organizationId: string; documentId: string }` | Yes | Organization and document context. | | `commentAnnotation` | `Record; metadata: object }>` | Yes | Comment annotations keyed by annotationId. | ### `SaveNotificationsRequest` SH (Node) Request payload for `sdk.selfHosting.getNotifications().saveNotifications`. | Field | Type | Required | Description | | --------------- | ------------------------------------------------ | -------- | ---------------------------------- | | `metadata` | `{ organizationId: string; documentId: string }` | Yes | Organization and document context. | | `notifications` | `Array` | Yes | Notification entries to persist. | ### `SaveReactionsRequest` SH (Node) Request payload for `sdk.selfHosting.getReactions().saveReactions`. | Field | Type | Required | Description | | -------------------- | ------------------------------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------- | | `metadata` | `{ organizationId: string; documentId: string }` | Yes | Organization and document context. | | `reactionAnnotation` | `Record` | Yes | Reaction annotations keyed by annotationId. The reacting user is set via `from` (renamed from `user` in v1.0.5). | ### `SaveRecorderAnnotationRequest` SH (Node) Request payload for `sdk.selfHosting.getRecorder().saveRecorderAnnotation`. | Field | Type | Required | Description | | -------------------- | ------------------------------------------------ | -------- | ---------------------------------- | | `metadata` | `{ organizationId: string; documentId: string }` | Yes | Organization and document context. | | `recorderAnnotation` | `{ annotationId: string; metadata: object }` | Yes | Recorder annotation to persist. | ### `SendLoginLinkRequest` (Node) Request payload for `sdk.api.workspace.sendLoginLink`. | Field | Type | Required | Description | | ------------- | -------- | -------- | --------------------------------- | | `email` | `string` | Yes | Recipient email. | | `continueUrl` | `string` | Yes | Redirect destination after login. | ### `SetNotificationConfigRequest` (Node) Request payload for `sdk.api.notifications.setNotificationConfig`. | Field | Type | Required | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------- | -------- | ------------------------ | | `organizationId` | `string` | Yes | Organization context. | | `userIds` | `string[]` | Yes | Users to update. | | `config` | `{ inbox?: 'ALL' \| 'MINE' \| 'NONE'; email?: 'ALL' \| 'MINE' \| 'NONE'; slack?: 'ALL' \| 'MINE' \| 'NONE' }` | Yes | Per-channel preferences. | ### `UpdateActivitiesRequest` (Node) Request payload for `sdk.api.activities.updateActivities`. | Field | Type | Required | Description | | ---------------- | ------------------------------------------------------- | -------- | --------------------- | | `organizationId` | `string` | Yes | Organization context. | | `activities` | `Array<{ id: string; displayMessageTemplate: string }>` | Yes | Activity updates. | ### `UpdateApiKeyRequest` (Node) Request payload for `sdk.api.workspace.updateApiKey`. | Field | Type | Required | Description | | ------------ | -------- | -------- | ------------------ | | `apiKey` | `string` | Yes | API key to update. | | `apiKeyName` | `string` | Yes | New display name. | ### `UpdateCommentAnnotationsRequest` (Node) Request payload for `sdk.api.commentAnnotations.updateCommentAnnotations`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | ------------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document the annotations belong to. | | `annotationIds` | `string[]` | Yes | Annotations to update. | | `updatedData` | `object` | Yes | Fields to merge into each annotation. | ### `UpdateCommentsRequest` (Node) Request payload for `sdk.api.commentAnnotations.updateComments`. | Field | Type | Required | Description | | ---------------- | ---------------------------------------------- | -------- | -------------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document the comments belong to. | | `annotationId` | `string` | Yes | Annotation that contains the comments. | | `commentIds` | `number[]` | Yes | Comments to update. | | `updatedData` | `{ commentText: string; commentHtml: string }` | Yes | Fields to merge into each comment. | ### `UpdateCrdtDataRequest` (Node) Request payload for `sdk.api.crdt.updateCrdtData`. | Field | Type | Required | Description | | ---------------- | ------------------------------------- | -------- | ------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document the editor belongs to. | | `editorId` | `string` | Yes | Editor instance ID. | | `data` | `string \| object` | Yes | New editor content. | | `type` | `'text' \| 'map' \| 'array' \| 'xml'` | Yes | CRDT data type. | ### `UpdateDocumentAccessRequest` (Node) Request payload for `sdk.api.documents.updateDocumentAccess`. | Field | Type | Required | Description | | ---------------- | --------------------------------------------------- | -------- | ------------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the documents. | | `documentIds` | `string[]` | Yes | Documents to update. | | `accessType` | `'organizationPrivate' \| 'restricted' \| 'public'` | Yes | New access type. | ### `UpdateDocumentDisableStateRequest` (Node) Request payload for `sdk.api.documents.updateDocumentDisableState`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | ------------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the documents. | | `documentIds` | `string[]` | Yes | Documents to update. | | `disabled` | `boolean` | Yes | `true` to disable, `false` to enable. | ### `UpdateDocumentsRequest` (Node) Request payload for `sdk.api.documents.updateDocuments`. | Field | Type | Required | Description | | ---------------- | ------------------------------------------------------ | -------- | ------------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the documents. | | `documents` | `Array<{ documentId: string; documentName?: string }>` | Yes | Document updates. | ### `UpdateEmailConfigRequest` (Node) Request payload for `sdk.api.workspace.updateEmailConfig`. | Field | Type | Required | Description | | -------------------- | --------------------------------------------------------- | -------- | -------------------------------- | | `useEmailService` | `boolean` | Yes | Toggle the custom email service. | | `emailServiceConfig` | `{ type: 'sendgrid'; apiKey: string; fromEmail: string }` | Yes | Provider configuration. | ### `UpdateFolderAccessRequest` (Node) Request payload for `sdk.api.folders.updateFolderAccess`. | Field | Type | Required | Description | | ---------------- | -------------- | -------- | ----------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the folders. | | `folderIds` | `string[]` | Yes | Folders to update. | | `accessType` | `'restricted'` | Yes | New access type. | ### `UpdateFolderRequest` (Node) Request payload for `sdk.api.folders.updateFolder`. | Field | Type | Required | Description | | ---------------- | -------------------------------------------------- | -------- | ----------------------------------- | | `organizationId` | `string` | Yes | Organization that owns the folders. | | `folders` | `Array<{ folderId: string; folderName?: string }>` | Yes | Folder updates. | ### `UpdateNotificationsRequest` (Node) Request payload for `sdk.api.notifications.updateNotifications`. | Field | Type | Required | Description | | ---------------- | ----------------------------------------------------------- | -------- | --------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `userId` | `string` | Yes | Owner of the notifications. | | `notifications` | `Array<{ notificationId: string; [key: string]: unknown }>` | Yes | Notifications to update. | ### `UpdateOrganizationDisableStateRequest` (Node) Request payload for `sdk.api.organizations.updateOrganizationDisableState`. | Field | Type | Required | Description | | ----------------- | ---------- | -------- | ------------------------------------- | | `organizationIds` | `string[]` | Yes | Organizations to update. | | `disabled` | `boolean` | Yes | `true` to disable, `false` to enable. | ### `UpdateOrganizationsRequest` (Node) Request payload for `sdk.api.organizations.updateOrganizations`. | Field | Type | Required | Description | | --------------- | -------------------------------------------------------------- | -------- | ------------------------ | | `organizations` | `Array<{ organizationId: string; organizationName?: string }>` | Yes | Organizations to update. | ### `UpdatePresenceRequest` (Node) Request payload for `sdk.api.presence.updatePresence`. | Field | Type | Required | Description | | ---------------- | --------------------------------------------------------------------- | -------- | ------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document to update presence on. | | `users` | `Array<{ userId: string; status?: 'online' \| 'away' \| 'offline' }>` | Yes | Presence updates. | ### `UpdateUsersRequest` (Node) Request payload for `sdk.api.users.updateUsers`. | Field | Type | Required | Description | | ---------------- | ------------------------------------------------------------------------------- | -------- | -------------------------------- | | `organizationId` | `string` | Yes | Organization to update users in. | | `users` | `Array<{ userId: string; name?: string; email?: string; accessRole?: string }>` | Yes | User updates. | ### `UpdateWebhookConfigRequest` (Node) Request payload for `sdk.api.workspace.updateWebhookConfig`. | Field | Type | Required | Description | | ---------------------- | --------------------------------------------------------------------------------------- | -------- | --------------------------------------- | | `useWebhookService` | `boolean` | Yes | Toggle the webhook service. | | `webhookServiceConfig` | `{ authToken: string; rawNotificationUrl?: string; processedNotificationUrl?: string }` | Yes | Webhook destinations and shared secret. | ### `VeltConfig` (Node) Configuration passed to `VeltSDK.initialize`. | Field | Type | Required | Description | | -------------------- | ------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `database` | `DatabaseConfig` | Yes | MongoDB connection config. In `@veltdev/node@1.0.7`, this is still validated during initialization, including when you only use `sdk.api.*` or `sdk.selfHosting.verifyToken`. | | `apiKey` | `string` | No | Velt API key. Falls back to `VELT_API_KEY`. | | `authToken` | `string` | No | Velt auth token. Falls back to `VELT_AUTH_TOKEN`. | | `workspaceId` | `string` | No | Workspace ID. Falls back to `VELT_WORKSPACE_ID`. | | `workspaceAuthToken` | `string` | No | Workspace auth token. Falls back to `VELT_WORKSPACE_AUTH_TOKEN`. | | `user_schema` | `Record` | No | User schema mapping. | | `collections` | `CollectionNames` | No | Custom collection names for self-hosting data. | | `aws` | `AwsConfig` | No | AWS S3 config for attachment storage. | | `environment` | `'prod' \| 'staging'` | No | SDK API environment. | | `resolverAuth` | [`ResolverAuthConfig`](#resolverauthconfig-node) | No | Token verification config for `sdk.selfHosting.verifyToken`. | ### `VerifyTokenResult` (Node) Result returned by `sdk.selfHosting.verifyToken`. See [`verifyToken`](/backend-sdks/node#verifytoken). | Field | Type | Required | Description | | ----------- | ------------------------------------------------------ | -------- | ----------------------------------------------------------------- | | `verified` | `boolean` | Yes | Whether the credential passed verification. | | `claims` | `Record` | No | Decoded JWT payload; present when verified. | | `error` | `string` | No | Generic, code-based message — never contains the token or secret. | | `errorCode` | [`ResolverAuthErrorCode`](#resolverautherrorcode-node) | No | Machine-readable failure code. | ### `CreateAgentRequest` (Node) Request payload for `sdk.api.agents.createAgent`. Accepts additional passthrough fields. | Field | Type | Required | Description | | ------------------ | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | Yes | Agent display name. | | `description` | `string` | No | Human-readable agent description. | | `rawInstructions` | `string` | No | Unprocessed natural-language instructions. | | `instructions` | `string` | No | Resolved/structured instructions. Required when the configured strategy is `ai`, `service+ai`, or `stagehand-agent`. | | `enabled` | `boolean` | No | Whether the agent is active. | | `metadata` | `Record` | No | Arbitrary metadata. Server-managed metadata keys (`type`, `category`, `internal`, `apiKey`) are rejected on create/update-version payloads. | | `contextGathering` | `ContextGatheringConfig` | No | Context gathering configuration. | | `execution` | `AgentExecutionConfig` | No | Execution configuration. | | `response` | `AgentResponseConfig` | No | Response configuration. | | `postProcess` | `AgentPostProcessConfig` | No | Post-processing configuration. | | `input` | `AgentInputConfig` | No | Input configuration. | | `scope` | `AgentScopeConfig` | No | Scope configuration. | | `setup` | `AgentSetupConfig` | No | Setup configuration. | Create and update-version payloads also reject the top-level server-managed `managedBy` field with `400 INVALID_ARGUMENT`. ### `UpdateAgentRequest` (Node) Request payload for `sdk.api.agents.updateAgent`. | Field | Type | Required | Description | | ------------- | --------- | -------- | -------------------------- | | `agentId` | `string` | Yes | Agent to update. | | `name` | `string` | No | New display name. | | `description` | `string` | No | New description. | | `enabled` | `boolean` | No | Toggle agent active state. | ### `UpdateAgentVersionRequest` (Node) Request payload for `sdk.api.agents.updateAgentVersion`. Accepts additional passthrough fields. Partial updates deep-merge nested config objects, so omitted siblings under `execution`, `contextGathering`, and similar blocks are preserved. | Field | Type | Required | Description | | ------------------ | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------- | | `agentId` | `string` | Yes | Agent to version. | | `rawInstructions` | `string` | No | Unprocessed natural-language instructions. | | `instructions` | `string` | No | Resolved/structured instructions. Required when the configured strategy is `ai`, `service+ai`, or `stagehand-agent`. | | `phaseTimeoutMs` | `number` | No | Positive integer phase timeout in ms. | | `contextGathering` | `ContextGatheringConfig` | No | Context gathering configuration. | | `execution` | `AgentExecutionConfig` | No | Execution configuration. | | `response` | `AgentResponseConfig` | No | Response configuration. | | `postProcess` | `AgentPostProcessConfig` | No | Post-processing configuration. | | `input` | `AgentInputConfig` | No | Input configuration. | | `scope` | `AgentScopeConfig` | No | Scope configuration. | | `setup` | `AgentSetupConfig` | No | Setup configuration. | Update-version payloads also reject the top-level server-managed `managedBy` field and server-managed metadata keys (`metadata.type`, `metadata.category`, `metadata.internal`, `metadata.apiKey`) with `400 INVALID_ARGUMENT`. ### `DeleteAgentRequest` (Node) Request payload for `sdk.api.agents.deleteAgent`. | Field | Type | Required | Description | | --------- | -------- | -------- | ---------------- | | `agentId` | `string` | Yes | Agent to delete. | ### `GetAgentRequest` (Node) Request payload for `sdk.api.agents.getAgent`. | Field | Type | Required | Description | | --------- | ------------------------------- | -------- | --------------------------------------------- | | `agentId` | `string` | No | Agent to fetch. | | `filter` | `'defaultOnly' \| 'customOnly'` | No | Restrict results to default or custom agents. | | `groupId` | `string` | No | Filter agents by group. | ### `ListAgentVersionsRequest` (Node) Request payload for `sdk.api.agents.listAgentVersions`. | Field | Type | Required | Description | | --------- | -------- | -------- | ----------------------------- | | `agentId` | `string` | Yes | Agent whose versions to list. | ### `RestoreAgentVersionRequest` (Node) Request payload for `sdk.api.agents.restoreAgentVersion`. | Field | Type | Required | Description | | --------- | -------- | -------- | ------------------------------- | | `agentId` | `string` | Yes | Agent whose version to restore. | ### `GetAgentAnalyticsRequest` (Node) Request payload for `sdk.api.agents.getAgentAnalytics`. | Field | Type | Required | Description | | --------- | -------- | -------- | ---------------------------- | | `agentId` | `string` | No | Agent to scope analytics to. | | `year` | `string` | No | Year filter. | | `month` | `string` | No | Month filter. | | `model` | `string` | No | Model filter. | ### `RunAgentExecutionRequest` (Node) Request payload for `sdk.api.agents.runExecution`. Accepts additional passthrough fields. | Field | Type | Required | Description | | --------------------- | ---------------------------- | -------- | ------------------------------- | | `agentId` | `string` | Yes | Agent to run. | | `url` | `string` | Yes | URL the agent executes against. | | `crossPageExecute` | `boolean` | No | Execute across linked pages. | | `maxUrlsToProcess` | `number` | No | Cap on URLs processed. | | `organizationId` | `string` | No | Organization context. | | `documentId` | `string` | No | Document context. | | `trigger` | `'standalone' \| 'workflow'` | No | Execution trigger source. | | `workflowExecutionId` | `string` | No | Parent workflow execution ID. | | `ranBy` | `AgentRunBy` | No | Who/what initiated the run. | | `userContext` | `Record` | No | Arbitrary user context. | ### `GetAgentExecutionRequest` (Node) Request payload for `sdk.api.agents.getExecution`. | Field | Type | Required | Description | | ---------------- | --------- | -------- | ------------------------------- | | `executionId` | `string` | Yes | Execution to fetch. | | `includeResults` | `boolean` | No | Include full execution results. | ### `ListAgentExecutionsRequest` (Node) Request payload for `sdk.api.agents.listExecutions`. Server accepts exactly `{agentId}`, `{organizationId, documentId}`, or `{agentId, organizationId, documentId}`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------------ | | `agentId` | `string` | No | Agent filter. | | `organizationId` | `string` | No | Organization filter. | | `documentId` | `string` | No | Document filter. | | `pageSize` | `number` | No | Page size, 1..100, default 20. | | `pageToken` | `string` | No | Pagination cursor. | ### `CountAgentExecutionsRequest` (Node) Request payload for `sdk.api.agents.countExecutions`. | Field | Type | Required | Description | | ---------- | ---------------------- | -------- | --------------------------- | | `agentIds` | `string \| string[]` | No | Agent ID(s), up to 200. | | `status` | `AgentExecutionStatus` | No | Filter by execution status. | ### `PromptEnhancerRequest` (Node) Request payload for `sdk.api.agents.enhancePrompt`. | Field | Type | Required | Description | | ------------------- | -------------------------- | -------- | ------------------------------ | | `prompt` | `string` | Yes | Prompt to enhance. | | `provider` | `string` | No | Model provider override. | | `userContextFields` | `PromptUserContextField[]` | No | User context fields to inject. | ### `PromptValidatorRequest` (Node) Request payload for `sdk.api.agents.validatePrompt`. | Field | Type | Required | Description | | ------------------- | -------------------------- | -------- | ------------------------------ | | `prompt` | `string` | Yes | Prompt to validate. | | `provider` | `string` | No | Model provider override. | | `userContextFields` | `PromptUserContextField[]` | No | User context fields to inject. | ### `PromptRefinerRequest` (Node) Request payload for `sdk.api.agents.refinePrompt`. | Field | Type | Required | Description | | ---------------- | ----------------------------- | -------- | -------------------------- | | `analysisPrompt` | `string` | Yes | Analysis prompt to refine. | | `demoFeedback` | `PromptRefinerDemoFeedback[]` | Yes | Demo feedback samples. | | `provider` | `string` | No | Model provider override. | ### `ResolveConfigRequest` (Node) Request payload for `sdk.api.agents.resolveConfig`. | Field | Type | Required | Description | | ----------------- | -------- | -------- | ------------------------------------------ | | `instructions` | `string` | Yes | Resolved/structured instructions. | | `rawInstructions` | `string` | No | Unprocessed natural-language instructions. | | `provider` | `string` | No | Model provider override. | ### `ParseAgentsRequest` (Node) Request payload for `sdk.api.agents.parseAgents`. | Field | Type | Required | Description | | ------------ | -------- | -------- | --------------------------- | | `fileBase64` | `string` | Yes | Base64-encoded source file. | | `mimeType` | `string` | Yes | MIME type of the file. | | `provider` | `string` | No | Model provider override. | | `fileName` | `string` | No | Original file name. | ### `CreateAgentGroupRequest` (Node) Request payload for `sdk.api.agents.createAgentGroup`. | Field | Type | Required | Description | | ------------- | ------------------------- | -------- | ------------------------------------ | | `name` | `string` | Yes | Group name, 1..200 chars. | | `description` | `string` | No | Group description, up to 2000 chars. | | `agentIds` | `string[]` | No | Agents to include, up to 100. | | `metadata` | `Record` | No | Arbitrary metadata. | ### `GetAgentGroupRequest` (Node) Request payload for `sdk.api.agents.getAgentGroup`. | Field | Type | Required | Description | | --------- | -------- | -------- | --------------- | | `groupId` | `string` | Yes | Group to fetch. | ### `ListAgentGroupsRequest` (Node) Request payload for `sdk.api.agents.listAgentGroups`. No parameters. Pass an empty object `{}`. ### `UpdateAgentGroupRequest` (Node) Request payload for `sdk.api.agents.updateAgentGroup`. At least one of `name`/`description` is required. | Field | Type | Required | Description | | ------------- | -------- | -------- | ---------------------- | | `groupId` | `string` | Yes | Group to update. | | `name` | `string` | No | New group name. | | `description` | `string` | No | New group description. | ### `DeleteAgentGroupRequest` (Node) Request payload for `sdk.api.agents.deleteAgentGroup`. | Field | Type | Required | Description | | --------- | -------- | -------- | ---------------- | | `groupId` | `string` | Yes | Group to delete. | ### `AddAgentsToGroupRequest` (Node) Request payload for `sdk.api.agents.addAgentsToGroup`. | Field | Type | Required | Description | | ---------- | ---------- | -------- | ---------------------- | | `groupId` | `string` | Yes | Target group. | | `agentIds` | `string[]` | Yes | Agents to add, 1..100. | ### `RemoveAgentsFromGroupRequest` (Node) Request payload for `sdk.api.agents.removeAgentsFromGroup`. | Field | Type | Required | Description | | ---------- | ---------- | -------- | ------------------------- | | `groupId` | `string` | Yes | Target group. | | `agentIds` | `string[]` | Yes | Agents to remove, 1..100. | ### Agent configuration nested types (Node) These config types are referenced by `CreateAgentRequest` and `UpdateAgentVersionRequest`. ```ts theme={null} interface ResponseFieldDescriptions { summary?: string; title?: string; description?: string; severity?: string; targetText?: string; suggestion?: string; isPageLevel?: string; issueType?: string; confidence?: string; htmlSelector?: string; findingType?: string; } type RestApiAuthConfig = | { type: 'none' } | { type: 'bearer'; token: string } | { type: 'basic'; username: string; password: string } | { type: 'header'; headers: Record }; interface RestApiEndpoint { url: string; description: string; method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; auth?: RestApiAuthConfig; headers?: Record; query?: Record; body?: unknown; cacheTtlSeconds?: number; // default 0, max 86400 timeoutMs?: number; // default 10000, max 30000 responsePath?: string; } interface RestApiContextStrategyOptions { endpoints: RestApiEndpoint[]; // 1..10 maxResponseBytes?: number; // default 1000000, max 5000000 } interface ContextGatheringConfig { strategies?: string[]; // include 'rest-api' to inject {{restApiData}} strategyOptions?: { 'rest-api'?: RestApiContextStrategyOptions; } & Record>; } type McpAuthConfig = { type: 'none' } | { type: 'header'; headers: Record }; interface McpServerConfig { url: string; auth?: McpAuthConfig; allowedTools?: string[]; } interface AgentExecutionConfig { executionStrategy?: 'default' | 'ai' | 'service+ai' | 'stagehand-agent' | 'mcp-tools' | string; mcpServers?: McpServerConfig[]; responseDescriptions?: ResponseFieldDescriptions; serviceId?: string; strategyOptions?: Record>; knowledge?: Record; } ``` Secret-bearing `rest-api` and `mcp-tools` auth fields are encrypted at rest and returned redacted on read paths, including agent version snapshots. ### `MemorySearchRequest` (Node) Request payload for `sdk.api.memory.search`. | Field | Type | Required | Description | | ---------------- | ------------------------------------------ | -------- | -------------------------------------------- | | `query` | `string` | Yes | Search query. | | `embeddingType` | `'review' \| 'content'` | No | Embedding space to search. | | `scope` | `'document' \| 'organization' \| 'apiKey'` | No | Search scope. | | `organizationId` | `string` | No | Organization context. | | `documentId` | `string` | No | Document context; requires `organizationId`. | | `limit` | `number` | No | Result limit, 1..50. | | `filters` | `MemorySearchFilters` | No | Additional search filters. | | `recencyDays` | `number` | No | 1..365; skips vector search when set. | ### `MemoryQueryJudgmentsRequest` (Node) Request payload for `sdk.api.memory.queryJudgments`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------------------------------ | | `organizationId` | `string` | No | Organization context. | | `documentId` | `string` | No | Document context. | | `decision` | `string` | No | Filter by decision. | | `judgeType` | `string` | No | Filter by judge type. | | `contentType` | `string` | No | Filter by content type. | | `reviewerId` | `string` | No | Filter by reviewer. | | `annotationId` | `string` | No | Filter by annotation; requires `organizationId`. | | `limit` | `number` | No | Result limit, 1..100. | ### `MemorySuggestRequest` (Node) Request payload for `sdk.api.memory.suggest`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | --------------------- | | `query` | `string` | Yes | Suggestion query. | | `organizationId` | `string` | No | Organization context. | | `documentId` | `string` | No | Document context. | ### `MemoryAskRequest` (Node) Request payload for `sdk.api.memory.ask`. | Field | Type | Required | Description | | ---------------- | --------------------- | -------- | -------------------------- | | `question` | `string` | Yes | Question to ask. | | `organizationId` | `string` | No | Organization context. | | `documentId` | `string` | No | Document context. | | `filters` | `MemorySearchFilters` | No | Additional search filters. | | `recencyDays` | `number` | No | Recency window, 1..365. | ### `MemoryGetReviewerProfileRequest` (Node) Request payload for `sdk.api.memory.getReviewerProfile`. Falls back to the caller's uid when omitted. | Field | Type | Required | Description | | -------------- | -------- | -------- | -------------------------------------- | | `targetUserId` | `string` | No | Reviewer to fetch; defaults to caller. | ### `MemoryGetPatternsRequest` (Node) Request payload for `sdk.api.memory.getPatterns`. No parameters. Pass an empty object `{}`. ### `MemoryGetStatsRequest` (Node) Request payload for `sdk.api.memory.getStats`. No parameters. Pass an empty object `{}`. ### `MemoryIngestKnowledgeRequest` (Node) Request payload for `sdk.api.memory.ingestKnowledge`. Union of `MemoryIngestInlineRequest` and `MemoryIngestFileRefRequest`. | Field | Type | Required | Description | | ---------------- | ------------------------- | -------- | ---------------------------------------- | | `source` | `'inline' \| 'fileRef'` | Yes | Ingestion source mode. | | `file` | `MemoryIngestInlineFile` | No | Inline file payload. | | `fileRef` | `string` | No | Reference to a previously uploaded file. | | `mimeType` | `MemoryKnowledgeMimeType` | No | MIME type of the content. | | `organizationId` | `string` | No | Organization context. | | `documentId` | `string` | No | Document context. | ### `MemoryKnowledgeUploadUrlRequest` (Node) Request payload for `sdk.api.memory.getKnowledgeUploadUrl`. | Field | Type | Required | Description | | ---------------- | ------------------------- | -------- | -------------------------------------------- | | `mimeType` | `MemoryKnowledgeMimeType` | Yes | MIME type of the file. | | `fileSize` | `number` | Yes | Positive integer bytes, `<= 30 MB`. | | `fileName` | `string` | No | File name, 1..255 chars. | | `organizationId` | `string` | No | Organization context. | | `documentId` | `string` | No | Document context; requires `organizationId`. | ### `MemoryIngestStatusRequest` (Node) Request payload for `sdk.api.memory.getIngestStatus`. | Field | Type | Required | Description | | ---------- | -------- | -------- | -------------------------- | | `sourceId` | `string` | Yes | Knowledge source to check. | ### `MemoryUpdateKnowledgeRequest` (Node) Request payload for `sdk.api.memory.updateKnowledge`. | Field | Type | Required | Description | | ------------ | -------- | -------- | --------------------------- | | `sourceId` | `string` | Yes | Knowledge source to update. | | `newContent` | `string` | Yes | Replacement content. | ### `MemoryDeleteKnowledgeRequest` (Node) Request payload for `sdk.api.memory.deleteKnowledge`. | Field | Type | Required | Description | | ---------- | -------- | -------- | --------------------------- | | `sourceId` | `string` | Yes | Knowledge source to delete. | ### `MemoryKnowledgeSearchRequest` (Node) Request payload for `sdk.api.memory.searchKnowledge`. | Field | Type | Required | Description | | -------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | `string` | Yes | Search query. | | `sourceId` | `string \| string[]` | No | Omit for whole workspace; array of 2..30 ids. When `includeRules` is `true`, narrows both knowledge chunks and extracted rules. | | `limit` | `number` | No | Result limit, 1..50, default 10. When `includeRules` is `true`, this is the combined cap after merging both corpora. | | `includeRules` | `boolean` | No | Defaults to `false`. When `true`, also searches extracted rules and merges them with knowledge-chunk hits. Non-boolean values are rejected. | ### `MemoryKnowledgeSearchResult` (Node) Result item returned by `sdk.api.memory.searchKnowledge`. | Field | Type | Required | Description | | ---------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------ | | `sourceId` | `string` | No | Knowledge source that produced the hit. | | `text` | `string` | Yes | Matched chunk text or extracted-rule text. | | `score` | `number` | No | Cosine distance; lower is more relevant. Absent for recency-fallback hits. | | `kind` | `'chunk' \| 'rule'` | No | Present only when `includeRules` is `true`; distinguishes knowledge chunks from extracted rules. | | `ruleId` | `string` | No | Rule document id. Present only on `kind: 'rule'` hits. | | `category` | `string` | No | Optional rule category. Present only on rule hits when the rule has a category. | ### `MemoryKnowledgeSearchResponse` (Node) Response payload returned under `result` from `sdk.api.memory.searchKnowledge`. | Field | Type | Required | Description | | ----------------- | ------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `results` | `MemoryKnowledgeSearchResult[]` | Yes | Search results. When `includeRules` is omitted or `false`, result items keep the existing chunk-only shape with no `kind`, `ruleId`, or `category`. | | `recordsSearched` | `number` | Yes | For `includeRules: true`, equals the number of returned results after merging and truncating to `limit`. | ### `KnowledgeRuleHit` (Node) Extracted-rule hit returned by internal rule search helpers and surfaced in `MemoryKnowledgeSearchResult` when `includeRules` is `true`. | Field | Type | Required | Description | | ---------- | -------- | -------- | -------------------------------------------------------------------------- | | `ruleId` | `string` | Yes | Firestore document id for the extracted rule. | | `sourceId` | `string` | No | Knowledge source that produced the rule. | | `text` | `string` | Yes | Extracted rule text. | | `score` | `number` | No | Cosine distance; lower is more relevant. Absent for recency-fallback hits. | | `category` | `string` | No | Optional category from the rule document. | ### `MemoryListKnowledgeSourcesRequest` (Node) Request payload for `sdk.api.memory.listKnowledgeSources`. No parameters. Pass an empty object `{}`. ### `MemoryDownloadCanonicalMdRequest` (Node) Request payload for `sdk.api.memory.downloadCanonicalMd`. | Field | Type | Required | Description | | ---------- | -------- | -------- | ----------------------------- | | `sourceId` | `string` | Yes | Knowledge source to download. | ### `MemoryListExtractedRulesRequest` (Node) Request payload for `sdk.api.memory.listExtractedRules`. | Field | Type | Required | Description | | ---------- | -------- | -------- | ----------------------------------- | | `sourceId` | `string` | Yes | Knowledge source to list rules for. | ### `MemoryListAlertsRequest` (Node) Request payload for `sdk.api.memory.listAlerts`. No parameters. Pass an empty object `{}`. ### `MemoryDismissAlertRequest` (Node) Request payload for `sdk.api.memory.dismissAlert`. | Field | Type | Required | Description | | --------- | -------- | -------- | ----------------- | | `alertId` | `string` | Yes | Alert to dismiss. | ### `MemoryMarkAlertActionedRequest` (Node) Request payload for `sdk.api.memory.markAlertActioned`. | Field | Type | Required | Description | | --------- | -------- | -------- | -------------------------- | | `alertId` | `string` | Yes | Alert to mark as actioned. | ### `MemoryUpdateAlertConfigRequest` (Node) Request payload for `sdk.api.memory.updateAlertConfig`. | Field | Type | Required | Description | | -------- | ------------------- | -------- | ----------------------------- | | `config` | `MemoryAlertConfig` | Yes | Alert configuration to apply. | ### `MemoryGetAlertConfigRequest` (Node) Request payload for `sdk.api.memory.getAlertConfig`. No parameters. Pass an empty object `{}`. ### `MemoryTriggerConsolidationRequest` (Node) Request payload for `sdk.api.memory.triggerConsolidation`. | Field | Type | Required | Description | | ------- | --------- | -------- | ------------------------------------ | | `force` | `boolean` | No | Force consolidation even if not due. | ### `MemorySeedActiveApiKeysRequest` (Node) Request payload for `sdk.api.memory.seedActiveApiKeys`. No parameters. Pass an empty object `{}`. ### `MemoryBackfillJudgmentsRequest` (Node) Request payload for `sdk.api.memory.backfillJudgments`. | Field | Type | Required | Description | | ----------------------- | --------- | -------- | -------------------------------------------- | | `storeDbId` | `string` | No | Required when `allApiKeysInStore` is set. | | `resumeFrom` | `string` | No | Cursor to resume from. | | `batchSize` | `number` | No | Batch size, 1..1000, default 500. | | `timestampLowerBoundMs` | `number` | No | Lower timestamp bound in ms. | | `timestampUpperBoundMs` | `number` | No | Upper timestamp bound in ms. | | `force` | `boolean` | No | Force backfill. | | `allApiKeysInStore` | `boolean` | No | Backfill all API keys; requires `storeDbId`. | | `migrateOldSdk` | `boolean` | No | Migrate legacy SDK judgments. | ### `ApprovalCreateDefinitionRequest` (Node) Request payload for `sdk.api.approval.createDefinition`. | Field | Type | Required | Description | | ---------------- | ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `definitionId` | `string` | Yes | Lowercase start, `[a-z0-9-]`, 3..64 chars. | | `name` | `string` | Yes | Definition name, 1..200 chars. | | `description` | `string` | No | Description, up to 2000 chars. | | `scope` | `ApprovalScope` | No | Definition scope. | | `nodes` | `ApprovalNode[]` | Yes | Workflow nodes, 1..100. | | `edges` | `ApprovalEdge[]` | Yes | Workflow edges (unified `EdgeSchema`: `from`/`to`/`on`/`when`/`loop`); may be empty; max 500. Reject paths and loop-backs are `on:'reject'` edges. | | `groups` | `ApprovalGroup[]` | No | Node groups. | | `triggers` | `ApprovalTrigger[]` | No | Trigger definitions. | | `tags` | `string[]` | No | Tags. | | `custom` | `Record` | No | Arbitrary custom data. | | `organizationId` | `string` | No | Organization context. | | `documentId` | `string` | No | Document context. | | `webhookConfig` | `ApprovalWebhookConfig` | No | Webhook configuration. | ### `ApprovalUpdateDefinitionRequest` (Node) Request payload for `sdk.api.approval.updateDefinition`. Extends `ApprovalCreateDefinitionRequest`: all fields of `ApprovalCreateDefinitionRequest`, plus: | Field | Type | Required | Description | | ----------- | -------- | -------- | --------------------------------------------- | | `ifVersion` | `number` | Yes | Optimistic-concurrency version; integer >= 1. | ### `ApprovalDeleteDefinitionRequest` (Node) Request payload for `sdk.api.approval.deleteDefinition`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | --------------------- | | `definitionId` | `string` | Yes | Definition to delete. | | `organizationId` | `string` | No | Organization context. | | `documentId` | `string` | No | Document context. | ### `ApprovalGetDefinitionRequest` (Node) Request payload for `sdk.api.approval.getDefinition`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | --------------------- | | `definitionId` | `string` | Yes | Definition to fetch. | | `organizationId` | `string` | No | Organization context. | | `documentId` | `string` | No | Document context. | ### `ApprovalListDefinitionsRequest` (Node) Request payload for `sdk.api.approval.listDefinitions`. | Field | Type | Required | Description | | ---------------- | -------- | -------- | --------------------- | | `pageSize` | `number` | No | Page size, 1..500. | | `cursor` | `number` | No | Pagination cursor. | | `organizationId` | `string` | No | Organization context. | | `documentId` | `string` | No | Document context. | ### Approval graph nested types (Node) These graph types are referenced by approval definition requests and `DefinitionView` responses. ```ts theme={null} type JsonAst = Record; 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 string, only valid when on === 'custom' loop?: { maxIterations: number }; // 1..20, only on an on:'reject' back-edge } interface ApprovalNodeBase { nodeId: string; type: 'agent' | 'human' | 'webhook'; slaMs?: number; requireNonEmptyOutput?: boolean; name?: string; // 1..200 description?: string; // max 2000 } type ApprovalNode = | (ApprovalNodeBase & { type: 'agent'; config: Record }) | (ApprovalNodeBase & { type: 'human'; config: { reviewerIds?: string[]; reviewers?: Array<{ userId: string; mandatory: boolean }>; reviewerEmails?: string[]; commentBody?: string; }; }) | (ApprovalNodeBase & { type: 'webhook'; config: Record }); 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[]; } ``` Every `DefinitionView` returned by create, get, and list includes read-only `compiled.forwardEdges` and `compiled.loops` alongside the authored `edges`. ### `ApprovalDispatchExecutionRequest` (Node) Request payload for `sdk.api.approval.dispatchExecution`. | Field | Type | Required | Description | | ---------------- | ------------------------- | -------- | -------------------------------------- | | `definitionId` | `string` | Yes | Definition to execute. | | `idempotencyKey` | `string` | No | Idempotency key for the dispatch. | | `triggerContext` | `Record` | No | Trigger context payload. | | `correlationId` | `string` | No | Correlation ID. | | `organizationId` | `string` | No | Organization context. | | `documentId` | `string` | No | Document context. | | `folderId` | `string` | No | Folder context. | | `webhookUrl` | `string` | No | Webhook URL; requires `webhookSecret`. | | `webhookSecret` | `string` | No | Webhook secret; requires `webhookUrl`. | ### `ApprovalCancelExecutionRequest` (Node) Request payload for `sdk.api.approval.cancelExecution`. | Field | Type | Required | Description | | ------------- | -------- | -------- | -------------------- | | `executionId` | `string` | Yes | Execution to cancel. | | `reason` | `string` | No | Cancellation reason. | ### `ApprovalGetExecutionRequest` (Node) Request payload for `sdk.api.approval.getExecution`. | Field | Type | Required | Description | | ------------- | -------- | -------- | ------------------- | | `executionId` | `string` | Yes | Execution to fetch. | ### `ApprovalGetExecutionEventsRequest` (Node) Request payload for `sdk.api.approval.getExecutionEvents`. | Field | Type | Required | Description | | ------------- | -------- | -------- | ----------------------------------------- | | `executionId` | `string` | Yes | Execution to fetch events for. | | `sinceSeq` | `number` | No | Return events after this sequence number. | | `pageSize` | `number` | No | Page size, 1..500. | ### `ApprovalListExecutionsRequest` (Node) Request payload for `sdk.api.approval.listExecutions`. | Field | Type | Required | Description | | -------------- | ------------------------------------------------------------------ | -------- | ------------------ | | `definitionId` | `string` | No | Definition filter. | | `status` | `'pending' \| 'running' \| 'completed' \| 'failed' \| 'cancelled'` | No | Status filter. | | `pageSize` | `number` | No | Page size, 1..500. | | `cursor` | `string` | No | Pagination cursor. | ### `ApprovalCancelStepRequest` (Node) Request payload for `sdk.api.approval.cancelStep`. | Field | Type | Required | Description | | ------------- | -------- | -------- | ---------------------------------- | | `executionId` | `string` | Yes | Execution containing the step. | | `stepId` | `string` | Yes | Step to cancel. | | `actorId` | `string` | Yes | Actor performing the cancellation. | | `reason` | `string` | No | Cancellation reason. | ### `ApprovalResolveStepRequest` (Node) Request payload for `sdk.api.approval.resolveStep`. | Field | Type | Required | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------ | -------- | -------------------------------- | | `executionId` | `string` | Yes | Execution containing the step. | | `stepId` | `string` | Yes | Step to resolve. | | `action` | `'force-approve' \| 'force-reject' \| 'force-complete' \| 'force-fail' \| 'reviewer-approve' \| 'reviewer-reject'` | Yes | Resolution action. | | `output` | `Record` | No | Step output payload. | | `reason` | `string` | No | Resolution reason. | | `actorId` | `string` | Yes | Actor performing the resolution. | ### `ApprovalRecordAgentResolutionRequest` (Node) Request payload for `sdk.api.approval.recordAgentResolution`. | Field | Type | Required | Description | | ------------- | -------------------------- | -------- | ------------------------------- | | `executionId` | `string` | Yes | Execution containing the step. | | `stepId` | `string` | Yes | Step the resolution applies to. | | `responseId` | `string` | Yes | Agent response being resolved. | | `resolution` | `'resolved' \| 'rejected'` | Yes | Resolution outcome. | | `actorId` | `string` | Yes | Actor recording the resolution. | | `reason` | `string` | No | Resolution reason. | ### `ApprovalRecordReviewerDecisionRequest` (Node) Request payload for `sdk.api.approval.recordReviewerDecision`. | Field | Type | Required | Description | | ------------- | ----------------------- | -------- | ------------------------------ | | `executionId` | `string` | Yes | Execution containing the step. | | `stepId` | `string` | Yes | Step the decision applies to. | | `reviewerId` | `string` | Yes | Reviewer making the decision. | | `decision` | `'approve' \| 'reject'` | Yes | Reviewer decision. | | `reason` | `string` | No | Decision reason. | ### `DeleteCrdtDataRequest` (Node) Request payload for `sdk.api.crdt.deleteCrdtData`. | Field | Type | Required | Description | | ---------------- | ---------- | -------- | --------------------------------------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | Yes | Document whose CRDT data is deleted. | | `editorIds` | `string[]` | No | Editors to delete; omit to delete all editors for the document. | | `isServerIds` | `boolean` | No | Treat provided IDs as server IDs. | ### `GetDocumentsCountRequest` (Node) Request payload for `sdk.api.documents.getDocumentsCount`. | Field | Type | Required | Description | | ------------------- | --------- | -------- | ------------------------------------------------ | | `organizationId` | `string` | Yes | Organization context. | | `folderId` | `string` | No | Restrict count to this folder. | | `excludeFolderDocs` | `boolean` | No | Exclude documents inside folders from the count. | ### `GetUsersCountRequest` (Node) Request payload for `sdk.api.users.getUsersCount`. | Field | Type | Required | Description | | ---------------- | --------- | -------- | ----------------------------------------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `documentId` | `string` | No | Document scope; mutually exclusive with `allDocuments`. | | `userId` | `string` | No | Restrict count to this user. | | `allDocuments` | `boolean` | No | Count across all documents; mutually exclusive with `documentId`. | ### `GetDocUsersRequest` (Node) Request payload for `sdk.api.users.getDocUsers`. | Field | Type | Required | Description | | -------------------------- | ---------- | -------- | ------------------------------------------------------ | | `organizationId` | `string` | Yes | Organization context. | | `userIds` | `string[]` | No | Max 20; max 5 when `includeInvolvedDocuments` is true. | | `includeInvolvedDocuments` | `boolean` | No | When true, `userIds` is required (1..5). | | `pageSize` | `number` | No | Page size, 1..1000. | | `pageToken` | `string` | No | Pagination token. | ### `AddUserInviteRequest` (Node) Request payload for `sdk.api.users.addUserInvite`. | Field | Type | Required | Description | | ------------------ | ------------------------------------------- | -------- | -------------------------------------------------------------------------------- | | `email` | `string` | Yes | Invitee email address. | | `organizationId` | `string` | Yes | Organization context. | | `type` | `'org_user' \| 'doc_user' \| 'folder_user'` | Yes | Invite type; `documentId` required for `doc_user`, `folderId` for `folder_user`. | | `organizationName` | `string` | No | Organization display name. | | `documentId` | `string` | No | Document scope; mutually exclusive with `folderId`. | | `documentName` | `string` | No | Document display name. | | `folderId` | `string` | No | Folder scope; mutually exclusive with `documentId`. | | `folderName` | `string` | No | Folder display name. | | `invitedBy` | [`InvitedByUser`](#invitedbyuser-node) | No | User issuing the invite. | ### `RespondToUserInviteRequest` (Node) Request payload for `sdk.api.users.respondToUserInvite`. | Field | Type | Required | Description | | ---------------- | -------------------------------------------- | -------- | ---------------------------------------------------------- | | `email` | `string` | Yes | Invitee email address. | | `organizationId` | `string` | Yes | Organization context. | | `status` | `'ACCEPTED' \| 'REJECTED' \| 'WITHDRAWN'` | Yes | Response status; `ACCEPTED` requires `user` + `authToken`. | | `type` | `'org_user' \| 'doc_user' \| 'folder_user'` | Yes | Invite type. | | `documentId` | `string` | No | Document scope; mutually exclusive with `folderId`. | | `folderId` | `string` | No | Folder scope; mutually exclusive with `documentId`. | | `user` | [`User`](#user) \| `Record` | No | Required when `status` is `ACCEPTED`. | | `authToken` | `string` | No | Required when `status` is `ACCEPTED`. | ### `GetUserInvitesRequest` (Node) Request payload for `sdk.api.users.getUserInvites`. | Field | Type | Required | Description | | -------------------- | --------- | -------- | -------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `email` | `string` | No | Filter invites by email. | | `pageSize` | `number` | No | Page size, 1..1000, default 100. | | `pageToken` | `string` | No | Pagination token. | | `isPendingUsersOnly` | `boolean` | No | Return only pending users. | ### `GetUserInvitationsRequest` (Node) Request payload for `sdk.api.users.getUserInvitations`. | Field | Type | Required | Description | | ---------------- | ------------------------------------------------------ | -------- | -------------------------------- | | `organizationId` | `string` | Yes | Organization context. | | `email` | `string` | Yes | Invitee email address. | | `pageSize` | `number` | No | Page size, 1..1000, default 100. | | `pageToken` | `string` | No | Pagination token. | | `status` | `'PENDING' \| 'ACCEPTED' \| 'REJECTED' \| 'WITHDRAWN'` | No | Filter by invite status. | | `type` | `'org_user' \| 'doc_user' \| 'folder_user'` | No | Filter by invite type. | ### `GetInvitedPendingUsersCountRequest` (Node) Request payload for `sdk.api.users.getInvitedPendingUsersCount`. | Field | Type | Required | Description | | ---------------- | ------------------------------------------- | -------- | --------------------- | | `organizationId` | `string` | Yes | Organization context. | | `type` | `'org_user' \| 'doc_user' \| 'folder_user'` | Yes | Invite type to count. | ### `GetRequestedDomainsRequest` (Node) Request payload for `sdk.api.workspace.getRequestedDomains`. No parameters. Pass an empty object `{}`. ### `AcceptRejectAdditionalUrlRequest` (Node) Request payload for `sdk.api.workspace.acceptRejectAdditionalUrlRequest`. | Field | Type | Required | Description | | ------------- | ---------------------- | -------- | ------------------------------- | | `action` | `'accept' \| 'reject'` | Yes | Decision on the requested URL. | | `id` | `string` | Yes | Requested URL record ID. | | `clientDocId` | `string` | Yes | Client document ID for the URL. | ### `CreateDomainRequest` (Node) Request payload for `sdk.api.workspace.createDomainRequest`. | Field | Type | Required | Description | | ------------------ | -------- | -------- | ---------------------------------------- | | `domain` | `string` | Yes | Domain to register; must be a valid URL. | | `clientDocumentId` | `string` | Yes | Client document ID for the domain. | | `organizationId` | `string` | Yes | Organization context. | ### `CopyApiKeyRequest` (Node) Request payload for `sdk.api.workspace.copyApiKey`. | Field | Type | Required | Description | | -------------- | -------- | -------- | ----------------------------------- | | `sourceApiKey` | `string` | Yes | API key to copy configuration from. | | `targetApiKey` | `string` | Yes | API key to copy configuration to. | ### `UpdateApiKeyConfigRequest` (Node) Request payload for `sdk.api.workspace.updateApiKeyConfig`. Strict; at least one field required. | Field | Type | Required | Description | | --------------------------- | --------------------------------------------------- | -------- | ------------------------------------------- | | `enablePrivateComments` | `boolean` | No | Enable private comments. | | `requireJwtToken` | `boolean` | No | Require JWT token for auth. | | `requireAutoOrgUser` | `boolean` | No | Require auto organization user. | | `defaultDocumentAccessType` | `'public' \| 'restricted' \| 'organizationPrivate'` | No | Default access type for documents. | | `aiModelApiKey` | [`AiModelApiKey[]`](#aimodelapikey-node) | No | AI model API keys; non-empty when provided. | ### `GetWorkspaceNotificationConfigRequest` (Node) Request payload for `sdk.api.workspace.getNotificationConfig`. No parameters. Pass an empty object `{}`. ### `UpdateWorkspaceNotificationConfigRequest` (Node) Request payload for `sdk.api.workspace.updateNotificationConfig`. At least one field required. | Field | Type | Required | Description | | --------------------------- | -------------------------------------------------------------- | -------- | ----------------------------------- | | `useNotificationService` | `boolean` | No | Toggle the notification service. | | `notificationServiceConfig` | [`NotificationServiceConfig`](#notificationserviceconfig-node) | No | Notification service configuration. | ### `GetPermissionProviderConfigRequest` (Node) Request payload for `sdk.api.workspace.getPermissionProviderConfig`. No parameters. Pass an empty object `{}`. ### `UpdatePermissionProviderConfigRequest` (Node) Request payload for `sdk.api.workspace.updatePermissionProviderConfig`. | Field | Type | Required | Description | | -------------------------- | ------------------------------------------------------------ | -------- | ---------------------------------- | | `usePermissionProvider` | `boolean` | No | Toggle the permission provider. | | `permissionProviderConfig` | [`PermissionProviderConfig`](#permissionproviderconfig-node) | No | Permission provider configuration. | ### `GetActivityConfigRequest` (Node) Request payload for `sdk.api.workspace.getActivityConfig`. No parameters. Pass an empty object `{}`. ### `UpdateActivityConfigRequest` (Node) Request payload for `sdk.api.workspace.updateActivityConfig`. | Field | Type | Required | Description | | ----------------------- | ------------------------------------------------------ | -------- | -------------------------------------------------------- | | `activityServiceConfig` | [`ActivityServiceConfig`](#activityserviceconfig-node) | Yes | Activity configuration; must contain at least one field. | ### `EnsureWorkspaceAuthTokenRequest` (Node) Request payload for `sdk.api.workspace.ensureWorkspaceAuthToken`. No parameters. Pass an empty object `{}`. ### `GetAdvancedWebhookConfigRequest` (Node) Request payload for `sdk.api.workspace.getAdvancedWebhookConfig`. No parameters. Pass an empty object `{}`. ### `UpdateAdvancedWebhookConfigRequest` (Node) Request payload for `sdk.api.workspace.updateAdvancedWebhookConfig`. At least one field required. | Field | Type | Required | Description | | ---------------------- | --------- | -------- | ---------------------------------- | | `isEnabled` | `boolean` | No | Enable advanced webhooks. | | `encryptData` | `boolean` | No | Encrypt webhook payloads. | | `encodeData` | `boolean` | No | Encode webhook payloads. | | `publicKey` | `string` | No | Public key for payload encryption. | | `enableDataProtection` | `boolean` | No | Enable data protection. | ### `GetAdvancedWebhookEndpointsRequest` (Node) Request payload for `sdk.api.workspace.getAdvancedWebhookEndpoints`. | Field | Type | Required | Description | | ---------- | -------- | -------- | -------------------- | | `limit` | `number` | No | Page size, 1..250. | | `iterator` | `string` | No | Pagination iterator. | ### `CreateAdvancedWebhookEndpointRequest` (Node) Request payload for `sdk.api.workspace.createAdvancedWebhookEndpoint`. | Field | Type | Required | Description | | ------------- | ------------------------ | -------- | -------------------------------------- | | `url` | `string` | Yes | Endpoint URL; must be http(s). | | `description` | `string` | No | Endpoint description. | | `filterTypes` | `string[]` | No | Event types to deliver. | | `channels` | `string[]` | No | Channels to deliver on. | | `disabled` | `boolean` | No | Create the endpoint disabled. | | `rateLimit` | `number` | No | Delivery rate limit; positive integer. | | `uid` | `string` | No | Custom endpoint UID. | | `metadata` | `Record` | No | Endpoint metadata. | ### `UpdateAdvancedWebhookEndpointRequest` (Node) Request payload for `sdk.api.workspace.updateAdvancedWebhookEndpoint`. At least one mutable field required. | Field | Type | Required | Description | | ------------- | ------------------------ | -------- | ----------------------- | | `endpointId` | `string` | Yes | Endpoint to update. | | `url` | `string` | No | Endpoint URL. | | `description` | `string` | No | Endpoint description. | | `filterTypes` | `string[]` | No | Event types to deliver. | | `channels` | `string[]` | No | Channels to deliver on. | | `disabled` | `boolean` | No | Disable the endpoint. | | `rateLimit` | `number` | No | Delivery rate limit. | | `metadata` | `Record` | No | Endpoint metadata. | ### `DeleteAdvancedWebhookEndpointRequest` (Node) Request payload for `sdk.api.workspace.deleteAdvancedWebhookEndpoint`. | Field | Type | Required | Description | | ------------ | -------- | -------- | ------------------- | | `endpointId` | `string` | Yes | Endpoint to delete. | ### `GetAdvancedWebhookEndpointSecretRequest` (Node) Request payload for `sdk.api.workspace.getAdvancedWebhookEndpointSecret`. | Field | Type | Required | Description | | ------------ | -------- | -------- | --------------------------------- | | `endpointId` | `string` | Yes | Endpoint whose secret is fetched. | ### `InvitedByUser` (Node) Identifies the user who issued an invite. Used by [`AddUserInviteRequest`](#adduserinviterequest-node). | Field | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------ | | `email` | `string` | Yes | Inviter email address. | | `userId` | `string` | Yes | Inviter user ID. | | `userSnippylyId` | `string` | No | Legacy Snippyly user ID. | | `clientUserId` | `string` | Yes | Inviter client user ID. | ### `AiModelApiKey` (Node) AI model provider key. Used by [`UpdateApiKeyConfigRequest`](#updateapikeyconfigrequest-node); encrypted server-side. | Field | Type | Required | Description | | ---------------- | ------------------------------------- | -------- | -------------------------- | | `provider` | `'openai' \| 'anthropic' \| 'gemini'` | Yes | AI model provider. | | `customerApiKey` | `string` | Yes | Customer-provided API key. | ### `CommentNotificationTriggers` (Node) Comment notification triggers. Used by [`NotificationServiceConfig`](#notificationserviceconfig-node) and [`ActivityServiceConfig`](#activityserviceconfig-node). | Field | Type | Required | Description | | -------------------- | --------- | -------- | ------------------------------------ | | `newlyAdded` | `boolean` | No | Notify on first comment in a thread. | | `added` | `boolean` | No | Notify on comment added. | | `updated` | `boolean` | No | Notify on comment updated. | | `deleted` | `boolean` | No | Notify on comment deleted. | | `approved` | `boolean` | No | Notify on comment approved. | | `assigned` | `boolean` | No | Notify on comment assigned. | | `reactionAdded` | `boolean` | No | Notify on reaction added. | | `reactionDeleted` | `boolean` | No | Notify on reaction deleted. | | `statusChanged` | `boolean` | No | Notify on status changed. | | `priorityChanged` | `boolean` | No | Notify on priority changed. | | `accessModeChanged` | `boolean` | No | Notify on access mode changed. | | `accepted` | `boolean` | No | Notify on comment accepted. | | `rejected` | `boolean` | No | Notify on comment rejected. | | `suggestionAccepted` | `boolean` | No | Notify on suggestion accepted. | | `suggestionRejected` | `boolean` | No | Notify on suggestion rejected. | | `customListChanged` | `boolean` | No | Notify on custom list changed. | | `subscribed` | `boolean` | No | Notify on subscribe. | | `unsubscribed` | `boolean` | No | Notify on unsubscribe. | ### `HuddleNotificationTriggers` (Node) Huddle notification triggers. Used by [`NotificationServiceConfig`](#notificationserviceconfig-node). | Field | Type | Required | Description | | --------- | --------- | -------- | ------------------------- | | `created` | `boolean` | No | Notify on huddle created. | | `join` | `boolean` | No | Notify on huddle join. | ### `NotificationDelayConfig` (Node) Notification delay settings. Used by [`NotificationServiceConfig`](#notificationserviceconfig-node). | Field | Type | Required | Description | | -------------- | --------- | -------- | ---------------------------------- | | `isEnabled` | `boolean` | No | Enable delayed delivery. | | `delaySeconds` | `number` | No | Delay before delivery, in seconds. | ### `NotificationBatchLevelConfig` (Node) Per-level notification batching settings. Used by [`NotificationServiceConfig`](#notificationserviceconfig-node). | Field | Type | Required | Description | | -------------------- | --------- | -------- | ------------------------------ | | `isEnabled` | `boolean` | No | Enable batching at this level. | | `batchWindowSeconds` | `number` | No | Batch window, in seconds. | | `maxActivities` | `number` | No | Max activities per batch. | ### `NotificationServiceConfig` (Node) Notification service configuration. Used by [`UpdateWorkspaceNotificationConfigRequest`](#updateworkspacenotificationconfigrequest-node). | Field | Type | Required | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------- | | `triggers` | `{ comment?:` [`CommentNotificationTriggers`](#commentnotificationtriggers-node)`; huddle?:` [`HuddleNotificationTriggers`](#huddlenotificationtriggers-node) `}` | No | Trigger toggles by feature. | | `delayConfig` | [`NotificationDelayConfig`](#notificationdelayconfig-node) | No | Delayed delivery settings. | | `batchConfig` | `{ document?:` [`NotificationBatchLevelConfig`](#notificationbatchlevelconfig-node)`; user?:` [`NotificationBatchLevelConfig`](#notificationbatchlevelconfig-node) `}` | No | Batching settings by level. | ### `PermissionProviderConfig` (Node) Permission provider configuration. Used by [`UpdatePermissionProviderConfigRequest`](#updatepermissionproviderconfigrequest-node). | Field | Type | Required | Description | | ----------------------- | -------- | -------- | ------------------------------------------- | | `permissionProviderUrl` | `string` | No | Provider endpoint URL; empty url clears it. | | `authToken` | `string` | No | Auth token sent to the provider. | ### `ActivityServiceConfig` (Node) Activity service configuration. Used by [`UpdateActivityConfigRequest`](#updateactivityconfigrequest-node). | Field | Type | Required | Description | | ------------- | ------------------------------------------------------------------------------------ | -------- | ------------------------------------ | | `isEnabled` | `boolean` | No | Enable the activity service. | | `enabledTime` | `number` | No | Timestamp when activity was enabled. | | `immutable` | `boolean` | No | Mark activity records immutable. | | `triggers` | `{ comment?:` [`CommentNotificationTriggers`](#commentnotificationtriggers-node) `}` | No | Activity trigger toggles. |