// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../core/resource';
import * as QuestionsAPI from './questions';
import * as Shared from './shared';
import * as CompletionsAPI from './chat/completions';
import { APIPromise } from '../core/api-promise';
import { CursorPage, type CursorPageParams, PagePromise } from '../core/pagination';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';

export class Questions extends APIResource {
  /**
   * Create a new question owned by the caller's account.
   *
   * The question is one of six types selected by the required `question_type`
   * discriminator (categorical, rating, number, free_text, form, or timestamp), and
   * each type carries its own `configuration` block; `name` and `prompt` are
   * required for every type. Questions are the reusable units that are grouped into
   * question sets and referenced by rubrics, so create them before assembling a
   * question set. The created question is scoped to the caller's account and records
   * the creating identity. The question type and its configuration are set at
   * creation time and cannot be changed afterward through the update endpoint.
   */
  create(params: QuestionCreateParams, options?: RequestOptions): APIPromise<Question> {
    const { question } = params;
    return this._client.post('/v5/questions', { body: question, ...options });
  }

  /**
   * Retrieve a single question in the caller's account by its ID.
   *
   * Both active and archived questions are returned; the archived state is conveyed
   * by the `archived_at` field on the response. The lookup is scoped to the caller's
   * account, and a question that does not exist within that account results in a
   * not-found error.
   */
  retrieve(questionID: string, options?: RequestOptions): APIPromise<Question> {
    return this._client.get(path`/v5/questions/${questionID}`, options);
  }

  /**
   * Update a question's display name.
   *
   * Only the `name` is mutable through this endpoint; a question's type, prompt, and
   * type-specific configuration are fixed at creation and cannot be changed here.
   * Updating an archived question is rejected with a client error, so restore it
   * first if it needs to be edited. The update is scoped to the caller's account.
   */
  update(questionID: string, body: QuestionUpdateParams, options?: RequestOptions): APIPromise<Question> {
    return this._client.patch(path`/v5/questions/${questionID}`, { body, ...options });
  }

  /**
   * Return a paginated list of the caller's account's questions.
   *
   * Archived questions are excluded by default; set `include_archived` to true to
   * include them alongside active ones. Pass `ids` to restrict the result to a
   * specific set of question IDs. Results are paginated through the standard
   * pagination parameters. Use this to discover existing questions before adding
   * them to a question set, or to audit which questions have been archived.
   */
  list(
    query: QuestionListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<QuestionsCursorPage, Question> {
    return this._client.getAPIList('/v5/questions', CursorPage<Question>, { query, ...options });
  }

  /**
   * Soft-delete a question by setting its `archived_at` timestamp.
   *
   * This is not a permanent delete: the row is retained and can be brought back with
   * the restore endpoint. Once archived, the question is excluded from list results
   * by default (unless `include_archived` is set) and can no longer be updated until
   * it is restored. The archived question is returned in the response with its
   * `archived_at` populated.
   */
  archive(questionID: string, options?: RequestOptions): APIPromise<Question> {
    return this._client.delete(path`/v5/questions/${questionID}`, options);
  }

  /**
   * Restore a previously archived question, reversing an archive.
   *
   * This clears the question's `archived_at` timestamp, returning it to the active
   * state so it reappears in default listings and becomes editable again. It is the
   * inverse of the archive (DELETE) operation and is intended for questions that
   * were archived by mistake or are needed again.
   */
  restore(questionID: string, options?: RequestOptions): APIPromise<Question> {
    return this._client.post(path`/v5/questions/${questionID}/restore`, options);
  }
}

export type QuestionsCursorPage = CursorPage<Question>;

export interface CategoricalQuestion {
  /**
   * Unique identifier of the entity
   */
  id: string;

  configuration: CategoricalQuestionConfiguration;

  /**
   * ISO-timestamp when the entity was created
   */
  created_at: string;

  /**
   * The identity that created the entity.
   */
  created_by: Shared.Identity;

  name: string;

  /**
   * user-facing question prompt
   */
  prompt: string;

  /**
   * ISO-timestamp when the entity was archived
   */
  archived_at?: string;

  /**
   * Conditions for the question to be shown
   */
  conditions?: Array<{ [key: string]: unknown }>;

  object?: 'question';

