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

import { APIResource } from '../core/resource';
import { APIPromise } from '../core/api-promise';
import { APIListPage, PagePromise } from '../core/pagination';
import { buildHeaders } from '../internal/headers';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';

export class SpanAssessments extends APIResource {
  /**
   * Attach a new assessment to a span within a trace.
   *
   * A span assessment records feedback on a single span's output. Its
   * assessment_type selects one of comment, rating (an integer 1-5), approval
   * (approved or rejected), rubric (key-value rule pairs), metadata (arbitrary
   * JSON), or overwrite (a corrected span output), and exactly the content field
   * matching that type must be supplied; a free-text comment may additionally
   * accompany any type. trace_id is required, while span_id is optional and, when
   * omitted, the assessment is attached to the trace's root span. The call returns
   * 404 if the given span_id and trace_id do not identify an existing span, or if no
   * root span is found for the trace. Creating an overwrite for a span that already
   * holds a live overwrite returns 409, whether that overwrite is yours or another
   * user's. Update or delete the existing one instead. Use the list endpoint to read
   * a span's or trace's existing assessments.
   */
  create(body: SpanAssessmentCreateParams, options?: RequestOptions): APIPromise<SpanAssessment> {
    return this._client.post('/v5/span-assessments', { body, ...options });
  }

