sovrium 0.0.2

package/src/domain/models/app/page/meta/structured-data/common-fields.ts

@@ -0,0 +1,201 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Schema } from 'effect'
+
+/**
+ * Common Schema.org field definitions
+ *
+ * This module provides reusable field definitions that are shared across multiple
+ * structured data schemas. Using these common fields ensures consistency in:
+ * - Validation rules (e.g., email format, URI format)
+ * - Annotations (descriptions, formats)
+ * - Type definitions
+ *
+ * Benefits:
+ * - **DRY principle**: Single source of truth for common field patterns
+ * - **Consistency**: Same validation rules across all schemas
+ * - **Maintainability**: Update field definition in one place
+ * - **Type safety**: Reusable schema types
+ *
+ * Usage:
+ * ```typescript
+ * import { SchemaOrgContext, SchemaOrgEmail, SchemaOrgTelephone } from './common-fields'
+ *
+ * export const PersonSchema = Schema.Struct({
+ *   '@context': SchemaOrgContext,
+ *   email: Schema.optional(SchemaOrgEmail),
+ *   telephone: Schema.optional(SchemaOrgTelephone),
+ *   // ... other fields
+ * })
+ * ```
+ */
+
+/**
+ * Schema.org @context field
+ *
+ * Required in all Schema.org structured data to indicate the vocabulary being used.
+ * Always set to "https://schema.org" for Schema.org compliance.
+ *
+ * Used in: Person, Organization, LocalBusiness, Product, Article, Breadcrumb, FAQPage, EducationEvent
+ */
+export const SchemaOrgContext = Schema.Literal('https://schema.org').annotations({
+  description: 'Schema.org context',
+})
+
+/**
+ * Email address field
+ *
+ * Validates email format according to RFC 5322.
+ * Used for contact information in Person, Organization, and LocalBusiness schemas.
+ *
+ * Used in: Person, Organization, LocalBusiness
+ */
+export const SchemaOrgEmail = Schema.String.annotations({
+  description: 'Email address',
+  format: 'email',
+})
+
+/**
+ * Telephone number field
+ *
+ * Stores telephone number as a string to support international formats.
+ * No format validation to allow flexibility (e.g., +1-555-123-4567, (555) 123-4567, etc.)
+ *
+ * Used in: Person, Organization, LocalBusiness
+ */
+export const SchemaOrgTelephone = Schema.String.annotations({
+  description: 'Phone number',
+})
+
+/**
+ * Array of social media profile URLs
+ *
+ * The "sameAs" property links an entity to its social media profiles for verification.
+ * Each URL should be a valid URI pointing to an official social media account.
+ *
+ * Common platforms: Twitter, LinkedIn, Facebook, GitHub, Instagram, YouTube
+ *
+ * SEO impact:
+ * - Verifies entity's online identity across platforms
+ * - Helps search engines understand the entity's social presence
+ * - May appear in Knowledge Graph panels
+ *
+ * Used in: Person, Organization, LocalBusiness
+ */
+export const SchemaOrgSameAs = Schema.Array(
+  Schema.String.annotations({
+    description: 'Social media profile URL',
+    format: 'uri',
+  })
+).annotations({
+  description: 'Social media profile URLs',
+  examples: [
+    [
+      'https://twitter.com/example',
+      'https://linkedin.com/in/example',
+      'https://facebook.com/example',
+    ],
+  ],
+})
+
+/**
+ * URL field for web resources
+ *
+ * Validates URI format and is used for various web resource references:
+ * - Personal/organization website
+ * - Product pages
+ * - Profile URLs
+ * - Image URLs
+ *
+ * Used in: Person, Organization, LocalBusiness, Product, Article
+ */
+export const SchemaOrgUrl = Schema.String.annotations({
+  description: 'URL',
+  format: 'uri',
+})
+
+/**
+ * Image URL field
+ *
+ * URL to an image resource (JPEG, PNG, WebP, etc.).
+ * Used for photos, logos, product images, etc.
+ *
+ * SEO impact:
+ * - Displayed in search result cards
+ * - Shown in Knowledge Graph panels
+ * - Used in rich results (products, articles, etc.)
+ *
+ * Used in: Person, Organization, LocalBusiness, Product, Article
+ */
+export const SchemaOrgImageUrl = Schema.String.annotations({
+  description: 'Image URL',
+  format: 'uri',
+})
+
+/**
+ * Helper: Create optional field
+ *
+ * Utility function to wrap a schema in Schema.optional() while preserving type inference.
+ * Reduces boilerplate when defining optional fields.
+ *
+ * @example
+ * ```typescript
+ * // Instead of:
+ * email: Schema.optional(SchemaOrgEmail),
+ *
+ * // You can use:
+ * email: optional(SchemaOrgEmail),
+ * ```
+ */
+export const optional = <A, I, R>(schema: Schema.Schema<A, I, R>) => Schema.optional(schema)
+
+/**
+ * Helper: Create Schema.org @type field
+ *
+ * Creates a Schema.Literal for Schema.org @type fields with standard annotation.
+ * Reduces duplication across all structured data schemas.
+ *
+ * @example
+ * ```typescript
+ * // Instead of:
+ * '@type': Schema.Literal('Person').annotations({ description: 'Schema.org type' }),
+ *
+ * // You can use:
+ * '@type': schemaType('Person'),
+ * ```
+ *
+ * Used in: Person, Organization, LocalBusiness, Product, Article, Breadcrumb, FAQPage, EducationEvent
+ */
+export const schemaType = <T extends string>(type: T) =>
+  Schema.Literal(type).annotations({
+    description: 'Schema.org type',
+  })
+
+/**
+ * Helper: Create positive integer field
+ *
+ * Creates a Schema.Int with a minimum value of 1, commonly used for:
+ * - Breadcrumb positions (1-indexed)
+ * - Review counts
+ * - Any count or index that must be positive
+ *
+ * @example
+ * ```typescript
+ * // Instead of:
+ * position: Schema.Int.pipe(Schema.greaterThanOrEqualTo(1)).annotations({ description: 'Position' }),
+ *
+ * // You can use:
+ * position: positiveInt('Position'),
+ * ```
+ *
+ * Used in: BreadcrumbListItem (position), AggregateRating (reviewCount)
+ */
+export const positiveInt = (description: string) =>
+  Schema.Int.pipe(Schema.greaterThanOrEqualTo(1)).annotations({
+    description,
+  })

