vue_uk 1.0.0

data/README.md

@@ -0,0 +1,141 @@
+# VueUk
+
+A simple gem to pull cinemas and performances from the API behind the [Vue cinemas website](https://www.myvue.com) and spit out useful formatted info.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'vue_uk'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install vue_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 language versions, years, screening dates and festival prefixes.
+
+No token or setup is needed. The API answers uncached requests only within the
+guest session the website starts for every visitor, so the gem starts one with
+`POST /api/microservice/auth/token` and sends its cookies, starting a fresh one
+once if the API rejects it.
+
+### Cinema
+
+Only UK cinemas are returned; Vue's euro-priced cinemas are left out. The API
+has no addresses, so the first call to an address method reads the cinema's page
+on myvue.com.
+
+``` ruby
+VueUk::Cinema.all
+#=> [<VueUk::Cinema ...>, <VueUk::Cinema ...>, ...]
+
+cinema = VueUk::Cinema.new(10051)
+#=> <VueUk::Cinema ...>
+
+cinema.adr
+#=> {
+  street_address:   'The Viaduct',
+  extended_address: 'Hyndburn Road',
+  locality:         'Accrington',
+  region:           nil,
+  postal_code:      'BB5 1QF',
+  country_name:     'United Kingdom'
+}
+
+cinema.brand
+#=> 'Vue'
+
+cinema.full_name
+#=> 'Vue Accrington'
+
+cinema.id
+#=> '10051'
+
+cinema.url
+#=> 'https://www.myvue.com/cinema/accrington'
+```
+
+### Performances
+
+`Performance.at` returns performances for an inclusive range of showing dates,
+defaulting to today in London and the following 13 days. It makes one request
+for all of the cinema's advertised dates and keeps those in the range.
+
+``` ruby
+VueUk::Performance.at(10051, from: Date.today, to: Date.today + 2)
+#=> [<VueUk::Performance ...>, <VueUk::Performance ...>, ...]
+
+performance = VueUk::Performance.at(10051).first
+#=> <VueUk::Performance ...>
+
+performance.film_name
+#=> 'Clayface'
+
+performance.language
+#=> 'English' # Vue tags English audio too
+
+performance.film_year
+#=> nil # from the title, e.g. 2026 for 'Street Fighter (2026)'
+
+performance.dimension
+#=> '2d'
+
+performance.variant
+#=> ['audio_described']
+
+performance.subtitled?
+#=> false
+
+performance.festival
+#=> nil # e.g. #<data Cinebase::Festival name="CFF", year=2026>
+
+performance.starting_at
+#=> 2026-10-23 16:00:00 UTC
+
+performance.booking_url
+#=> 'https://www.myvue.com/book-tickets/summary/10051/HO00020288/139988'
+
+performance.cinema_name
+#=> 'Accrington'
+
+performance.cinema_id
+#=> '10051'
+```
+
+Variants are `arts`, `audio_described`, `autism_friendly`, `kids` and
+`subtitled`.
+
+## Tests
+
+```sh
+bundle exec rake          # unit tests against fixtures
+bundle exec rake live     # live myvue.com
+```
+
+Fixtures in `test/fixtures` are hand-written: invented films and addresses in
+the shape of Vue's responses, never recorded output. `test/support/api_shapes.rb`
+describes the fields the gem reads. The unit suite checks the fixtures against
+it and the live suite checks real responses, held only in memory. When the API
+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/Rakefile

@@ -0,0 +1,35 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib/vue_uk'
+  t.test_files = FileList[
+    'test/lib/vue_uk/*_test.rb',
+    'test/lib/vue_uk/internal/*_test.rb',
+    'test/lib/vue_uk/internal/parser/api/*_test.rb'
+  ]
+  t.verbose = true
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib/vue_uk'
+  t.name = :live
+  t.test_files = FileList[
+    'test/live/*_test.rb'
+  ]
+  t.verbose = true
+end
+
+# http://erniemiller.org/2014/02/05/7-lines-every-gems-rakefile-should-have/
+desc 'run gem console'
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require 'vue_uk'
+  ARGV.clear
+  IRB.start
+end
+
+task default: :test

data/lib/vue_uk/cinema.rb

@@ -0,0 +1,115 @@
+module VueUk
+  # The object representing a cinema on the Vue website
+  class Cinema < Cinebase::Cinema
+    # @!attribute [r] id
+    #   @return [String] the Vue id of the cinema, e.g. '10051'
+
+    # UK postcode, the last line of an address
+    POSTCODE = /\A[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}\z/i.freeze
+
+    # A county and postcode on one line, e.g. 'Essex CO4 5UP'
+    REGION_AND_POSTCODE = /\A(.+?)\s+([A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2})\z/i.freeze
+
+    # Map coordinates some cinemas list in place of a postcode
+    COORDINATES = /\A-?\d+(\.\d+)?,\s*-?\d+(\.\d+)?\z/.freeze
+
+    # Constructor
+    # @param [Integer, String] id the cinema id of the format 10051/'10051'
+    # @return [VueUk::Cinema]
+    def initialize(id)
+      @id = id.to_s
+    end
+
+    # Return basic cinema information for all UK cinemas
+    # @return [Array<VueUk::Cinema>]
+    # @example
+    #   VueUk::Cinema.all
+    #   #=> [<VueUk::Cinema>, <VueUk::Cinema>, ...]
+    def self.all
+      cinemas_hash.keys.map { |id| new(id) }
+    end
+
+    # @!method address
+    #   Address of the cinema
+    #   @return [Hash] of different address parts
+    #   @see #adr
+
+    # Address of the cinema, read from its page on the Vue website
+    # @return [Hash] contains :street_address, :extended_address,
+    # :locality, :region, :postal_code, :country_name
+    # @example
+    #   cinema = VueUk::Cinema.new(10051)
+    #   cinema.adr
+    #   #=> {
+    #         street_address:   'The Viaduct',
+    #         extended_address: 'Hyndburn Road',
+    #         locality:         'Accrington',
+    #         region:           nil,
+    #         postal_code:      'BB5 1QF',
+    #         country_name:     'United Kingdom'
+    #       }
+    # @note Uses method naming as at http://microformats.org/wiki/adr
+    def adr
+      lines = address_lines
+      if lines.last&.match?(POSTCODE)
+        postal_code = lines.pop
+      elsif (match = lines.last&.match(REGION_AND_POSTCODE))
+        lines.pop
+        region, postal_code = match.captures
+      end
+      street_address = lines.shift
+      locality = lines.pop
+      {
+        street_address:   street_address,
+        extended_address: lines.empty? ? nil : lines.join(', '),
+        locality:         locality,
+        region:           region,
+        postal_code:      postal_code,
+        country_name:     'United Kingdom'.freeze
+      }
+    end
+
+    # Brand of the cinema
+    # @return [String] which will always be 'Vue'
+    def brand
+      'Vue'.freeze
+    end
+
+    # The name of the cinema
+    # @return [String]
+    # @example
+    #   VueUk::Cinema.new(10051).name
+    #   #=> 'Accrington'
+    def name
+      cinema_hash['cinemaName'].to_s
+    end
+
+    # The url of the cinema on the Vue website
+    # @return [String]
+    def url
+      cinema_hash['whatsOnUrl'].to_s.delete_suffix('/whats-on')
+    end
+
+    # @api private
+    # Leaves out Vue's euro-priced cinemas outside the UK.
+    def self.cinemas_hash
+      @cinemas_hash ||= VueUk::Internal::ApiResponse.new.cinemas
+                                                    .select { |cinema| cinema['venueCurrency'] == 'GBP' }
+                                                    .to_h { |cinema| [cinema.fetch('cinemaId'), cinema] }
+    end
+    private_class_method :cinemas_hash
+
+    private
+
+    def address_lines
+      @page ||= VueUk::Internal::Website.new.cinema(cinema_hash.fetch('whatsOnUrl'))
+      @page.dig('cinemaAddress', 'value').to_s.split(/\r?\n/)
+           .map { |line| line.strip.sub(/,\s*(UK|United Kingdom)\z/i, '') }
+           .reject { |line| line.empty? || line.match?(COORDINATES) }
+    end
+
+    def cinema_hash
+      @cinema_hash ||= self.class.send(:cinemas_hash).fetch(id, {})
+    end
+  end
+end

data/lib/vue_uk/internal/api_response.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "json"
+
+module VueUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Fetches cinema and showing data from the API behind myvue.com
+    class ApiResponse
+      include Http
+
+      BASE_URL = "https://www.myvue.com/api/microservice/"
+      # The query the website itself sends; embargo level 3 is public listings
+      FILM_QUERY = {
+        "minEmbargoLevel" => 3, "includesSession" => true, "includeSessionAttributes" => true
+      }.freeze
+
+      # @return [Array<Hash>] cinemas
+      def cinemas
+        fetch("showings/cinemas").fetch("result").flat_map { |group| group.fetch("cinemas") }
+      end
+
+      # @param [String] cinema_id e.g. '10051'
+      # @return [Array<Hash>] films with their sessions on every advertised date
+      def films(cinema_id)
+        fetch("showings/cinemas/#{cinema_id}/films", FILM_QUERY).fetch("result")
+      end
+
+      private
+
+      # Uncached responses need the guest session the website starts for
+      # every visitor; start a fresh one once if it is rejected.
+      def fetch(path, query = {})
+        url = BASE_URL + path
+        url += "?#{URI.encode_www_form(query)}" unless query.empty?
+        retried = false
+        begin
+          @session ||= post_for_cookies("#{BASE_URL}auth/token", accept: "application/json")
+          JSON.parse(get(url, accept: "application/json", cookie: @session))
+        rescue Unauthorized
+          raise if retried
+
+          retried = true
+          @session = nil
+          retry
+        end
+      end
+    end
+  end
+end

data/lib/vue_uk/internal/http.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module VueUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Requests to myvue.com
+    module Http
+      class Unauthorized < StandardError; end
+
+      private
+
+      def get(url, accept:, cookie: nil)
+        request = Net::HTTP::Get.new(URI(url))
+        request["Cookie"] = cookie if cookie
+        perform(request, accept: accept).body
+      end
+
+      # @return [String] the response's cookies as a Cookie header value
+      def post_for_cookies(url, accept:)
+        response = perform(Net::HTTP::Post.new(URI(url)), accept: accept)
+        response.get_fields("Set-Cookie").to_a.map { |cookie| cookie.split(";").first }.join("; ")
+      end
+
+      def perform(request, accept:)
+        request["Accept"] = accept
+        uri = request.uri
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: true,
+                                                       open_timeout: 10, read_timeout: 30) do |http|
+          http.request(request)
+        end
+        # Omit response bodies from errors, and never follow redirects.
+        raise Unauthorized, "Vue HTTP error 401" if response.is_a?(Net::HTTPUnauthorized)
+        raise "Vue HTTP error #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        response
+      end
+    end
+  end
+end

