Class: Ashby::Postings

Inherits:
Client
  • Object
show all
Defined in:
lib/ashby/postings.rb

Overview

Ashby::Postings provides access to job posting related functionality in the Ashby API.

It wraps the jobPosting.info and jobPosting.list endpoints and exposes a few convenience helpers for commonly accessed nested fields such as linkedData (for SEO rich results) and applicationFormDefinition.

Endpoints referenced:

- jobPosting.info   -> Retrieve a single job posting by ID
- jobPosting.list   -> List job postings (optionally only those that are publicly listed)
- jobPosting.update -> Update an existing job posting

Example usage:

Ashby::Postings.list                     # list all postings (listed + unlisted)
Ashby::Postings.list(listed_only: true)  # only postings publicly listed
Ashby::Postings.all                      # (deprecated) alias to .list
Ashby::Postings.find('jp_abc123')        # posting hash
Ashby::Postings.linked_data('jp_abc123') # structured data for SEO
Ashby::Postings.application_form_definition('jp_abc123')
Ashby::Postings.update(id: 'jp_abc123', payload: { title: 'Updated Title' })

Note: A Ashby::JobPostings class already exists; this class provides a cleaner name (Postings) and a couple of ergonomic helpers while delegating to the same underlying API endpoints. Either class can be used interchangeably.

Constant Summary

Constants inherited from Client

Client::API_URL

Class Method Summary collapse

Methods inherited from Client

build_url, headers, paginated_post, post

Class Method Details

.all(listed_only: nil, **_deprecated) ⇒ Object

Deprecated: Use .list(listed_only: ...) instead. Retained for backward compatibility.



39
40
41
42
 
# File 'lib/ashby/postings.rb', line 39

def self.all(listed_only: nil, **_deprecated)
  Kernel.warn('[DEPRECATION] Ashby::Postings.all is deprecated. Use Ashby::Postings.list(listed_only: ...) instead.')
  list(listed_only: listed_only)
end

.application_form_definition(id) ⇒ Object

Convenience: Returns the applicationFormDefinition of a posting.



64
65
66
 
# File 'lib/ashby/postings.rb', line 64

def self.application_form_definition(id)
  find(id)['applicationFormDefinition']
end

.find(id) ⇒ Hash Also known as: find_by_id, info

Retrieve a single job posting by its Ashby Job Posting ID.

Parameters:

  • id (String) —

    The Ashby Job Posting ID (e.g., "jp_abc123")

Returns:

  • (Hash) —

    The job posting object

Raises:

  • (ArgumentError) 


47
48
49
50
51
52
 
# File 'lib/ashby/postings.rb', line 47

def self.find(id)
  raise ArgumentError, 'Job Posting ID is required' if id.to_s.strip.empty?

  payload = { jobPostingId: id }
  post('jobPosting.info', payload)['results']
end

.linked_data(id) ⇒ Object

Convenience: Returns the linkedData section (for SEO rich results) of a posting.



59
60
61
 
# File 'lib/ashby/postings.rb', line 59

def self.linked_data(id)
  find(id)['linkedData']
end

.list(listed_only: nil) ⇒ Object

Lists job postings. By default returns both listed and unlisted job postings. Pass listed_only: true to restrict to those safe for public display.

Parameters:

  • listed_only (Boolean, nil) (defaults to: nil) —

    When true only include publicly listed postings; when nil omit filter.



32
33
34
35
36
 
# File 'lib/ashby/postings.rb', line 32

def self.list(listed_only: nil)
  payload = {}
  payload[:listedOnly] = true if listed_only == true
  post('jobPosting.list', payload)['results']
end

.update(id:, payload: {}) ⇒ Hash

Update a job posting via jobPosting.update. You must supply at least one field to update in the payload.

Parameters:

  • id (String) —

    The Ashby Job Posting ID

  • payload (Hash) (defaults to: {}) —

    Fields to update (see Ashby API docs for allowed keys)

Returns:

  • (Hash) —

    Updated job posting object

Raises:

  • (ArgumentError) 


74
75
76
77
78
79
80
81
 
# File 'lib/ashby/postings.rb', line 74

def self.update(id:, payload: {})
  raise ArgumentError, 'Job Posting ID is required' if id.to_s.strip.empty?
  raise ArgumentError, 'Update payload cannot be empty' if payload.empty?

  body = payload.dup
  body[:jobPostingId] = id
  post('jobPosting.update', body)['results']
end