@veltdev/sdk-staging 5.0.2-beta.2 → 5.0.2-beta.21

package/app/client/snippyly.model.d.ts

@@ -5,6 +5,7 @@ import { DocumentUser } from "../models/data/document-user.data.model";
 import { Location } from "../models/data/location.model";
 import { User, UserOptions, VeltAuthProvider, VeltPermissionProvider } from "../models/data/user.data.model";
 import { CustomCss } from "../models/data/custom-css.data.model";
+import { ActivityElement } from "../models/element/activity-element.model";
 import { AreaElement } from "../models/element/area-element.model";
 import { ArrowElement } from "../models/element/arrow-element.model";
 import { CommentElement } from "../models/element/comment-element.model";
@@ -29,7 +30,7 @@ import { VeltEventMetadata, VeltDebugInfo } from "../models/data/event-metadata.
 import { CoreEventTypesMap } from "../models/data/core-events.data.model";
 import { Document, SetDocumentsRequestOptions, FetchDocumentsRequest, FetchFoldersRequest, UpdateDocumentsRequest, UpdateLocationsRequest } from "../models/data/document.data.model";
 import { FetchDocumentsResponse, FetchFoldersResponse } from "../models/data/document-events.data.model";
-import { UserDataProvider, GetUserPermissionsRequest, GetUserPermissionsResponse } from "../models/data/user-resolver.data.model";
+import { AnonymousUserDataProvider, UserDataProvider, GetUserPermissionsRequest, GetUserPermissionsResponse } from "../models/data/user-resolver.data.model";
 import { VeltDataProvider } from "../models/data/provider.data.model";
 import { VeltEncryptionProvider } from "../models/data/encryption-provider.data.model";
 import { VeltResetButtonStateConfig } from "../models/data/button.data.model";
