// 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 { Cursor, type CursorParams, PagePromise } from '../core/pagination';
import { RequestOptions } from '../internal/request-options';

export class Projects extends APIResource {
  /**
   * List all projects accessible to the current authentication.
   *
   * The projects returned depend on the authentication method:
   *
   * - **API Key**: Returns only the project associated with the API key
   * - **Organization-scoped PAT**: Returns all projects in that organization
   * - **Full-access PAT**: Returns all projects across all organizations the user is
   *   a member of
   *
   * Each project includes its organization information for easy grouping and
   * display.
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const project of client.projects.list()) {
   *   // ...
   * }
   * ```
   */
  list(
    query: ProjectListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<ProjectsCursor, Project> {
    return this._client.getAPIList('/projects', Cursor<Project>, { query, ...options });
  }

  /**
   * Returns the project associated with the API key or X-Project header.
   *
   * The project contains metadata about your organization's configuration,
   * including:
   *
   * - Project ID and organization ID
   * - Project name and slug
   * - Organization details
   * - Creation and update timestamps
   *
   * This endpoint is useful for verifying your API key is valid and retrieving
   * project details.
   *
   * @example
   * ```ts
   * const project = await client.projects.retrieveCurrent();
   * ```
   */
  retrieveCurrent(options?: RequestOptions): APIPromise<Project> {
    return this._client.get('/projects/current', options);
  }
}

export type ProjectsCursor = Cursor<Project>;

export interface Project {
  /**
   * Unique identifier for the project
   */
  id: string;

  /**
   * ISO 8601 timestamp when the project was created
   */
  createdAt: string;

  /**
   * Human-readable name of the project
   */
  name: string;

  /**
   * Organization that owns this project
   */
  organization: Project.Organization;

  /**
   * ID of the organization that owns this project
   */
  organizationId: string;

  /**
   * URL-friendly identifier for the project
   */
  slug: string;

  /**
   * ISO 8601 timestamp when the project was last updated
   */
  updatedAt: string;
}

export namespace Project {
  /**
   * Organization that owns this project
   */
  export interface Organization {
    /**
     * Unique identifier for the organization
     */
    id: string;

    /**
     * Human-readable name of the organization
     */
    name: string;

    /**
     * URL-friendly identifier for the organization
     */
    slug: string;
  }
}

export interface ProjectListParams extends CursorParams {}

export declare namespace Projects {
  export {
    type Project as Project,
    type ProjectsCursor as ProjectsCursor,
    type ProjectListParams as ProjectListParams,
  };
}