omi-clients 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 707c10caf0cbc1fbde84af118e236e4a9790f3b9666dd93e3b8bd26408da7df5
+  data.tar.gz: 63b8ccd1e43589f4a90d80362e59dfdf9bc4c9cb97c8c1726862bebf0a4981e5
+SHA512:
+  metadata.gz: 519c17d04677cb962e43a2c2f1f7f2bb0d25a3107fab52df7dd7cb6e17e65c34c7fd0bdaab620d9e502db90eb1c200bd10b0802ed397205080afb251847edfd8
+  data.tar.gz: e6a0e09f0bd03e0840f39c58483d9d9a703e0a3047d91d00fb6065755f48ccfb93b0e6c6ab55c270c97d7b97ec882618d25d9c0f31244036938ded0b7d65d9d6

data/.ruby-version

@@ -0,0 +1 @@
+4.0.1

data/AGENTS.md

@@ -0,0 +1,33 @@
+# Omi Clients - Agent Guide
+
+Welcome to the `omi-clients` codebase! This document outlines what you need to know to work effectively in this repository.
+
+## Project Type
+This is a Ruby gem project that provides various client implementations (like `HttpClient`, `IfpiClient`, `MlcClient`, etc.) under the `Omi::Clients` module.
+
+## Essential Commands
+
+The project uses `rake` to orchestrate common tasks.
+
+* **Run all tests and linting (Default):** `bundle exec rake`
+* **Run tests only:** `bundle exec rake spec` or `bundle exec rspec`
+* **Run linting only:** `bundle exec rake rubocop` or `bundle exec rubocop`
+
+## Code Organization & Structure
+
+* **`lib/omi/clients.rb`**: The main entry point for the gem, defining the `Omi::Clients` module.
+* **`lib/omi/clients/`**: Contains the core logic and various client implementations (e.g., `http_client.rb`, `ifpi_client.rb`).
+* **`spec/`**: Contains all the RSpec tests. Follows the structure of the `lib/` directory.
+* **`HttpClient`**: The `HttpClient` module (`lib/omi/clients/http_client.rb`) provides a standardized way to make HTTP requests (`request(method:, base:, path:, ...)`).
+
+## Coding Conventions & Style
+
+* **String Literals**: Use **double quotes** for strings and string interpolation. This is strictly enforced by RuboCop in `.rubocop.yml`.
+* **Frozen String Literal**: All Ruby files should begin with `# frozen_string_literal: true`.
+* **Linting**: The project uses RuboCop. Always ensure your code passes `bundle exec rubocop` after making changes.
+
+## Testing Approach
+
+* The project uses **RSpec** for testing.
+* Tests should be placed in the `spec/` directory, mirroring the structure of the `lib/` directory.
+* Run tests frequently using `bundle exec rake spec` to verify your changes. Note that the default generated tests may contain an intentionally failing test (`expect(false).to eq(true)`), be mindful when running tests on a fresh codebase.

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-03-23
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Chris Garrett
+
+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,145 @@
+# Omi::Clients
+
+Welcome to the `omi-clients` gem! This library provides easy-to-use API clients for communicating with various music rights and data organizations:
+- **MLC Client**: Connects to The Mechanical Licensing Collective (MLC) API to search for works and matched recordings.
+- **USCO Client**: Connects to the US Copyright Office API to search public records.
+- **IFPI Client**: Connects to the IFPI ISRC API (via SoundExchange) to search for recordings and ISRCs.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'omi-clients'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install omi-clients
+```
+
+## Usage
+
+Below are examples of how to initialize and use each of the available clients.
+
+### MLC Client
+
+The `MlcClient` allows you to search for works and recordings in The Mechanical Licensing Collective database.
+
+```ruby
+require 'omi/clients'
+
+client = MlcClient.new
+
+# Search for a work by title
+works = client.search_works('yesterday', size: 1)
+```
+
+**Example Response:**
+```json
+{
+  "content": [
+    {
+      "id": 992933336,
+      "title": "YESTERDAY",
+      "songCode": "YP8CWO",
+      "writers": [
+        {
+          "fullName": "JESSE J SANDERS",
+          "ipiNumber": "00819749198",
+          "roleCode": 11
+        }
+      ]
+    }
+  ],
+  "number": 1,
+  "size": 1,
+  "totalElements": 10835
+}
+```
+
+### USCO Client
+
+The `UscoClient` interacts with the US Copyright Office API to query registered copyright records.
+
+```ruby
+require 'omi/clients'
+
+client = UscoClient.new
+
+# Search the USCO public records
+records = client.search('yesterday', size: 1)
+```
+
+**Example Response:**
+```json
+{
+  "metadata": {
+    "took_ms": 43,
+    "hit_count": 31849,
+    "max_score": 54.251675
+  },
+  "data": [
+    {
+      "score": 54.251675,
+      "hit": {
+        "author": ["MARVIN F. MOODY"],
+        "title_of_work": ["Today and Yesterday"],
+        "registration_number": ["AA 448496"],
+        "registration_status": "published",
+        "first_published_date": ["1944-02-10"]
+      }
+    }
+  ]
+}
+```
+
+### IFPI Client
+
+The `IfpiClient` searches the IFPI ISRC database to find recording information and ISRCs. *Note: You must call `login!` before performing any searches to fetch the required authentication token.*
+
+```ruby
+require 'omi/clients'
+
+client = IfpiClient.new
+
+# Fetch authentication token
+client.login!
+
+# Search for recordings (number must be between 10 and 100)
+recordings = client.search_recordings(recording_title: 'yesterday', number: 10)
+```
+
+**Example Response:**
+```json
+{
+  "numberOfRecordings": 10000,
+  "show_releases": true,
+  "recordings": [
+    {
+      "duration": "5:23",
+      "recordingType": "Audio",
+      "recordingYear": "2017",
+      "recordingArtistName": "Eric Reed",
+      "isrc": "USL4Q1776253",
+      "recordingTitle": "Yesterday - Yesterdays",
+      "id": "USL4Q1776253"
+    }
+  ]
+}
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run the tests and linter. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/omi/clients/http_client.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+# A module to make HTTP requests
+module HttpClient
+  def request(method:, base:, path:, **options)
+    uri = build_uri(base, path, options[:query])
+    req = prepare_request(method, uri, options)
+    res = execute_request(req, uri)
+    handle_response(res)
+  end
+
+  private
+
+  def prepare_request(method, uri, options)
+    req = build_request(method, uri)
+    headers = options[:headers] || {}
+    default_headers.merge(headers).each { |k, v| req[k] = v }
+    req.body = options[:body] if options[:body]
+    req
+  end
+
+  def execute_request(req, uri)
+    Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+      http.request(req)
+    end
+  end
+
+  def handle_response(res)
+    raise "#{self.class} API error: #{res.code} – #{res.body}" unless res.is_a?(Net::HTTPSuccess)
+
+    JSON.parse(res.body)
+  end
+
+  def build_uri(base, path, query)
+    uri = URI.join(base.end_with?('/') ? base : "#{base}/", path)
+    uri.query = URI.encode_www_form(query) if query&.any?
+    uri
+  end
+
+  def build_request(method, uri)
+    case method
+    when :get  then Net::HTTP::Get.new(uri)
+    when :post then Net::HTTP::Post.new(uri)
+    else
+      raise ArgumentError, "Unsupported HTTP method: #{method}"
+    end
+  end
+end