@@ -97,6 +98,10 @@ export declare class Snippyly {
     * To set the user data provider.
     */
    setUserDataProvider: (userDataProvider: UserDataProvider) => void;
+   /**
+    * To set the anonymous user data provider.
+    */
+   setAnonymousUserDataProvider: (resolver: AnonymousUserDataProvider, config?: { ha?: boolean }) => void;
    /**
     * To set the data provider.
     */
@@ -228,6 +233,10 @@ export declare class Snippyly {
     * Get the Autocomplete Object.
     */
    getAutocompleteElement: () => AutocompleteElement;
+   /**
+    * Get the Activity Element Object.
+    */
+   getActivityElement: () => ActivityElement;
    /**
     * Get the Area Object.
     */

package/app/models/data/activity.data.model.d.ts

@@ -0,0 +1,177 @@
+import { Observable } from 'rxjs';
+import { BaseMetadata } from './base-metadata.data.model';
+import { User } from './user.data.model';
+/**
+ * Feature types that can generate activities.
+ */
+export type ActivityFeatureType = 'comment' | 'reaction' | 'recorder' | 'crdt' | 'custom';
+/**
+ * Comment action type constants following the `entity_type.action` naming pattern.
+ * Annotation-level actions use `comment_annotation.*`, comment-level use `comment.*`.
+ */
+export declare const CommentActivityActionTypes: {
+    readonly ANNOTATION_ADD: "comment_annotation.add";
+    readonly ANNOTATION_DELETE: "comment_annotation.delete";
+    readonly COMMENT_ADD: "comment.add";
+    readonly COMMENT_UPDATE: "comment.update";
+    readonly COMMENT_DELETE: "comment.delete";
+    readonly STATUS_CHANGE: "comment_annotation.status_change";
+    readonly PRIORITY_CHANGE: "comment_annotation.priority_change";
+    readonly ASSIGN: "comment_annotation.assign";
+    readonly ACCESS_MODE_CHANGE: "comment_annotation.access_mode_change";
+    readonly CUSTOM_LIST_CHANGE: "comment_annotation.custom_list_change";
+    readonly APPROVE: "comment_annotation.approve";
+    readonly ACCEPT: "comment.accept";
+    readonly REJECT: "comment.reject";
+    readonly REACTION_ADD: "comment.reaction_add";
+    readonly REACTION_DELETE: "comment.reaction_delete";
+    readonly SUBSCRIBE: "comment_annotation.subscribe";
+    readonly UNSUBSCRIBE: "comment_annotation.unsubscribe";
+};
+export type CommentActivityActionType = typeof CommentActivityActionTypes[keyof typeof CommentActivityActionTypes];
+/**
+ * Recorder action type constants following the `recording.*` naming pattern.
+ */
+export declare const RecorderActivityActionTypes: {
+    readonly RECORDING_ADD: "recording.add";
+    readonly RECORDING_DELETE: "recording.delete";
+};
+export type RecorderActivityActionType = typeof RecorderActivityActionTypes[keyof typeof RecorderActivityActionTypes];
+/**
+ * Reaction action type constants following the `reaction.*` naming pattern.
+ */
+export declare const ReactionActivityActionTypes: {
+    readonly REACTION_ADD: "reaction.add";
+    readonly REACTION_DELETE: "reaction.delete";
+};
+export type ReactionActivityActionType = typeof ReactionActivityActionTypes[keyof typeof ReactionActivityActionTypes];
+/**
+ * CRDT action type constants following the `crdt.*` naming pattern.
+ */
+export declare const CrdtActivityActionTypes: {
+    readonly EDITOR_EDIT: "crdt.editor_edit";
+};
+export type CrdtActivityActionType = typeof CrdtActivityActionTypes[keyof typeof CrdtActivityActionTypes];
+/**
+ * Represents a single from/to change pair.
+ * `from` is always present (null for 'added' events) for uniform structure.
+ */
+export interface ActivityChange<T = unknown> {
+    from?: T | null;
+    to?: T | null;
+}
+/**
+ * Dynamic change tracking. Keys are domain-specific (e.g., 'status', 'commentText', 'assignedTo').
+ * No fixed keys — activities span multiple features.
+ */
+export interface ActivityChanges {
+    [key: string]: ActivityChange | undefined;
+}
+/**
+ * Metadata for activity records. Extends BaseMetadata with denormalized IDs
+ * for efficient querying at the organization level.
+ */
+export declare class ActivityMetadata extends BaseMetadata {
+    [key: string]: any;
+}
+/**
+ * Core activity record representing a single activity event.
+ *
+ * @typeParam TEntity - Type of the parent entity snapshot (e.g., CommentAnnotation)
+ * @typeParam TTarget - Type of the sub-entity snapshot (e.g., Comment)
+ */
+export declare class ActivityRecord<TEntity = unknown, TTarget = unknown> {
+    /** Auto-generated unique ID */
+    id: string;
+    /** Feature that generated this activity */
+    featureType: ActivityFeatureType;
+    /** Action that occurred, following `entity_type.action` pattern */
+    actionType: string;
+    /** Event type that occurred */
+    eventType?: string;
+    /** User who performed the action */
+    actionUser: User;
+    /** Server timestamp (set by backend) */
+    timestamp: number;
+    /** Denormalized IDs for querying */
+    metadata: ActivityMetadata;
+    /** ID of the parent entity (annotationId, recordingId, etc.) */
+    targetEntityId: string;
+    /** ID of the sub-entity acted on (commentId within annotation, null for entity-level actions) */
+    targetSubEntityId?: string | null;
+    /** Linear-style from/to change pairs */
+    changes?: ActivityChanges;
+    /** Full parent entity snapshot at time of action */
+    entityData?: TEntity;
+    /** Sub-entity snapshot (or user-provided data for custom activities) */
+    entityTargetData?: TTarget;
+    /** Display message template — ONLY for custom activities */
+    displayMessageTemplate?: string;
+    /** Template variable values — ONLY for custom activities */
+    displayMessageTemplateData?: Record<string, unknown>;
+    /** Computed display message (generated client-side, never stored in Firestore) */
+    displayMessage?: string;
+    /** Icon URL or identifier for display */
+    actionIcon?: string;
+    /** If true, this activity cannot be updated or deleted via REST API */
+    immutable?: boolean;
+}
+/**
+ * Configuration for subscribing to activities.
+ * Behavior is determined by the props passed:
+ * - No config → org-wide
+ * - documentIds → specific documents
+ * - currentDocumentOnly → current document only
+ */
+export interface ActivitySubscribeConfig {
+    /** Subscribe to activities for a specific organization (defaults to current org) */
+    organizationId?: string;
+    /** Subscribe to activities for specific document IDs */
+    documentIds?: string[];
+    /** Subscribe to activities for the current document only (auto-switches on setDocument) */
+    currentDocumentOnly?: boolean;
+    /** Only fetch activities from the last N days (default: 30) */
+    maxDays?: number;
+    /** Allowlist: only include activities with these feature types */
+    featureTypes?: ActivityFeatureType[];
+    /** Disallowlist: exclude activities with these feature types (ignored if featureTypes is set) */
+    excludeFeatureTypes?: ActivityFeatureType[];
+    /** Allowlist: only include activities with these action types */
+    actionTypes?: string[];
+    /** Disallowlist: exclude activities with these action types (ignored if actionTypes is set) */
+    excludeActionTypes?: string[];
+    /** Allowlist: only include activities by these user IDs */
+    userIds?: string[];
+    /** Disallowlist: exclude activities by these user IDs (ignored if userIds is set) */
+    excludeUserIds?: string[];
+}
+/**
+ * Represents an active activity subscription.
+ * Returned by `activityService.subscribe()`.
+ */
+export interface ActivitySubscription {
+    /** Observable stream of activities for this subscription's scope. null = not yet loaded. */
+    getActivities$(): Observable<ActivityRecord[] | null>;
+    /** Unsubscribe and clean up this subscription */
+    unsubscribe(): void;
+}
+/**
+ * Data required to create an activity.
+ * Used for all activity types: comment, reaction, recorder, custom, etc.
+ */
+export interface CreateActivityData<TEntity = unknown, TTarget = unknown> {
+    featureType: ActivityFeatureType;
+    actionType: string;
+    eventType?: string;
+    targetEntityId: string;
+    targetSubEntityId?: string | null;
+    changes?: ActivityChanges;
+    entityData?: TEntity;
+    entityTargetData?: TTarget;
+    /** Icon URL or identifier — typically used for custom activities */
+    actionIcon?: string;
+    /** Display message template — only for custom activities */
+    displayMessageTemplate?: string;
+    /** Template variable values — only for custom activities */
+    displayMessageTemplateData?: Record<string, unknown>;
+}

package/app/models/data/autocomplete.data.model.d.ts

@@ -22,17 +22,17 @@ export declare class AutocompleteItem {
     groupId?: string;
 }
 export declare class AutocompleteReplaceData {
-    text: string;
+    text?: string;
     custom: AutocompleteItem;
 }
 export declare class AutocompleteGroupReplaceData {
-    text: string;
+    text?: string;
     groupId: string;
     clientGroupId: string;
     group?: OrganizationUserGroup;
 }
 export declare class AutocompleteUserContactReplaceData {
-    text: string;
+    text?: string;
     userId: string;
     contact?: UserContact;
 }

package/app/models/data/base-metadata.data.model.d.ts

@@ -1,3 +1,4 @@
+import { DocumentMetadata } from './document-metadata.model';
 export declare class BaseMetadata {
     apiKey?: string;
     documentId?: string;
@@ -6,4 +7,6 @@ export declare class BaseMetadata {
     clientOrganizationId?: string;
     folderId?: string;
     veltFolderId?: string;
+    documentMetadata?: DocumentMetadata;
+    sdkVersion?: string | null;
 }

package/app/models/data/comment-actions.data.model.d.ts

@@ -141,6 +141,8 @@ export interface AddCommentRequest {
     assignedTo?: User;
     assigned?: boolean;
     options?: RequestOptions;
+    /** Optional visibility configuration for the comment */
+    visibility?: CommentVisibilityConfig;
 }
 export interface UpdateCommentRequest {
     annotationId: string;

package/app/models/data/comment-annotation.data.model.d.ts

@@ -1,5 +1,6 @@
-import { CommentAccessMode } from "../../utils/enums";
+import { CommentAccessMode, CommentVisibilityOptionType } from "../../utils/enums";
 import { BaseMetadata } from "./base-metadata.data.model";
+import { CommentVisibilityType } from "./comment-actions.data.model";
 import { Comment } from "./comment.data.model";
 import { CursorPosition } from "./cursor-position.data.model";
 import { CustomAnnotationDropdownItem } from "./custom-chip-dropdown.data.model";
@@ -10,6 +11,11 @@ import { TargetElement } from "./target-element.data.model";
 import { TargetTextRange } from "./target-text-range.data.model";
 import { User } from "./user.data.model";
 import { CommentAnnotationViews } from "./views.data.model";
+export interface CommentAnnotationVisibilityConfig {
+    type: CommentVisibilityType;
+    organizationId?: string;
+    userIds?: string[];
+}
 export declare class CommentAnnotation {
     /**
      * Unique identifier for the comment pin annotation.
@@ -23,6 +29,7 @@ export declare class CommentAnnotation {
      * Auto generated.
      */
     annotationNumber?: number;
+    visibilityConfig?: CommentAnnotationVisibilityConfig;
     /**
      * This is the list of all comments part of this annotation.
      *
@@ -232,9 +239,10 @@ export declare class CommentSelectionChangeData {
     selected: boolean;
     annotation: CommentAnnotation;
 }
-export declare class LocationClickedData {
+export declare class VisibilityOptionClickedData {
     annotationId: string;
-    location: 'public' | 'private';
+    visibility: CommentVisibilityOptionType;
+    users?: any[];
 }
 export declare class InlineCommentSectionConfig {
     id: string;

package/app/models/data/comment-events.data.model.d.ts

@@ -1,4 +1,4 @@
-import { AssignToType, CommentAccessMode, CommentEventTypes, CommentStatus } from "../../utils/enums";
+import { AssignToType, CommentAccessMode, CommentEventTypes, CommentStatus, CommentVisibilityOptionType } from "../../utils/enums";
 import { Attachment } from "./attachment.model";
 import { VeltButtonClickEvent } from "./button.data.model";
 import { AddAttachmentResponse } from "./comment-actions.data.model";
@@ -85,10 +85,13 @@ export type CommentEventTypesMap = {
     [CommentEventTypes.COMMENT_PIN_CLICKED]: CommentPinClickedEvent;
     [CommentEventTypes.COMMENT_BUBBLE_CLICKED]: CommentBubbleClickedEvent;
     [CommentEventTypes.COMMENT_TOOL_CLICK]: CommentToolClickEvent;
+    [CommentEventTypes.COMMENT_TOOL_CLICKED]: CommentToolClickedEvent;
     [CommentEventTypes.SIDEBAR_BUTTON_CLICK]: SidebarButtonClickEvent;
+    [CommentEventTypes.SIDEBAR_BUTTON_CLICKED]: SidebarButtonClickedEvent;
     [CommentEventTypes.ATTACHMENT_DOWNLOAD_CLICKED]: AttachmentDownloadClickedEvent;
     [CommentEventTypes.COMMENT_SAVED]: CommentSavedEvent;
-    [CommentEventTypes.LOCATION_CLICKED]: LocationClickedEvent;
+    [CommentEventTypes.COMMENT_SAVE_TRIGGERED]: CommentSaveTriggeredEvent;
+    [CommentEventTypes.VISIBILITY_OPTION_CLICKED]: VisibilityOptionClickedEvent;
 };
 export interface AddAttachmentEvent {
     annotationId: string;
@@ -183,6 +186,11 @@ export interface CommentSavedEvent {
     commentAnnotation: CommentAnnotation;
     metadata: VeltEventMetadata;
 }
+export interface CommentSaveTriggeredEvent {
+    annotationId: string;
+    commentAnnotation: CommentAnnotation;
+    metadata: VeltEventMetadata;
+}
 export interface UpdateCommentEvent {
     annotationId: string;
     commentAnnotation: CommentAnnotation;
@@ -309,18 +317,23 @@ export interface CommentToolClickEvent {
     targetElementId?: string | null;
     metadata?: VeltEventMetadata;
 }
+export interface CommentToolClickedEvent extends CommentToolClickEvent {
+}
 export interface SidebarButtonClickEvent {
     metadata?: VeltEventMetadata;
 }
+export interface SidebarButtonClickedEvent extends SidebarButtonClickEvent {
+}
 export interface AttachmentDownloadClickedEvent {
     annotationId: string;
     commentAnnotation: CommentAnnotation;
     attachment: Attachment;
     metadata?: VeltEventMetadata;
 }
-export interface LocationClickedEvent {
+export interface VisibilityOptionClickedEvent {
     annotationId: string;
     commentAnnotation: CommentAnnotation;
-    location: 'public' | 'private';
+    visibility: CommentVisibilityOptionType;
+    users?: any[];
     metadata?: VeltEventMetadata;
 }

package/app/models/data/config.data.model.d.ts

@@ -76,4 +76,9 @@ export interface DisableLogsConfig {
 }
 export interface GetProjectConfigResponse {
     isPrivateCommentsEnabled: boolean;
+    activityConfig?: ActivityConfig;
+}
+export interface ActivityConfig {
+    immutable: boolean;
+    isEnabled: boolean;
 }

package/app/models/data/core-events.data.model.d.ts

@@ -23,7 +23,8 @@ export declare enum UserResolverSource {
     SET_SINGLE_EDITOR_MODE_LIVE_STATE_DATA_FOR_DIFFERENT_USER_PRESENT_ON_TAB = "setSingleEditorModeLiveStateDataForDifferentUserPresentOnTab",
     RESOLVE_AND_MERGE_SINGLE_EDITOR_LIVE_STATE_DATA_WITH_USER = "resolveAndMergeSingleEditorLiveStateDataWithUser",
     GET_SINGLE_EDITOR_MODE_DATA = "getSingleEditorModeData",
-    RESOLVE_USERS_FROM_HUDDLE_MESSAGES = "resolveUsersFromHuddleMessages"
+    RESOLVE_USERS_FROM_HUDDLE_MESSAGES = "resolveUsersFromHuddleMessages",
+    RESOLVE_USER_IDS_BY_EMAIL = "resolveUserIdsByEmail"
 }
 export declare enum UserResolverModuleName {
     IDENTIFY = "identify/authProvider",

package/app/models/data/crdt.data.model.d.ts

@@ -58,3 +58,54 @@ export interface CrdtDeleteVersionQuery {
     id: string;
     versionId: string;
 }
+export interface CrdtPushMessageQuery {
+    id: string;
+    data: number[];
+    yjsClientId: number;
+    messageType?: 'sync' | 'awareness';
+    /** User-facing value for event emission only (not stored in database) */
+    eventData?: unknown;
+    /** Yjs data type: 'text' | 'map' | 'array' | 'xml' | 'xmltext' */
+    type?: string;
+    /** Content key used in Y.Doc shared types */
+    contentKey?: string;
+    /** Editor/library source: 'tiptap', 'plate', 'codemirror', etc. */
+    source?: string;
+}
+export interface CrdtOnMessageQuery {
+    id: string;
+    callback: (message: CrdtMessageData) => void;
+    afterTs?: number;
+}
+export interface CrdtMessageData {
+    data: number[];
+    yjsClientId: number;
+    timestamp: number;
+}
+export interface CrdtSnapshotData {
+    state?: Uint8Array | number[];
+    vector?: Uint8Array | number[];
+    timestamp?: number;
+}
+export interface CrdtGetSnapshotQuery {
+    id: string;
+}
+export interface CrdtSaveSnapshotQuery {
+    id: string;
+    state: Uint8Array | number[];
+    vector: Uint8Array | number[];
+    /** Yjs data type: 'text' | 'map' | 'array' | 'xml' | 'xmltext' */
+    type?: string;
+    /** Content key used in Y.Doc shared types */
+    contentKey?: string;
+    /** Editor/library source: 'tiptap', 'plate', 'codemirror', etc. */
+    source?: string;
+}
+export interface CrdtGetMessagesQuery {
+    id: string;
+    afterTs?: number;
+}
+export interface CrdtPruneMessagesQuery {
+    id: string;
+    beforeTs: number;
+}

package/app/models/data/live-state-events.data.model.d.ts

@@ -5,12 +5,18 @@ export interface AccessRequestEvent {
     editor?: User;
     timestamp?: number;
     status?: string;
+    totalUsers?: number;
+    presenceSnippylyUserIds?: string[];
+    presenceClientUserIds?: string[];
 }
 export interface SEMEvent {
     viewer?: User;
     editor?: User;
     timestamp?: number;
     role?: string;
+    totalUsers?: number;
+    presenceSnippylyUserIds?: string[];
+    presenceClientUserIds?: string[];
 }
 export type LiveStateEventTypesMap = {
     [LiveStateSyncEventTypes.ACCESS_REQUESTED]: AccessRequestEvent;

package/app/models/data/provider.data.model.d.ts

@@ -1,10 +1,11 @@
 import { CommentAnnotationDataProvider } from "./comment-resolver.data.model";
 import { AttachmentDataProvider } from "./attachment-resolver.data.model";
 import { ReactionAnnotationDataProvider } from "./reaction-resolver.data.model";
-import { UserDataProvider } from "./user-resolver.data.model";
+import { AnonymousUserDataProvider, UserDataProvider } from "./user-resolver.data.model";
 export interface VeltDataProvider {
     comment?: CommentAnnotationDataProvider;
     user?: UserDataProvider;
     reaction?: ReactionAnnotationDataProvider;
     attachment?: AttachmentDataProvider;
+    anonymousUser?: AnonymousUserDataProvider;
 }

package/app/models/data/user-resolver.data.model.d.ts

@@ -1,10 +1,24 @@
-import { ResolverConfig } from "./resolver.data.model";
+import { ResolverConfig, ResolverResponse, RetryConfig } from "./resolver.data.model";
 import { User } from "./user.data.model";
 export interface UserDataProvider {
     get(userIds: string[]): Promise<Record<string, User>>;
     config?: ResolverConfig;
     resolveTimeout?: number;
 }
+export interface AnonymousUserDataProvider {
+    resolveUserIdsByEmail(request: ResolveUserIdsByEmailRequest): Promise<ResolverResponse<Record<string, string>>>;
+    config?: AnonymousUserDataProviderConfig;
+}
+export interface AnonymousUserDataProviderConfig {
+    resolveTimeout?: number;
+    getRetryConfig?: RetryConfig;
+}
+export interface ResolveUserIdsByEmailRequest {
+    organizationId: string;
+    documentId?: string;
+    folderId?: string;
+    emails: string[];
+}
 export interface GetUserResolverRequest {
     organizationId: string;
     userIds: string[];

package/app/models/element/activity-element.model.d.ts

@@ -0,0 +1,33 @@
+// @ts-nocheck
+import { Observable } from "rxjs";
+import { ActivityRecord, ActivitySubscribeConfig, CreateActivityData } from "../data/activity.data.model";
+
+export declare class ActivityElement {
+
+    /**
+     * Subscribe to activities with optional filtering configuration.
+     * Returns an Observable that, when unsubscribed, automatically cleans up the internal subscription.
+     * @param config Optional configuration to filter activities by scope, feature types, action types, etc.
+     * @returns Observable<ActivityRecord[] | null>
+     */
+    getAllActivities: (config?: ActivitySubscribeConfig) => Observable<ActivityRecord[] | null>;
+
+    /**
+     * Create a new activity record.
+     * @param data The activity data including feature type, action type, target entity, etc.
+     * @returns Promise<void>
+     */
+    createActivity: (data: CreateActivityData) => Promise<void>;
+
+    constructor();
+
+    /**
+     * Subscribe to activities with optional filtering configuration.
+     */
+    private _getAllActivities;
+
+    /**
+     * Create a new activity record.
+     */
+    private _createActivity;
+}

package/app/models/element/comment-element.model.d.ts

@@ -290,6 +290,16 @@ export declare class CommentElement {
    */
   public disableStatus: () => any;
 
+  /**
+   * To enable visibility options on comments
+   */
+  public enableVisibilityOptions: () => any;
+
+  /**
+   * To disable visibility options on comments
+   */
+  public disableVisibilityOptions: () => any;
+
   /**
    * To enable feature to show resolve button
    */
@@ -1615,6 +1625,16 @@ export declare class CommentElement {
    */
   private _disableStatus;
 
+  /**
+   * To enable visibility options on comments
+   */
+  private _enableVisibilityOptions;
+
+  /**
+   * To disable visibility options on comments
+   */
+  private _disableVisibilityOptions;
+
   /**
    * To enable feature to show resolve button
    */