data/lib/vue_uk/internal/parser/api/showtime.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "time"
+
+module VueUk
+  # @api private
+  module Internal
+    module Parser
+      module Api
+        # Parses a single Vue session into performance attributes
+        class Showtime
+          BOOKING_HOST = "https://www.myvue.com"
+
+          # Vue attribute names
+          VARIANTS = {
+            "Audio Description (AD)" => "audio_described",
+            "Autism Friendly" => "autism_friendly",
+            "Big Screen Events" => "arts",
+            "Big Screen Music" => "arts",
+            "Big Screen Musicals" => "arts",
+            "Big Shorts" => "kids",
+            "Event" => "arts",
+            "Mighty Mornings" => "kids",
+            "Open Captioned" => "subtitled"
+          }.freeze
+
+          # Vue tags English audio too, unlike the other chains
+          LANGUAGES = (Cinebase::TitleSanitizer::LANGUAGES + ["English"]).freeze
+
+          # @param [Hash] session one session
+          # @param [Hash] film the film the session shows
+          def initialize(session, film:)
+            @session = session
+            @film = film
+          end
+
+          # @return [Hash] options for VueUk::Performance.new
+          def to_hash
+            {
+              booking_url: booking_url,
+              dimension: attribute_names.any? { |name| name.match?(/\b3D\b/i) } ? "3d" : "2d",
+              festival: Cinebase::Festival.from_title(title, year: starting_at.year),
+              film_name: TitleSanitizer.new(title).sanitized,
+              film_year: Cinebase::TitleSanitizer.film_year(title),
+              language: attribute_names.find { |name| LANGUAGES.include?(name) },
+              starting_at: starting_at,
+              variant: attribute_names.filter_map { |name| VARIANTS[name] }.uniq
+            }
+          end
+
+          private
+
+          def attribute_names
+            @attribute_names ||= @session.fetch("attributes", []).map { |attribute| attribute["name"].to_s.strip }
+          end
+
+          def booking_url
+            path = @session["bookingUrl"]
+            URI.join(BOOKING_HOST, path).to_s if path
+          end
+
+          def starting_at
+            Time.iso8601(@session.fetch("showTimeWithTimeZone")).utc
+          end
+
+          def title
+            @film.fetch("filmTitle")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vue_uk/internal/title_sanitizer.rb

