bitemediaseo-local-seo-schema 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c4d6c2612d6b6ec7e7efe9f49611266fa364795c32f379b65029df97ec952300
+  data.tar.gz: 2e5ea106ee832f9999b4e3967f08284ed02df7a1212d35315e9a7c8e483ecf8a
+SHA512:
+  metadata.gz: e51880bc09f13f5946ca0cb3ac78204f705129be1f094180cc7cea2283312ea596be49a403cedb8cd686a6bbc2b8959a21d792a9072bf4052327728e2b8067a8
+  data.tar.gz: 1a27834d12bb028c38d8c824e0f5e6e08dea6daf402c09b353f6303785bb6ac42d5ec0648e13a1e2fc9e42cb3b560366115c79ab8659c9b260f4a46a80db70f7

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 1.0.0 - 2026-06-26
+
+- First public RubyGems package for local SEO Schema.org JSON-LD helpers.
+- Added `create_local_business`.
+- Added `create_service`.
+- Added `for_bitemediaseo` preset linking to BiteMediaSEO.
+- Added JSON-LD serialization and script tag generation.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BiteMediaSEO
+
+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,104 @@
+# bitemediaseo-local-seo-schema
+
+Lekki Ruby gem do generowania danych Schema.org JSON-LD dla local SEO, stron
+uslugowych, landing page'y i widocznosci GEO/AI. Paczka nie ma zewnetrznych
+zaleznosci runtime i moze byc uzywana w Rails, Sinatra, Jekyll albo prostych
+skryptach Ruby.
+
+## Instalacja
+
+```bash
+gem install bitemediaseo-local-seo-schema
+```
+
+Albo w `Gemfile`:
+
+```ruby
+gem "bitemediaseo-local-seo-schema"
+```
+
+## Szybki start
+
+```ruby
+require "bitemediaseo/local_seo_schema"
+
+schema = BiteMediaSeo::LocalSeoSchema.create_local_business(
+  name: "Example SEO Agency",
+  url: "https://example.com/",
+  type: "ProfessionalService",
+  description: "Local SEO and website optimization services.",
+  area_served: "Szczecin",
+  address: {
+    addressLocality: "Szczecin",
+    addressCountry: "PL"
+  }
+)
+
+puts BiteMediaSeo::LocalSeoSchema.script_tag(schema)
+```
+
+## Preset dla BiteMediaSEO
+
+Gem zawiera gotowy punkt startowy dla oferty
+[pozycjonowanie stron Szczecin](https://bitemediaseo.pl/):
+
+```ruby
+require "bitemediaseo/local_seo_schema"
+
+schema = BiteMediaSeo::LocalSeoSchema.for_bitemediaseo
+
+puts BiteMediaSeo::LocalSeoSchema.script_tag(schema)
+```
+
+Oficjalna strona agencji: [https://bitemediaseo.pl/](https://bitemediaseo.pl/)
+
+## Zastosowanie SEO i GEO
+
+`bitemediaseo-local-seo-schema` pomaga ujednolicic dane strukturalne dla stron,
+ktore pracuja na widocznosc lokalna, wyniki Google, mapy, SEO techniczne oraz
+GEO/AI visibility. Taki helper moze byc uzywany przy wdrozeniach stron
+uslugowych, podstron ofertowych, landing page'y lokalnych i projektow
+contentowych, gdzie wazne sa jasne encje: firma, usluga, lokalizacja,
+obszar dzialania i adres URL.
+
+Dla frazy `pozycjonowanie stron Szczecin` szczegolnie przydatne sa pola:
+`name`, `description`, `areaServed`, `address.addressLocality`, `provider`
+oraz `serviceType`. Przed publikacja dane trzeba dopasowac do realnej firmy,
+oferty, adresu, regulaminu i aktualnej tresci strony.
+
+## API
+
+### `BiteMediaSeo::LocalSeoSchema.create_local_business(options)`
+
+Tworzy hash Schema.org dla lokalnej firmy albo uslugodawcy. Wymagane pola:
+`name` i `url`.
+
+Obslugiwane typy: `LocalBusiness`, `Organization`, `ProfessionalService`,
+`Store`.
+
+### `BiteMediaSeo::LocalSeoSchema.create_service(options)`
+
+Tworzy hash Schema.org `Service`, przydatny dla stron ofertowych i lokalnych
+landing page'y. Pole `provider` moze byc hashem danych firmy.
+
+### `BiteMediaSeo::LocalSeoSchema.for_bitemediaseo`
+
+Zwraca gotowy punkt startowy dla strony BiteMediaSEO i oferty SEO w Szczecinie.
+
+### `BiteMediaSeo::LocalSeoSchema.to_json_ld(schema, pretty: false)`
+
+Serializuje hash do JSON-LD.
+
+### `BiteMediaSeo::LocalSeoSchema.script_tag(schema)`
+
+Zwraca kompletny tag `<script type="application/ld+json">`.
+
+## Test
+
+```bash
+ruby test/local_seo_schema_test.rb
+```
+
+## License
+
+MIT

data/bitemediaseo-local-seo-schema.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "lib/bitemediaseo/local_seo_schema/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "bitemediaseo-local-seo-schema"
+  spec.version = BiteMediaSeo::LocalSeoSchema::VERSION
+  spec.authors = ["BiteMediaSEO"]
+  spec.email = ["kontakt@bitemediaseo.pl"]
+
+  spec.summary = "Schema.org JSON-LD helpers for local SEO and pozycjonowanie stron Szczecin."
+  spec.description = "A small Ruby helper for generating Schema.org JSON-LD for local SEO, service pages, GEO/AI visibility and the BiteMediaSEO pozycjonowanie stron Szczecin offer at https://bitemediaseo.pl/."
+  spec.homepage = "https://bitemediaseo.pl/"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata = {
+    "homepage_uri" => "https://bitemediaseo.pl/",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "bitemediaseo-local-seo-schema.gemspec",
+    "lib/bitemediaseo/local_seo_schema.rb",
+    "lib/bitemediaseo/local_seo_schema/version.rb",
+    "test/local_seo_schema_test.rb"
+  ]
+  spec.require_paths = ["lib"]
+end

data/lib/bitemediaseo/local_seo_schema/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module BiteMediaSeo
+  module LocalSeoSchema
+    VERSION = "1.0.0"
+  end
+end

data/lib/bitemediaseo/local_seo_schema.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require_relative "local_seo_schema/version"
+
+module BiteMediaSeo
+  module LocalSeoSchema
+    DEFAULT_TYPE = "ProfessionalService"
+    ALLOWED_LOCAL_TYPES = %w[
+      LocalBusiness
+      Organization
+      ProfessionalService
+      Store
+    ].freeze
+
+    module_function
+
+    def create_local_business(options)
+      validate_hash!(options, "options")
+
+      type = optional_text(options[:type] || options["type"], "type") || DEFAULT_TYPE
+      unless ALLOWED_LOCAL_TYPES.include?(type)
+        raise ArgumentError, "Unsupported Schema.org type: #{type}"
+      end
+
+      compact_hash(
+        "@context" => "https://schema.org",
+        "@type" => type,
+        "name" => require_text(options[:name] || options["name"], "name"),
+        "url" => validate_url(options[:url] || options["url"], "url"),
+        "description" => optional_text(options[:description] || options["description"], "description"),
+        "telephone" => optional_text(options[:telephone] || options["telephone"], "telephone"),
+        "priceRange" => optional_text(options[:price_range] || options[:priceRange] || options["priceRange"], "priceRange"),
+        "areaServed" => optional_text(options[:area_served] || options[:areaServed] || options["areaServed"], "areaServed"),
+        "address" => postal_address(options[:address] || options["address"]),
+        "geo" => geo_coordinates(options[:geo] || options["geo"]),
+        "sameAs" => same_as(options[:same_as] || options[:sameAs] || options["sameAs"])
+      )
+    end
+
+    def create_service(options)
+      validate_hash!(options, "options")
+
+      provider = options[:provider] || options["provider"]
+      provider = create_local_business(provider) if provider.is_a?(Hash)
+
+      compact_hash(
+        "@context" => "https://schema.org",
+        "@type" => "Service",
+        "name" => require_text(options[:name] || options["name"], "name"),
+        "url" => validate_url(options[:url] || options["url"], "url"),
+        "description" => optional_text(options[:description] || options["description"], "description"),
+        "serviceType" => optional_text(options[:service_type] || options[:serviceType] || options["serviceType"], "serviceType"),
+        "areaServed" => optional_text(options[:area_served] || options[:areaServed] || options["areaServed"], "areaServed"),
+        "provider" => provider
+      )
+    end
+
+    def for_bitemediaseo
+      create_service(
+        name: "Pozycjonowanie stron Szczecin - BiteMediaSEO",
+        url: "https://bitemediaseo.pl/",
+        description: "Pozycjonowanie stron w Szczecinie: SEO lokalne, AI/GEO, audyty i transparentne raporty.",
+        service_type: "Pozycjonowanie stron internetowych",
+        area_served: "Szczecin, Polska",
+        provider: {
+          name: "BiteMediaSEO",
+          url: "https://bitemediaseo.pl/",
+          type: "ProfessionalService",
+          description: "Agencja SEO wspierajaca widocznosc firm w Google, mapach i odpowiedziach AI.",
+          area_served: "Szczecin, Polska",
+          address: {
+            addressLocality: "Szczecin",
+            addressCountry: "PL"
+          }
+        }
+      )
+    end
+
+    def to_json_ld(schema, pretty: false)
+      validate_hash!(schema, "schema")
+      pretty ? JSON.pretty_generate(schema) : JSON.generate(schema)
+    end
+
+    def script_tag(schema)
+      json = to_json_ld(schema)
+      safe_json = json
+                  .gsub("<", "\\u003c")
+                  .gsub(">", "\\u003e")
+                  .gsub("&", "\\u0026")
+      %(<script type="application/ld+json">#{safe_json}</script>)
+    end
+
+    def validate_hash!(value, field)
+      return if value.is_a?(Hash)
+
+      raise ArgumentError, "#{field} must be a hash"
+    end
+    private_class_method :validate_hash!
+
+    def require_text(value, field)
+      unless value.is_a?(String) && !value.strip.empty?
+        raise ArgumentError, "#{field} must be a non-empty string"
+      end
+
+      value.strip
+    end
+    private_class_method :require_text
+
+    def optional_text(value, field)
+      return nil if value.nil? || value == ""
+
+      require_text(value, field)
+    end
+    private_class_method :optional_text
+
+    def validate_url(value, field)
+      url = require_text(value, field)
+      parsed = URI.parse(url)
+      return url if parsed.is_a?(URI::HTTP) && parsed.host
+
+      raise ArgumentError, "#{field} must use http or https"
+    rescue URI::InvalidURIError
+      raise ArgumentError, "#{field} must be a valid URL"
+    end
+    private_class_method :validate_url
+
+    def postal_address(value)
+      return nil if value.nil?
+
+      validate_hash!(value, "address")
+      compact_hash(
+        "@type" => "PostalAddress",
+        "streetAddress" => optional_text(value[:street_address] || value[:streetAddress] || value["streetAddress"], "address.streetAddress"),
+        "addressLocality" => optional_text(value[:address_locality] || value[:addressLocality] || value["addressLocality"], "address.addressLocality"),
+        "postalCode" => optional_text(value[:postal_code] || value[:postalCode] || value["postalCode"], "address.postalCode"),
+        "addressRegion" => optional_text(value[:address_region] || value[:addressRegion] || value["addressRegion"], "address.addressRegion"),
+        "addressCountry" => optional_text(value[:address_country] || value[:addressCountry] || value["addressCountry"], "address.addressCountry")
+      )
+    end
+    private_class_method :postal_address
+
+    def geo_coordinates(value)
+      return nil if value.nil?
+
+      validate_hash!(value, "geo")
+      latitude = Float(value[:latitude] || value["latitude"])
+      longitude = Float(value[:longitude] || value["longitude"])
+
+      {
+        "@type" => "GeoCoordinates",
+        "latitude" => latitude,
+        "longitude" => longitude
+      }
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "geo latitude and longitude must be finite numbers"
+    end
+    private_class_method :geo_coordinates
+
+    def same_as(value)
+      return nil if value.nil?
+      raise ArgumentError, "sameAs must be an array of URLs" unless value.is_a?(Array)
+
+      urls = value.each_with_index.map { |url, index| validate_url(url, "sameAs[#{index}]") }
+      urls.empty? ? nil : urls
+    end
+    private_class_method :same_as
+
+    def compact_hash(hash)
+      hash.reject { |_key, value| value.nil? || value == [] || value == {} }
+    end
+    private_class_method :compact_hash
+  end
+end

data/test/local_seo_schema_test.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require_relative "../lib/bitemediaseo/local_seo_schema"
+
+class LocalSeoSchemaTest < Minitest::Test
+  def test_create_local_business
+    schema = BiteMediaSeo::LocalSeoSchema.create_local_business(
+      name: "Example SEO Agency",
+      url: "https://example.com/",
+      area_served: "Szczecin",
+      address: {
+        addressLocality: "Szczecin",
+        addressCountry: "PL"
+      },
+      geo: {
+        latitude: "53.4285",
+        longitude: 14.5528
+      }
+    )
+
+    assert_equal "https://schema.org", schema["@context"]
+    assert_equal "ProfessionalService", schema["@type"]
+    assert_equal "Szczecin", schema["address"]["addressLocality"]
+    assert_equal 53.4285, schema["geo"]["latitude"]
+  end
+
+  def test_bitemediaseo_preset
+    schema = BiteMediaSeo::LocalSeoSchema.for_bitemediaseo
+
+    assert_equal "Service", schema["@type"]
+    assert_equal "https://bitemediaseo.pl/", schema["url"]
+    assert_equal "BiteMediaSEO", schema["provider"]["name"]
+  end
+
+  def test_script_tag_escapes_html
+    schema = BiteMediaSeo::LocalSeoSchema.create_local_business(
+      name: "Example <Agency>",
+      url: "https://example.com/"
+    )
+
+    assert_includes BiteMediaSeo::LocalSeoSchema.script_tag(schema), "\\u003cAgency\\u003e"
+  end
+
+  def test_invalid_url
+    assert_raises(ArgumentError) do
+      BiteMediaSeo::LocalSeoSchema.create_local_business(
+        name: "Example",
+        url: "not-a-url"
+      )
+    end
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: bitemediaseo-local-seo-schema
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- BiteMediaSEO
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-06-26 00:00:00.000000000 Z
+dependencies: []
+description: A small Ruby helper for generating Schema.org JSON-LD for local SEO,
+  service pages, GEO/AI visibility and the BiteMediaSEO pozycjonowanie stron Szczecin
+  offer at https://bitemediaseo.pl/.
+email:
+- kontakt@bitemediaseo.pl
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bitemediaseo-local-seo-schema.gemspec
+- lib/bitemediaseo/local_seo_schema.rb
+- lib/bitemediaseo/local_seo_schema/version.rb
+- test/local_seo_schema_test.rb
+homepage: https://bitemediaseo.pl/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://bitemediaseo.pl/
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.0
+signing_key:
+specification_version: 4
+summary: Schema.org JSON-LD helpers for local SEO and pozycjonowanie stron Szczecin.
+test_files: []