@veltdev/types-dev 5.0.2-beta.67 → 5.0.2-beta.68

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

@@ -8,6 +8,7 @@
  * 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.
  *
@@ -32,7 +33,16 @@ export type SuggestionMode = 'editing' | 'suggesting';
  */
 export type SuggestionTargetType = 'custom';
 /**
- * Function the customer registers via SuggestionElement.registerTarget(id, getter).
+ * 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:
@@ -151,26 +161,23 @@ export interface SuggestionData {
     driftDetected: boolean;
     /** Populated only when status === 'rejected'. */
     rejectReason: string | null;
-    /** Populated when status moves to approved | rejected | stale | apply_failed. */
-    resolvedBy: 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;
 }
-/**
- * The actor (user) involved in a suggestion event. Sourced from the existing
- * Velt identity layer.
- */
-export interface SuggestionActor {
-    userId: string;
-    name?: string;
-    email?: string;
-}
 /**
  * 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 CommentAnnotation.annotationId. */
-    id: string;
+    /** Annotation document id (same as the underlying CommentAnnotation.annotationId). */
+    annotationId: string;
     /** Stable, customer-owned target identifier. */
     targetId: string;
     /** v1: always 'custom'. */
@@ -185,8 +192,10 @@ interface SuggestionBase<T = unknown> {
     metadata: Record<string, any>;
     /** True iff the live value at approve time differed from oldValue. */
     driftDetected: boolean;
-    /** Author of the suggestion. */
-    createdBy: string;
+    /**
+     * 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. */
@@ -200,21 +209,21 @@ export interface PendingSuggestion<T = unknown> extends SuggestionBase<T> {
 export interface ApprovedSuggestion<T = unknown> extends SuggestionBase<T> {
     status: 'approved' | 'apply_failed';
     rejectReason: null;
-    resolvedBy: string;
+    resolvedBy: User;
     resolvedAt: number;
 }
 /** A suggestion that has been rejected. rejectReason is non-null. */
 export interface RejectedSuggestion<T = unknown> extends SuggestionBase<T> {
     status: 'rejected';
     rejectReason: string;
-    resolvedBy: string;
+    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: string | null;
+    resolvedBy: User | null;
     resolvedAt: number | null;
 }
 /**

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

@@ -0,0 +1,180 @@
+// @ts-nocheck
+import { Observable } from "rxjs";
+import { SuggestionEventType } from "../../utils/enums";
+import { SuggestionEventTypesMap } from "../data/suggestion-events.data.model";
+import { CommitSuggestionConfig, EnableSuggestionModeConfig, RegisterTargetConfig, Suggestion, SuggestionGetSuggestionsFilter } from "../data/suggestion.data.model";
+
+export declare class SuggestionElement {
+
+  /**
+   * Turn on suggestion mode for this user/session and (optionally) register
+   * the onTargetEditStart / onTargetEditCommit callbacks the SDK invokes
+   * during the auto-detect edit lifecycle.
+   *
+   * Re-calling with a new config replaces the previous callbacks.
+   */
+  enableSuggestionMode: (config?: EnableSuggestionModeConfig) => void;
+
+  /**
+   * Turn off suggestion mode and clear any registered callbacks.
+   */
+  disableSuggestionMode: () => void;
+
+  /**
+   * Synchronous read of the current enable flag.
+   */
+  isSuggestionModeEnabled: () => boolean;
+
+  /**
+   * Reactive enable-flag stream; deduplicated.
+   */
+  isSuggestionModeEnabled$: () => Observable<boolean>;
+
+  /**
+   * Register a getter that returns the current value of a tagged target.
+   * Required for non-primitive (wrapper) targets — the SDK calls this on
+   * focus to snapshot the pre-edit value, and again on commit for the diff.
+   *
+   * The getter must reflect edit-time state (typically read from the DOM),
+   * not the persisted customer state. See `RegisterTargetConfig`.
+   */
+  registerTarget: <T = unknown>(config: RegisterTargetConfig<T>) => void;
+
+  /**
+   * Drop the registered getter for a target.
+   */
+  unregisterTarget: (targetId: string) => void;
+
+  /**
+   * Manually capture the current value as the snapshot for a target.
+   * Use for non-focusable elements (custom widgets, virtualized rows)
+   * where the auto-focus snapshot does not fire.
+   */
+  startSuggestion: (targetId: string) => void;
+
+  /**
+   * Programmatically commit a suggestion. Resolves with the new annotation id.
+   * Rejects with one of: INVALID_CONFIG, MODE_NOT_SUGGESTING,
+   * TARGET_NOT_REGISTERED, NO_GETTER_FOR_COMPLEX, NO_CHANGE_TO_SUGGEST,
+   * SNAPSHOT_FAILED.
+   */
+  commitSuggestion: <T = unknown>(config: CommitSuggestionConfig<T>) => Promise<{ id: string }>;
+
+  /**
+   * Synchronous read of all suggestions on the current document, optionally filtered.
+   */
+  getSuggestions: (filter?: SuggestionGetSuggestionsFilter) => Suggestion[];
+
+  /**
+   * Reactive variant of getSuggestions. Re-emits on every annotation change,
+   * deduplicated via the SDK's standard distinct-until-changed comparator.
+   */
+  getSuggestions$: (filter?: SuggestionGetSuggestionsFilter) => Observable<Suggestion[]>;
+
+  /**
+   * Newest pending suggestion for a target, or null. Convenience for
+   * pending-overlay UX patterns where each input shows the proposed
+   * value while a suggestion is awaiting resolution.
+   */
+  getPendingSuggestion: <T = unknown>(targetId: string) => Suggestion<T> | null;
+
+  /**
+   * Reactive variant of getPendingSuggestion.
+   */
+  getPendingSuggestion$: <T = unknown>(targetId: string) => Observable<Suggestion<T> | null>;
+
+  /**
+   * Subscribe to a suggestion event. Customers call `.subscribe(handler)`
+   * on the returned Observable. Event names: 'suggestionCreated',
+   * 'suggestionApproved', 'suggestionRejected', 'suggestionStale',
+   * 'targetEditStart', 'targetEditCommit'.
+   */
+  on: <T extends SuggestionEventType>(action: T) => Observable<SuggestionEventTypesMap[T]>;
+
+  constructor();
+
+  /**
+   * Turn on suggestion mode for this user/session and (optionally) register
+   * the onTargetEditStart / onTargetEditCommit callbacks the SDK invokes
+   * during the auto-detect edit lifecycle.
+   *
+   * Re-calling with a new config replaces the previous callbacks.
+   */
+  private _enableSuggestionMode;
+
+  /**
+   * Turn off suggestion mode and clear any registered callbacks.
+   */
+  private _disableSuggestionMode;
+
+  /**
+   * Synchronous read of the current enable flag.
+   */
+  private _isSuggestionModeEnabled;
+
+  /**
+   * Reactive enable-flag stream; deduplicated.
+   */
+  private _isSuggestionModeEnabled$;
+
+  /**
+   * Register a getter that returns the current value of a tagged target.
+   * Required for non-primitive (wrapper) targets — the SDK calls this on
+   * focus to snapshot the pre-edit value, and again on commit for the diff.
+   *
+   * The getter must reflect edit-time state (typically read from the DOM),
+   * not the persisted customer state. See `RegisterTargetConfig`.
+   */
+  private _registerTarget;
+
+  /**
+   * Drop the registered getter for a target.
+   */
+  private _unregisterTarget;
+
+  /**
+   * Manually capture the current value as the snapshot for a target.
+   * Use for non-focusable elements (custom widgets, virtualized rows)
+   * where the auto-focus snapshot does not fire.
+   */
+  private _startSuggestion;
+
+  /**
+   * Programmatically commit a suggestion. Resolves with the new annotation id.
+   * Rejects with one of: INVALID_CONFIG, MODE_NOT_SUGGESTING,
+   * TARGET_NOT_REGISTERED, NO_GETTER_FOR_COMPLEX, NO_CHANGE_TO_SUGGEST,
+   * SNAPSHOT_FAILED.
+   */
+  private _commitSuggestion;
+
+  /**
+   * Synchronous read of all suggestions on the current document, optionally filtered.
+   */
+  private _getSuggestions;
+
+  /**
+   * Reactive variant of getSuggestions. Re-emits on every annotation change,
+   * deduplicated via the SDK's standard distinct-until-changed comparator.
+   */
+  private _getSuggestions$;
+
+  /**
+   * Newest pending suggestion for a target, or null. Convenience for
+   * pending-overlay UX patterns where each input shows the proposed
+   * value while a suggestion is awaiting resolution.
+   */
+  private _getPendingSuggestion;
+
+  /**
+   * Reactive variant of getPendingSuggestion.
+   */
+  private _getPendingSuggestion$;
+
+  /**
+   * Subscribe to a suggestion event. Customers call `.subscribe(handler)`
+   * on the returned Observable. Event names: 'suggestionCreated',
+   * 'suggestionApproved', 'suggestionRejected', 'suggestionStale',
+   * 'targetEditStart', 'targetEditCommit'.
+   */
+  private _on;
+}

package/models.d.ts

@@ -50,6 +50,8 @@ export * from './app/models/data/recorder-annotation.data.model';
 export * from './app/models/data/recorder-events.data.model';
 export * from './app/models/data/rewriter-annotation.data.model';
 export * from './app/models/data/rewriter-events.data.model';
+export * from './app/models/data/suggestion.data.model';
+export * from './app/models/data/suggestion-events.data.model';
 export * from './app/models/data/screen-size.data.model';
 export * from './app/models/data/screenshot.data.model';
 export * from './app/models/data/selection.model';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@veltdev/types-dev",
-    "version": "5.0.2-beta.67",
+    "version": "5.0.2-beta.68",
     "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

@@ -18,4 +18,5 @@ 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 './app/models/element/suggestion-element.model';
 export * from './models';