package/src/domain/models/app/page/meta/structured-data/education-event.ts

@@ -0,0 +1,256 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Schema } from 'effect'
+import { positiveInt, schemaType } from './common-fields'
+import { PostalAddressSchema } from './postal-address'
+import { CurrencyCodeSchema } from './product'
+
+/**
+ * Event attendance mode
+ *
+ * 3 attendance modes for events:
+ * - OfflineEventAttendanceMode: In-person event at physical location
+ * - OnlineEventAttendanceMode: Virtual/online event (Zoom, livestream)
+ * - MixedEventAttendanceMode: Hybrid event (both in-person and online)
+ */
+export const EventAttendanceModeSchema = Schema.Literal(
+  'https://schema.org/OfflineEventAttendanceMode',
+  'https://schema.org/OnlineEventAttendanceMode',
+  'https://schema.org/MixedEventAttendanceMode'
+).annotations({
+  description: 'Event attendance mode',
+})
+
+/**
+ * Event status
+ *
+ * 4 event statuses:
+ * - EventScheduled: Event is scheduled and happening as planned
+ * - EventCancelled: Event has been cancelled
+ * - EventPostponed: Event postponed to later date (TBD)
+ * - EventRescheduled: Event rescheduled to specific new date
+ */
+export const EventStatusSchema = Schema.Literal(
+  'https://schema.org/EventScheduled',
+  'https://schema.org/EventCancelled',
+  'https://schema.org/EventPostponed',
+  'https://schema.org/EventRescheduled'
+).annotations({
+  description: 'Event status',
+})
+
+/**
+ * Event location (Place)
+ *
+ * Physical location for in-person or hybrid events.
+ * - @type: "Place"
+ * - name: Venue name (e.g., "Convention Center", "Library Hall")
+ * - address: Venue address (PostalAddress object)
+ */
+export const EventLocationSchema = Schema.Struct({
+  '@type': schemaType('Place'),
+  name: Schema.optional(
+    Schema.String.annotations({
+      description: 'Venue name',
+    })
+  ),
+  address: Schema.optional(PostalAddressSchema),
+}).annotations({
+  description: 'Event location',
+})
+
+/**
+ * Event organizer
+ *
+ * Organization or Person organizing the event.
+ * - @type: "Organization" or "Person"
+ * - name: Organizer name
+ * - url: Organizer website/profile URL
+ */
+export const EventOrganizerSchema = Schema.Struct({
+  '@type': Schema.Literal('Organization', 'Person').annotations({
+    description: 'Organizer type',
+  }),
+  name: Schema.optional(
+    Schema.String.annotations({
+      description: 'Organizer name',
+    })
+  ),
+  url: Schema.optional(
+    Schema.String.annotations({
+      description: 'Organizer URL',
+      format: 'uri',
+    })
+  ),
+}).annotations({
+  description: 'Event organizer',
+})
+
+/**
+ * Ticket availability status
+ *
+ * 4 availability statuses for event tickets:
+ * - InStock: Tickets available
+ * - OutOfStock: Sold out (temporarily)
+ * - PreOrder: Tickets available for pre-order
+ * - SoldOut: Permanently sold out
+ */
+export const TicketAvailabilitySchema = Schema.Literal(
+  'https://schema.org/InStock',
+  'https://schema.org/OutOfStock',
+  'https://schema.org/PreOrder',
+  'https://schema.org/SoldOut'
+).annotations({
+  description: 'Ticket availability status',
+})
+
+/**
+ * Event ticket offer
+ *
+ * Pricing and availability for event tickets.
+ * - @type: "Offer"
+ * - price: Ticket price (string or number, "0" for free events)
+ * - priceCurrency: ISO 4217 currency code (e.g., "USD", "EUR")
+ * - availability: Stock status (InStock, OutOfStock, PreOrder, SoldOut)
+ * - url: URL to ticket purchase page
+ */
+export const EventOfferSchema = Schema.Struct({
+  '@type': schemaType('Offer'),
+  price: Schema.optional(
+    Schema.Union(Schema.String, Schema.Number).annotations({
+      description: 'Ticket price',
+    })
+  ),
+  priceCurrency: Schema.optional(CurrencyCodeSchema),
+  availability: Schema.optional(TicketAvailabilitySchema),
+  url: Schema.optional(
+    Schema.String.annotations({
+      description: 'Ticket purchase URL',
+      format: 'uri',
+    })
+  ),
+}).annotations({
+  description: 'Event ticket offer',
+})
+
+/**
+ * Schema.org EducationEvent structured data
+ *
+ * Represents educational events (workshops, courses, training, seminars) for rich results
+ * in Google Search and Google Maps. Enables event cards with dates, location, pricing,
+ * and registration directly in search results.
+ *
+ * Required properties:
+ * - @type: "EducationEvent" (Schema.org type identifier)
+ * - name: Event name (e.g., "React Masterclass", "Photography Workshop")
+ * - startDate: Event start date/time (ISO 8601 format)
+ *
+ * Optional properties:
+ * - description: Event description
+ * - endDate: Event end date/time (ISO 8601 format)
+ * - eventAttendanceMode: In-person, online, or hybrid
+ * - eventStatus: Scheduled, cancelled, postponed, or rescheduled
+ * - location: Event venue (Place object with name and address)
+ * - organizer: Event organizer (Organization or Person)
+ * - offers: Ticket pricing (Offer object with price, currency, availability, URL)
+ * - maximumAttendeeCapacity: Maximum number of attendees
+ * - minimumAttendeeCapacity: Minimum number of attendees
+ *
+ * Common use cases:
+ * - **Workshops**: Hands-on training sessions (e.g., "3-hour React Workshop")
+ * - **Courses**: Educational courses (e.g., "8-week Python Bootcamp")
+ * - **Seminars**: Lecture-style events (e.g., "AI in Healthcare Seminar")
+ * - **Webinars**: Online educational events (eventAttendanceMode: OnlineEventAttendanceMode)
+ * - **Hybrid events**: Both in-person and online (eventAttendanceMode: MixedEventAttendanceMode)
+ *
+ * SEO impact:
+ * - **Event rich results**: Cards with date, time, location, price in search
+ * - **Google Maps**: Events appear in Google Maps for local discovery
+ * - **Event discovery**: Appears in Google's event discovery features
+ * - **Calendar integration**: "Add to calendar" button in search results
+ * - **Mobile optimization**: One-tap registration, directions, calendar add
+ *
+ * @example
+ * ```typescript
+ * const educationEvent = {
+ *   "@type": "EducationEvent",
+ *   name: "React Masterclass Workshop",
+ *   description: "Learn advanced React patterns with hands-on exercises",
+ *   startDate: "2025-02-15T14:00:00-05:00",
+ *   endDate: "2025-02-15T17:00:00-05:00",
+ *   eventAttendanceMode: "https://schema.org/MixedEventAttendanceMode",
+ *   eventStatus: "https://schema.org/EventScheduled",
+ *   location: {
+ *     "@type": "Place",
+ *     name: "Tech Hub Conference Center",
+ *     address: {
+ *       "@type": "PostalAddress",
+ *       streetAddress: "123 Innovation Dr",
+ *       addressLocality: "San Francisco",
+ *       addressRegion: "CA",
+ *       postalCode: "94105",
+ *       addressCountry: "US"
+ *     }
+ *   },
+ *   organizer: {
+ *     "@type": "Organization",
+ *     name: "React Academy",
+ *     url: "https://reactacademy.com"
+ *   },
+ *   offers: {
+ *     "@type": "Offer",
+ *     price: "149.00",
+ *     priceCurrency: "USD",
+ *     availability: "https://schema.org/InStock",
+ *     url: "https://reactacademy.com/workshops/react-masterclass"
+ *   },
+ *   maximumAttendeeCapacity: 30
+ * }
+ * ```
+ *
+ * @see specs/app/pages/meta/structured-data/education-event.schema.json
+ */
+export const EducationEventSchema = Schema.Struct({
+  '@type': schemaType('EducationEvent'),
+  name: Schema.String.annotations({
+    description: 'Event name',
+  }),
+  description: Schema.optional(
+    Schema.String.annotations({
+      description: 'Event description',
+    })
+  ),
+  startDate: Schema.String.annotations({
+    description: 'Event start date/time (ISO 8601)',
+    format: 'date-time',
+  }),
+  endDate: Schema.optional(
+    Schema.String.annotations({
+      description: 'Event end date/time (ISO 8601)',
+      format: 'date-time',
+    })
+  ),
+  eventAttendanceMode: Schema.optional(EventAttendanceModeSchema),
+  eventStatus: Schema.optional(EventStatusSchema),
+  location: Schema.optional(EventLocationSchema),
+  organizer: Schema.optional(EventOrganizerSchema),
+  offers: Schema.optional(EventOfferSchema),
+  maximumAttendeeCapacity: Schema.optional(positiveInt('Maximum number of attendees')),
+  minimumAttendeeCapacity: Schema.optional(positiveInt('Minimum number of attendees')),
+}).annotations({
+  title: 'Education Event Schema',
+  description: 'Schema.org EducationEvent structured data',
+})
+
+export type EventAttendanceMode = Schema.Schema.Type<typeof EventAttendanceModeSchema>
+export type EventStatus = Schema.Schema.Type<typeof EventStatusSchema>
+export type EventLocation = Schema.Schema.Type<typeof EventLocationSchema>
+export type EventOrganizer = Schema.Schema.Type<typeof EventOrganizerSchema>
+export type TicketAvailability = Schema.Schema.Type<typeof TicketAvailabilitySchema>
+export type EventOffer = Schema.Schema.Type<typeof EventOfferSchema>
+export type EducationEvent = Schema.Schema.Type<typeof EducationEventSchema>

