{"id":42925045,"url":"https://github.com/tulibraries/primo","last_synced_at":"2026-01-30T18:07:42.182Z","repository":{"id":27534559,"uuid":"109992918","full_name":"tulibraries/primo","owner":"tulibraries","description":"API wrapper for ExLibres Primo APIs","archived":false,"fork":false,"pushed_at":"2026-01-28T16:24:46.000Z","size":416,"stargazers_count":4,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-29T07:21:00.587Z","etag":null,"topics":["librarysearch"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tulibraries.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-11-08T15:22:23.000Z","updated_at":"2026-01-28T16:24:36.000Z","dependencies_parsed_at":"2025-12-14T15:05:45.734Z","dependency_job_id":null,"html_url":"https://github.com/tulibraries/primo","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tulibraries/primo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tulibraries%2Fprimo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tulibraries%2Fprimo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tulibraries%2Fprimo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tulibraries%2Fprimo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tulibraries","download_url":"https://codeload.github.com/tulibraries/primo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tulibraries%2Fprimo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28917034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T16:37:38.804Z","status":"ssl_error","status_checked_at":"2026-01-30T16:37:37.878Z","response_time":66,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["librarysearch"],"created_at":"2026-01-30T18:07:42.027Z","updated_at":"2026-01-30T18:07:42.174Z","avatar_url":"https://github.com/tulibraries.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Primo [![Build Status](https://travis-ci.org/tulibraries/primo.svg?branch=main)](https://travis-ci.org/tulibraries/primo)\n\nA client that wraps the Primo PNX REST API. The primary motivator for this\nwrapper is to set up the authentication against the Primo PNX server in a\ncanonical and configurable way and to guard against changes and thus create\ndependencies to known stable fields.\n\n## Installation\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'primo'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install primo\n\n## Usage\n\n### Configuration\nYou'll need to configure the Primo gem to ensure you query the appropriate data. To do so in a rails app, create config/initializers/primo.rb with :\n\n```ruby\nPrimo.configure do |config|\n  # An API Key is required for the hosted environment.\n  config.apikey     = 'EXAMPLE_PRIMO_API_KEY'\n\n  # An Institutation value is required for the local environment.\n  config.inst     = 'EXAMPLE_INSTITUTION'\n\n  # Primo gem defaults to querying Ex Libris's North American  Api servers. You can override that here.\n  config.region   = \"https://api-eu.hosted.exlibrisgroup.com\n\n  # By dafault advance queries are combined using the :AND logical operator.\n  config.operator = :AND\n\n  # By default queries use the :title field\n  config.field = :sub\n\n  # By default queries use the :contains precision\n  config.precision = :exact\n\n  # By default by id queries use the :L context\n  config.context = :PC\n\n  # By default the environment is assumed to be :hosted\n  config.environment = :local\n\n  # By default vid will be nil\n  config.vid = \"MYVID\"\n\n  # By default scope will be nil\n  config.scope = \"pci_scope\"\n\n  # By default the pcAvailability is set to false\n  config.pcavailability = false\n\n  # By default enable_loggagle is set to false\n  config.enable_loggagle = false\n\n  # By default timeout is set to 5 seconds\n  config.timeout = 10\n\n  # By default retries is set to 3 times\n  config.retries = 3\n\n  # By default we validate parameters.\n  config.validate_parameters = false\n\n  # We do not enable primo request logs by default\n  config.enable_log_requests = false\n\n  # By default we use the built in Ruby logger, but you can set it to another logger\n  config.logger = Logger.new(\"log/primo_requests.log\")\n\n  # Log level is set to :info by default\n  config.log_level = :info\n\n  # Log format is set to :logstash by deafult\n  config.log_format = :logstash\n\n  # debugging output is disabled by default\n  config.enable_debug_output = false\n\n  # The debug_output_stream is set to $stderr by default\n  config.debug_output_stream = $stderr\nend\n```\nNow you can access those configuration attributes with `Primo.configuration.apikey`\n\n### Making Requests\n\n#### Making simple requests\nSimple requests are easy:\n\n* Pass a string and you will query titles containing the string (the default field and precison used are configurable)\n\n```\nPrimo.find(\"otter\")\n```\n\nor\n\n```\nPrimo.find_by_id(\"foobar\")\n```\n\n#### Making More advanced requests\n* `Primo.find_by_id` accepts a hash in order to pass in context or other attributes as defined in the [Primo PNX REST API](https://developers.exlibrisgroup.com/primo/apis/webservices/rest/pnxs) docs.\n\n```ruby\nPrimo.find_by_id(id: \"foo\", context: :PC)\n```\n\n* `Primo.find` also accepts a hash of attributes as defined in the [Primo PNX REST API](https://developers.exlibrisgroup.com/primo/apis/webservices/rest/pnxs) page and returns the API request result wrapped in an instance of the `Primo::Search` class.\n\n`q` is the only required parameter for this hash and it is either composed of a `Primo::Search::Query` object, or a hash that is converted into a `Primo::Search::Query` object.\n\n```ruby\n  # q is an instance of Primo::Search::Query, see the next section for details.\n  # defaults for :field and :precision are added if not included in the hash.\n  response = Primo.find q: { field: sub:, precision: :contains, value: \"goats\" }\n\n  response.docs.first.date\n  response.info\n  response.facets\n  # ...\n```\n\n#### (Advanced) Generating a Query object\n```ruby\nquery = Primo::Search::Query.new(\n    precision: :exact,\n    field: :facet_local23,\n    value: \"bar\",\n    operator: :AND)\n```\nThis API wrapper validates the `query` object according the specifications documented in [the Ex Libris Api docs](https://developers.exlibrisgroup.com/primo/apis/webservices/xservices/search/briefsearch) for the `query` field.\n\n#### (Advanced) Adding Facets to a query\n\nOnce you have your base query, you can add facet queries to limit the search\n\n```ruby\nquery = Primo::Search::Query.new(...)\n\nquery.facet(\n  { field: \"creator\",\n    value: \"Williams, John\",\n    })\n\nresponse = Primo.find(q: query)    \n```\n\n##### Exclude Facets\n\nBy default, facets are *include facets*, so that records returned should include the value\nin the field. You can also set *exclude facets* for results that should not contain a value\nin a given field, by setting the `operator` parameter to `:exclude`\n\n```ruby\nquery.facet(\n  { field: \"creator\",\n    value: \"Williams, John\",\n    operator: :exclude\n    })\n\n```\n##### Multiple Facets\n\nYou can also call facet multiple times to apply multiple facets\n```ruby\nquery.facet({\n  field: \"creator\",\n  value: \"Williams, John\",\n}).facet({\n    field: \"format\",\n    value: \"Book\"\n    })\n```\n\n##### Date Range Facet\n\nYou can also add a date range facet (inclusive or execlusive)\n\n```ruby\nquery.date_range_facet({\n  min: 1973, # defauls to 0\n  max: 2012, # defaults to 9999\n  operator: :exclude, #defaults inclusive\n}).facet({\n    field: \"format\",\n    value: \"Book\"\n    })\n```\n\n\n#### Generating advanced queries with advanced operators\n```ruby\nquery = Primo::Search::Query.new(\n    precision: :exact,\n    field: :facet_local23,\n    value: \"bar\",\n    operator: :AND)\n\nquery.and( field: :title, precision: :contains, value: \"foo\")\nquery.or( field: :title, precision: :contains, value: \"foo\")\nquery.not( field: :title, precision: :contains, value: \"foo\")\n```\n\n#### Generating an advanced query with the `#build` method:\n```ruby\nq1 = field: :title, precision: :contains, value: \"foo\"\nq1 = field: :title, precision: :contains, value: \"bar\"\nPrimo::Search::Query::build([q1, q2])\n```\n\nThis API wrapper validates the `query` object according the specifications documented in [the Ex Libris Api docs](https://developers.exlibrisgroup.com/primo/apis/webservices/xservices/search/briefsearch) for the `query` field.\n\n### Logging\n\n#### Using :enable_loggable\nThis gem exposes a loggable interface to responses.  Thus a response will respond to `loggable` and return a hash with state values that may be of use to log.\n\nAs a bonus, when we enable this feature using the `enable_loggable` configuration, error messages will contain the loggable values and be formatted as JSON.\n\n#### Using logging configuration.\nYou can configure logging via the following configurations:\n* `enable_log_requests`: (`true/false`)\n* `log_level`\n* `log_format`\n* `logger`\n\nThe logger can be any logger including the Rails.logger.  This logging feature is provided through [HTTParty](https://www.rubydoc.info/github/jnunemaker/httparty/HTTParty/ClassMethods#logger-instance_method).\n\n### Debugging requests\nYou can configure debugging requests by setting the `enable_debug_output` configuration which is false by default. This feature is also provided through [HTTParty](https://www.rubydoc.info/github/jnunemaker/httparty/HTTParty/ClassMethods#debug_output-instance_method).\n\nYou can configure the `debug_output_stream` which is set to `$stderr` by default.\n\n\n\n## Development\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo 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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\nBug reports and pull requests are welcome on GitHub at https://github.com/tulibraries/primo. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftulibraries%2Fprimo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftulibraries%2Fprimo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftulibraries%2Fprimo/lists"}