Humaans.People behaviour (Humaans v0.4.0)

View Source

This module provides functions for managing people resources in the Humaans API.

Summary

Types

delete_response()
list_response()
response()

Callbacks

create(client, map)
delete(client, t)
list(client, map)
retrieve(client, t)
update(client, t, map)

Functions

create(client, params)

Creates a new person resource.

delete(client, id)

Deletes a specific person by ID.

list(client, params \\ %{})

Lists all people resources.

retrieve(client, id)

Retrieves a specific person by ID.

update(client, id, params)

Updates a specific person by ID.

Types

delete_response()

@type delete_response() :: {:ok, %{id: String.t(), deleted: bool()}} | {:error, any()}

list_response()

@type list_response() ::
  {:ok,
   [
     %Humaans.Resources.Person{
       address: term(),
       bio: term(),
       birthday: term(),
       calendar_feed_token: term(),
       city: term(),
       company_id: term(),
       contract_type: term(),
       country: term(),
       country_code: term(),
       created_at: term(),
       demo: term(),
       dietary_preference: term(),
       email: term(),
       employee_id: term(),
       employment_end_date: term(),
       employment_start_date: term(),
       first_name: term(),
       first_working_day: term(),
       food_allergies: term(),
       formatted_personal_phone_number: term(),
       formatted_phone_number: term(),
       gender: term(),
       github: term(),
       id: term(),
       is_birthday_hidden: term(),
       is_verified: term(),
       is_work_email_hidden: term(),
       last_name: term(),
       last_working_day: term(),
       leaving_file_id: term(),
       leaving_note: term(),
       leaving_reason: term(),
       linked_in: term(),
       location_id: term(),
       middle_name: term(),
       nationalities: term(),
       nationality: term(),
       payroll_provider: term(),
       personal_email: term(),
       personal_phone_number: term(),
       phone_number: term(),
       postcode: term(),
       preferred_name: term(),
       probation_end_date: term(),
       profile_photo: term(),
       profile_photo_id: term(),
       public_holiday_calendar_id: term(),
       remote_city: term(),
       remote_country_code: term(),
       remote_region_code: term(),
       remote_timezone: term(),
       role: term(),
       seen_documents_at: term(),
       source: term(),
       source_id: term(),
       spoken_languages: term(),
       state: term(),
       status: term(),
       tax_code: term(),
       tax_id: term(),
       teams: term(),
       timezone: term(),
       turnover_impact: term(),
       twitter: term(),
       updated_at: term(),
       working_days: term()
     }
   ]}
  | {:error, any()}

response()

@type response() ::
  {:ok,
   %Humaans.Resources.Person{
     address: term(),
     bio: term(),
     birthday: term(),
     calendar_feed_token: term(),
     city: term(),
     company_id: term(),
     contract_type: term(),
     country: term(),
     country_code: term(),
     created_at: term(),
     demo: term(),
     dietary_preference: term(),
     email: term(),
     employee_id: term(),
     employment_end_date: term(),
     employment_start_date: term(),
     first_name: term(),
     first_working_day: term(),
     food_allergies: term(),
     formatted_personal_phone_number: term(),
     formatted_phone_number: term(),
     gender: term(),
     github: term(),
     id: term(),
     is_birthday_hidden: term(),
     is_verified: term(),
     is_work_email_hidden: term(),
     last_name: term(),
     last_working_day: term(),
     leaving_file_id: term(),
     leaving_note: term(),
     leaving_reason: term(),
     linked_in: term(),
     location_id: term(),
     middle_name: term(),
     nationalities: term(),
     nationality: term(),
     payroll_provider: term(),
     personal_email: term(),
     personal_phone_number: term(),
     phone_number: term(),
     postcode: term(),
     preferred_name: term(),
     probation_end_date: term(),
     profile_photo: term(),
     profile_photo_id: term(),
     public_holiday_calendar_id: term(),
     remote_city: term(),
     remote_country_code: term(),
     remote_region_code: term(),
     remote_timezone: term(),
     role: term(),
     seen_documents_at: term(),
     source: term(),
     source_id: term(),
     spoken_languages: term(),
     state: term(),
     status: term(),
     tax_code: term(),
     tax_id: term(),
     teams: term(),
     timezone: term(),
     turnover_impact: term(),
     twitter: term(),
     updated_at: term(),
     working_days: term()
   }}
  | {:error, any()}

Callbacks

create(client, map)

@callback create(client :: map(), map()) :: {:ok, map()} | {:error, any()}

delete(client, t)

@callback delete(client :: map(), String.t()) :: {:ok, map()} | {:error, any()}

list(client, map)

@callback list(client :: map(), map()) :: {:ok, map()} | {:error, any()}

retrieve(client, t)

@callback retrieve(client :: map(), String.t()) :: {:ok, map()} | {:error, any()}

update(client, t, map)

@callback update(client :: map(), String.t(), map()) :: {:ok, map()} | {:error, any()}

Functions

create(client, params)

@spec create(client :: map(), params :: keyword()) :: response()

Creates a new person resource.

Parameters

  • client - Client map created with Humaans.new/1
  • params - Map of parameters for the new person

Examples 

client = Humaans.new(access_token: "your_access_token")

params = %{
  firstName: "Jane",
  lastName: "Doe",
  email: "jane@example.com"
}

{:ok, person} = Humaans.People.create(client, params)

delete(client, id)

@spec delete(client :: map(), id :: String.t()) :: delete_response()

Deletes a specific person by ID.

Parameters

  • client - Client map created with Humaans.new/1
  • id - String ID of the person to delete

Examples 

client = Humaans.new(access_token: "your_access_token")

{:ok, result} = Humaans.People.delete(client, "person_id")
# result contains %{id: "person_id", deleted: true}

list(client, params \\ %{})

@spec list(client :: map(), params :: keyword()) :: list_response()

Lists all people resources.

Returns a list of people resources that match the optional filters provided in params.

Parameters

  • client - Client map created with Humaans.new/1
  • params - Optional parameters for filtering the results (default: %{})

Examples 

client = Humaans.new(access_token: "your_access_token")

# List all people
{:ok, people} = Humaans.People.list(client)

# List with filtering parameters
{:ok, people} = Humaans.People.list(client, %{limit: 10})

retrieve(client, id)

@spec retrieve(client :: map(), id :: String.t()) :: response()

Retrieves a specific person by ID.

Parameters

  • client - Client map created with Humaans.new/1
  • id - String ID of the person to retrieve

Examples 

client = Humaans.new(access_token: "your_access_token")

{:ok, person} = Humaans.People.retrieve(client, "person_id")

update(client, id, params)

@spec update(client :: map(), id :: String.t(), params :: keyword()) :: response()

Updates a specific person by ID.

Parameters

  • client - Client map created with Humaans.new/1
  • id - String ID of the person to update
  • params - Map of parameters to update

Examples 

client = Humaans.new(access_token: "your_access_token")

params = %{firstName: "Janet"}

{:ok, updated_person} = Humaans.People.update(client, "person_id", params)