package/src/domain/models/app/page/meta/structured-data/faq-page.ts

@@ -0,0 +1,127 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Schema } from 'effect'
+import { SchemaOrgContext, schemaType } from './common-fields'
+
+/**
+ * FAQ answer
+ *
+ * Represents the accepted answer to a question.
+ *
+ * Required properties:
+ * - @type: "Answer" (Schema.org type identifier)
+ * - text: The answer text/content
+ */
+export const FaqAnswerSchema = Schema.Struct({
+  '@type': schemaType('Answer'),
+  text: Schema.String.annotations({
+    description: 'The answer text',
+  }),
+}).annotations({
+  description: 'FAQ answer',
+})
+
+/**
+ * FAQ question with accepted answer
+ *
+ * Represents a single question-answer pair in an FAQ.
+ *
+ * Required properties:
+ * - @type: "Question" (Schema.org type identifier)
+ * - name: The question text
+ * - acceptedAnswer: The answer object (Answer type with text)
+ */
+export const FaqQuestionSchema = Schema.Struct({
+  '@type': schemaType('Question'),
+  name: Schema.String.annotations({
+    description: 'The question text',
+  }),
+  acceptedAnswer: FaqAnswerSchema,
+}).annotations({
+  description: 'FAQ question',
+})
+
+/**
+ * Schema.org FAQPage structured data
+ *
+ * Represents a Frequently Asked Questions page with a list of question-answer pairs.
+ * Enables expandable Q&A rich results in Google search, dramatically increasing
+ * visibility and click-through rates.
+ *
+ * Required properties:
+ * - @context: "https://schema.org" (Schema.org vocabulary)
+ * - @type: "FAQPage" (Schema.org type identifier)
+ * - mainEntity: Array of Question objects (each with name and acceptedAnswer)
+ *
+ * Question structure:
+ * - Each question has @type "Question", name (question text), acceptedAnswer
+ * - Each acceptedAnswer has @type "Answer", text (answer content)
+ * - Questions can include HTML in answer text for formatting (lists, bold, links)
+ *
+ * Best practices:
+ * - **5-10 questions**: Optimal number for comprehensive FAQ
+ * - **Concise questions**: Clear, direct questions users would ask
+ * - **Detailed answers**: Complete answers that satisfy user intent
+ * - **Natural language**: Write questions as users would ask them
+ * - **Avoid promotional content**: Focus on answering questions, not selling
+ *
+ * SEO impact:
+ * - **Rich results**: Expandable Q&A boxes in Google search results
+ * - **SERP visibility**: Takes up more screen space (higher CTR)
+ * - **Answer surfacing**: Users see answers without clicking through
+ * - **Featured snippets**: FAQ answers can appear in featured snippets
+ * - **Voice search**: Answers optimized for voice search queries
+ * - **Support reduction**: Answers in search reduce support ticket volume
+ *
+ * Google display:
+ * - Questions appear as expandable boxes in search results
+ * - Users can expand/collapse answers directly in search
+ * - Clicking question takes user to FAQ page with answer highlighted
+ *
+ * @example
+ * ```typescript
+ * const faqPage = {
+ *   "@context": "https://schema.org",
+ *   "@type": "FAQPage",
+ *   mainEntity: [
+ *     {
+ *       "@type": "Question",
+ *       name: "What is the refund policy?",
+ *       acceptedAnswer: {
+ *         "@type": "Answer",
+ *         text: "We offer a 30-day money-back guarantee on all purchases."
+ *       }
+ *     },
+ *     {
+ *       "@type": "Question",
+ *       name: "How long does shipping take?",
+ *       acceptedAnswer: {
+ *         "@type": "Answer",
+ *         text: "Standard shipping takes 5-7 business days. Express shipping takes 2-3 business days."
+ *       }
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * @see specs/app/pages/meta/structured-data/faq-page.schema.json
+ */
+export const FaqPageSchema = Schema.Struct({
+  '@context': SchemaOrgContext,
+  '@type': schemaType('FAQPage'),
+  mainEntity: Schema.Array(FaqQuestionSchema).annotations({
+    description: 'Array of questions and answers',
+  }),
+}).annotations({
+  title: 'FAQ Page Schema',
+  description: 'Schema.org FAQPage structured data',
+})
+
+export type FaqAnswer = Schema.Schema.Type<typeof FaqAnswerSchema>
+export type FaqQuestion = Schema.Schema.Type<typeof FaqQuestionSchema>
+export type FaqPage = Schema.Schema.Type<typeof FaqPageSchema>

