sovrium 0.0.2

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

@@ -0,0 +1,214 @@
+/**
+ * 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'
+
+/**
+ * Product brand
+ *
+ * Brand object with @type "Brand" and name.
+ * Identifies the product manufacturer or brand.
+ */
+export const ProductBrandSchema = Schema.Struct({
+  '@type': schemaType('Brand'),
+  name: Schema.optional(
+    Schema.String.annotations({
+      description: 'Brand name',
+    })
+  ),
+}).annotations({
+  description: 'Product brand',
+})
+
+/**
+ * ISO 4217 currency code
+ *
+ * 3-letter currency code (uppercase).
+ * - Pattern: ^[A-Z]{3}$ (exactly 3 uppercase letters)
+ * - Examples: USD (US Dollar), EUR (Euro), GBP (British Pound), JPY (Japanese Yen)
+ */
+export const CurrencyCodeSchema = Schema.String.pipe(
+  Schema.pattern(/^[A-Z]{3}$/, {
+    message: () =>
+      'Currency code must be ISO 4217 format (3 uppercase letters, e.g., USD, EUR, GBP, JPY)',
+  })
+).annotations({
+  description: 'ISO 4217 currency code',
+  examples: ['USD', 'EUR', 'GBP'],
+})
+
+/**
+ * Product offer
+ *
+ * Pricing and availability information for a product.
+ * - @type: "Offer"
+ * - price: Price as string or number (e.g., "29.99", 29.99)
+ * - priceCurrency: ISO 4217 currency code (e.g., "USD", "EUR")
+ * - availability: Stock status URL (e.g., "https://schema.org/InStock")
+ * - url: URL to purchase page
+ */
+export const ProductOfferSchema = Schema.Struct({
+  '@type': schemaType('Offer'),
+  price: Schema.optional(
+    Schema.Union(Schema.String, Schema.Number).annotations({
+      description: 'Product price',
+    })
+  ),
+  priceCurrency: Schema.optional(CurrencyCodeSchema),
+  availability: Schema.optional(
+    Schema.String.annotations({
+      description: 'Stock availability status',
+    })
+  ),
+  url: Schema.optional(
+    Schema.String.annotations({
+      description: 'URL to purchase page',
+      format: 'uri',
+    })
+  ),
+}).annotations({
+  description: 'Product offer',
+})
+
+/**
+ * Aggregate rating
+ *
+ * Average rating and review count for a product.
+ * - @type: "AggregateRating"
+ * - ratingValue: Average rating (e.g., 4.5 out of 5)
+ * - reviewCount: Total number of reviews (integer)
+ */
+export const AggregateRatingSchema = Schema.Struct({
+  '@type': schemaType('AggregateRating'),
+  ratingValue: Schema.optional(
+    Schema.Number.annotations({
+      description: 'Average rating value',
+    })
+  ),
+  reviewCount: Schema.optional(
+    Schema.Int.annotations({
+      description: 'Total number of reviews',
+    })
+  ),
+}).annotations({
+  description: 'Aggregate rating',
+})
+
+/**
+ * Schema.org Product structured data
+ *
+ * Represents a product for e-commerce rich results in Google Search.
+ * Enables product cards with images, prices, availability, and star ratings
+ * directly in search results, dramatically increasing click-through rates.
+ *
+ * Required properties:
+ * - @context: "https://schema.org" (Schema.org vocabulary)
+ * - @type: "Product" (Schema.org type identifier)
+ * - name: Product name (e.g., "iPhone 15 Pro", "Nike Air Max 90")
+ *
+ * Optional properties:
+ * - description: Product description
+ * - image: Product image(s) - string or array (photos, angles, colors)
+ * - brand: Product brand (Brand object with name)
+ * - sku: Stock Keeping Unit (internal product ID)
+ * - gtin: Global Trade Item Number (UPC, EAN, ISBN - standardized ID)
+ * - offers: Pricing information (Offer object with price, currency, availability, URL)
+ * - aggregateRating: Average rating (AggregateRating object with ratingValue, reviewCount)
+ *
+ * E-commerce SEO impact:
+ * - **Product rich results**: Cards with image, price, availability, ratings in search
+ * - **Google Shopping**: Eligible for Google Shopping results (with additional requirements)
+ * - **Star ratings**: Visual star ratings increase CTR by 20-30%
+ * - **Price display**: Price shown directly in search results
+ * - **Availability**: "In Stock" / "Out of Stock" status shown in results
+ * - **Mobile optimization**: Tap to purchase, quick product comparison
+ *
+ * @example
+ * ```typescript
+ * const product = {
+ *   "@context": "https://schema.org",
+ *   "@type": "Product",
+ *   name: "iPhone 15 Pro",
+ *   description: "Advanced camera system, A17 Pro chip, titanium design",
+ *   image: [
+ *     "https://example.com/iphone-front.jpg",
+ *     "https://example.com/iphone-back.jpg"
+ *   ],
+ *   brand: {
+ *     "@type": "Brand",
+ *     name: "Apple"
+ *   },
+ *   sku: "IPHONE15PRO-256-TIT",
+ *   gtin: "0194253779999",
+ *   offers: {
+ *     "@type": "Offer",
+ *     price: "999.00",
+ *     priceCurrency: "USD",
+ *     availability: "https://schema.org/InStock",
+ *     url: "https://example.com/products/iphone-15-pro"
+ *   },
+ *   aggregateRating: {
+ *     "@type": "AggregateRating",
+ *     ratingValue: 4.8,
+ *     reviewCount: 2547
+ *   }
+ * }
+ * ```
+ *
+ * @see specs/app/pages/meta/structured-data/product.schema.json
+ */
+export const ProductSchema = Schema.Struct({
+  '@context': SchemaOrgContext,
+  '@type': schemaType('Product'),
+  name: Schema.String.annotations({
+    description: 'Product name',
+  }),
+  description: Schema.optional(
+    Schema.String.annotations({
+      description: 'Product description',
+    })
+  ),
+  image: Schema.optional(
+    Schema.Union(
+      Schema.String.annotations({
+        description: 'Product image URL',
+        format: 'uri',
+      }),
+      Schema.Array(
+        Schema.String.annotations({
+          description: 'Product image URL',
+          format: 'uri',
+        })
+      )
+    ).annotations({
+      description: 'Product image(s)',
+    })
+  ),
+  brand: Schema.optional(ProductBrandSchema),
+  sku: Schema.optional(
+    Schema.String.annotations({
+      description: 'Stock Keeping Unit',
+    })
+  ),
+  gtin: Schema.optional(
+    Schema.String.annotations({
+      description: 'Global Trade Item Number (UPC, EAN, ISBN)',
+    })
+  ),
+  offers: Schema.optional(ProductOfferSchema),
+  aggregateRating: Schema.optional(AggregateRatingSchema),
+}).annotations({
+  title: 'Product Schema',
+  description: 'Schema.org Product structured data',
+})
+
+export type ProductBrand = Schema.Schema.Type<typeof ProductBrandSchema>
+export type CurrencyCode = Schema.Schema.Type<typeof CurrencyCodeSchema>
+export type ProductOffer = Schema.Schema.Type<typeof ProductOfferSchema>
+export type AggregateRating = Schema.Schema.Type<typeof AggregateRatingSchema>
+export type Product = Schema.Schema.Type<typeof ProductSchema>

