ashby 0.1.3

data/lib/ashby/custom_fields.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Ashby
+  # Ashby::CustomFields manages setting custom field values for objects
+  # in the Ashby API, such as jobs or candidates.
+  #
+  # This class provides a method to assign a specific value to a custom field
+  # identified by field ID, for a particular object type and ID.
+  #
+  # Example:
+  #   Ashby::CustomFields.set_field(
+  #     object_id: 'job_abc123',
+  #     object_type: 'job',
+  #     field_id: 'cf_custom_location',
+  #     field_value: 'Remote'
+  #   )
+  #
+  class CustomFields < Client
+    def self.set_field(object_id: nil, object_type: nil, field_id: nil, field_value: nil)
+      raise ArgumentError, '`object_id` is required' if object_id.blank?
+      raise ArgumentError, '`object_type` is required' if object_type.blank?
+      raise ArgumentError, '`field_id` is required' if field_id.blank?
+      raise ArgumentError, '`field_value` is required' if field_value.blank?
+
+      payload = {
+        objectId: object_id,
+        objectType: object_type,
+        fieldId: field_id,
+        fieldValue: field_value
+      }
+
+      post('customField.setValue', payload)['results']
+    end
+  end
+end

data/lib/ashby/departments.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ashby
+  # Ashby::Departments provides methods to interact with the
+  # Ashby API's department-related endpoints.
+  #
+  # Includes fetching a list of departments and retrieving a specific department by ID.
+  #
+  # Example:
+  #   Ashby::Departments.all
+  #   Ashby::Departments.find(id: 'abc123')
+  #
+  class Departments < Client
+    # Fetches all departments
+    def self.all
+      response = post('department.list')
+      response['results']
+    end
+
+    # Finds a department by its Ashby ID
+    def self.find(id: nil)
+      raise ArgumentError, 'Department ID is required' if id.to_s.strip.empty?
+
+      payload = { departmentId: id }
+      response = post('department.info', payload)
+      response['results']
+    end
+  end
+end

data/lib/ashby/error.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Ashby
+  # Custom error class for the Ashby module that extends StandardError
+  # with optional error code support.
+  #
+  # This class provides a standardized way to handle errors within the Ashby
+  # module by allowing both error messages and optional error codes to be
+  # associated with exceptions.
+  #
+  # @example Basic usage with message only
+  #   raise Ashby::Error.new("Something went wrong")
+  #
+  # @example Usage with message and error code
+  #   raise Ashby::Error.new("API request failed", 500)
+  #
+  # @example Accessing the error code
+  #   begin
+  #     raise Ashby::Error.new("Not found", 404)
+  #   rescue Ashby::Error => e
+  #     puts e.message  # => "Not found"
+  #     puts e.code     # => 404
+  #   end
+  #
+  # @attr_reader [Object, nil] code The optional error code associated with this error
+  class Error < StandardError
+    attr_reader :code
+
+    # Initialize a new Ashby::Error instance
+    #
+    # @param message [String] The error message
+    # @param code [Object, nil] Optional error code (typically an integer, but can be any object)
+    def initialize(message, code = nil)
+      super(message)
+      @code = code
+    end
+  end
+end

data/lib/ashby/feedback.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Ashby
+  #
+  # Ashby::Feedback provides access to feedback-related operations via the Ashby API.
+  # # Supported functionality includes:
+  #   - Retrieving a paginated list of all feedback
+  # # Example usage:
+  #   Ashby::Feedback.all
+  #
+  class Feedback < Client
+    # Fetches all feedback with pagination support
+    def self.all(payload = {})
+      paginated_post('applicationFeedback.list', payload)
+    end
+  end
+end

data/lib/ashby/hiring_teams.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Ashby
+  # Ashby::HiringTeams provides access to hiring team management functionality in the Ashby API.
+  #
+  # Includes support for:
+  #   - Adding a member to a hiring team
+  #   - Removing a member from a hiring team
+  #
+  # Example usage:
+  #   Ashby::HiringTeams.add_hiring_team_member(type: :job, id: 'job_123', member_id: 'user_456', role_id: 'role_789')
+  #   Ashby::HiringTeams.remove_hiring_team_member(type: :application, id: 'app_123', member_id: 'user_456',
+  #   role_id: 'role_789')
+  #
+  class HiringTeams < Client
+    def self.remove_hiring_team_member(type, id, member_id, role_id)
+      payload = build_hiring_team_payload(type, id, member_id, role_id)
+      response = post('hiringTeam.removeMember', payload)
+      response['results']
+    end
+
+    def self.add_hiring_team_member(type, id, member_id, role_id)
+      payload = build_hiring_team_payload(type, id, member_id, role_id)
+      response = post('hiringTeam.addMember', payload)
+      response['results']
+    end
+
+    def self.build_hiring_team_payload(type, id, member_id, role_id) # rubocop:disable Metrics/MethodLength
+      payload = {}
+      case type
+      when :job
+        payload[:jobId] = id.to_s if id
+      when :application
+        payload[:applicationId] = id.to_s
+      when :opening
+        payload[:openingId] = id.to_s
+      else
+        raise ArgumentError, "Invalid type: #{type}. Must be one of :job, :application, or :opening."
+      end
+      payload[:teamMemberId] = member_id if member_id
+      payload[:roleId] = role_id if role_id
+      payload
+    end
+  end
+end

