@veltdev/sdk-staging 5.0.2-beta.8 → 5.0.2-beta.80

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

@@ -0,0 +1,267 @@
+/**
+ * Suggestions feature — public type surface for v1.
+ *
+ * Source contract: docs/suggestions-api-contract.md
+ * Source flows:    docs/suggestions-implementation-flows.md
+ *
+ * Types are exported from the SDK's public barrel. Customer code interacts
+ * with these via Snippyly.getSuggestionElement(); the SDK constructs all
+ * Suggestion objects internally and customers do not build them directly.
+ */
+import { User } from './user.data.model';
+/**
+ * Lifecycle state machine for a Suggestion.
+ *
+ * - pending:      Just created, awaiting owner action.
+ * - approved:     Owner clicked Approve. Customer apply handler ran successfully.
+ * - rejected:     Owner clicked Reject (with optional reason).
+ * - stale:        Target was unresolvable at approve time. Owner can dismiss.
+ * - apply_failed: Customer apply handler threw during a suggestionApproved event.
+ *                 Status set by the SDK after the throw was caught.
+ */
+export type SuggestionStatus = 'pending' | 'accepted' | 'rejected' | 'stale' | 'apply_failed';
+/**
+ * Global per-user-per-session suggestion mode. Not persisted; reload returns to 'editing'.
+ */
+export type SuggestionMode = 'editing' | 'suggesting';
+/**
+ * Discriminator for the substrate that produced a suggestion. v1: always 'custom'.
+ * Wrapper libraries (e.g. tiptap-velt-comments) widen this union when they integrate.
+ *
+ * Customers should treat unknown values as opaque; the field exists so customer code
+ * can differentiate substrate when domain-specific rendering matters.
+ */
+export type SuggestionTargetType = 'custom';
+/**
+ * Single-arg config passed to `SuggestionElement.registerTarget(config)`.
+ * Carrying both `targetId` and `getter` in one object so the API can grow
+ * (e.g., metadata, target-specific options) without breaking customers.
+ */
+export interface RegisterTargetConfig<T = unknown> {
+    targetId: string;
+    getter: TargetGetter<T>;
+}
+/**
+ * Function the customer registers via SuggestionElement.registerTarget(config).
+ * Required for any non-primitive (wrapper) target.
+ *
+ * The SDK calls this getter twice in a typical edit cycle:
+ *   1. On focus of the tagged element — to snapshot the pre-edit value.
+ *   2. On commit (focusout / change) — to read the current value for the diff.
+ *
+ * IMPORTANT — edit-time state, not persisted state: the getter must reflect
+ * what the user is currently editing, not what's persisted in the customer's
+ * app store. If the customer's state is only updated on commit/approve (as
+ * is typical when suggesting mode is on), reading from that state would
+ * return the snapshot value at commit time, the diff check would short-
+ * circuit, and no suggestion would ever fire.
+ *
+ * Recommended: read from the DOM (controlled or uncontrolled inputs) so the
+ * getter always returns what's visible to the user.
+ *
+ *   el.registerTarget('row.123', () => ({
+ *     qty:   parseInt(qtyInput.value, 10),
+ *     price: parseInt(priceInput.value, 10),
+ *   }));
+ *
+ * For controlled inputs (state updates on every keystroke), reading from
+ * the customer state is fine: `() => myState.row123`. The contract is
+ * "edit-time state" — whichever source of truth has it.
+ */
+export type TargetGetter<T = unknown> = () => T;
+/**
+ * Returned from SuggestionElement.on(...). Calling it removes the handler.
+ */
+export type Unsubscribe = () => void;
+/**
+ * Details about a target edit, passed to the customer's resolver handler and
+ * to subscribers of `targetEditStart` / `targetEditCommit` events.
+ *
+ * `element` is the DOM element that produced the edit. It's the tagged
+ * descendant — or, for wrappers that nest interactive controls inside a
+ * tagged container, the inner element that actually fired the event. In
+ * either case the SDK walks up to the nearest ancestor carrying
+ * `data-velt-suggestion-target` to resolve `targetId`.
+ *
+ * `element` is provided for read access only — customers should not retain
+ * the reference past the synchronous handler call.
+ */
+export interface TargetEditDetails<T = unknown> {
+    targetId: string;
+    oldValue: T;
+    newValue: T;
+    element: Element | null;
+}
+/**
+ * Return type of `onTargetEditCommit`. Returning a value auto-commits the
+ * suggestion using the (optional) overrides; returning null skips the
+ * auto-commit so a subscriber to `targetEditCommit` can drive it explicitly.
+ */
+export interface TargetEditCommitResult {
+    /** Override the SDK's default `${targetId}: ${old} → ${new}` summary. */
+    summary?: string;
+    /** Customer metadata persisted on the resulting Suggestion. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Return type of `onTargetEditStart`. Reserved for future fields; v1 has
+ * no behavior-bearing return values, so customers may omit a return.
+ *
+ * Roadmap: future versions may accept `{ oldValue }` here so customers can
+ * override the SDK's auto-snapshot with a domain-canonical value.
+ */
+export interface TargetEditStartResult {
+}
+export type TargetEditStartHandler<T = unknown> = (details: TargetEditDetails<T>) => TargetEditStartResult | void | null;
+export type TargetEditCommitHandler<T = unknown> = (details: TargetEditDetails<T>) => TargetEditCommitResult | null;
+/**
+ * Config passed to `SuggestionElement.enableSuggestionMode(config?)`.
+ * Both callbacks are optional. If `onTargetEditCommit` is omitted, customers
+ * can still drive auto-commit by subscribing to the `targetEditCommit` event
+ * and calling the pre-bound `commitSuggestion` builder on the payload.
+ */
+export interface EnableSuggestionModeConfig {
+    /**
+     * Invoked on focus of a tagged element, after the SDK captures the
+     * snapshot. v1: informational — return value is reserved for future
+     * use (e.g. `{ oldValue }` to override the SDK's auto-snapshot).
+     */
+    onTargetEditStart?: TargetEditStartHandler;
+    /**
+     * Invoked once per detected commit (on `change` for atomic inputs, on
+     * `focusout` for text-like inputs). Returning a `TargetEditCommitResult`
+     * auto-commits with the supplied summary/metadata; returning null defers
+     * to event subscribers.
+     */
+    onTargetEditCommit?: TargetEditCommitHandler;
+}
+/**
+ * SDK-managed suggestion data persisted on a CommentAnnotation.
+ * Present iff annotation.type === 'suggestion'.
+ *
+ * Customer code must not write to this directly — use the SuggestionElement API.
+ */
+export interface SuggestionData {
+    /** Lifecycle state machine. */
+    status: SuggestionStatus;
+    /** Stable, customer-owned target identifier. */
+    targetId: string;
+    /** v1: always 'custom'. Wrappers widen later. */
+    targetType: SuggestionTargetType;
+    /** Snapshot taken at startSuggestion / focus time. Frozen via structuredClone. */
+    oldValue: any;
+    /** Value submitted via commitSuggestion. */
+    newValue: any;
+    /** Optional human-readable description for logs / notifications. */
+    summary: string | null;
+    /**
+     * True if the live value at approve time differed from oldValue.
+     * v1 records flag only; v1.1 will surface a confirmation prompt.
+     */
+    driftDetected: boolean;
+    /** Populated only when status === 'rejected'. */
+    rejectReason: string | null;
+    /**
+     * Full User snapshot of the resolver, populated when status moves to
+     * approved | rejected | stale | apply_failed. Snapshot rather than userId
+     * so customer code can render name/email/photoUrl without an extra lookup,
+     * and so historical suggestions retain their resolver record even if the
+     * user later updates their profile.
+     */
+    resolvedBy: User | null;
+    resolvedAt: number | null;
+}
+/**
+ * Fields shared across every Suggestion regardless of status.
+ * Internal — used to build the per-status discriminated types below.
+ */
+interface SuggestionBase<T = unknown> {
+    /** Annotation document id (same as the underlying CommentAnnotation.annotationId). */
+    annotationId: string;
+    /** Stable, customer-owned target identifier. */
+    targetId: string;
+    /** v1: always 'custom'. */
+    targetType: SuggestionTargetType;
+    /** Snapshot taken at startSuggestion / focus time. */
+    oldValue: T;
+    /** Value submitted via commitSuggestion. */
+    newValue: T;
+    /** Optional human-readable description. */
+    summary: string | null;
+    /** Customer-defined metadata supplied via CommitSuggestionConfig.metadata. */
+    metadata: Record<string, any>;
+    /** True iff the live value at approve time differed from oldValue. */
+    driftDetected: boolean;
+    /**
+     * User of the suggestion's creator (sourced from annotation.from).
+     */
+    createdBy?: User;
+    createdAt: number;
+}
+/** A suggestion in the 'pending' state — newly created, no owner action yet. */
+export interface PendingSuggestion<T = unknown> extends SuggestionBase<T> {
+    status: 'pending';
+    rejectReason: null;
+    resolvedBy: null;
+    resolvedAt: null;
+}
+/** A suggestion that has been approved (apply handler success or pending invocation). */
+export interface ApprovedSuggestion<T = unknown> extends SuggestionBase<T> {
+    status: 'accepted' | 'apply_failed';
+    rejectReason: null;
+    resolvedBy: User;
+    resolvedAt: number;
+}
+/**
+ * A suggestion that has been rejected. `rejectReason` may be null when the
+ * rejecter dismissed without supplying a reason — matches the persisted
+ * `SuggestionData.rejectReason: string | null` shape.
+ */
+export interface RejectedSuggestion<T = unknown> extends SuggestionBase<T> {
+    status: 'rejected';
+    rejectReason: string | null;
+    resolvedBy: User;
+    resolvedAt: number;
+}
+/** A suggestion whose target was unresolvable at approve time. */
+export interface StaleSuggestion<T = unknown> extends SuggestionBase<T> {
+    status: 'stale';
+    rejectReason: null;
+    resolvedBy: User | null;
+    resolvedAt: number | null;
+}
+/**
+ * Public Suggestion — discriminated union keyed by `status`. TypeScript narrows
+ * field types per status (e.g. `resolvedBy: User` is non-null on approved/rejected,
+ * `rejectReason: string | null` on rejected since one-click reject without a reason
+ * is supported).
+ */
+export type Suggestion<T = unknown> = PendingSuggestion<T> | ApprovedSuggestion<T> | RejectedSuggestion<T> | StaleSuggestion<T>;
+export interface CommitSuggestionConfig<T = unknown> {
+    /**
+     * Must be registered (via data-velt-target attribute or registerTarget call)
+     * before commit, otherwise the suggestion is rejected with a dev-mode warning.
+     */
+    targetId: string;
+    /** Any JSON-serializable value. Customer's apply handler interprets it. */
+    newValue: T;
+    /** Optional human-readable string for logs and notifications. */
+    summary?: string;
+    /** Optional customer-defined metadata. Stored on Suggestion.metadata. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Pre-bound builder attached to `targetEditCommit` payloads. Calling it
+ * commits the suggestion with the SDK's default summary/metadata, optionally
+ * overridden by `result`. If the customer's `onTargetEditCommit` handler
+ * already returned a non-null result for this edit, this builder is a no-op
+ * (resolves immediately) so subscribers can't double-commit.
+ */
+export type TargetEditCommitBuilder = (result?: TargetEditCommitResult) => Promise<{
+    id: string;
+} | null>;
+export interface SuggestionGetSuggestionsFilter {
+    targetId?: string;
+    status?: SuggestionStatus | SuggestionStatus[];
+}
+export {};

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[];
@@ -19,6 +33,7 @@ export interface GetUserPermissionsResponse {
         folders?: {
             [folderId: string]: {
                 accessRole?: UserPermissionAccessRole;
+                accessType?: string;
                 expiresAt?: number;
                 error?: string;
                 errorCode?: UserPermissionAccessRoleResult;
@@ -35,6 +50,7 @@ export interface GetUserPermissionsResponse {
         documents?: {
             [documentId: string]: {
                 accessRole?: UserPermissionAccessRole;
+                accessType?: string;
                 expiresAt?: number;
                 error?: string;
                 errorCode?: UserPermissionAccessRoleResult;

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

@@ -12,6 +12,8 @@ export declare class User {
      * Default: Random avatar name.
      */
     name?: string;
+    email_lowercase?: string;
+    name_lowercase?: string;
     clientUserName?: string;
     /**
     * Your user's display picture URL.
@@ -158,6 +160,7 @@ export interface PermissionQuery {
         source: PermissionSource;
         organizationId: string;
         context?: Context | SetDocumentsContext;
+        parentFolderId?: string;
     };
 }
 export interface PermissionResult {

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

@@ -291,14 +291,14 @@ export declare class CommentElement {
   public disableStatus: () => any;
 
   /**
-   * To enable visibility option dropdown on comments
+   * To enable visibility options on comments
    */
-  public enableVisibilityOptionDropdown: () => any;
+  public enableVisibilityOptions: () => any;
 
   /**
-   * To disable visibility option dropdown on comments
+   * To disable visibility options on comments
    */
-  public disableVisibilityOptionDropdown: () => any;
+  public disableVisibilityOptions: () => any;
 
   /**
    * To enable feature to show resolve button
@@ -503,6 +503,16 @@ export declare class CommentElement {
    */
   public disableReactions: () => void;
 
+  /**
+   * To enable anonymous email mentions in comments
+   */
+  public enableAnonymousEmail: () => void;
+
+  /**
+   * To disable anonymous email mentions in comments
+   */
+  public disableAnonymousEmail: () => void;
+
   /**
    * To set allowed recordings in comments
    * @param allowedRecordings "all", "none" or "audio", "video", "screen"
@@ -1385,6 +1395,16 @@ export declare class CommentElement {
    */
   public getComposerData: (request: GetComposerDataRequest) => ComposerTextChangeEvent | null;
 
+  /**
+   * To enable pin drag
+   */
+  public enablePinDrag: () => void;
+
+  /**
+   * To disable pin drag
+   */
+  public disablePinDrag: () => void;
+
   constructor();
   /**
    * Subscribe to comments on the current document.
@@ -1626,14 +1646,14 @@ export declare class CommentElement {
   private _disableStatus;
 
   /**
-   * To enable visibility option dropdown on comments
+   * To enable visibility options on comments
    */
-  private _enableVisibilityOptionDropdown;
+  private _enableVisibilityOptions;
 
   /**
-   * To disable visibility option dropdown on comments
+   * To disable visibility options on comments
    */
-  private _disableVisibilityOptionDropdown;
+  private _disableVisibilityOptions;
 
   /**
    * To enable feature to show resolve button
@@ -1834,6 +1854,16 @@ export declare class CommentElement {
    */
   private _disableReactions;
 
+  /**
+   * To enable anonymous email mentions in comments
+   */
+  private _enableAnonymousEmail;
+
+  /**
+   * To disable anonymous email mentions in comments
+   */
+  private _disableAnonymousEmail;
+
   /**
    * To set allowed recordings in comments
    * @param allowedRecordings "all", "none" or "audio", "video", "screen"
@@ -2741,4 +2771,14 @@ export declare class CommentElement {
    * @param type 'dropdown' | 'checkbox'
    */
   private _setAssignToType;
+
+  /**
+   * To enable pin drag
+   */
+  private _enablePinDrag;
+
+  /**
+   * To disable pin drag
+   */
+  private _disablePinDrag;
 }

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

@@ -1,5 +1,5 @@
 // @ts-nocheck
-import { CrdtGetDataQuery, CrdtGetVersionQuery, CrdtOnDataChangeQuery, CrdtOnPresenceChangeQuery, CrdtOnRegisteredUserChangeQuery, CrdtOnStateChangeQuery, CrdtRegisterSyncUserQuery, CrdtSetPresenceQuery, CrdtSaveVersionQuery, CrdtUpdateDataQuery, CrdtUpdateStateQuery } from "../data/crdt.data.model";
+import { CrdtGetDataQuery, CrdtGetMessagesQuery, CrdtGetSnapshotQuery, CrdtGetVersionQuery, CrdtGetVersionsQuery, CrdtMessageData, CrdtOnDataChangeQuery, CrdtOnMessageQuery, CrdtOnPresenceChangeQuery, CrdtOnRegisteredUserChangeQuery, CrdtOnStateChangeQuery, CrdtPruneMessagesQuery, CrdtPushMessageQuery, CrdtRegisterSyncUserQuery, CrdtSaveSnapshotQuery, CrdtSetPresenceQuery, CrdtSaveVersionQuery, CrdtSnapshotData, CrdtUpdateDataQuery, CrdtUpdateStateQuery } from "../data/crdt.data.model";
 import { CrdtEventTypesMap } from "../data/crdt-events.data.model";
 
 export declare class CrdtElement {
@@ -80,6 +80,12 @@ export declare class CrdtElement {
      */
     getVersion: (getVersionQuery: CrdtGetVersionQuery) => Promise<any>;
 
+    /**
+     * Get all versions of a specific CRDT document
+     * @param id Document ID
+     */
+    getVersions: (getVersionsQuery: CrdtGetVersionsQuery) => Promise<any>;
+
     /**
      * Enable webhook
      */
@@ -96,6 +102,51 @@ export declare class CrdtElement {
      */
     setWebhookDebounceTime: (time: number) => void;
 
+    /**
+     * Push a lib0-encoded message to the unified message stream.
+     * Uses Firebase push() for chronologically-ordered keys.
+     * Carries both sync (type 0) and awareness (type 1) messages.
+     * @param pushMessageQuery - contains id, data (encoded bytes), yjsClientId (Y.Doc client ID), optional messageType and eventData
+     */
+    pushMessage: (pushMessageQuery: CrdtPushMessageQuery) => Promise<void>;
+    /**
+     * Subscribe to the unified message stream for real-time sync.
+     * Emits each new message individually as it arrives (streaming pattern).
+     * Returns an unsubscribe function.
+     * @param onMessageQuery - contains id, callback, and optional afterTs for filtering
+     */
+    onMessage: (onMessageQuery: CrdtOnMessageQuery) => () => void;
+    /**
+     * Fetch all messages after a given timestamp (one-time read).
+     * Used for message replay during initial load (y-redis pattern).
+     * @param getMessagesQuery - contains id and optional afterTs
+     */
+    getMessages: (getMessagesQuery: CrdtGetMessagesQuery) => Promise<CrdtMessageData[]>;
+    /**
+     * Get the latest full-state snapshot for a document.
+     * Used as the baseline for message replay during initial load.
+     * @param getSnapshotQuery - contains id
+     */
+    getSnapshot: (getSnapshotQuery: CrdtGetSnapshotQuery) => Promise<CrdtSnapshotData | null>;
+    /**
+     * Save a full-state snapshot (state + vector) for fast initial load.
+     * Called periodically to create checkpoints, enabling message pruning.
+     * @param saveSnapshotQuery - contains id, state (Y.Doc update), and vector (state vector)
+     */
+    saveSnapshot: (saveSnapshotQuery: CrdtSaveSnapshotQuery) => Promise<void>;
+    /**
+     * Remove messages older than the given timestamp from the message stream.
+     * Called after saving a snapshot to keep the message stream bounded.
+     * @param pruneMessagesQuery - contains id and beforeTs
+     */
+    pruneMessages: (pruneMessagesQuery: CrdtPruneMessagesQuery) => Promise<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
      * @param action Action to subscribe to
@@ -188,6 +239,36 @@ export declare class CrdtElement {
      */
     private _getVersions;
 
+    /**
+     * Push a message to the unified message stream
+     */
+    private _pushMessage;
+
+    /**
+     * Subscribe to the unified message stream
+     */
+    private _onMessage;
+
+    /**
+     * Fetch all messages after a given timestamp
+     */
+    private _getMessages;
+
+    /**
+     * Get the latest snapshot for a document
+     */
+    private _getSnapshot;
+
+    /**
+     * Save a full-state snapshot
+     */
+    private _saveSnapshot;
+
+    /**
+     * Remove messages older than a given timestamp
+     */
+    private _pruneMessages;
+
     /**
      * Enable webhook
      */
@@ -204,6 +285,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/models/element/cross-organization-config.model.d.ts

@@ -0,0 +1,17 @@
+// @ts-nocheck
+
+/**
+ * Configuration for the opt-in cross-organization "For You" notifications feature.
+ */
+export interface CrossOrganizationConfig {
+    /** Whether cross-organization notifications are active. Defaults to `true` on enable. */
+    enabled?: boolean;
+    /** Allowlist of organization IDs to include. When omitted, all indexed orgs are eligible. */
+    organizationIds?: string[];
+    /** Organization IDs to exclude. The current organization is always excluded. */
+    excludeOrganizationIds?: string[];
+    /** Upper bound on the number of organizations fetched. Defaults to 20. */
+    maxOrganizations?: number;
+    /** Feeds the merge applies to. Only `'forYou'` is supported; `'all'` is ignored with a warning. */
+    feeds?: ('forYou' | 'all')[];
+}

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

@@ -1,6 +1,7 @@
 // @ts-nocheck
 
 import { GetNotificationsDataQuery, Notification, NotificationInitialSettingsConfig, NotificationSettingsConfig, NotificationTabConfig } from "../data/notification.model";
+import { CrossOrganizationConfig } from "./cross-organization-config.model";
 
 export declare class NotificationElement {
     /**
@@ -128,6 +129,16 @@ export declare class NotificationElement {
      */
     disableCurrentDocumentOnly: () => void;
 
+    /**
+     * Opt in to cross-organization "For You" notifications.
+     */
+    enableCrossOrganization: (config?: CrossOrganizationConfig | null) => void;
+
+    /**
+     * Opt out of cross-organization "For You" notifications.
+     */
+    disableCrossOrganization: () => void;
+
     constructor();
 
     /**
@@ -254,4 +265,8 @@ export declare class NotificationElement {
      * To disable current document only
      */
     private _disableCurrentDocumentOnly;
+
+    private _enableCrossOrganization;
+
+    private _disableCrossOrganization;
 }

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

@@ -50,6 +50,21 @@ export declare class PresenceElement {
      * Subscribe to presence events
      */
     on: <T extends keyof PresenceEventTypesMap>(action: T) => Observable<PresenceEventTypesMap[T]>;
+
+    /**
+     * Add a custom user to the presence list (e.g., an AI agent).
+     * The user will appear in presence alongside real users.
+     * @param request Object containing user data with at least userId required.
+     */
+    addUser: (request: { user: Partial<PresenceUser>, localOnly?: boolean }) => void;
+
+    /**
+     * Remove a previously added custom user from the presence list.
+     * @param request Object containing user data with at least userId required, and optional localOnly flag.
+     * @param request.localOnly If true, user is only removed locally (not removed from DB). Default: false.
+     */
+    removeUser: (request: { user: Partial<PresenceUser>, localOnly?: boolean }) => void;
+
     constructor();
     /**
      * Subscribe to a list of all online users who are either active or inactive on the current document.
@@ -95,4 +110,14 @@ export declare class PresenceElement {
      * Subscribe to presence events
      */
     private _on;
+
+    /**
+     * Add a custom user to the presence list
+     */
+    private _addUser;
+
+    /**
+     * Remove a custom user from the presence list
+     */
+    private _removeUser;
 }