@veltdev/sdk 5.0.2-beta.31 → 5.0.2-beta.32

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

@@ -23,6 +23,8 @@ export declare const CommentActivityActionTypes: {
     readonly APPROVE: "comment_annotation.approve";
     readonly ACCEPT: "comment.accept";
     readonly REJECT: "comment.reject";
+    readonly SUGGESTION_ACCEPT: "comment_annotation.suggestion_accept";
+    readonly SUGGESTION_REJECT: "comment_annotation.suggestion_reject";
     readonly REACTION_ADD: "comment.reaction_add";
     readonly REACTION_DELETE: "comment.reaction_delete";
     readonly SUBSCRIBE: "comment_annotation.subscribe";

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

@@ -0,0 +1,57 @@
+/**
+ * Public configuration surface for AI agent suggestion comment actions.
+ *
+ * Hosts can override or augment the built-in accept (convert suggestion ->
+ * comment) and reject (delete) actions rendered on an agent suggestion card.
+ * When no config is provided, the built-in defaults are used (INV-004).
+ *
+ * Part of the SDK public API (exported via velt-types). Backward-compatible /
+ * additive — see specs/agent-suggestion-comment-ui/spec.md `## Outbound contract changes`.
+ */
+import { CommentAnnotation } from './comment-annotation.data.model';
+/**
+ * A single host-defined action button on an agent suggestion card.
+ */
+export interface AgentSuggestionAction {
+    /** Stable identifier for the action. */
+    id: string;
+    /** Display label (button text / aria-label). */
+    label?: string;
+    /** Optional icon identifier or URL. */
+    icon?: string;
+    /**
+     * Invoked when the action button is clicked. Receives the raw
+     * CommentAnnotation (review decision 2026-06-03 — accepted public-contract
+     * surface). Handler throws are caught by the SDK (EC-006).
+     */
+    onClick: (annotation: CommentAnnotation) => void | Promise<void>;
+}
+/**
+ * Host configuration for agent suggestion card actions.
+ * When `actions` is provided it replaces the default accept/reject pair.
+ */
+export interface AgentSuggestionActionsConfig {
+    actions?: AgentSuggestionAction[];
+}
+/**
+ * Discriminator for the bespoke agent-suggestion overflow-menu rows.
+ * Drives the icon, label and click action of the generic menu-item primitive.
+ */
+export type AgentSuggestionMenuItemType = 'copy-link' | 'delete';
+/**
+ * Canonical agent-suggestion overflow-menu item types.
+ * Avoids repeating the discriminator string literals across primitives.
+ */
+export declare const AGENT_SUGGESTION_MENU_ITEM_TYPE: {
+    readonly COPY_LINK: "copy-link";
+    readonly DELETE: "delete";
+};
+/**
+ * Translation keys / labels used by the agent-suggestion overflow menu.
+ * Centralised so the menu-item, label and trigger primitives stay in sync.
+ */
+export declare const AGENT_SUGGESTION_MENU_LABEL: {
+    readonly COPY_LINK: "Copy link";
+    readonly LINK_COPIED: "Link copied!";
+    readonly DELETE_THREAD: "Delete thread";
+};

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

@@ -85,6 +85,16 @@ export interface RejectCommentAnnotationRequest {
     annotationId: string;
     options?: RequestOptions;
 }
+export interface AcceptSuggestionRequest {
+    annotationId: string;
+    options?: RequestOptions;
+}
+export interface RejectSuggestionRequest {
+    annotationId: string;
+    /** Optional human-readable reason persisted on the suggestion. */
+    reason?: string;
+    options?: RequestOptions;
+}
 export interface DeleteCommentAnnotationRequest {
     annotationId: string;
     options?: RequestOptions;

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

@@ -17,6 +17,34 @@ export interface CommentAnnotationVisibilityConfig {
     organizationId?: string;
     userIds?: string[];
 }
+/**
+ * Structured result produced by an AI agent for a comment annotation.
+ * Read-only from the SDK's perspective — written upstream by the agent.
+ */
+export interface AgentResult {
+    /** Short, bold headline rendered at the top of the agent suggestion card. */
+    title?: string;
+}
+/**
+ * Identity + output of the AI agent that authored a comment annotation.
+ * Present on annotations created by an agent. The agent-suggestion UI renders
+ * iff `agent` is present AND `type === 'suggestion'` (and the viewer is admin).
+ *
+ * `agentFields` mirrors the Firestore query field used by
+ * `CommentRequestQuery.agentFields` (see comment-actions.data.model.ts).
+ */
+export interface AgentData {
+    /** Canonical display name of the agent (card header). */
+    agentName?: string;
+    /** Legacy display name of the agent (card header); superseded by `agentName`. */
+    name?: string;
+    /** Avatar URL for the agent (card header); falls back to a default icon. */
+    avatar?: string;
+    /** Structured agent output (title, …). */
+    result?: AgentResult;
+    /** Queryable agent attributes. */
+    agentFields?: string[];
+}
 export declare class CommentAnnotation {
     /**
      * Unique identifier for the comment pin annotation.
@@ -151,6 +179,12 @@ export declare class CommentAnnotation {
     location?: Location | null;
     type?: string;
     commentType?: string;
+    /**
+     * Origin of the annotation. `'agent'` indicates the annotation was authored by
+     * an AI agent (drives the blue pin marker, agent identity header and blue text
+     * highlight). Absent / any other value indicates a regular user comment.
+     */
+    sourceType?: string;
     metadata?: CommentMetadata;
     /**
      * Selected text range of comment annotation
@@ -162,6 +196,10 @@ export declare class CommentAnnotation {
     selectAllContent?: boolean;
     approved?: boolean;
     status: CustomStatus;
+    /**
+     * User id of the user who updated the status of the comment annotation
+     */
+    statusUpdatedByUserId?: string | null;
     /**
      * To maintain index of current annotation in available list of annotations
      * It will start from 1, so no need to add 1 in that.
@@ -207,6 +245,12 @@ export declare class CommentAnnotation {
      * See docs/suggestions-api-contract.md for the full storage model.
      */
     suggestion?: SuggestionData;
+    /**
+     * AI agent identity + output. Present on agent-authored annotations.
+     * Read-only from the SDK; written upstream by the agent.
+     * See specs/agent-suggestion-comment-ui/spec.md (INV-001).
+     */
+    agent?: AgentData;
 }
 export declare class GhostComment {
     targetElement?: TargetElement | null;

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

@@ -93,6 +93,8 @@ export type CommentEventTypesMap = {
     [CommentEventTypes.COMMENT_SAVED]: CommentSavedEvent;
     [CommentEventTypes.COMMENT_SAVE_TRIGGERED]: CommentSaveTriggeredEvent;
     [CommentEventTypes.VISIBILITY_OPTION_CLICKED]: VisibilityOptionClickedEvent;
+    [CommentEventTypes.SUGGESTION_ACCEPTED]: SuggestionAcceptEvent;
+    [CommentEventTypes.SUGGESTION_REJECTED]: SuggestionRejectEvent;
 };
 export interface AddAttachmentEvent {
     annotationId: string;
@@ -146,6 +148,20 @@ export interface DeleteCommentAnnotationEvent {
     commentAnnotation: CommentAnnotation;
     metadata: VeltEventMetadata;
 }
+export interface SuggestionAcceptEvent {
+    annotationId: string;
+    commentAnnotation: CommentAnnotation;
+    metadata: VeltEventMetadata;
+    actionUser: User;
+}
+export interface SuggestionRejectEvent {
+    annotationId: string;
+    commentAnnotation: CommentAnnotation;
+    metadata: VeltEventMetadata;
+    actionUser: User;
+    /** Optional human-readable reason supplied at reject time. */
+    rejectReason?: string | null;
+}
 export interface GetCommentAnnotationsResponse {
     data: Record<string, CommentAnnotation[]> | null;
 }

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

@@ -19,7 +19,7 @@ import { User } from './user.data.model';
  * - 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';
+export type SuggestionStatus = 'pending' | 'accepted' | 'rejected' | 'stale' | 'apply_failed';
 /**
  * Global per-user-per-session suggestion mode. Not persisted; reload returns to 'editing'.
  */
@@ -207,7 +207,7 @@ export interface PendingSuggestion<T = unknown> extends SuggestionBase<T> {
 }
 /** A suggestion that has been approved (apply handler success or pending invocation). */
 export interface ApprovedSuggestion<T = unknown> extends SuggestionBase<T> {
-    status: 'approved' | 'apply_failed';
+    status: 'accepted' | 'apply_failed';
     rejectReason: null;
     resolvedBy: User;
     resolvedAt: number;

package/app/utils/enums.d.ts

@@ -14,7 +14,9 @@ export declare enum CommentStatus {
     REACTION_ADDED = "reactionAdded",
     REACTION_DELETED = "reactionDeleted",
     SUBSCRIBED = "subscribed",
-    UNSUBSCRIBED = "unsubscribed"
+    UNSUBSCRIBED = "unsubscribed",
+    SUGGESTION_ACCEPTED = "suggestionAccepted",
+    SUGGESTION_REJECTED = "suggestionRejected"
 }
 export declare enum ResolverActions {
     COMMENT_ANNOTATION_ADD = "comment_annotation.add",
@@ -72,6 +74,8 @@ export declare const CommentEventTypes: {
     readonly COMMENT_SAVED: "commentSaved";
     readonly COMMENT_SAVE_TRIGGERED: "commentSaveTriggered";
     readonly VISIBILITY_OPTION_CLICKED: "visibilityOptionClicked";
+    readonly SUGGESTION_ACCEPTED: "suggestionAccepted";
+    readonly SUGGESTION_REJECTED: "suggestionRejected";
 };
 export declare const RecorderEventTypes: {
     readonly TRANSCRIPTION_DONE: "transcriptionDone";

package/models.d.ts

@@ -4,6 +4,7 @@ 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/agent-suggestion.data.model';
 export * from './app/models/data/base-metadata.data.model';
 export * from './app/models/data/button.data.model';
 export * from './app/models/data/chatgpt.data.model';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@veltdev/sdk",
-    "version": "5.0.2-beta.31",
+    "version": "5.0.2-beta.32",
     "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": [