sovrium 0.0.2

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

@@ -0,0 +1,247 @@
+/**
+ * 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'
+import { PostalAddressSchema } from './postal-address'
+
+/**
+ * Day of week for opening hours
+ *
+ * 7 days of the week (full names, capitalized).
+ * Used in openingHoursSpecification to specify which days hours apply to.
+ */
+export const DayOfWeekSchema = Schema.Literal(
+  'Monday',
+  'Tuesday',
+  'Wednesday',
+  'Thursday',
+  'Friday',
+  'Saturday',
+  'Sunday'
+).annotations({
+  description: 'Day of the week',
+})
+
+/**
+ * Time in HH:MM format (24-hour)
+ *
+ * Pattern: ^[0-9]{2}:[0-9]{2}$ (e.g., "09:00", "18:30", "23:59")
+ * Examples: "09:00" (9 AM), "13:30" (1:30 PM), "18:00" (6 PM)
+ */
+export const TimeSchema = Schema.String.pipe(
+  Schema.pattern(/^[0-9]{2}:[0-9]{2}$/, {
+    message: () => 'Time must be in HH:MM format (24-hour, e.g., 09:00, 18:30, 23:59)',
+  })
+).annotations({
+  description: 'Time in HH:MM format',
+  examples: ['09:00', '18:00'],
+})
+
+/**
+ * Opening hours specification
+ *
+ * Defines opening hours for specific days of the week.
+ * - @type: "OpeningHoursSpecification"
+ * - dayOfWeek: Array of days these hours apply to (e.g., ["Monday", "Tuesday", "Wednesday"])
+ * - opens: Opening time in HH:MM format (e.g., "09:00")
+ * - closes: Closing time in HH:MM format (e.g., "18:00")
+ */
+export const OpeningHoursSpecificationSchema = Schema.Struct({
+  '@type': schemaType('OpeningHoursSpecification'),
+  dayOfWeek: Schema.optional(
+    Schema.Array(DayOfWeekSchema).annotations({
+      description: 'Days these hours apply to',
+    })
+  ),
+  opens: Schema.optional(TimeSchema.annotations({ description: 'Opening time' })),
+  closes: Schema.optional(TimeSchema.annotations({ description: 'Closing time' })),
+}).annotations({
+  description: 'Opening hours specification',
+})
+
+/**
+ * Geographic coordinates
+ *
+ * Latitude and longitude for precise map location.
+ * - @type: "GeoCoordinates"
+ * - latitude: Latitude as string (e.g., "48.5734", "-37.8136")
+ * - longitude: Longitude as string (e.g., "7.7521", "144.9631")
+ */
+export const GeoCoordinatesSchema = Schema.Struct({
+  '@type': schemaType('GeoCoordinates'),
+  latitude: Schema.optional(
+    Schema.String.annotations({
+      description: 'Latitude',
+    })
+  ),
+  longitude: Schema.optional(
+    Schema.String.annotations({
+      description: 'Longitude',
+    })
+  ),
+}).annotations({
+  description: 'Geographic coordinates',
+})
+
+/**
+ * Schema.org LocalBusiness structured data
+ *
+ * Represents a local business with physical location for local SEO and map display.
+ * Enables Google Business Profile rich results with map pins, directions, opening hours,
+ * and contact information directly in search results.
+ *
+ * Required properties:
+ * - @context: "https://schema.org" (Schema.org vocabulary)
+ * - @type: "LocalBusiness" (Schema.org type identifier)
+ * - name: Business name (e.g., "Joe's Pizza", "Acme Hardware Store")
+ *
+ * Optional properties:
+ * - description: Business description
+ * - url: Business website URL
+ * - logo: Business logo URL
+ * - image: Business image(s) - string or array (storefront, products, interior)
+ * - email: Contact email address
+ * - telephone: Contact phone number
+ * - priceRange: Price level indicator (e.g., "$", "$$", "$$$", "$$$$")
+ * - address: Physical address (PostalAddress object) - CRITICAL for local SEO
+ * - geo: Geographic coordinates (GeoCoordinates object) - enables map pin
+ * - sameAs: Array of social media profile URLs
+ * - openingHoursSpecification: Array of opening hours for each day/day range
+ *
+ * Local SEO impact:
+ * - **Map display**: Address + geo coordinates enable map pin in search results
+ * - **Directions**: "Get directions" button in search results
+ * - **Opening hours**: Shows current open/closed status and hours
+ * - **Local pack**: Appears in local 3-pack for "near me" searches
+ * - **Mobile optimization**: Click-to-call phone number, one-tap directions
+ * - **Rich snippets**: Business info shown prominently in search results
+ *
+ * @example
+ * ```typescript
+ * const localBusiness = {
+ *   "@context": "https://schema.org",
+ *   "@type": "LocalBusiness",
+ *   name: "Joe's Pizza",
+ *   description: "Authentic Italian pizza restaurant",
+ *   url: "https://joespizza.com",
+ *   telephone: "+1-555-123-4567",
+ *   priceRange: "$$",
+ *   address: {
+ *     "@type": "PostalAddress",
+ *     streetAddress: "123 Main St",
+ *     addressLocality: "Strasbourg",
+ *     addressRegion: "Grand Est",
+ *     postalCode: "67000",
+ *     addressCountry: "FR"
+ *   },
+ *   geo: {
+ *     "@type": "GeoCoordinates",
+ *     latitude: "48.5734",
+ *     longitude: "7.7521"
+ *   },
+ *   openingHoursSpecification: [
+ *     {
+ *       "@type": "OpeningHoursSpecification",
+ *       dayOfWeek: ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
+ *       opens: "11:00",
+ *       closes: "22:00"
+ *     },
+ *     {
+ *       "@type": "OpeningHoursSpecification",
+ *       dayOfWeek: ["Saturday", "Sunday"],
+ *       opens: "12:00",
+ *       closes: "23:00"
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * @see specs/app/pages/meta/structured-data/local-business.schema.json
+ */
+export const LocalBusinessSchema = Schema.Struct({
+  '@context': SchemaOrgContext,
+  '@type': schemaType('LocalBusiness'),
+  name: Schema.String.annotations({
+    description: 'Business name',
+  }),
+  description: Schema.optional(
+    Schema.String.annotations({
+      description: 'Business description',
+    })
+  ),
+  url: Schema.optional(
+    Schema.String.annotations({
+      description: 'Business website URL',
+      format: 'uri',
+    })
+  ),
+  logo: Schema.optional(
+    Schema.String.annotations({
+      description: 'Business logo URL',
+      format: 'uri',
+    })
+  ),
+  image: Schema.optional(
+    Schema.Union(
+      Schema.String.annotations({
+        description: 'Business image URL',
+        format: 'uri',
+      }),
+      Schema.Array(
+        Schema.String.annotations({
+          description: 'Business image URL',
+          format: 'uri',
+        })
+      )
+    ).annotations({
+      description: 'Business image(s)',
+    })
+  ),
+  email: Schema.optional(
+    Schema.String.annotations({
+      description: 'Contact email',
+      format: 'email',
+    })
+  ),
+  telephone: Schema.optional(
+    Schema.String.annotations({
+      description: 'Contact phone number',
+    })
+  ),
+  priceRange: Schema.optional(
+    Schema.String.annotations({
+      description: "Price range (e.g., '$-$$$$')",
+    })
+  ),
+  address: Schema.optional(PostalAddressSchema),
+  geo: Schema.optional(GeoCoordinatesSchema),
+  sameAs: Schema.optional(
+    Schema.Array(
+      Schema.String.annotations({
+        description: 'Social media profile URL',
+        format: 'uri',
+      })
+    ).annotations({
+      description: 'Social media profile URLs',
+    })
+  ),
+  openingHoursSpecification: Schema.optional(
+    Schema.Array(OpeningHoursSpecificationSchema).annotations({
+      description: 'Opening hours specifications',
+    })
+  ),
+}).annotations({
+  title: 'Local Business Schema',
+  description: 'Schema.org LocalBusiness structured data',
+})
+
+export type DayOfWeek = Schema.Schema.Type<typeof DayOfWeekSchema>
+export type Time = Schema.Schema.Type<typeof TimeSchema>
+export type OpeningHoursSpecification = Schema.Schema.Type<typeof OpeningHoursSpecificationSchema>
+export type GeoCoordinates = Schema.Schema.Type<typeof GeoCoordinatesSchema>
+export type LocalBusiness = Schema.Schema.Type<typeof LocalBusinessSchema>

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

