@veltdev/types 6.0.8-beta.1 → 6.0.8-beta.2

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

@@ -0,0 +1,55 @@
+/**
+ * Public data model for customer-defined action buttons on a comment.
+ *
+ * Customers attach a list of actions to a comment (or to the annotation, which
+ * acts as the per-agent-row default). Velt renders them as chips and emits
+ * `commentActionClicked` when one is clicked. **Velt never interprets an
+ * action** — clicking one performs no SDK write of any kind (spec AC-003).
+ *
+ * Part of the SDK public API (exported via `src/models.ts` → velt-types).
+ * Additive — see `specs/agent-comment-actions-and-progress/spec.md`
+ * `## Outbound contract changes`.
+ */
+/**
+ * A single customer-defined action rendered as a chip on a comment.
+ *
+ * Identity is `id` and only `id` (spec AC-002). There is deliberately no
+ * `type` field — two opaque customer strings on one object is confusing, and
+ * `id` matches the already-shipped `AgentSuggestionAction`. There is also no
+ * `actor` (clicks are fire-and-forget, so the SDK has nothing to record), no
+ * `selected` / `singleSelect`, and no visual `variant`.
+ */
+export interface CommentAction {
+    /**
+     * Stable, opaque, customer-owned identifier. REQUIRED — the only identity.
+     *
+     * The same `id` legitimately appears on many comments in one thread, which is
+     * why duplicate-click suppression is keyed on
+     * `(annotationId, commentId, actionId)` and never on `id` alone.
+     */
+    id: string;
+    /** Display label (chip text). Also the accessible name when an icon is set. */
+    label?: string;
+    /**
+     * Raw SVG string (a trimmed value starting with `<`) rendered through the
+     * `safeSvg` pipe, OR a URL / data-URI rendered as an `<img>`. Anything else
+     * is ignored — label only, no throw and no broken glyph.
+     *
+     * There is no named-icon registry and none is planned.
+     */
+    icon?: string;
+    /** Renders the chip non-interactive. A disabled chip emits nothing. */
+    disabled?: boolean;
+    /**
+     * Omits the chip entirely. An `actions` array in which every entry is hidden
+     * is a present-but-empty list: it renders NO row and does NOT fall back to
+     * the built-in accept/reject (spec INV-008 — that fallback would re-expose a
+     * state-changing control the customer deliberately suppressed).
+     */
+    hidden?: boolean;
+    /**
+     * Customer-owned bag, persisted as-is and echoed back verbatim on the click
+     * event. Velt never reads it.
+     */
+    metadata?: any;
+}

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

@@ -1,6 +1,7 @@
 import { CommentAccessMode, CommentVisibilityOptionType } from "../../utils/enums";
 import { BaseMetadata } from "./base-metadata.data.model";
 import { CommentVisibilityType } from "./comment-actions.data.model";
+import type { CommentAction } from "./comment-action.data.model";
 import { Comment } from "./comment.data.model";
 import { CursorPosition } from "./cursor-position.data.model";
 import { CustomAnnotationDropdownItem } from "./custom-chip-dropdown.data.model";
