picturehouse_uk 6.0.0-aarch64-linux-gnu

data/README.md

@@ -0,0 +1,175 @@
+# PicturehouseUk
+
+A simple gem to pull cinemas and performances from the Vista API behind the [Picturehouse website](https://www.picturehouses.com) and spit out useful formatted info.
+
+[![Gem Version](https://badge.fury.io/rb/picturehouse_uk.svg)](https://badge.fury.io/rb/picturehouse_uk)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'picturehouse_uk'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install picturehouse_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 'screening type' information, years, Q&A add-ons and festival prefixes, and standardising theatre and opera event naming.
+
+### Guest token
+
+Every API call needs the public guest token the Picturehouse ticketing site
+gives each visitor. Fetch one before anything else:
+
+``` ruby
+PicturehouseUk.acquire_token!
+PicturehouseUk::Cinema.all
+```
+
+This shells out to **`curl-impersonate`**, not ordinary system `curl`, using its
+Chrome 150 TLS/HTTP profile, and reads `gasToken` from the page data of
+`https://web.picturehouses.com/`. No browser or JavaScript execution is needed.
+
+Platform-specific gem packages include the pinned `curl-impersonate` 2.2.3
+executable for glibc Linux (x86-64, ARM64) and macOS (Intel, Apple Silicon).
+On other platforms, or when installing from Git, install a
+[curl-impersonate release](https://github.com/lexiforest/curl-impersonate/releases/tag/v2.2.3)
+yourself and put it on your `PATH` or pass its path:
+
+``` ruby
+PicturehouseUk.acquire_token!(curl: '/opt/curl-impersonate/curl-impersonate')
+```
+
+Or supply your own current guest JWT, without the `Bearer ` prefix:
+
+``` ruby
+PicturehouseUk.token = ENV.fetch('PICTUREHOUSE_TOKEN')
+```
+
+Tokens currently last 12 hours. The gem checks the declared expiry but does not
+verify the signature. Missing, expired or rejected tokens raise
+`PicturehouseUk::AuthenticationError`; call `PicturehouseUk.acquire_token!`
+again. Normal API calls never acquire or renew a token automatically.
+
+### Cinema
+
+Cinema ids are Vista site ids. Duke's at Komedia is `'019'`.
+
+``` ruby
+PicturehouseUk::Cinema.all
+#=> [<PicturehouseUk::Cinema ...>, <PicturehouseUk::Cinema ...>, ...]
+
+cinema = PicturehouseUk::Cinema.new(19)
+#=> <PicturehouseUk::Cinema ...>
+
+cinema.adr
+#=> {
+  street_address:   '44-47 Gardner Street',
+  extended_address: nil,
+  locality:         'Brighton',
+  region:           nil,
+  postal_code:      'BN1 1UN',
+  country_name:     'United Kingdom'
+}
+
+cinema.brand
+#=> 'Picturehouse'
+
+cinema.name
+#=> "Duke's at Komedia"
+
+cinema.id
+#=> '019'
+
+cinema.url
+#=> 'https://www.picturehouses.com/cinema/duke-s-at-komedia'
+```
+
+### Performances
+
+`Performance.at` returns performances for an inclusive range of business dates,
+defaulting to today in London and the following 13 days. It makes one request
+per day.
+
+``` ruby
+PicturehouseUk::Performance.at(19, from: Date.today, to: Date.today + 2)
+#=> [<PicturehouseUk::Performance ...>, <PicturehouseUk::Performance ...>, ...]
+
+performance = PicturehouseUk::Performance.at(19).first
+#=> <PicturehouseUk::Performance ...>
+
+performance.film_name
+#=> 'Sense and Sensibility'
+
+performance.film_year
+#=> 2026 # from the title, nil when it has no year
+
+performance.dimension
+#=> '2d'
+
+performance.variant
+#=> ['audio_described', 'subtitled']
+
+performance.subtitled?
+#=> true
+
+performance.festival
+#=> #<data Cinebase::Festival name="CFF", year=2026> # nil outside festivals
+
+performance.starting_at
+#=> 2026-10-23 15:00:00 UTC
+
+performance.booking_url
+#=> 'https://web.picturehouses.com/order/showtimes/019-41632/seats'
+
+performance.cinema_name
+#=> "Duke's at Komedia"
+
+performance.cinema_id
+#=> '019'
+```
+
+Variants are `arts`, `audio_described`, `baby`, `kids`, `q&a`, `relaxed`,
+`senior` and `subtitled`. Picturehouse doesn't tag audio languages, so
+`language` is always `nil`.
+
+## Tests
+
+```sh
+bundle exec rake          # unit tests against fixtures
+bundle exec rake live     # live API, needs curl-impersonate or PICTUREHOUSE_TOKEN
+```
+
+Fixtures in `test/fixtures/api` are hand-written: invented films and
+addresses in the shape of Vista responses, never recorded API 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.
+
+## Building release packages
+
+```sh
+bundle exec rake build         # Portable source gem; external curl-impersonate required
+bundle exec rake package:all   # Four platform gems with bundled executables
+```
+
+To release, bump the version, merge, then run the **Release Gem** workflow in
+GitHub Actions. It builds the source and four platform gems, publishes them
+through RubyGems trusted publishing (no MFA code needed) and tags the release.
+Versions already on RubyGems are skipped, so a failed run can be rerun.
+
+## 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,37 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+require 'cinebase/vista/package_task'
+
+Cinebase::Vista::PackageTask.new('picturehouse_uk.gemspec', root: __dir__)
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib/picturehouse_uk'
+  t.test_files = FileList[
+    'test/lib/picturehouse_uk/*_test.rb',
+    'test/lib/picturehouse_uk/internal/*_test.rb',
+    'test/lib/picturehouse_uk/internal/parser/api/*_test.rb'
+  ]
+  t.verbose = true
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib/picturehouse_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/
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require 'picturehouse_uk'
+  ARGV.clear
+  IRB.start
+end
+
+task default: :test

data/lib/picturehouse_uk/cinema.rb

@@ -0,0 +1,127 @@
+module PicturehouseUk
+  # The object representing a cinema on the Picturehouse UK website
+  class Cinema < Cinebase::Cinema
+    # @!attribute [r] id
+    #   @return [String] the zero-padded Vista id of the cinema, e.g. '019'
+
+    # Vista site ids whose page slug differs from the cinema name
+    URL_SLUGS = {
+      '013' => 'picturehouse-at-fact',
+      '030' => 'epsom-picturehouse'
+    }.freeze
+
+    # 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
+
+    # Constructor
+    # @param [Integer, String] id the cinema id of the format 19/'019'
+    # @return [PicturehouseUk::Cinema]
+    def initialize(id)
+      @id = id.to_s.rjust(3, '0')
+    end
+
+    # Return basic cinema information for all cinemas
+    # @return [Array<PicturehouseUk::Cinema>]
+    # @example
+    #   PicturehouseUk::Cinema.all
+    #   #=> [<PicturehouseUk::Cinema>, <PicturehouseUk::Cinema>, ...]
+    def self.all
+      sites_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
+    # @return [Hash] contains :street_address, :extended_address,
+    # :locality, :region, :postal_code, :country_name
+    # @example
+    #   cinema = PicturehouseUk::Cinema.new(19)
+    #   cinema.adr
+    #   #=> {
+    #         street_address:   '44-47 Gardner Street',
+    #         extended_address: nil,
+    #         locality:         'Brighton',
+    #         region:           nil,
+    #         postal_code:      'BN1 1UN',
+    #         country_name:     'United Kingdom'
+    #       }
+    # @note Uses method naming as at http://microformats.org/wiki/adr
+    def adr
+      lines = address_lines
+      postal_code = lines.pop if lines.last&.match?(POSTCODE)
+      street_address = lines.shift
+      locality = lines.pop
+      {
+        street_address:   street_address,
+        extended_address: lines.empty? ? nil : lines.join(', '),
+        locality:         locality,
+        region:           nil,
+        postal_code:      postal_code,
+        country_name:     'United Kingdom'.freeze
+      }
+    end
+
+    # Brand of the cinema
+    # @return [String] which will always be 'Picturehouse'
+    def brand
+      'Picturehouse'.freeze
+    end
+
+    # The name of the cinema, which often includes the brand
+    # @return [String]
+    # @example
+    #   cinema = PicturehouseUk::Cinema.new(19)
+    #   cinema.full_name
+    #   #=> "Duke's at Komedia"
+    def full_name
+      name
+    end
+
+    # The name of the cinema
+    # @return [String]
+    # @example
+    #   cinema = PicturehouseUk::Cinema.new(19)
+    #   cinema.name
+    #   #=> "Duke's at Komedia"
+    def name
+      site_hash.dig('name', 'text').to_s
+    end
+
+    # The url of the cinema on the Picturehouse website
+    # @return [String]
+    def url
+      "https://www.picturehouses.com/cinema/#{url_slug}"
+    end
+
+    # @api private
+    def self.sites_hash
+      @sites_hash ||= PicturehouseUk::Internal::ApiResponse.new.sites.to_h do |site|
+        [site.fetch('id'), site]
+      end
+    end
+    private_class_method :sites_hash
+
+    private
+
+    def address_lines
+      address = site_hash.dig('contactDetails', 'addressV2') || {}
+      %w(line1 line2 line3 line4).filter_map do |key|
+        text = address.dig(key, 'text').to_s.strip
+        text unless text.empty?
+      end
+    end
+
+    def site_hash
+      @site_hash ||= self.class.send(:sites_hash).fetch(id, {})
+    end
+
+    def url_slug
+      URL_SLUGS.fetch(id) do
+        name.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/\A-|-\z/, '')
+      end
+    end
+  end
+end

data/lib/picturehouse_uk/internal/api_response.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "date"
+
+module PicturehouseUk
+  # Internal utility classes: Do not use
+  # @api private
+  module Internal
+    # Fetches cinema and showtime data from the Vista API behind picturehouses.com
+    class ApiResponse
+      BASE_URL = "https://digital-api.picturehouses.com/ocapi/v1/"
+
+      # @return [Array<Hash>] cinemas
+      def sites
+        client.get("sites").fetch("sites")
+      end
+
+      # @param [String] cinema_id zero-padded site id, e.g. '019'
+      # @param [Date] date business date
+      # @return [Hash] showtimes plus their related films and attributes
+      def showtimes(cinema_id, date)
+        client.get("showtimes/by-business-date/#{date.iso8601}",
+                   "siteIds" => cinema_id)
+      end
+
+      private
+
+      # Picturehouse's API rejects every Connect-Region-Code, so send none.
+      def client
+        Cinebase::Vista::Client.new(base_url: BASE_URL, region_code: nil,
+                                    token: PicturehouseUk.token)
+      end
+    end
+  end
+end

data/lib/picturehouse_uk/internal/guest_token.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "json"
+
+module PicturehouseUk
+  module Internal
+    # Reads the public guest token from the ticketing site's page data
+    class GuestToken < Cinebase::Vista::GuestToken
+      PAGE_URL = "https://web.picturehouses.com/"
+
+      private
+
+      # The ticketing site serves the same page data for unknown paths.
+      def accepted_statuses
+        %w[200 404]
+      end
+
+      def bundled_curl
+        File.expand_path("../../../vendor/curl-impersonate/bin/curl-impersonate", __dir__)
+      end
+
+      def extract_token(html)
+        script = html[%r{<script id="__NEXT_DATA__"[^>]*>(.*?)</script>}m, 1].to_s
+        JSON.parse(script).dig("props", "pageProps", "environment", "gasToken")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "time"
+
+module PicturehouseUk
+  # @api private
+  module Internal
+    module Parser
+      module Api
+        # Parses a single Vista showtime into performance attributes
+        class Showtime
+          BOOKING_URL = "https://web.picturehouses.com/order/showtimes/%s/seats"
+
+          # Vista attribute names, stripped
+          VARIANTS = {
+            "AD" => "audio_described",
+            "Kids' Club" => "kids",
+            "Q&A" => "q&a",
+            "Relaxed" => "relaxed",
+            "Screen Arts" => "arts",
+            "Silver Screen" => "senior",
+            "Subtitled" => "subtitled",
+            "Subtitled (Captioned)" => "subtitled",
+            "Toddler Time" => "kids",
+            "Watch with Baby" => "baby"
+          }.freeze
+
+          # @param [Hash] data one showtime
+          # @param [Hash{String => Hash}] films related films keyed by id
+          # @param [Hash{String => Hash}] attributes related attributes keyed by id
+          def initialize(data, films:, attributes:)
+            @data = data
+            @films = films
+            @attributes = attributes
+          end
+
+          # @return [Hash] options for PicturehouseUk::Performance.new
+          def to_hash
+            {
+              booking_url: format(BOOKING_URL, @data.fetch("id")),
+              dimension: @data["requires3dGlasses"] ? "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),
+              starting_at: starting_at,
+              variant: variant
+            }
+          end
+
+          private
+
+          def starting_at
+            Time.iso8601(@data.dig("schedule", "startsAt")).utc
+          end
+
+          def title
+            @films.fetch(@data.fetch("filmId")).dig("title", "text")
+          end
+
+          def variant
+            @data.fetch("attributeIds", []).filter_map do |id|
+              name = @attributes.dig(id, "name", "text").to_s.strip
+              VARIANTS[name.delete_prefix("+ ")]
+            end.uniq
+          end
+        end
+      end
+    end
+  end
+end

data/lib/picturehouse_uk/internal/title_sanitizer.rb

@@ -0,0 +1,78 @@
+module PicturehouseUk
+  # @api private
+  module Internal
+    # Sanitize and standardize film titles
+    class TitleSanitizer < Cinebase::TitleSanitizer
+      # @!method initialize(title)
+      #   Constructor
+      #   @param [String] title a film title
+      #   @return [CineworldUk::Internal::TitleSanitizer]
+
+      # @!method sanitized
+      #   sanitized and standardized title
+      #   @return [String] sanitised title
+
+      private
+
+      # strings and regex to be removed
+      def remove
+        [
+          /\s\[(AS LIVE:\s*)?[ACPGU1258]+\]/, # regular certificate
+          /\s\[R18\]/,                        # R18
+          /\s+\(?[23][dD]\)?/,                # 2d or 3d from title
+          /\bIMAX\b/i,                        # imax from title
+          /\s\[NO CERT\]/,                    # no certificate
+          /\s\[TBC\]/,                        # tbc
+          /\s\[N\/A\]/i,                      # n/a
+          /\s\(Theatre\)/i,                   # (theatre)
+          /\s\[\]/,                           # blank certificate
+          /ourscreen\: /,                     # ourscreen
+          /\s\(Re(\: \d{0,4})?\)/i,           # Re-release
+          /\s\[CERT TBC\]/,                   # certificate TBC
+          /\s?\-\s?autism.*ing\s?/i,          # austim screening
+          /\s?\+\s?Q\&(amp;)*A\.?/i,          # +Q&A
+          /KIDS CLUB\s*/i,                    # kids club
+          /DISCOVER TUE(sday\:)*\s*/i,        # discover tue
+          /FREE Screening\s*-\s*/i,           # free screening
+          /\s*-?\s*Big Scream\s*-?\s*/i,      # big scream
+          /\*?HOH Subtitled\*?/i,             # subtitled
+          /\s*\-?\s*Reminiscence/i,           # reminiscence
+          /\s*\-?\s*\(?Re\-issue\)?/i,        # reissue
+          /\s*-?\s*Kids\'? Club\s*-?\s*/,     # kids club
+          /\s*plus Q\&A.*/i,                  # extended Q&A
+          /Cinemania\s*[\:\-]/i,              # cinemania
+          /\@\s*komedia/i,                    # @ komedia
+          /\s*\+ panel.*/i,                   # panel
+          /toddler time\s*\:*\-*/i,           # toddler time
+          /\(.*\d{4}\)/,                      # year or captured year
+          /\bsingalong\b/i,                   # singalong
+          /\s+\-?\s*Parents \& Babies/i,      # parents and babies
+          /Subtitled\:*\s*/i,                 # subtitled
+          /\(?live\)?\z/i,                    # live
+          /amp\;/i,
+          /\ADog-Friendly - /,                # dog friendly
+          /\ARelaxed-Screening: /,            # relaxed screening
+          /\ALMF Presents: /,                 # LMF strand
+          /\AGreen Screen: /,                 # Green Screen strand
+          /\AFFQ: /                           # FFQ strand
+        ] + COMMON_REMOVE
+      end
+
+      # regexes and their replacements
+      def replace
+        {
+          /Met\.? Encore:\s*(.*)/    => 'Met Opera: ',
+          /Met\.? Opera:\s*(.*)/     => 'Met Opera: ',
+          /National Theatre:\s*(.*)/ => 'NT Live: ',
+          /NT Encore:\s*(.*)/        => 'NT Live: ',
+          /NT Live:\s*(.*)/          => 'NT Live: ',
+          /ROH\.? Live:\s*(.*)/      => 'Royal Opera House: ',
+          /ROH\.? Encore:\s*(.*)/    => 'Royal Opera House: ',
+          /RSC\.? Live:\s*(.*)/      => 'Royal Shakespeare Company: ',
+          /RSC\.? Encore:\s*(.*)/    => 'Royal Shakespeare Company: ',
+          /(.*) \(Bolshoi Ballet\)/  => 'Bolshoi Ballet: '
+        }.merge(COMMON_REPLACE)
+      end
+    end
+  end
+end

data/lib/picturehouse_uk/performance.rb

@@ -0,0 +1,80 @@
+module PicturehouseUk
+  # A single screening of a film on the Picturehouse UK 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 [Time] :starting_at listed start time of the performance
+
+    # Performances within an inclusive range of cinema business 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<PicturehouseUk::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
+
+      api = PicturehouseUk::Internal::ApiResponse.new
+      cinema = Cinema.new(cinema_id)
+      (from..to).flat_map do |date|
+        performances_on(api, cinema, date)
+      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, baby, kids, senior, subtitled ...)
+    #   @return <Array[String]>
+
+    # private
+
+    def self.performances_on(api, cinema, date)
+      response = api.showtimes(cinema.id, date)
+      related = response.fetch('relatedData')
+      films = by_id(related.fetch('films'))
+      attributes = by_id(related.fetch('attributes'))
+
+      response.fetch('showtimes').map do |data|
+        showtime = PicturehouseUk::Internal::Parser::Api::Showtime.new(
+          data, films: films, attributes: attributes
+        )
+        new(showtime.to_hash.merge(cinema_id: cinema.id,
+                                   cinema_name: cinema.name))
+      end
+    end
+    private_class_method :performances_on
+
+    def self.by_id(items)
+      items.to_h { |item| [item.fetch('id'), item] }
+    end
+    private_class_method :by_id
+  end
+end

data/lib/picturehouse_uk/version.rb

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

data/lib/picturehouse_uk.rb

@@ -0,0 +1,30 @@
+require 'json'
+
+require 'cinebase'
+require 'cinebase/vista'
+
+require_relative './picturehouse_uk/version'
+
+require_relative './picturehouse_uk/internal/api_response'
+require_relative './picturehouse_uk/internal/guest_token'
+require_relative './picturehouse_uk/internal/title_sanitizer'
+
+require_relative './picturehouse_uk/internal/parser/api/showtime'
+
+require_relative './picturehouse_uk/cinema'
+require_relative './picturehouse_uk/performance'
+
+# picturehouse_uk gem
+module PicturehouseUk
+  AuthenticationError = Cinebase::Vista::AuthenticationError
+
+  # A raw guest JWT, without the "Bearer " prefix. Never persisted by the gem.
+  class << self
+    attr_accessor :token
+
+    # Explicit acquisition/renewal; ordinary API calls never launch a subprocess.
+    def acquire_token!(curl: nil)
+      self.token = Internal::GuestToken.new(curl: curl).fetch
+    end
+  end
+end