package/src/domain/models/app/page/meta/twitter-card.ts

@@ -0,0 +1,217 @@
+/**
+ * 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'
+
+/**
+ * Twitter Card type
+ *
+ * 4 card formats for different content types:
+ * - summary: Small square image (144x144px, 1:1 aspect) - compact card for brief updates
+ * - summary_large_image: Large rectangular image (800x418px, 1.91:1) - most popular, highest engagement
+ * - app: Mobile app promotion with install button - links to App Store/Google Play
+ * - player: Video/audio player embed - plays inline in Twitter feed
+ */
+export const TwitterCardTypeSchema = Schema.Literal(
+  'summary',
+  'summary_large_image',
+  'app',
+  'player'
+).annotations({
+  description: 'Type of Twitter Card',
+})
+
+/**
+ * Twitter username pattern
+ *
+ * Twitter @username format: starts with @ followed by alphanumeric and underscores.
+ * - Pattern: ^@[A-Za-z0-9_]+$ (must start with @)
+ * - Valid: @mysite, @johndoe, @acmeblog123
+ * - Invalid: mysite (missing @), @my-site (hyphen not allowed)
+ */
+export const TwitterUsernameSchema = Schema.String.pipe(
+  Schema.pattern(/^@[A-Za-z0-9_]+$/, {
+    message: () =>
+      'Twitter username must start with @ and contain only letters, numbers, and underscores (e.g., @mysite, @johndoe)',
+  })
+).annotations({
+  description: 'Twitter @username',
+  examples: ['@mysite', '@johndoe'],
+})
+
+/**
+ * App name configuration for Twitter App Card
+ *
+ * App names per platform (iPhone, iPad, Google Play).
+ * Used in App Card to show app name and link to app store.
+ */
+export const TwitterAppNameSchema = Schema.Struct({
+  iPhone: Schema.optional(Schema.String.annotations({ description: 'App name for iPhone' })),
+  iPad: Schema.optional(Schema.String.annotations({ description: 'App name for iPad' })),
+  googlePlay: Schema.optional(
+    Schema.String.annotations({ description: 'App name for Google Play' })
+  ),
+}).annotations({
+  description: 'Name of app (for app cards)',
+})
+
+/**
+ * App ID configuration for Twitter App Card
+ *
+ * App Store IDs per platform (iPhone, iPad, Google Play).
+ * Used in App Card to link directly to app store listing.
+ */
+export const TwitterAppIdSchema = Schema.Struct({
+  iPhone: Schema.optional(Schema.String.annotations({ description: 'App Store ID for iPhone' })),
+  iPad: Schema.optional(Schema.String.annotations({ description: 'App Store ID for iPad' })),
+  googlePlay: Schema.optional(
+    Schema.String.annotations({ description: 'Google Play package name (e.g., com.example.myapp)' })
+  ),
+}).annotations({
+  description: 'App ID in respective stores',
+})
+
+/**
+ * CORS setting for Twitter Card resources
+ *
+ * 3 options:
+ * - true: Anonymous CORS (no credentials)
+ * - false: No CORS
+ * - 'anonymous': Explicit anonymous CORS
+ * - 'use-credentials': CORS with credentials
+ */
+export const TwitterCrossOriginSchema = Schema.Union(
+  Schema.Boolean,
+  Schema.Literal('anonymous', 'use-credentials')
+).annotations({
+  description: 'CORS setting for the resource',
+})
+
+/**
+ * Twitter Card metadata for rich Twitter/X sharing
+ *
+ * Defines how pages appear when shared on Twitter/X platform.
+ * Creates rich preview cards with images, titles, and descriptions to
+ * dramatically increase engagement and click-through rates.
+ *
+ * Required properties:
+ * - card: Card type (summary, summary_large_image, app, player)
+ *
+ * Optional properties:
+ * - title: Card title (max 70 chars, shorter than Open Graph's 90)
+ * - description: Card description (max 200 chars, same as Open Graph)
+ * - image: Image URL (min 144x144px for summary, 300x157px for large)
+ * - imageAlt: Image alternative text (max 420 chars, longer than Open Graph)
+ * - site: Twitter @username of website (e.g., @acmeblog)
+ * - creator: Twitter @username of content author (e.g., @johndoe)
+ *
+ * Player card properties (for video/audio):
+ * - player: HTTPS URL to player iframe
+ * - playerWidth: Player width in pixels
+ * - playerHeight: Player height in pixels
+ *
+ * App card properties (for mobile apps):
+ * - appName: App names per platform (iPhone, iPad, Google Play)
+ * - appId: App Store IDs per platform
+ *
+ * Card types comparison:
+ * 1. **summary**: Small square image (144x144px), compact format
+ *    - Good for: news updates, blog posts, simple links
+ *    - Layout: [Square image] [Title + Description]
+ *
+ * 2. **summary_large_image**: Large rectangular image (800x418px), most popular
+ *    - Good for: featured content, product launches, visual content
+ *    - Layout: [Large image full width] [Title] [Description]
+ *    - Highest engagement (most popular card type)
+ *
+ * 3. **app**: Mobile app promotion with install button
+ *    - Good for: app launches, mobile-first products
+ *    - Layout: [App icon] [Title + Description] [Install button]
+ *    - Click: opens App Store/Google Play directly
+ *
+ * 4. **player**: Video/audio player embed
+ *    - Good for: video content, podcasts, demos
+ *    - Layout: [Video thumbnail] [Play button]
+ *    - Click: embeds player iframe inline in Twitter feed
+ *
+ * Impact:
+ * - Rich cards get 2-3x more clicks than plain links
+ * - Large image card most effective (highest engagement)
+ * - Without Twitter Card: falls back to Open Graph or generic unfurl
+ *
+ * @example
+ * ```typescript
+ * const twitterCard = {
+ *   card: 'summary_large_image',
+ *   title: 'Transform Your Business with AI-Powered Analytics',
+ *   description: 'Get real-time insights and automated reporting. Start free trial.',
+ *   image: 'https://example.com/twitter-800x418.jpg',
+ *   imageAlt: 'Dashboard screenshot showing analytics graphs',
+ *   site: '@acmeanalytics',
+ *   creator: '@johndoe'
+ * }
+ * ```
+ *
+ * @see specs/app/pages/meta/social/twitter-card.schema.json
+ */
+export const TwitterCardSchema = Schema.Struct({
+  card: TwitterCardTypeSchema,
+  title: Schema.optional(
+    Schema.String.pipe(Schema.maxLength(70)).annotations({
+      description: 'Twitter Card title',
+    })
+  ),
+  description: Schema.optional(
+    Schema.String.pipe(Schema.maxLength(200)).annotations({
+      description: 'Twitter Card description',
+    })
+  ),
+  image: Schema.optional(
+    Schema.String.annotations({
+      description: 'Image URL (min 144x144px for summary, 300x157px for large)',
+      format: 'uri',
+    })
+  ),
+  imageAlt: Schema.optional(
+    Schema.String.pipe(Schema.maxLength(420)).annotations({
+      description: 'Alternative text for the image',
+    })
+  ),
+  site: Schema.optional(
+    TwitterUsernameSchema.annotations({ description: 'Twitter @username of website' })
+  ),
+  creator: Schema.optional(
+    TwitterUsernameSchema.annotations({ description: 'Twitter @username of content creator' })
+  ),
+  player: Schema.optional(
+    Schema.String.annotations({
+      description: 'HTTPS URL to video player (for player cards)',
+      format: 'uri',
+    })
+  ),
+  playerWidth: Schema.optional(
+    Schema.Int.pipe(Schema.greaterThanOrEqualTo(1)).annotations({
+      description: 'Width of video player in pixels',
+    })
+  ),
+  playerHeight: Schema.optional(
+    Schema.Int.pipe(Schema.greaterThanOrEqualTo(1)).annotations({
+      description: 'Height of video player in pixels',
+    })
+  ),
+  appName: Schema.optional(TwitterAppNameSchema),
+  appId: Schema.optional(TwitterAppIdSchema),
+}).annotations({
+  title: 'Twitter Card Metadata',
+  description: 'Twitter Card metadata for rich Twitter/X sharing',
+})
+
+export type TwitterCardType = Schema.Schema.Type<typeof TwitterCardTypeSchema>
+export type TwitterUsername = Schema.Schema.Type<typeof TwitterUsernameSchema>
+export type TwitterAppName = Schema.Schema.Type<typeof TwitterAppNameSchema>
+export type TwitterAppId = Schema.Schema.Type<typeof TwitterAppIdSchema>
+export type TwitterCard = Schema.Schema.Type<typeof TwitterCardSchema>

