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

import { APIResource } from '../core/resource';
import * as BusinessPartnersAPI from './business-partners';
import * as JobRequisitionsAPI from './job-requisitions';
import * as WorkLocationsAPI from './work-locations';
import { APIPromise } from '../core/api-promise';
import { PageCursorURL, PagePromise } from '../core/pagination';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';

/**
 * Customer-facing postings associated with job requisitions
 */
export class JobPosts extends APIResource {
  /**
   * List location-specific job posts belonging to non-confidential active job
   * requisitions. Use filter=job_requisition_id eq '...' and filter=published eq
   * true for standard OData filtering. Named job_requisition_id and published
   * parameters remain supported as aliases. The requisition_id parameter is a
   * cross-resource lookup of the parent requisition's customer-defined identifier
   * and requires job-requisitions.read. Use the returned job post identifier when
   * submitting an application for a specific posting.
   *
   * - Requires: `Internal Testing`
   * - Filterable fields: `job_requisition_id`, `published`
   * - Expandable fields: `job_requisition`, `work_locations`
   * - Sortable fields: `id`, `created_at`, `updated_at`
   *
   * @example HTTP
   * Representative request and response shapes.
   * ```
   * GET /job-posts/?filter=filter&expand=expand&order_by=order_by&job_requisition_id=job_requisition_id&requisition_id=requisition_id&published=true&limit=50&cursor=cursor HTTP/1.1
   * Host: rest.ripplingapis.com
   * Accept: application/json
   * Rippling-Api-Version: 2024-08-01
   *
   * HTTP/1.1 200 OK
   * Content-Type: application/json
   *
   * {
   *   "__meta": {
   *     "redacted_fields": [
   *       {
   *         "name": "date_of_birth",
   *         "reason": "Insufficient entitlements"
   *       }
   *     ]
   *   },
   *   "results": [
   *     {
   *       "id": "string",
   *       "created_at": "string",
   *       "updated_at": "string",
   *       "job_requisition_id": "string",
   *       "job_requisition": {
   *         "id": "string",
   *         "created_at": "string",
   *         "updated_at": "string",
   *         "name": "string",
   *         "status": "OPEN",
   *         "requisition_id": "string"
   *       },
   *       "name": "string",
   *       "published": false,
   *       "locations": [
   *         {}
   *       ],
   *       "work_location_ids": [
   *         "string"
   *       ],
   *       "work_locations": [
   *         {}
   *       ],
   *       "public_url": "string",
   *       "language": "string"
   *     }
   *   ],
   *   "next_link": "string"
   * }
   * ```
   */
  list(
    query: JobPostListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<JobPostListResponsesPageCursorURL, JobPostListResponse> {
    return this._client.getAPIList('/job-posts/', PageCursorURL<JobPostListResponse>, { query, ...options });
  }

  /**
   * Retrieve a job post belonging to a non-confidential active job requisition.
   *
   * @example HTTP
   * Representative request and response shapes.
   * ```
   * GET /job-posts/{id}/?expand=expand HTTP/1.1
   * Host: rest.ripplingapis.com
   * Accept: application/json
   * Rippling-Api-Version: 2024-08-01
   *
   * HTTP/1.1 200 OK
   * Content-Type: application/json
   *
   * {
   *   "__meta": {
   *     "redacted_fields": [
   *       {}
   *     ]
   *   }
   * }
   * ```
   */
  retrieve(
    id: string,
    query: JobPostRetrieveParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<JobPostRetrieveResponse> {
    return this._client.get(path`/job-posts/${id}/`, { query, ...options });
  }
}

export type JobPostListResponsesPageCursorURL = PageCursorURL<JobPostListResponse>;

export interface JobPostListResponse {
  /**
   * Identifier field
   */
  id: string;

  /**
   * Record creation date
   */
  created_at: string;

  /**
   * Configured and manually entered locations associated with the job post.
   * Configured entries expose only work_location_id; manual entries expose
   * manual_location_id and inline location details.
   */
  locations: Array<JobPostListResponse.Location>;

  /**
   * Job post name
   */
  name: string;

  /**
   * Whether the job post is published
   */
  published: boolean;

  /**
   * Record update date
   */
  updated_at: string;

  /**
   * Parent job requisition; null when not expanded or unavailable. Request
   * expand=job_requisition to include it
   *
   * Expandable field
   */
  job_requisition?: JobRequisitionsAPI.JobRequisition;

  /**
   * Identifier of the parent Job Requisition resource. Applications use the legacy
   * field name job_id for the same resource. Null when the parent Job Requisition
   * reference is unavailable.
   */
  job_requisition_id?: string;

  /**
   * BCP 47 job post language tag; defaults to en-US when not otherwise set
   */
  language?: string;

  /**
   * Public job post URL; null when the post is not published
   */
  public_url?: string;

  /**
   * Canonical Work Location identifiers for the configured subset of locations[].
   * Unlike locations[], this list excludes manually entered locations and supports
   * expand=work_locations. Returns an empty list when there are no configured
   * locations.
   */
  work_location_ids?: Array<string>;

  /**
   * Configured Work Location resources; request expand=work_locations to include
   * them
   *
   * Expandable field
   */
  work_locations?: Array<WorkLocationsAPI.WorkLocation>;
}

export namespace JobPostListResponse {
  export interface Location {
    /**
     * City for a manually entered location; null for a configured Work Location
     * resource
     */
    city?: string;

    /**
     * ISO 3166-1 alpha-2 country code for a manually entered location; null for a
     * configured Work Location resource
     */
    country_code?: string;

    /**
     * Opaque job-post-local identifier for a manually entered location; null for a
     * configured Work Location.
     */
    manual_location_id?: string;

    /**
     * Display name for a manually entered location; null for a configured Work
     * Location resource
     */
    name?: string;

    /**
     * State or region for a manually entered location; null for a configured Work
     * Location resource
     */
    state?: string;

    /**
     * Canonical Work Location resource identifier for a configured location; null for
     * a manually entered location. Request expand=work_locations on the parent job
     * post to retrieve the corresponding Work Location resources.
     */
    work_location_id?: string;

    /**
     * Workplace type for a manually entered location: ON_SITE, REMOTE, or HYBRID.
     * Configured Work Location resources return null.
     */
    workplace_type?: 'ON_SITE' | 'REMOTE' | 'HYBRID';
  }
}

/**
 * Meta information for the response.
 */
export interface JobPostRetrieveResponse extends BusinessPartnersAPI.Meta {
  /**
   * Identifier field
   */
  id: string;

  /**
   * Record creation date
   */
  created_at: string;

  /**
   * Configured and manually entered locations associated with the job post.
   * Configured entries expose only work_location_id; manual entries expose
   * manual_location_id and inline location details.
   */
  locations: Array<JobPostRetrieveResponse.Location>;

  /**
   * Job post name
   */
  name: string;

  /**
   * Whether the job post is published
   */
  published: boolean;

  /**
   * Record update date
   */
  updated_at: string;

  /**
   * Parent job requisition; null when not expanded or unavailable. Request
   * expand=job_requisition to include it
   *
   * Expandable field
   */
  job_requisition?: JobRequisitionsAPI.JobRequisition;

  /**
   * Identifier of the parent Job Requisition resource. Applications use the legacy
   * field name job_id for the same resource. Null when the parent Job Requisition
   * reference is unavailable.
   */
  job_requisition_id?: string;

  /**
   * BCP 47 job post language tag; defaults to en-US when not otherwise set
   */
  language?: string;

  /**
   * Public job post URL; null when the post is not published
   */
  public_url?: string;

  /**
   * Canonical Work Location identifiers for the configured subset of locations[].
   * Unlike locations[], this list excludes manually entered locations and supports
   * expand=work_locations. Returns an empty list when there are no configured
   * locations.
   */
  work_location_ids?: Array<string>;

  /**
   * Configured Work Location resources; request expand=work_locations to include
   * them
   *
   * Expandable field
   */
  work_locations?: Array<WorkLocationsAPI.WorkLocation>;
}

export namespace JobPostRetrieveResponse {
  export interface Location {
    /**
     * City for a manually entered location; null for a configured Work Location
     * resource
     */
    city?: string;

    /**
     * ISO 3166-1 alpha-2 country code for a manually entered location; null for a
     * configured Work Location resource
     */
    country_code?: string;

    /**
     * Opaque job-post-local identifier for a manually entered location; null for a
     * configured Work Location.
     */
    manual_location_id?: string;

    /**
     * Display name for a manually entered location; null for a configured Work
     * Location resource
     */
    name?: string;

    /**
     * State or region for a manually entered location; null for a configured Work
     * Location resource
     */
    state?: string;

    /**
     * Canonical Work Location resource identifier for a configured location; null for
     * a manually entered location. Request expand=work_locations on the parent job
     * post to retrieve the corresponding Work Location resources.
     */
    work_location_id?: string;

    /**
     * Workplace type for a manually entered location: ON_SITE, REMOTE, or HYBRID.
     * Configured Work Location resources return null.
     */
    workplace_type?: 'ON_SITE' | 'REMOTE' | 'HYBRID';
  }
}

export interface JobPostListParams {
  cursor?: string;

  expand?: string;

  filter?: string;

  /**
   * Return job posts for this Rippling job requisition identifier.
   */
  job_requisition_id?: string;

  /**
   * The maximum number of results to return. Defaults to 50. Maximum is 100.
   */
  limit?: number;

  order_by?: string;

  /**
   * Filter job posts by external job board publication state. When omitted, returns
   * both published and unpublished posts.
   */
  published?: boolean;

  /**
   * Return job posts for this customer-defined requisition identifier. Requires the
   * job-requisitions.read scope.
   */
  requisition_id?: string;
}

export interface JobPostRetrieveParams {
  expand?: string;
}

export declare namespace JobPosts {
  export {
    type JobPostListResponse as JobPostListResponse,
    type JobPostRetrieveResponse as JobPostRetrieveResponse,
    type JobPostListResponsesPageCursorURL as JobPostListResponsesPageCursorURL,
    type JobPostListParams as JobPostListParams,
    type JobPostRetrieveParams as JobPostRetrieveParams,
  };
}