  question_type?: 'categorical';
}

export interface CategoricalQuestionConfiguration {
  /**
   * Categorical answer choices (must contain at least one entry)
   */
  choices: Array<string>;

  /**
   * Whether the question is displayed as a dropdown in the UI.
   */
  dropdown?: boolean;

  /**
   * Whether the question allows multiple answers.
   */
  multi?: boolean;
}

export interface FormQuestion {
  /**
   * Unique identifier of the entity
   */
  id: string;

  configuration: FormQuestionConfiguration;

  /**
   * ISO-timestamp when the entity was created
   */
  created_at: string;

  /**
   * The identity that created the entity.
   */
  created_by: Shared.Identity;

  name: string;

  /**
   * user-facing question prompt
   */
  prompt: string;

  /**
   * ISO-timestamp when the entity was archived
   */
  archived_at?: string;

  /**
   * Conditions for the question to be shown
   */
  conditions?: Array<{ [key: string]: unknown }>;

  object?: 'question';

  question_type?: 'form';
}

export interface FormQuestionConfiguration {
  /**
   * The JSON schema of the desired form object
   */
  form_schema: { [key: string]: unknown };
}

export interface FreeTextQuestion {
  /**
   * Unique identifier of the entity
   */
  id: string;

  /**
   * ISO-timestamp when the entity was created
   */
  created_at: string;

  /**
   * The identity that created the entity.
   */
  created_by: Shared.Identity;

  name: string;

  /**
   * user-facing question prompt
   */
  prompt: string;

  /**
   * ISO-timestamp when the entity was archived
   */
  archived_at?: string;

  /**
   * Conditions for the question to be shown
   */
  conditions?: Array<{ [key: string]: unknown }>;

  configuration?: FreeTextQuestionConfiguration;

  object?: 'question';

  question_type?: 'free_text';
}

export interface FreeTextQuestionConfiguration {
  /**
   * Maximum characters allowed
   */
  max_length?: number;

  /**
   * Minimum characters required
   */
  min_length?: number;
}

export interface NumberQuestion {
  /**
   * Unique identifier of the entity
   */
  id: string;

  /**
   * ISO-timestamp when the entity was created
   */
  created_at: string;

  /**
   * The identity that created the entity.
   */
  created_by: Shared.Identity;

  name: string;

  /**
   * user-facing question prompt
   */
  prompt: string;

  /**
   * ISO-timestamp when the entity was archived
   */
  archived_at?: string;

  /**
   * Conditions for the question to be shown
   */
  conditions?: Array<{ [key: string]: unknown }>;

  configuration?: NumberQuestionConfiguration;

  object?: 'question';

  question_type?: 'number';
}

export interface NumberQuestionConfiguration {
  /**
   * Maximum value for the number
   */
  max?: number;

  /**
   * Minimum value for the number
   */
  min?: number;
}

export type Question =
  | CategoricalQuestion
  | RatingQuestion
  | NumberQuestion
  | FreeTextQuestion
  | FormQuestion
  | TimestampQuestion;

export interface RatingQuestion {
  /**
   * Unique identifier of the entity
   */
  id: string;

  configuration: RatingQuestionConfiguration;

  /**
   * ISO-timestamp when the entity was created
   */
  created_at: string;

  /**
   * The identity that created the entity.
   */
  created_by: Shared.Identity;

  name: string;

  /**
   * user-facing question prompt
   */
  prompt: string;

  /**
   * ISO-timestamp when the entity was archived
   */
  archived_at?: string;

  /**
   * Conditions for the question to be shown
   */
  conditions?: Array<{ [key: string]: unknown }>;

  object?: 'question';

  question_type?: 'rating';
}

export interface RatingQuestionConfiguration {
  /**
   * Label shown for the maximum rating
   */
  max_label: string;

  /**
   * Label shown for the minimum rating
   */
  min_label: string;

  /**
   * Number of discrete points on the scale (e.g., 5 for a 1–5 scale)
   */
  steps: number;
}

export interface TimestampQuestion {
  /**
   * Unique identifier of the entity
   */
  id: string;

  /**
   * ISO-timestamp when the entity was created
   */
  created_at: string;

  /**
   * The identity that created the entity.
   */
  created_by: Shared.Identity;

  name: string;

  /**
   * user-facing question prompt
   */
  prompt: string;

  /**
   * ISO-timestamp when the entity was archived
   */
  archived_at?: string;