@@ -0,0 +1,31 @@
+module VueUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Sanitize and standardize film titles
+    class TitleSanitizer < Cinebase::TitleSanitizer
+      # @!method initialize(title)
+      #   Constructor
+      #   @param [String] title a film title
+      #   @return [VueUk::Internal::TitleSanitizer]
+
+      # @!method sanitized
+      #   sanitized and standardized title
+      #   @return [String] sanitised title
+
+      private
+
+      # strings and regex to be removed
+      def remove
+        [
+          /\s*\(\d{1,2} [A-Z][a-z]+ \d{4}\)/ # screening date
+        ] + COMMON_REMOVE
+      end
+
+      # regexes and their replacements
+      def replace
+        COMMON_REPLACE
+      end
+    end
+  end
+end

data/lib/vue_uk/internal/website.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "json"
+
+module VueUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Reads cinema details the API doesn't give from a cinema's page data
+    class Website
+      include Http
+
+      # @param [String] url a cinema's what's on page
+      # @return [Hash] the page's cinema details, e.g. its cinemaAddress
+      def cinema(url)
+        html = get(url, accept: "text/html")
+        script = html[%r{<script id="__NEXT_DATA__"[^>]*>(.*?)</script>}m, 1].to_s
+        JSON.parse(script).dig("props", "pageProps", "layoutData", "sitecore", "context", "cinema") || {}
+      end
+    end
+  end
+end

