featurebase-node 0.0.2

package/resources/posts/posts.d.mts

@@ -0,0 +1,799 @@
+import { APIResource } from "../../core/resource.mjs";
+import * as PostStatusesAPI from "../post-statuses.mjs";
+import * as VotersAPI from "./voters.mjs";
+import { VoterAddParams, VoterAddResponse, VoterListParams, VoterListResponse, VoterRemoveParams, VoterRemoveResponse, Voters } from "./voters.mjs";
+import * as TicketsAPI from "../tickets/tickets.mjs";
+import { APIPromise } from "../../core/api-promise.mjs";
+import { RequestOptions } from "../../internal/request-options.mjs";
+/**
+ * User-submitted feedback and feature requests. Posts belong to boards and can be upvoted, commented on, and tracked through statuses.
+ */
+export declare class Posts extends APIResource {
+    voters: VotersAPI.Voters;
+    /**
+     * Creates a new post (feedback submission) in the specified board.
+     *
+     * ### Required Fields
+     *
+     * - `title` - Post title (minimum 2 characters)
+     * - `boardId` - Board ID to create the post in
+     *
+     * ### Optional Fields
+     *
+     * - `content` - Post content in HTML format
+     * - `tags` - Array of tag names to attach
+     * - `statusId` - Status ID to set (defaults to board's default status)
+     * - `commentsEnabled` - Whether comments are allowed (default: true)
+     * - `inReview` - Whether post is pending moderation (default: false)
+     * - `customFields` - Custom field values as key-value pairs
+     * - `eta` - Estimated completion date (Unix timestamp or ISO date)
+     * - `assigneeId` - Admin ID to assign this post to
+     * - `visibility` - Post-level visibility restriction: 'public' (no additional
+     *   restrictions), 'authorOnly' (only author and admins), or 'companyOnly' (only
+     *   users in author's company). Note: even 'public' posts are still subject to
+     *   board-level and organization-level access controls.
+     *
+     * ### Author Attribution
+     *
+     * For posts created on behalf of users, use the `author` object:
+     *
+     * - `id` - Featurebase user ID
+     * - `userId` - External SSO user ID
+     * - `email` - User's email address
+     * - `name` - Display name
+     * - `profilePicture` - Profile picture URL
+     *
+     * Resolution priority: `id` > `userId` > `email` > authenticated user
+     *
+     * ### Backdating (Imports)
+     *
+     * - `createdAt` - Override creation date for importing historical data
+     *
+     * ### Response
+     *
+     * Returns the created post object with all fields populated.
+     *
+     * @example
+     * ```ts
+     * const post = await client.posts.create({
+     *   boardId: '507f1f77bcf86cd799439011',
+     *   title: 'Add dark mode support',
+     * });
+     * ```
+     */
+    create(params: PostCreateParams, options?: RequestOptions): APIPromise<Post>;
+    /**
+     * Retrieves a single post by its unique identifier.
+     *
+     * Returns the full post object including:
+     *
+     * - Author information
+     * - Current status
+     * - Tags
+     * - Voting stats
+     * - Engagement metrics
+     * - Custom field values
+     *
+     * @example
+     * ```ts
+     * const post = await client.posts.retrieve(
+     *   '507f1f77bcf86cd799439011',
+     * );
+     * ```
+     */
+    retrieve(id: string, params?: PostRetrieveParams | null | undefined, options?: RequestOptions): APIPromise<Post>;
+    /**
+     * Updates an existing post. Only provided fields will be modified.
+     *
+     * ### Updatable Fields
+     *
+     * - `title` - Post title (minimum 2 characters)
+     * - `content` - Post content in HTML format
+     * - `boardId` - Move post to a different board
+     * - `statusId` - Update post status
+     * - `tags` - Replace existing tags with new set
+     * - `commentsEnabled` - Enable/disable comments
+     * - `inReview` - Put post in/out of moderation queue
+     * - `customFields` - Update custom field values
+     * - `eta` - Set estimated completion date (null to clear)
+     * - `createdAt` - Update creation date (for backdating)
+     * - `assigneeId` - Admin ID to assign this post to (null to unassign)
+     * - `visibility` - Post-level visibility restriction: 'public' (no additional
+     *   restrictions), 'authorOnly' (only author and admins), or 'companyOnly' (only
+     *   users in author's company). Note: even 'public' posts are still subject to
+     *   board-level and organization-level access controls.
+     * - `author` - Change post attribution (id, userId, email, name, profilePicture)
+     *
+     * ### Status Update Notifications
+     *
+     * - `sendStatusUpdateEmail` - When changing status, optionally send email
+     *   notification to voters (default: false)
+     *
+     * ### Response
+     *
+     * Returns the updated post object with all fields populated.
+     *
+     * @example
+     * ```ts
+     * const post = await client.posts.update(
+     *   '507f1f77bcf86cd799439011',
+     * );
+     * ```
+     */
+    update(id: string, params: PostUpdateParams, options?: RequestOptions): APIPromise<Post>;
+    /**
+     * Returns all posts (feedback submissions) for the authenticated organization.
+     *
+     * Posts are user-submitted feedback items. Each post belongs to a board and can
+     * have:
+     *
+     * - Status (in progress, complete, etc.)
+     * - Tags for categorization
+     * - Upvotes from users
+     * - Comments (if enabled)
+     * - Custom field values
+     *
+     * ### Pagination
+     *
+     * This endpoint uses **cursor-based pagination**:
+     *
+     * - `limit` - Number of posts 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/posts?limit=10`
+     * 2. If `nextCursor` is not null, use it for the next page
+     * 3. Next request: `GET /v2/posts?limit=10&cursor={nextCursor}`
+     *
+     * ### Response Format
+     *
+     * Returns a list object with:
+     *
+     * - `object` - Always "list"
+     * - `data` - Array of post objects
+     * - `nextCursor` - Cursor for the next page (null if no more results)
+     *
+     * ### Filtering
+     *
+     * Filter posts using query parameters:
+     *
+     * - `boardId` - Filter by board (category) ID
+     * - `statusId` - Filter by status ID
+     * - `tags` - Filter by tag names (can be comma-separated or repeated)
+     * - `q` - Search query for title/content
+     * - `inReview` - Include posts pending moderation
+     *
+     * ### Sorting
+     *
+     * Use `sortBy` to sort results:
+     *
+     * - `createdAt` - Sort by creation date (default)
+     * - `upvotes` - Sort by vote count
+     * - `trending` - Sort by trending score
+     * - `recent` - Sort by most recently updated
+     *
+     * @example
+     * ```ts
+     * const posts = await client.posts.list();
+     * ```
+     */
+    list(params?: PostListParams | null | undefined, options?: RequestOptions): APIPromise<PostListResponse>;
+    /**
+     * Permanently deletes a post. This action cannot be undone.
+     *
+     * ### What Gets Deleted
+     *
+     * When you delete a post:
+     *
+     * - The post itself is permanently removed
+     * - All comments on the post are deleted
+     * - Vote records are removed
+     * - Any associated notifications are cleared
+     *
+     * ### Response
+     *
+     * Returns a deletion confirmation object with:
+     *
+     * - `id` - The ID of the deleted post
+     * - `object` - Always "post"
+     * - `deleted` - Always true
+     *
+     * ### Permissions
+     *
+     * Requires member-level access or higher to delete posts.
+     *
+     * @example
+     * ```ts
+     * const post = await client.posts.delete(
+     *   '507f1f77bcf86cd799439011',
+     * );
+     * ```
+     */
+    delete(id: string, params?: PostDeleteParams | null | undefined, options?: RequestOptions): APIPromise<PostDeleteResponse>;
+}
+export interface Post {
+    /**
+     * Unique identifier
+     */
+    id: string;
+    access: Post.Access;
+    /**
+     * ID of the admin assigned to this post, null if unassigned
+     */
+    assigneeId: string | null;
+    author: Post.Author | null;
+    /**
+     * Board (category) ID this post belongs to
+     */
+    boardId: string;
+    /**
+     * Total number of comments
+     */
+    commentCount: number;
+    /**
+     * Post content in HTML format
+     */
+    content: string;
+    /**
+     * ISO 8601 timestamp when created
+     */
+    createdAt: string;
+    /**
+     * Custom field values keyed by field ID
+     */
+    customFields: {
+        [key: string]: unknown;
+    };
+    /**
+     * Estimated completion time as ISO 8601 timestamp, null if not set
+     */
+    eta: string | null;
+    features: Post.Features;
+    /**
+     * Whether the post is pending moderation review
+     */
+    inReview: boolean;
+    /**
+     * Third-party integration links associated with this post
+     */
+    integrations: Post.Integrations;
+    /**
+     * Whether the post is pinned to the top
+     */
+    isPinned: boolean;
+    /**
+     * Object type identifier
+     */
+    object: 'post';
+    /**
+     * Total opportunity amount from linked HubSpot deals and Salesforce opportunities
+     */
+    opportunityAmount: number | null;
+    /**
+     * Full URL to view the post
+     */
+    postUrl: string;
+    /**
+     * URL-friendly slug
+     */
+    slug: string;
+    status: PostStatusesAPI.PostStatus;
+    /**
+     * Tags attached to this post
+     */
+    tags: Array<Post.Tag>;
+    /**
+     * Post title
+     */
+    title: string;
+    /**
+     * ISO 8601 timestamp when last modified
+     */
+    updatedAt: string;
+    /**
+     * Total number of upvotes
+     */
+    upvotes: number;
+}
+export declare namespace Post {
+    interface Access {
+        /**
+         * External company IDs explicitly granted access to this post. Empty array means
+         * no company-level restrictions. Non-empty means only users belonging to these
+         * companies can see the post.
+         */
+        companyExternalIds: Array<string>;
+        /**
+         * User IDs explicitly granted access to this post. Empty array means no user-level
+         * restrictions (post uses board/org visibility). Non-empty means only these users
+         * (plus admins) can see the post.
+         */
+        userIds: Array<string>;
+    }
+    interface Author {
+        /**
+         * Author unique identifier
+         */
+        id: string | null;
+        /**
+         * Author email (if available)
+         */
+        email: string | null;
+        /**
+         * Author display name
+         */
+        name: string;
+        /**
+         * Author profile picture URL
+         */
+        profilePicture: string | null;
+        /**
+         * Type of user who authored the post
+         */
+        type: 'admin' | 'customer' | 'guest' | 'integration' | 'bot' | 'lead';
+    }
+    interface Features {
+        /**
+         * Whether comments are allowed on this post
+         */
+        commentsEnabled: boolean;
+    }
+    /**
+     * Third-party integration links associated with this post
+     */
+    interface Integrations {
+        clickup: Array<Integrations.Clickup>;
+        devops: Array<Integrations.Devop>;
+        github: Array<Integrations.GitHub>;
+        hubspot: Array<Integrations.Hubspot>;
+        jira: Array<Integrations.Jira>;
+        linear: Array<Integrations.Linear>;
+        salesforce: Array<Integrations.Salesforce>;
+    }
+    namespace Integrations {
+        interface Clickup {
+            /**
+             * ClickUp task ID
+             */
+            id: string;
+            /**
+             * ClickUp task title
+             */
+            title: string;
+            /**
+             * URL to the ClickUp task
+             */
+            url: string;
+        }
+        interface Devop {
+            /**
+             * Azure DevOps work item ID
+             */
+            id: number;
+            /**
+             * Azure DevOps project ID
+             */
+            projectId: string;
+            /**
+             * Azure DevOps project name
+             */
+            projectName: string;
+            /**
+             * Work item title
+             */
+            title: string;
+            /**
+             * URL to the work item
+             */
+            url: string;
+        }
+        interface GitHub {
+            /**
+             * GitHub issue ID
+             */
+            id: string;
+            /**
+             * GitHub issue number
+             */
+            number: string;
+            /**
+             * Full repository name (owner/repo)
+             */
+            repositoryFullName: string;
+            /**
+             * Repository name
+             */
+            repositoryName: string;
+            /**
+             * GitHub issue title
+             */
+            title: string;
+            /**
+             * URL to the GitHub issue
+             */
+            url: string;
+        }
+        interface Hubspot {
+            /**
+             * Deal amount (for DEAL type)
+             */
+            dealAmount: number | null;
+            /**
+             * Whether the deal is closed (for DEAL type)
+             */
+            dealClosed: boolean | null;
+            /**
+             * HubSpot object ID
+             */
+            objectId: number;
+            /**
+             * HubSpot object type
+             */
+            type: 'TICKET' | 'DEAL' | 'CONTACT';
+        }
+        interface Jira {
+            /**
+             * Jira issue ID
+             */
+            issueId: string;
+            /**
+             * URL to the Jira issue
+             */
+            issueUrl: string | null;
+        }
+        interface Linear {
+            /**
+             * Linear issue ID
+             */
+            issueId: string;
+            /**
+             * URL to the Linear issue
+             */
+            issueUrl: string | null;
+        }
+        interface Salesforce {
+            /**
+             * Opportunity amount (for Opportunity type)
+             */
+            amount: number | null;
+            /**
+             * Whether the opportunity is closed (for Opportunity type)
+             */
+            isClosed: boolean | null;
+            /**
+             * Salesforce record ID
+             */
+            objectId: string;
+            /**
+             * Salesforce object type
+             */
+            objectType: 'Opportunity' | 'Case';
+        }
+    }
+    interface Tag {
+        /**
+         * Tag unique identifier
+         */
+        id: string;
+        /**
+         * Tag color hex code
+         */
+        color: string | null;
+        /**
+         * Tag name
+         */
+        name: string;
+    }
+}
+export interface PostListResponse {
+    /**
+     * Array of posts
+     */
+    data: Array<Post>;
+    /**
+     * Cursor for fetching the next page (cursor-based pagination)
+     */
+    nextCursor: string | null;
+    /**
+     * Object type identifier
+     */
+    object: 'list';
+    /**
+     * Pagination metadata for page-based requests
+     */
+    pagination?: PostListResponse.Pagination;
+}
+export declare namespace PostListResponse {
+    /**
+     * Pagination metadata for page-based requests
+     */
+    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 PostDeleteResponse {
+    /**
+     * Unique identifier of the deleted post
+     */
+    id: string;
+    /**
+     * Indicates the resource was deleted
+     */
+    deleted: true;
+    /**
+     * Object type identifier
+     */
+    object: 'post';
+}
+export interface PostCreateParams {
+    /**
+     * Body param: Board ID to create post in
+     */
+    boardId: string;
+    /**
+     * Body param: Post title
+     */
+    title: string;
+    /**
+     * Body param: Admin ID to assign this post to
+     */
+    assigneeId?: 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: Whether comments are enabled on this post
+     */
+    commentsEnabled?: boolean | null;
+    /**
+     * Body param: Post content (HTML)
+     */
+    content?: string;
+    /**
+     * Body param: Creation date (for backdating imports)
+     */
+    createdAt?: string | null;
+    /**
+     * Body param: Custom field values. Keys must be valid ObjectIds. Values can be:
+     * string, boolean, number, ISO date string, array of strings, ObjectId string, or
+     * null.
+     */
+    customFields?: {
+        [key: string]: Array<string> | boolean | number | string | string | null;
+    };
+    /**
+     * Body param: Estimated completion date
+     */
+    eta?: string | null;
+    /**
+     * Body param: Whether post is pending moderation
+     */
+    inReview?: boolean | null;
+    /**
+     * Body param: Push the created post to third-party integrations configured on your
+     * organization. Each integration must be explicitly set to true to trigger;
+     * omitted integrations will not be pushed to.
+     */
+    integrations?: PostCreateParams.Integrations;
+    /**
+     * Body param: Whether to send email notifications to admins when this post is
+     * created. When true, admins will receive the same email notifications as when a
+     * post is created from the dashboard. Defaults to false (no emails sent).
+     */
+    notifyAdmins?: boolean;
+    /**
+     * Body param: Status ID to set
+     */
+    statusId?: string;
+    /**
+     * Body param: Tag names to attach
+     */
+    tags?: string | Array<string>;
+    /**
+     * Body param: Initial upvotes count. Defaults to 1 (post author is automatically
+     * added as voter). Use 0 to create a post without any votes.
+     */
+    upvotes?: number | null;
+    /**
+     * Body param: Post visibility. 'public' = visible to all users, 'authorOnly' =
+     * only visible to the author and admins, 'companyOnly' = only visible to users in
+     * the same company as the author
+     */
+    visibility?: 'public' | 'authorOnly' | 'companyOnly';
+    /**
+     * Header param: API version for this request. Defaults to your organization's
+     * configured API version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export declare namespace PostCreateParams {
+    /**
+     * Push the created post to third-party integrations configured on your
+     * organization. Each integration must be explicitly set to true to trigger;
+     * omitted integrations will not be pushed to.
+     */
+    interface Integrations {
+        /**
+         * Push to ClickUp
+         */
+        clickup?: boolean;
+        /**
+         * Push to Discord
+         */
+        discord?: boolean;
+        /**
+         * Push to GitHub
+         */
+        github?: boolean;
+        /**
+         * Push to Jira
+         */
+        jira?: boolean;
+        /**
+         * Push to Linear
+         */
+        linear?: boolean;
+        /**
+         * Push to Slack
+         */
+        slack?: boolean;
+    }
+}
+export interface PostRetrieveParams {
+    /**
+     * API version for this request. Defaults to your organization's configured API
+     * version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface PostUpdateParams {
+    /**
+     * Body param: Admin ID to assign this post to (null to unassign)
+     */
+    assigneeId?: string | null;
+    /**
+     * 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: Board ID to move post to
+     */
+    boardId?: string;
+    /**
+     * Body param: Whether comments are enabled on this post
+     */
+    commentsEnabled?: boolean | null;
+    /**
+     * Body param: Post content (HTML)
+     */
+    content?: string;
+    /**
+     * Body param: Creation date (for backdating)
+     */
+    createdAt?: string | null;
+    /**
+     * Body param: Custom field values. Keys must be valid ObjectIds. Values can be:
+     * string, boolean, number, ISO date string, array of strings, ObjectId string, or
+     * null.
+     */
+    customFields?: {
+        [key: string]: Array<string> | boolean | number | string | string | null;
+    };
+    /**
+     * Body param: Estimated completion date (null to clear)
+     */
+    eta?: string | null;
+    /**
+     * Body param: Whether post is pending moderation
+     */
+    inReview?: boolean | null;
+    /**
+     * Body param: Whether to send status update email to voters
+     */
+    sendStatusUpdateEmail?: boolean | null;
+    /**
+     * Body param: Status ID to set
+     */
+    statusId?: string;
+    /**
+     * Body param: Tag names to set (replaces existing)
+     */
+    tags?: string | Array<string>;
+    /**
+     * Body param: Post title
+     */
+    title?: string;
+    /**
+     * Body param: Set the upvotes count directly. Use with caution as this overrides
+     * the actual vote count.
+     */
+    upvotes?: number | null;
+    /**
+     * Body param: Post visibility. 'public' = visible to all users, 'authorOnly' =
+     * only visible to the author and admins, 'companyOnly' = only visible to users in
+     * the same company as the author
+     */
+    visibility?: 'public' | 'authorOnly' | 'companyOnly';
+    /**
+     * Header param: API version for this request. Defaults to your organization's
+     * configured API version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface PostListParams {
+    /**
+     * Query param: Filter by board (category) ID(s)
+     */
+    boardId?: string | Array<string>;
+    /**
+     * Query param: An opaque cursor for pagination. Use the nextCursor value from a
+     * previous response to fetch the next page of results.
+     */
+    cursor?: string;
+    /**
+     * Query param: Include posts that are in review
+     */
+    inReview?: boolean | null;
+    /**
+     * Query param: A limit on the number of posts to be returned, between 1 and 100.
+     */
+    limit?: number;
+    /**
+     * Query param: Search query to filter posts by title/content
+     */
+    q?: string;
+    /**
+     * Query param: Sort order for posts
+     */
+    sortBy?: 'createdAt' | 'upvotes' | 'trending' | 'recent';
+    /**
+     * Query param: Sort direction
+     */
+    sortOrder?: 'asc' | 'desc';
+    /**
+     * Query param: Filter by status ID(s)
+     */
+    statusId?: string | Array<string>;
+    /**
+     * Query param: Filter by tag names
+     */
+    tags?: string | Array<string>;
+    /**
+     * Header param: API version for this request. Defaults to your organization's
+     * configured API version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export interface PostDeleteParams {
+    /**
+     * API version for this request. Defaults to your organization's configured API
+     * version if not specified.
+     */
+    'Featurebase-Version'?: string;
+}
+export declare namespace Posts {
+    export { type Post as Post, type PostListResponse as PostListResponse, type PostDeleteResponse as PostDeleteResponse, type PostCreateParams as PostCreateParams, type PostRetrieveParams as PostRetrieveParams, type PostUpdateParams as PostUpdateParams, type PostListParams as PostListParams, type PostDeleteParams as PostDeleteParams, };
+    export { Voters as Voters, type VoterListResponse as VoterListResponse, type VoterAddResponse as VoterAddResponse, type VoterRemoveResponse as VoterRemoveResponse, type VoterListParams as VoterListParams, type VoterAddParams as VoterAddParams, type VoterRemoveParams as VoterRemoveParams, };
+}
+//# sourceMappingURL=posts.d.mts.map