jekyll-apple-maps 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5507e6244102f89cacead6f1bb80f138d42501dbcce290f3acc30c2955fc2cbe
+  data.tar.gz: 886821f616922e5aa68ff16d0a52a60e5650048df572cb08c73c747498196290
+SHA512:
+  metadata.gz: b4d7b68571c9f9a22dc10cbc2ae3f7a7aa1abd523153928cdd9a069ee275c4d62e5e0053d986eb1bca0f249e8646816877d97f84a96859d56a2d70992af085ba
+  data.tar.gz: '09731d93e886215f1c131b1b6a87c68bfd10ace7d7465cb7ea47ab627f16f88e80657b5ba4bdcaafe87dbaa4b67f52bb3c808663e213cb1ca8ebe2b5671b25c9'

data/README.md

@@ -0,0 +1,190 @@
+# jekyll-apple-maps
+[![CircleCI](https://dl.circleci.com/status-badge/img/circleci/aW12qZgMpxbXNYTbdzFe5/FS3eDPqnpMpZJ2cKYi2aN9/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/circleci/aW12qZgMpxbXNYTbdzFe5/FS3eDPqnpMpZJ2cKYi2aN9/tree/main) [![codecov](https://codecov.io/gh/ZekeSnider/jekyll-apple-maps/graph/badge.svg?token=2V7NFD77OL)](https://codecov.io/gh/ZekeSnider/jekyll-apple-maps)
+
+![Hero image for jekyll-apple-maps](/assets/hero_image.png)
+
+This gem provides [Jekyll](https://jekyllrb.com) integrations for the [Apple Maps server APIs](https://developer.apple.com/documentation/applemapsserverapi/). It allows you to include Apple Maps content in your site using Jekyll Liquid tags. Currently it supports the following APIs:
+
++ [Snapshots](https://developer.apple.com/documentation/snapshots)
+  + Supports both light and dark modes with dynamic `picture` tags
+  + Caches images to avoid regenerating images with the same parameters, saving on API calls
+  + Supports all parameters currently accepted by the Snapshots API
+  + Cleans up asset images for maps that are no longer being used
+
+## Installation
+
+1. Install gem
+
+This plugin is available as the [jekyll-apple-maps RubyGem](https://rubygems.org/gems/jekyll-apple-maps). You can add it to your project by adding this line to your `Gemfile`: `gem 'jekyll-apple-maps'`. Then run `bundle` to install the gem.
+
+2. Add to configuration
+
+After the gem has been installed, you need to add to your site's `_config.yml` to configure the plugin. 
+
+```
+plugins:
+- jekyll-apple-maps
+```
+
+You can also optionally override the `referer` parameter in your `_config.yml`. This can be useful when serving locally, where your site's URL is `localhost` by default.
+
+```
+apple-maps:
+  referer: https://example.com
+```
+
+3. Add API Key
+
+To use this plugin, you'll need an Apple Developer account to generate an API key. This plugin uses a "Web Snapshots" Maps token, you can use the steps [listed here](https://developer.apple.com/documentation/mapkitjs/creating_a_maps_token) to generate one.
+
+> [!NOTE]
+> This plugin uses your Jekyll site's `site.url` as the `referer` header on requests to the Apple Maps API by default. As mentioned above, you can also override it in your `_config.yml` file. When creating an API key you should either specify your site's url as the domain restriction, or generate a key without a domain restriction. 
+
+Once you have your API key, you should set the the `APPLE_MAPS_SNAPSHOT_API_KEY` environment variable.
+
+`export APPLE_MAPS_SNAPSHOT_API_KEY=your_api_key_here`
+
+## Usage
+
+### Snapshots
+
+The `apple_maps_snapshot_block` creates an Apple Maps image snapshot using the specified parameters. The [Apple Docs](https://developer.apple.com/documentation/snapshots/create_a_maps_web_snapshot) provide more details on each of the API parameters.
+
+The following parameters are accepted by the block:
++ `center` - Coordinates of the center of the map. Can be set to `auto` if annotations and/or overlays are specified. Defaults to `auto`.
++ `map_type` - What type of map view to use. Options are: `standard`, `hybrid`, `satellite`, and `mutedStandard`. Defaults to `standard`.
++ `show_poi` - Whether to display places of interest on the map. Defaults to `true`.
++ `language` - Language to use for map labels. Defaults to `en-US`.
++ `span` - Coordinate span of how much to display around the map's center. Defaults to `nil`.
++ `zoom` - Zoom level with the range of `3` to `20`. Defaults to `12`.
++ `width` - Pixel width of the image. Defaults to `600`.
++ `height` -  Pixel height of the image. Defaults to `300`.
++ `scale` - The pixel density of the image. Valid values are `1`, `2`, `3`. Defaults to `2`.
++ `color_schemes` - Array of which color schemes to generate for the map. Options are `light` and `dark`. Defaults to both (`['light', 'dark']`).
++ `overlays` - An array of [overlay objects](https://developer.apple.com/documentation/snapshots/overlay). Defaults to empty `[]`.
++ `annotations` - An array of [annotation objects](https://developer.apple.com/documentation/snapshots/annotation). Defaults to empty `[]`.
++ `overlays_styles` - An array of [overlay style objects](https://developer.apple.com/documentation/snapshots/overlaystyle). Defaults to empty `[]`.
++ `images` - An array of [image objects](https://developer.apple.com/documentation/snapshots/image) for annotations. Defaults to empty `[]`.
+
+#### Examples
+A map with a single annotation
+```
+{% apple_maps_snapshot_block %}
+  center: "33.24767,-115.73192"
+  show_poi: true
+  zoom: 6
+  width: 600
+  height: 400
+  annotations: [
+    {
+      "point": "33.24767,-115.73192",
+      "color":"449944",
+      "glyphText": "S",
+      "markerStyle": "large"
+    }
+  ]
+{% endapple_maps_snapshot_block %}
+```
+![Example map using a single annotation](/assets/single_annotation.png)
+
+Using an image annotation
+```
+{% apple_maps_snapshot_block %}
+  center: "33.24767,-115.73192"
+  show_poi: false
+  zoom: 8
+  width: 600
+  height: 400
+  color_schemes: ["dark"]
+  annotations: [
+    {
+      "markerStyle": "img", 
+      "imgIdx": 0, 
+      "point":"33.24767,-115.73192", 
+      "color":"449944", 
+      "offset": "0,15"
+    }
+  ]
+  images: [
+    {
+      "url": "https://www.iconfinder.com/icons/2376758/download/png/48",
+      "height": 48,
+      "width": 48
+    }
+  ]
+{% endapple_maps_snapshot_block %}
+```
+![Example map using an image annotation](/assets/image_annotation.png)
+
+A map with multiple annotations
+```
+{% apple_maps_snapshot_block %}
+  center: "37.772318, -122.447326"
+  zoom: 11.5
+  width: 600
+  height: 400
+  annotations: [
+    {
+      "point": "37.819724, -122.478557",
+      "color":"red",
+      "glyphText": "G",
+      "markerStyle": "large"
+    },
+    {
+      "point": "37.750472,-122.484132",
+      "color": "blue",
+      "glyphText": "S",
+      "markerStyle": "large"
+    },
+    {
+      "point": "37.755217, -122.452776",
+      "color": "red",
+      "markerStyle": "balloon"
+    },
+    {
+      "point": "37.778457, -122.389238",
+      "color": "orange",
+      "markerStyle": "dot"
+    }
+  ]
+{% endapple_maps_snapshot_block %}
+```
+![Example map using multiple annotations](/assets/multiple_annotations.png)
+
+## Rate limiting
+Apple specifies the following limits on usage of the Apple Maps Server APIs. This plugin caches snapshot images for the same parameters to avoid regenerating images. But if you initially generate a large number of snapshots (>25,000), you may exceed this limit.
+
+```
+The service provides up to 25,000 service calls per day per team between Apple Maps Server API and MapKit JS. If your app exceeds this quota, the service returns an HTTP 429 error (Too Many Requests) and your app needs to retry later. If your app requires a larger daily quota, submit a quota increase request form.
+
+MapKit JS provides a free daily limit of 250,000 map views and 25,000 service calls per Apple Developer Program membership. For additional capacity needs, contact us.
+https://developer.apple.com/maps/web/
+```
+
+## Development
+
+To execute the test suite locally:
+```
+bundle exec rspec
+```
+
+To build and use the gem locally:
+```
+gem build jekyll-apple-maps.gemspec
+gem install ./jekyll-apple-maps-1.0.0.gem
+```
+
+You can also use the local version of this gem from your gemfile:
+```
+gem 'jekyll-apple-maps', path: '/PathHere/jekyll-apple-maps'
+```
+
+There's also a CLI utility for testing templates. 
++ `-s` Is the source directory where the maps assets should be written to
++ `-r` Is the referer header to use for the request
++ `-h` prints help options
+
+When you execute the script you'll paste in the full template text (as seen above in examples).
+```
+./script/render.rb -s /YourUser/Developer/jekyll-test -r https://example.com
+```

data/lib/jekyll/apple_maps/client.rb

@@ -0,0 +1,37 @@
+require 'net/http'
+require 'uri'
+require 'json'
+require 'digest'
+
+module Jekyll
+  module AppleMaps
+    class AppleMapsClient
+      class AppleMapsNetworkError < StandardError; end
+
+      @@snapshot_base_url = "https://snapshot.apple-mapkit.com/api/v1/snapshot"
+      @@snapshot_uri = URI(@@snapshot_base_url)
+
+      def initialize(api_key)
+        @api_key = api_key
+      end
+
+      def fetch_snapshot(query, referer)
+        query[:token] = @api_key
+        uri = @@snapshot_uri.dup
+        uri.query = URI.encode_www_form(query)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        request = Net::HTTP::Get.new(uri)
+        request['referer'] = referer
+        response = http.request(request)
+        unless response.is_a?(Net::HTTPSuccess)
+          query.delete(:token)
+          raise AppleMapsNetworkError, "Failed to generate map snapshot. Response: #{response.body}, Query: #{query}"
+        end
+
+        response.body
+      end
+    end
+  end
+end

data/lib/jekyll/apple_maps/snapshot_block.rb

@@ -0,0 +1,141 @@
+require 'net/http'
+require 'uri'
+require 'json'
+require 'digest'
+require_relative './client.rb'
+
+module Jekyll
+  module AppleMaps
+    class SnapshotBlock < Liquid::Block
+      class AppleMapsError < StandardError; end
+
+      @@used_snapshots = Set.new
+      @@color_schemes = ['light', 'dark']
+      @@log_prefix = "AppleMapsSnapshotBlock:"
+
+      def initialize(tag_name, markup, options)
+        super
+
+        api_key = ENV['APPLE_MAPS_SNAPSHOT_API_KEY']
+        unless api_key
+          log_and_raise("Apple Maps API key not found")
+        end
+        @client = AppleMapsClient.new(api_key)
+      end
+
+      def render(context)
+        content = super
+        params = YAML.safe_load(content)
+        width = params['width'] || 600
+        height = params['height'] || 300
+        size = "#{width}x#{height}"
+        annotations = params['annotations'] || []
+        overlays = params['overlays'] || []
+        overlay_styles = params['overlay_styles'] || []
+        images = params['images'] || []
+        color_schemes = params['color_schemes'] || ['light', 'dark']
+        color_schemes.uniq!
+        show_poi = params['show_poi'] || true ? 1 : 0
+
+        if color_schemes.empty?
+          log_and_raise("Color Schemes cannot be empty")
+        end
+
+        unless color_schemes.all? { |scheme| @@color_schemes.include?(scheme) }
+          log_and_raise("Invalid color scheme specified, only 'light' and 'dark' are allowed")
+        end
+
+        query = {
+          center: params['center'] || 'auto',
+          annotations: annotations.to_json,
+          overlays: overlays.to_json,
+          overlayStyles: overlay_styles.to_json,
+          imgs: images.to_json,
+          size: size,
+          z: params['zoom'] || 12,
+          t: params['map_type'] || 'standard',
+          scale: params['scale'] || 2,
+          lang: params['language'] || 'en-US',
+          spn: params['span'] || nil,
+          poi: show_poi,
+        }
+        query.compact!
+
+        image_relative_paths = color_schemes.to_h do |color_scheme|
+          query[:colorScheme] = color_scheme
+          [color_scheme, get_relative_path(context, query)]
+        end
+
+        result_tag = "<picture>"
+        image_relative_paths.each do |color_scheme, relative_path|
+          result_tag << "<source srcset='/#{relative_path}' media='(prefers-color-scheme: #{color_scheme})'>"
+        end
+        result_tag << "<img src='/#{image_relative_paths.first}' alt='Map of location'>"
+        result_tag << "</picture>"
+
+        return result_tag
+      end
+
+      def self.cleanup(site)
+        Jekyll.logger.info @@log_prefix, "Starting cleanup of unused snapshots"
+
+        maps_dir = File.join(site.source, 'assets', 'maps')
+        return unless File.directory?(maps_dir)
+
+        Dir.glob(File.join(maps_dir, 'apple_maps_snapshot_*.png')).each do |file|
+          filename = File.basename(file)
+          unless @@used_snapshots.include?(filename)
+            File.delete(file)
+            Jekyll.logger.info @@log_prefix, "Deleted unused map snapshot: #{filename}"
+          end
+        end
+
+        Jekyll.logger.info @@log_prefix, "Cleanup completed"
+      end
+
+      private
+
+      def get_relative_path(context, query)
+        hash = Digest::SHA256.hexdigest(query.to_s)
+        filename = "apple_maps_snapshot_#{hash}.png"
+        relative_path = "assets/maps/#{filename}"
+        full_path = File.join(context.registers[:site].source, relative_path)
+
+        @@used_snapshots.add(filename)
+
+        if File.exist?(full_path)
+          return relative_path
+        end
+
+        Jekyll.logger.info @@log_prefix, "Fetching new snapshot from Apple Maps API"
+        image_data = @client.fetch_snapshot(query, get_referer(context))
+
+        FileUtils.mkdir_p(File.dirname(full_path))
+        static_file = Jekyll::StaticFile.new(context.registers[:site], context.registers[:site].source,
+          File.dirname(relative_path), filename)
+        FileUtils.mkdir_p(File.dirname(static_file.path))
+        File.open(static_file.path, 'wb') do |file|
+          file.write(image_data)
+        end
+        context.registers[:site].static_files << static_file
+
+        return relative_path
+      end
+
+      def get_referer(context)
+        context.registers[:site].config.dig('apple_maps', 'referer') || context.registers[:site].config['url']
+      end
+
+      def log_and_raise(message)
+        Jekyll.logger.error @@log_prefix, message
+        raise AppleMapsError, message
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag('apple_maps_snapshot_block', Jekyll::AppleMaps::SnapshotBlock)
+
+Jekyll::Hooks.register :site, :post_write do |site|
+  Jekyll::AppleMaps::SnapshotBlock.cleanup(site)
+end

data/lib/jekyll/apple_maps/version.rb

@@ -0,0 +1,5 @@
+module Jekyll
+  module AppleMaps
+    VERSION = "1.0.0"
+  end
+end

data/lib/jekyll-apple-maps.rb

@@ -0,0 +1,3 @@
+require 'jekyll'
+
+require_relative "jekyll/apple-maps/snapshot_block.rb"

metadata

@@ -0,0 +1,175 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-apple-maps
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Zeke Snider
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-08-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: liquid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.23.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.23.1
+- !ruby/object:Gem::Dependency
+  name: fakefs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+description: Provides tags for the Jekyll blogging engine to generate Apple Maps content
+  for your site.
+email:
+- zekesnider@me.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/jekyll-apple-maps.rb
+- lib/jekyll/apple_maps/client.rb
+- lib/jekyll/apple_maps/snapshot_block.rb
+- lib/jekyll/apple_maps/version.rb
+homepage: https://github.com/zekesnider/jekyll-apple-maps
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: Apple Maps plugin for Jekyll
+test_files: []