@@ -66,6 +67,16 @@ export declare class CommentAnnotation {
      */
     annotationNumber?: number;
     visibilityConfig?: CommentAnnotationVisibilityConfig;
+    /**
+     * Customer-defined action buttons for this annotation.
+     *
+     * These are the PER-ROW DEFAULT, not a thread-level row: every comment row
+     * without its own `comment.actions` renders these, regardless of who authored
+     * it. A progress row deliberately does NOT inherit them (spec AC-043) — only
+     * explicitly-set comment-level actions render there, because a row whose
+     * content has not been written yet has nothing for a "Copy"/"Retry" to act on.
+     */
+    actions?: CommentAction[];
     /**
      * This is the list of all comments part of this annotation.
      *

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

@@ -2,6 +2,7 @@ import { AssignToType, CommentAccessMode, CommentEventTypes, CommentStatus, Comm
 import { Attachment } from "./attachment.model";
 import { VeltButtonClickEvent } from "./button.data.model";
 import { AddAttachmentResponse } from "./comment-actions.data.model";
+import { CommentAction } from "./comment-action.data.model";
 import { CommentAnnotation, UpdateContextConfig } from "./comment-annotation.data.model";
 import { Comment } from "./comment.data.model";
 import { CustomPriority, CustomStatus } from "./custom-filter.data.model";
@@ -100,7 +101,58 @@ export type CommentEventTypesMap = {
     [CommentEventTypes.VISIBILITY_OPTION_CLICKED]: VisibilityOptionClickedEvent;
     [CommentEventTypes.SUGGESTION_ACCEPTED]: SuggestionAcceptEvent;
     [CommentEventTypes.SUGGESTION_REJECTED]: SuggestionRejectEvent;
+    [CommentEventTypes.COMMENT_ACTION_CLICKED]: CommentActionClickedEvent;
 };
+/**
+ * Emitted when a customer-defined action chip is clicked.
+ *
+ * Consumed as `Velt.getCommentElement().on('commentActionClicked')` — the same
+ * surface as `suggestionAccepted`.
+ *
+ * The SDK writes NOTHING in response. If the customer wants a one-time action,
+ * or wants to record who clicked, they rewrite the action list themselves via
+ * `updateComment`.
+ */
+export interface CommentActionClickedEvent {
+    /** The full action object, including the customer's `metadata`. */
+    action: CommentAction;
+    actionId: string;
+    /**
+     * Where the action was DEFINED. Independent of `commentId`.
+     *
+     * `scope` and `commentId` answer different questions: `scope` says where the
+     * action came from, `commentId` says which row it was clicked on. An
+     * annotation-scoped action clicked on the second of three replies emits
+     * `scope: 'annotation'` WITH that reply's `commentId` — without which an
+     * annotation-level action on a multi-reply thread would be unactionable.
+     */
+    scope: 'comment' | 'annotation';
+    annotationId: string;
+    /**
+     * Which ROW was clicked. Present for any thread-row click regardless of
+     * `scope`; absent ONLY on the standalone suggestion card, which has no rows.
+     */
+    commentId?: number;
+    commentAnnotation: CommentAnnotation;
+    /** Same presence rule as `commentId`. */
+    comment?: Comment;
+    /**
+     * The user who clicked.
+     *
+     * Named `actionUser`, not `user`, for two reasons. Convention: all six
+     * events meaning "a user performed an action" use it (approve / accept /
+     * reject / delete comment-annotation, suggestion accept / reject). And
+     * semantics: on an AGENT comment a bare `user` is genuinely ambiguous —
+     * the comment's author is an agent, the clicker is a human. `actionUser`
+     * disambiguates what `user` would leave open.
+     */
+    actionUser: User;
+    /**
+     * Velt event metadata. Distinct from `action.metadata`, which is the
+     * customer's opaque bag — they never occupy the same level.
+     */
+    metadata: VeltEventMetadata;
+}
 export interface AddAttachmentEvent {
     annotationId: string;
     commentAnnotation: CommentAnnotation;

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

@@ -0,0 +1,127 @@
+/**
+ * Public data model for the comment progress indicator.
+ *
+ * A customer creates a comment in a progress state via `addComment`, pushes
+ * updates via repeated `updateComment` calls, and finally writes the real
+ * content with `state: 'completed'` on the SAME comment.
+ *
+ * DELIBERATELY NOT AGENT-SPECIFIC, and this is the whole point of the shape.
+ * An earlier revision nested this under the agent block as `AgentData.progress`.
+ * That forced a caller to supply a valid agent identity — `agentSource`,
+ * `agentId`, `agentName`, and backend-side a full `reason` with
+ * title/description/severity — merely to render three animated dots. Progress
+ * is a property of the COMMENT, not of who authored it: translation pipelines,
+ * moderation checks and multi-step workflows all want it without pretending to
+ * be an agent. It therefore sits on `Comment.progress`, beside
+ * `Comment.actions`, and nothing about progress touches the agent block.
+ *
+ * Part of the SDK public API (exported via `src/models.ts` → velt-types).
+ *
+ * NAMING: this feature uses `state`, never `status`. `status` already means
+ * four different things on adjacent objects (`CommentAnnotation.status` is a
+ * `CustomStatus`, `Comment.status` is `'added' | 'updated'`,
+ * `SuggestionData.status` is the suggestion lifecycle, plus per-step).
+ */
+/**
+ * Lifecycle of one progress run.
+ *
+ * REQUIRED on `CommentProgress`, and deliberately so: presence-based state
+ * would force the final update to DELETE the field, and a Firestore merge write
+ * cannot remove a field without `FieldValue.delete()`. An explicit
+ * `state: 'completed'` makes the final update a plain merge.
+ *
+ * `'active'` deliberately matches the per-step `'active'`: both mean "the one
+ * currently running", at different levels.
+ */
+export type CommentProgressState = 'active' | 'completed' | 'failed' | 'cancelled';
+/** Lifecycle of one step within a progress run. */
+export type CommentProgressStepState = 'pending' | 'active' | 'completed' | 'failed';
+/**
+ * One step of the progress trace.
+ *
+ * Phase 1 renders only the current step's label. The array exists so this can
+ * grow into an expandable trace later without a model change.
+ */
+export interface CommentProgressStep {
+    id?: string;
+    /**
+     * Customer-authored label shown on the progress row.
+     *
+     * This is CUSTOMER CONTENT and is never translated — see
+     * `resolveProgressLabel` in `src/app/utils/comment-progress.utils.ts`.
+     */
+    label: string;
+    state?: CommentProgressStepState;
+    startedAt?: number;
+    completedAt?: number;
+    metadata?: any;
+}
+/**
+ * Progress payload on a comment.
+ */
+export interface CommentProgress {
+    /** REQUIRED. See `CommentProgressState` for why presence-based state was rejected. */
+    state: CommentProgressState;
+    /**
+     * Progress steps.
+     *
+     * **The customer owns this array outright.** `updateComment` replaces the
+     * comment wholesale, so whatever `steps` you send IS the new array. There is
+     * deliberately NO server-side appending: it would make the SDK stateful about
+     * array order, and it would break the checklist pattern below, where
+     * re-sending the same list with a different step marked active is exactly the
+     * right move.
+     *
+     * Three authoring patterns are supported, and label resolution handles all
+     * three without being told which is in play:
+     *
+     *  - **Replace** — send a single-element array on each push.
+     *    ```
+     *    push 1:  [ { label: 'Getting data',    state: 'active' } ]
+     *    push 2:  [ { label: 'Processing data', state: 'active' } ]
+     *    ```
+     *    Simplest, and keeps no history.
+     *
+     *  - **Append** — grow the array, marking the newest step active.
+     *    ```
+     *    push 1:  [ { label: 'Getting data', state: 'active' } ]
+     *    push 2:  [ { label: 'Getting data', state: 'completed' },
+     *               { label: 'Processing data', state: 'active' } ]
+     *    ```
+     *    Richer, and what a streaming agent naturally produces. It preserves the
+     *    history a future expandable trace needs. Phase 1 renders only the tail.
+     *
+     *  - **Checklist** — send the full list up front and move the `active` marker.
+     *    ```
+     *    push 1:  [ { label: 'Getting data',    state: 'active'  },
+     *               { label: 'Processing data', state: 'pending' } ]
+     *    push 2:  [ { label: 'Getting data',    state: 'completed' },
+     *               { label: 'Processing data', state: 'active'    } ]
+     *    ```
+     *
+     * **At most one step should be `state: 'active'` at a time.** The resolver
+     * tolerates violations gracefully — it takes the LAST active step, so an
+     * append-without-demoting still advances correctly — but a single active step
+     * is the contract, and relying on the tolerance makes the rendered label
+     * depend on array order rather than on what you marked.
+     */
+    steps?: CommentProgressStep[];
+    /**
+     * DISPLAY-ONLY. Phase 1 defaults to everyone and NEVER scopes.
+     *
+     * This is explicitly **not a security boundary**: Velt visibility is
+     * annotation-level, so a comment inside a readable annotation is readable by
+     * all. Do not add a filter keyed on this field without changing that
+     * architecture first.
+     */
+    visibleToUserIds?: string[];
+    /**
+     * Customer-supplied start time.
+     *
+     * NEVER used for staleness — the staleness fail-safe reads the comment's own
+     * SERVER-STAMPED `lastUpdated` (spec AC-046). Also never used for ordering
+     * multiple progress rows, which sort by server-stamped `createdAt`, because
+     * `startedAt` is optional and has no value when absent (spec AC-036).
+     */
+    startedAt?: number;
+}

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

@@ -1,4 +1,6 @@
 import { Attachment } from "./attachment.model";
+import type { CommentAction } from "./comment-action.data.model";
+import type { CommentProgress } from "./comment-progress.data.model";
 import { AutocompleteGroupReplaceData, AutocompleteReplaceData, AutocompleteUserContactReplaceData } from "./autocomplete.data.model";
 import type { AgentData } from "./comment-annotation.data.model";
 import { ReactionAnnotation } from "./reaction-annotation.data.model";
@@ -106,4 +108,31 @@ export declare class Comment {
      * provides it; not server-generated.
      */
     metadata?: any;
+    /**
+     * Customer-defined action buttons rendered on this comment.
+     *
+     * Overrides `CommentAnnotation.actions` for this comment. `undefined` falls
+     * back to the annotation-level list; an explicit `[]` (or a list whose every
+     * entry is non-renderable) renders NO row and does NOT fall back to the
+     * built-in accept/reject.
+     *
+     * NOT inside `agent`: `agent` is provenance (who authored), `actions` is
+     * affordance (what you can do), and they have different lifecycles — the
+     * action list is rewritten many times over one immutable agent identity.
+     */
+    actions?: CommentAction[];
+    /**
+     * Progress payload for an in-flight or finished multi-step operation on this
+     * comment — an agent run, a translation pass, a moderation check, a workflow.
+     *
+     * NOT inside `agent`, and that is the point: requiring a valid agent identity
+     * to render a progress indicator was a bad constraint, and progress is a
+     * property of the comment rather than of its author. See
+     * `CommentProgress` for the full rationale.
+     *
+     * A content-less comment carrying this field is split out of
+     * `annotation.comments` at the data layer, so it never affects reply count,
+     * sidebar preview text, resolve, or any `comments.length`-driven dialog gate.
+     */
+    progress?: CommentProgress;
 }

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

@@ -1323,6 +1323,14 @@ export declare class CommentElement {
    * To set max reply avatars
    */
   public setMaxReplyAvatars: (maxReplyAvatars: number) => void;
+  /**
+   * Staleness window for the comment progress indicator, in milliseconds. Default 600000.
+   *
+   * Not a timeout: this is a staleness comparison evaluated only when a component
+   * receives the annotation, and a stale row already on screen is allowed to remain.
+   * Raise it for long-running agents.
+   */
+  public setCommentProgressStaleAfter: (commentProgressStaleAfter: number) => void;
 
   /**
    * To set sidebar button count type
@@ -2692,6 +2700,7 @@ export declare class CommentElement {
   /**
    * To set max reply avatars
    */
+  private _setCommentProgressStaleAfter;
   private _setMaxReplyAvatars;
 
   /**

package/app/utils/enums.d.ts

@@ -109,6 +109,7 @@ export declare const CommentEventTypes: {
     readonly VISIBILITY_OPTION_CLICKED: "visibilityOptionClicked";
     readonly SUGGESTION_ACCEPTED: "suggestionAccepted";
     readonly SUGGESTION_REJECTED: "suggestionRejected";
+    readonly COMMENT_ACTION_CLICKED: "commentActionClicked";
 };
 export declare const RecorderEventTypes: {
     readonly TRANSCRIPTION_DONE: "transcriptionDone";

package/models.d.ts

@@ -5,6 +5,8 @@ export * from './app/models/data/activity.data.model';
 export * from './app/models/data/area-annotation.data.model';
 export * from './app/features/arrow/models/arrow-annotation.model';
 export * from './app/models/data/agent-suggestion.data.model';
+export * from './app/models/data/comment-progress.data.model';
+export * from './app/models/data/comment-action.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/types",
-    "version": "6.0.8-beta.1",
+    "version": "6.0.8-beta.2",
     "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": [