package/src/domain/models/app/page/meta/structured-data/index.ts

@@ -0,0 +1,95 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Schema } from 'effect'
+import { ArticleSchema } from './article'
+import { BreadcrumbSchema } from './breadcrumb'
+import { EducationEventSchema } from './education-event'
+import { FaqPageSchema } from './faq-page'
+import { LocalBusinessSchema } from './local-business'
+import { OrganizationSchema } from './organization'
+import { PersonSchema } from './person'
+import { ProductSchema } from './product'
+
+/**
+ * Schema.org structured data for search engine understanding
+ *
+ * Orchestrator schema that combines all 8 structured data types into a single configuration.
+ * Each property is optional, allowing pages to include only the relevant structured data types.
+ *
+ * Available structured data types:
+ * - **organization**: Company/organization information for Knowledge Graph
+ * - **person**: Individual person profiles for author attribution
+ * - **localBusiness**: Local business for maps and local SEO
+ * - **product**: E-commerce products for shopping rich results
+ * - **article**: Articles/blog posts for content rich results
+ * - **breadcrumb**: Navigation hierarchy for breadcrumb trails
+ * - **faqPage**: FAQ pages for Q&A rich results
+ * - **educationEvent**: Educational events for event discovery
+ *
+ * Usage patterns:
+ * - **Homepage**: organization (company info in Knowledge Graph)
+ * - **About page**: organization + person (company + team members)
+ * - **Blog post**: article + breadcrumb + person (content with navigation and author)
+ * - **Product page**: product + breadcrumb (e-commerce with navigation)
+ * - **FAQ page**: faqPage + breadcrumb (Q&A with navigation)
+ * - **Event page**: educationEvent + breadcrumb (event with navigation)
+ * - **Local business**: localBusiness + organization (location + company info)
+ *
+ * SEO impact:
+ * - **Rich results**: Enables rich snippets in Google search results
+ * - **Knowledge Graph**: Company/person information panels
+ * - **Maps integration**: Local business map pins and directions
+ * - **Event discovery**: Events in Google Search and Google Maps
+ * - **E-commerce**: Product cards with pricing and ratings
+ * - **Navigation**: Breadcrumb trails replace URLs in search results
+ *
+ * @example
+ * ```typescript
+ * const structuredData = {
+ *   organization: {
+ *     "@context": "https://schema.org",
+ *     "@type": "Organization",
+ *     name: "Acme Inc",
+ *     url: "https://acme.com"
+ *   },
+ *   breadcrumb: {
+ *     "@context": "https://schema.org",
+ *     "@type": "BreadcrumbList",
+ *     itemListElement: [...]
+ *   }
+ * }
+ * ```
+ *
+ * @see specs/app/pages/meta/structured-data/structured-data.schema.json
+ */
+export const StructuredDataSchema = Schema.Struct({
+  organization: Schema.optional(OrganizationSchema),
+  person: Schema.optional(PersonSchema),
+  localBusiness: Schema.optional(LocalBusinessSchema),
+  product: Schema.optional(ProductSchema),
+  article: Schema.optional(ArticleSchema),
+  breadcrumb: Schema.optional(BreadcrumbSchema),
+  faqPage: Schema.optional(FaqPageSchema),
+  educationEvent: Schema.optional(EducationEventSchema),
+}).annotations({
+  title: 'Structured Data',
+  description: 'Schema.org structured data for search engine understanding',
+})
+
+export type StructuredData = Schema.Schema.Type<typeof StructuredDataSchema>
+
+// Re-export all structured data schemas for convenience
+export * from './postal-address'
+export * from './person'
+export * from './breadcrumb'
+export * from './faq-page'
+export * from './article'
+export * from './organization'
+export * from './local-business'
+export * from './product'
+export * from './education-event'