data/lib/ashby/interviews.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Ashby
+  # Ashby::InterviewSchedules provides access to Interview Schedule-related functionality in the Ashby API.
+  #
+  # Includes support for:
+  #   - Fetching all interviews (with pagination)
+  #
+  # Example:
+  #   Ashby::InterviewSchedules.all
+  #
+  class Interviews < Client
+    # Fetches all interview schedules with pagination support
+    def self.schedule_all(payload = {})
+      paginated_post('interviewSchedule.list', payload)
+    end
+
+    def self.plans_all
+      response = post('interviewPlan.list')
+      response['results']
+    end
+
+    def self.stages_all
+      response = post('interviewStage.list')
+      response['results']
+    end
+
+    def self.interview_by_id(id: nil)
+      raise ArgumentError, 'Interview ID is required' if id.to_s.strip.empty?
+
+      payload = { id: id }
+      response = post('interview.info', payload)
+      response['results']
+    end
+
+    def self.stage_by_id(id: nil)
+      raise ArgumentError, 'Stage ID is required' if id.to_s.strip.empty?
+
+      payload = { interviewStageId: id }
+      response = post('interviewStage.info', payload)
+      response['results']
+    end
+  end
+end

data/lib/ashby/job_boards.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Ashby
+  class JobBoards < Client
+    def self.all
+      response = post('jobBoard.list')
+      response['results']
+    end
+  end
+end

data/lib/ashby/job_postings.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Ashby
+  # Ashby::JobPostings provides access to job posting-related functionality in the Ashby API.
+  #
+  # Includes support for:
+  #   - Fetching all job postings (active only by default, can include inactive)
+  #   - Looking up a job posting by its Ashby ID
+  #
+  # Example usage:
+  #   Ashby::JobPostings.all
+  #   Ashby::JobPostings.all(active_only: false)
+  #   Ashby::JobPostings.find_by_id(id: 'jp_abc456')
+  #
+  class JobPostings < Client
+    # Fetches all job postings
+    def self.all(active_only: true, job_board_id: nil)
+      payload = { listedOnly: active_only }
+      payload[:jobBoardId] = job_board_id if job_board_id
+
+      response = post('jobPosting.list', payload)
+      response['results']
+    end
+
+    # Finds a Job Posting by the Ashby ID
+    def self.find_by_id(id: nil)
+      raise ArgumentError, 'Job Posting ID is required' if id.to_s.strip.empty?
+
+      payload = { jobPostingId: id }
+      response = post('jobPosting.info', payload)
+      response['results']
+    end
+
+    # Finds all Job Postings associated with a given Job ID
+    def self.by_job_id(job_id: nil)
+      raise ArgumentError, 'Job ID is required' if job_id.to_s.strip.empty?
+
+      payload = { id: job_id }
+      response = post('job.info', payload)
+      job_posting_ids = response.dig('results', 'jobPostingIds') || []
+
+      job_posting_ids.map { |jp_id| find_by_id(id: jp_id) }
+    end
+  end
+end

