@coherent.js/seo 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thomas Drouvin
+
+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/dist/index.js

@@ -0,0 +1,549 @@
+// src/meta.js
+var MetaBuilder = class {
+  constructor(defaults = {}) {
+    this.defaults = {
+      siteName: "",
+      siteUrl: "",
+      locale: "en_US",
+      twitterHandle: "",
+      ...defaults
+    };
+    this.tags = [];
+  }
+  /**
+   * Set page title
+   */
+  title(title, options = {}) {
+    const fullTitle = options.template ? options.template.replace("%s", title) : title;
+    this.tags.push({ title: { text: fullTitle } });
+    this.og("title", fullTitle);
+    this.twitter("title", fullTitle);
+    return this;
+  }
+  /**
+   * Set page description
+   */
+  description(description) {
+    this.tags.push({
+      meta: {
+        name: "description",
+        content: description
+      }
+    });
+    this.og("description", description);
+    this.twitter("description", description);
+    return this;
+  }
+  /**
+   * Set canonical URL
+   */
+  canonical(url) {
+    this.tags.push({
+      link: {
+        rel: "canonical",
+        href: url
+      }
+    });
+    this.og("url", url);
+    return this;
+  }
+  /**
+   * Set keywords
+   */
+  keywords(keywords) {
+    const keywordString = Array.isArray(keywords) ? keywords.join(", ") : keywords;
+    this.tags.push({
+      meta: {
+        name: "keywords",
+        content: keywordString
+      }
+    });
+    return this;
+  }
+  /**
+   * Set robots directives
+   */
+  robots(directives) {
+    const content = Array.isArray(directives) ? directives.join(", ") : directives;
+    this.tags.push({
+      meta: {
+        name: "robots",
+        content
+      }
+    });
+    return this;
+  }
+  /**
+   * Set Open Graph tag
+   */
+  og(property, content) {
+    this.tags.push({
+      meta: {
+        property: `og:${property}`,
+        content
+      }
+    });
+    return this;
+  }
+  /**
+   * Set Twitter Card tag
+   */
+  twitter(name, content) {
+    this.tags.push({
+      meta: {
+        name: `twitter:${name}`,
+        content
+      }
+    });
+    return this;
+  }
+  /**
+   * Set image for social sharing
+   */
+  image(url, options = {}) {
+    this.og("image", url);
+    if (options.width) this.og("image:width", options.width);
+    if (options.height) this.og("image:height", options.height);
+    if (options.alt) this.og("image:alt", options.alt);
+    this.twitter("image", url);
+    if (options.alt) this.twitter("image:alt", options.alt);
+    return this;
+  }
+  /**
+   * Set article metadata
+   */
+  article(options = {}) {
+    this.og("type", "article");
+    if (options.publishedTime) {
+      this.og("article:published_time", options.publishedTime);
+    }
+    if (options.modifiedTime) {
+      this.og("article:modified_time", options.modifiedTime);
+    }
+    if (options.author) {
+      this.og("article:author", options.author);
+    }
+    if (options.section) {
+      this.og("article:section", options.section);
+    }
+    if (options.tags) {
+      options.tags.forEach((tag) => this.og("article:tag", tag));
+    }
+    return this;
+  }
+  /**
+   * Set Twitter Card type
+   */
+  twitterCard(type = "summary_large_image") {
+    this.twitter("card", type);
+    if (this.defaults.twitterHandle) {
+      this.twitter("site", this.defaults.twitterHandle);
+    }
+    return this;
+  }
+  /**
+   * Set locale
+   */
+  locale(locale, alternates = []) {
+    this.og("locale", locale);
+    alternates.forEach((alt) => {
+      this.og("locale:alternate", alt);
+    });
+    return this;
+  }
+  /**
+   * Set site name
+   */
+  siteName(name) {
+    this.og("site_name", name || this.defaults.siteName);
+    return this;
+  }
+  /**
+   * Add custom meta tag
+   */
+  meta(attributes) {
+    this.tags.push({ meta: attributes });
+    return this;
+  }
+  /**
+   * Add link tag
+   */
+  link(attributes) {
+    this.tags.push({ link: attributes });
+    return this;
+  }
+  /**
+   * Build all meta tags
+   */
+  build() {
+    return this.tags;
+  }
+  /**
+   * Reset builder
+   */
+  reset() {
+    this.tags = [];
+    return this;
+  }
+};
+function createMetaBuilder(defaults = {}) {
+  return new MetaBuilder(defaults);
+}
+function generateMeta(options = {}) {
+  const builder = new MetaBuilder(options.defaults);
+  if (options.title) {
+    builder.title(options.title, { template: options.titleTemplate });
+  }
+  if (options.description) {
+    builder.description(options.description);
+  }
+  if (options.canonical) {
+    builder.canonical(options.canonical);
+  }
+  if (options.keywords) {
+    builder.keywords(options.keywords);
+  }
+  if (options.image) {
+    builder.image(options.image.url, options.image);
+  }
+  if (options.robots) {
+    builder.robots(options.robots);
+  }
+  if (options.article) {
+    builder.article(options.article);
+  }
+  if (options.twitterCard !== false) {
+    builder.twitterCard(options.twitterCard);
+  }
+  if (options.locale) {
+    builder.locale(options.locale, options.alternateLocales);
+  }
+  if (options.siteName) {
+    builder.siteName(options.siteName);
+  }
+  return builder.build();
+}
+
+// src/sitemap.js
+var SitemapGenerator = class {
+  constructor(options = {}) {
+    this.options = {
+      hostname: "",
+      xmlns: "http://www.sitemaps.org/schemas/sitemap/0.9",
+      ...options
+    };
+    this.urls = [];
+  }
+  /**
+   * Add URL to sitemap
+   */
+  add(url, options = {}) {
+    this.urls.push({
+      loc: this.normalizeUrl(url),
+      lastmod: options.lastmod || (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+      changefreq: options.changefreq || "weekly",
+      priority: options.priority !== void 0 ? options.priority : 0.5,
+      ...options
+    });
+    return this;
+  }
+  /**
+   * Add multiple URLs
+   */
+  addMultiple(urls) {
+    urls.forEach((url) => {
+      if (typeof url === "string") {
+        this.add(url);
+      } else {
+        this.add(url.url, url);
+      }
+    });
+    return this;
+  }
+  /**
+   * Normalize URL
+   */
+  normalizeUrl(url) {
+    if (url.startsWith("http")) {
+      return url;
+    }
+    const hostname = this.options.hostname.replace(/\/$/, "");
+    const path = url.startsWith("/") ? url : `/${url}`;
+    return `${hostname}${path}`;
+  }
+  /**
+   * Generate XML sitemap
+   */
+  generate() {
+    const urlEntries = this.urls.map((url) => {
+      const entries = [`    <loc>${this.escapeXml(url.loc)}</loc>`];
+      if (url.lastmod) {
+        entries.push(`    <lastmod>${url.lastmod}</lastmod>`);
+      }
+      if (url.changefreq) {
+        entries.push(`    <changefreq>${url.changefreq}</changefreq>`);
+      }
+      if (url.priority !== void 0) {
+        entries.push(`    <priority>${url.priority}</priority>`);
+      }
+      return `  <url>
+${entries.join("\n")}
+  </url>`;
+    }).join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="${this.options.xmlns}">
+${urlEntries}
+</urlset>`;
+  }
+  /**
+   * Escape XML special characters
+   */
+  escapeXml(str) {
+    return String(str).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+  }
+  /**
+   * Clear all URLs
+   */
+  clear() {
+    this.urls = [];
+    return this;
+  }
+  /**
+   * Get URL count
+   */
+  count() {
+    return this.urls.length;
+  }
+};
+function createSitemapGenerator(options = {}) {
+  return new SitemapGenerator(options);
+}
+function generateSitemap(urls, options = {}) {
+  const generator = new SitemapGenerator(options);
+  generator.addMultiple(urls);
+  return generator.generate();
+}
+
+// src/structured-data.js
+var StructuredDataBuilder = class {
+  constructor() {
+    this.schemas = [];
+  }
+  /**
+   * Add schema
+   */
+  add(schema) {
+    this.schemas.push(schema);
+    return this;
+  }
+  /**
+   * Create Organization schema
+   */
+  organization(data) {
+    return this.add({
+      "@context": "https://schema.org",
+      "@type": "Organization",
+      name: data.name,
+      url: data.url,
+      logo: data.logo,
+      description: data.description,
+      contactPoint: data.contactPoint,
+      sameAs: data.socialLinks
+    });
+  }
+  /**
+   * Create WebSite schema
+   */
+  website(data) {
+    return this.add({
+      "@context": "https://schema.org",
+      "@type": "WebSite",
+      name: data.name,
+      url: data.url,
+      description: data.description,
+      potentialAction: data.searchAction ? {
+        "@type": "SearchAction",
+        target: data.searchAction.target,
+        "query-input": data.searchAction.queryInput || "required name=search_term_string"
+      } : void 0
+    });
+  }
+  /**
+   * Create Article schema
+   */
+  article(data) {
+    return this.add({
+      "@context": "https://schema.org",
+      "@type": "Article",
+      headline: data.headline,
+      description: data.description,
+      image: data.image,
+      author: data.author ? {
+        "@type": "Person",
+        name: data.author.name,
+        url: data.author.url
+      } : void 0,
+      publisher: data.publisher ? {
+        "@type": "Organization",
+        name: data.publisher.name,
+        logo: data.publisher.logo ? {
+          "@type": "ImageObject",
+          url: data.publisher.logo
+        } : void 0
+      } : void 0,
+      datePublished: data.datePublished,
+      dateModified: data.dateModified
+    });
+  }
+  /**
+   * Create Product schema
+   */
+  product(data) {
+    return this.add({
+      "@context": "https://schema.org",
+      "@type": "Product",
+      name: data.name,
+      description: data.description,
+      image: data.image,
+      brand: data.brand ? {
+        "@type": "Brand",
+        name: data.brand
+      } : void 0,
+      offers: data.offers ? {
+        "@type": "Offer",
+        price: data.offers.price,
+        priceCurrency: data.offers.currency || "USD",
+        availability: data.offers.availability || "https://schema.org/InStock",
+        url: data.offers.url
+      } : void 0,
+      aggregateRating: data.rating ? {
+        "@type": "AggregateRating",
+        ratingValue: data.rating.value,
+        reviewCount: data.rating.count
+      } : void 0
+    });
+  }
+  /**
+   * Create BreadcrumbList schema
+   */
+  breadcrumb(items) {
+    return this.add({
+      "@context": "https://schema.org",
+      "@type": "BreadcrumbList",
+      itemListElement: items.map((item, index) => ({
+        "@type": "ListItem",
+        position: index + 1,
+        name: item.name,
+        item: item.url
+      }))
+    });
+  }
+  /**
+   * Create FAQ schema
+   */
+  faq(questions) {
+    return this.add({
+      "@context": "https://schema.org",
+      "@type": "FAQPage",
+      mainEntity: questions.map((q) => ({
+        "@type": "Question",
+        name: q.question,
+        acceptedAnswer: {
+          "@type": "Answer",
+          text: q.answer
+        }
+      }))
+    });
+  }
+  /**
+   * Create Person schema
+   */
+  person(data) {
+    return this.add({
+      "@context": "https://schema.org",
+      "@type": "Person",
+      name: data.name,
+      url: data.url,
+      image: data.image,
+      jobTitle: data.jobTitle,
+      worksFor: data.organization ? {
+        "@type": "Organization",
+        name: data.organization
+      } : void 0,
+      sameAs: data.socialLinks
+    });
+  }
+  /**
+   * Build JSON-LD script tag
+   */
+  build() {
+    if (this.schemas.length === 0) {
+      return null;
+    }
+    const data = this.schemas.length === 1 ? this.schemas[0] : this.schemas;
+    return {
+      script: {
+        type: "application/ld+json",
+        text: JSON.stringify(data, null, 2)
+      }
+    };
+  }
+  /**
+   * Build as JSON string
+   */
+  toJSON() {
+    const data = this.schemas.length === 1 ? this.schemas[0] : this.schemas;
+    return JSON.stringify(data, null, 2);
+  }
+  /**
+   * Clear all schemas
+   */
+  clear() {
+    this.schemas = [];
+    return this;
+  }
+};
+function createStructuredData() {
+  return new StructuredDataBuilder();
+}
+function generateStructuredData(type, data) {
+  const builder = new StructuredDataBuilder();
+  switch (type) {
+    case "organization":
+      builder.organization(data);
+      break;
+    case "website":
+      builder.website(data);
+      break;
+    case "article":
+      builder.article(data);
+      break;
+    case "product":
+      builder.product(data);
+      break;
+    case "breadcrumb":
+      builder.breadcrumb(data);
+      break;
+    case "faq":
+      builder.faq(data);
+      break;
+    case "person":
+      builder.person(data);
+      break;
+    default:
+      builder.add(data);
+  }
+  return builder.build();
+}
+export {
+  MetaBuilder,
+  SitemapGenerator,
+  StructuredDataBuilder,
+  createMetaBuilder,
+  createSitemapGenerator,
+  createStructuredData,
+  generateMeta,
+  generateSitemap,
+  generateStructuredData
+};
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@coherent.js/seo",
+  "version": "1.0.0-beta.2",
+  "description": "SEO utilities for Coherent.js applications",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./meta": "./dist/meta.js",
+    "./sitemap": "./dist/sitemap.js",
+    "./structured-data": "./dist/structured-data.js"
+  },
+  "keywords": [
+    "coherent",
+    "seo",
+    "meta-tags",
+    "sitemap",
+    "structured-data"
+  ],
+  "author": "Coherent.js Team",
+  "license": "MIT",
+  "peerDependencies": {
+    "@coherent.js/core": "1.0.0-beta.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tomdrouv1/coherent.js.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./types/index.d.ts",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "types/"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "clean": "rm -rf dist"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Coherent.js SEO TypeScript Definitions
+ * @module @coherent.js/seo
+ */
+
+// ===== Meta Builder Types =====
+
+export interface MetaTags {
+  title?: string;
+  description?: string;
+  keywords?: string | string[];
+  author?: string;
+  robots?: string;
+  canonical?: string;
+  viewport?: string;
+  charset?: string;
+  language?: string;
+  themeColor?: string;
+  // Open Graph
+  ogTitle?: string;
+  ogDescription?: string;
+  ogImage?: string;
+  ogUrl?: string;
+  ogType?: string;
+  ogSiteName?: string;
+  ogLocale?: string;
+  // Twitter Card
+  twitterCard?: 'summary' | 'summary_large_image' | 'app' | 'player';
+  twitterSite?: string;
+  twitterCreator?: string;
+  twitterTitle?: string;
+  twitterDescription?: string;
+  twitterImage?: string;
+  // Custom meta tags
+  [key: string]: any;
+}
+
+export class MetaBuilder {
+  constructor(tags?: MetaTags);
+  setTitle(title: string): this;
+  setDescription(description: string): this;
+  setKeywords(keywords: string | string[]): this;
+  setAuthor(author: string): this;
+  setRobots(robots: string): this;
+  setCanonical(url: string): this;
+  setViewport(viewport: string): this;
+  setOpenGraph(tags: Partial<MetaTags>): this;
+  setTwitterCard(tags: Partial<MetaTags>): this;
+  addCustomTag(name: string, content: string, type?: 'name' | 'property'): this;
+  build(): object;
+  render(): object;
+  toHTML(): string;
+}
+
+export function createMetaBuilder(tags?: MetaTags): MetaBuilder;
+export function generateMeta(tags: MetaTags): object;
+
+// ===== Sitemap Generator Types =====
+
+export interface SitemapEntry {
+  url: string;
+  lastmod?: string | Date;
+  changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+  priority?: number;
+  images?: Array<{
+    loc: string;
+    title?: string;
+    caption?: string;
+  }>;
+  videos?: Array<{
+    thumbnail_loc: string;
+    title: string;
+    description: string;
+    content_loc?: string;
+    player_loc?: string;
+  }>;
+}
+
+export interface SitemapOptions {
+  hostname: string;
+  cacheTime?: number;
+  xmlNs?: Record<string, string>;
+  xslUrl?: string;
+}
+
+export class SitemapGenerator {
+  constructor(options: SitemapOptions);
+  addUrl(entry: SitemapEntry): this;
+  addUrls(entries: SitemapEntry[]): this;
+  removeUrl(url: string): this;
+  generate(): string;
+  toXML(): string;
+  toJSON(): SitemapEntry[];
+}
+
+export function createSitemapGenerator(options: SitemapOptions): SitemapGenerator;
+export function generateSitemap(entries: SitemapEntry[], options: SitemapOptions): string;
+
+// ===== Structured Data Types =====
+
+export type StructuredDataType =
+  | 'Article'
+  | 'BlogPosting'
+  | 'NewsArticle'
+  | 'WebPage'
+  | 'WebSite'
+  | 'Organization'
+  | 'Person'
+  | 'Product'
+  | 'Review'
+  | 'Event'
+  | 'Recipe'
+  | 'BreadcrumbList'
+  | 'LocalBusiness'
+  | 'FAQPage'
+  | 'HowTo'
+  | 'VideoObject'
+  | 'ImageObject';
+
+export interface StructuredData {
+  '@context': string;
+  '@type': StructuredDataType | StructuredDataType[];
+  [key: string]: any;
+}
+
+export class StructuredDataBuilder {
+  constructor(type: StructuredDataType);
+  setType(type: StructuredDataType): this;
+  setProperty(key: string, value: any): this;
+  setProperties(properties: Record<string, any>): this;
+  addToArray(key: string, value: any): this;
+  build(): StructuredData;
+  toJSON(): string;
+  toJSONLD(): object;
+}
+
+export function createStructuredData(type: StructuredDataType, properties?: Record<string, any>): StructuredDataBuilder;
+export function generateStructuredData(type: StructuredDataType, properties: Record<string, any>): StructuredData;
+
+// Helper types for common structured data
+
+export interface ArticleData {
+  headline: string;
+  image: string | string[];
+  datePublished: string;
+  dateModified?: string;
+  author: {
+    '@type': 'Person' | 'Organization';
+    name: string;
+  };
+  publisher: {
+    '@type': 'Organization';
+    name: string;
+    logo: {
+      '@type': 'ImageObject';
+      url: string;
+    };
+  };
+  description?: string;
+  mainEntityOfPage?: string;
+}
+
+export interface ProductData {
+  name: string;
+  image: string | string[];
+  description: string;
+  brand?: {
+    '@type': 'Brand';
+    name: string;
+  };
+  offers?: {
+    '@type': 'Offer';
+    price: number;
+    priceCurrency: string;
+    availability?: string;
+    url?: string;
+  };
+  aggregateRating?: {
+    '@type': 'AggregateRating';
+    ratingValue: number;
+    reviewCount: number;
+  };
+}
+
+export interface BreadcrumbData {
+  itemListElement: Array<{
+    '@type': 'ListItem';
+    position: number;
+    name: string;
+    item?: string;
+  }>;
+}