omniplex_uk 1.0.0

data/README.md

@@ -0,0 +1,168 @@
+# OmniplexUk
+
+A simple gem to pull cinemas and performances from the [Omniplex Cinemas website](https://www.omniplexcinemas.co.uk) and spit out useful formatted info.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'omniplex_uk'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install omniplex_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 classics,
+encore and anniversary markers, language versions and years, and giving
+Royal Ballet and Opera, Met Opera and National Theatre Live broadcasts the
+standard prefixes.
+
+No token or setup is needed. Omniplex's UK website runs on Admit One, but
+with its own templates rather than the A1Web pages that cinebase's
+`Cinebase::A1web` reads, so the gem has its own client. The gem covers the UK
+venues only: Great Britain and Northern Ireland. The Republic of Ireland
+venues are on omniplex.ie.
+
+### Cinema
+
+The venue list is cached for an hour. Ids are the website's site codes, such
+as `OMP_KENN`. The gem holds each venue's address and coordinates, from the
+address block and directions link on its listings page. High Wycombe and
+Sutton have neither, so theirs come from OpenStreetMap.
+
+``` ruby
+OmniplexUk::Cinema.all
+#=> [<OmniplexUk::Cinema ...>, <OmniplexUk::Cinema ...>, ...]
+
+cinema = OmniplexUk::Cinema.new('OMP_KENN')
+#=> <OmniplexUk::Cinema ...>
+
+cinema.adr
+#=> {
+  street_address:   'Kennedy Centre',
+  extended_address: '564-568 Falls Road',
+  locality:         'Belfast',
+  region:           'County Antrim',
+  postal_code:      'BT11 9AB',
+  country_name:     'United Kingdom'
+}
+
+cinema.brand
+#=> 'Omniplex'
+
+cinema.full_name
+#=> 'Omniplex Belfast - Kennedy Centre'
+
+cinema.id
+#=> 'OMP_KENN'
+
+cinema.latitude
+#=> 54.58149
+
+cinema.url
+#=> 'https://www.omniplexcinemas.co.uk/cinema/showtimes?sitecode=OMP_KENN'
+```
+
+### Performances
+
+`Performance.at` returns performances for an inclusive range of showing dates,
+defaulting to today in London and the following 13 days. The website lists one
+day per page. The first page also lists every date the venue advertises, so
+the gem then reads only those dates in the range, one after another over one
+connection. A year's range for one venue is about 45 to 60 requests.
+
+``` ruby
+OmniplexUk::Performance.at('OMP_SUND', from: Date.today, to: Date.today + 2)
+#=> [<OmniplexUk::Performance ...>, <OmniplexUk::Performance ...>, ...]
+
+performance = OmniplexUk::Performance.at('OMP_SUND').first
+#=> <OmniplexUk::Performance ...>
+
+performance.film_name
+#=> 'Clayface'
+
+performance.language
+#=> nil # e.g. 'Hindi' from '(Hindi)' in the title
+
+performance.film_year
+#=> nil # from the title, e.g. 1996 for 'Scream (1996) (Omniplex Classics)'
+
+performance.dimension
+#=> '2d'
+
+performance.variant
+#=> ['maxx']
+
+performance.subtitled?
+#=> false
+
+performance.starting_at
+#=> 2026-11-01 16:20:00 UTC
+
+performance.booking_url
+#=> 'https://www.omniplexcinemas.co.uk/booking/seats/sunderland/44797'
+
+performance.cinema_name
+#=> 'Sunderland'
+
+performance.cinema_id
+#=> 'OMP_SUND'
+```
+
+Booking links go straight to seat selection for the performance.
+
+Variants come from the hall icons and tags on each showtime, and the film's
+Event genre:
+
+| Website | Variant |
+| --- | --- |
+| Event genre, LIVE broadcasts | `arts` |
+| Audio Described | `audio_described` |
+| Avenue | `avenue` |
+| D-BOX | `dbox` |
+| 4D E-Motion | `4d` |
+| Infinity Vision, Infinity Vision 3D | `infinity_vision` |
+| MAXX | `maxx` |
+| Seniors Club | `senior` |
+| Sensory Friendly | `relaxed` |
+| Sofa Bed | `sofabed` |
+| Subtitled | `subtitled` |
+
+Infinity Vision 3D showings are also `3d`.
+
+## Tests
+
+```sh
+bundle exec rake          # unit tests against fixtures
+bundle exec rake live     # live omniplexcinemas.co.uk
+```
+
+Fixtures in `test/fixtures` are pages captured from omniplexcinemas.co.uk,
+trimmed to a few films and showtimes, with the Sunderland calendar cut to the
+dates captured. They keep the site's mix of UTF-8 and Windows-1252 bytes.
+`test/support/api_shapes.rb` describes the parts of the pages the gem reads.
+The unit suite checks the fixtures against it and the live suite checks real
+responses, held only in memory. When the website 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/omniplex_uk/cinema.rb

@@ -0,0 +1,172 @@
+module OmniplexUk
+  # The object representing a cinema on the Omniplex Cinemas website
+  class Cinema < Cinebase::A1web::Cinema
+    # @!attribute [r] id
+    #   @return [String] the Admit One site code of the cinema, e.g. 'OMP_KENN'
+
+    # @!method initialize(id)
+    #   @param [String] id the cinema id, e.g. 'OMP_KENN' or 'omp_kenn'
+    #   @return [OmniplexUk::Cinema]
+
+    # @!method self.all
+    #   Return basic cinema information for the UK cinemas: Great Britain
+    #   and Northern Ireland, not the Republic of Ireland
+    #   @return [Array<OmniplexUk::Cinema>]
+    #   @example
+    #     OmniplexUk::Cinema.all
+    #     #=> [<OmniplexUk::Cinema>, <OmniplexUk::Cinema>, ...]
+
+    # @!method adr
+    #   Address of the cinema
+    #   @return [Hash] contains :street_address, :extended_address,
+    #   :locality, :region, :postal_code, :country_name
+    #   @example
+    #     cinema = OmniplexUk::Cinema.new('OMP_KENN')
+    #     cinema.adr
+    #     #=> {
+    #           street_address:   'Kennedy Centre',
+    #           extended_address: '564-568 Falls Road',
+    #           locality:         'Belfast',
+    #           region:           'County Antrim',
+    #           postal_code:      'BT11 9AB',
+    #           country_name:     'United Kingdom'
+    #         }
+    #   @note Uses method naming as at http://microformats.org/wiki/adr
+
+    # @!method latitude
+    #   @return [Float, nil]
+
+    # @!method longitude
+    #   @return [Float, nil]
+
+    # @!method name
+    #   The name of the cinema
+    #   @return [String]
+    #   @example
+    #     OmniplexUk::Cinema.new('OMP_KENN').name
+    #     #=> 'Belfast - Kennedy Centre'
+
+    # @!method url
+    #   The cinema's listings page, which also selects it on the website
+    #   @return [String]
+    #   @example
+    #     OmniplexUk::Cinema.new('OMP_KENN').url
+    #     #=> 'https://www.omniplexcinemas.co.uk/cinema/showtimes?sitecode=OMP_KENN'
+
+    # Addresses and coordinates from the address block and directions link
+    # on each venue's listings page, except High Wycombe and Sutton, which
+    # have neither and come from OpenStreetMap.
+    LOCATIONS = {
+      'OMP_ANTR' => {
+        street_address: 'Junction One Retail Park', locality: 'Antrim', region: 'County Antrim',
+        postal_code: 'BT41 4LL', latitude: 54.7297, longitude: -6.2311
+      },
+      'OMP_BANB' => {
+        street_address: 'Unit 4-12, The Outlet', locality: 'Banbridge', region: 'County Down',
+        postal_code: 'BT32 4GJ', latitude: 54.3326344, longitude: -6.2783001
+      },
+      'OMP_BANG' => {
+        street_address: 'Valentines Road', locality: 'Bangor', region: 'County Down',
+        postal_code: 'BT20 4JH', latitude: 54.6548005, longitude: -5.6631795
+      },
+      'OMP_BIRM' => {
+        street_address: 'Great Park', extended_address: 'Rubery', locality: 'Birmingham',
+        region: 'West Midlands', postal_code: 'B45 9JL', latitude: 52.39882, longitude: -2.00826
+      },
+      'OMP_CARR' => {
+        street_address: 'Unit 3-4, Rodgers Quay', locality: 'Carrickfergus', region: 'County Antrim',
+        postal_code: 'BT38 8BE', latitude: 54.7123617, longitude: -5.8125379
+      },
+      'OMP_CLYD' => {
+        street_address: '23 Britannia Way', locality: 'Clydebank', region: 'West Dunbartonshire',
+        postal_code: 'G81 2RZ', latitude: 55.9015, longitude: -4.4056
+      },
+      'OMP_CRAI' => {
+        street_address: 'Highfield Heights', locality: 'Craigavon', region: 'County Armagh',
+        postal_code: 'BT64 3AE', latitude: 54.4492, longitude: -6.3985
+      },
+      'OMP_DERR' => {
+        street_address: 'Quayside Centre', extended_address: 'Strand Road', locality: 'Derry',
+        region: 'County Londonderry', postal_code: 'BT48 7PX', latitude: 55.0002376, longitude: -7.3215562
+      },
+      'OMP_DOWN' => {
+        street_address: '5 Owenbeg Avenue', locality: 'Downpatrick', region: 'County Down',
+        postal_code: 'BT30 6FJ', latitude: 54.3237579, longitude: -5.7139260
+      },
+      'OMP_DUDO' => {
+        street_address: 'Entertainment Village', extended_address: 'Dundonald', locality: 'Belfast',
+        region: 'County Down', postal_code: 'BT16 1YG', latitude: 54.5874, longitude: -5.8189
+      },
+      'OMP_DUGA' => {
+        street_address: 'Oaks Retail Park', extended_address: 'Oaks Road', locality: 'Dungannon',
+        region: 'County Tyrone', postal_code: 'BT71 4AR', latitude: 54.5125018, longitude: -6.7616527
+      },
+      'OMP_GLAS' => {
+        street_address: '7 Renfrew Street', locality: 'Glasgow', region: 'Glasgow City',
+        postal_code: 'G2 3AB', latitude: 55.864976, longitude: -4.254477
+      },
+      'OMP_HIWY' => {
+        street_address: 'Crest Road', locality: 'High Wycombe', region: 'Buckinghamshire',
+        postal_code: 'HP11 1UA', latitude: 51.6131257, longitude: -0.7719008
+      },
+      'OMP_IPSW' => {
+        street_address: '1 Buttermarket Shopping Centre', locality: 'Ipswich', region: 'Suffolk',
+        postal_code: 'IP1 1DT', latitude: 52.0575, longitude: 1.1550
+      },
+      'OMP_KENN' => {
+        street_address: 'Kennedy Centre', extended_address: '564-568 Falls Road', locality: 'Belfast',
+        region: 'County Antrim', postal_code: 'BT11 9AB', latitude: 54.58149, longitude: -5.97779
+      },
+      'OMP_LARN' => {
+        street_address: 'Larne Leisure Park', extended_address: 'Redlands Road', locality: 'Larne',
+        region: 'County Antrim', postal_code: 'BT40 1FD', latitude: 54.8470005, longitude: -5.8102719
+      },
+      'OMP_LISB' => {
+        street_address: 'Lisburn Leisure Park', extended_address: 'Governors Road', locality: 'Lisburn',
+        region: 'County Antrim', postal_code: 'BT28 1LP', latitude: 54.507481, longitude: -6.051616
+      },
+      'OMP_NEWR' => {
+        street_address: 'The Quays Shopping Centre', locality: 'Newry', region: 'County Down',
+        postal_code: 'BT35 8QS', latitude: 54.1688, longitude: -6.3401
+      },
+      'OMP_OMAG' => {
+        street_address: 'Kevlin Road', locality: 'Omagh', region: 'County Tyrone',
+        postal_code: 'BT78 1JL', latitude: 54.5965088, longitude: -7.3006357
+      },
+      'OMP_SUND' => {
+        street_address: '4 Lambton Street', locality: 'Sunderland', region: 'Tyne and Wear',
+        postal_code: 'SR1 1TP', latitude: 54.9082446, longitude: -1.3800217
+      },
+      'OMP_SUTT' => {
+        street_address: 'St Nicholas Centre', extended_address: 'St Nicholas Way', locality: 'Sutton',
+        region: 'Greater London', postal_code: 'SM1 1AY', latitude: 51.3647655, longitude: -0.1953102
+      },
+      'OMP_WIGA' => {
+        street_address: 'Unit 2, Robin Leisure Park', locality: 'Wigan', region: 'Greater Manchester',
+        postal_code: 'WN5 0UJ', latitude: 53.54603, longitude: -2.65797
+      }
+    }.freeze
+
+    # @return [String]
+    def self.website
+      Internal::Client::WEBSITE
+    end
+
+    # @api private
+    # @return [OmniplexUk::Internal::Client]
+    def self.client
+      Internal::Client.new
+    end
+
+    # @api private
+    def self.locations
+      LOCATIONS
+    end
+
+    # Brand of the cinema
+    # @return [String] which will always be 'Omniplex'
+    def brand
+      'Omniplex'.freeze
+    end
+  end
+end

data/lib/omniplex_uk/internal/client.rb

@@ -0,0 +1,108 @@
+require 'cgi/escape'
+require 'net/http'
+
+module OmniplexUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Reads the venue list and daily listings from omniplexcinemas.co.uk,
+    # Omniplex's Admit One site. A venue's listings take one request per
+    # day, so requests share one kept-alive connection until #close.
+    class Client
+      WEBSITE = 'https://www.omniplexcinemas.co.uk'.freeze
+      SHOWTIMES_PATH = '/cinema/showtimes'.freeze
+
+      # The home page's site picker groups venues by region. The Ireland
+      # region is the Republic, served by omniplex.ie.
+      REGION_OR_VENUE = /data-region="(\w+)"|data-name="([^"]*)" data-sitecode="(\w+)"/
+      UK_REGIONS = %w(England NorthernIreland Scotland Wales).freeze
+
+      # Pages claim ISO-8859-1 but mix UTF-8 with Windows-1252 apostrophes
+      LEGACY_ENCODING = Encoding::Windows_1252
+      RETRIES = 2
+      TRANSIENT_ERRORS = [
+        EOFError, Errno::ECONNRESET, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError
+      ].freeze
+
+      # UK venues in the home page's site picker
+      # @return [Array<Hash>] with :url, :name and :code, e.g.
+      #   { url: 'https://www.omniplexcinemas.co.uk/cinema/showtimes?sitecode=OMP_KENN',
+      #     name: 'Belfast - Kennedy Centre', code: 'OMP_KENN' }
+      def venues
+        region = nil
+        venues = get('/').scan(REGION_OR_VENUE).filter_map do |group, name, code|
+          if group
+            region = group
+            nil
+          elsif UK_REGIONS.include?(region)
+            { url: showtimes_url(code), name: CGI.unescapeHTML(name).strip, code: code }
+          end
+        end
+        venues.uniq { |venue| venue[:code] }
+      end
+
+      # One day's listings for a venue, or its default day's without a date.
+      # Each page also lists every advertised date.
+      # @param [String] site_code e.g. 'OMP_KENN'
+      # @param [Date, nil] date
+      # @return [String]
+      def showtimes(site_code, date = nil)
+        get(showtimes_path(site_code, date))
+      end
+
+      # @param [String] site_code e.g. 'OMP_KENN'
+      # @return [String] the venue's listings page; it also selects the venue
+      #   on the website for later visits
+      def showtimes_url(site_code)
+        WEBSITE + showtimes_path(site_code)
+      end
+
+      def close
+        @http.finish if @http&.started?
+        @http = nil
+      end
+
+      private
+
+      def showtimes_path(site_code, date = nil)
+        query = { sitecode: site_code }
+        query.merge!(action: 'processFilters', filterDate: date.iso8601) if date
+        "#{SHOWTIMES_PATH}?#{URI.encode_www_form(query)}"
+      end
+
+      def get(path)
+        attempts = 0
+        begin
+          response = http.request(Net::HTTP::Get.new(path))
+        rescue *TRANSIENT_ERRORS
+          close
+          attempts += 1
+          raise if attempts > RETRIES
+
+          sleep(attempts)
+          retry
+        end
+
+        if response.is_a?(Net::HTTPSuccess)
+          decode(response.body)
+        else
+          # Omit response bodies from errors, and never follow redirects.
+          raise "HTTP error #{response.code} from #{URI(WEBSITE).host}"
+        end
+      end
+
+      def http
+        @http ||= begin
+          uri = URI(WEBSITE)
+          Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30, max_retries: 0)
+        end
+      end
+
+      def decode(body)
+        body.dup.force_encoding(Encoding::UTF_8).scrub do |bytes|
+          bytes.force_encoding(LEGACY_ENCODING).encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+        end
+      end
+    end
+  end
+end

