// 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 { RequestOptions } from '../internal/request-options';

/**
 * Documents attached to existing employees
 */
export class EmployeeDocuments extends APIResource {
  /**
   * Create a new employee document
   */
  create(
    body: EmployeeDocumentCreateParams,
    options?: RequestOptions,
  ): APIPromise<EmployeeDocumentCreateResponse> {
    return this._client.post('/employee-documents/', { body, ...options });
  }
}

/**
 * Top-level request body for `POST /employee-documents/`.
 */
export interface EmployeeDocumentCreateResponse {
  /**
   * Identifier field
   */
  id: string;

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

  /**
   * List of role/document items to process. No limit on number of items; total
   * documents across all items must not exceed 250.
   */
  items: Array<EmployeeDocumentCreateResponse.Item>;

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

export namespace EmployeeDocumentCreateResponse {
  /**
   * A single item: attach `documents` to the worker identified by `worker_id`.
   */
  export interface Item {
    /**
     * Documents to attach to the role. At least one required. Each entry references a
     * FileUploadTracker by file_id.
     */
    documents: Array<Item.Document>;

    /**
     * Id of the worker to attach documents to.
     */
    worker_id: string;

    /**
     * Optional destination folder for documents. Accepts either: (1) an ObjectId
     * string for custom folders, or (2) a default folder identifier ('root',
     * 'confidential_documents', 'notices', 'work_authorization'). When omitted,
     * documents land at the root of the worker's profile (current default behavior).
     * When supplied, the folder must exist, be in an active state, be provisioned for
     * the target worker, and the caller must have UPLOAD permission on it — otherwise
     * behavior is governed by `on_invalid_folder`.
     */
    folder_id?: string;

    /**
     * Fallback behavior when `folder_id` is supplied but inaccessible. 'fail'
     * (default) rejects each affected document with FOLDER_ACCESS_ERROR.
     * 'fallback_to_root' uploads to the worker's root profile instead and attaches a
     * FOLDER_ACCESS_FALLBACK warning to each result. Ignored when `folder_id` is
     * omitted.
     */
    on_invalid_folder?: 'fail' | 'fallback_to_root';
  }

  export namespace Item {
    /**
     * A document to attach to a draft hire, referencing a pre-uploaded file.
     */
    export interface Document {
      /**
       * Id of a FileUploadTracker in ACTIVE status whose file should become a document
       * on the hire
       */
      file_id: string;

      /**
       * Document name. Defaults to the uploaded file name when omitted.
       */
      name?: string;

      /**
       * Signature date in YYYY-MM-DD format.
       */
      signature_date?: string;
    }
  }
}

export interface EmployeeDocumentCreateParams {
  /**
   * List of role/document items to process. No limit on number of items; total
   * documents across all items must not exceed 250.
   */
  items: Array<EmployeeDocumentCreateParams.Item>;
}

export namespace EmployeeDocumentCreateParams {
  /**
   * A single item: attach `documents` to the worker identified by `worker_id`.
   */
  export interface Item {
    /**
     * Documents to attach to the role. At least one required. Each entry references a
     * FileUploadTracker by file_id.
     */
    documents: Array<Item.Document>;

    /**
     * Id of the worker to attach documents to.
     */
    worker_id: string;

    /**
     * Optional destination folder for documents. Accepts either: (1) an ObjectId
     * string for custom folders, or (2) a default folder identifier ('root',
     * 'confidential_documents', 'notices', 'work_authorization'). When omitted,
     * documents land at the root of the worker's profile (current default behavior).
     * When supplied, the folder must exist, be in an active state, be provisioned for
     * the target worker, and the caller must have UPLOAD permission on it — otherwise
     * behavior is governed by `on_invalid_folder`.
     */
    folder_id?: string;

    /**
     * Fallback behavior when `folder_id` is supplied but inaccessible. 'fail'
     * (default) rejects each affected document with FOLDER_ACCESS_ERROR.
     * 'fallback_to_root' uploads to the worker's root profile instead and attaches a
     * FOLDER_ACCESS_FALLBACK warning to each result. Ignored when `folder_id` is
     * omitted.
     */
    on_invalid_folder?: 'fail' | 'fallback_to_root';
  }

  export namespace Item {
    /**
     * A document to attach to a draft hire, referencing a pre-uploaded file.
     */
    export interface Document {
      /**
       * Id of a FileUploadTracker in ACTIVE status whose file should become a document
       * on the hire
       */
      file_id: string;

      /**
       * Document name. Defaults to the uploaded file name when omitted.
       */
      name?: string;

      /**
       * Signature date in YYYY-MM-DD format.
       */
      signature_date?: string;
    }
  }
}

export declare namespace EmployeeDocuments {
  export {
    type EmployeeDocumentCreateResponse as EmployeeDocumentCreateResponse,
    type EmployeeDocumentCreateParams as EmployeeDocumentCreateParams,
  };
}