@@ -0,0 +1,171 @@
+/**
+ * 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'
+import { EducationEventSchema } from './education-event'
+import { PostalAddressSchema } from './postal-address'
+
+/**
+ * Schema.org Organization structured data
+ *
+ * Represents a company, business, or organization for knowledge graphs and rich results.
+ * Enables Google Knowledge Graph panel with company information, logo, and social profiles.
+ *
+ * Required properties:
+ * - @context: "https://schema.org" (Schema.org vocabulary)
+ * - @type: "Organization" (Schema.org type identifier)
+ * - name: Organization name (e.g., "Acme Inc", "Google")
+ *
+ * Optional properties:
+ * - description: Organization description/tagline
+ * - url: Organization website URL
+ * - logo: Organization logo URL (shown in Knowledge Graph)
+ * - image: Organization image(s) - string or array (photos, headquarters, products)
+ * - email: Contact email address
+ * - telephone: Contact phone number
+ * - address: Mailing address (PostalAddress object)
+ * - sameAs: Array of social media profile URLs (Facebook, Twitter, LinkedIn, etc.)
+ * - founder: Founder name
+ * - foundingDate: Date organization was founded (YYYY-MM-DD format)
+ * - employees: Number of employees (integer)
+ * - event: Associated event hosted or organized by the organization (EducationEvent object)
+ *
+ * Common use cases:
+ * - **Knowledge Graph**: Company information panel in Google search results
+ * - **Publisher attribution**: Link articles to publishing organization
+ * - **Brand identity**: Establish company presence across search results
+ * - **Social verification**: Link organization to official social profiles
+ *
+ * SEO impact:
+ * - **Knowledge Graph panel**: Rich company information panel in search results (right side)
+ * - **Logo display**: Organization logo shown in search results and Knowledge Graph
+ * - **Social profiles**: sameAs links verify official social media accounts
+ * - **Brand search**: Improves brand search results with structured information
+ * - **Publisher credibility**: Used in Article schema for publisher attribution
+ *
+ * @example
+ * ```typescript
+ * const organization = {
+ *   "@context": "https://schema.org",
+ *   "@type": "Organization",
+ *   name: "Acme Inc",
+ *   description: "Leading provider of business software solutions",
+ *   url: "https://acme.com",
+ *   logo: "https://acme.com/logo.png",
+ *   email: "contact@acme.com",
+ *   telephone: "+1-555-123-4567",
+ *   address: {
+ *     "@type": "PostalAddress",
+ *     streetAddress: "123 Main St",
+ *     addressLocality: "San Francisco",
+ *     addressRegion: "CA",
+ *     postalCode: "94105",
+ *     addressCountry: "US"
+ *   },
+ *   sameAs: [
+ *     "https://facebook.com/acmeinc",
+ *     "https://twitter.com/acmeinc",
+ *     "https://linkedin.com/company/acmeinc"
+ *   ],
+ *   founder: "Jane Doe",
+ *   foundingDate: "2015-01-15",
+ *   employees: 150
+ * }
+ * ```
+ *
+ * @see specs/app/pages/meta/structured-data/organization.schema.json
+ */
+export const OrganizationSchema = Schema.Struct({
+  '@context': SchemaOrgContext,
+  '@type': schemaType('Organization'),
+  name: Schema.String.annotations({
+    description: 'Organization name',
+  }),
+  description: Schema.optional(
+    Schema.String.annotations({
+      description: 'Organization description',
+    })
+  ),
+  url: Schema.optional(
+    Schema.String.annotations({
+      description: 'Organization website URL',
+      format: 'uri',
+    })
+  ),
+  logo: Schema.optional(
+    Schema.String.annotations({
+      description: 'Organization logo URL',
+      format: 'uri',
+    })
+  ),
+  image: Schema.optional(
+    Schema.Union(
+      Schema.String.annotations({
+        description: 'Organization image URL',
+        format: 'uri',
+      }),
+      Schema.Array(
+        Schema.String.annotations({
+          description: 'Organization image URL',
+          format: 'uri',
+        })
+      )
+    ).annotations({
+      description: 'Organization image(s)',
+    })
+  ),
+  email: Schema.optional(
+    Schema.String.annotations({
+      description: 'Contact email',
+      format: 'email',
+    })
+  ),
+  telephone: Schema.optional(
+    Schema.String.annotations({
+      description: 'Contact phone number',
+    })
+  ),
+  address: Schema.optional(PostalAddressSchema),
+  sameAs: Schema.optional(
+    Schema.Array(
+      Schema.String.annotations({
+        description: 'Social media profile URL',
+        format: 'uri',
+      })
+    ).annotations({
+      description: 'Social media profile URLs',
+      examples: [['https://facebook.com/myorg', 'https://twitter.com/myorg']],
+    })
+  ),
+  founder: Schema.optional(
+    Schema.String.annotations({
+      description: 'Organization founder name',
+    })
+  ),
+  foundingDate: Schema.optional(
+    Schema.String.annotations({
+      description: 'Date organization was founded',
+      format: 'date',
+    })
+  ),
+  employees: Schema.optional(
+    Schema.Int.pipe(Schema.greaterThanOrEqualTo(1)).annotations({
+      description: 'Number of employees',
+    })
+  ),
+  event: Schema.optional(
+    EducationEventSchema.annotations({
+      description: 'Associated event hosted or organized by the organization',
+    })
+  ),
+}).annotations({
+  title: 'Organization Schema',
+  description: 'Schema.org Organization structured data',
+})
+
+export type Organization = Schema.Schema.Type<typeof OrganizationSchema>

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

