spektrix_uk 1.0.0

data/README.md

@@ -0,0 +1,181 @@
+# SpektrixUk
+
+A simple gem to pull cinemas and performances from UK independent cinemas that sell tickets through [Spektrix](https://www.spektrix.com) and spit out useful formatted info.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'spektrix_uk'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install spektrix_uk
+
+## Usage
+
+The gem conforms to the API set down in the `cinebase` gem, [andycroll/cinebase](https://github.com/andycroll/cinebase), which provides a lot of useful base vocabulary and repetitive code for this series of cinema focussed gems.
+
+Performance titles are sanitized as much as possible, removing strands,
+certificates, notes in square brackets, extras such as food or a Q&A, and
+standardizing event cinema names.
+
+No token or setup is needed. Each venue has its own Spektrix account, its
+client, and the public Spektrix API v3 at
+`https://system.spektrix.com/<client>/api/v3` lists its events and their
+instances. Each account names its attributes differently, so the gem holds a
+small configuration for each venue.
+
+| id         | Cinema                  | Client                  |
+|------------|-------------------------|-------------------------|
+| `broadway` | Broadway, Nottingham    | `broadwaynottingham`    |
+| `home`     | HOME, Manchester        | `home`                  |
+| `hpph`     | Hyde Park Picture House | `leedsheritagetheatres` |
+| `showroom` | Showroom Cinema         | `showroomworkstation`   |
+| `tyneside` | Tyneside Cinema         | `tynesidecinema`        |
+
+The ids belong to the gem and never change.
+
+### Cinema
+
+Cinemas, addresses and coordinates are held in the gem, so they make no
+requests. Every cinema's brand is `'Independent'`.
+
+``` ruby
+SpektrixUk::Cinema.all
+#=> [<SpektrixUk::Cinema ...>, <SpektrixUk::Cinema ...>, ...]
+
+cinema = SpektrixUk::Cinema.new('tyneside')
+#=> <SpektrixUk::Cinema ...>
+
+cinema.adr
+#=> {
+  street_address:   '10 Pilgrim Street',
+  extended_address: nil,
+  locality:         'Newcastle upon Tyne',
+  region:           nil,
+  postal_code:      'NE1 6QG',
+  country_name:     'United Kingdom'
+}
+
+cinema.brand
+#=> 'Independent'
+
+cinema.name
+#=> 'Tyneside Cinema'
+
+cinema.id
+#=> 'tyneside'
+
+cinema.latitude
+#=> 54.973903
+
+cinema.url
+#=> 'https://tynesidecinema.co.uk'
+```
+
+### Performances
+
+`Performance.at` returns performances for an inclusive range of showing dates,
+defaulting to today in London and the following 13 days. Any range takes two
+requests: the events with an instance in the range, and the instances. The API
+sets no limit on the range. The Leeds Heritage Theatres account answers slowly,
+in about half a minute for a year.
+
+``` ruby
+SpektrixUk::Performance.at('tyneside', from: Date.today, to: Date.today + 2)
+#=> [<SpektrixUk::Performance ...>, <SpektrixUk::Performance ...>, ...]
+
+performance = SpektrixUk::Performance.at('tyneside').first
+#=> <SpektrixUk::Performance ...>
+
+performance.film_name
+#=> 'The Grinch'
+
+performance.film_year
+#=> 2018 # from the venue's year attribute, or the title
+
+performance.dimension
+#=> '2d'
+
+performance.variant
+#=> ['audio_described', 'relaxed', 'subtitled']
+
+performance.starting_at
+#=> 2026-12-20 10:30:00 UTC
+
+performance.booking_url
+#=> 'https://tynesidecinema.co.uk/book-online/1808202'
+
+performance.cinema_name
+#=> 'Tyneside Cinema'
+
+performance.cinema_id
+#=> 'tyneside'
+```
+
+Only films are listed, including event cinema and screenings with a Q&A. Each
+venue marks films in its own way:
+
+| id         | Films are events where                                              |
+|------------|---------------------------------------------------------------------|
+| `broadway` | `Film` or `EventCinema` is true                                     |
+| `home`     | `ShowType` is `Film`                                                |
+| `hpph`     | `LiveOrFilm` is `Film`, `Website` is `HPPH` and `Venue` is the Picture House or blank |
+| `showroom` | `ShowroomNonFilmEvent` is not true                                  |
+| `tyneside` | `Medium` is not `Non-Film`                                          |
+
+Passes, bundles and lectures are left out by name. Cancelled instances are left
+out. Instances at midnight are left out, as Hyde Park Picture House lists films
+at midnight on the last day of the month before their times are set. Instances
+not on sale are kept: most have started or are not yet on sale.
+
+Booking links go to each venue's own booking page:
+
+| id         | Booking link                                                                    |
+|------------|---------------------------------------------------------------------------------|
+| `broadway` | `https://www.broadway.org.uk/book/<instance>`                                   |
+| `home`     | `https://tickets.homemcr.org/home/website/ChooseSeats.aspx?EventInstanceId=<instance>` |
+| `hpph`     | `https://tickets.hpph.co.uk/leedsheritagetheatres/website/ChooseSeats.aspx?EventInstanceId=<instance>` |
+| `showroom` | `https://tickets.showroomcinema.org.uk/showroomworkstation/website/ChooseSeats.aspx?EventInstanceId=<instance>` |
+| `tyneside` | `https://tynesidecinema.co.uk/book-online/<instance>`                           |
+
+The instance is the number that starts a Spektrix instance id. Showroom and Hyde
+Park Picture House open these pages in a frame on their own sites.
+
+Variants are `35mm`, `arts`, `audio_described`, `baby`, `kids`, `q&a`,
+`relaxed`, `senior` and `subtitled`, from each venue's event and instance
+attributes and from titles. `subtitled` means captions or subtitles for
+people who are deaf or hard of hearing, not a foreign language film's
+subtitles.
+
+## Tests
+
+```sh
+bundle exec rake          # unit tests against fixtures
+bundle exec rake live     # live Spektrix API
+```
+
+Fixtures in `test/fixtures` are API responses captured from each venue's
+account and trimmed to a few events. `test/support/api_shapes.rb` describes the
+fields and attributes the gem reads. The unit suite checks the fixtures against
+it and the live suite checks real responses, held only in memory. When an
+account changes, update the shape first, then the fixtures.
+
+## Releasing
+
+Bump the version, merge, then run the **Release Gem** workflow in GitHub
+Actions. It runs the tests, tags the version and publishes the gem through
+RubyGems trusted publishing.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/lib/spektrix_uk/cinema.rb

@@ -0,0 +1,87 @@
+module SpektrixUk
+  # An independent cinema that sells tickets through Spektrix
+  class Cinema < Cinebase::Cinema
+    # @!attribute [r] id
+    #   @return [String] the gem's id of the cinema, e.g. 'tyneside'
+
+    # Constructor
+    # @param [String, Symbol] id the cinema id, e.g. 'tyneside'
+    # @return [SpektrixUk::Cinema]
+    def initialize(id)
+      @id = id.to_s
+    end
+
+    # Every supported cinema, held in the gem
+    # @return [Array<SpektrixUk::Cinema>]
+    # @example
+    #   SpektrixUk::Cinema.all
+    #   #=> [<SpektrixUk::Cinema>, <SpektrixUk::Cinema>, ...]
+    def self.all
+      SpektrixUk::Internal::Venue::ALL.keys.map { |id| new(id) }
+    end
+
+    # @!method address
+    #   Address of the cinema
+    #   @return [Hash] of different address parts
+    #   @see #adr
+
+    # Address of the cinema
+    # @return [Hash] contains :street_address, :extended_address,
+    # :locality, :region, :postal_code, :country_name
+    # @example
+    #   cinema = SpektrixUk::Cinema.new('tyneside')
+    #   cinema.adr
+    #   #=> {
+    #         street_address:   '10 Pilgrim Street',
+    #         extended_address: nil,
+    #         locality:         'Newcastle upon Tyne',
+    #         region:           nil,
+    #         postal_code:      'NE1 6QG',
+    #         country_name:     'United Kingdom'
+    #       }
+    # @note Uses method naming as at http://microformats.org/wiki/adr
+    def adr
+      venue.address
+    end
+
+    # Brand of the cinema
+    # @return [String] which will always be 'Independent'
+    def brand
+      'Independent'.freeze
+    end
+
+    # @return [Float] latitude of the cinema
+    def latitude
+      venue.latitude
+    end
+
+    # @return [Float] longitude of the cinema
+    def longitude
+      venue.longitude
+    end
+
+    # The name of the cinema
+    # @return [String]
+    # @example
+    #   SpektrixUk::Cinema.new('tyneside').name
+    #   #=> 'Tyneside Cinema'
+    def name
+      venue.name
+    end
+
+    # The cinema's own website
+    # @return [String]
+    # @example
+    #   SpektrixUk::Cinema.new('tyneside').url
+    #   #=> 'https://tynesidecinema.co.uk'
+    def url
+      venue.url
+    end
+
+    private
+
+    def venue
+      SpektrixUk::Internal::Venue.find(id)
+    end
+  end
+end

data/lib/spektrix_uk/internal/api.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SpektrixUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Reads a venue's events and instances from the public Spektrix API v3,
+    # which needs no token. Each venue's Spektrix account is its client.
+    class Api
+      include Http
+
+      BASE_URL = "https://system.spektrix.com"
+
+      # @param [String] client the Spektrix client name, e.g. 'tynesidecinema'
+      def initialize(client)
+        @client = client
+      end
+
+      # Events with an instance starting within the range
+      # @param [Date] from first day
+      # @param [Date] to the day after the last, as the API reads a date as
+      #   its midnight
+      # @return [Array<Hash>]
+      def events(from, to)
+        get_json("events", instanceStart_from: from.iso8601, instanceStart_to: to.iso8601)
+      end
+
+      # Instances, or performances, starting within the range
+      # @param [Date] from first day
+      # @param [Date] to the day after the last
+      # @return [Array<Hash>]
+      def instances(from, to)
+        get_json("instances", startFrom: from.iso8601, startTo: to.iso8601)
+      end
+
+      private
+
+      def get_json(resource, query)
+        JSON.parse(get("#{BASE_URL}/#{@client}/api/v3/#{resource}?#{URI.encode_www_form(query)}"))
+      end
+    end
+  end
+end

data/lib/spektrix_uk/internal/http.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module SpektrixUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Requests to the Spektrix API
+    module Http
+      private
+
+      def get(url)
+        uri = URI(url)
+        request = Net::HTTP::Get.new(uri)
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: true,
+                                                       open_timeout: 10, read_timeout: 120) do |http|
+          http.request(request)
+        end
+        # Omit response bodies from errors, and never follow redirects.
+        raise "Spektrix HTTP error #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        String.new(response.body, encoding: Encoding::UTF_8)
+      end
+    end
+  end
+end

data/lib/spektrix_uk/internal/parser/instance.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "time"
+
+module SpektrixUk
+  # @api private
+  module Internal
+    module Parser
+      # Parses a Spektrix instance of a film into performance attributes
+      class Instance
+        # Variants a title names, at any venue
+        TITLE_VARIANTS = {
+          /\bQ&A\b/i => "q&a",
+          /\b35mm\b/i => "35mm",
+          /\A(?:Baby Kino|Baby & Carer\/)|Parent & Baby/i => "baby",
+          /\b(?:Toddler Kino|Family Time|Family Film)\b|\A(?:TK|FT):/ => "kids",
+          /\bRelaxed Screening\b/i => "relaxed"
+        }.freeze
+
+        THREE_D = /\b3D\b/
+        YEAR = /\A\d{4}\z/
+        TIME_ZONE = "Europe/London"
+
+        # @param [Hash] instance one Spektrix instance
+        # @param [Hash] event the event the instance belongs to
+        # @param [SpektrixUk::Internal::Venue] venue the venue that sells it
+        def initialize(instance, event:, venue:)
+          @instance = instance
+          @event = event
+          @venue = venue
+        end
+
+        # @return [Hash] options for SpektrixUk::Performance.new
+        def to_hash
+          {
+            booking_url: format(@venue.booking_url, instance: @instance.fetch("id")[/\A\d+/]),
+            dimension: three_d? ? "3d" : "2d",
+            festival: Cinebase::Festival.from_title(title, year: starting_at.year),
+            film_name: TitleSanitizer.new(title).sanitized,
+            film_year: film_year,
+            starting_at: starting_at,
+            variant: variant
+          }
+        end
+
+        private
+
+        def film_year
+          year = @event[@venue.year].to_s.strip
+          if year.match?(YEAR)
+            year.to_i
+          else
+            Cinebase::TitleSanitizer.film_year(title.gsub(TitleSanitizer::NOTES, ""))
+          end
+        end
+
+        # startUtc is UTC though it carries no zone
+        def starting_at
+          @starting_at ||=
+            if @instance["startUtc"]
+              Time.iso8601(@instance["startUtc"].delete_suffix("Z") + "Z")
+            else
+              local = Time.iso8601("#{@instance.fetch('start')}Z")
+              TZInfo::Timezone.get(TIME_ZONE).local_to_utc(local) { |periods| periods.first }.utc
+            end
+        end
+
+        def three_d?
+          @instance[@venue.three_d] == true || title.match?(THREE_D)
+        end
+
+        def title
+          @title ||= @event.fetch("name").strip
+        end
+
+        def variant
+          attributes = [[@venue.event_variants, @event], [@venue.instance_variants, @instance]]
+          variants = attributes.flat_map do |map, record|
+            map.filter_map { |attribute, values| values[record[attribute]] }
+          end
+          variants += TITLE_VARIANTS.filter_map { |pattern, name| name if title.match?(pattern) }
+          variants.uniq
+        end
+      end
+    end
+  end
+end

data/lib/spektrix_uk/internal/title_sanitizer.rb

@@ -0,0 +1,76 @@
+module SpektrixUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Sanitize and standardize film titles
+    class TitleSanitizer < Cinebase::TitleSanitizer
+      # Square-bracketed notes, e.g. '[35mm]', '[+ Filmmaker Q&A]' or
+      # Tyneside's programme year '[2026]'
+      NOTES = /\s*\[[^\]]*\]/
+
+      # Strands and seasons named before a colon, e.g. 'Classics: Dracula'
+      STRANDS = [
+        'Baby Kino', 'BHM\d+', 'Classics', 'Cult', 'DocNights', 'Dog Friendly', 'Early Doors(?: - \w+)?',
+        'Family Time', 'FF[FS]\d+(?: x [^:]+)?', 'Film Studies', 'FT', 'Healthy Holidays',
+        'Into Film Festival', 'Japanese Film Club presents', 'My Movie', 'PBPB', 'Perspectives',
+        'Philosophy', 'Popcorn & Prosecco', 'Presents', 'Preview', 'Queer East \d+',
+        'Queer Up Duck! Festival', 'Reclaim the Frame presents', 'Spotlight',
+        'TK', 'Toddler Kino', 'UK Jewish Film Festival', 'VHS Screening', 'WTF'
+      ].freeze
+
+      # Extras after a '+', e.g. 'The Holiday + Popcorn & Prosecco'
+      EXTRAS = [
+        'Event', 'Family Yoga', 'Intro(?:duction)?', 'Live Score.*', 'Mince Pie & Prosecco',
+        'Popcorn & Prosecco', 'Shorts?'
+      ].freeze
+
+      # Versions after a dash, e.g. 'Elf - Pay What You Feel'
+      VERSIONS = [
+        '\d+(?:st|nd|rd|th) Anniversary', '4K Restoration', 'Parent & Baby', 'Pay What You Feel',
+        'Presented by .*', 'Quiet Coach.*', 'Santa Extravaganza', 'Sing Along'
+      ].freeze
+
+      # @!method initialize(title)
+      #   Constructor
+      #   @param [String] title a film title
+      #   @return [SpektrixUk::Internal::TitleSanitizer]
+
+      # @!method sanitized
+      #   sanitized and standardized title
+      #   @return [String] sanitised title
+
+      private
+
+      # strings and regex to be removed
+      def remove
+        [
+          NOTES,
+          /\s*\((?:U|PG|12A?|15|18|R18|CTBA|TBC)\)/,                  # certificate
+          /\s*\((?:Preview|NEIFF|[^)]*Festival)\)/i,                  # preview or festival
+          /\AChristmas \d+\s*[-:]\s*/,                                # season
+          /\A(?!NT Live|Royal )[^\/]{1,30}\/\s+/,                     # strand, e.g. 'Cinema Social/ '
+          /\A(?:#{STRANDS.join('|')}):\s*/,                           # strand, e.g. 'Classics: '
+          /\A(?:FFS\d+|See It First –|Family Film Club -|Family Supper Club -)\s+/, # strand
+          /\A(?:Festive Afternoon Tea|Supper Club) \+\s*/,            # food before the film
+          /\s+\+\s+(?:#{EXTRAS.join('|')})\z/i,                       # extras after the film
+          /\s*\+[^+]*\bQ&A\b.*\z/i,                                   # Q&A, e.g. '+ Q&A with the director'
+          /\s+[-–]\s+(?:#{VERSIONS.join('|')})\z/i,                   # version
+          /:\s*\d+(?:st|nd|rd|th) Anniversary\z/i,                    # anniversary
+          /\s+Family Event\z/i,                                       # family event
+          /\s*\(\d+(?:st|nd|rd|th) Anniversary [^)]*\)/i,             # anniversary restoration
+          /\s*\(4K Restoration\)/i                                    # restoration
+        ] + COMMON_REMOVE
+      end
+
+      # regexes and their replacements
+      def replace
+        {
+          /\A(?:EOS|Exhibition on Screen):\s*(.*)/i                             => 'Exhibition on Screen: ',
+          /\A(.*) - Met Opera \d+\/\d+\z/                                        => 'Met Opera: ',
+          /\A(?:NT Live|NTL|National Theatre Live)[:\/]\s*(.*)/                  => 'National Theatre Live: ',
+          /\A(?:RBO|(?:The )?Royal (?:Ballet|Opera)(?: and Opera)?)[:\/]\s*(.*)/ => 'Royal Ballet and Opera: '
+        }.merge(COMMON_REPLACE)
+      end
+    end
+  end
+end