pinterest-url-normalizer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5293ed706c039755df8a8f487ffb434813eaf3a7c26bdd35b18f24b22decb4d9
+  data.tar.gz: e058bc0992ee1da9af2470a04fec5b148bf2dbb756f0666fad6db4ff76d64f1d
+SHA512:
+  metadata.gz: 03b33feb90157133ee8dc29fa422d1800694f4a24ed2662642f9034150214f8a83f8f97a7b75a4de00b965a2516ff9cc49572528ad7a2ed9310c64b14539d8bd
+  data.tar.gz: a593d71cded361ce53a460ea4b7226c757bf4e7899d35b182404b6380e2d0c0274855aed1947c686206397c7614b6ce1cc114f2019b7b7eeda91097a662ec765

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SavePinner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,62 @@
+# pinterest-url-normalizer
+
+Parse, classify, and normalize Pinterest URLs in Ruby without making network requests.
+
+[SavePinner](https://savepinner.com/pinterest-downloader/) · [RubyGems](https://rubygems.org/gems/pinterest-url-normalizer) · [RubyDoc.info](https://www.rubydoc.info/gems/pinterest-url-normalizer) · [npm](https://www.npmjs.com/package/pinterest-url-normalizer) · [PyPI](https://pypi.org/project/pinterest-url-normalizer/) · [crates.io](https://crates.io/crates/pinterest-url-normalizer) · [Packagist](https://packagist.org/packages/savepinner/pinterest-url-normalizer) · [Go](https://pkg.go.dev/github.com/jiankn/pinterest-url-normalizer-go)
+
+The gem recognizes Pin, `pin.it`, profile, board, and Ideas URLs across Pinterest country domains. It uses an exact host allow list, rejects HTTP URLs and lookalike domains, and removes query parameters and fragments from normalized output.
+
+## Install
+
+```bash
+gem install pinterest-url-normalizer
+```
+
+## Library
+
+```ruby
+require "pinterest_url_normalizer"
+
+parsed = PinterestURLNormalizer.parse(
+  "https://de.pinterest.com/pin/987654321/?utm_source=share"
+)
+
+parsed.pin_id
+# => "987654321"
+
+parsed.normalized_url
+# => "https://www.pinterest.com/pin/987654321/"
+```
+
+## CLI
+
+```bash
+pinterest-url-normalizer \
+  "https://de.pinterest.com/pin/987654321/?utm_source=share" \
+  "https://pin.it/AbC123"
+```
+
+Read one URL per line and emit JSON Lines:
+
+```bash
+printf '%s\n' 'https://www.pinterest.com/pin/123/' | \
+  pinterest-url-normalizer --json
+```
+
+The process exits with status `1` when any input is invalid and status `2` for usage errors.
+
+## Supported URLs
+
+| Kind | Example |
+| --- | --- |
+| Pin | `https://www.pinterest.com/pin/123456789/` |
+| Short | `https://pin.it/AbC123` |
+| Profile | `https://www.pinterest.com/savepinner/` |
+| Board | `https://www.pinterest.com/savepinner/media-tools/` |
+| Ideas | `https://www.pinterest.com/ideas/space-wallpaper/926295399832/` |
+
+`pin.it` links are classified and normalized but are not followed. Resolving them requires a network request and belongs in the consuming application.
+
+## License
+
+MIT

data/exe/pinterest-url-normalizer

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "pinterest_url_normalizer/cli"
+
+exit PinterestURLNormalizer::CLI.run(ARGV)

data/lib/pinterest_url_normalizer/cli.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../pinterest_url_normalizer"
+
+module PinterestURLNormalizer
+  # Command-line interface for the gem executable.
+  module CLI
+    module_function
+
+    def run(arguments, input: $stdin, output: $stdout, error: $stderr)
+      json_output = false
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: pinterest-url-normalizer [--json] [URL ...]"
+        options.on("--json", "Emit JSON Lines") { json_output = true }
+      end
+
+      urls = arguments.dup
+      begin
+        parser.parse!(urls)
+      rescue OptionParser::ParseError => exception
+        error.puts exception.message
+        error.puts parser
+        return 2
+      end
+
+      urls = input.each_line.map(&:strip).reject(&:empty?) if urls.empty?
+      if urls.empty?
+        error.puts parser
+        return 2
+      end
+
+      exit_code = 0
+      urls.each do |url|
+        begin
+          parsed = PinterestURLNormalizer.parse(url)
+          if json_output
+            output.puts JSON.generate(parsed.to_h.compact)
+          else
+            output.puts parsed.normalized_url
+          end
+        rescue Error => exception
+          exit_code = 1
+          if json_output
+            output.puts JSON.generate(
+              input: url,
+              error: { code: exception.code, message: exception.message }
+            )
+          else
+            error.puts "#{exception.code}: #{exception.message}: #{url}"
+          end
+        end
+      end
+      exit_code
+    end
+  end
+end

data/lib/pinterest_url_normalizer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PinterestURLNormalizer
+  VERSION = "0.1.0"
+end

data/lib/pinterest_url_normalizer.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "pinterest_url_normalizer/version"
+
+# Parses, classifies, and normalizes supported Pinterest URLs without making
+# network requests.
+#
+# Full Pinterest URLs are normalized to www.pinterest.com. Short pin.it links
+# retain their host because resolving them requires a network request.
+#
+# SavePinner: https://savepinner.com/pinterest-downloader/
+module PinterestURLNormalizer
+  CANONICAL_HOST = "www.pinterest.com"
+  SHORT_HOST = "pin.it"
+  MAX_URL_LENGTH = 2048
+
+  COUNTRY_HOSTS = %w[
+    pinterest.at pinterest.be pinterest.ca pinterest.ch pinterest.cl
+    pinterest.co pinterest.co.kr pinterest.co.nz pinterest.co.uk
+    pinterest.com.au pinterest.com.br pinterest.com.mx pinterest.com.pe
+    pinterest.com.tr pinterest.cz pinterest.de pinterest.dk pinterest.es
+    pinterest.fi pinterest.fr pinterest.gr pinterest.hu pinterest.id
+    pinterest.ie pinterest.it pinterest.jp pinterest.nl pinterest.no
+    pinterest.ph pinterest.pl pinterest.pt pinterest.ro pinterest.se
+    pinterest.sk
+  ].freeze
+
+  REGIONAL_SUBDOMAINS = %w[
+    at au be br ca ch cl co cz de dk es fi fr gr hu id ie it jp kr mx nl
+    no nz pe ph pl pt ro se sk tr uk
+  ].freeze
+
+  RESERVED_FIRST_SEGMENTS = %w[
+    business categories explore help ideas login logout oauth pin pin-builder
+    resource search settings signup today topics
+  ].freeze
+
+  # A supported Pinterest URL and its canonical fields.
+  ParsedURL = Struct.new(
+    :kind,
+    :original_url,
+    :normalized_url,
+    :host,
+    :pin_id,
+    :shortcode,
+    :username,
+    :board_slug,
+    :idea_slug,
+    :idea_id,
+    keyword_init: true
+  )
+
+  # An invalid URL or unsupported Pinterest path.
+  class Error < StandardError
+    attr_reader :code
+
+    def initialize(code, message)
+      @code = code
+      super(message)
+    end
+  end
+
+  module_function
+
+  # Parses a supported Pinterest URL and returns its canonical fields.
+  def parse(input)
+    original = input.to_s.strip
+    raise_invalid("URL is empty or too long") if original.empty? || original.bytesize > MAX_URL_LENGTH
+
+    uri = URI.parse(original)
+    raise_invalid("URL could not be parsed") unless uri.host
+    raise_invalid("only HTTPS URLs are supported") unless uri.scheme == "https"
+    raise_invalid("credentials are not supported") if uri.userinfo
+    raise_invalid("non-standard ports are not supported") unless uri.port == 443
+    raise_invalid("encoded paths are not supported") if uri.path.include?("%")
+
+    host = uri.host.downcase
+    segments = uri.path.split("/").reject(&:empty?)
+    return parse_short(original, segments) if host == SHORT_HOST
+
+    raise_invalid("host is not an allowed Pinterest domain") unless pinterest_host?(host)
+
+    parse_pin(original, segments) ||
+      parse_ideas(original, segments) ||
+      parse_profile_or_board(original, segments)
+  rescue URI::InvalidURIError, URI::InvalidComponentError, ArgumentError
+    raise_invalid("URL could not be parsed")
+  end
+
+  # Returns the canonical URL for a supported Pinterest URL.
+  def normalize(input)
+    parse(input).normalized_url
+  end
+
+  # Reports whether input is a supported Pinterest URL.
+  def pinterest_url?(input)
+    parse(input)
+    true
+  rescue Error
+    false
+  end
+
+  # Reports whether host is an exact supported Pinterest host.
+  def pinterest_host?(host)
+    host = host.to_s.downcase
+    return true if %w[pinterest.com www.pinterest.com m.pinterest.com].include?(host)
+    return true if COUNTRY_HOSTS.include?(host)
+    return true if host.start_with?("www.") && COUNTRY_HOSTS.include?(host.delete_prefix("www."))
+
+    region = host.delete_suffix(".pinterest.com")
+    region != host && REGIONAL_SUBDOMAINS.include?(region)
+  end
+
+  def parse_short(original, segments)
+    unless segments.length == 1 && segments.first.length >= 2 && ascii_alphanumeric?(segments.first)
+      raise_unsupported("unsupported pin.it path")
+    end
+
+    shortcode = segments.first
+    ParsedURL.new(
+      kind: "short",
+      original_url: original,
+      normalized_url: "https://#{SHORT_HOST}/#{shortcode}/",
+      host: SHORT_HOST,
+      shortcode: shortcode
+    )
+  end
+  private_class_method :parse_short
+
+  def parse_pin(original, segments)
+    return unless [2, 3].include?(segments.length) && segments.first == "pin"
+
+    pin_segment = segments[1]
+    pin_id = if numeric_id?(pin_segment)
+               pin_segment
+             else
+               candidate = pin_segment.rpartition("--").last
+               candidate if slug?(pin_segment) && numeric_id?(candidate)
+             end
+    return unless pin_id
+    return if segments.length == 3 && !slug?(segments[2])
+
+    ParsedURL.new(
+      kind: "pin",
+      original_url: original,
+      normalized_url: "https://#{CANONICAL_HOST}/pin/#{pin_id}/",
+      host: CANONICAL_HOST,
+      pin_id: pin_id
+    )
+  end
+  private_class_method :parse_pin
+
+  def parse_ideas(original, segments)
+    return unless segments.length == 3 && segments.first == "ideas"
+    return unless slug?(segments[1]) && numeric_id?(segments[2])
+
+    ParsedURL.new(
+      kind: "ideas",
+      original_url: original,
+      normalized_url: "https://#{CANONICAL_HOST}/ideas/#{segments[1]}/#{segments[2]}/",
+      host: CANONICAL_HOST,
+      idea_slug: segments[1],
+      idea_id: segments[2]
+    )
+  end
+  private_class_method :parse_ideas
+
+  def parse_profile_or_board(original, segments)
+    username = segments.first
+    raise_unsupported("unsupported Pinterest path") unless username
+    raise_unsupported("unsupported Pinterest path") if RESERVED_FIRST_SEGMENTS.include?(username.downcase)
+
+    if segments.length == 1 && username?(username)
+      return ParsedURL.new(
+        kind: "profile",
+        original_url: original,
+        normalized_url: "https://#{CANONICAL_HOST}/#{username}/",
+        host: CANONICAL_HOST,
+        username: username
+      )
+    end
+
+    if segments.length == 2 && username?(username) && slug?(segments[1])
+      return ParsedURL.new(
+        kind: "board",
+        original_url: original,
+        normalized_url: "https://#{CANONICAL_HOST}/#{username}/#{segments[1]}/",
+        host: CANONICAL_HOST,
+        username: username,
+        board_slug: segments[1]
+      )
+    end
+
+    raise_unsupported("unsupported Pinterest path")
+  end
+  private_class_method :parse_profile_or_board
+
+  def numeric_id?(value)
+    value.match?(/\A\d{1,20}\z/)
+  end
+  private_class_method :numeric_id?
+
+  def ascii_alphanumeric?(value)
+    value.match?(/\A[A-Za-z0-9]+\z/)
+  end
+  private_class_method :ascii_alphanumeric?
+
+  def slug?(value)
+    value.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/)
+  end
+  private_class_method :slug?
+
+  def username?(value)
+    value.match?(/\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/)
+  end
+  private_class_method :username?
+
+  def raise_invalid(message)
+    raise Error.new("INVALID_URL", message)
+  end
+  private_class_method :raise_invalid
+
+  def raise_unsupported(message)
+    raise Error.new("UNSUPPORTED_URL", message)
+  end
+  private_class_method :raise_unsupported
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: pinterest-url-normalizer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- SavePinner
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.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'
+description: A network-free Pinterest URL parser and normalizer with an exact host
+  allow list.
+email:
+- jiankn@users.noreply.github.com
+executables:
+- pinterest-url-normalizer
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/pinterest-url-normalizer
+- lib/pinterest_url_normalizer.rb
+- lib/pinterest_url_normalizer/cli.rb
+- lib/pinterest_url_normalizer/version.rb
+homepage: https://savepinner.com/pinterest-downloader/
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/jiankn/pinterest-url-normalizer-ruby
+  documentation_uri: https://www.rubydoc.info/gems/pinterest-url-normalizer
+  homepage_uri: https://savepinner.com/pinterest-downloader/
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Parse, classify, and normalize Pinterest URLs
+test_files: []