package/src/domain/models/app/page/name.ts

@@ -0,0 +1,38 @@
+/**
+ * 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'
+
+/**
+ * Page Name (human-readable display name for the page)
+ *
+ * Unlike the common NameSchema (database identifier with snake_case), page names
+ * are human-readable labels used in admin interfaces, logs, and internal references.
+ * They can contain spaces, capital letters, and other readable characters.
+ *
+ * Must be non-empty with max 63 characters to match database constraints for
+ * internal identifiers, but doesn't enforce snake_case pattern since this is
+ * a display name, not a database column name.
+ *
+ * @example "Home"
+ * @example "About Us"
+ * @example "Home Page"
+ * @example "Pricing Plans"
+ *
+ * @see specs/app/pages/name/name.schema.json
+ */
+export const PageNameSchema = Schema.String.pipe(
+  Schema.minLength(1),
+  Schema.maxLength(63),
+  Schema.annotations({
+    title: 'Page Name',
+    description: 'Human-readable name for the page',
+    examples: ['Home', 'About Us', 'Home Page', 'Pricing', 'Contact'],
+  })
+)
+
+export type PageName = Schema.Schema.Type<typeof PageNameSchema>

package/src/domain/models/app/page/path.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 { PathSchema as CommonPathSchema } from '../common/definitions'
+
+/**
+ * URL Path (where the page is accessible)
+ *
+ * Re-exports the common Path schema from definitions.
+ * See PathSchema in common/definitions for full documentation.
+ *
+ * @see specs/app/pages/path/path.schema.json
+ * @see specs/app/common/definitions.schema.json#/definitions/path
+ */
+export const PagePathSchema = CommonPathSchema
+
+export type PagePath = typeof PagePathSchema.Type