  /**
   * Retrieve a single span assessment by its identifier.
   *
   * Returns the assessment's type and content fields, the span and trace it is
   * attached to, and the identity that created it. Returns 404 if no assessment with
   * that id exists for the caller's account. Use the list endpoint instead when you
   * have a span or trace id rather than an assessment id.
   *
   * `x-project-id` answers 404 for an assessment on a trace outside that project,
   * when `PROJECT_SCOPED_SPAN_LISTING` is on for the account.
   */
  retrieve(
    spanAssessmentID: string,
    params: SpanAssessmentRetrieveParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<SpanAssessment> {
    const { 'x-project-id': xProjectID } = params ?? {};
    return this._client.get(path`/v5/span-assessments/${spanAssessmentID}`, {
      ...options,
      headers: buildHeaders([
        { ...(xProjectID != null ? { 'x-project-id': xProjectID } : undefined) },
        options?.headers,
      ]),
    });
  }

  /**
   * Update the content of an existing span assessment.
   *
   * Only the assessment's original creator, or an account admin or manager, may
   * update it; a request from any other identity returns 403. Supplied fields
   * overwrite the stored values and the merged result is re-validated against the
   * assessment's type, so the content must stay consistent with assessment_type (the
   * matching content field present and no conflicting fields set) or the call
   * returns 422. The span and trace an assessment is attached to cannot be changed
   * through this endpoint. Returns 404 if no assessment with that id exists for the
   * caller's account.
   */
  update(
    spanAssessmentID: string,
    body: SpanAssessmentUpdateParams,
    options?: RequestOptions,
  ): APIPromise<SpanAssessment> {
    return this._client.patch(path`/v5/span-assessments/${spanAssessmentID}`, { body, ...options });
  }

  /**
   * Return the assessments attached to a given span or trace.
   *
   * Results are scoped to the caller's account. Exactly one of span_id or trace_id
   * must be supplied as a query parameter, and a request providing neither
   * returns 400. Filtering by trace_id returns assessments across every span of that
   * trace, whereas span_id returns only that span's assessments; an optional
   * assessment_type narrows the results to a single type. Use the get-by-id endpoint
   * when you already have a specific assessment id.
   *
   * `x-project-id` narrows the result to assessments on traces whose root span
   * carries that project, when `PROJECT_SCOPED_SPAN_LISTING` is on for the account.
   */
  list(
    params: SpanAssessmentListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<SpanAssessmentsAPIListPage, SpanAssessment> {
    const { 'x-project-id': xProjectID, ...query } = params ?? {};
    return this._client.getAPIList('/v5/span-assessments', APIListPage<SpanAssessment>, {
      query,
      ...options,
      headers: buildHeaders([
        { ...(xProjectID != null ? { 'x-project-id': xProjectID } : undefined) },
        options?.headers,
      ]),
    });
  }

  /**
   * Permanently delete a span assessment by its identifier.
   *
   * Only the assessment's original creator, or an account admin or manager, may
   * delete it; a request from any other identity returns 403. This is a hard delete:
   * the assessment row is removed rather than archived, so it cannot be restored
   * afterward. The response echoes the deleted assessment's id. Returns 404 if no
   * assessment with that id exists for the caller's account.
   */
  delete(spanAssessmentID: string, options?: RequestOptions): APIPromise<SpanAssessmentDeleteResponse> {
    return this._client.delete(path`/v5/span-assessments/${spanAssessmentID}`, options);
  }
}

export type SpanAssessmentsAPIListPage = APIListPage<SpanAssessment>;

/**
 * Status options for approval assessments
 */
export type ApprovalStatus = 'approved' | 'rejected';

/**
 * Types of assessments that can be provided
 */
export type AssessmentType = 'comment' | 'rating' | 'approval' | 'rubric' | 'metadata' | 'overwrite';

/**
 * Response model for span assessment
 */
export interface SpanAssessment {
  /**
   * Unique identifier for the assessment
   */
  assessment_id: string;

  /**
   * Type of assessment
   */
  assessment_type: AssessmentType;

  /**
   * User who submitted the assessment
   */
  created_by: string;

  /**
   * The span this assessment is attached to
   */
  span_id: string;

  /**
   * The trace this assessment is attached to
   */
  trace_id: string;

  /**
   * Account this assessment belongs to
   */
  account_id?: string;

  /**
   * Approval status (approved/rejected)
   */
  approval?: ApprovalStatus;

  /**
   * Raw text feedback
   */
  comment?: string;

  /**
   * When this assessment was created
   */
  created_at?: string;

  /**
   * Arbitrary JSON object for additional data
   */
  metadata?: { [key: string]: unknown };

  object?: 'span.assessment';

  /**
   * User corrections to span output
   */
  overwrite?: { [key: string]: unknown };

  /**
   * Numerical rating (1-5)
   */
  rating?: number;

  /**
   * Rule key-value pairs for rubric evaluation
   */
  rubric?: { [key: string]: string };

  /**
   * When this assessment was last updated
   */
  updated_at?: string;

  [k: string]: unknown;
}

export interface SpanAssessmentDeleteResponse {
  id: string;

  deleted: boolean;

  object?: 'span.assessment';
}

export interface SpanAssessmentCreateParams {
  /**
   * Type of assessment
   */
  assessment_type: AssessmentType;

  /**
   * The ID of the trace this assessment is attached to
   */
  trace_id: string;

  /**
   * Approval status (approved/rejected)
   */
  approval?: ApprovalStatus;

  /**
   * Raw text feedback
   */
  comment?: string;

  /**
   * Arbitrary JSON object for additional data
   */
  metadata?: { [key: string]: unknown };

  /**
   * User corrections to span output
   */
  overwrite?: { [key: string]: unknown };

  /**
   * Numerical rating (1-5)
   */
  rating?: number;

  /**
   * Rule key-value pairs for rubric evaluation
   */
  rubric?: { [key: string]: string };

  /**
   * The ID of the span this assessment is attached to. If omitted, the assessment is
   * attached to the root span of the trace.
   */
  span_id?: string;
}

export interface SpanAssessmentRetrieveParams {
  'x-project-id'?: string;
}

export interface SpanAssessmentUpdateParams {
  /**
   * Approval status (approved/rejected)
   */
  approval?: ApprovalStatus;

  /**
   * Type of assessment
   */
  assessment_type?: AssessmentType;

  /**
   * Raw text feedback
   */
  comment?: string;

  /**
   * Arbitrary JSON object for additional data
   */
  metadata?: { [key: string]: unknown };

  /**
   * User corrections to span output
   */
  overwrite?: { [key: string]: unknown };

  /**
   * Numerical rating (1-5)
   */
  rating?: number;

  /**
   * Rule key-value pairs for rubric evaluation
   */
  rubric?: { [key: string]: string };
}

export interface SpanAssessmentListParams {
  /**
   * Query param: Filter by assessment type
   */
  assessment_type?: AssessmentType;

  /**
   * Query param: Filter by span ID. Either span_id or trace_id must be provided as a
   * query parameter.
   */
  span_id?: string;

  /**
   * Query param: Filter by trace ID. Either span_id or trace_id must be provided as
   * a query parameter.
   */
  trace_id?: string;

  /**
   * Header param
   */
  'x-project-id'?: string;
}

export declare namespace SpanAssessments {
  export {
    type ApprovalStatus as ApprovalStatus,
    type AssessmentType as AssessmentType,
    type SpanAssessment as SpanAssessment,
    type SpanAssessmentDeleteResponse as SpanAssessmentDeleteResponse,
    type SpanAssessmentsAPIListPage as SpanAssessmentsAPIListPage,
    type SpanAssessmentCreateParams as SpanAssessmentCreateParams,
    type SpanAssessmentRetrieveParams as SpanAssessmentRetrieveParams,
    type SpanAssessmentUpdateParams as SpanAssessmentUpdateParams,
    type SpanAssessmentListParams as SpanAssessmentListParams,
  };
}