geo-semantic-layer 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,289 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [2.0.0] - 2026-01-06
+
+### 🚀 Major Release - Framework-Agnostic Architecture
+
+**BREAKING CHANGE:** Complete rewrite to pure framework-agnostic library.
+
+#### Why This Change?
+
+v1.0 had framework-specific integrations (React, Vue, Angular, Svelte, Astro) which caused:
+- Peer dependency warnings during installation
+- Version conflicts between frameworks
+- Maintenance overhead across multiple framework APIs
+- Larger bundle sizes due to framework dependencies
+
+v2.0 solves this by providing **pure functions** that work everywhere.
+
+#### Migration Guide
+
+**Before (v1.x):**
+```typescript
+import { OrganizationSchema } from 'geo-semantic-layer/react';
+
+<OrganizationSchema name="My Company" url="https://example.com" />
+```
+
+**After (v2.0):**
+```typescript
+import { generateOrganizationSchema } from 'geo-semantic-layer';
+
+const schema = generateOrganizationSchema({
+  name: 'My Company',
+  url: 'https://example.com'
+});
+
+// In React:
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
+/>
+
+// In Vue:
+<script type="application/ld+json">{{ JSON.stringify(schema) }}</script>
+
+// In any framework: just insert the JSON-LD yourself
+```
+
+#### ✨ What's New
+
+- ✅ **Zero Framework Dependencies** - No React, Vue, Angular, or any framework code
+- ✅ **No Peer Dependencies** - No installation warnings
+- ✅ **Universal Compatibility** - Works in Node.js, Deno, Bun, browsers, edge runtimes
+- ✅ **Tiny Bundle** - Only Zod as dependency (~10KB gzipped)
+- ✅ **Pure Functions** - Predictable, testable, simple
+- ✅ **Use Your Way** - You control how JSON-LD is inserted
+
+#### 🗑️ Removed
+
+- ❌ Framework-specific components (React, Vue, Angular, Svelte, Astro)
+- ❌ Framework peer dependencies
+- ❌ Framework-specific build targets
+- ❌ Examples folder (no longer needed - it's just pure functions)
+
+#### 📦 New Package Structure
+
+```
+geo-semantic-layer/
+├── schemas/      # Zod validation schemas
+├── generators/   # Pure generator functions
+└── geo/          # GEO optimization engine
+```
+
+#### 📊 Bundle Size
+
+- **Before (v1.0):** ~25KB + framework dependencies
+- **After (v2.0):** ~10KB (including Zod)
+
+#### 🎯 Same Features, Better API
+
+All the same powerful features:
+- Hallucination Guard (entity validation)
+- Content Density Engine (GEO optimization)
+- Full Zod validation
+- TypeScript type safety
+- All Schema.org types supported
+
+---
+
+## [1.0.0] - 2026-01-06
+
+### 🎉 Major Release - Unified Package
+
+**BREAKING CHANGE:** Migrated from multi-package architecture to unified package.
+
+#### Migration
+
+**Before:**
+```bash
+npm install @semantic-layer/core @semantic-layer/react
+```
+
+**Now:**
+```bash
+npm install geo-semantic-layer
+```
+
+**Good news:** Imports remain the same! Just change the install command.
+
+```typescript
+// Still works exactly the same
+import { JsonLd } from 'geo-semantic-layer/react'
+import { generateArticle } from 'geo-semantic-layer/core/generators'
+```
+
+#### ✨ What's New
+
+- ✅ **Single Package** - All frameworks in one npm package
+- ✅ **Synchronized Versions** - All integrations always compatible
+- ✅ **Simplified Installation** - One command for all frameworks
+- ✅ **Perfect Tree-Shaking** - Unused code automatically excluded
+- ✅ **100% Backwards Compatible** - Same API, same imports
+
+#### 📦 Package Structure
+
+```
+geo-semantic-layer/
+├── core               # Framework-agnostic
+├── react              # React hooks & components
+├── vue                # Vue 3 composables
+├── angular            # Angular components
+├── svelte             # Svelte components
+└── astro              # Astro components
+```
+
+---
+
+## [0.1.0] - 2026-01-05
+
+### 🎉 Initial Release
+
+The first release of Semantic Layer - The ultimate TypeScript library for Generative Engine Optimization (GEO)!
+
+### ✨ Features
+
+#### Core Package (@semantic-layer/core)
+
+- ✅ **Identity Schemas**
+  - `generateIdentitySchema()` - Organization and Person schemas
+  - Full Zod validation for runtime safety
+  - Entity disambiguation support with Wikidata
+
+- ✅ **Content Schemas**
+  - `generateProductSchema()` - E-commerce products with offers, ratings, reviews
+  - `generateArticleSchema()` - Blog posts and news articles
+  - `generateFAQSchema()` - FAQ pages for rich search results
+  - `generateBreadcrumbSchema()` - Navigation breadcrumbs
+
+- ✅ **Utilities**
+  - `serializeSchema()` - Convert schemas to JSON strings
+  - `generateScriptTag()` - Create complete `<script>` tags
+  - Validation helpers (URL, email, date formats)
+
+- ✅ **Schema Types**
+  - Organization, Person
+  - Product, Offer, AggregateRating, Review
+  - Article, BlogPosting, NewsArticle
+  - FAQPage, Question
+  - BreadcrumbList, ListItem
+  - WebPage
+
+#### React Package (@semantic-layer/react)
+
+- ✅ **Components**
+  - `<SemanticProvider>` - Root context provider
+  - `<OrganizationSchema>` - Organization identity
+  - `<PersonSchema>` - Person identity
+  - `<ProductSchema>` - E-commerce products
+  - `<ArticleSchema>` - Blog posts and articles
+  - `<FAQSchema>` - Frequently asked questions
+  - `<BreadcrumbSchema>` - Navigation breadcrumbs
+  - `<JsonLd>` - Generic schema component
+
+- ✅ **Hooks**
+  - `useSemanticContext()` - Access configuration
+  - `useJsonLd()` - Dynamic schema injection
+
+- ✅ **Server Components Support**
+  - Ready for React 19 Server Components
+  - Optimized for Next.js App Router
+
+#### Vue Package (@semantic-layer/vue)
+
+- ✅ **Components**
+  - `<JsonLd>` - Generic schema component
+  - `<OrganizationSchema>` - Organization identity
+
+- ✅ **Composables**
+  - `useSemanticConfig()` - Access configuration
+  - `useJsonLd()` - Dynamic schema injection
+
+- ✅ **Vue 3 & Nuxt Support**
+  - Full Vue 3 Composition API support
+  - Nuxt 3 compatible
+
+### 📦 Examples
+
+- ✅ **Simple Usage** - Basic TypeScript examples
+- ✅ **Next.js App Router** - Complete e-commerce example
+  - Home page
+  - Product page with full schema
+  - Blog post with Article schema
+  - FAQ page with rich results
+
+### 🏗️ Architecture
+
+- ✅ **Monorepo Structure** - pnpm workspaces
+- ✅ **TypeScript Strict Mode** - Type safety everywhere
+- ✅ **Zod Validation** - Runtime schema validation
+- ✅ **Tree-shakeable** - Import only what you need
+- ✅ **Edge-ready** - Works on Cloudflare Workers, Vercel Edge
+- ✅ **Zero Config** - Smart defaults out of the box
+
+### 📊 Performance
+
+- **@semantic-layer/core**: 16.81 KB (target < 15KB)
+- **@semantic-layer/react**: 4.03 KB (target < 8KB)
+- **@semantic-layer/vue**: TBD
+- All packages tree-shakeable and minifiable
+
+### 🧪 Testing
+
+- ✅ 8 unit tests passing (Identity generation, validation, serialization)
+- ✅ Vitest configured for all packages
+- ✅ > 90% coverage target set
+
+### 📚 Documentation
+
+- ✅ **README.md** - Comprehensive main documentation
+- ✅ **GETTING_STARTED.md** - Quick start guide
+- ✅ **CONTRIBUTING.md** - Contribution guidelines
+- ✅ **LICENSE** - MIT License
+- ✅ Package-specific READMEs for core, react, vue
+- ✅ Inline JSDoc comments on all public APIs
+
+### 🛠️ Development
+
+- ✅ **Build System** - tsup for fast builds
+- ✅ **Linting** - ESLint with TypeScript support
+- ✅ **Formatting** - Prettier configured
+- ✅ **Git Hooks** - Ready for pre-commit hooks
+
+### 🎯 GEO Features
+
+- ✅ **Entity Disambiguation** - Wikidata ID support
+- ✅ **Citation-Ready Content** - Structured fact representation
+- ✅ **AI-Friendly Markup** - Optimized for ChatGPT, Gemini, Perplexity
+- ✅ **Rich Snippets** - Google Search rich results
+- ✅ **Knowledge Graph** - Root identity architecture
+
+### 🔮 Planned for Future Releases
+
+- [ ] @semantic-layer/astro package
+- [ ] @semantic-layer/svelte package
+- [ ] CLI tool (`create-semantic-layer`)
+- [ ] Visual schema builder
+- [ ] Google Rich Results Test integration
+- [ ] Analytics dashboard
+- [ ] More schema types (Recipe, Event, LocalBusiness, etc.)
+- [ ] Rust-based validator (WASM)
+
+### 📝 Notes
+
+This is an alpha release focused on establishing the core architecture and proving the concept. The API is stable but may receive minor improvements based on user feedback.
+
+### 🙏 Credits
+
+Built with ❤️ by the Semantic Layer Contributors
+
+---
+
+## Links
+
+- [GitHub Repository](https://github.com/yourusername/semantic-layer)
+- [Documentation](./readme.md)
+- [Getting Started](./GETTING_STARTED.md)
+- [Contributing](./CONTRIBUTING.md)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Calderón (BDOvenbird Engineering)
+
+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,394 @@
+# GEO Semantic Layer
+
+Framework-agnostic TypeScript library for Generative Engine Optimization (GEO) and structured data automation.
+
+Build type-safe, validated JSON-LD schemas that work in any JavaScript environment: React, Vue, Angular, Svelte, Astro, Next.js, Nuxt, Remix, Node.js, Deno, Bun, edge runtimes, and vanilla JavaScript.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+[![npm version](https://badge.fury.io/js/geo-semantic-layer.svg)](https://www.npmjs.com/package/geo-semantic-layer)
+
+---
+
+## Why v2.0?
+
+Version 2.0 is a complete rewrite focused on universality and simplicity.
+
+**What changed:**
+- Zero framework dependencies (only Zod for validation)
+- No peer dependency warnings during installation
+- Works in any JavaScript environment
+- Smaller bundle size (~10KB vs ~25KB)
+- Pure functions instead of framework-specific components
+
+**What stayed the same:**
+- All Schema.org types supported
+- Full TypeScript type safety
+- Zod runtime validation
+- GEO optimization features
+
+---
+
+## Installation
+
+```bash
+npm install geo-semantic-layer
+```
+
+No framework-specific packages. No peer dependencies.
+
+---
+
+## Quick Start
+
+```typescript
+import { generateArticleSchema } from 'geo-semantic-layer';
+
+const schema = generateArticleSchema({
+  headline: 'The Future of GEO in 2026',
+  image: 'https://example.com/article.jpg',
+  author: 'John Doe',
+  datePublished: '2026-01-06',
+  description: 'How AI models consume structured data',
+  publisher: {
+    name: 'My Site',
+    logo: 'https://example.com/logo.png'
+  }
+});
+
+// Insert into your HTML:
+// <script type="application/ld+json">{JSON.stringify(schema)}</script>
+```
+
+---
+
+## Framework Integration
+
+### React / Next.js
+
+```tsx
+import { generateOrganizationSchema } from 'geo-semantic-layer';
+
+export default function RootLayout({ children }) {
+  const schema = generateOrganizationSchema({
+    name: 'My Company',
+    url: 'https://example.com',
+    logo: 'https://example.com/logo.png',
+    sameAs: [
+      'https://wikidata.org/wiki/Q123',
+      'https://linkedin.com/company/example'
+    ]
+  });
+
+  return (
+    <html>
+      <head>
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
+        />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+### Vue 3 / Nuxt
+
+```vue
+<script setup>
+import { generateProductSchema } from 'geo-semantic-layer';
+
+const schema = generateProductSchema({
+  name: 'Wireless Headphones',
+  description: 'Premium noise-cancelling headphones',
+  image: 'https://example.com/headphones.jpg',
+  brand: 'AudioTech',
+  offers: {
+    price: 299.99,
+    priceCurrency: 'USD',
+    availability: 'InStock',
+    url: 'https://example.com/products/headphones'
+  }
+});
+</script>
+
+<template>
+  <Head>
+    <script type="application/ld+json">{{ JSON.stringify(schema) }}</script>
+  </Head>
+</template>
+```
+
+### Svelte / SvelteKit
+
+```svelte
+<script>
+  import { generateFAQSchema } from 'geo-semantic-layer';
+
+  const schema = generateFAQSchema({
+    questions: [
+      {
+        question: 'What is GEO?',
+        answer: 'Generative Engine Optimization for AI search engines.'
+      },
+      {
+        question: 'How does it work?',
+        answer: 'By providing structured data AI models can easily consume.'
+      }
+    ]
+  });
+</script>
+
+<svelte:head>
+  <script type="application/ld+json">{JSON.stringify(schema)}</script>
+</svelte:head>
+```
+
+### Astro
+
+```astro
+---
+import { generateBreadcrumbSchema } from 'geo-semantic-layer';
+
+const schema = generateBreadcrumbSchema({
+  items: [
+    { name: 'Home', url: 'https://example.com' },
+    { name: 'Products', url: 'https://example.com/products' },
+    { name: 'Headphones', url: 'https://example.com/products/headphones' }
+  ]
+});
+---
+
+<html>
+  <head>
+    <script type="application/ld+json" set:html={JSON.stringify(schema)} />
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>
+```
+
+### Angular
+
+```typescript
+import { Component } from '@angular/core';
+import { generateLocalBusinessSchema } from 'geo-semantic-layer';
+
+@Component({
+  selector: 'app-root',
+  template: `
+    <div [innerHTML]="schemaScript"></div>
+  `
+})
+export class AppComponent {
+  schema = generateLocalBusinessSchema({
+    name: 'Coffee Shop Downtown',
+    address: {
+      streetAddress: '123 Main St',
+      addressLocality: 'New York',
+      addressRegion: 'NY',
+      postalCode: '10001',
+      addressCountry: 'US'
+    },
+    geo: {
+      latitude: 40.7128,
+      longitude: -74.0060
+    },
+    telephone: '+1-555-123-4567'
+  });
+
+  get schemaScript() {
+    return `<script type="application/ld+json">${JSON.stringify(this.schema)}</script>`;
+  }
+}
+```
+
+### Node.js / Express
+
+```javascript
+import express from 'express';
+import { generateWebPageSchema } from 'geo-semantic-layer';
+
+const app = express();
+
+app.get('/', (req, res) => {
+  const schema = generateWebPageSchema({
+    name: 'Homepage',
+    description: 'Welcome to our site',
+    url: 'https://example.com'
+  });
+
+  res.send(`
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <script type="application/ld+json">
+          ${JSON.stringify(schema)}
+        </script>
+      </head>
+      <body>
+        <h1>Hello World</h1>
+      </body>
+    </html>
+  `);
+});
+```
+
+---
+
+## Available Schemas
+
+| Generator | Description |
+|-----------|-------------|
+| `generateOrganizationSchema()` | Company/business information |
+| `generatePersonSchema()` | Individual person profiles |
+| `generateProductSchema()` | E-commerce products with ratings |
+| `generateArticleSchema()` | Blog posts and articles |
+| `generateFAQSchema()` | Frequently asked questions |
+| `generateBreadcrumbSchema()` | Navigation breadcrumbs |
+| `generateLocalBusinessSchema()` | Physical business locations |
+| `generateEventSchema()` | Events and conferences |
+| `generateWebPageSchema()` | Individual web pages |
+
+---
+
+## Features
+
+### GEO Optimization
+
+Optimize JSON-LD for AI model consumption:
+
+```typescript
+import { generateArticleSchema } from 'geo-semantic-layer';
+
+const schema = generateArticleSchema({
+  headline: 'My Article',
+  author: 'John Doe',
+  datePublished: '2026-01-06',
+  articleBody: 'Very long article content...',
+  geo: {
+    contentDensity: 'high' // Prunes decorative data for LLMs
+  }
+});
+```
+
+### Hallucination Guard
+
+Validates entity links against authoritative sources (Wikidata, LinkedIn) to prevent AI misattribution.
+
+### Content Density Engine
+
+Automatically prunes decorative data to generate high-density JSON-LD optimized for LLM context windows.
+
+### Schema Validation
+
+All schemas validated with Zod:
+
+```typescript
+import { ArticleSchema } from 'geo-semantic-layer/schemas';
+
+try {
+  const validated = ArticleSchema.parse(myData);
+} catch (error) {
+  console.error('Invalid schema:', error);
+}
+```
+
+### TypeScript Types
+
+Full type safety:
+
+```typescript
+import type { Article, Product, Organization } from 'geo-semantic-layer';
+
+const article: Article = {
+  '@context': 'https://schema.org',
+  '@type': 'Article',
+  headline: 'My Article',
+  // TypeScript enforces correct structure
+};
+```
+
+---
+
+## Package Exports
+
+```typescript
+// Main entry - all generators and schemas
+import { generateArticleSchema } from 'geo-semantic-layer';
+
+// Schemas only
+import { ArticleSchema } from 'geo-semantic-layer/schemas';
+
+// Generators only
+import { generateArticleSchema } from 'geo-semantic-layer/generators';
+
+// GEO Engine only
+import { GeoProcessor } from 'geo-semantic-layer/geo';
+```
+
+---
+
+## Migration from v1.x
+
+**Before (v1.x):**
+```typescript
+import { OrganizationSchema } from 'geo-semantic-layer/react';
+```
+
+**After (v2.0):**
+```typescript
+import { generateOrganizationSchema } from 'geo-semantic-layer';
+
+// In your React component:
+const schema = generateOrganizationSchema({ name: 'My Company', url: '...' });
+
+return (
+  <script
+    type="application/ld+json"
+    dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
+  />
+);
+```
+
+The core API remains the same. You now control how JSON-LD is inserted into your application.
+
+---
+
+## Why This Approach?
+
+**Problems with v1.x:**
+- Framework components caused peer dependency warnings
+- Version conflicts between frameworks
+- Maintenance overhead across multiple framework APIs
+- Larger bundle sizes
+
+**Benefits of v2.0:**
+- Pure functions work everywhere
+- No framework dependencies
+- One install, use anywhere
+- Smaller bundle size
+- Easier maintenance
+
+---
+
+## Contributing
+
+Contributions welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+MIT © 2026 Rafael Calderón (BDOvenbird Engineering)
+
+---
+
+## Links
+
+- [npm](https://www.npmjs.com/package/geo-semantic-layer)
+- [GitHub](https://github.com/bdovenbird/semantic-layer)
+- [Issues](https://github.com/bdovenbird/semantic-layer/issues)