docusign

# NOTE: This file is auto generated by OpenAPI Generator 6.4.0 (https://openapi-generator.tech).
# Do not edit this file manually.

defmodule DocuSign.Api.Folders do
  @moduledoc """
  API calls for all endpoints tagged `Folders`.
  """

  alias DocuSign.Connection
  import DocuSign.RequestBuilder

  @doc """
  Gets information about the specified folder.
  Gets information about the specified folder. To include a list of the items in the folder, set the `include_items` query parameter to **true.**  ### Related topics  - [Searching for envelopes](/docs/esign-rest-api/esign101/concepts/envelopes/search/) - [Sharing templates](/docs/esign-rest-api/esign101/concepts/templates/sharing/)

  ### Parameters

  - `connection` (DocuSign.Connection): Connection to server
  - `account_id` (String.t): The external account number (int) or account ID GUID.
  - `folder_id` (String.t): The ID of the folder.
  - `opts` (keyword): Optional parameters
    - `:from_date` (String.t): Reserved for DocuSign.
    - `:include_items` (String.t): Indicates whether folder items are included in the response. If this parameter is omitted, the default is false.
    - `:owner_email` (String.t): Reserved for DocuSign.
    - `:owner_name` (String.t): Reserved for DocuSign.
    - `:search_text` (String.t): Reserved for DocuSign.
    - `:start_position` (String.t): Reserved for DocuSign.
    - `:status` (String.t): Reserved for DocuSign.
    - `:to_date` (String.t): Reserved for DocuSign.

  ### Returns

  - `{:ok, DocuSign.Model.FolderItemsResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec folders_get_folder_items(Tesla.Env.client(), String.t(), String.t(), keyword()) ::
          {:ok, DocuSign.Model.ErrorDetails.t()}
          | {:ok, DocuSign.Model.FolderItemsResponse.t()}
          | {:error, Tesla.Env.t()}
  def folders_get_folder_items(connection, account_id, folder_id, opts \\ []) do
    optional_params = %{
      :from_date => :query,
      :include_items => :query,
      :owner_email => :query,
      :owner_name => :query,
      :search_text => :query,
      :start_position => :query,
      :status => :query,
      :to_date => :query
    }

    request =
      %{}
      |> method(:get)
      |> url("/v2.1/accounts/#{account_id}/folders/#{folder_id}")
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, %DocuSign.Model.FolderItemsResponse{}},
      {400, %DocuSign.Model.ErrorDetails{}}
    ])
  end

  @doc """
  Gets a list of the folders for the account.
  Retrieves a list of the folders for the account.  Use the `include` query parameter to specify the kinds of folders to return.  By default, only the first level of subfolders is shown. Set the `sub_folder_depth` query parameter to `-1` to return the entire folder hierarchy.   <ds-column>  <ds-step open=\"false\" hideIcon=\"true\">  Default returns only top-level folders.  <div>  `GET 'https://demo.docusign.net/restapi/v2.1/accounts/624e3e00-xxxx-xxxx-xxxx-43918c520dab/folders'`   ```json {   \"resultSetSize\": \"5\",   \"startPosition\": \"0\",   \"endPosition\": \"4\",   \"totalSetSize\": \"5\",   \"folders\": [     {       \"name\": \"Draft\",       \"type\": \"draft\",       \"itemCount\": \"1\",       \"subFolderCount\": \"0\",       \"hasSubFolders\": \"false\"     },     {       \"name\": \"Inbox\",       \"type\": \"inbox\",       \"itemCount\": \"0\",       \"subFolderCount\": \"1\",       \"hasSubFolders\": \"true\",       \"folders\": [         {           \"name\": \"Project Fair\",           \"type\": \"normal\",           \"hasSubFolders\": \"false\",           \"parentFolderId\": \"3ed02ee3-xxxx-xxxx-xxxx-e6795f96a840\",           \"parentFolderUri\": \"/folders/3ed02ee3-xxxx-xxxx-xxxx-e6795f96a840\"         }       ]     },     {       \"name\": \"Deleted Items\",       \"type\": \"recyclebin\",       \"itemCount\": \"0\",       \"subFolderCount\": \"0\",       \"hasSubFolders\": \"false\"     },     {       \"name\": \"Sent Items\",       \"type\": \"sentitems\",       \"itemCount\": \"3\",       \"subFolderCount\": \"0\",       \"hasSubFolders\": \"false\"     }   ] }  ```  </div></ds-step>   <ds-step open=\"false\" hideIcon=\"true\">  Setting `sub_folder_depth` to `-1` returns the entire folder hierarchy.   <div>  `GET 'https://demo.docusign.net/restapi/v2.1/accounts/624e3e00-xxxx-xxxx-xxxx-43918c520dab/folders?sub_folder_depth=-1'`  One envelope has been moved from the `Inbox` folder to the `Project Fair/Phase 1` folder, and the endpoint is invoked with `sub_folder_depth=-1`.   ```json {   \"resultSetSize\": \"5\",   \"startPosition\": \"0\",   \"endPosition\": \"4\",   \"totalSetSize\": \"4\",   \"folders\": [     {       \"name\": \"Draft\",       \"type\": \"draft\",       \"itemCount\": \"1\",       \"hasSubFolders\": \"false\"     },     {       \"name\": \"Inbox\",       \"type\": \"inbox\",       \"itemCount\": \"0\",       \"hasSubFolders\": \"true\",       \"folders\": [         {           \"name\": \"Project Fair\",           \"type\": \"normal\",           \"itemCount\": \"0\",           \"hasSubFolders\": \"true\",           \"parentFolderId\": \"3ed02ee3-xxxx-xxxx-xxxx-e6795f96a840\",           \"parentFolderUri\": \"/folders/3ed02ee3-xxxx-xxxx-xxxx-e6795f96a840\",           \"folders\": [             {               \"name\": \"NDAs\",               \"type\": \"normal\",               \"itemCount\": \"0\",               \"hasSubFolders\": \"false\",               \"parentFolderId\": \"12882f2f-xxxx-xxxx-xxxx-e04a714f8e2d\",               \"parentFolderUri\": \"/folders/12882f2f-xxxx-xxxx-xxxx-e04a714f8e2d\"             },             {               \"name\": \"Phase 1\",               \"type\": \"normal\",               \"itemCount\": \"1\",               \"hasSubFolders\": \"false\",               \"parentFolderId\": \"12882f2f-xxxx-xxxx-xxxx-e04a714f8e2d\",               \"parentFolderUri\": \"/folders/12882f2f-xxxx-xxxx-xxxx-e04a714f8e2d\"             }           ]         }       ]     },     {       \"name\": \"Deleted Items\",       \"type\": \"recyclebin\",       \"itemCount\": \"0\",       \"hasSubFolders\": \"false\"     },     {       \"name\": \"Sent Items\",       \"type\": \"sentitems\",       \"itemCount\": \"1\",       \"hasSubFolders\": \"false\"     }   ] } ```  </div></ds-step> </ds-column>   ### Related topics  - [Searching for envelopes](/docs/esign-rest-api/esign101/concepts/envelopes/search/) - [Sharing templates](/docs/esign-rest-api/esign101/concepts/templates/sharing/)

  ### Parameters

  - `connection` (DocuSign.Connection): Connection to server
  - `account_id` (String.t): The external account number (int) or account ID GUID.
  - `opts` (keyword): Optional parameters
    - `:count` (String.t): The maximum number of results to return.
    - `:include` (String.t): A comma-separated list of folder types to include in the response. Valid values are:  - `envelope_folders`: Returns a list of envelope folders. (Default) - `template_folders`: Returns a list of template folders.  - `shared_template_folders`: Returns a list of shared template folders.
    - `:include_items` (String.t): Indicates whether folder items are included in the response. If this parameter is omitted, the default is false.
    - `:start_position` (String.t): The zero-based index of the result from which to start returning results.  The default value is `0`.
    - `:sub_folder_depth` (String.t): If missing or any value other than `-1`, the returned list contains only the top-level folders. A value of `-1` returns the complete folder hierarchy.
    - `:template` (String.t): This parameter is deprecated as of version 2.1. Use `include` instead.
    - `:user_filter` (String.t): Narrows down the resulting folder list by the following values:  - `all`: Returns all templates owned or shared with the user. (default) - `owned_by_me`: Returns only  templates the user owns. - `shared_with_me`: Returns only templates that are shared with the user.

  ### Returns

  - `{:ok, DocuSign.Model.FoldersResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec folders_get_folders(Tesla.Env.client(), String.t(), keyword()) ::
          {:ok, DocuSign.Model.FoldersResponse.t()}
          | {:ok, DocuSign.Model.ErrorDetails.t()}
          | {:error, Tesla.Env.t()}
  def folders_get_folders(connection, account_id, opts \\ []) do
    optional_params = %{
      :count => :query,
      :include => :query,
      :include_items => :query,
      :start_position => :query,
      :sub_folder_depth => :query,
      :template => :query,
      :user_filter => :query
    }

    request =
      %{}
      |> method(:get)
      |> url("/v2.1/accounts/#{account_id}/folders")
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, %DocuSign.Model.FoldersResponse{}},
      {400, %DocuSign.Model.ErrorDetails{}}
    ])
  end

  @doc """
  Moves an envelope from its current folder to the specified folder.
  Moves an envelope from its current folder to the specified folder.  You can use this method to delete envelopes by specifying `recyclebin` in the `folderId` parameter. Placing an in-process envelope (envelope status of `sent` or `delivered`) in the recycle bin voids the envelope.  You can also use this method to delete templates by specifying a template ID instead of an envelope ID in the `envelopeIds` property and specifying `recyclebin` in the `folderId` parameter.  ### Related topics  - [Searching for envelopes](/docs/esign-rest-api/esign101/concepts/envelopes/search/) - [Sharing templates](/docs/esign-rest-api/esign101/concepts/templates/sharing/)

  ### Parameters

  - `connection` (DocuSign.Connection): Connection to server
  - `account_id` (String.t): The external account number (int) or account ID GUID.
  - `folder_id` (String.t): The ID of the folder.
  - `opts` (keyword): Optional parameters
    - `:body` (FoldersRequest):

  ### Returns

  - `{:ok, DocuSign.Model.FoldersResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec folders_put_folder_by_id(Tesla.Env.client(), String.t(), String.t(), keyword()) ::
          {:ok, DocuSign.Model.FoldersResponse.t()}
          | {:ok, DocuSign.Model.ErrorDetails.t()}
          | {:error, Tesla.Env.t()}
  def folders_put_folder_by_id(connection, account_id, folder_id, opts \\ []) do
    optional_params = %{
      :body => :body
    }

    request =
      %{}
      |> method(:put)
      |> url("/v2.1/accounts/#{account_id}/folders/#{folder_id}")
      |> add_optional_params(optional_params, opts)
      |> ensure_body()
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, %DocuSign.Model.FoldersResponse{}},
      {400, %DocuSign.Model.ErrorDetails{}}
    ])
  end

  @doc """
  Gets a list of envelopes in folders matching the specified criteria.
  **This method is deprecated in API v2.1.**  Use  [Envelopes::listStatusChanges](/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges/) instead.  Retrieves a list of items that match the criteria specified in the query.  If the user ID of the user making the call is the same as the user ID for any returned recipient, then the userId property is added to the returned information for those recipients.

  ### Parameters

  - `connection` (DocuSign.Connection): Connection to server
  - `account_id` (String.t): The external account number (int) or account ID GUID.
  - `search_folder_id` (String.t): Specifies the envelope group that is searched by the request. These are logical groupings, not actual folder names. Valid values are: drafts, awaiting_my_signature, completed, out_for_signature.
  - `opts` (keyword): Optional parameters
    - `:all` (String.t): Specifies that all envelopes that match the criteria are returned.
    - `:count` (String.t): The maximum number of results to return.  Use `start_position` to specify the number of results to skip.  Valid values: `1` to `100`
    - `:from_date` (String.t): Specifies the start of the date range to return. If no value is provided, the default search is the previous 30 days.
    - `:include_recipients` (String.t): When **true,** the recipient information is returned in the response.
    - `:order` (String.t): Specifies the order in which the list is returned. Valid values are: `asc` for ascending order, and `desc` for descending order.
    - `:order_by` (String.t): Specifies the property used to sort the list. Valid values are: `action_required`, `created`, `completed`, `sent`, `signer_list`, `status`, or `subject`.
    - `:start_position` (String.t): The zero-based index of the result from which to start returning results.  Use with `count` to limit the number of results.  The default value is `0`.
    - `:to_date` (String.t): Specifies the end of the date range to return.

  ### Returns

  - `{:ok, DocuSign.Model.FolderItemResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec search_folders_get_search_folder_contents(
          Tesla.Env.client(),
          String.t(),
          String.t(),
          keyword()
        ) ::
          {:ok, DocuSign.Model.ErrorDetails.t()}
          | {:ok, DocuSign.Model.FolderItemResponse.t()}
          | {:error, Tesla.Env.t()}
  def search_folders_get_search_folder_contents(
        connection,
        account_id,
        search_folder_id,
        opts \\ []
      ) do
    optional_params = %{
      :all => :query,
      :count => :query,
      :from_date => :query,
      :include_recipients => :query,
      :order => :query,
      :order_by => :query,
      :start_position => :query,
      :to_date => :query
    }

    request =
      %{}
      |> method(:get)
      |> url("/v2.1/accounts/#{account_id}/search_folders/#{search_folder_id}")
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, %DocuSign.Model.FolderItemResponse{}},
      {400, %DocuSign.Model.ErrorDetails{}}
    ])
  end
end