berkeley_library-tind 0.4.0

data/.ruby-version

@@ -0,0 +1 @@
+2.7

data/.simplecov

@@ -0,0 +1,8 @@
+require 'simplecov-rcov'
+
+SimpleCov.start 'rails' do
+  add_filter 'module_info.rb'
+  coverage_dir 'artifacts'
+  formatter SimpleCov::Formatter::RcovFormatter
+  minimum_coverage 100
+end

data/.yardopts

@@ -0,0 +1 @@
+--no-private --protected lib/**/*.rb -m markdown

data/CHANGES.md

@@ -0,0 +1,58 @@
+# 0.4.0 (2021-08-19)
+
+- Rename to `BerkeleyLibrary::TIND` in prep for move to GitHub
+
+# 0.3.3 (2021-08-05)
+
+- Send a custom `User-Agent` header to deal with new TIND firewall rules.
+
+# 0.3.2 (2021-07-29)
+
+- Loosen `spec.required_ruby_version` to support Ruby 3.x
+
+# 0.3.1 (2021-05-17)
+
+- `API#get` now raises an `APIException` with a simulated '404 Not Found'
+  status if `UCBLIT::TIND::Config.base_uri` is not set, or is blank.
+
+# 0.3.0 (2021-05-11)
+
+- Extracts `MARCExtensions` into a separate gem, 
+  [`ucblit-marc`](https://git.lib.berkeley.edu/lap/ucblit-marc/edit).
+
+# 0.2.4 (2021-05-06)
+
+- `API#get` now raises an `APIException` with a simulated '401 Unauthorized' status 
+  if `UCBLIT::TIND::Config.api_key` is not set.
+
+# 0.2.3 (2021-05-04)
+
+- `UCBLIT::TIND::Export`:
+  - new method `#exporter_for` returns a `UCBLIT::TIND::Exporter` but doesn't
+    export immediately.
+  - `#export` now raises `NoResultsError` if no records are returned.
+
+- `UCBLIT::TIND::Exporter` exposes an `any_results?` method that returns false if
+  there are no results to export.
+
+# 0.2.2 (2021-05-03)
+
+- `UCBLIT::TIND::API::Search` now gracefully returns an empty result when it gets the 500 Internal
+  Server Error that TIND thinks is an acceptable empty search result, instead of raising an exception.
+
+# 0.2.1 (2021-04-02)
+
+- `bin/tind-export` script now supports passing an environment file on the command line with the
+  `-e` option; `-e` with no arguments reads from `.env` in the current working directory.
+- Table metrics (font size, line height, max column width etc.) can now be customized
+  with environment variables (see [`UCBLIT::TIND::Export::Config`](lib/berkeley_library/tind/export/config.rb))
+
+# 0.2.0 (2021-03-31)
+
+- Columns in exported OpenOffice / LibreOffice that should not be edited are now marked
+  in red but **not** protected.
+- API key configuration has moved from `UCBLIT::TIND::API` to `UCBLIT::TIND::Config`.
+
+# 0.1.0 (2021-03-12)
+
+- Initial prerelease

data/Dockerfile

@@ -0,0 +1,57 @@
+# =============================================================================
+# Target: base
+
+FROM ruby:2.7-alpine AS base
+
+RUN apk --no-cache --update upgrade && \
+    apk --no-cache add \
+        bash \
+        ca-certificates \
+        git \
+        libc6-compat \
+        openssl \
+        tzdata \
+        xz-libs \
+    && rm -rf /var/cache/apk/*
+
+WORKDIR /opt/app
+
+# =============================================================================
+# Target: development
+#
+
+FROM base AS development
+
+# Install system packages needed to build gems with C extensions.
+RUN apk --update --no-cache add \
+        build-base \
+        coreutils \
+        git \
+    && rm -rf /var/cache/apk/*
+
+# The base image ships bundler 1.17.2, but we want something more recent
+RUN gem install bundler -v 2.1.4
+
+# Copy codebase to WORKDIR. Unlike application projects, for a gem project
+# we need to do this before running `bundle install`, in order for the gem
+# we're building to be able to "install" itself.
+COPY . .
+
+# Install gems.
+RUN bundle install --path=/usr/local/bundle
+
+# =============================================================================
+# Target: production
+
+FROM base AS production
+
+# Copy the built codebase from the dev stage
+COPY --from=development /opt/app /opt/app
+COPY --from=development /usr/local/bundle /usr/local/bundle
+
+# Sanity-check that everything was installed correctly and still runs in the
+# slimmed-down production image.
+RUN bundle config set deployment 'true'
+RUN bundle install --local --path=/usr/local/bundle
+
+CMD ['bundle', 'exec', 'rake']

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Jenkinsfile

@@ -0,0 +1,18 @@
+#!/usr/bin/env groovy
+
+dockerComposePipeline(
+    commands: [
+        'bundle exec rake coverage',
+        'bundle exec rake rubocop',
+        'bundle exec rake bundle:audit',
+        'bundle exec rake gem'
+    ],
+    artifacts: [
+        junit: 'artifacts/rspec/**/*.xml',
+        html : [
+            'Code Coverage': 'artifacts/rcov',
+            'RuboCop'      : 'artifacts/rubocop'
+        ],
+        raw  : ['artifacts/**/*.gem']
+    ]
+)