package/src/domain/models/app/page/scripts/external-scripts.ts

@@ -0,0 +1,163 @@
+/**
+ * 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'
+
+/**
+ * CORS settings for external scripts
+ *
+ * Controls cross-origin resource sharing:
+ * - anonymous: No credentials sent (default for public CDN scripts)
+ * - use-credentials: Send credentials (cookies, auth headers)
+ */
+export const CrossOriginSchema = Schema.Literal('anonymous', 'use-credentials').annotations({
+  description: 'CORS setting for cross-origin scripts',
+})
+
+/**
+ * Script insertion position in HTML document
+ *
+ * Controls where the script tag is inserted:
+ * - head: In document <head> (loads before DOM)
+ * - body-start: At start of <body> (loads before content)
+ * - body-end: At end of <body> (default, loads after content)
+ *
+ * Performance impact:
+ * - head: Blocks rendering, use with defer/async
+ * - body-start: Blocks content, use sparingly
+ * - body-end: Non-blocking, best for most scripts
+ */
+export const ScriptPositionSchema = Schema.Literal('head', 'body-start', 'body-end').annotations({
+  description: 'Where to insert the script in the document',
+})
+
+/**
+ * External JavaScript dependency
+ *
+ * Defines an external script loaded from a URL (CDN or local path).
+ *
+ * Required properties:
+ * - src: Script source URL (https:// for CDN, relative for local)
+ *
+ * Optional properties:
+ * - async: Load asynchronously (non-blocking, execute when ready)
+ * - defer: Defer execution until DOM loaded (preserves order)
+ * - module: Load as ES module (type="module")
+ * - integrity: Subresource integrity hash for security
+ * - crossorigin: CORS setting (anonymous or use-credentials)
+ * - position: Where to insert script (head, body-start, body-end)
+ *
+ * Loading strategies:
+ * - async: Best for analytics, ads (execute ASAP, order doesn't matter)
+ * - defer: Best for frameworks (preserve order, non-blocking)
+ * - neither: Blocking (avoid unless script must execute before DOM)
+ *
+ * @example
+ * ```typescript
+ * const alpineJS = {
+ *   src: 'https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js',
+ *   defer: true,
+ *   position: 'head'
+ * }
+ *
+ * const chartJS = {
+ *   src: 'https://cdn.jsdelivr.net/npm/chart.js',
+ *   async: true
+ * }
+ *
+ * const localApp = {
+ *   src: './js/app.js',
+ *   module: true,
+ *   position: 'body-end'
+ * }
+ * ```
+ *
+ * @see specs/app/pages/scripts/external-scripts/external-scripts.schema.json
+ */
+export const ExternalScriptSchema = Schema.Struct({
+  src: Schema.String.annotations({
+    description: 'Script source URL',
+    format: 'uri',
+  }),
+  async: Schema.optional(
+    Schema.Boolean.annotations({
+      description: 'Load script asynchronously',
+      default: false,
+    })
+  ),
+  defer: Schema.optional(
+    Schema.Boolean.annotations({
+      description: 'Defer script execution',
+      default: false,
+    })
+  ),
+  module: Schema.optional(
+    Schema.Boolean.annotations({
+      description: 'Load as ES module',
+      default: false,
+    })
+  ),
+  integrity: Schema.optional(
+    Schema.String.annotations({
+      description: 'Subresource integrity hash',
+    })
+  ),
+  crossorigin: Schema.optional(CrossOriginSchema),
+  position: Schema.optional(ScriptPositionSchema),
+}).annotations({
+  description: 'External JavaScript dependency',
+})
+
+/**
+ * External JavaScript dependencies
+ *
+ * Array of external scripts loaded from CDN or local paths.
+ * Scripts are loaded in order when using defer or blocking mode.
+ *
+ * Common use cases:
+ * - Frameworks: Alpine.js, htmx (defer for order preservation)
+ * - Libraries: Chart.js, D3.js (async for parallel loading)
+ * - Analytics: Google Analytics, Plausible (async, non-blocking)
+ * - UI widgets: Intercom, Crisp chat (async, low priority)
+ *
+ * Performance best practices:
+ * - Use async for non-dependent scripts (analytics, ads)
+ * - Use defer for frameworks/libraries that depend on each other
+ * - Add integrity hashes for security (CDN scripts)
+ * - Prefer body-end position for non-critical scripts
+ *
+ * @example
+ * ```typescript
+ * const externalScripts = [
+ *   {
+ *     src: 'https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js',
+ *     defer: true,
+ *     position: 'head'
+ *   },
+ *   {
+ *     src: 'https://cdn.jsdelivr.net/npm/chart.js',
+ *     async: true
+ *   },
+ *   {
+ *     src: './js/app.js',
+ *     module: true,
+ *     position: 'body-end'
+ *   }
+ * ]
+ * ```
+ *
+ * @see specs/app/pages/scripts/external-scripts/external-scripts.schema.json
+ */
+export const ExternalScriptsSchema = Schema.Array(ExternalScriptSchema).annotations({
+  title: 'External Scripts',
+  description: 'External JavaScript dependencies',
+})
+
+export type CrossOrigin = Schema.Schema.Type<typeof CrossOriginSchema>
+export type ScriptPosition = Schema.Schema.Type<typeof ScriptPositionSchema>
+export type ExternalScript = Schema.Schema.Type<typeof ExternalScriptSchema>
+export type ExternalScripts = Schema.Schema.Type<typeof ExternalScriptsSchema>