data/lib/ashby/jobs.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Ashby
+  # Ashby::Jobs handles interactions with job-related endpoints in the Ashby API.
+  #
+  # Supports fetching all jobs with pagination, finding a job by ID, and searching
+  # jobs based on requisition ID or title.
+  #
+  # Example:
+  #   Ashby::Jobs.all
+  #   Ashby::Jobs.find('job_abc123')
+  #   Ashby::Jobs.search(req_id: 'REQ-001')
+  #
+  class Jobs < Client
+    # Fetches all jobs with pagination support
+    def self.all(payload = {})
+      paginated_post('job.list', payload)
+    end
+
+    # Finds a job by its Ashby ID
+    def self.find(id, expand: '')
+      raise ArgumentError, 'Job ID is required' if id.to_s.strip.empty?
+
+      payload = {
+        id: id,
+        expand: expand.strip.empty? ? [] : [expand]
+      }
+      post('job.info', payload)['results']
+    end
+
+    # Searches for jobs based on requisition ID or title
+    def self.search(req_id: nil, title: nil)
+      payload = {}
+      payload[:requisitionId] = req_id.to_s if req_id
+      payload[:title] = title if title
+
+      raise ArgumentError, 'You must provide at least a job title or a requisition id' if payload.empty?
+
+      post('job.search', payload)['results']
+    end
+
+    # Fetches all job templates
+    def self.templates
+      paginated_post('jobTemplate.list')
+    end
+
+    def self.create(payload)
+      required_fields = %i[title teamId locationId]
+      missing = required_fields.select { |f| payload[f].to_s.strip.empty? }
+      raise ArgumentError, "Missing required fields: #{missing.join(', ')}" if missing.any?
+
+      post('job.create', payload)['results']
+    end
+
+    def self.update(id: nil, payload: {})
+      raise ArgumentError, 'You must provide a job id' if id.nil?
+
+      payload[:jobId] = id
+      post('job.update', payload)['results']
+    end
+
+    def self.set_status(job_id:, status:)
+      valid_statuses = %w[Draft Open Closed Archived]
+      raise ArgumentError, 'Job ID is required' if job_id.to_s.strip.empty?
+      raise ArgumentError, "Invalid status: #{status}" unless valid_statuses.include?(status)
+
+      payload = {
+        jobId: job_id,
+        status: status
+      }
+
+      post('job.setStatus', payload)['results']
+    end
+  end
+end

data/lib/ashby/offers.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Ashby
+  # Ashby::Offers provides access to offer-related endpoints in the Ashby API.
+  #
+  # Supports fetching all offers with pagination and retrieving a specific offer by ID.
+  #
+  # Example:
+  #   Ashby::Offers.all
+  #   Ashby::Offers.find(id: 'offer_xyz789')
+  #
+  class Offers < Client
+    # Fetches all offers with pagination support
+    def self.all
+      paginated_post('offer.list')
+    end
+
+    # Finds an offer by its Ashby ID
+    def self.find(id: nil)
+      raise ArgumentError, 'Offer ID is required' if id.to_s.strip.empty?
+
+      payload = { id: id }
+      response = post('offer.info', payload)
+      response['results']
+    end
+
+    def self.offers_by_application_id(application_id: nil)
+      raise ArgumentError, 'Application ID is required' if application_id.to_s.strip.empty?
+
+      payload = { applicationId: application_id }
+      response = post('offer.list', payload)
+      response['results']
+    end
+
+    def self.most_recent_offer_by_application_id(application_id: nil)
+      raise ArgumentError, 'Application ID is required' if application_id.to_s.strip.empty?
+
+      payload = { applicationId: application_id }
+      response = post('offer.list', payload)
+      response['results'].max_by { |o| o['latestVersion']['createdAt'] }
+    end
+  end
+end

data/lib/ashby/openings.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Ashby
+  # Ashby::Candidates provides access to candidate-related functionality in the Ashby API.
+  #
+  # Includes support for:
+  #   - Fetching all candidates (with pagination)
+  #   - Searching by email or name
+  #   - Looking up by ID
+  #   - Adding notes to candidate profiles in plain text or HTML
+  #
+  # Example:
+  #   Ashby::Candidates.all
+  #   Ashby::Candidates.find(email: 'jane@company.com')
+  #   Ashby::Candidates.find_by_id(id: 'cand_abc123')
+  #
+  #   client = Ashby::Candidates.new
+  #   client.create_candidate_note('cand_abc123', 'Reached out via email.')
+  #   client.create_formatted_candidate_note('cand_abc123', title: 'Initial Contact',
+  #     content: 'Spoke with Jane over Zoom.')
+  #
+  class Openings < Client
+    # Fetches all openings with pagination support
+    def self.all
+      paginated_post('opening.list')
+    end
+
+    # Finds an opening by email or name
+    def self.find(email: nil, name: nil)
+      payload = {}
+      payload[:email] = email if email
+      payload[:name] = name if name
+
+      raise ArgumentError, 'You must provide at least an email or a name' if payload.empty?
+
+      response = post('opening.search', payload)
+      response['results']
+    end
+
+    # Searches for openings by the identifier
+    def self.search(identifier: nil)
+      raise ArgumentError, 'You must provide an identifier' if identifier.to_s.strip.empty?
+
+      payload = { identifier: identifier.to_s }
+      response = post('opening.search', payload)
+      response['results']
+    end
+
+    # Finds an opening by its Ashby ID
+    def self.find_by_id(id: nil)
+      raise ArgumentError, 'Opening ID is required' if id.to_s.strip.empty?
+
+      payload = { openingId: id }
+      response = post('opening.info', payload)
+      response['results']
+    end
+
+    def self.set_status(id, state)
+      payload = {}
+      payload[:openingId] = id if id
+      payload[:openingState] = state if state
+
+      raise ArgumentError, 'You must provide the opening ID and the state' if payload.empty?
+
+      response = post('opening.setOpeningState', payload)
+      response['results']
+    end
+
+    def self.create(payload)
+      raise ArgumentError, 'No payload provided' if payload.empty?
+
+      response = post('opening.create', payload)
+      response['results']
+    end
+  end
+end

