featurebase-node 0.0.2

package/src/resources/surveys.ts

@@ -0,0 +1,576 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as SurveysAPI from './surveys';
+import * as ContactsAPI from './contacts/contacts';
+import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Surveys allow you to collect targeted feedback from your users within your product. Surveys can be targeted to specific user segments or pages and can contain multiple questions with conditional logic.
+ */
+export class Surveys extends APIResource {
+  /**
+   * Retrieves a single survey by its unique identifier.
+   *
+   * Returns the survey object if found in your organization.
+   *
+   * ### Response
+   *
+   * Returns a survey object with:
+   *
+   * - `id` - Unique identifier
+   * - `title` - Survey title
+   * - `description` - Survey description
+   * - `isActive` - Whether the survey is active
+   * - `responseCount` - Number of responses received
+   * - `targeting` - Targeting configuration
+   * - `pages` - Array of survey pages/questions
+   * - `createdAt` - ISO 8601 timestamp when created
+   * - `updatedAt` - ISO 8601 timestamp when last updated
+   *
+   * ### Survey Pages
+   *
+   * Each page represents a question or screen in the survey:
+   *
+   * - `type` - Page type (text, link, rating, multiple-choice)
+   * - `title` - Question title
+   * - `description` - Optional description
+   * - `logic` - Conditional logic rules
+   * - `defaultAction` - Default action when no logic matches
+   *
+   * ### Errors
+   *
+   * - `404` - Survey not found in your organization
+   */
+  retrieve(
+    id: string,
+    params: SurveyRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Survey> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.get(path`/v2/surveys/${id}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Returns all surveys configured in your Featurebase organization.
+   *
+   * ### Query Parameters
+   *
+   * - `limit` - Number of items to return (1-100, default 10)
+   * - `cursor` - Cursor for pagination
+   * - `type` - Filter by survey page type (text, link, rating, multiple-choice)
+   * - `isActive` - Filter by active status
+   *
+   * ### Response Format
+   *
+   * Returns a list object with:
+   *
+   * - `object` - Always "list"
+   * - `data` - Array of survey objects
+   * - `nextCursor` - Cursor for next page (null if no more results)
+   *
+   * ### Survey Object
+   *
+   * Each survey includes:
+   *
+   * - `id` - Unique identifier
+   * - `title` - Survey title
+   * - `description` - Survey description
+   * - `isActive` - Whether the survey is active
+   * - `responseCount` - Number of responses received
+   * - `targeting` - Targeting configuration (segments, URLs, CSS selectors)
+   * - `pages` - Array of survey pages/questions
+   * - `createdAt` - ISO 8601 timestamp when created
+   * - `updatedAt` - ISO 8601 timestamp when last updated
+   */
+  list(
+    params: SurveyListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<SurveyListResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+    return this._client.get('/v2/surveys', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Retrieves all user responses for a specific survey.
+   *
+   * ### Query Parameters
+   *
+   * - `pageId` - Filter responses to a specific survey page
+   * - `limit` - Number of items to return (1-100, default 10)
+   * - `cursor` - Cursor for pagination
+   *
+   * ### Response Format
+   *
+   * Returns a list object with:
+   *
+   * - `object` - Always "list"
+   * - `data` - Array of survey response objects
+   * - `nextCursor` - Cursor for next page (null if no more results)
+   *
+   * ### Survey Response Object
+   *
+   * Each response includes:
+   *
+   * - `id` - Unique response identifier
+   * - `user` - User who submitted the response (may be null for anonymous)
+   * - `responses` - Array of individual answers
+   * - `createdAt` - ISO 8601 timestamp when submitted
+   *
+   * ### Individual Response
+   *
+   * Each item in the responses array:
+   *
+   * - `pageId` - The survey page this response is for
+   * - `type` - Response type (text, rating, multiple-choice)
+   * - `value` - The response value
+   *
+   * ### Errors
+   *
+   * - `404` - Survey not found in your organization
+   */
+  retrieveResponses(
+    id: string,
+    params: SurveyRetrieveResponsesParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<SurveyRetrieveResponsesResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+    return this._client.get(path`/v2/surveys/${id}/responses`, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        { ...(featurebaseVersion != null ? { 'Featurebase-Version': featurebaseVersion } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface Survey {
+  /**
+   * Unique identifier
+   */
+  id: string;
+
+  /**
+   * ISO 8601 timestamp when created
+   */
+  createdAt: string;
+
+  /**
+   * Whether the survey is active
+   */
+  isActive: boolean;
+
+  /**
+   * Object type identifier
+   */
+  object: 'survey';
+
+  /**
+   * Organization ID
+   */
+  organization: string;
+
+  /**
+   * Survey pages
+   */
+  pages: Array<Survey.Page>;
+
+  /**
+   * Number of responses
+   */
+  responseCount: number;
+
+  /**
+   * Survey title
+   */
+  title: string;
+
+  /**
+   * ISO 8601 timestamp when last updated
+   */
+  updatedAt: string;
+
+  /**
+   * Survey description
+   */
+  description?: string;
+
+  /**
+   * Targeting configuration
+   */
+  targeting?: Survey.Targeting;
+}
+
+export namespace Survey {
+  export interface Page {
+    /**
+     * Page ID
+     */
+    id: string;
+
+    /**
+     * Page title
+     */
+    title: string;
+
+    /**
+     * Page type
+     */
+    type: 'text' | 'link' | 'rating' | 'multiple-choice';
+
+    /**
+     * Allow multiple selections
+     */
+    allowSelectMultiple?: boolean;
+
+    /**
+     * Available choices
+     */
+    choices?: Array<Page.Choice>;
+
+    /**
+     * Action to take if condition matches
+     */
+    defaultAction?: SurveysAPI.SurveyNextAction;
+
+    /**
+     * Page description
+     */
+    description?: string;
+
+    /**
+     * Label for high rating
+     */
+    highLabel?: string;
+
+    /**
+     * Button text for link
+     */
+    linkButtonText?: string;
+
+    /**
+     * URL to redirect to
+     */
+    linkRedirectUrl?: string;
+
+    /**
+     * Link target
+     */
+    linkTarget?: '_blank' | '_self' | '_parent' | '_top';
+
+    /**
+     * Conditional logic rules
+     */
+    logic?: Array<Page.Logic>;
+
+    /**
+     * Label for low rating
+     */
+    lowLabel?: string;
+
+    /**
+     * Placeholder for text input
+     */
+    placeholder?: string;
+
+    /**
+     * Rating scale
+     */
+    scale?: number;
+
+    /**
+     * Sub-type for rating/multiple-choice
+     */
+    subType?: 'number' | 'emoji' | 'generic' | 'featurebase-posts' | 'nps';
+  }
+
+  export namespace Page {
+    export interface Choice {
+      /**
+       * Choice ID
+       */
+      id: string;
+
+      /**
+       * Choice text
+       */
+      choice?: string;
+    }
+
+    export interface Logic {
+      /**
+       * Comparison operator
+       */
+      comparator: string;
+
+      /**
+       * Action to take if condition matches
+       */
+      next: SurveysAPI.SurveyNextAction;
+
+      /**
+       * Value to compare against
+       */
+      value: string | number | Array<string>;
+
+      /**
+       * Logic rule ID
+       */
+      id?: string;
+    }
+  }
+
+  /**
+   * Targeting configuration
+   */
+  export interface Targeting {
+    /**
+     * CSS selector targeting rules
+     */
+    css?: Array<Targeting.Css>;
+
+    /**
+     * Whether login is required
+     */
+    loginRequired?: boolean;
+
+    /**
+     * Segment IDs to target
+     */
+    segmentIds?: Array<string>;
+
+    /**
+     * URL targeting rules
+     */
+    url?: Array<Targeting.URL>;
+  }
+
+  export namespace Targeting {
+    export interface Css {
+      /**
+       * CSS selector
+       */
+      value: string;
+    }
+
+    export interface URL {
+      /**
+       * Type of URL matching
+       */
+      matchType: 'exact' | 'contains' | 'regex';
+
+      /**
+       * URL pattern to match
+       */
+      value: string;
+
+      /**
+       * Rule ID
+       */
+      id?: string;
+    }
+  }
+}
+
+/**
+ * Action to take if condition matches
+ */
+export interface SurveyNextAction {
+  /**
+   * Type of next action
+   */
+  type: 'page' | 'end' | 'next';
+
+  /**
+   * Page ID to navigate to
+   */
+  pageId?: string;
+}
+
+export interface SurveyListResponse {
+  /**
+   * Array of surveys
+   */
+  data: Array<Survey>;
+
+  /**
+   * Cursor for fetching the next page (cursor-based pagination)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+}
+
+export interface SurveyRetrieveResponsesResponse {
+  /**
+   * Array of survey responses
+   */
+  data: Array<SurveyRetrieveResponsesResponse.Data>;
+
+  /**
+   * Cursor for fetching the next page (cursor-based pagination)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Object type identifier
+   */
+  object: 'list';
+}
+
+export namespace SurveyRetrieveResponsesResponse {
+  export interface Data {
+    /**
+     * Unique identifier
+     */
+    id: string;
+
+    /**
+     * ISO 8601 timestamp when created
+     */
+    createdAt: string;
+
+    /**
+     * Object type identifier
+     */
+    object: 'survey_response';
+
+    /**
+     * Individual responses to questions
+     */
+    responses: Array<Data.Response>;
+
+    /**
+     * User who submitted the response
+     */
+    user: ContactsAPI.Contact | null;
+  }
+
+  export namespace Data {
+    export interface Response {
+      /**
+       * Page ID this response is for
+       */
+      pageId: string;
+
+      /**
+       * Response type
+       */
+      type: 'text' | 'link' | 'rating' | 'multiple-choice';
+
+      /**
+       * Response value
+       */
+      value: string | number | boolean | Array<string>;
+
+      /**
+       * Response ID
+       */
+      id?: string;
+
+      /**
+       * ISO 8601 timestamp when created
+       */
+      createdAt?: string;
+
+      /**
+       * ISO 8601 timestamp when updated
+       */
+      updatedAt?: string;
+    }
+  }
+}
+
+export interface SurveyRetrieveParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface SurveyListParams {
+  /**
+   * Query param: An opaque cursor for pagination. Use the nextCursor value from a
+   * previous response to fetch the next page.
+   */
+  cursor?: string;
+
+  /**
+   * Query param: Filter by active status
+   */
+  isActive?: boolean | null;
+
+  /**
+   * Query param: A limit on the number of objects to be returned, between 1 and 100.
+   */
+  limit?: number;
+
+  /**
+   * Query param: Filter by survey page type
+   */
+  type?: 'text' | 'link' | 'rating' | 'multiple-choice';
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: string;
+}
+
+export interface SurveyRetrieveResponsesParams {
+  /**
+   * Query param: An opaque cursor for pagination. Use the nextCursor value from a
+   * previous response to fetch the next page.
+   */
+  cursor?: string;
+
+  /**
+   * Query param: A limit on the number of objects to be returned, between 1 and 100.
+   */
+  limit?: number;
+
+  /**
+   * Query param: Filter by survey page ID
+   */
+  pageId?: 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 Surveys {
+  export {
+    type Survey as Survey,
+    type SurveyNextAction as SurveyNextAction,
+    type SurveyListResponse as SurveyListResponse,
+    type SurveyRetrieveResponsesResponse as SurveyRetrieveResponsesResponse,
+    type SurveyRetrieveParams as SurveyRetrieveParams,
+    type SurveyListParams as SurveyListParams,
+    type SurveyRetrieveResponsesParams as SurveyRetrieveResponsesParams,
+  };
+}