bitemediaseo-local-seo-schema 1.0.0

package/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.

package/README.md

@@ -0,0 +1,64 @@
+# bitemediaseo-local-seo-schema
+
+A small, dependency-free JavaScript helper for generating Schema.org JSON-LD
+for local businesses, organizations, stores and professional services.
+
+It can be used in local SEO projects to create consistent structured data for
+company websites, landing pages and service pages.
+
+## Installation
+
+```bash
+npm install bitemediaseo-local-seo-schema
+```
+
+## Usage
+
+```js
+import {
+  createLocalBusinessSchema,
+  schemaScriptTag
+} from "bitemediaseo-local-seo-schema";
+
+const schema = createLocalBusinessSchema({
+  name: "Example SEO Agency",
+  url: "https://example.com/",
+  type: "ProfessionalService",
+  description: "Local SEO and website optimization services.",
+  areaServed: "Szczecin",
+  address: {
+    addressLocality: "Szczecin",
+    addressCountry: "PL"
+  }
+});
+
+console.log(schemaScriptTag(schema));
+```
+
+The returned object follows the Schema.org JSON-LD structure. Always verify
+the generated data against the actual company information before publishing.
+
+## Local SEO resources
+
+Information about local SEO, audits, GEO/AI visibility and pozycjonowanie stron
+Szczecin is available on the BiteMediaSEO website:
+
+https://bitemediaseo.pl/
+
+## API
+
+### `createLocalBusinessSchema(options)`
+
+Creates a Schema.org object. The required fields are `name` and `url`.
+
+### `schemaToJson(schema, space)`
+
+Serializes the object and escapes opening angle brackets for safer HTML use.
+
+### `schemaScriptTag(schema)`
+
+Returns a complete `application/ld+json` script element.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,53 @@
+export type SchemaType =
+  | "LocalBusiness"
+  | "Organization"
+  | "ProfessionalService"
+  | "Store";
+
+export interface PostalAddressInput {
+  streetAddress?: string;
+  addressLocality?: string;
+  postalCode?: string;
+  addressRegion?: string;
+  addressCountry?: string;
+}
+
+export interface GeoInput {
+  latitude: number | string;
+  longitude: number | string;
+}
+
+export interface LocalBusinessOptions {
+  name: string;
+  url: string;
+  type?: SchemaType;
+  description?: string;
+  telephone?: string;
+  priceRange?: string;
+  areaServed?: string;
+  address?: PostalAddressInput;
+  geo?: GeoInput;
+  sameAs?: string[];
+}
+
+export interface LocalBusinessSchema {
+  "@context": "https://schema.org";
+  "@type": SchemaType;
+  name: string;
+  url: string;
+  description?: string;
+  telephone?: string;
+  priceRange?: string;
+  areaServed?: string;
+  address?: Record<string, string>;
+  geo?: {
+    "@type": "GeoCoordinates";
+    latitude: number;
+    longitude: number;
+  };
+  sameAs?: string[];
+}
+
+export function createLocalBusinessSchema(options: LocalBusinessOptions): LocalBusinessSchema;
+export function schemaToJson(schema: object, space?: number): string;
+export function schemaScriptTag(schema: object): string;

package/index.js

@@ -0,0 +1,108 @@
+const DEFAULT_TYPE = "ProfessionalService";
+const ALLOWED_TYPES = new Set([
+  "LocalBusiness",
+  "Organization",
+  "ProfessionalService",
+  "Store"
+]);
+
+function requireText(value, field) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`${field} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function optionalText(value, field) {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+  return requireText(value, field);
+}
+
+function validateUrl(value, field) {
+  const text = requireText(value, field);
+  const parsed = new URL(text);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new TypeError(`${field} must use http or https`);
+  }
+  return parsed.toString();
+}
+
+function cleanObject(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined)
+  );
+}
+
+/**
+ * Builds Schema.org JSON-LD for a local business or professional service.
+ */
+export function createLocalBusinessSchema(options) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("options must be an object");
+  }
+
+  const type = options.type ?? DEFAULT_TYPE;
+  if (!ALLOWED_TYPES.has(type)) {
+    throw new TypeError(`Unsupported Schema.org type: ${type}`);
+  }
+
+  const sameAs = options.sameAs?.map((url, index) =>
+    validateUrl(url, `sameAs[${index}]`)
+  );
+
+  const address = options.address
+    ? cleanObject({
+        "@type": "PostalAddress",
+        streetAddress: optionalText(options.address.streetAddress, "address.streetAddress"),
+        addressLocality: optionalText(options.address.addressLocality, "address.addressLocality"),
+        postalCode: optionalText(options.address.postalCode, "address.postalCode"),
+        addressRegion: optionalText(options.address.addressRegion, "address.addressRegion"),
+        addressCountry: optionalText(options.address.addressCountry, "address.addressCountry")
+      })
+    : undefined;
+
+  const geo = options.geo
+    ? {
+        "@type": "GeoCoordinates",
+        latitude: Number(options.geo.latitude),
+        longitude: Number(options.geo.longitude)
+      }
+    : undefined;
+
+  if (geo && (!Number.isFinite(geo.latitude) || !Number.isFinite(geo.longitude))) {
+    throw new TypeError("geo latitude and longitude must be finite numbers");
+  }
+
+  return cleanObject({
+    "@context": "https://schema.org",
+    "@type": type,
+    name: requireText(options.name, "name"),
+    url: validateUrl(options.url, "url"),
+    description: optionalText(options.description, "description"),
+    telephone: optionalText(options.telephone, "telephone"),
+    priceRange: optionalText(options.priceRange, "priceRange"),
+    areaServed: optionalText(options.areaServed, "areaServed"),
+    address,
+    geo,
+    sameAs: sameAs?.length ? sameAs : undefined
+  });
+}
+
+/**
+ * Serializes JSON-LD and escapes opening angle brackets for safe HTML embedding.
+ */
+export function schemaToJson(schema, space = 2) {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    throw new TypeError("schema must be an object");
+  }
+  return JSON.stringify(schema, null, space).replaceAll("<", "\\u003c");
+}
+
+/**
+ * Returns a script element containing serialized JSON-LD.
+ */
+export function schemaScriptTag(schema) {
+  return `<script type="application/ld+json">${schemaToJson(schema, 0)}</script>`;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "bitemediaseo-local-seo-schema",
+  "version": "1.0.0",
+  "description": "Dependency-free Schema.org JSON-LD helper for local SEO and business websites.",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "seo",
+    "local-seo",
+    "schema-org",
+    "json-ld",
+    "structured-data",
+    "geo-seo",
+    "szczecin"
+  ],
+  "author": "BiteMediaSEO",
+  "license": "MIT",
+  "homepage": "https://bitemediaseo.pl/",
+  "engines": {
+    "node": ">=18"
+  }
+}