@veltdev/sdk-staging 5.0.2-beta.7 → 5.0.2-beta.70

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

@@ -16,6 +16,8 @@ export interface SetDocumentsRequestOptions {
     locationId?: string;
     rootDocumentId?: string;
     context?: SetDocumentsContext;
+    debounceTime?: number;
+    optimisticPermissions?: boolean;
 }
 export interface UpdateDocumentsRequest<T = unknown> {
     organizationId?: string;

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/notification-resolver.data.model.d.ts

@@ -0,0 +1,39 @@
+import { ResolverEndpointConfig, ResolverResponse, RetryConfig } from "./resolver.data.model";
+import { User } from "./user.data.model";
+export interface NotificationDataProvider {
+    get?: (request: GetNotificationResolverRequest) => Promise<ResolverResponse<Record<string, PartialNotification>>>;
+    delete?: (request: DeleteNotificationResolverRequest) => Promise<ResolverResponse<undefined>>;
+    config?: NotificationResolverConfig;
+}
+export interface NotificationResolverConfig {
+    resolveTimeout?: number;
+    getRetryConfig?: RetryConfig;
+    deleteRetryConfig?: RetryConfig;
+    getConfig?: ResolverEndpointConfig;
+    deleteConfig?: ResolverEndpointConfig;
+}
+export interface GetNotificationResolverRequest {
+    organizationId: string;
+    notificationIds: string[];
+}
+export interface DeleteNotificationResolverRequest {
+    notificationId: string;
+    organizationId: string;
+}
+export interface PartialNotification {
+    notificationId: string;
+    displayHeadlineMessageTemplate?: string;
+    displayHeadlineMessageTemplateData?: {
+        actionUser?: User;
+        recipientUser?: User;
+        actionMessage?: string;
+        [key: string]: any;
+    };
+    displayBodyMessage?: string;
+    displayBodyMessageTemplate?: string;
+    displayBodyMessageTemplateData?: {
+        [key: string]: any;
+    };
+    notificationSourceData?: any;
+    [key: string]: any;
+}

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

@@ -137,6 +137,10 @@ export declare class Notification {
      * Is comment text available
      */
     isCommentResolverUsed?: boolean;
+    /**
+     * Is notification resolver used
+     */
+    isNotificationResolverUsed?: boolean;
     /**
      * Display body message template
        */

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

@@ -83,4 +83,9 @@ export declare class PresenceUser {
     initial?: string;
     isTabAway?: boolean;
     isUserIdle?: boolean;
+    /**
+     * Whether this custom user is local-only (not persisted to DB).
+     * Only applicable to users added via addUser API.
+     */
+    localOnly?: boolean;
 }

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

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

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

@@ -4,9 +4,9 @@ import { PartialUser } from "./comment-resolver.data.model";
 import { ReactionAnnotation } from "./reaction-annotation.data.model";
 import { ResolverConfig, ResolverResponse } from "./resolver.data.model";
 export interface ReactionAnnotationDataProvider {
-    get: (request: GetReactionResolverRequest) => Promise<ResolverResponse<Record<string, PartialReactionAnnotation>>>;
-    save: (request: SaveReactionResolverRequest) => Promise<ResolverResponse<undefined>>;
-    delete: (request: DeleteReactionResolverRequest) => Promise<ResolverResponse<undefined>>;
+    get?: (request: GetReactionResolverRequest) => Promise<ResolverResponse<Record<string, PartialReactionAnnotation>>>;
+    save?: (request: SaveReactionResolverRequest) => Promise<ResolverResponse<undefined>>;
+    delete?: (request: DeleteReactionResolverRequest) => Promise<ResolverResponse<undefined>>;
     config?: ResolverConfig;
 }
 export interface GetReactionResolverRequest {

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

@@ -150,6 +150,17 @@ export declare class RecorderAnnotation {
     chunkUrls?: {
         [key: number]: string;
     };
+    /**
+     * Whether the recorder resolver is used for this annotation.
+     * Used by UI components to show loading states while resolver data is being fetched.
+     */
+    isRecorderResolverUsed?: boolean;
+    /**
+     * Whether the real recording URL is available.
+     * Set to false when the annotation is first saved (URL is still a local blob),
+     * and true once the actual URL from storage is available after the async upload completes.
+     */
+    isUrlAvailable?: boolean;
 }
 export interface RecorderAnnotationEditVersion {
     from?: User;

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

@@ -4,6 +4,8 @@ export interface TranscriptionDoneEvent extends RecorderData {
 }
 export interface RecordingDoneEvent extends RecorderData {
 }
+export interface RecordingDoneLocalEvent extends RecorderData {
+}
 export interface RecordingDeleteEvent extends RecorderData {
 }
 export interface RecordingEditDoneEvent extends RecorderData {
@@ -35,6 +37,7 @@ export interface RecordingSaveInitiatedEvent {
 export type RecorderEventTypesMap = {
     [RecorderEventTypes.TRANSCRIPTION_DONE]: TranscriptionDoneEvent;
     [RecorderEventTypes.RECORDING_DONE]: RecordingDoneEvent;
+    [RecorderEventTypes.RECORDING_DONE_LOCAL]: RecordingDoneLocalEvent;
     [RecorderEventTypes.RECORDING_EDIT_DONE]: RecordingEditDoneEvent;
     [RecorderEventTypes.DELETE_RECORDING]: RecordingDeleteEvent;
     [RecorderEventTypes.RECORDING_STARTED]: RecordingStartedEvent;

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

@@ -0,0 +1,58 @@
+import { ResolverActions } from "../../utils/enums";
+import { AttachmentDataProvider } from "./attachment-resolver.data.model";
+import { BaseMetadata } from "./base-metadata.data.model";
+import { RecorderAnnotation } from "./recorder-annotation.data.model";
+import { ResolverConfig, ResolverResponse } from "./resolver.data.model";
+import { Attachment } from "./attachment.model";
+import { Transcription } from "./transcription.data.model";
+import { User } from "./user.data.model";
+export interface RecorderAnnotationDataProvider {
+    get?: (request: GetRecorderResolverRequest) => Promise<ResolverResponse<Record<string, PartialRecorderAnnotation>>>;
+    save?: (request: SaveRecorderResolverRequest) => Promise<ResolverResponse<SaveRecorderResolverData | undefined>>;
+    delete?: (request: DeleteRecorderResolverRequest) => Promise<ResolverResponse<undefined>>;
+    config?: ResolverConfig;
+    uploadChunks?: boolean;
+    storage?: AttachmentDataProvider;
+}
+export interface GetRecorderResolverRequest {
+    organizationId: string;
+    recorderAnnotationIds?: string[];
+    documentIds?: string[];
+}
+export interface SaveRecorderResolverRequest {
+    recorderAnnotation: Record<string, PartialRecorderAnnotation>;
+    event?: ResolverActions;
+    metadata?: BaseMetadata;
+}
+export interface SaveRecorderResolverData {
+    transcription?: Transcription;
+    attachment?: Attachment | null;
+    attachments?: Attachment[];
+}
+export interface DeleteRecorderResolverRequest {
+    recorderAnnotationId: string;
+    metadata?: BaseMetadata;
+    event?: ResolverActions;
+}
+export interface PartialRecorderAnnotation {
+    annotationId: string;
+    metadata?: BaseMetadata;
+    from?: User;
+    transcription?: Transcription;
+    attachment?: Attachment | null;
+    attachments?: Attachment[];
+    chunkUrls?: Record<number, string>;
+    recordingEditVersions?: Record<number, PartialRecorderAnnotationEditVersion>;
+    [key: string]: any;
+}
+export interface PartialRecorderAnnotationEditVersion {
+    from?: User;
+    attachment?: Attachment | null;
+    attachments?: Attachment[];
+    transcription?: Transcription;
+}
+export interface PartialRecorderAnnotationResult {
+    strippedData: Record<string, PartialRecorderAnnotation> | null;
+    originalData: RecorderAnnotation | null;
+    eventType?: ResolverActions;
+}

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

@@ -9,6 +9,7 @@ export interface ResolverConfig {
     getRetryConfig?: RetryConfig;
     resolveUsersConfig?: ResolveUsersConfig;
     fieldsToRemove?: string[];
+    additionalFields?: string[];
     getConfig?: ResolverEndpointConfig;
     saveConfig?: ResolverEndpointConfig;
     deleteConfig?: ResolverEndpointConfig;

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

@@ -0,0 +1,44 @@
+import { TargetTextRange } from './target-text-range.data.model';
+import { RewriterEventTypes } from '../../utils/enums';
+export 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';
+export 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';
+export 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';
+export type AiModel = OpenAiModel | AnthropicModel | GeminiModel | (string & NonNullable<unknown>);
+export interface TextSelectedEvent {
+    selectionId: string;
+    text: string;
+    targetTextRange: TargetTextRange;
+}
+export interface RewriterAskAiRequest {
+    model: AiModel;
+    prompt: string;
+    selectedText: string;
+}
+export interface RewriterReplaceTextRequest {
+    text: string;
+    event: TextSelectedEvent;
+}
+export interface RewriterAddCommentRequest {
+    text: string;
+    event: TextSelectedEvent;
+}
+export interface RewriterAskAiResponse {
+    text: string;
+    success: boolean;
+    error?: string;
+}
+export interface RewriterReplaceTextResponse {
+    success: boolean;
+    originalText: string;
+    replacedText: string;
+    error?: string;
+}
+export interface RewriterAddCommentResponse {
+    success: boolean;
+    annotationId?: string;
+    commentText?: string;
+    error?: string;
+}
+export type RewriterEventTypesMap = {
+    [RewriterEventTypes.TEXT_SELECTED]: TextSelectedEvent;
+};

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

@@ -0,0 +1,57 @@
+import { SuggestionEventTypes } from '../../utils/enums';
+import { ApprovedSuggestion, PendingSuggestion, RejectedSuggestion, StaleSuggestion, TargetEditCommitBuilder, TargetEditDetails } from './suggestion.data.model';
+/**
+ * Public payload types for the v1 Suggestions feature. Mirrors the layout of
+ * `comment-events.data.model.ts` and `recorder-events.data.model.ts`:
+ *
+ *   - One named interface per event payload.
+ *   - One `SuggestionEventTypesMap` keyed by `SuggestionEventTypes` enum values.
+ *
+ * Customers pass an event-name string (or the enum constant — they're
+ * equivalent) to `velt.getSuggestionElement().on(...)` and receive an
+ * `Observable<SuggestionEventTypesMap[T]>`.
+ *
+ * No separate `actor`/`user` field on the payloads: the user info is on
+ * `suggestion.createdBy` (for created) and `suggestion.resolvedBy` (for
+ * approved/rejected/stale). Matches the comment-event shape.
+ */
+export interface SuggestionCreatedEvent {
+    suggestion: PendingSuggestion;
+    timestamp: number;
+}
+export interface SuggestionApprovedEvent {
+    suggestion: ApprovedSuggestion;
+    timestamp: number;
+}
+export interface SuggestionRejectedEvent {
+    suggestion: RejectedSuggestion;
+    timestamp: number;
+}
+export interface SuggestionStaleEvent {
+    suggestion: StaleSuggestion;
+    timestamp: number;
+}
+export interface TargetEditStartEvent {
+    details: TargetEditDetails;
+    timestamp: number;
+}
+export interface TargetEditCommitEvent {
+    details: TargetEditDetails;
+    /**
+     * Pre-bound builder. Calling it commits the suggestion using 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 so subscribers can't
+     * double-commit.
+     */
+    commitSuggestion: TargetEditCommitBuilder;
+    timestamp: number;
+}
+export type SuggestionEventTypesMap = {
+    [SuggestionEventTypes.SUGGESTION_CREATED]: SuggestionCreatedEvent;
+    [SuggestionEventTypes.SUGGESTION_APPROVED]: SuggestionApprovedEvent;
+    [SuggestionEventTypes.SUGGESTION_REJECTED]: SuggestionRejectedEvent;
+    [SuggestionEventTypes.SUGGESTION_STALE]: SuggestionStaleEvent;
+    [SuggestionEventTypes.TARGET_EDIT_START]: TargetEditStartEvent;
+    [SuggestionEventTypes.TARGET_EDIT_COMMIT]: TargetEditCommitEvent;
+};

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' | 'approved' | '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: 'approved' | '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 {