@@ -0,0 +1,138 @@
+/**
+ * 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,
+  SchemaOrgEmail,
+  SchemaOrgImageUrl,
+  SchemaOrgSameAs,
+  SchemaOrgTelephone,
+  SchemaOrgUrl,
+  schemaType,
+} from './common-fields'
+import { PostalAddressSchema } from './postal-address'
+
+/**
+ * Organization reference for Person's employer
+ *
+ * Simplified Organization object with @type and name.
+ * Links person to their employer organization.
+ */
+export const PersonWorksForSchema = Schema.Struct({
+  '@type': schemaType('Organization'),
+  name: Schema.optional(
+    Schema.String.annotations({
+      description: 'Organization name',
+    })
+  ),
+}).annotations({
+  description: "Person's employer organization",
+})
+
+/**
+ * Schema.org Person structured data
+ *
+ * Represents an individual person with contact information, professional details,
+ * and social profiles. Used for author attribution, knowledge graphs, and notable persons.
+ *
+ * Required properties:
+ * - @context: "https://schema.org" (Schema.org vocabulary)
+ * - @type: "Person" (Schema.org type identifier)
+ * - name: Person's full name (e.g., "John Doe")
+ *
+ * Optional properties:
+ * - givenName: First name (e.g., "John")
+ * - familyName: Last name (e.g., "Doe")
+ * - email: Email address (format validated)
+ * - telephone: Phone number
+ * - url: Personal website or profile URL
+ * - image: Photo URL (headshot, profile picture)
+ * - jobTitle: Professional role (e.g., "CEO", "Software Engineer")
+ * - worksFor: Employer organization (Organization object with name)
+ * - sameAs: Array of social media profile URLs (LinkedIn, Twitter, GitHub, etc.)
+ * - address: Mailing address (PostalAddress object)
+ *
+ * Common use cases:
+ * - **Author attribution**: Link articles to specific authors (article.author)
+ * - **Knowledge Graph**: Enable Google Knowledge Graph panel for notable persons
+ * - **Contact information**: Provide structured contact details for business persons
+ * - **Social profiles**: Link person to their social media presence
+ *
+ * SEO impact:
+ * - Author attribution: Improves content credibility and E-E-A-T signals
+ * - Knowledge Graph: Notable persons get rich panel in search results
+ * - Social verification: sameAs links verify person's online identity
+ * - Professional context: jobTitle and worksFor provide professional context
+ *
+ * @example
+ * ```typescript
+ * const person = {
+ *   "@context": "https://schema.org",
+ *   "@type": "Person",
+ *   name: "John Doe",
+ *   givenName: "John",
+ *   familyName: "Doe",
+ *   jobTitle: "CEO",
+ *   email: "john@example.com",
+ *   url: "https://johndoe.com",
+ *   worksFor: {
+ *     "@type": "Organization",
+ *     name: "Acme Inc"
+ *   },
+ *   sameAs: [
+ *     "https://linkedin.com/in/johndoe",
+ *     "https://twitter.com/johndoe"
+ *   ]
+ * }
+ * ```
+ *
+ * @see specs/app/pages/meta/structured-data/person.schema.json
+ */
+export const PersonSchema = Schema.Struct({
+  '@context': SchemaOrgContext,
+  '@type': schemaType('Person'),
+  name: Schema.String.annotations({
+    description: "Person's full name",
+  }),
+  givenName: Schema.optional(
+    Schema.String.annotations({
+      description: 'First name',
+    })
+  ),
+  familyName: Schema.optional(
+    Schema.String.annotations({
+      description: 'Last name',
+    })
+  ),
+  email: Schema.optional(SchemaOrgEmail),
+  telephone: Schema.optional(SchemaOrgTelephone),
+  url: Schema.optional(
+    SchemaOrgUrl.annotations({
+      description: "Person's website or profile",
+    })
+  ),
+  image: Schema.optional(
+    SchemaOrgImageUrl.annotations({
+      description: "Person's photo URL",
+    })
+  ),
+  jobTitle: Schema.optional(
+    Schema.String.annotations({
+      description: 'Professional role',
+    })
+  ),
+  worksFor: Schema.optional(PersonWorksForSchema),
+  sameAs: Schema.optional(SchemaOrgSameAs),
+  address: Schema.optional(PostalAddressSchema),
+}).annotations({
+  title: 'Person Schema',
+  description: 'Schema.org Person structured data',
+})
+
+export type PersonWorksFor = Schema.Schema.Type<typeof PersonWorksForSchema>
+export type Person = Schema.Schema.Type<typeof PersonSchema>

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