data/lib/omniplex_uk/internal/listings.rb

@@ -0,0 +1,100 @@
+require 'cgi/escape'
+require 'date'
+
+module OmniplexUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Reads one day's showtimes, and the venue's advertised dates, from a
+    # listings page.
+    class Listings
+      # The calendar's dates are local midnights in milliseconds, so dates
+      # in British Summer Time fall at 23:00 UTC the day before
+      ADVERTISED_DATES = /allowedDatesTimestamps = \[([\d,\s]*)\]/
+      PAGE_DATE = /var defaultDate = "(\d{4}-\d{2}-\d{2})"/
+      FILM = %r{
+        <p\sclass="font-medium\stext-lg[^"]*">\s*<a\s[^>]*>(.*?)</a>\s*</p>
+        \s*<img\s[^>]*id="favourite([^"]+)"
+      }mx
+      GENRES = %r{/images/ratings/[^"]*"[^>]*>\s*<p[^>]*>([^<]*)</p>}
+      SHOWTIME = %r{<a aria-label="[^"]*? at (\d{1,2}):(\d{2}) in [^"]*" href="([^"]*)"[^>]*>(.*?)</a>}m
+      ICON = %r{<img src="[^"]*/([\w-]+)\.(?:png|svg)"}
+      TAG = %r{<span class="text-xs[^"]*">([^<]*)</span>}
+
+      # Hall icons on a showtime, named as the website names them
+      ICONS = {
+        '4d_emotion' => '4D E-Motion',
+        'avenue' => 'Avenue',
+        'infinity3d_icon' => 'Infinity Vision 3D',
+        'infinity_icon' => 'Infinity Vision',
+        'omniplex_mobile-app-2025_svgs_audio-described-alt' => 'Audio Described',
+        'omniplex_mobile-app-2025_svgs_dbox-orange' => 'D-BOX',
+        'omniplex_mobile-app-2025_svgs_maxx' => 'MAXX',
+        'sofabed' => 'Sofa Bed'
+      }.freeze
+
+      # Films whose genres include it are live and recorded events
+      EVENT_GENRE = 'Event'.freeze
+      MILLISECONDS = 1000
+      TIME_ZONE = 'Europe/London'.freeze
+
+      # @return [Date, nil] the day this page lists
+      attr_reader :date
+
+      # @param [String] html a listings page
+      def initialize(html)
+        @html = html
+        page_date = html[PAGE_DATE, 1]
+        @date = Date.iso8601(page_date) if page_date
+      end
+
+      # @return [Array<Date>] every date the venue advertises, in order
+      def dates
+        timestamps = @html[ADVERTISED_DATES, 1].to_s.split(',')
+        timestamps.map { |milliseconds| local_date(milliseconds.to_i / MILLISECONDS) }.uniq.sort
+      end
+
+      # @return [Array<Cinebase::A1web::Showing>]
+      def showings
+        if date
+          @html.split(FILM).drop(1).each_slice(3).flat_map do |title, film_id, markup|
+            film_showings(text(title), film_id, markup.to_s)
+          end
+        else
+          []
+        end
+      end
+
+      private
+
+      def film_showings(title, film_id, markup)
+        genres = markup[GENRES, 1].to_s.split(',').map(&:strip)
+        film_tags = genres.include?(EVENT_GENRE) ? [EVENT_GENRE] : []
+        markup.scan(SHOWTIME).map do |hour, minute, href, box|
+          Cinebase::A1web::Showing.new(
+            film_id: film_id, title: title, date: date, starting_at: starting_at(hour.to_i, minute.to_i),
+            booking_url: CGI.unescapeHTML(href), tags: film_tags + tags(box)
+          )
+        end
+      end
+
+      def tags(box)
+        icons = box.scan(ICON).flatten.filter_map { |icon| ICONS[icon] }
+        icons + box.scan(TAG).flatten.map { |tag| text(tag) }
+      end
+
+      def local_date(seconds)
+        TZInfo::Timezone.get(TIME_ZONE).to_local(Time.at(seconds).utc).to_date
+      end
+
+      def starting_at(hour, minute)
+        local = Time.utc(date.year, date.month, date.day, hour, minute)
+        TZInfo::Timezone.get(TIME_ZONE).local_to_utc(local) { |periods| periods.first }.utc
+      end
+
+      def text(html)
+        CGI.unescapeHTML(html.gsub(/<[^>]*>/, ' ')).gsub(/\s+/, ' ').strip
+      end
+    end
+  end
+end