  /**
   * Conditions for the question to be shown
   */
  conditions?: Array<{ [key: string]: unknown }>;

  configuration?: TimestampQuestionConfiguration;

  object?: 'question';

  question_type?: 'timestamp';
}

export interface TimestampQuestionConfiguration {
  /**
   * Whether to allow multiple timestamps
   */
  multi?: boolean;
}

export interface QuestionCreateParams {
  question:
    | QuestionCreateParams.CategoricalQuestionRequest
    | QuestionCreateParams.RatingQuestionRequest
    | QuestionCreateParams.NumberQuestionRequest
    | QuestionCreateParams.FreeTextQuestionRequest
    | QuestionCreateParams.FormQuestionRequest
    | QuestionCreateParams.TimestampQuestionRequest;
}

export namespace QuestionCreateParams {
  export interface CategoricalQuestionRequest {
    configuration: QuestionsAPI.CategoricalQuestionConfiguration;

    name: string;

    /**
     * user-facing question prompt
     */
    prompt: string;

    /**
     * Conditions for the question to be shown
     */
    conditions?: Array<{ [key: string]: unknown }>;

    question_type?: 'categorical';
  }

  export interface RatingQuestionRequest {
    configuration: QuestionsAPI.RatingQuestionConfiguration;

    name: string;

    /**
     * user-facing question prompt
     */
    prompt: string;

    /**
     * Conditions for the question to be shown
     */
    conditions?: Array<{ [key: string]: unknown }>;

    question_type?: 'rating';
  }

  export interface NumberQuestionRequest {
    name: string;

    /**
     * user-facing question prompt
     */
    prompt: string;

    /**
     * Conditions for the question to be shown
     */
    conditions?: Array<{ [key: string]: unknown }>;

    configuration?: QuestionsAPI.NumberQuestionConfiguration;

    question_type?: 'number';
  }

  export interface FreeTextQuestionRequest {
    name: string;

    /**
     * user-facing question prompt
     */
    prompt: string;

    /**
     * Conditions for the question to be shown
     */
    conditions?: Array<{ [key: string]: unknown }>;

    configuration?: QuestionsAPI.FreeTextQuestionConfiguration;

    question_type?: 'free_text';
  }

  export interface FormQuestionRequest {
    configuration: QuestionsAPI.FormQuestionConfiguration;

    name: string;

    /**
     * user-facing question prompt
     */
    prompt: string;

    /**
     * Conditions for the question to be shown
     */
    conditions?: Array<{ [key: string]: unknown }>;

    question_type?: 'form';
  }

  export interface TimestampQuestionRequest {
    name: string;

    /**
     * user-facing question prompt
     */
    prompt: string;

    /**
     * Conditions for the question to be shown
     */
    conditions?: Array<{ [key: string]: unknown }>;

    configuration?: QuestionsAPI.TimestampQuestionConfiguration;

    question_type?: 'timestamp';
  }
}

export interface QuestionUpdateParams {
  /**
   * Display name for the question
   */
  name: string;
}

export interface QuestionListParams extends CursorPageParams {
  ids?: Array<string>;

  include_archived?: boolean;

  sort_by?: string;

  sort_order?: CompletionsAPI.SortOrder;
}

export declare namespace Questions {
  export {
    type CategoricalQuestion as CategoricalQuestion,
    type CategoricalQuestionConfiguration as CategoricalQuestionConfiguration,
    type FormQuestion as FormQuestion,
    type FormQuestionConfiguration as FormQuestionConfiguration,
    type FreeTextQuestion as FreeTextQuestion,
    type FreeTextQuestionConfiguration as FreeTextQuestionConfiguration,
    type NumberQuestion as NumberQuestion,
    type NumberQuestionConfiguration as NumberQuestionConfiguration,
    type Question as Question,
    type RatingQuestion as RatingQuestion,
    type RatingQuestionConfiguration as RatingQuestionConfiguration,
    type TimestampQuestion as TimestampQuestion,
    type TimestampQuestionConfiguration as TimestampQuestionConfiguration,
    type QuestionsCursorPage as QuestionsCursorPage,
    type QuestionCreateParams as QuestionCreateParams,
    type QuestionUpdateParams as QuestionUpdateParams,
    type QuestionListParams as QuestionListParams,
  };
}