@@ -0,0 +1,106 @@
+/**
+ * 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 { schemaType } from './common-fields'
+
+/**
+ * ISO 3166-1 alpha-2 country code
+ *
+ * Two-letter country code format (uppercase).
+ * - Pattern: ^[A-Z]{2}$ (exactly 2 uppercase letters)
+ * - Examples: US (United States), FR (France), GB (United Kingdom), DE (Germany), JP (Japan)
+ * - Standard: ISO 3166-1 alpha-2 (international standard for country codes)
+ */
+export const CountryCodeSchema = Schema.String.pipe(
+  Schema.pattern(/^[A-Z]{2}$/, {
+    message: () =>
+      'Country code must be ISO 3166-1 alpha-2 format (2 uppercase letters, e.g., US, FR, GB, DE, JP)',
+  })
+).annotations({
+  description: 'ISO 3166-1 alpha-2 country code',
+  examples: ['US', 'FR', 'GB', 'DE'],
+})
+
+/**
+ * Schema.org PostalAddress structured data
+ *
+ * Represents a physical mailing address for organizations, businesses, and persons.
+ * Used in LocalBusiness, Organization, and Person schemas to provide location information
+ * for local SEO and map display in search results.
+ *
+ * Required properties:
+ * - @type: Must be "PostalAddress" (Schema.org type identifier)
+ *
+ * Optional properties:
+ * - streetAddress: Street address (e.g., "123 Main St", "45 Rue de la Paix")
+ * - addressLocality: City or locality name (e.g., "Strasbourg", "Paris", "San Francisco")
+ * - addressRegion: State, province, or region (e.g., "Grand Est", "California", "Ontario")
+ * - postalCode: Postal or ZIP code (e.g., "67000", "94105", "SW1A 1AA")
+ * - addressCountry: ISO 3166-1 alpha-2 country code (e.g., "FR", "US", "GB")
+ *
+ * Address format examples:
+ * - US: "123 Main St, San Francisco, CA 94105, US"
+ * - FR: "45 Rue de la Paix, Strasbourg, Grand Est 67000, FR"
+ * - GB: "10 Downing St, London, England SW1A 1AA, GB"
+ *
+ * Use cases:
+ * - **LocalBusiness**: Enable map display and directions in search results
+ * - **Organization**: Provide company headquarters address for Knowledge Graph
+ * - **Person**: Include contact address for notable persons
+ * - **EducationEvent**: Specify venue address for event listings
+ *
+ * SEO impact:
+ * - Local search ranking: Complete addresses improve local SEO
+ * - Map visibility: Address + geo coordinates enable map pins in search results
+ * - Rich snippets: Address shown in business listings and Knowledge Graph panels
+ * - Mobile search: "Near me" searches prioritize businesses with addresses
+ *
+ * @example
+ * ```typescript
+ * const address = {
+ *   "@type": "PostalAddress",
+ *   streetAddress: "123 Main St",
+ *   addressLocality: "Strasbourg",
+ *   addressRegion: "Grand Est",
+ *   postalCode: "67000",
+ *   addressCountry: "FR"
+ * }
+ * ```
+ *
+ * @see specs/app/pages/meta/structured-data/postal-address.schema.json
+ */
+export const PostalAddressSchema = Schema.Struct({
+  '@type': schemaType('PostalAddress'),
+  streetAddress: Schema.optional(
+    Schema.String.annotations({
+      description: 'Street address',
+    })
+  ),
+  addressLocality: Schema.optional(
+    Schema.String.annotations({
+      description: 'City or locality',
+    })
+  ),
+  addressRegion: Schema.optional(
+    Schema.String.annotations({
+      description: 'State or region',
+    })
+  ),
+  postalCode: Schema.optional(
+    Schema.String.annotations({
+      description: 'Postal or ZIP code',
+    })
+  ),
+  addressCountry: Schema.optional(CountryCodeSchema),
+}).annotations({
+  title: 'Postal Address',
+  description: 'Schema.org PostalAddress structured data',
+})
+
+export type CountryCode = Schema.Schema.Type<typeof CountryCodeSchema>
+export type PostalAddress = Schema.Schema.Type<typeof PostalAddressSchema>