data/lib/vue_uk/performance.rb

@@ -0,0 +1,70 @@
+module VueUk
+  # A single screening of a film on the Vue website
+  class Performance < Cinebase::Performance
+    # @!attribute [r] booking_url
+    #   @return [String] the booking URL on the cinema website
+    # @!attribute [r] cinema_name
+    #   @return [String] the cinema name
+    # @!attribute [r] cinema_id
+    #   @return [String] the cinema id
+    # @!attribute [r] dimension
+    #   @return [String] 2d or 3d
+    # @!attribute [r] film_name
+    #   @return [String] the film name
+
+    # @!method initialize(options)
+    #   @param [Hash] options options hash
+    #   @option options [String] :booking_url (nil) buying url for the screening
+    #   @option options [String] :cinema_name name of the cinema
+    #   @option options [String] :cinema_id website id of the cinema
+    #   @option options [String] :dimension ('2d') dimension of the screening
+    #   @option options [Cinebase::Festival] :festival (nil) festival edition
+    #   @option options [String] :film_name name of the film
+    #   @option options [Integer] :film_year (nil) year from the film's title
+    #   @option options [String] :language (nil) audio language, e.g. 'English'
+    #   @option options [Time] :starting_at listed start time of the performance
+
+    # Performances within an inclusive range of showing dates, from one request
+    # for all of the cinema's advertised dates.
+    # @param [Integer, String] cinema_id id of the cinema
+    # @param [Date] from first date (defaults to today in London)
+    # @param [Date] to last date (defaults to 13 days after from)
+    # @return [Array<VueUk::Performance>]
+    def self.at(
+      cinema_id,
+      from: TZInfo::Timezone.get('Europe/London').now.to_date,
+      to: from + 13
+    )
+      raise ArgumentError, 'to must not precede from' if to < from
+
+      cinema = Cinema.new(cinema_id)
+      VueUk::Internal::ApiResponse.new.films(cinema.id).flat_map do |film|
+        sessions_between(film, from, to).map do |session|
+          showtime = VueUk::Internal::Parser::Api::Showtime.new(session, film: film)
+          new(showtime.to_hash.merge(cinema_id: cinema.id, cinema_name: cinema.name))
+        end
+      end
+    end
+
+    # @!method showing_on
+    #   The date of the screening
+    #   @return [Date]
+
+    # @!method starting_at
+    #   UTC time of the screening
+    #   @return [Time]
+
+    # @!method variant
+    #   The kinds of screening (arts, audio_described, kids, subtitled ...)
+    #   @return <Array[String]>
+
+    # private
+
+    def self.sessions_between(film, from, to)
+      film.fetch('showingGroups', [])
+          .select { |group| (from..to).cover?(Date.iso8601(group.fetch('date')[0, 10])) }
+          .flat_map { |group| group.fetch('sessions', []) }
+    end
+    private_class_method :sessions_between
+  end
+end