data/lib/omi/clients/ifpi_client.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'literal'
+require_relative './http_client'
+
+# Client for IFPI ISRC API
+class IfpiClient < Literal::Object
+  include HttpClient
+
+  API_BASE   = 'https://isrc-api.soundexchange.com/api/ext'
+  USER_AGENT = 'Mozilla/5.0 (X11; Linux x86_64) ' \
+               'AppleWebKit/537.36 (KHTML, like Gecko) ' \
+               'Chrome/138.0.0.0 Safari/537.36'
+  TOKEN_TTL  = 3600
+
+  prop :token, _String?
+  prop :token_fetched_at, _String?
+
+  def login!
+    resp = request(
+      method: :get,
+      base: API_BASE,
+      path: 'login',
+      headers: login_headers
+    )
+
+    @token = resp.fetch('token')
+    @token_fetched_at = Time.now
+    self
+  end
+
+  def search_recordings(**args)
+    raise 'Call login! first' unless valid_token?
+
+    request(
+      method: :post,
+      base: API_BASE,
+      path: 'recordings',
+      body: build_search_payload(**args).to_json,
+      headers: default_headers.merge('Authorization' => "Token #{@token}")
+    )
+  end
+
+  private
+
+  def build_search_payload(**kwargs)
+    {
+      searchFields: {
+        recordingArtistName: { value: kwargs[:recording_artist_name].to_s },
+        recordingTitle: { value: kwargs[:recording_title].to_s },
+        releaseName: { value: kwargs[:release_name].to_s }
+      },
+      start: kwargs.fetch(:start, 0),
+      number: kwargs.fetch(:number, 100),
+      showReleases: kwargs.fetch(:show_releases, true)
+    }
+  end
+
+  def valid_token?
+    @token &&
+      @token_fetched_at &&
+      (Time.now - @token_fetched_at) < TOKEN_TTL
+  end
+
+  def default_headers
+    {
+      'Accept' => 'application/json',
+      'Content-Type' => 'application/json',
+      'User-Agent' => USER_AGENT
+    }
+  end
+
+  def login_headers
+    {
+      'Accept' => 'application/json',
+      'Authorization' => 'Token undefined',
+      'Content-Type' => 'application/json',
+      'User-Agent' => USER_AGENT
+    }
+  end
+end

