job_boardly_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 62bc0b8712d1e3b4cca8521c55a1d39923a0947c66f3f046d4c05834389d9ce5
+  data.tar.gz: d97e4d783e39a760897e7563fe6f7da59ee9da82651fb679e12291eba293371b
+SHA512:
+  metadata.gz: eeae331b2a33a05ed54b64abb9499f73b011258bec48b74fa3d16fb859c2747b7b1cdcfd9a6d1eb4bcafb347f10784e1ffa42f668fa6d2bf27a7093e21b138d3
+  data.tar.gz: e22a0310a25812d133fb2dcbf984e22de75f4c93db242e9a1ba0890a424f3d6a7658f59ec5cb4907ed35b6878c3816a0fbf570a32033cdb7a4fcd4e57750f84b

data/.github/workflows/ruby.yml

@@ -0,0 +1,38 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.7', '3.0']
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@55283cc23133118229fd3f97f9336ee23a179fcf # v1.146.0
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rake

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-06-30
+
+- Initial release
+

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"job_boardly_api" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["williamkennedyjnr@gmail.com"](mailto:"williamkennedyjnr@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 William Kennedy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,207 @@
+# JobBoardlyApi
+
+A Ruby wrapper around the [Jobboardly](https://jobboardly.com) Management and Headless Board APIs.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```bash
+bundle add job_boardly_api
+```
+
+Or install it yourself as:
+
+```bash
+gem install job_boardly_api
+```
+
+## Usage
+
+Every request returns a `JobBoardlyApi::Response` object. You can call `body` or `to_object` on it to get either the JSON hash or a Ruby object.
+
+### Management API
+
+You will need an API key from Jobboardly. Find it in the app under `Settings → Board → API access`.
+
+```ruby
+client = JobBoardlyApi::Client.new(api_key: ENV["JOBBOARDLY_API_KEY"])
+
+# Or target a specific board host
+client = JobBoardlyApi::Client.new(api_key: ENV["JOBBOARDLY_API_KEY"], board_host: "jobs.example.com")
+```
+
+### Board & Metadata
+
+```ruby
+response = client.me
+response.body => Hash of the JSON body
+response.to_object => OpenStruct
+
+response = client.categories
+response = client.category(1)
+response = client.arrangements
+```
+
+### Jobs
+
+```ruby
+response = client.jobs(page: 1, per: 50)
+response = client.create_job(
+  title: "API Engineer",
+  company_name: "Acme",
+  application_link: "mailto:jobs@acme.com",
+  description: "<div>Build APIs</div>",
+  location: "remote"
+)
+response = client.job(123)
+response = client.update_job(123, title: "Senior API Engineer")
+response = client.delete_job(123)
+response = client.publish_job(123)
+response = client.unpublish_job(123)
+response = client.restore_job(123)
+response = client.job_counts
+response = client.bulk_draft_jobs([1, 2, 3])
+response = client.bulk_publish_jobs([1, 2, 3])
+response = client.bulk_expire_jobs([1, 2, 3])
+response = client.bulk_destroy_jobs([1, 2, 3])
+```
+
+### Blog Posts
+
+```ruby
+response = client.blog_posts(state: "published")
+response = client.create_blog_post(title: "Hello World")
+response = client.blog_post(1)
+response = client.update_blog_post(1, title: "Hello Universe")
+response = client.delete_blog_post(1)
+response = client.publish_blog_post(1)
+response = client.unpublish_blog_post(1)
+```
+
+### Prices & Employer Products
+
+```ruby
+response = client.prices
+response = client.price(1)
+response = client.employer_products
+response = client.employer_product(1)
+```
+
+### Memberships
+
+```ruby
+response = client.membership_subscriptions(page: 1)
+response = client.grant_membership_subscription(
+  email: "customer@example.com",
+  membership_plan_id: 1,
+  external_ref: "unique-ref"
+)
+response = client.membership_subscription("unique-ref")
+response = client.revoke_membership_subscription("unique-ref")
+
+response = client.membership_purchases(page: 1)
+response = client.grant_membership_purchase(
+  email: "customer@example.com",
+  membership_plan_id: 1,
+  external_ref: "unique-ref"
+)
+response = client.membership_purchase("unique-ref")
+response = client.revoke_membership_purchase("unique-ref")
+```
+
+### Entitlements
+
+```ruby
+response = client.employer_entitlements(page: 1)
+response = client.grant_employer_entitlement(
+  email: "customer@example.com",
+  employer_product_id: 1,
+  external_ref: "unique-ref"
+)
+response = client.employer_entitlement("unique-ref")
+response = client.cancel_employer_entitlement("unique-ref")
+
+response = client.candidate_entitlements(page: 1)
+response = client.grant_candidate_entitlement(
+  email: "customer@example.com",
+  candidate_product_id: 1,
+  external_ref: "unique-ref"
+)
+response = client.candidate_entitlement("unique-ref")
+response = client.cancel_candidate_entitlement("unique-ref")
+```
+
+### Job Payments
+
+```ruby
+response = client.job_payments(page: 1)
+response = client.grant_job_payment(
+  job_id: 123,
+  amount_cents: 5000,
+  external_ref: "unique-ref"
+)
+response = client.job_payment("unique-ref")
+response = client.revoke_job_payment("unique-ref")
+response = client.revoke_job_payment("unique-ref", unpublish: false)
+```
+
+## Headless Board API
+
+The Headless API is public and does not require an API key. It is used for rendering a board from a custom frontend.
+
+```ruby
+# Using board host
+client = JobBoardlyApi::HeadlessClient.new(board_host: "jobs.example.com")
+
+# Or using board id via central API
+client = JobBoardlyApi::HeadlessClient.new(board_id: 42)
+```
+
+```ruby
+response = client.bootstrap
+response = client.jobs(page: 1, per: 10)
+response = client.job(123)
+response = client.categories
+response = client.arrangements
+response = client.places(q: "Berlin")
+response = client.blog_posts(tag: "ruby")
+response = client.blog_post("hello-world")
+response = client.page("about-us")
+response = client.employer_products
+response = client.candidate_products
+response = client.membership_plans
+response = client.create_subscriber(
+  subscriber: {
+    email: "user@example.com"
+  }
+)
+```
+
+## Response Object
+
+All API calls return a `JobBoardlyApi::Response`:
+
+```ruby
+response = client.me
+
+response.success?  # => true/false
+response.status    # => 200
+response.headers   # => { "content-type" => "application/json" }
+response.body      # => { "board" => { "id" => 1, ... } }
+response.to_object # => #<OpenStruct board=#<OpenStruct id=1, ...>>
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/williamkennedy/job_boardly_api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/job_boardly_api/base_client.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module JobBoardlyApi
+  class BaseClient
+    def initialize(base_url:)
+      @base_url = URI.parse(base_url.to_s)
+    end
+
+    def get(path, params = {})
+      make_request(Net::HTTP::Get, path, params)
+    end
+
+    def post(path, params = {}, body = {})
+      make_request(Net::HTTP::Post, path, params, body)
+    end
+
+    def patch(path, params = {}, body = {})
+      make_request(Net::HTTP::Patch, path, params, body)
+    end
+
+    def delete(path, params = {})
+      make_request(Net::HTTP::Delete, path, params)
+    end
+
+    private
+
+    def make_request(http_class, path, params = {}, body = nil)
+      uri = build_uri(path, params)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+
+      request = http_class.new(uri)
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      configure_request(request)
+      request.body = JSON.dump(body) if body
+
+      response = http.request(request)
+      Response.new(response)
+    end
+
+    def build_uri(path, params)
+      uri = @base_url.dup
+      uri.path = uri.path.chomp("/") + path
+      uri.query = URI.encode_www_form(params) if params && !params.empty?
+      uri
+    end
+
+    def configure_request(request)
+      # override in subclasses
+    end
+  end
+end

data/lib/job_boardly_api/client.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module JobBoardlyApi
+  class Client < BaseClient
+    DEFAULT_BASE_URL = "https://api.jobboardly.com/v1"
+
+    def initialize(api_key:, base_url: nil, board_host: nil)
+      url = base_url || (board_host ? "https://api.#{board_host}/v1" : DEFAULT_BASE_URL)
+      super(base_url: url)
+      @api_key = api_key
+    end
+
+    # Board & Metadata
+
+    def me
+      get("/me")
+    end
+
+    def categories
+      get("/categories")
+    end
+
+    def category(id)
+      get("/categories/#{id}")
+    end
+
+    def arrangements
+      get("/arrangements")
+    end
+
+    # Jobs
+
+    def jobs(params = {})
+      get("/jobs", params)
+    end
+
+    def create_job(body)
+      post("/jobs", {}, body)
+    end
+
+    def job(id)
+      get("/jobs/#{id}")
+    end
+
+    def update_job(id, body)
+      patch("/jobs/#{id}", {}, body)
+    end
+
+    def delete_job(id)
+      delete("/jobs/#{id}")
+    end
+
+    def publish_job(id)
+      post("/jobs/#{id}/publish")
+    end
+
+    def unpublish_job(id)
+      post("/jobs/#{id}/unpublish")
+    end
+
+    def restore_job(id)
+      patch("/jobs/#{id}/restore")
+    end
+
+    def job_counts
+      get("/jobs/counts")
+    end
+
+    def bulk_draft_jobs(job_ids)
+      post("/jobs/bulk_draft", {}, { job_ids: Array(job_ids).join(",") })
+    end
+
+    def bulk_publish_jobs(job_ids)
+      post("/jobs/bulk_publish", {}, { job_ids: Array(job_ids).join(",") })
+    end
+
+    def bulk_expire_jobs(job_ids)
+      post("/jobs/bulk_expire", {}, { job_ids: Array(job_ids).join(",") })
+    end
+
+    def bulk_destroy_jobs(job_ids)
+      post("/jobs/bulk_destroy", {}, { job_ids: Array(job_ids).join(",") })
+    end
+
+    # Membership Subscriptions
+
+    def membership_subscriptions(params = {})
+      get("/membership_subscriptions", params)
+    end
+
+    def grant_membership_subscription(body)
+      post("/membership_subscriptions", {}, body)
+    end
+
+    def membership_subscription(external_ref)
+      get("/membership_subscriptions/#{external_ref}")
+    end
+
+    def revoke_membership_subscription(external_ref)
+      delete("/membership_subscriptions/#{external_ref}")
+    end
+
+    # Membership Purchases
+
+    def membership_purchases(params = {})
+      get("/membership_purchases", params)
+    end
+
+    def grant_membership_purchase(body)
+      post("/membership_purchases", {}, body)
+    end
+
+    def membership_purchase(external_ref)
+      get("/membership_purchases/#{external_ref}")
+    end
+
+    def revoke_membership_purchase(external_ref)
+      delete("/membership_purchases/#{external_ref}")
+    end
+
+    # Blog Posts
+
+    def blog_posts(params = {})
+      get("/blog_posts", params)
+    end
+
+    def create_blog_post(body)
+      post("/blog_posts", {}, body)
+    end
+
+    def blog_post(id)
+      get("/blog_posts/#{id}")
+    end
+
+    def update_blog_post(id, body)
+      patch("/blog_posts/#{id}", {}, body)
+    end
+
+    def delete_blog_post(id)
+      delete("/blog_posts/#{id}")
+    end
+
+    def publish_blog_post(id)
+      post("/blog_posts/#{id}/publish")
+    end
+
+    def unpublish_blog_post(id)
+      post("/blog_posts/#{id}/unpublish")
+    end
+
+    # Job Payments
+
+    def job_payments(params = {})
+      get("/job_payments", params)
+    end
+
+    def grant_job_payment(body)
+      post("/job_payments", {}, body)
+    end
+
+    def job_payment(external_ref)
+      get("/job_payments/#{external_ref}")
+    end
+
+    def revoke_job_payment(external_ref, unpublish: true)
+      delete("/job_payments/#{external_ref}", { unpublish: unpublish })
+    end
+
+    # Prices
+
+    def prices(params = {})
+      get("/prices", params)
+    end
+
+    def price(id)
+      get("/prices/#{id}")
+    end
+
+    # Employer Products
+
+    def employer_products(params = {})
+      get("/employer_products", params)
+    end
+
+    def employer_product(id)
+      get("/employer_products/#{id}")
+    end
+
+    # Employer Entitlements
+
+    def employer_entitlements(params = {})
+      get("/employer_entitlements", params)
+    end
+
+    def grant_employer_entitlement(body)
+      post("/employer_entitlements", {}, body)
+    end
+
+    def employer_entitlement(external_ref)
+      get("/employer_entitlements/#{external_ref}")
+    end
+
+    def cancel_employer_entitlement(external_ref)
+      delete("/employer_entitlements/#{external_ref}")
+    end
+
+    # Candidate Entitlements
+
+    def candidate_entitlements(params = {})
+      get("/candidate_entitlements", params)
+    end
+
+    def grant_candidate_entitlement(body)
+      post("/candidate_entitlements", {}, body)
+    end
+
+    def candidate_entitlement(external_ref)
+      get("/candidate_entitlements/#{external_ref}")
+    end
+
+    def cancel_candidate_entitlement(external_ref)
+      delete("/candidate_entitlements/#{external_ref}")
+    end
+
+    private
+
+    def configure_request(request)
+      request["Authorization"] = "Bearer #{@api_key}"
+    end
+  end
+end

data/lib/job_boardly_api/headless_client.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module JobBoardlyApi
+  class HeadlessClient < BaseClient
+    DEFAULT_BASE_URL = "https://api.jobboardly.com/headless/v1"
+
+    def initialize(board_host: nil, board_id: nil)
+      if board_host
+        url = "https://#{board_host}/headless/v1"
+      elsif board_id
+        url = "#{DEFAULT_BASE_URL}/boards/#{board_id}"
+      else
+        raise ArgumentError, "Either board_host or board_id is required"
+      end
+      super(base_url: url)
+    end
+
+    def bootstrap
+      get("/bootstrap")
+    end
+
+    def create_subscriber(body)
+      post("/subscribers", {}, body)
+    end
+
+    def jobs(params = {})
+      get("/jobs", params)
+    end
+
+    def job(id)
+      get("/jobs/#{id}")
+    end
+
+    def categories
+      get("/categories")
+    end
+
+    def arrangements
+      get("/arrangements")
+    end
+
+    def places(params = {})
+      get("/places", params)
+    end
+
+    def blog_posts(params = {})
+      get("/blog_posts", params)
+    end
+
+    def blog_post(slug)
+      get("/blog_posts/#{slug}")
+    end
+
+    def page(path)
+      get("/pages/#{path}")
+    end
+
+    def employer_products
+      get("/employer_products")
+    end
+
+    def candidate_products
+      get("/candidate_products")
+    end
+
+    def membership_plans
+      get("/membership_plans")
+    end
+  end
+end

data/lib/job_boardly_api/response.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+require "ostruct"
+
+module JobBoardlyApi
+  class Response
+    attr_reader :raw_response, :body, :status, :headers
+
+    def initialize(response)
+      @raw_response = response
+      @status = response.code.to_i
+      @headers = response.each_header.to_h
+      @body = parse_body(response.body)
+    end
+
+    def success?
+      (200..299).cover?(@status)
+    end
+
+    def to_object
+      return nil if @body.nil?
+
+      JSON.parse(JSON.generate(@body), object_class: OpenStruct)
+    end
+
+    private
+
+    def parse_body(body)
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+  end
+end

data/lib/job_boardly_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JobBoardlyApi
+  VERSION = "0.1.0"
+end

data/lib/job_boardly_api.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "job_boardly_api/version"
+require_relative "job_boardly_api/response"
+require_relative "job_boardly_api/base_client"
+require_relative "job_boardly_api/client"
+require_relative "job_boardly_api/headless_client"
+
+module JobBoardlyApi
+  class Error < StandardError; end
+end

data/sig/job_boardly_api.rbs

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

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: job_boardly_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- William Kennedy
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby wrapper around the Jobboardly Management and Headless Board APIs.
+email:
+- williamkennedyjnr@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ruby.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/job_boardly_api.rb
+- lib/job_boardly_api/base_client.rb
+- lib/job_boardly_api/client.rb
+- lib/job_boardly_api/headless_client.rb
+- lib/job_boardly_api/response.rb
+- lib/job_boardly_api/version.rb
+- sig/job_boardly_api.rbs
+homepage: https://github.com/williamkennedy/job_boardly_api
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/williamkennedy/job_boardly_api
+  source_code_uri: https://github.com/williamkennedy/job_boardly_api
+  changelog_uri: https://github.com/williamkennedy/job_boardly_api/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: A Ruby wrapper around the Jobboardly API.
+test_files: []