featurebase-node 0.0.2

package/src/resources/comments.ts

@@ -0,0 +1,786 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as TicketsAPI from './tickets/tickets';
+import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Threaded discussions on posts and changelogs. Comments support voting, moderation, and privacy controls.
+ */
+export class Comments extends APIResource {
+  /**
+   * Creates a new comment or reply to an existing comment.
+   *
+   * You can create a comment for a post or changelog. Comments support:
+   *
+   * - HTML content (images are automatically uploaded to our storage)
+   * - Threading (replies via `parentCommentId`)
+   * - Privacy controls (private comments visible only to admins)
+   * - Author attribution (post on behalf of users)
+   *
+   * ### Required Fields
+   *
+   * - `content` - Comment content in HTML format
+   * - `postId` OR `changelogId` - One is required to specify the target
+   *
+   * ### Optional Fields
+   *
+   * - `parentCommentId` - Create a reply to an existing comment
+   * - `isPrivate` - Make comment visible only to admins (default: false)
+   * - `sendNotification` - Notify voters about the comment (default: true)
+   * - `author` - Post comment under a specific user (uses authenticated user if not
+   *   provided)
+   * - `createdAt` - Backdate creation (useful for imports)
+   *
+   * ### Author Object
+   *
+   * The `author` field supports multiple identification methods:
+   *
+   * - `id` - Featurebase user ID (direct reference)
+   * - `userId` - External user ID from your system (via SSO)
+   * - `email` - Email address (finds existing or creates new user)
+   * - `name` - Display name (used with email for new users)
+   * - `profilePicture` - Profile picture URL
+   *
+   * If no author is provided, the comment is posted under the authenticated user.
+   *
+   * ### Content Format
+   *
+   * Content should be formatted as HTML. For images:
+   *
+   * - External URLs in `img src` attributes are automatically pulled into our
+   *   storage
+   * - Base64 encoded data URIs (`data:image/...`) are also supported and processed
+   *
+   * ### Response
+   *
+   * Returns the created comment object with all fields populated, including:
+   *
+   * - `id` - Unique comment identifier
+   * - `author` - Author information
+   * - Voting stats and timestamps
+   *
+   * ### Errors
+   *
+   * - `400` - Invalid input (missing required fields, invalid IDs)
+   * - `403` - Commenting disabled or not authorized
+   * - `404` - Post/changelog not found or parent comment not found
+   *
+   * @example
+   * ```ts
+   * const comment = await client.comments.create({
+   *   content: '<p>This is a great idea!</p>',
+   * });
+   * ```
+   */
+  create(params: CommentCreateParams, options?: RequestOptions): APIPromise<Comment> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/comments', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Retrieves a single comment by its unique identifier.
+   *
+   * Returns the full comment object including:
+   *
+   * - Author information
+   * - Voting stats (upvotes, downvotes, score)
+   * - Privacy and moderation status
+   * - Threading information (parentCommentId)
+   * - Timestamps
+   *
+   * ### Response
+   *
+   * Returns a comment object with all fields populated.
+   *
+   * ### Errors
+   *
+   * - `400` - Invalid comment ID format
+   * - `404` - Comment not found or doesn't belong to your organization
+   *
+   * @example
+   * ```ts
+   * const comment = await client.comments.retrieve(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  retrieve(
+    id: string,
+    params: CommentRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Comment> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.get(path`/v2/comments/${id}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Updates an existing comment by its unique identifier.
+   *
+   * You can update:
+   *
+   * - **content** - Comment text (HTML format)
+   * - **isPrivate** - Privacy status (admin-only visibility)
+   * - **isPinned** - Pinned status (displayed at top)
+   * - **inReview** - Moderation status
+   *
+   * ### Content Format
+   *
+   * Content should be formatted as HTML. For images:
+   *
+   * - External URLs in `img src` attributes are automatically pulled into our
+   *   storage
+   * - Base64 encoded data URIs (`data:image/...`) are also supported and processed
+   *
+   * ### Permissions
+   *
+   * - Comment authors can update their own comment content
+   * - Admin permissions required for:
+   *   - `isPrivate` - Requires `manage_comments_private` permission
+   *   - `isPinned` - Requires `set_comment_pinned` permission
+   *   - `inReview` - Requires `moderate_comments` permission
+   *   - Updating other users' comments - Requires `moderate_comments` permission
+   *
+   * ### Response
+   *
+   * Returns the updated comment object with all fields populated.
+   *
+   * ### Errors
+   *
+   * - `400` - Invalid comment ID format or input
+   * - `403` - Not authorized to update this comment
+   * - `404` - Comment not found
+   *
+   * @example
+   * ```ts
+   * const comment = await client.comments.update(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  update(id: string, params: CommentUpdateParams, options?: RequestOptions): APIPromise<Comment> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.patch(path`/v2/comments/${id}`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Returns comments for your organization.
+   *
+   * Comments are threaded discussions. Each comment can have:
+   *
+   * - Author information
+   * - Voting (upvotes/downvotes)
+   * - Privacy settings (public/private)
+   * - Moderation status
+   * - Parent comment reference for threading
+   *
+   * ### Filtering
+   *
+   * Optionally filter by:
+   *
+   * - `postId` - Get comments for a specific post
+   * - `changelogId` - Get comments for a specific changelog
+   *
+   * If no filter is provided, returns all comments across the organization.
+   *
+   * ### Pagination
+   *
+   * This endpoint uses **cursor-based pagination**:
+   *
+   * - `limit` - Number of comments to return (1-100, default 10)
+   * - `cursor` - Opaque cursor from a previous response's `nextCursor` field
+   *
+   * **Example:** To paginate through results:
+   *
+   * 1. First request: `GET /v2/comments?postId={id}&limit=10`
+   * 2. If `nextCursor` is not null, use it for the next page
+   * 3. Next request: `GET /v2/comments?postId={id}&limit=10&cursor={nextCursor}`
+   *
+   * ### Response Format
+   *
+   * Returns a list object with:
+   *
+   * - `object` - Always "list"
+   * - `data` - Array of comment objects (flat structure with `parentCommentId` for
+   *   threading)
+   * - `nextCursor` - Cursor for the next page (null if no more results)
+   *
+   * ### Comment Structure
+   *
+   * Each comment includes:
+   *
+   * - `id` - Unique comment identifier
+   * - `postId` / `changelogId` - Reference to the parent content
+   * - `parentCommentId` - Reference to parent comment (null for root comments)
+   * - `content` - Comment content in HTML format
+   * - `author` - Author information (id, name, profilePicture, type)
+   * - `upvotes` / `downvotes` / `score` - Voting metrics
+   * - `isPrivate` - Whether comment is only visible to admins
+   * - `inReview` - Whether comment is pending moderation
+   * - `created` / `updated` - Unix timestamps
+   *
+   * ### Additional Filters
+   *
+   * - `privacy` - Filter by privacy: "public", "private", or "all"
+   * - `inReview` - Filter by moderation status (true/false)
+   *
+   * ### Sorting
+   *
+   * Use `sortBy` to sort results:
+   *
+   * - `best` - Sort by confidence score (default, like Reddit)
+   * - `top` - Sort by net score (upvotes - downvotes)
+   * - `new` - Sort by creation date, newest first
+   * - `old` - Sort by creation date, oldest first
+   *
+   * @example
+   * ```ts
+   * const comments = await client.comments.list();
+   * ```
+   */
+  list(
+    params: CommentListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<CommentListResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+    return this._client.get('/v2/comments', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Deletes a comment by its unique identifier.
+   *
+   * ### Deletion Behavior
+   *
+   * - **Comments with replies**: Soft delete
+   *
+   *   - Content is replaced with "[deleted]"
+   *   - Author information is anonymized
+   *   - Comment remains visible to maintain conversation context
+   *   - Votes and scores are reset to 0
+   *
+   * - **Comments without replies**: Hard delete
+   *   - Comment is permanently removed from the database
+   *   - All associated data is deleted
+   *
+   * ### Permissions
+   *
+   * - Comment authors can delete their own comments
+   * - Admins can delete any comment (subject to permissions)
+   * - Lite seat admins can only delete their own comments
+   * - Non-authors require `manage_comments` or `manage_comments_private` permission
+   *
+   * ### Response
+   *
+   * Returns a deletion confirmation:
+   *
+   * ```json
+   * {
+   *   "id": "507f1f77bcf86cd799439011",
+   *   "object": "comment",
+   *   "deleted": true
+   * }
+   * ```
+   *
+   * ### Errors
+   *
+   * - `400` - Invalid comment ID format
+   * - `403` - Not authorized to delete this comment
+   * - `404` - Comment not found or doesn't belong to your organization
+   *
+   * @example
+   * ```ts
+   * const response = await client.comments.delete0(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  delete0(
+    id: string,
+    params: CommentDelete0Params | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<CommentDelete0Response> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.delete(path`/v2/comments/${id}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Deletes a comment using the legacy Clover API format.
+   *
+   * This endpoint accepts the comment ID in the request body instead of the route
+   * parameter.
+   *
+   * ### Request Body
+   *
+   * ```json
+   * {
+   *   "id": "507f1f77bcf86cd799439011"
+   * }
+   * ```
+   *
+   * ### Deletion Behavior
+   *
+   * - **Comments with replies**: Soft delete
+   *
+   *   - Content is replaced with "[deleted]"
+   *   - Author information is anonymized
+   *   - Comment remains visible to maintain conversation context
+   *   - Votes and scores are reset to 0
+   *
+   * - **Comments without replies**: Hard delete
+   *   - Comment is permanently removed from the database
+   *   - All associated data is deleted
+   *
+   * ### Permissions
+   *
+   * - Comment authors can delete their own comments
+   * - Admins can delete any comment (subject to permissions)
+   * - Lite seat admins can only delete their own comments
+   * - Non-authors require `manage_comments` or `manage_comments_private` permission
+   *
+   * ### Response
+   *
+   * Returns a success confirmation (Clover format):
+   *
+   * ```json
+   * {
+   *   "success": true
+   * }
+   * ```
+   *
+   * Note: Nova API returns `{ id, object: "comment", deleted: true }`, but Clover
+   * transformer converts it to `{ success: true }` for backwards compatibility.
+   *
+   * ### Errors
+   *
+   * - `400` - Invalid comment ID format or missing ID in body
+   * - `403` - Not authorized to delete this comment
+   * - `404` - Comment not found or doesn't belong to your organization
+   *
+   * @example
+   * ```ts
+   * const response = await client.comments.delete1({
+   *   id: '507f1f77bcf86cd799439011',
+   * });
+   * ```
+   */
+  delete1(params: CommentDelete1Params, options?: RequestOptions): APIPromise<CommentDelete1Response> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.delete('/v2/comment', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface Comment {
+  /**
+   * Unique identifier
+   */
+  id: string;
+
+  author: Comment.Author | null;
+
+  /**
+   * Changelog ID this comment belongs to
+   */
+  changelogId: string | null;
+
+  /**
+   * Comment content in HTML format
+   */
+  content: string;
+
+  /**
+   * ISO 8601 timestamp when created
+   */
+  createdAt: string;
+
+  /**
+   * Number of downvotes
+   */
+  downvotes: number;
+
+  /**
+   * Whether the comment is in review
+   */
+  inReview: boolean;
+
+  /**
+   * Whether the comment is deleted
+   */
+  isDeleted: boolean;
+
+  /**
+   * Whether the comment is pinned
+   */
+  isPinned: boolean;
+
+  /**
+   * Whether the comment is private
+   */
+  isPrivate: boolean;
+
+  /**
+   * Whether the comment is spam
+   */
+  isSpam: boolean;
+
+  /**
+   * Object type identifier
+   */
+  object: 'comment';
+
+  /**
+   * Parent comment ID for replies, null for root comments
+   */
+  parentCommentId: string | null;
+
+  /**
+   * Post ID this comment belongs to
+   */
+  postId: string | null;
+
+  /**
+   * Net score (upvotes - downvotes)
+   */
+  score: number;
+
+  /**
+   * ISO 8601 timestamp when updated
+   */
+  updatedAt: string;
+
+  /**
+   * Number of upvotes
+   */
+  upvotes: number;
+}
+
+export namespace Comment {
+  export interface Author {
+    /**
+     * Author unique identifier
+     */
+    id: string | null;
+
+    /**
+     * Author display name
+     */
+    name: string;
+
+    /**
+     * Author profile picture URL
+     */
+    profilePicture: string | null;
+
+    /**
+     * Type of user who authored the comment
+     */
+    type: 'admin' | 'customer' | 'guest' | 'integration' | 'bot' | 'lead';
+  }
+}
+
+export interface CommentListResponse {
+  /**
+   * Array of comments
+   */
+  data: Array<Comment>;
+
+  /**
+   * Cursor for fetching the next page (cursor-based pagination)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+
+  /**
+   * Pagination metadata for page-based requests
+   */
+  pagination?: CommentListResponse.Pagination;
+}
+
+export namespace CommentListResponse {
+  /**
+   * Pagination metadata for page-based requests
+   */
+  export interface Pagination {
+    /**
+     * Items per page
+     */
+    limit: number;
+
+    /**
+     * Current page number
+     */
+    page: number;
+
+    /**
+     * Total number of items
+     */
+    total: number;
+
+    /**
+     * Total number of pages
+     */
+    totalPages: number;
+  }
+}
+
+export interface CommentDelete0Response {
+  /**
+   * Unique identifier of the deleted comment
+   */
+  id: string;
+
+  /**
+   * Indicates the resource was deleted
+   */
+  deleted: true;
+
+  /**
+   * Object type identifier
+   */
+  object: 'comment';
+}
+
+export interface CommentDelete1Response {
+  success: boolean;
+}
+
+export interface CommentCreateParams {
+  /**
+   * Body param: Comment content in HTML format
+   */
+  content: string;
+
+  /**
+   * Body param: Author to attribute the post to. If not provided, uses the
+   * authenticated user. Supports multiple identification methods: id (Featurebase
+   * ID), userId (external SSO ID), or email.
+   */
+  author?: TicketsAPI.AuthorInput;
+
+  /**
+   * Body param: Changelog ID to comment on (accepts ObjectId or slug)
+   */
+  changelogId?: string;
+
+  /**
+   * Body param: Set the date when the comment was created. Useful for importing
+   * comments from other platforms.
+   */
+  createdAt?: string | null;
+
+  /**
+   * Body param: Initial downvotes count. Useful for importing comments from other
+   * platforms. Score will be calculated as upvotes - downvotes.
+   */
+  downvotes?: number | null;
+
+  /**
+   * Body param: Whether the comment is private (only visible to admins)
+   */
+  isPrivate?: boolean | null;
+
+  /**
+   * Body param: Parent comment ID if this is a reply
+   */
+  parentCommentId?: string;
+
+  /**
+   * Body param: Post ID to comment on (accepts ObjectId or slug)
+   */
+  postId?: string;
+
+  /**
+   * Body param: Whether to notify voters of the submission about the comment
+   */
+  sendNotification?: boolean | null;
+
+  /**
+   * Body param: Initial upvotes count. Useful for importing comments from other
+   * platforms. Score will be calculated as upvotes - downvotes.
+   */
+  upvotes?: number | null;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface CommentRetrieveParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface CommentUpdateParams {
+  /**
+   * Body param: Comment content in HTML format
+   */
+  content?: string;
+
+  /**
+   * Body param: Update the creation date (useful for imports)
+   */
+  createdAt?: string | null;
+
+  /**
+   * Body param: Set the downvotes count directly. Score will be recalculated as
+   * upvotes - downvotes.
+   */
+  downvotes?: number | null;
+
+  /**
+   * Body param: Whether the comment is pending moderation review
+   */
+  inReview?: boolean | null;
+
+  /**
+   * Body param: Whether the comment is pinned at the top
+   */
+  isPinned?: boolean | null;
+
+  /**
+   * Body param: Whether the comment is private (only visible to admins)
+   */
+  isPrivate?: boolean | null;
+
+  /**
+   * Body param: Set the upvotes count directly. Score will be recalculated as
+   * upvotes - downvotes.
+   */
+  upvotes?: number | null;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface CommentListParams {
+  /**
+   * Query param: Filter comments by changelog ID
+   */
+  changelogId?: string;
+
+  /**
+   * Query param: Cursor for pagination. Use nextCursor from previous response.
+   */
+  cursor?: string;
+
+  /**
+   * Query param: Filter by review status
+   */
+  inReview?: boolean | null;
+
+  /**
+   * Query param: Maximum number of comments to return
+   */
+  limit?: number;
+
+  /**
+   * Query param: Filter comments by post ID
+   */
+  postId?: string;
+
+  /**
+   * Query param: Filter comments by privacy
+   */
+  privacy?: 'public' | 'private' | 'all';
+
+  /**
+   * Query param: Sort order for comments
+   */
+  sortBy?: 'best' | 'top' | 'new' | 'old';
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface CommentDelete0Params {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface CommentDelete1Params {
+  /**
+   * Body param: Comment ID
+   */
+  id: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export declare namespace Comments {
+  export {
+    type Comment as Comment,
+    type CommentListResponse as CommentListResponse,
+    type CommentDelete0Response as CommentDelete0Response,
+    type CommentDelete1Response as CommentDelete1Response,
+    type CommentCreateParams as CommentCreateParams,
+    type CommentRetrieveParams as CommentRetrieveParams,
+    type CommentUpdateParams as CommentUpdateParams,
+    type CommentListParams as CommentListParams,
+    type CommentDelete0Params as CommentDelete0Params,
+    type CommentDelete1Params as CommentDelete1Params,
+  };
+}