data/lib/omi/clients/mlc_client.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative './http_client'
+
+# Client for MLC API
+class MlcClient
+  include HttpClient
+
+  API_BASE = 'https://api.ptl.themlc.com/api'
+  API_2_BASE = 'https://api.ptl.themlc.com/api2v/public'
+  DSP_BASE   = 'https://api.ptl.themlc.com/api/dsp-recording'
+  USER_AGENT = 'Mozilla/5.0 (X11; Linux x86_64) ' \
+               'AppleWebKit/537.36 (KHTML, like Gecko) ' \
+               'Chrome/138.0.0.0 Safari/537.36'
+
+  def search_works(title, writer_names: nil, page: 1, size: 100)
+    request(
+      method: :post,
+      base: API_2_BASE,
+      path: 'search/works',
+      query: { page:, size: },
+      body: { title:, writerFullNames: writer_names }.compact.to_json
+    )
+  end
+
+  def matched_recordings(song_code, limit: 100, page: 1, order: 'matchedAmount', direction: 'desc')
+    request(
+      method: :get,
+      base: DSP_BASE,
+      path: "matched/#{song_code}",
+      query: { limit:, page:, order:, direction: }
+    )
+  end
+
+  def get_work(work_id)
+    request(
+      method: :get,
+      base: API_BASE,
+      path: "catalog/work/#{work_id}"
+    )
+  end
+
+  private
+
+  def default_headers
+    {
+      'Accept' => 'application/json',
+      'User-Agent' => USER_AGENT,
+      'Content-Type' => 'application/json'
+    }
+  end
+end

data/lib/omi/clients/usco_client.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative './http_client'
+
+# Client for US Copyright Office API
+class UscoClient
+  include HttpClient
+
+  API_BASE = 'https://api.publicrecords.copyright.gov'
+
+  USER_AGENT = 'Mozilla/5.0 (X11; Linux x86_64) ' \
+               'AppleWebKit/537.36 (KHTML, like Gecko) ' \
+               'Chrome/138.0.0.0 Safari/537.36'
+
+  def search(query, **options)
+    request(
+      method: :get,
+      base: API_BASE,
+      path: 'search_service_external/simple_search_dsl',
+      query: build_search_query(query, **options)
+    )
+  end
+
+  private
+
+  def build_search_query(query, **options)
+    {
+      query:,
+      page_number: options.fetch(:page, 1),
+      records_per_page: options.fetch(:size, 100),
+      field_type: options.fetch(:field_type, 'keyword'),
+      sort_order: options.fetch(:sort, 'asc'),
+      model: options.fetch(:model, '')
+    }
+  end
+
+  def default_headers
+    {
+      'Accept' => 'application/json',
+      'User-Agent' => USER_AGENT,
+      'Content-Type' => 'application/json'
+    }
+  end
+end

data/lib/omi/clients/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Omi
+  module Clients
+    VERSION = '0.1.0'
+  end
+end

data/lib/omi/clients.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'clients/version'
+require 'literal'
+require_relative 'clients/http_client'
+require_relative 'clients/ifpi_client'
+require_relative 'clients/mlc_client'
+require_relative 'clients/usco_client'
+
+module Omi
+  module Clients
+    class Error < StandardError; end
+    # Your code goes here...
+  end
+end

data/sig/omi/clients.rbs

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

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: omi-clients
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Open Music Initiative
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: literal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+description: Access datasets like the MLC, IFPI and USCO to access data critical to
+  songwriters and artists.
+email:
+- chris@chrsgrrtt.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ruby-version"
+- AGENTS.md
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/omi/clients.rb
+- lib/omi/clients/http_client.rb
+- lib/omi/clients/ifpi_client.rb
+- lib/omi/clients/mlc_client.rb
+- lib/omi/clients/usco_client.rb
+- lib/omi/clients/version.rb
+- sig/omi/clients.rbs
+homepage: https://github.com/open-music-initiative/omi-clients
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/open-music-initiative/omi-clients
+  source_code_uri: https://github.com/open-music-initiative/omi-clients
+  changelog_uri: https://github.com/open-music-initiative/omi-clients
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.1
+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 range of clients to access critical music data repositories.
+test_files: []