featurebase-node 0.0.2

package/resources/comments.js

@@ -0,0 +1,397 @@
+"use strict";
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Comments = void 0;
+const resource_1 = require("../core/resource.js");
+const headers_1 = require("../internal/headers.js");
+const path_1 = require("../internal/utils/path.js");
+/**
+ * Threaded discussions on posts and changelogs. Comments support voting, moderation, and privacy controls.
+ */
+class Comments extends resource_1.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, options) {
+        const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+        return this._client.post('/v2/comments', {
+            body,
+            ...options,
+            headers: (0, headers_1.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, params = {}, options) {
+        const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+        return this._client.get((0, path_1.path) `/v2/comments/${id}`, {
+            ...options,
+            headers: (0, headers_1.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, params, options) {
+        const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+        return this._client.patch((0, path_1.path) `/v2/comments/${id}`, {
+            body,
+            ...options,
+            headers: (0, headers_1.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 = {}, options) {
+        const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+        return this._client.get('/v2/comments', {
+            query,
+            ...options,
+            headers: (0, headers_1.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, params = {}, options) {
+        const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+        return this._client.delete((0, path_1.path) `/v2/comments/${id}`, {
+            ...options,
+            headers: (0, headers_1.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, options) {
+        const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+        return this._client.delete('/v2/comment', {
+            body,
+            ...options,
+            headers: (0, headers_1.buildHeaders)([
+                { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+                options?.headers,
+            ]),
+        });
+    }
+}
+exports.Comments = Comments;
+//# sourceMappingURL=comments.js.map

package/resources/comments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.js","sourceRoot":"","sources":["../src/resources/comments.ts"],"names":[],"mappings":"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"}