@veltdev/sdk 5.0.2-beta.5 → 5.0.2-beta.7

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";
@@ -232,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/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/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/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/crdt-element.model.d.ts

@@ -95,6 +95,11 @@ export declare class CrdtElement {
      * @param time debounce time in milliseconds
      */
     setWebhookDebounceTime: (time: number) => void;
+    /**
+     * To set activity debounce time for batching CRDT edits (Default value is 10 minutes)
+     * @param time debounce time in milliseconds (minimum: 10 seconds)
+     */
+    setActivityDebounceTime: (time: number) => void;
 
     /**
      * Subscribe to crdt actions
@@ -204,6 +209,12 @@ export declare class CrdtElement {
      */
     private _setWebhookDebounceTime;
 
+    /**
+     * Set activity debounce time for batching CRDT edits
+     * @param time debounce time in milliseconds (minimum: 10 seconds)
+     */
+    private _setActivityDebounceTime;
+
     /**
      * Subscribe to crdt actions
      * @param action Action to subscribe to

package/app/utils/constants.d.ts

@@ -57,6 +57,8 @@ export declare class Constants {
     static FIREBASE_PARTIAL_PATH_NOTIFICATIONS: string;
     static FIREBASE_PARTIAL_PATH_ORGANIZATION_NOTIFICATIONS: string;
     static FIREBASE_PARTIAL_PATH_LAST_NOTIFICATION_TIMESTAMP: string;
+    static FIREBASE_PARTIAL_PATH_ACTIVITIES: string;
+    static FIREBASE_PARTIAL_PATH_LAST_ACTIVITY_TIMESTAMP: string;
     static FIREBASE_PARTIAL_PATH_HEARTBEAT: string;
     static FIREBASE_PARTIAL_PATH_HEARTBEAT_BY_DOCUMENT: string;
     static FIREBASE_PARTIAL_PATH_USERS: string;
@@ -259,6 +261,21 @@ export declare class Constants {
         VELT_AUTOCOMPLETE_CHIP_TOOLTIP_NAME: string;
         VELT_AUTOCOMPLETE_CHIP_TOOLTIP_DESCRIPTION: string;
         VELT_AUTOCOMPLETE_CONTEXT_WRAPPER: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER_ICON: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER_TEXT: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER_DROPDOWN: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER_DROPDOWN_TRIGGER: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER_DROPDOWN_TRIGGER_LABEL: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER_DROPDOWN_TRIGGER_AVATAR_LIST: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER_DROPDOWN_TRIGGER_AVATAR_LIST_ITEM: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER_DROPDOWN_TRIGGER_AVATAR_LIST_REMAINING_COUNT: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER_DROPDOWN_TRIGGER_ICON: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER_DROPDOWN_CONTENT: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER_DROPDOWN_CONTENT_ITEM: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER_DROPDOWN_CONTENT_ITEM_ICON: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER_DROPDOWN_CONTENT_ITEM_LABEL: string;
+        VELT_COMMENT_DIALOG_VISIBILITY_BANNER_DROPDOWN_CONTENT_USER_PICKER: string;
         VELT_COMMENT_COMPOSER: string;
         VELT_SKELETON_LOADER: string;
         VELT_SHADOW_DOM_INTERNAL: string;

package/app/utils/enums.d.ts

@@ -172,7 +172,8 @@ export declare enum Features {
     REWRITER = "rewriter",
     LIVE_SELECTION = "liveSelection",
     NOTIFICATION = "notification",
-    REACTION = "reaction"
+    REACTION = "reaction",
+    ACTIVITY = "activity"
 }
 export declare enum AnalyticsFeatures {
     AREA = "area",
@@ -194,7 +195,7 @@ export declare enum AnalyticsFeatures {
     INLINE_COMMENT = "inlineComment",
     COMMENT_SIDEBAR = "commentSidebar"
 }
-export type FeatureType = 'area' | 'arrow' | 'audioHuddle' | 'comment' | 'cursor' | 'huddle' | 'liveStateSync' | 'presence' | 'recorder' | 'rewriter' | 'tag' | 'liveSelection' | 'notification' | 'reaction' | 'multiThread';
+export type FeatureType = 'area' | 'arrow' | 'audioHuddle' | 'comment' | 'cursor' | 'huddle' | 'liveStateSync' | 'presence' | 'recorder' | 'rewriter' | 'tag' | 'liveSelection' | 'notification' | 'reaction' | 'multiThread' | 'activity';
 export type AssignToType = 'dropdown' | 'checkbox';
 export declare enum DeviceType {
     DESKTOP = "Desktop",

package/models.d.ts

@@ -1,6 +1,7 @@
 export * from './app/utils/enums';
 export * from './app/models/data/anchor-record.data.model';
 export * from './app/models/data/attachment.model';
+export * from './app/models/data/activity.data.model';
 export * from './app/models/data/area-annotation.data.model';
 export * from './app/models/data/arrow-annotation.data.model';
 export * from './app/models/data/base-metadata.data.model';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@veltdev/sdk",
-    "version": "5.0.2-beta.5",
+    "version": "5.0.2-beta.7",
     "description": "Velt is an SDK to add collaborative features to your product within minutes. Example: Comments like Figma, Frame.io, Google docs or sheets, Recording like Loom, Huddles like Slack and much more.",
     "homepage": "https://velt.dev",
     "keywords": [

package/types.d.ts

@@ -17,4 +17,5 @@ export * from './app/models/element/notification-element.model';
 export * from './app/models/element/autocomplete-element.model';
 export * from './app/models/element/reaction-element.model';
 export * from './app/models/element/crdt-element.model';
+export * from './app/models/element/activity-element.model';
 export * from './models';