featurebase-node 0.0.2

package/src/resources/posts/voters.ts

@@ -0,0 +1,453 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as CompaniesAPI from '../companies/companies';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * User-submitted feedback and feature requests. Posts belong to boards and can be upvoted, commented on, and tracked through statuses.
+ */
+export class Voters extends APIResource {
+  /**
+   * Returns all voters (upvoters) for a specific post.
+   *
+   * Voters are users who have upvoted the post. Each voter is returned in the
+   * standard user format with:
+   *
+   * - Basic info: id, name, email, profilePicture
+   * - User type (admin, customer, guest, etc.)
+   * - Companies the user belongs to
+   * - Activity stats: commentsCreated, postsCreated, lastActivity
+   * - Preferences: subscribedToChangelog, locale, verified
+   *
+   * ### Pagination
+   *
+   * This endpoint uses **cursor-based pagination**:
+   *
+   * - `limit` - Number of voters 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/{id}/voters?limit=10`
+   * 2. If `nextCursor` is not null, use it for the next page
+   * 3. Next request: `GET /v2/posts/{id}/voters?limit=10&cursor={nextCursor}`
+   *
+   * ### Response Format
+   *
+   * Returns a list object with:
+   *
+   * - `object` - Always "list"
+   * - `data` - Array of user objects
+   * - `nextCursor` - Cursor for the next page (null if no more results)
+   *
+   * ### Permissions
+   *
+   * Requires member-level access or higher.
+   *
+   * @example
+   * ```ts
+   * const voters = await client.posts.voters.list(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  list(
+    id: string,
+    params: VoterListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<VoterListResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+    return this._client.get(path`/v2/posts/${id}/voters`, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Adds a voter (upvote) to a post.
+   *
+   * ### Voter Identification
+   *
+   * To add a vote on behalf of a user, provide one or more identification fields:
+   *
+   * - `id` - Featurebase user ID
+   * - `userId` - External SSO user ID from your system
+   * - `email` - User's email address
+   * - `name` - Display name (used when creating a new user)
+   * - `profilePicture` - Profile picture URL (used when creating a new user)
+   *
+   * Resolution priority: `id` > `userId` > `email` > authenticated user
+   *
+   * If no fields are provided, the authenticated user's vote is added.
+   *
+   * If the user doesn't exist, a new customer will be created with the provided
+   * information.
+   *
+   * ### Idempotency
+   *
+   * If the user has already voted on this post, the request succeeds but no
+   * duplicate vote is added.
+   *
+   * ### Response
+   *
+   * Returns a confirmation object with:
+   *
+   * - `object` - Always "voter"
+   * - `added` - Always true
+   * - `id` - The voter's user ID
+   * - `postId` - The post ID the vote was added to
+   *
+   * ### Permissions
+   *
+   * Requires member-level access or higher.
+   *
+   * @example
+   * ```ts
+   * const response = await client.posts.voters.add(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  add(id: string, params: VoterAddParams, options?: RequestOptions): APIPromise<VoterAddResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post(path`/v2/posts/${id}/voters`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Removes a voter (upvote) from a post.
+   *
+   * ### Voter Identification
+   *
+   * To remove a vote on behalf of a user, provide one or more identification fields:
+   *
+   * - `id` - Featurebase user ID
+   * - `userId` - External SSO user ID from your system
+   * - `email` - User's email address
+   *
+   * Resolution priority: `id` > `userId` > `email` > authenticated user
+   *
+   * If no fields are provided, the authenticated user's vote will be removed.
+   *
+   * ### Response
+   *
+   * Returns a confirmation object with:
+   *
+   * - `object` - Always "voter"
+   * - `removed` - Always true
+   * - `id` - The voter's user ID
+   * - `postId` - The post ID the vote was removed from
+   *
+   * ### Permissions
+   *
+   * Requires member-level access or higher.
+   *
+   * @example
+   * ```ts
+   * const voter = await client.posts.voters.remove(
+   *   '507f1f77bcf86cd799439011',
+   * );
+   * ```
+   */
+  remove(id: string, params: VoterRemoveParams, options?: RequestOptions): APIPromise<VoterRemoveResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.delete(path`/v2/posts/${id}/voters`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface VoterListResponse {
+  /**
+   * Array of users
+   */
+  data: Array<VoterListResponse.Data>;
+
+  /**
+   * Cursor for fetching the next page (cursor-based pagination)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+
+  /**
+   * Pagination metadata for page-based requests
+   */
+  pagination?: VoterListResponse.Pagination;
+}
+
+export namespace VoterListResponse {
+  export interface Data {
+    /**
+     * Unique identifier
+     */
+    id: string;
+
+    /**
+     * User display name
+     */
+    name: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'contact';
+
+    /**
+     * Type of user
+     */
+    type: 'admin' | 'customer' | 'guest' | 'integration' | 'bot' | 'lead';
+
+    /**
+     * Number of comments created
+     */
+    commentsCreated?: number;
+
+    /**
+     * Companies the user belongs to
+     */
+    companies?: Array<CompaniesAPI.Company>;
+
+    /**
+     * Custom field values on the user
+     */
+    customFields?: { [key: string]: unknown };
+
+    /**
+     * User description/bio
+     */
+    description?: string;
+
+    /**
+     * User email
+     */
+    email?: string | null;
+
+    /**
+     * Last activity ISO timestamp
+     */
+    lastActivity?: string;
+
+    /**
+     * User locale
+     */
+    locale?: string;
+
+    /**
+     * Whether manually opted out from changelog
+     */
+    manuallyOptedOutFromChangelog?: boolean;
+
+    /**
+     * Organization ID the user belongs to
+     */
+    organizationId?: string;
+
+    /**
+     * Number of posts created
+     */
+    postsCreated?: number;
+
+    /**
+     * Profile picture URL
+     */
+    profilePicture?: string | null;
+
+    /**
+     * User roles
+     */
+    roles?: Array<string>;
+
+    /**
+     * Whether subscribed to changelog
+     */
+    subscribedToChangelog?: boolean;
+
+    /**
+     * External user ID from SSO
+     */
+    userId?: string;
+
+    /**
+     * Whether email is verified
+     */
+    verified?: boolean;
+  }
+
+  /**
+   * 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 VoterAddResponse {
+  /**
+   * Voter unique identifier
+   */
+  id: string;
+
+  /**
+   * Indicates the voter was added
+   */
+  added: true;
+
+  /**
+   * Object type identifier
+   */
+  object: 'voter';
+
+  /**
+   * Post ID the voter was added to
+   */
+  postId: string;
+}
+
+export interface VoterRemoveResponse {
+  /**
+   * Voter unique identifier
+   */
+  id: string;
+
+  /**
+   * Object type identifier
+   */
+  object: 'voter';
+
+  /**
+   * Post ID the voter was removed from
+   */
+  postId: string;
+
+  /**
+   * Indicates the voter was removed
+   */
+  removed: true;
+}
+
+export interface VoterListParams {
+  /**
+   * 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: A limit on the number of voters to be returned, between 1 and 100.
+   */
+  limit?: number;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface VoterAddParams {
+  /**
+   * Body param: Featurebase user ID to add as voter
+   */
+  id?: string;
+
+  /**
+   * Body param: Voter email (used to find or create user)
+   */
+  email?: string;
+
+  /**
+   * Body param: Voter display name (used when creating new user)
+   */
+  name?: string;
+
+  /**
+   * Body param: Voter profile picture URL
+   */
+  profilePicture?: string;
+
+  /**
+   * Body param: External user ID from your system (matched via SSO)
+   */
+  userId?: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface VoterRemoveParams {
+  /**
+   * Body param: Featurebase user ID to remove as voter
+   */
+  id?: string;
+
+  /**
+   * Body param: Voter email to identify user
+   */
+  email?: string;
+
+  /**
+   * Body param: External user ID from your system (matched via SSO)
+   */
+  userId?: 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 Voters {
+  export {
+    type VoterListResponse as VoterListResponse,
+    type VoterAddResponse as VoterAddResponse,
+    type VoterRemoveResponse as VoterRemoveResponse,
+    type VoterListParams as VoterListParams,
+    type VoterAddParams as VoterAddParams,
+    type VoterRemoveParams as VoterRemoveParams,
+  };
+}

package/src/resources/posts.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './posts/index';