data/lib/ashby/postings.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Ashby
+  # 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.
+  #
+  class Postings < Client
+    # Lists job postings. By default returns both listed and unlisted job postings.
+    # Pass listed_only: true to restrict to those safe for public display.
+    # @param listed_only [Boolean, nil] When true only include publicly listed postings; when nil omit filter.
+    def self.list(listed_only: nil)
+      payload = {}
+      payload[:listedOnly] = true if listed_only == true
+      post('jobPosting.list', payload)['results']
+    end
+
+    # Deprecated: Use .list(listed_only: ...) instead. Retained for backward compatibility.
+    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
+
+    # Retrieve a single job posting by its Ashby Job Posting ID.
+    # @param id [String] The Ashby Job Posting ID (e.g., "jp_abc123")
+    # @return [Hash] The job posting object
+    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
+    class << self
+      alias find_by_id find
+      alias info find
+    end
+
+    # Convenience: Returns the `linkedData` section (for SEO rich results) of a posting.
+    def self.linked_data(id)
+      find(id)['linkedData']
+    end
+
+    # Convenience: Returns the `applicationFormDefinition` of a posting.
+    def self.application_form_definition(id)
+      find(id)['applicationFormDefinition']
+    end
+
+    # Update a job posting via jobPosting.update.
+    # You must supply at least one field to update in the payload.
+    #
+    # @param id [String] The Ashby Job Posting ID
+    # @param payload [Hash] Fields to update (see Ashby API docs for allowed keys)
+    # @return [Hash] Updated job posting object
+    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
+  end
+end

data/lib/ashby/users.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ashby
+  # Ashby::Users provides access to user-related functionality in the Ashby API.
+  #
+  # Includes support for:
+  #   - Fetching all users with pagination
+  #   - Searching users by email
+  #   - Looking up users by their Ashby ID
+  #
+  # Example usage:
+  #   Ashby::Users.all
+  #   Ashby::Users.find_by_email(email: 'recruiter@company.com')
+  #   Ashby::Users.find_by_id(id: 'user_xyz789')
+  #
+  class Users < Client
+    # Fetches all users with pagination support
+    def self.all
+      paginated_post('user.list')
+    end
+
+    # Find a user by their email
+    def self.find_by_email(email: nil)
+      payload = {}
+      payload[:email] = email if email
+
+      raise ArgumentError, 'You must provide an email' if payload.empty?
+
+      response = post('user.search', payload)
+      response['results']
+    end
+
+    # Finds a user by their Ashby ID
+    def self.find_by_id(id: nil)
+      raise ArgumentError, 'User ID is required' if id.to_s.strip.empty?
+
+      payload = { userId: id }
+      response = post('user.info', payload)
+      response['results']
+    end
+  end
+end

data/lib/ashby/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ashby
+  VERSION = '0.1.3'
+end

data/lib/ashby.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'ashby/version'
+require_relative 'ashby/configuration'
+require_relative 'ashby/client'
+require_relative 'ashby/candidates'
+require_relative 'ashby/departments'
+require_relative 'ashby/jobs'
+require_relative 'ashby/offers'
+require_relative 'ashby/applications'
+require_relative 'ashby/openings'
+require_relative 'ashby/users'
+require_relative 'ashby/job_postings'
+require_relative 'ashby/hiring_teams'
+require_relative 'ashby/error'
+require_relative 'ashby/close_reasons'
+require_relative 'ashby/interviews'
+require_relative 'ashby/custom_fields'
+require_relative 'ashby/feedback'
+require_relative 'ashby/postings'
+require_relative 'ashby/job_boards'
+
+# This module handles integration with Ashby's API
+# for recruitment and hiring processes
+module Ashby
+  extend Configuration
+
+  class Error < StandardError; end
+end

data/sig/ashby.rbs

@@ -0,0 +1,4 @@
+module Ashby
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end