> ## Documentation Index > Fetch the complete documentation index at: https://velt.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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 | | `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, and userIds. Defaults to `{ type: 'public' }` for new annotations without explicit visibility. | | `suggestion` | [`SuggestionData`](#suggestiondata) | No | Present only when `annotation.type === 'suggestion'`; SDK-managed. | #### 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 | #### 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. Required when `type` is `'organizationPrivate'`. | | `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` and `organizationId`. Uses [`CommentVisibilityType`](#commentvisibilitytype) values. ```typescript theme={null} type PrivateModeConfig = Omit< CommentVisibilityConfig, "annotationId" | "organizationId" >; ``` | Property | Type | Required | Description | | --------- | ------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `type` | [`CommentVisibilityType`](#commentvisibilitytype) | Yes | Visibility level applied when private mode is active. | | `userIds` | `string[]` | No | User IDs who can see comments. Used when `type` is `'restricted'`. The current user is automatically appended if not present. | #### 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. | | `userIds` | `string[]` | No | The user IDs for restricted visibility. Always includes the current user when type is `'restricted'`. | #### 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 | #### 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` | No | Event name that caused the save request | | `commentId` | `string` | No | ID of the comment to save | #### 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[]` | 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`. | ### 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. | #### 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. | #### 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 | #### 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 | #### 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 | ### Comment Dialog Primitives Types for the 92+ primitive components used to build custom comment dialog interfaces. See [Comment Dialog Primitives Overview](/ui-customization/features/async/comments/comment-dialog/primitives) for usage examples and [API Methods](/api-reference/sdk/api/api-methods#comment-dialog-primitives) for component documentation. #### CommentDialogCommonProps ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#common-inputs) 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 ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcontextwrapper) 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 ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogthreadcard) 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 ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogthreadcardavatar) 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 ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcomposer) 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 ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcomposerinput) Props for VeltCommentDialogComposerInput. | Property | Type | Required | Description | | ------------- | -------- | -------- | ---------------------- | | `placeholder` | `string` | No | Input placeholder text | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### StatusDropdownItemProps ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogstatusdropdowncontentitem) 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 ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogprioritydropdowncontentitem) 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 ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogoptionsdropdown) 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 ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcustomannotationdropdowntriggerlistitem) 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 ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogreplyavatarslistitem) 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). #### 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 *** Type: `'editor' | 'viewer'` * editor: Write access * viewer: Read-only access #### UserPermissionAccessRoleResult *** Type: `'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 #### 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 *** | Property | Type | Required | Description | | ------------ | -------- | -------- | -------------------------------------------- | | `color` | `string` | Yes | Primary color for the status. | | `id` | `string` | Yes | Unique identifier for the status. | | `lightColor` | `string` | Yes | Light variant of the status color. | | `name` | `string` | Yes | Display name of the status. | | `svg` | `string` | Yes | SVG icon for the status. | | `type` | `string` | No | Optional type classification for the status. | #### 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. | #### 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 | #### CommentSidebarFilters *** | Property | Type | Required | Description | | ---------- | -------------------- | -------- | ---------------------------------------------------------------------------------------- | | `location` | `{id: string}[]` | No | Filter by location Ids | | `document` | `{id: string}[]` | No | Filter by document Ids | | `people` | `{userId: string}[]` | No | Filter by author of comment annotation | | `tagged` | `{userId: string}[]` | No | Filter by users who were tagged/mentioned in the comment | | `assigned` | `{userId: string}[]` | No | Filter by users who were assigned to the comment annotation | | `involved` | `{userId: string}[]` | No | Filter by users who are involved in the comment annotation (author, mentioned, assigned) | | `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 | #### 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. Defaults to true | | `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 *** | Property | Type | Required | Description | | ------------------------ | -------- | -------- | ----------------------------------------------------------------------------------------------- | | `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` | `string` | No | Sidebar position, e.g., `'right'`, `'left'` | | `variant` | `string` | No | Sidebar variant, e.g., `'sidebar'`, `'inline'` | | `forceClose` | `boolean` | No | Force-close the sidebar | | `version` | `string` | No | When `"2"`, routes `VeltCommentsSidebar` to the V2 implementation | | `onSidebarOpen` | `(data: any) => void` | No | Callback when sidebar opens | | `onSidebarClose` | `(data: any) => void` | No | Callback when sidebar closes | | `onCommentClick` | `(data: any) => void` | No | Callback when a comment is clicked | | `onCommentNavigationButtonClick` | `(data: any) => void` | No | Callback when navigation 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 | #### 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. | #### 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-primitives) for usage examples. #### NotificationsPrimitiveCommonProps ## [Usage Examples →](/ui-customization/features/async/notifications/notifications-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 *** | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------------------------------------------------- | | `ONLINE` | string | Yes | Server connection is online and active. Value: 'online' | | `OFFLINE` | string | Yes | Server connection is offline. Value: 'offline' | | `PENDING_INIT` | string | Yes | Server connection initialization is pending. Value: 'pendingInit' | | `PENDING_DATA` | string | Yes | Server is waiting for data. Value: 'pendingData' | # 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 | Only allows the provided Velt features to run. | | `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 | #### 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 | | `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 *** | Property | Type | Required | Description | | ------------- | -------- | -------- | --------------------------------- | | `baseUrl` | `string` | Yes | Base URL of the page. | | `path` | `string` | Yes | Path of the page. | | `queryParams` | `string` | No | Query parameters of the page URL. | | `title` | `string` | Yes | Title of the page. | | `url` | `string` | Yes | Full URL of the page. | #### 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. | | `organizationId` | `string` | No | Unique identifier for the organization. | | `folderId` | `string` | No | Unique identifier for the folder. | #### Document *** | Property | Type | Required | Description | | ---------- | ------------------ | -------- | ------------------------------------- | | `id` | `string` | Yes | Unique identifier for the document | | `metadata` | `DocumentMetadata` | Yes | Metadata associated with 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` | No | Unique identifier for the location. | | `locationName` | `string` | No | Name of the location. | | `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 | #### ResolverActions *** An enum that defines the different types of actions that can trigger resolver events. | Name | 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 | #### 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` | `{ [attachmentId: number]: PartialAttachment }` | 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 | #### 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` | Yes | Map of comment IDs to partial comments data | #### 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` | No | Custom HTTP headers for the request | #### 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 | #### 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 | #### 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 | #### 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 | | `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 Enum *** | Enum Name | Event Type | Description | | ------------------------- | ----------------------- | ------------------------------ | | `ALL` | `all` | Show all the contacts | | `ORGANIZATION` | `organization` | Show organization contacts. | | `ORGANIZATION_USER_GROUP` | `organizationUserGroup` | Show organization user groups. | | `DOCUMENT` | `document` | Show document 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 Enum *** | Enum Name | Value | Description | | --------- | --------- | ------------------------------------------------- | | `Start` | `'start'` | Indicator anchored at the start of the selection. | | `End` | `'end'` | Indicator anchored at the end of the selection. | #### UserIndicatorType Enum *** | Enum Name | Value | Description | | --------- | ---------- | ------------------------------------ | | `Avatar` | `'avatar'` | Show user's avatar on the indicator. | | `Label` | `'label'` | Show 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 | | `baseUrl` | `string` | No | Base URL (domain) of a webpage | | `title` | `string` | No | Title of the webpage | | `commentUrl` | `string` | No | Reference url of a comment annotation | | `recorderUrl` | `string` | No | Reference url of a recorder annotation | | `screenWidth` | `number` | No | User's screen width. 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. | #### UserOptions *** | Property | Type | Required | Description | | ----------------- | ------- | -------- | ---------------------------------------------------------------------------------------------- | | `replaceContacts` | boolean | No | If set to true, it will replace the user's personal and group contacts with the ones provided. | | `authToken` | string | No | The authentication token of the user. | | `throwError` | boolean | No | If true, throws error if user authentication fails. Default: false. | #### 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 *** Enum specifying when to automatically revoke permissions. | Value | Description | | ---------------- | ---------------------------------------------------- | | `DOCUMENT_UNSET` | Revoke access when user unsets or leaves a document | | `USER_LOGOUT` | Revoke access when user logs out of the organization | #### PermissionSource *** Enum identifying which SDK method triggered the permission check. This helps debug and trace permission request origins. | Value | Description | | ------------------- | ----------------------------------------------------- | | `SET_DOCUMENTS` | Permission check triggered by `setDocuments()` method | | `IDENTIFY` | Permission check triggered by `identify()` method | | `GET_NOTIFICATIONS` | Permission check triggered by notifications fetching | | `SET_NOTIFICATIONS` | Permission check triggered by notifications setting | #### PermissionResourceType *** Enum defining the types of resources that can be validated through Permission Provider. Used in permission queries to identify the resource type being accessed. | Value | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `ORGANIZATION` | `organization`: Organization-level resource permissions | | `DOCUMENT` | `document`: Document-level resource permissions | | `LOCATION` | `location`: Location-specific resource permissions within a document | | `CONTEXT` | `context`: Context-based resource permissions. Added in v4.5.8-beta.4 for granular context-level access control 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). | #### 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) `}` | Yes | Resource the user is requesting access to. The `type` uses [`PermissionResourceType`](#permissionresourcetype) enum. 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. | #### 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 `organization`, `document`, `location`, 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. | # 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 | #### 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 | | `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) to override `summary` or `metadata` on commit. | Property | Type | Required | Description | | ---------- | ------------------------- | -------- | ------------------------------------ | | `summary` | `string` | No | Override for the suggestion summary | | `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 | 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. | ### `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. | ### `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. |