data/lib/omniplex_uk/internal/title_sanitizer.rb

@@ -0,0 +1,43 @@
+module OmniplexUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Sanitize and standardize film titles
+    class TitleSanitizer < Cinebase::TitleSanitizer
+      # The website loses some apostrophes, e.g. 'Andre Rieu?s'
+      LOST_APOSTROPHE = /(\w)\?(s)\b/
+
+      # @!method initialize(title)
+      #   Constructor
+      #   @param [String] title a film title
+      #   @return [OmniplexUk::Internal::TitleSanitizer]
+
+      # sanitized and standardized title
+      # @return [String] sanitised title
+      def sanitized
+        @restored ||= super.gsub(LOST_APOSTROPHE, "\\1'\\2")
+      end
+
+      private
+
+      # strings and regex to be removed
+      def remove
+        [
+          /\s*\(Omniplex Classics\)/i,  # classics season
+          /\s*\(Sunrise Screening\)/i,  # early screening
+          /\s*\(Poland\)/,              # Polish film
+          /\s+Encore\z/i                # encore screening
+        ] + COMMON_REMOVE
+      end
+
+      # regexes and their replacements
+      def replace
+        {
+          /\A(.*?)\s+-\s*LIVE\s*-\s*The Royal (?:Ballet|Opera) \d{2}-\d{2}\z/ => 'Royal Ballet and Opera: ',
+          /\A(.*?)\s+-\s+The Met Opera \d{2}-\d{2}\z/                       => 'Met Opera: ',
+          /\ANT Live:\s*(.*)/                                                => 'National Theatre Live: '
+        }.merge(COMMON_REPLACE)
+      end
+    end
+  end
+end