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

import { APIResource } from '../../core/resource';
import * as CompletionsAPI from '../chat/completions';
import { APIPromise } from '../../core/api-promise';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

export class Criteria extends APIResource {
  /**
   * Add a single criterion to an existing rubric.
   *
   * Creates a new criterion at version 1 under the given rubric. Criteria are
   * versioned independently of the rubric they belong to. The request is rejected if
   * the target rubric is archived.
   */
  create(
    rubricID: string,
    body: CriterionCreateParams,
    options?: RequestOptions,
  ): APIPromise<RubricCriteriaResponse> {
    return this._client.post(path`/v5/rubrics/${rubricID}/criteria`, { body, ...options });
  }

  /**
   * Apply a partial update to a criterion, creating a new version.
   *
   * Updates are append-only: rather than overwriting the criterion in place, each
   * update inserts a new immutable version with an incremented version number, so
   * every prior state stays available through the versions endpoint. Fields not
   * supplied are carried forward from the current version. The request is rejected
   * if the criterion does not belong to the rubric named in the path.
   */
  update(
    rubricCriteriaID: string,
    params: CriterionUpdateParams,
    options?: RequestOptions,
  ): APIPromise<RubricCriteriaResponse> {
    const { rubric_id, ...body } = params;
    return this._client.patch(path`/v5/rubrics/${rubric_id}/criteria/${rubricCriteriaID}`, {
      body,
      ...options,
    });
  }

  /**
   * List the full version history of a single criterion, paginated.
   *
   * Because criterion updates are append-only, this returns one entry per version,
   * exposing every prior state of the criterion, ordered by version descending
   * (newest first) by default. The request is rejected if the criterion does not
   * belong to the rubric named in the path.
   */
  listVersions(
    rubricCriteriaID: string,
    params: CriterionListVersionsParams,
    options?: RequestOptions,
  ): APIPromise<CriterionListVersionsResponse> {
    const { rubric_id, ...query } = params;
    return this._client.get(path`/v5/rubrics/${rubric_id}/criteria/${rubricCriteriaID}/versions`, {
      query,
      ...options,
    });
  }
}

export interface RubricCriteriaInput {
  /**
   * The Criteria text
   */
  title: string;

  /**
   * Free-form metadata for the Criteria
   */
  annotations?: { [key: string]: unknown };

  /**
   * Weight multiplier for scoring
   */
  weight?: number;
}

export interface RubricCriteriaResponse {
  id: string;

  created_at: string;

  rubric_id: string;

  title: string;

  version: number;

  annotations?: { [key: string]: unknown };

  object?: 'rubric_criteria';

  weight?: number;
}

/**
 * Slim criteria projection for list endpoints (title + weight only).
 */
export interface RubricCriteriaSummaryResponse {
  title: string;

  weight?: number;
}

export interface CriterionListVersionsResponse {
  /**
   * Whether there are more items left to be fetched.
   */
  has_more: boolean;

  items: Array<RubricCriteriaResponse>;

  /**
   * The total of items that match the query. This is greater than or equal to the
   * number of items returned.
   */
  total: number;

  /**
   * The maximum number of items to return.
   */
  limit?: number;

  object?: 'list';
}

export interface CriterionCreateParams {
  /**
   * The Criteria text
   */
  title: string;

  /**
   * Free-form metadata for the Criteria
   */
  annotations?: { [key: string]: unknown };

  /**
   * Weight multiplier for scoring
   */
  weight?: number;
}

export interface CriterionUpdateParams {
  /**
   * Path param
   */
  rubric_id: string;

  /**
   * Body param: Free-form metadata for the Criteria
   */
  annotations?: { [key: string]: unknown };

  /**
   * Body param: The Criteria text
   */
  title?: string;

  /**
   * Body param: Weight multiplier for scoring
   */
  weight?: number;
}

export interface CriterionListVersionsParams {
  /**
   * Path param
   */
  rubric_id: string;

  /**
   * Query param
   */
  ending_before?: string;

  /**
   * Query param
   */
  limit?: number;

  /**
   * Query param
   */
  sort_by?: string;

  /**
   * Query param
   */
  sort_order?: CompletionsAPI.SortOrder;

  /**
   * Query param
   */
  starting_after?: string;
}

export declare namespace Criteria {
  export {
    type RubricCriteriaInput as RubricCriteriaInput,
    type RubricCriteriaResponse as RubricCriteriaResponse,
    type RubricCriteriaSummaryResponse as RubricCriteriaSummaryResponse,
    type CriterionListVersionsResponse as CriterionListVersionsResponse,
    type CriterionCreateParams as CriterionCreateParams,
    type CriterionUpdateParams as CriterionUpdateParams,
    type CriterionListVersionsParams as CriterionListVersionsParams,
  };
}