data/lib/vue_uk/version.rb

@@ -0,0 +1,6 @@
+# Ruby interface for https://www.myvue.com
+# @version 1.0.0
+module VueUk
+  # Gem version
+  VERSION = '1.0.0'.freeze
+end

data/lib/vue_uk.rb

@@ -0,0 +1,19 @@
+require 'json'
+
+require 'cinebase'
+
+require_relative './vue_uk/version'
+
+require_relative './vue_uk/internal/http'
+require_relative './vue_uk/internal/api_response'
+require_relative './vue_uk/internal/website'
+require_relative './vue_uk/internal/title_sanitizer'
+
+require_relative './vue_uk/internal/parser/api/showtime'
+
+require_relative './vue_uk/cinema'
+require_relative './vue_uk/performance'
+
+# vue_uk gem
+module VueUk
+end

data/test/fixtures/api/cinemas.json

@@ -0,0 +1,42 @@
+{
+  "result": [
+    {
+      "alpha": "A",
+      "cinemas": [
+        {
+          "cinemaId": "10051",
+          "cinemaName": "Accrington",
+          "fullName": "Accrington - Example Viaduct",
+          "venueCurrency": "GBP",
+          "whatsOnUrl": "https://www.myvue.com/cinema/accrington/whats-on"
+        }
+      ]
+    },
+    {
+      "alpha": "B",
+      "cinemas": [
+        {
+          "cinemaId": "10015",
+          "cinemaName": "Birmingham (Star City)",
+          "fullName": "Birmingham - Example Park",
+          "venueCurrency": "GBP",
+          "whatsOnUrl": "https://www.myvue.com/cinema/birmingham-star-city/whats-on"
+        }
+      ]
+    },
+    {
+      "alpha": "E",
+      "cinemas": [
+        {
+          "cinemaId": "90001",
+          "cinemaName": "Example Euro",
+          "fullName": "Example Euro - Elsewhere",
+          "venueCurrency": "EUR",
+          "whatsOnUrl": "https://www.myvue.com/cinema/example-euro/whats-on"
+        }
+      ]
+    }
+  ],
+  "responseCode": 0,
+  "errorMessage": null
+}