data/LICENSE.md

@@ -0,0 +1,21 @@
+# The MIT License (MIT)
+
+Copyright © 2021 The Regents of the University of California
+
+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,73 @@
+# BerkeleyLibrary::TIND
+
+[![Build Status](https://github.com/BerkeleyLibrary/tind/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/BerkeleyLibrary/tind/actions/workflows/build.yml)
+[![Gem Version](https://img.shields.io/gem/v/berkeley_library-tind.svg)](https://github.com/BerkeleyLibrary/tind/releases)
+
+Utility gem for working with the TIND DA digital archive.
+
+## Configuration
+
+To access the TIND API, you will need to set:
+
+1. the base URL for your TIND installation (e.g. `https://digicoll.lib.berkeley.edu/`)
+2. the TIND API key (see the "[API Token Generator](https://docs.tind.io/article/2xaplzx9cn-api-token-generator)"
+   article on [`docs.tind.io`](https://docs.tind.io). TIND's code and
+   docs are inconsistent in their use of "token" and "key". The UI calls
+   it a "key", so that's the term we use here.)
+
+These can be set directly, via accessors in the `BerkeleyLibrary::TIND::Config` module;
+if they are not set, a value will be read from the environment, and if no 
+value is present in the environment and Rails is loaded, from the Rails
+application configuration (`Rails.application.config`).
+
+| Value         | Config    | ENV                 | Rails            |
+| ---           | ---         | ---                 | ---              |
+| TIND base URI | `:base_uri` | `LIT_TIND_BASE_URL` | `:tind_base_uri` |
+| API key       | `:api_key`  | `LIT_TIND_API_KEY`  | `:tind_api_key`  |
+
+**Note:** The TIND base URI can be set either as a string or as a `URI`
+object, but will always be returned as a `URI` object, and an invalid
+string setting will raise `URI::InvalidURIError`.
+
+## Command-line tool: `tind-export`
+
+The `tind-export` command allows you to list TIND collections, or to 
+export a TIND collection from the command line. (If the gem is installed,
+`tind-export` should be in your `$PATH`. If you've cloned the gem source,
+you can invoke it with `bin/tind-export` from the project root directory.)
+
+Examples:
+
+1. list collections
+
+   ```sh
+   tind-export --list-collections
+   ```
+
+2. export a collection as an OpenOffice/LibreOffice spreadsheet
+
+   ```sh
+   tind-export -o lincoln-papers.ods 'Abraham Lincoln Papers'
+   ```
+
+3. export a collection as an OpenOffice/LibreOffice spreadsheet in exploded XML format,
+   where `lincoln-papers` is a directory
+
+   ```sh
+   tind-export -f ODS -o lincoln-papers 'Abraham Lincoln Papers'
+   ```
+
+   (Note that OpenOffice itself and many other tools get confused by the extra text
+   nodes in the pretty-printed files and won't read them properly; this feature
+   is mostly for debugging.)
+
+4. export a collection as CSV, to standard output
+
+   ```sh
+   tind-export -f CSV 'Abraham Lincoln Papers'
+   ```
+
+For the full list of options, type `tind-export --help`. Note that you can set
+the TIND base URL and API key either via the environment, as above, or as options
+passed to the `tind-export` command. If both an explicit option and an environment
+variable are set for either, the explicit option takes precedence.

data/Rakefile

@@ -0,0 +1,20 @@
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('Gemfile', __dir__)
+require 'bundler/setup' # Set up gems listed in the Gemfile.
+
+# ------------------------------------------------------------
+# Application code
+
+File.expand_path('lib', __dir__).tap do |lib|
+  $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+end
+
+# ------------------------------------------------------------
+# CI
+
+ENV['RAILS_ENV'] = 'test' if ENV['CI']
+
+# ------------------------------------------------------------
+# Custom tasks
+
+desc 'Run tests, check test coverage, check code style, check for vulnerabilities, build gem'
+task default: %i[coverage rubocop bundle:audit gem]

data/berkeley_library-tind.gemspec

@@ -0,0 +1,50 @@
+File.expand_path('lib', __dir__).tap do |lib|
+  $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+end
+
+ruby_version = '>= 2.7'
+
+require 'berkeley_library/tind/module_info'
+
+Gem::Specification.new do |spec|
+  spec.name = BerkeleyLibrary::TIND::ModuleInfo::NAME
+  spec.author = BerkeleyLibrary::TIND::ModuleInfo::AUTHOR
+  spec.email = BerkeleyLibrary::TIND::ModuleInfo::AUTHOR_EMAIL
+  spec.summary = BerkeleyLibrary::TIND::ModuleInfo::SUMMARY
+  spec.description = BerkeleyLibrary::TIND::ModuleInfo::DESCRIPTION
+  spec.license = BerkeleyLibrary::TIND::ModuleInfo::LICENSE
+  spec.version = BerkeleyLibrary::TIND::ModuleInfo::VERSION
+  spec.homepage = BerkeleyLibrary::TIND::ModuleInfo::HOMEPAGE
+
+  spec.files = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+  spec.executables << 'tind-export'
+
+  spec.required_ruby_version = ruby_version
+
+  spec.add_dependency 'berkeley_library-logging', '~> 0.2'
+  spec.add_dependency 'berkeley_library-marc', '~> 0.2'
+  spec.add_dependency 'ice_nine', '~> 0.11'
+  spec.add_dependency 'marc', '~> 1.0'
+  spec.add_dependency 'rchardet', '~> 1.8'
+  spec.add_dependency 'rest-client', '~> 2.1'
+  spec.add_dependency 'rubyzip', '~> 2.3'
+  spec.add_dependency 'typesafe_enum', '~> 0.3'
+
+  spec.add_development_dependency 'bundle-audit', '~> 0.1'
+  spec.add_development_dependency 'ci_reporter_rspec', '~> 1.0'
+  spec.add_development_dependency 'colorize', '~> 0.8'
+  spec.add_development_dependency 'dotenv', '~> 2.7'
+  spec.add_development_dependency 'listen', '>= 3.0.5', '< 3.2'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'roo', '~> 2.8'
+  spec.add_development_dependency 'rspec', '~> 3.10'
+  spec.add_development_dependency 'rubocop', '= 1.11'
+  spec.add_development_dependency 'rubocop-rake', '~> 0.5'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.2'
+  spec.add_development_dependency 'ruby-prof', '~> 0.17.0'
+  spec.add_development_dependency 'simplecov', '~> 0.21'
+  spec.add_development_dependency 'simplecov-rcov', '~> 0.2'
+  spec.add_development_dependency 'webmock', '~> 3.12'
+end

data/bin/tind-export

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+begin
+  # This should work if (1) the gem is installed, or
+  # (2) we're in development and used `bundle exec`
+  require 'berkeley_library/tind'
+rescue LoadError
+  # If we're in development, `require 'bundler/setup'`
+  # is roughly equivalent to `bundle exec`
+  require 'bundler/setup'
+  require 'berkeley_library/tind'
+end
+
+BerkeleyLibrary::TIND::Export::ExportCommand.new(*ARGV).execute!

data/docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  gem:
+    build:
+      context: .
+      target: development
+    ports:
+      - target: 3000
+        published: 3000
+    restart: always
+    volumes:
+      # Note that this mounts the *entire* repo directory (including
+      # files ignored in .dockerignore when building the image)
+      - ./:/opt/app
+
+version: "3.7"

data/lib/berkeley_library/tind.rb

@@ -0,0 +1,3 @@
+require 'marc_extensions'
+
+Dir.glob(File.expand_path('tind/*.rb', __dir__)).sort.each(&method(:require))

data/lib/berkeley_library/tind/api.rb

@@ -0,0 +1 @@
+Dir.glob(File.expand_path('api/*.rb', __dir__)).sort.each(&method(:require))

data/lib/berkeley_library/tind/api/api.rb

@@ -0,0 +1,132 @@
+require 'stringio'
+require 'open-uri'
+
+require 'berkeley_library/util/uris'
+require 'berkeley_library/util/logging'
+require 'berkeley_library/tind/config'
+require 'berkeley_library/tind/api/api_exception'
+
+module BerkeleyLibrary
+  module TIND
+    module API
+      class << self
+        include BerkeleyLibrary::Util
+        include BerkeleyLibrary::Logging
+
+        # Gets the TIND API key.
+        # @return [String, nil] the TIND API key, or `nil` if not set.
+        def api_key
+          BerkeleyLibrary::TIND::Config.api_key
+        end
+
+        # Gets the value to send in the User-Agent header
+        # @return [String] the user agent
+        def user_agent
+          BerkeleyLibrary::TIND::Config.user_agent
+        end
+
+        # Gets the API base URI.
+        # @return [URI] the API base URI
+        def api_base_uri
+          return if Config.blank?((base_uri = Config.base_uri))
+
+          URIs.append(base_uri, '/api/v1')
+        end
+
+        # Gets the URI for the specified API endpoint.
+        # @param endpoint [Symbol, String] the endpoint (e.g. `:search` or `:collection`)
+        # @return [URI] the URI for the specified endpoint
+        # @raise [API::BaseURINotSet] if the TIND base URI is not set
+        def uri_for(endpoint)
+          return if Config.blank?(api_base_uri)
+
+          URIs.append(api_base_uri, endpoint)
+        end
+
+        # Makes a GET request.
+        #
+        # @overload get(endpoint, **params)
+        #   Makes a GET request to the specified endpoint with the specified parameters,
+        #   and returns the response body as a string. Example:
+        #
+        #   ```ruby
+        #   marc_xml = API.get(:search, c: 'The Bancroft Library')
+        #   XMLReader.new(marc_xml).each { |record| ... }
+        #   ```
+        #
+        #   @param endpoint [Symbol] the API endpoint, e.g. `:search` or `:collection`
+        #   @param **params [Hash] the query parameters
+        #   @return [String] the response body
+        # @overload get(endpoint, **params, &block)
+        #   Makes a GET request to the specified endpoint with the specified parameters,
+        #   and yields an `IO` that streams the response body. Example:
+        #
+        #   ```ruby
+        #   API.get(:search, c: 'The Bancroft Library') do |body|
+        #     XMLReader.new(body).each { |record| ... }
+        #   end
+        #   ```
+        #
+        #   @param endpoint [Symbol, String] the API endpoint, e.g. `:search` or `:collections`
+        #   @param **params [Hash] the query parameters
+        #   @yieldparam body [IO] the response body, as an IO stream
+        def get(endpoint, **params, &block)
+          endpoint_uri = uri_for(endpoint)
+          raise BaseURINotSet.new(endpoint, params) if Config.blank?(endpoint_uri)
+
+          logger.debug(format_request(endpoint_uri, params))
+
+          body = do_get(endpoint_uri, params)
+          return body unless block_given?
+
+          stream_response_body(body, &block)
+        end
+
+        # Returns a formatted string version of the request, suitable for
+        # logging or error messages.
+        #
+        # @param uri [URI, String] the URI
+        # @param params [Hash, nil] the query parameters
+        # @param method [String] the request method
+        def format_request(uri, params = nil, method = 'GET')
+          query_string = format_query(params)
+          uri = URIs.append(uri, '?', query_string) if query_string
+
+          "#{method} #{uri}"
+        end
+
+        def format_query(params)
+          return unless params
+          return URI.encode_www_form(params.to_hash) if params.respond_to?(:to_hash)
+
+          raise ArgumentError, "Argument #{params.inspect} does not appear to be a set of query parameters"
+        end
+
+        private
+
+        def do_get(endpoint_uri, params)
+          raise APIKeyNotSet.new(endpoint_uri, params) if Config.blank?(api_key)
+
+          begin
+            URIs.get(endpoint_uri, params, {
+                       'Authorization' => "Token #{api_key}",
+                       'User-Agent' => user_agent
+                     })
+          rescue RestClient::RequestFailed => e
+            raise APIException.wrap(e, url: endpoint_uri, params: params)
+          end
+        end
+
+        # TODO: make real body streaming work
+        def stream_response_body(body)
+          yield StringIO.new(body)
+        rescue StandardError => e
+          # We don't log the full stack trace here as we assume the block will do that
+          logger.warn("Error yielding response body: #{e}: body was: #{body}")
+          raise
+        end
+      end
+
+    end
+  end
+end